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.
|
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
|
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.
|
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:
*Since this function is fully reentrant, it can be safely called
simultaneously from different threads or processes.
*This function enables itself to retrieve any file type. Thus it can download
HTML files, images, sounds, executables or any other files.
*If the function fails to retrieve the specified file, the local file is
removed unless a timeout error is returned.
*The application must have successfully called Tcp4uInit, before calling any
Http4u functions.
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 */ );
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) :
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 :
*If the parameters szLocalFile and CbkTransmit are both set to NULL,
HttpGetFileEx sends a HEAD request instead of the usual GET. Thus the
Entity field is not sent by the server.
*The application must have successfully called Tcp4uInit, before calling any
Http4u functions.
*Since this function is fully reentrant, it can be safely called
simultaneously from different threads or processes.
*This function enables itself to retrieve any file type. Thus it can download
HTML files, images, sounds, executables or any other files.
*The buffers szResponse and szHeaders can be safely read from the application
once the callback function is called.
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 */ );