96e069c19e
* include/hbextern.ch
* src/rtl/Makefile
+ src/rtl/hbdoc.prg
+ Added __HBDOC_LOADDIR() internal RTL function to read
NFDOC formatted documentation source directories into
memory. The result will be a list of hashes which contain
the raw content of doc files. The function does format
validation (but not content) and add all agreed-on metadata
to the hashes.
It's a start and I hope others can join to create new
layers of function for below functionality:
- doc content validation
- pre-formatting
- output generators
The goal is to avoid local solutions and standardize
the format.
+ tests/hbdoctst.prg
+ Added small test app which will find and parse all
documentation inside the Harbour source tree and
save them in .hbd (serialized doc hash) format.
Such .hdb files can be generated by the build process
in the future, so tools like HBIDE can use the content
to display intellisense or built-in help.
; TODO: HBQT doc/html should be removed as it's
hbdoc tools' job to convert HBDOC source
format to html or whatever else format needed.
* harbour.spec
* debian/rules
- doc/man
+ src/pp/hbpp.1
+ src/main/harbour.1
+ utils/hbmk2/hbmk2.1
+ utils/hbtest/hbtest.1
+ utils/hbrun/hbrun.1
* Moved man doc files to their own component dirs.
* doc/Makefile
* doc/en/Makefile
+ doc/clipper.txt
- doc/en/clipper.txt
* Moved non-NFDOC formatted doc file to doc dir.
* doc/en/Makefile
! Fixed missing 1stread.txt
* doc/en/hb_apigt.txt
* doc/en/hbinet.txt
* doc/en/tbrowse.txt
* doc/en/hb_apifs.txt
! Fixed NFDOC non-standard entries.
* bin/hbxpatch.hbs
! Fixed detecting dirs. (could cause errors only in rare cases)
* contrib/hbdoc2/tmplates.prg
* Formatting.
1829 lines
40 KiB
Plaintext
1829 lines
40 KiB
Plaintext
/*
|
|
* $Id$
|
|
*/
|
|
|
|
/*
|
|
* The following parts are Copyright of the individual authors.
|
|
* www - http://harbour-project.org
|
|
*
|
|
* Copyright (date unknown) Giancarlo Niccolai <gian@niccolai.ws>
|
|
* Documentation for: Harbour INET API
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2, or (at your option)
|
|
* any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this software; see the file COPYING. If not, write to
|
|
* the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
|
|
* Boston, MA 02111-1307 USA (or visit the web site http://www.gnu.org/).
|
|
*
|
|
* As a special exception, the Harbour Project gives permission for
|
|
* additional uses of the text contained in its release of Harbour.
|
|
*
|
|
* The exception is that, if you link the Harbour libraries with other
|
|
* files to produce an executable, this does not by itself cause the
|
|
* resulting executable to be covered by the GNU General Public License.
|
|
* Your use of that executable is in no way restricted on account of
|
|
* linking the Harbour library code into it.
|
|
*
|
|
* This exception does not however invalidate any other reasons why
|
|
* the executable file might be covered by the GNU General Public License.
|
|
*
|
|
* This exception applies only to the code released by the Harbour
|
|
* Project under the name Harbour. If you copy code from other
|
|
* Harbour Project or Free Software Foundation releases into a copy of
|
|
* Harbour, as the General Public License permits, the exception does
|
|
* not apply to the code that you add in this way. To avoid misleading
|
|
* anyone as to the status of such modified files, you must delete
|
|
* this exception notice from them.
|
|
*
|
|
* If you write modifications of your own for Harbour, it is your choice
|
|
* whether to permit this exception to apply to your modifications.
|
|
* If you do not wish that, delete this exception notice.
|
|
*
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETINIT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Activate Harbour INET support
|
|
* $SYNTAX$
|
|
* HB_INETINIT() -> lResult
|
|
* $ARGUMENTS$
|
|
* (This function has no arguments)
|
|
* $RETURNS$
|
|
* Returns .T. or .F. whether the internal INET system was successfully initialized
|
|
* $DESCRIPTION$
|
|
* Activates inet support; mainly used for winsock start up at the moment, but
|
|
* could be used in the future for many other purpose. Put it at the beginning
|
|
* of every program using INET functions.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Procedure
|
|
* $NAME$
|
|
* HB_INETCLEANUP
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Terminate Harbour INET support
|
|
* $SYNTAX$
|
|
* HB_INETCLEANUP()
|
|
* $ARGUMENTS$
|
|
* (This function has no arguments)
|
|
* $DESCRIPTION$
|
|
* Closes inet support; mainly used for Windows. Put it at the end of any program
|
|
* using Inet functions, just before the program exits.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETCREATE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Create an INET socket
|
|
* $SYNTAX$
|
|
* HB_INETCREATE( [ <nTimeout> ] ) -> SOCKET
|
|
* $ARGUMENTS$
|
|
* <nTimeout> Socket timeout (optional) TODO: what is the scale (seconds, milliseconds?)
|
|
* $RETURNS$
|
|
* An INET socket
|
|
* $DESCRIPTION$
|
|
* Creates 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.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETCLOSE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Close an INET socket
|
|
* $SYNTAX$
|
|
* HB_INETCLOSE( <socket> ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* 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 )
|
|
* $DESCRIPTION$
|
|
* 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.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETFD
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* ?
|
|
* $SYNTAX$
|
|
* HB_INETFD( <socket> [, <lNoSocket> ] ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <lNoSocket>
|
|
* $RETURNS$
|
|
* ?
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETSTATUS
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the status of a socket
|
|
* $SYNTAX$
|
|
* HB_INETSTATUS( <socket> ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Returns 1 (one) if the socket exists, -1 if it does not
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETERRORCODE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the last INET error code
|
|
* $SYNTAX$
|
|
* HB_INETERRORCODE( <socket> ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Last error code
|
|
* $DESCRIPTION$
|
|
* Returns the last error code that has been provoked by a network operation,
|
|
* or 0 if none.
|
|
*
|
|
* Error codes are the ones used for winsock or UnixSockets (they
|
|
* are the same); 1 is reserved for "connection closed" message.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETERRORDESC
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the last INET error code description
|
|
* $SYNTAX$
|
|
* HB_INETERRORDESC( <socket> ) -> cResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* System-dependant error string
|
|
* $DESCRIPTION$
|
|
* Returns a string describing the last error that occurred in the socket;
|
|
* the string is system dependent, and should be used only for debugging
|
|
* purposes.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Procedure
|
|
* $NAME$
|
|
* HB_INETCLEARERROR
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Clear the socket error value
|
|
* $SYNTAX$
|
|
* HB_INETCLEARERROR( <socket> )
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETCOUNT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the number of bytes last read or sent
|
|
* $SYNTAX$
|
|
* HB_INETCOUNT( <socket> ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Last socket operation character count
|
|
* $DESCRIPTION$
|
|
* Returns the amount of characters read or written in the latest socket
|
|
* operation.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETADDRESS
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get a remote server address
|
|
* $SYNTAX$
|
|
* HB_INETADDRESS( <socket> ) -> cResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Server address
|
|
* $DESCRIPTION$
|
|
* 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.
|
|
*
|
|
* TODO: have a version that returns a vector of 4 numbers.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETPORT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the port a socket is bound to.
|
|
* $SYNTAX$
|
|
* HB_INETPORT( <socket> ) -> cResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Port name the socket is bound to.
|
|
* $DESCRIPTION$
|
|
* Returns the port to which this socket is bound, or the remote port if this
|
|
* socket is connected with a remote host or client
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETTIMEOUT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get or change the timeout value of a socket
|
|
* $SYNTAX$
|
|
* HB_INETTIMEOUT( <socket> [, <nTimeout> ] ) -> nPreviousTimeout
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <nTimeout> is the new socket timeout value
|
|
* $RETURNS$
|
|
* Returns the previous timeout value of the socket
|
|
* $DESCRIPTION$
|
|
* Sets or changes the timeout value of the socket.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Procedure
|
|
* $NAME$
|
|
* HB_INETCLEARTIMEOUT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Clear the timeout value of a socket
|
|
* $SYNTAX$
|
|
* HB_INETCLEARTIMEOUT( <socket> )
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $DESCRIPTION$
|
|
* Clears the default timeout of the given socket. Default timeout is used in all
|
|
* blocking operations.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETTIMELIMIT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get or change the time limit value of a socket
|
|
* $SYNTAX$
|
|
* HB_INETTIMELIMIT( <socket> [, <nTimeLimit> ) -> NIL
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <nTimeLimit>
|
|
* $RETURNS$
|
|
* Returns the previous time limit value of the socket
|
|
* $DESCRIPTION$
|
|
* Sets or changes the time limit value of the socket.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Procedure
|
|
* $NAME$
|
|
* HB_INETCLEARTIMELIMIT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Clear the time limit value of a socket
|
|
* $SYNTAX$
|
|
* HB_INETCLEARTIMELIMIT( <socket> )
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $DESCRIPTION$
|
|
* Clears the default time limit of the given socket.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETPERIODCALLBACK
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get or change the periodic callback value of a socket
|
|
* $SYNTAX$
|
|
* HB_INETPERIODCALLBACK( <socket> [, <xCallback> ] ) -> xPreviousCallback
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* xCallback a new periodic callback
|
|
* $RETURNS$
|
|
* The previous periodic callback value
|
|
* $DESCRIPTION$
|
|
* Sets or returns the socket periodic callback value
|
|
*
|
|
* xCallback can be one of: a codeblock, an array of (...), or a (symbol)
|
|
* TODO: describe these better
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Procedure
|
|
* $NAME$
|
|
* HB_INETCLEARPERIODCALLBACK
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Clear the periodic callback value of a socket
|
|
* $SYNTAX$
|
|
* HB_INETCLEARPERIODCALLBACK( <socket> )
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETGETSNDBUFSIZE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the socket send buffer size
|
|
* $SYNTAX$
|
|
* HB_INETGETSNDBUFSIZE( <socket> ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Returns the socket send buffer size or -1 if the socket is closed or an error occurs
|
|
* $DESCRIPTION$
|
|
* Returns the socket send buffer size or -1 if the socket is closed or an error occurs
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETGETRCVBUFSIZE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get the socket receive buffer size
|
|
* $SYNTAX$
|
|
* HB_INETGETRCVBUFSIZE( <socket> ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Returns the socket receive buffer size or -1 if the socket is closed or an error occurs
|
|
* $DESCRIPTION$
|
|
* Returns the socket receive buffer size or -1 if the socket is closed or an error occurs
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETSETSNDBUFSIZE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Set the send buffer size of a socket
|
|
* $SYNTAX$
|
|
* HB_INETSETSNDBUFSIZE( <socket>, <nSize> ) -> nSize
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* nSize
|
|
* $RETURNS$
|
|
* Returns the passed nSize or -1 on error
|
|
* $DESCRIPTION$
|
|
* Sets the send buffer size of a socket
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETSETRCVBUFSIZE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Set the receive buffer size of a socket
|
|
* $SYNTAX$
|
|
* HB_INETSETRCVBUFSIZE( <socket>, nSize ) -> nSize
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* nSize
|
|
* $RETURNS$
|
|
* Returns the passed nSize or -1 on error
|
|
* $DESCRIPTION$
|
|
* Sets the receive buffer size of a socket
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETRECV
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Read from a socket
|
|
* $SYNTAX$
|
|
* HB_INETRECV( <socket>, @<cResult>, [ <nAmount> ] ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cResult> is the target buffer 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 cResult
|
|
* $RETURNS$
|
|
* The number of the characters read from the socket.
|
|
* $DESCRIPTION$
|
|
* Reads from the socket into a buffer.
|
|
*
|
|
* The parameter cString must be preallocated so that it has enough
|
|
* space to receive the data. The routine will block the thread until some
|
|
* bytes are read from the socket, the socket is closed (either from the
|
|
* receiver or the sender side) or a network error occurs, whichever comes
|
|
* first. In the latter cases, an error is set, and only the characters
|
|
* received until premature end of communications are returned.
|
|
*
|
|
* Notice that there is no guarantee that all the available bytes will be
|
|
* read before the function returns, in fact, hb_InetRecv returns as soon it
|
|
* is able to fill cString with one or more bytes. To block the current
|
|
* process until the whole cString is filled (or nAmount bytes are read),
|
|
* use the hb_InetRecvALL().
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETRECVALL
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Read from a socket without blocking
|
|
* $SYNTAX$
|
|
* HB_INETRECVALL( <socket>, @<cResult>, [ <nAmount> ] ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cResult> is the target buffer 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 cResult
|
|
* $RETURNS$
|
|
* The number of the characters read from the socket. Might be
|
|
* less than nAmount on premature socket closing or on network error.
|
|
* $DESCRIPTION$
|
|
* This function works exactly as hb_InetRecv except that it
|
|
* blocks until nAmount bytes are read, if nAmount is given, or
|
|
* cString is filled for its whole length.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETRECVLINE
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Read a line from a socket
|
|
* $SYNTAX$
|
|
* HB_INETRECVLINE( <socket> [, @<nBytesRead>, [, <nMaxLength> [, <nBufSize> ]]] ) -> cResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <nBytesRead> must be passed by reference
|
|
*
|
|
* <nMaxLength>
|
|
*
|
|
* <nBufSize>
|
|
* $RETURNS$
|
|
* Line read
|
|
* $DESCRIPTION$
|
|
* Blocks the calling thread until a sequence CRLF is read from the socket.
|
|
* Incremental allocation and end-of-line checking are done in an efficient
|
|
* way.
|
|
*
|
|
* If an error occurs, or if the stream is closed before a CRLF is read,
|
|
* the function returns nothing and sets the socket error.
|
|
*
|
|
* The returned string does not contain the trailing CRLF sequence, so an
|
|
* empty line is effectively returned as an empty string.
|
|
*
|
|
* If the nBytesRead parameter is given, it will contain the number of bytes
|
|
* read from the socket, including the CRLF sequence, so that in normal
|
|
* conditions, nResult will report a count equal to the length of the
|
|
* returned string plus 2. nBytesRead 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.
|
|
*
|
|
* Finally, a nBufSize parameter can be given. If not, 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).
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETRECVENDBLOCK
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Read a block from a socket
|
|
* $SYNTAX$
|
|
* HB_INETRECVENDBLOCK( <socket> [, <cBlock >[, @<nBytesRead> [, <nMaxLength> [, <nBufSize> ]]]] ) -> cResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cBlock>
|
|
*
|
|
* <nBytesRead>
|
|
*
|
|
* <nMaxLength>
|
|
*
|
|
* <nBufSize>
|
|
* $RETURNS$
|
|
* Block read
|
|
* $DESCRIPTION$
|
|
* This function operates exactly the same way as hb_InetRecvLine, but
|
|
* the "record termination" is customizable through the cBlock parameter.
|
|
* If not given, this parameter defaults to the CRLF sequence.
|
|
* Provided by: Marcelo Lombardo
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETDATAREADY
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get whether there is data ready in a socket
|
|
* $SYNTAX$
|
|
* HB_INETDATAREADY( <socket>, [ <nMillisec> ] ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <nMillisec>
|
|
* $RETURNS$
|
|
* If there is data available 1 (one) is returned, 0 (zero) if there is no data
|
|
* and -1 if there is an error.
|
|
* $DESCRIPTION$
|
|
* Verifies if some data is available to be read in the socket without blocking
|
|
* execution of the caller.
|
|
*
|
|
* If nMillisecs is not given, the function returns
|
|
* immediately 1 if there is some data to be read, 0 if there isn't any data and
|
|
* -1 in case of error.
|
|
*
|
|
* If nMillisecs is given, the functon will wait up to that
|
|
* amount of milliseconds for data to be available; if some data arrives in the
|
|
* meanwhile, the wait is immediately interrupted.
|
|
*
|
|
* The next hb_InetRecv() function will read all the available data (up to the
|
|
* required length) without blocking.
|
|
*
|
|
* On error, hb_InetErrorCode and hb_InetErrorDesc can be use to determine what kind
|
|
* of error happened.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETSEND
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Sent data through a socket
|
|
* $SYNTAX$
|
|
* HB_INETSEND( <socket>, <cBuffer> [, <nLength> ] ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cBuffer>
|
|
*
|
|
* <nLength>
|
|
* $RETURNS$
|
|
* The amount of data written, 0 (zero) if the socket is closed, or -1 on an error
|
|
* $DESCRIPTION$
|
|
* Send data being stored in a string over the socket.
|
|
*
|
|
* The nLength parameter can be given to allow writing only a part of
|
|
* the string.
|
|
*
|
|
* There is no guarantee that all of cBuffer will be
|
|
* sent, as this is a decision that is up to the OS; 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 data is sent before the function returns, use the
|
|
* hb_InetSendAll() function.
|
|
*
|
|
* On error, the error in the socket is set.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETSENDALL
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Send data through a socket with blocking
|
|
* $SYNTAX$
|
|
* HB_INETSENDALL( <socket>, <cBuffer> [, <nLength> ] ) -> nResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cBuffer>
|
|
*
|
|
* <nLength>
|
|
* $RETURNS$
|
|
* The amount of data written, 0 (zero) if the socket is closed, or -1 on an error
|
|
* $DESCRIPTION$
|
|
* This function works exactly as hb_InetSend() but it ensures that all the
|
|
* data to be sent is written before returning.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETGETHOSTS
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get an array of IP addresses of a host
|
|
* $SYNTAX$
|
|
* HB_INETGETHOSTS( <cName> ) -> aHosts
|
|
* $ARGUMENTS$
|
|
* <cName>
|
|
* $RETURNS$
|
|
* An array of IP addresses
|
|
* $DESCRIPTION$
|
|
* Returns an array containing all the IP addresses associated with a given
|
|
* host name. The IP addressess returned by this funtion are strings in
|
|
* quad dot notations, eg "192.168.1.1", and can be directly used into
|
|
* hb_InetConnectIP().
|
|
*
|
|
* cName can be any string: valid DNS names (eg.
|
|
* "www.myserver.com"), locally available names (e.g. "localhost" or
|
|
* windows Network Neighborhood names), or even IP addresses in quad
|
|
* dot notation.
|
|
*
|
|
* NOTE: This function is not thread safe (by design), and programmers
|
|
* must be sure not to use it at the same time in two different threads,
|
|
* or not to use it together with a hb_InetConnect(). If this kind of situation
|
|
* should ever arise, you are advised to use a thread MUTEX.
|
|
*
|
|
* On error, and if the server can't be found, the function returns NIL.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETGETALIAS
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get an array of aliases of a server
|
|
* $SYNTAX$
|
|
* HB_INETGETALIAS( <cName> ) -> aHosts
|
|
* $ARGUMENTS$
|
|
* <cName>
|
|
* $RETURNS$
|
|
* Array of server aliases
|
|
* $DESCRIPTION$
|
|
* Returns an array containing the aliases ( CNAME DNS records ) by
|
|
* which the server is currently known.
|
|
*
|
|
* Whether this function is able
|
|
* to have the complete list of aliases or not depends on the verbosity
|
|
* of the DNS server.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETSERVER
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Create a socket bound to a port
|
|
* $SYNTAX$
|
|
* HB_INETSERVER( <port> [, <cBindAddr> [, <nListenLimit> ]] ) -> SOCKET
|
|
* $ARGUMENTS$
|
|
* <port>
|
|
*
|
|
* <cBindAddr>
|
|
*
|
|
* <nListenLimit> is an internal parameter and rarely needs to be passed, defaults to 10
|
|
* $RETURNS$
|
|
* An INET socket
|
|
* $DESCRIPTION$
|
|
* 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.
|
|
*
|
|
* On error, sets error description in the newly returned socket.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETACCEPT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Wait until a socket is ready
|
|
* $SYNTAX$
|
|
* HB_INETACCEPT( <socket> ) -> SOCKET
|
|
* $ARGUMENTS$
|
|
* An INET socket
|
|
* $RETURNS$
|
|
* <socket> a socket previously created / opened
|
|
* $DESCRIPTION$
|
|
* 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.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETCONNECT
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Connect a socket to a remote server by IP address or name
|
|
* $SYNTAX$
|
|
* HB_INETCONNECT( <cAddress>, <nPort> ) -> SOCKET
|
|
*
|
|
* HB_INETCONNECT( <cAddress>, <nPort>, <socket> ) -> NIL
|
|
* $ARGUMENTS$
|
|
* <cAddress>
|
|
*
|
|
* <nPort>
|
|
*
|
|
* <socket>
|
|
* $RETURNS$
|
|
* (First form) INET socket
|
|
*
|
|
* (Second form has no return value)
|
|
* $DESCRIPTION$
|
|
* Connects to a remote server described by cAddress, that can be in
|
|
* quad dot notation (e.g. "192.168.1.1") or in DNS name (e.g.
|
|
* "www.xharbour.org"), using the desired port.
|
|
*
|
|
* hb_InetConnect uses "gethostbyname" C system call to
|
|
* find the network address of the specified server; this means that
|
|
* this call is an hybrid function doing both a DNS scan and a TCP/IP
|
|
* connection. hb_InetConnect is not thread safe, and the
|
|
* program must take care that two hb_InetConnect functions are never
|
|
* called at the same moment from two different threads (or that
|
|
* hb_InetGetHosts is not called in the same moment as an hb_InetConnect).
|
|
*
|
|
* The second version of this function accepts a pre-built socket
|
|
* as a parameter. This allows to kill asyncronously a thread waiting
|
|
* for hb_InetConnect to connect, and then cleaning up the leftover
|
|
* socket data. Also, it is possible to give timeout to the given SOCKET,
|
|
* but this timeout will be used only in the connection phase, after that
|
|
* the network address resolution is completed. Use GetHosts() and
|
|
* hb_InetConnectIP for a finer timeout control.
|
|
* On error, the error of the returned socket is set. The error could
|
|
* be due to unavailable name resolving service, host name not valid,
|
|
* host address not reachable and host reachable but port not open.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETCONNECTIP
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Connect to a remote server by IP address
|
|
* $SYNTAX$
|
|
* HB_INETCONNECTIP( <cAddress>, <nPort> ) -> SOCKET
|
|
*
|
|
* HB_INETCONNECTIP( <cAddress>, <nPort>, <socket> ) -> NIL
|
|
* $ARGUMENTS$
|
|
* <cAddress>
|
|
*
|
|
* <nPort>
|
|
*
|
|
* <socket>
|
|
* $RETURNS$
|
|
* (First form) INET socket
|
|
*
|
|
* (Second form has no return value)
|
|
* $DESCRIPTION$
|
|
* Connects to a remote server described by cAddress, that can be specified
|
|
* only in quad dot IPV4 notation (e.g. "127.0.0.1"), using the desired port.
|
|
* This version of hb_InetConnect does not use gethostbyname, and thus is thread
|
|
* safe and can be used in combination with hb_InetGetHosts to have a finer
|
|
* timeout control while connecting to a server, and a finer error control.
|
|
*
|
|
* The second version of this function accepts a pre-built socket
|
|
* as a parameter. This allows to kill asyncronously a thread waiting
|
|
* for hb_InetConnectIP to connect, and then cleaning up the leftover
|
|
* socket data. Also, it is possible to give timeout at the given SOCKET.
|
|
*
|
|
* On error, the error of the returned socket is set.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETDGRAM
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Create a datagram socket
|
|
* $SYNTAX$
|
|
* HB_INETDGRAM( [<lBroadcast>] ) -> SOCKET
|
|
* $ARGUMENTS$
|
|
* lBroadcast
|
|
* $RETURNS$
|
|
* An INET socket
|
|
* $DESCRIPTION$
|
|
* Creates a datagram-oriented socket that will be able to send data and
|
|
* eventually receive data. Since the socket is not bound, the program can't
|
|
* retrieve the address at which this socket appaers to be, but a second
|
|
* socket receiving a message sent from this one would be able to reply
|
|
* correctly with a datagram that can be read from a non-bound socket.
|
|
*
|
|
* If lBroadcast is set to .T., the routine creates a broadcast capable socket:
|
|
* it will be able to receive and send broadcast messages. On most systems this
|
|
* requires special user privileges.
|
|
*
|
|
* Returns the socket, and if an error occurs, the socket error message
|
|
* and code are set.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETDGRAMBIND
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Create a bound datagram socket
|
|
* $SYNTAX$
|
|
* HB_INETDGRAMBIND( <nPort>, [<cAddress> [, <lBroadcast>] ] ) -> SOCKET
|
|
* $ARGUMENTS$
|
|
* <nPort>
|
|
*
|
|
* <cAddress>
|
|
*
|
|
* <bBroadcast>
|
|
* $RETURNS$
|
|
* An INET socket
|
|
* $DESCRIPTION$
|
|
* Creates a datagram-oriented socket and binds it to a particular port, and
|
|
* eventually to a certain interface if cAddress is given and not NIL.
|
|
*
|
|
* If lBroadcast is set to .T., the routine creates a broadcast capable socket:
|
|
* it will be able to receive and send broadcast messages. On most systems this
|
|
* requires special user privileges.
|
|
*
|
|
* Returns the socket
|
|
*
|
|
* If an error occurs, the socket error message
|
|
* and code are set.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETDGRAMSEND
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Send data to a datagram socket
|
|
* $SYNTAX$
|
|
* HB_INETDGRAMSEND( <socket>, <cAddress>, <nPort>, <cBuffer> [, <nSize> ] ) -> nBytesSent
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cAddress>
|
|
*
|
|
* <nPort>
|
|
*
|
|
* <cBuffer>
|
|
*
|
|
* <nSize>
|
|
* $RETURNS$
|
|
* Returns number of bytes sent, or -1 on error
|
|
* $DESCRIPTION$
|
|
* Sends a datagram (a fixed length data) to a determined ip address (cAddress,
|
|
* to be specified in quad-dot notation) and port.
|
|
*
|
|
* If nSize is not specified,
|
|
* all the data in cBuffer will be sent; if nSize is specified, only
|
|
* the first nSize bytes of cBuffer will be sent.
|
|
*
|
|
* There isn't any guarantee that all the data required to be written is
|
|
* really sent to the socket: the calling program should check for the
|
|
* numeric return and send iteratively the unsent data to complete
|
|
* the message.
|
|
*
|
|
* Anyway, the raw datagram is sent and received as once, and any data
|
|
* less than the system datagram size will be sent and received
|
|
* as a single item.
|
|
*
|
|
* If the socket is created in broadcast mode, the cAddress element
|
|
* can be a broadcast address.
|
|
*
|
|
* Returns -1 on error, or the number of bytes actually sent on success.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETDGRAMRECV
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get data from a datagram socket
|
|
* $SYNTAX$
|
|
* HB_INETDGRAMRECV( <socket>, @<cBuffer> [, <nSize> ] ) -> nBytesRead
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
*
|
|
* <cBuffer> is the target buffer and must be passed by reference
|
|
*
|
|
* <nSize>
|
|
* $RETURNS$
|
|
* Returns number of bytes read, or -1 on error
|
|
* $DESCRIPTION$
|
|
* Reads at maximum nSize bytes incoming from a UDP socket, if nSize is
|
|
* given, or reads at maximum cBuffer length if nSize is not given.
|
|
*
|
|
* There isn't any guarantee that all the data required to be read is
|
|
* really sent from the kernel to the application: the kernel should
|
|
* just return the last complete datagram that has been received, up
|
|
* to nSize bytes.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETCRLF
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get a CRLF sequence for internet protocols
|
|
* $SYNTAX$
|
|
* HB_INETCRLF() -> cResult
|
|
* $ARGUMENTS$
|
|
* (This function has no arguments)
|
|
* $RETURNS$
|
|
* Internet CRLF sequence
|
|
* $DESCRIPTION$
|
|
* Returns a CRLF sequence used in many internet protocols.
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_INETISSOCKET
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* INET
|
|
* $ONELINER$
|
|
* Get whether a variable is a socket
|
|
* $SYNTAX$
|
|
* HB_INETISSOCKET( <socket> ) -> lResult
|
|
* $ARGUMENTS$
|
|
* <socket> a socket previously created / opened
|
|
* $RETURNS$
|
|
* Returns whether the passed parameter is a socket
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
*
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|