Tcp4u - HTTP related functions


Http4uErrorString


This function translates integer error codes into constants strings.

Syntax:   const char *Http4uErrorString (int msg_code);


Arguments:

msg_code
An Http4u error code


Return:

LPCSTR
A long pointer on the error string associated with msg_code.

Http4uSetBufferSize


This functions changes the internal buffer size. By default, Http4u uses 4k buffers. If a value attempts to reduce the internal buffer below 256 bytes, a buffer of 256 is used.

Syntax:   void Http4uSetBufferSize (unsigned uBufferSize);


Arguments:

uBufferSize
The new buffer size in bytes. This value can not be lower than 256 bytes

Http4uSetTimeout


This functions changes the internal timeout. The new value is given in seconds. By default, Http4u uses a 60 seconds timeout.
Note: If used in a multi-thread environment or in a shared library (DLL or .so files), this value is changed for all threads or processes. However, it will not change the behavior of a waiting call.

Syntax:   Http4uSetTimeout (unsigned uTimeout);


Arguments:

uTimeout
The new timeout in seconds.

HttpGetFile


This function retrieves a file using the HTTP protocol and copy it into a local file. It can be used through a firewall.
The remote file name, its location, the server name and the port to be used are packed into the URL string. The URL format is specified in the RFC1738.
Since HttpGetFile accepts only the HTTP protocol, the "http:" specifications in the URL can be shortened. Thus the URL has the following form:
[http://]host[:port][/directory][file]
The URL of the proxy server (firewall) should have the same format.
Notes:

Syntax:   HttpGetFile (const char *szURL, 
                       const char *szProxyURL,
                       const char *szFile);

Arguments:

szURL
The URL which specify the remote file to be retrieved
szProxyURL
The URL of the proxy or NULL
szLocalFile
The local file to be written


Returns:

HTTP4U_BAD_PARAM
szLocalFile is NULL
HTTP4U_BAD_REQUEST
The HTTP rejects the request
HTTP4U_BAD_URL
Http4u can not process one of the given URL
HTTP4U_CANCELLED
A blocking call has been canceled by a TcpAbort call or by a user signal.
HTTP4U_FILE_ERROR
Http4u can not open the destination file or write into it
HTTP4U_FORBIDDEN
User has no right access to this file
HTTP4U_INSMEMORY
Http4u can not allocate its local buffers (since it does not much memory, this should not happen !)
HTTP4U_MOVED
The HTTP server answers that the requested file is no more at this location
HTTP4U_NO_CONTENT
The received file is empty.
HTTP4U_NOT_FOUND
Requested file has not been found
HTTP4U_OVERFLOW
The HTTP server overflows Http4u's buffers
HTTP4U_PROTOCOL_ERROR
Http4u can not process the given answer
HTTP4U_SUCCESS
Http4u has completed the task
HTTP4U_TCP_CONNECT
Http4u can not establish a connection with the remote host
HTTP4U_TCP_FAILED
Tcp4uInit has not been called or an undetermined network error has happened
HTTP4U_TIMEOUT
A timeout happen during a receive call

Exemple: 
  HttpGetFile ("http://www.magic.fr/~jounin-ph",  /* URL to be retrieved */
               "my_fw.fr:8080",    /* Use firewall my_fw.fr on port 8080 */
               "welcome.html"           /* save location in welcome.html */
              );


HttpGetFileEx


This function retrieves a file using the HTTP protocol and copy it into a local file.
A proxy server can be specified in order to reach a site through a firewall.
HTTP4U waits for a 3 parts response sent by the remote server (See RFC1945 for more information) :

Http4u is able to return each part to the application as soon as available. The Status Code and Response Header fields are returned into buffers. The Response Header field can be written into a file.
In order to return the Entity field, a callback user-function is called each time a new frame is read from the network. This callback function accepts following arguments filled by Http4u:

long lBytesTransferred
The number of bytes received for the file (not including headers)
long lTotalBytes
The length of the file to be retrieved. If Http4u can not read it, a value of -1 is passed to the function
long lUserValue
This parameter is a copy of the lUserValue value passed to HttpGetFileEx. It can be filled with a thread id, a pointer...
const char *sBuf
A pointer on the data which have been read. These data must be saved by the application.
Int nRvcd
The number of bytes which have been received.


The first time this function is called, lBytesTransferred and nRcvd are set to 0. This call tells the application that the file is to be retrieved.
If this callback function returns FALSE, the transfer is stopped and the value HTTP4U_CANCELLED is returned to the application.
Notes :

Syntax:   HttpGetFileEx (const char *szURL, 
                         const char *szProxyURL,
                         const char *szFile,
                         const char *szHeaderFile,
                         BOOL CALLBACK (*CbkTransmit)(),
                         long  lUserValue,
                         char *szResponse, 
                         int   nResponseSize,
                         char *szHeaders,
                         int   nHeadersSize);

Arguments:

szURL
The URL which specify the remote file to be retrieved
szProxyURL
The URL of the proxy server or NULL
szLocalFile
The local file to be written. If this parameter is NULL, the file is not retrieved.
SzHeaderFile
The local file which will contain the header frame
CbkTransmit
A user function which will be called each time a frame is read from the network. This function accepts 3 parameters and returns a boolean value.
lUserValue
A value which is passed to CbkTransmit. If CbkTransmit is NULL, this value is not used.
SzResponse
A user's buffers which is to be filled with the field Status Code and Reason Phrase. If this value is NULL, the status frame is not returned to the user.
nResponseSize
The size of the previous buffer
szHeaders
A user's buffers which is to be written with the field Response Header. If this value is NULL, the header frame is not returned to the user.
nHeaderSize
The size of the previous buffer


Returns:

HTTP4U_BAD_PARAM
An error in the parameters has been detected
HTTP4U_BAD_REQUEST
The HTTP rejects the request
HTTP4U_BAD_URL
Http4u can not process the given URL
HTTP4U_CANCELLED
A blocking call has been canceled by a TcpAbort call or by a user signal.
HTTP4U_FILE_ERROR
Http4u can not open the destination file or write into it
HTTP4U_FORBIDDEN
User has no right access to this file
HTTP4U_INSMEMORY
Http4u can not allocate its local buffers (since it does not much memory, this should not happen !)
HTTP4U_MOVED
The HTTP server answers that the requested file is no more at this location
HTTP4U_NO_CONTENT
The received file is empty.
HTTP4U_NOT_FOUND
Requested file has not been found
HTTP4U_OVERFLOW
The HTTP server overflows Http4u's buffers
HTTP4U_PROTOCOL_ERROR
Http4u can not process the given answer
HTTP4U_SUCCESS
Http4u has completed the task
HTTP4U_TCP_CONNECT
Http4u can not establish a connection with the remote host
HTTP4U_TCP_FAILED
Tcp4uInit has not been called or an undetermined network error has happened
HTTP4U_TIMEOUT
A timeout happen during a receive call

Exemple: 
HttpGetFileEx ("http://www.magic.fr/~jounin-ph",  /* URL to be retrieved */
               "my_fw.fr:8080/",   /* Use firewall my_fw.fr on port 8080 */
               NULL,                 /* do not save location into a File */
               NULL,                  /* do not save headers into a file */
              (HTTP4U_CALLBACK) DataAvailable, /* function in which the  */
                                               /* data are processed     */
               12345,                   /* to be tested in DataAvailable */
               szStatus, sizeof szStatus,/* on error display this string */
               szHeaders, sizeof szHeaders     /* save headers in memory */
              );
/* The HttpGetFile function */
return HttpGetFileEx (szURL, szProxyURL, szLocalFile,
                      NULL,           /* do not save headers into a file */
                      NULL,                               /* no callback */
                      0,                      /* and no associated value */
                      NULL, 0,                         /* no status code */
                      NULL, 0,                         /* and no headers */
                     );


Overview Multi purpose func. TCP functions Telnet related func HTTP functions UDP functions SMTP functions
Tcp4u version 3.31 by Ph. Jounin and Laurent Le Bras Last updated: 10th march 1998