Harbour Socket API - Petewg/harbour-core GitHub Wiki
For those not conversant with Socket programming, here are some quite good sources of info to start with: Beej's Guide to Network Programming and Winsock Programmerβs FAQ and Berkeley sockets, as well as, Linux socket interface
-
hb_socketAccept(
pSocket, [@aAddr], [nTimeout = FOREVER]
) β hConnectionSocket
creates a new socket for each incoming connection and removes the connection from the listening queue. returns the new socket descriptor for the accepted connection, or null pointer on failure. All further communication with the remote host now occurs via this new socket. -
hb_socketAutoFlush(
<pSocket>, [<nTimeout>]
) β nPrevTimeout
Enables or disables automatic flushing of written data.
<nTimeout>
is timeout for automatic flush operation on written data in milliseconds.<nTimeout> = -1
means wait forever and<nTimeout> = 0
disables auto flush.
Automatic flushing can help in adopting existing code anyhow it may strongly reduce the performance in some filters, i.e. compression filters like ZSOCK have to add special data to the stream after each flush operation so it's suggested to call flush explicitly when we want to force delivering written data to the peer. -
hb_socketAutoShutdown(
<pSocket>,[<lNewSetting>]
) β lPrevSetting
Allows to enable/disable automatic shutdown, when the connected socket is closed. -
hb_socketBind(
<pSocket>, <aAddr>
) β lSuccess
attempts to associate an address with an existing socket.
arguments:
<pSocket>
, a pointer to a socket that has been opened (created) using hb_socketOpen().<aAddr>
, array defining the address to be used. Structure of array is { nSOCKET_FAMILY, cADDRESS, nPORT }
returns: True on success, false otherwise. -
hb_socketClose(
pSocket
) β lSuccess
causes the system to release resources allocated to a socket. In case of TCP, the connection is terminated. In Changelog.txt we read that this function also "executes automatically shutdown() for connected sockets, which is important in windows only, where transmitted data can be lost, without explicit call to shutdown() before close". However, is a good idea, methinks, to explicitly "call hb_socketShutdown() before hb_socketClose() to force output buffer flush in systems like MS-Windows". -
hb_socketConnect(
pSocket, aAddr, [nTimeout = FOREVER]
) β lSuccess
establishes a direct communication link to a specific remote host identified by its address via a socket. -
hb_socketErrorString(
[nSocketErrror = hb_socketGetError()], [pSocket]
) β cError -
hb_socketFlush(
<pSocket>, [<nTimeout>], [<lSync>]
) β nNotFlushedBytes
Flushes data written to socket.
<lSync>
parameter is logical value which can be used to force special synchronization method in some filters. Usually users do not have to use it in normal code.
<nTimeout>
defaults to 'FOREVER'. -
hb_socketGetError() β nSocketError
-
hb_socketGetFD(
pSocket
) β nFD -
hb_socketGetFilter(
<pSocket>
) β cFilterName
Returns a filter name used by the<pSocket>
socket. -
hb_socketGetHostName(
aAddr
) β cHostName -
hb_socketGetHosts(
cAddr, [nFamily = HB_SOCKET_AF_INET]
) β aHosts -
hb_socketGetIFaces(
[nFamily], [lNoAliases]
) β aIfaces -
hb_socketGetOSError() β nOSError
-
hb_socketGetPeerName(
pSocket
) β aAddr | NIL -
hb_socketGetRcvBufSize(
pSocket, @nValue
) β lSuccess -
hb_socketGetSndBufSize(
pSocket, @nValue
) β lSuccess -
hb_socketGetSockName(
pSocket
) β aAddr | NIL -
hb_socketListen(
<pSocket>, [<nQueueLen>]
) β lSuccess
this function marks<pSocket>
as a "passive socket", i.e. prepares the socket for incoming connections. It must be called so that the socket be able to accept connections.
arguments:
<pSocket>
, a pointer to a socket that has been opened (created) using hb_socketOpen().<nQueueLen>
, optional number defining maximum pending connections that can be queued (if not specified, default is 10). Once a connection has been accepted, it is removed from queue, so the length of connection queue is not constant.
returns: True on success, false otherwise. -
hb_socketOpen(
[<nDomain>],[<nType>],[<nProtocol>]
) β pSocket
Windows docs: "The function creates a socket that is bound to a specific transport service provider."
Unix manual: "The function creates an endpoint for communication and returns a file descriptor for the socket. The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process."
arguments (all optional):
nDomain, specifies the protocol family of the created socket. For example:
HB_SOCKET_AF_INET for network protocol IPv4 (IPv4-only) HB_SOCKET_AF_INET6 for IPv6 (and in some cases, backward compatible with IPv4) HB_SOCKET_AF_UNIX for local socket (using a file) default: HB_SOCKET_AF_INET
nType, type of socket that can be one of:
HB_SOCKET_PT_STREAM (reliable stream-oriented service or Stream Sockets) HB_SOCKET_PT_DGRAM (datagram service or Datagram Sockets) HB_SOCKET_PT_SEQPACKET (reliable sequenced packet service) HB_SOCKET_PT_RAW (raw protocols atop the network layer) HB_SOCKET_PT_RDM (Reliably Delivered Messages) default: HB_SOCKET_PT_STREAM
nProtocol, specifying the actual transport protocol to use. The most common are:
HB_SOCKET_IPPROTO_TCP, HB_SOCKET_IPPROTO_SCTP, HB_SOCKET_IPPROTO_UDP, HB_SOCKET_IPPROTO_DCCP. Default value is0
(zero) (which is HB_SOCKET_IPPROTO_IP --> Dummy protocol for TCP) and may be used to select a default protocol from the specified nDomain and nType.
returns: pointer to created socket (or null pointer on failure). -
hb_socketRead(
<pSocket>, @<cData>, [<nLen>], [<nTimeout>]
) β nBytesRead
Reads from socket stream to<cData>
(must be passed by reference). This function is similar to hb_socketRecv() but is always redirected to socket stream filters.
<nLen>
defaults to Len(cData),<nTimeout>
defaults to 'FOREVER'. -
hb_socketRecv(
pSocket, @cBuffer, [nLen = Len( cBuffer )], [nFlags = 0], [nTimeout = FOREVER]
) β nBytesRecv -
hb_socketRecvFrom(
pSocket, @cBuffer, [nLen = Len( cBuffer )], [nFlags = 0], @aAddr, [nTimeout = FOREVER]
) β nBytesRecv -
hb_socketResolveAddr(
cAddr, [nFamily = HB_SOCKET_AF_INET]
) β cResolved -
hb_socketResolveINetAddr(
cAddr, nPort
) β aAddr | NIL -
hb_socketSend(
pSocket, cBuffer, [nLen = Len( cBuffer )], [nFlags = 0], [nTimeout = FOREVER]
) β nBytesSent -
hb_socketSendTo(
pSocket, cBuffer, [nLen = Len( cBuffer )], [nFlags = 0], aAddr, [nTimeout = FOREVER]
) β nBytesSent -
hb_socketSetBlockingIO(
pSocket, lValue
) β nSuccess -
hb_socketSetExclusiveAddr(
pSocket, lValue
) β lSuccess -
hb_socketSetFilter(
<pSocket>, <cFilterName>, [hParams]
) β pSocket | NIL
Adds or replaces socket filter(s).
<cFilterName>
is filter name. It's possible to set many filters in a single hb_socketSetFilter() call, separating filter names with|
character, i.e.:pSock := hb_socketSetFilter(pSocket, "ZSOCK|BFSOCK", hParams)
<hParams>
is hash array with initialization parameters used by given socket filter. The core implementation recognize the following settings:
"readahead" -> numeric value with size of read ahead buffer
"flush" -> numeric value with auto flush parameter (for more information look at hb_socketAutoFlush())
"redir" -> logical value which can be use to enable/disable hb_socketSend() and hb_socketRecv() redirection to filter stream. -
hb_socketSetNoDelay(
pSocket, lValue
) β lSuccess -
hb_socketSetReuseAddr(
pSocket, lValue
) β lSuccess -
hb_socketSetKeepAlive(
pSocket, lValue
) β lSuccess -
hb_socketSetBroadcast(
pSocket, lValue
) β lSuccess -
hb_socketSetSndBufSize(
pSocket, nValue
) β lSuccess -
hb_socketSetRcvBufSize(
pSocket, nValue
) β lSuccess -
hb_socketSetMulticast(
pSocket, [nFamily = HB_SOCKET_AF_INET], cAddr
) β lSuccess -
hb_socketSelectRead(
pSocket, [nTimeout = FOREVER]
) β nRet -
hb_socketSelectWrite(
pSocket, [nTimeout = FOREVER]
) β nRet -
hb_socketSelectWriteEx(
pSocket, [nTimeout = FOREVER]
) β nRet -
hb_socketSelect(
aRead, lSetRead, aWrite, lSetWrite, aExcep, lSetExcep, [nTimeout = FOREVER]
) β nRet -
hb_socketShutdown(
pSocket, [nMode = HB_SOCKET_SHUT_RDWR]
) β lSuccess -
hb_socketWrite(
<pSocket>, <cData>, [<nLen>], [<nTimeout>]
) β nBytesWritten
Writes<cData>
to socket stream. This function is similar to hb_socketSend() but it is always redirected to socket stream filters. Written data is not flushed by default and it should be flushed explicitly by hb_socketFlush(). Automatic flushing can be enabled by hb_socketAutoFlush() function.
<nLen>
defaults to Len(cData),<nTimeout>
defaults to 'FOREVER'.
- See also this interesting post about sockets