Harbour Socket API - Petewg/harbour-core GitHub Wiki

πŸ”™ Home

Harbour Socket API

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 is 0 (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'.



πŸ”™ Home

⚠️ **GitHub.com Fallback** ⚠️