Harbour INET API - Petewg/harbour-core GitHub Wiki

🔙 Home

NOTE: hb_inet***() function family are part of core harbour functions, (they do not belong in a separate external library), hence, are transparently linked into applications, when needed.

• hb_inetAccept( <socket> ) ➜ SOCKET
  Arguments: <socket> An INET socket.
  Waits until a connection is available on a socket created with hb_inetServer(), returns a socket that can be used to communicate with the incoming client. On error, NIL is returned and error code sets in the passed SOCKET. This error can be accessed using hb_inetErrorCode() function.

• hb_inetAddress( <socket> ) ➜ cServerAddress
  <socket> a socket previously created / opened.
  Returns a string representing the remote server address in quad dot notation, e.g. "192.168.1.1", or the local server address if the socket is server side.

• hb_inetCleanup() ➜ NIL ?
  Terminates Harbour INET support; mainly used for Windows. Put it at the end of any program/module that's using Inet functions, just before the program/module exits.

• hb_inetClearError( <socket> ) ➜ NIL ?
  Clear the socket error value. <socket> a socket previously created / opened.

• hb_inetClearPeriodCallback( <socket> )
  <socket> a socket previously created / opened.
  Clear the periodic callback value of a socket.

• hb_inetClearTimeLimit( <socket> ) ➜ NIL ?
  <socket> a socket previously created / opened.
  Clears the default time limit of the given socket.

• hb_inetClearTimeout( <socket> )
  <socket> a socket previously created / opened.
  Clears the default timeout of the given socket. Default timeout is used in all blocking operations.

• hb_inetClose( <socket> ) ➜ nResult
  Returns 0 on success or -1 on error; on error, the error code is set; (actually, on success the socket error code is set to 1 -- socket closed )
  <socket> is a socket previously created / opened.
  Closes the socket, notifiying both ends of the communication pipe that the connection is over.
  If you have threads waiting for data to be read from this socket, this method will make them stop waiting and return an error (socket closed) to their callers.
  The method does not destroy the socket, which can be used by subordinate threads to check that the socket is closed, and so they should stop as soon as they can. Don't destroy the socket unless you are sure that no other thread is using it.

• hb_inetCompress( <pSocket>, [<nCompressionLevel>], [<nStrategy>], [<cPass>] ) ) ➜ NIL
  enables ZLIB compression for given HB_INET*() socket.
  <pSocket> is a socket created by one of HB_INET*() functions
  <nCompressionLevel> is compression factor between 1 (fastest) and 9 (best) (see HB_ZLIB_COMPRESSION_*) 0 (none) disable compression on output data but decompression is still working.
  <nStrategy> is used to tune compression algorithm, see HB_ZLIB_STRATEGY_*
  The compression must be enabled on both connection sides, i.e.
  on the server side:

  conn := hb_inetAccept( sock )
  hb_inetCompress( conn )

  and on the client side:

  sock := hb_inetConnect( cServer, nPort )
  hb_inetCompress( sock )

  in the same moment but it's not necessary to enable it at the beginning of connection. It can be done later, i.e. when both sides agree to enable connection using some custom protocol.
  The compression has effect only on stream connections, i.e. TCP and it's ignored in datagram connections like UDP.
  This function can be executed more then once changing the compression parameters but it causes that all data in readahead decompression buffer is discarded.
  When called with HB_ZLIB_COMPRESSION_DISABLE as <nCompressionLevel> then support for stream compression is removed and sockets works again in raw mode. The compression level and strategy do not have to be the same on both connection sides. Each side can chose the best settings for data it's going to send. This code was written in a way which allows to easy implement alternative compression methods or other extensions like encryption in existing HB_INET*() sockets also by non core code. The public C functions declared in hbznet.h allows to use this extension with raw harbour sockets too.

• hb_inetCount( <socket> ) ➜ nResult
  <socket> a socket previously created / opened.
  Returns the amount of characters read or written in the latest socket operation.

• hb_inetCreate( [ <nTimeout> ] ) ➜ SOCKET
  returns an INET socket.
  <nTimeout> Socket timeout (optional) in milliseconds. (?)
  Create an INET socket, i.e. the raw data of the socket, that can be passed to a asynchronous connection function (hb_inetConnect() or hb_inetConnectIP()). This will prevent the connection function from allocating some data that could be never used in certain cases, i.e. an asynchronously detected timeout.

• hb_inetErrorCode( <socket> ) ➜ nResult
  Returns the last error code that has been provoked by a network operation, or 0 if none.
  <socket> is a socket previously created / opened.
  Error codes are the ones used for winsock or UnixSockets (they are the same); 1 is reserved for "connection closed" message.

• hb_inetErrorDesc( <socket> ) ➜ cResult
  <socket> a socket previously created / opened.
  Returns System-dependant error string, describing the last error that occurred in the socket; the string is system dependent, and should be used only for debugging purposes.

• hb_inetFD( <socket> [, <lNoSocket> ] ) ➜ nResult
  <socket> a socket previously created / opened. <lNoSocket> ?..

• hb_inetGetSndBufSize( <socket> ) ➜ nResult
  <socket> a socket previously created / opened.
  Returns the socket send buffer size or -1 if the socket is closed or an error occurs.

• hb_inetGetRcvBufSize(<socket>) ➜ nResult
  <socket> a socket previously created / opened.
  Returns the socket receive buffer size or -1 if the socket is closed or an error occurs.

• hb_inetIFInfo( [<lNoAliases>] [, <nAddrFamily>] ) ➜ aInfo
  <lNoAliases> is .F. by default so aliases are included.
  <nAddrFamily> is HB_SOCKET_AF_INET by default.
  Returned value aInfo is an array in which each item is a sub-array with the following fields:

  Defined constant (hbsocket.ch)	#	Returned value
  HB_SOCKET_IFINFO_FAMILY	1	address family
  HB_SOCKET_IFINFO_NAME	2	interface name
  HB_SOCKET_IFINFO_FLAGS	3	flags HB_SOCKET_IFF_*
  HB_SOCKET_IFINFO_ADDR	4	interface address
  HB_SOCKET_IFINFO_NETMASK	5	subnetmask
  HB_SOCKET_IFINFO_BROADCAST	6	broadcast address
  HB_SOCKET_IFINFO_P2PADDR	7	point-to-point address
  HB_SOCKET_IFINFO_HWADDR	8	hardware address

• hb_inetInit() ➜ lResult
  Activates Harbour INET support; returns .T. or .F. whether the internal INET system was successfully initialized or not. At the moment, it's mainly used for winsock start up, but could be used in the future for many other purposes. Put this function at the beginning of every program/module that is using INET functions.

• hb_inetIsSocket(<socket>) ➜ lResult
  Checks wether the passed <socket> (which normally should represent a previously created/opened socket) is actually a socket.

• hb_inetPeriodCallback( <socket> [, <xCallback> ] ) ➜ xPreviousCallback
  <socket> a socket previously created / opened.
  <xCallback> is a new periodic callback.
  Sets or gets the socket periodic callback value. Returns the previous periodic callback value.
  xCallback can be one of: a codeblock, an array of (...), or a (symbol). (Clarification needed...)

• hb_inetPort( <socket> ) ➜ cResult
  <socket> a socket previously created / opened.
  Returns the port name to which this socket is bound, or the remote port if this socket is connected with a remote host or client.

• hb_inetRecv(<socket>, @<cData>, [<nAmount>]) ➜ nBytesRead
  <socket> is a socket previously created/opened
  <cData> is the target buffer that will hold received data, and must be passed by reference
  <nAmount> is the upper limit of characters to be read from the socket. If not passed this defaults to the length of <cData>
  Reads from the socket into a buffer and returns the number of the characters read from the socket. The parameter <cData> must be pre-allocated so that it has enough space to receive the data. This function will block the thread until either some bytes are read from the socket or the socket closed (from the receiver or the sender side) or a network error happened, whatever occurred first. In the latter cases, an error is set, and only the characters received until premature end of communication are returned.
  NOTE: there is no guarantee that all the available bytes will be read before the function returns, in fact, hb_inetRecv() returns as soon as <cData> was filled with one or more bytes. Use the hb_inetRecvAll() to ensure continue receiving data until <cData> buffer is filled or <nAmount> bytes are read.

• hb_inetRecvAll(<socket>, @<cData>, [<nAmount>]) ➜ nBytesRead
  This function works exactly as the above hb_inetRecv() except that it waits until <cData> is entirely filled or until <nAmount> bytes was read. Note that the number of the received bytes might be less than <nAmount> or length of <cData> when a premature socket closing or a network error occurred.

• hb_inetRecvEndblock(<socket> [, <cEoB> [, @<nBytesRead> [, <nMaxLength> [, <nBufSize> ]]]]) ➜ cBlockRead <socket> a socket previously created/opened
  <cEoB> end of block character(s)
  <nBytesRead> must be passed by reference to obtain the number of bytes read
  <nMaxLength> maximum character count before the data is returned
  <nBufSize> memory allocation size
  Returns byte block read.
  This function operates exactly the same way as hb_inetRecvLine() (see below), but the "record termination" is customizable through the <cEoB> (end of block) parameter which if not given, defaults to the CRLF sequence.

• hb_inetRecvLine(<socket> [, @<nBytesRead>, [, <nMaxLength> [, <nBufSize> ]]]) ➜ cLineRead
  <socket> a socket previously created/opened
  <nBytesRead> must be passed by reference to obtain the number of bytes read
  <nMaxLength> maximum character count before the data is returned
  <nBufSize> memory allocation size
  Receives data until a CRLF sequence is read from the socket.
  If an error occurs, or if the stream is closed before a CRLF is read, the function returns empty string and sets the socket error.
  The returned string does not contain the trailing CRLF sequence, so an empty line is returned as an empty string.
  If the <nBytesRead> parameter is given (and passed by reference), it will contain the number of bytes read from the socket, including the CRLF length, so that in normal conditions, will report a count equal to the length of the returned string plus 2. It will be 0 if stream is closed before a CRLF sequence is read, and will be -1 on error.
  An optional <nMaxLength> parameter can be given to allow a maximum character count before the data is returned anyway. If this number is reached before a CRLF sequence is encountered, <nBytesRead> will contain the value one.
  If <nBufSize> parameter is given specifies the size of memory allocation; if not given, memory allocation will be increased by discrete amounts of 80 bytes. The programmer can provide here a different allocation strategy (e.g. setting <nBufSize> equal to <nMaxLength>, memory for reading the line will be allocated only once, at the beginning of the function).

• hb_inetSend(<socket>, <cBuffer> [, <nLength>]) ➜ nBytesSent
  <socket> a socket previously created/opened
  <cBuffer> content to be sent
  <nLength> amount of bytes to be sent (optional)
  Sends the data stored in <cBuffer>, over the socket.
  The <nLength> parameter can be given that specifies sending only a part of the buffer.
  There is no guarantee that all of <cBuffer> will be sent, as this is a decision that is up to the O/S; this function does not take care to ensure that the data is really sent. Check the returned number and send the part that has not been sent.
  To ensure that all the intended data have been sent, before the function returns, use the hb_inetSendAll() function. Returns the amount of data written or 0 (zero) if the socket is closed, or -1 on error. Also, on error, the error in the socket is set.

• hb_inetSendAll( , [, ] ) ➜ nBytesSent
  <socket> a socket previously created/opened
  <cBuffer> content to be sent
  <nLength> amount of bytes to be sent
  This function works exactly as above hb_inetSend() but it ensures that all the data to be sent, are actually written, before returning.

• hb_inetServer(<port> [,<cBindAddr> [,<nListenLimit>]]) ➜ SOCKET
  <port> port of the socket
  <cBindAddr>
<nListenLimit> is an internal parameter and rarely needs to be passed, defaults to 10
  Creates a server that can accept connections from client on a certain port.
  If the computer, on which hb_inetServer() is called, has more than one logical interface (e.g. one network card, one loopback and one PPP address), <cBindAddr> can be specified to select only one of these interfaces to accept connections for this process. This is useful when a server is present on two networks, and the service is to be available only in one of them. Also, the same port on other addresses is left free to be used, so you can have different server programs running for different networks but managing the same service. For example, an FTP server available to the internal network could be radically different from an FTP server available for the internet.
  <nListenLimit> is the number of incoming connections accepted by kernel before the kernel has the chance to report them to the application program. If the sockets receive <nListenLimit> connections before accepting them all, the nListenLimit + 1 connection will be notified to be "busy" by the kernel. The default value of 10 is enough for even a heavy duty server.
  Returns an INET socket to be used for INET operations. On error, sets error description in the newly returned socket.

• hb_inetStatus( <socket> ) ➜ nResult
  Get the status of a socket <socket> a socket previously created / opened.
  Returns 1 if the socket exists, -1 if it does not.

• hb_inetTimeLimit( <socket> [, <nTimeLimit>] ) ➜ NIL
  <socket> a socket previously created / opened.
  <nTimeLimit> new time limit value to set.
  Sets or changes the time limit value of the socket. Returns the previous time limit value of the socket

• hb_inetTimeout( <socket> [, <nTimeout> ] ) ➜ nPreviousTimeout
  <socket> a socket previously created / opened.
  <nTimeout> is the new socket timeout value.
  Get or sets/change the timeout value of a socket.
  Returns the previous timeout value of the socket

🔙 Home