<HTML><HEAD>
<!-- This document was created with h2.pl -->
<TITLE>Tcp4u - HTTP related functions</TITLE></HEAD>
<BODY BACKGROUND="" BGCOLOR="#FFFFC0" TEXT="#000000">
<H1>
Tcp4u - HTTP related functions</H1>
<UL>
<LI><A HREF="#Mention1">Http4uErrorString</A>
<LI><A HREF="#Mention2">Http4uSetBufferSize</A>
<LI><A HREF="#Mention3">Http4uSetTimeout</A>
<LI><A HREF="#Mention4">HttpGetFile</A>
<LI><A HREF="#Mention5">HttpGetFileEx</A>
</UL>
<hr size=4>
<h1>
<A NAME="Mention1">Http4uErrorString</A></h1>
<p><br>
This function translates integer error codes into constants strings.</p>
<pre>
Syntax: const char *Http4uErrorString (int msg_code);
</pre>
<p><br>
<tt>Arguments:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">msg_code <BR></TD>
<TD colspan=1 align="left">An Http4u error code <BR></TD></TR></TABLE><p><br>
<tt>Return: </tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">LPCSTR <BR></TD>
<TD colspan=1 align="left">A long pointer on the error string associated with msg_code. <BR></TD></TR></TABLE>
<HR><H1>
<A NAME="Mention2">Http4uSetBufferSize</A></h1>
<p><br>
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.</p>
<pre>
Syntax: void Http4uSetBufferSize (unsigned uBufferSize);
</pre>
<p><br>
<tt>Arguments:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">uBufferSize <BR></TD>
<TD colspan=1 align="left">The new buffer size in bytes. This value can not be lower than 256 bytes <BR></TD></TR></TABLE>
<HR><H1>
<A NAME="Mention3">Http4uSetTimeout</A></h1>
<p><br>
This functions changes the internal timeout. The new value is given in seconds. By default, Http4u uses a 60 seconds timeout.<br>
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.</p>
<pre>
Syntax: Http4uSetTimeout (unsigned uTimeout);
</pre>
<p><br>
<tt>Arguments: </tt></p>
<TABLE><TR align="left">
<TD colspan=1 align="left">uTimeout <BR></TD>
<TD colspan=1 align="left">The new timeout in seconds. <BR></TD></TR></TABLE>
<HR><H1>
<A NAME="Mention4">HttpGetFile</A></h1>
<p><br>
This function retrieves a file using the HTTP protocol and copy it into a local file. It can be used through a firewall.<br>
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 <u>RFC1738</u>.<br>
Since HttpGetFile accepts only the HTTP protocol, the "http:" specifications in the URL can be shortened. Thus the URL has the following form:<br>
[http://]<i>host</i>[:<i>port</i>][/<i>directory</i>][<i>file</i>]<br>
The URL of the proxy server (firewall) should have the same format.<br>
Notes: <br>
<UL><LI>Since this function is fully reentrant, it can be safely called simultaneously from different threads or processes.<br>
<LI>This function enables itself to retrieve any file type. Thus it can download HTML files, images, sounds, executables or any other files.<br>
<LI>If the function fails to retrieve the specified file, the local file is removed unless a timeout error is returned.<br>
<LI>The application must have successfully called Tcp4uInit, before calling any Http4u functions.<br>
</UL> <pre>
Syntax: HttpGetFile (const char *szURL,
const char *szProxyURL,
const char *szFile);
</pre>
<pre>
</pre>
<p><tt>Arguments:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">szURL <BR></TD>
<TD colspan=1 align="left">The URL which specify the remote file to be retrieved <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szProxyURL <BR></TD>
<TD colspan=1 align="left">The URL of the proxy or NULL <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szLocalFile <BR></TD>
<TD colspan=1 align="left">The local file to be written <BR></TD></TR></TABLE><p><br>
<tt>Returns:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">HTTP4U_BAD_PARAM <BR></TD>
<TD colspan=1 align="left">szLocalFile is NULL <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_BAD_REQUEST <BR></TD>
<TD colspan=1 align="left">The HTTP rejects the request <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_BAD_URL <BR></TD>
<TD colspan=1 align="left">Http4u can not process one of the given URL <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_CANCELLED <BR></TD>
<TD colspan=1 align="left">A blocking call has been canceled by a TcpAbort call or by a user signal. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_FILE_ERROR <BR></TD>
<TD colspan=1 align="left">Http4u can not open the destination file or write into it <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_FORBIDDEN <BR></TD>
<TD colspan=1 align="left">User has no right access to this file <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_INSMEMORY <BR></TD>
<TD colspan=1 align="left">Http4u can not allocate its local buffers (since it does not much memory, this should not happen !) <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_MOVED <BR></TD>
<TD colspan=1 align="left">The HTTP server answers that the requested file is no more at this location <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_NO_CONTENT <BR></TD>
<TD colspan=1 align="left">The received file is empty. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_NOT_FOUND <BR></TD>
<TD colspan=1 align="left">Requested file has not been found <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_OVERFLOW <BR></TD>
<TD colspan=1 align="left">The HTTP server overflows Http4u's buffers <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_PROTOCOL_ERROR <BR></TD>
<TD colspan=1 align="left">Http4u can not process the given answer <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_SUCCESS <BR></TD>
<TD colspan=1 align="left">Http4u has completed the task <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_TCP_CONNECT <BR></TD>
<TD colspan=1 align="left">Http4u can not establish a connection with the remote host <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_TCP_FAILED <BR></TD>
<TD colspan=1 align="left">Tcp4uInit has not been called or an undetermined network error has happened <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_TIMEOUT <BR></TD>
<TD colspan=1 align="left">A timeout happen during a receive call <BR></TD></TR></TABLE>
<pre>
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 */
);
</pre>
<pre>
</pre>
<HR><H1>
<A NAME="Mention5">HttpGetFileEx</A></h1>
<p><br>
This function retrieves a file using the HTTP protocol and copy it into a local file.<br>
A proxy server can be specified in order to reach a site through a firewall.<br>
HTTP4U waits for a 3 parts response sent by the remote server (See <i><A HREF="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</A></i> for more information) :<br>
<UL><LI>Status Code and Reason Phrase<br>
<LI>Response Header Fields<br>
<LI>Entity (The file to be received).<br>
</UL>Http4u is able to return each part to the application as soon as available. The <i>Status Code</i> and <i>Response Header</i> fields are returned into buffers. The <i>Response Header</i> field can be written into a file.<br>
In order to return the <i>Entity</i> 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:<br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">long lBytesTransferred <BR></TD>
<TD colspan=1 align="left">The number of bytes received for the file (not including headers) <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">long lTotalBytes <BR></TD>
<TD colspan=1 align="left">The length of the file to be retrieved. If Http4u can not read it, a value of -1 is passed to the function <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">long lUserValue <BR></TD>
<TD colspan=1 align="left">This parameter is a copy of the lUserValue value passed to HttpGetFileEx. It can be filled with a thread id, a pointer... <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">const char *sBuf <BR></TD>
<TD colspan=1 align="left">A pointer on the data which have been read. These data must be saved by the application. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">Int nRvcd <BR></TD>
<TD colspan=1 align="left">The number of bytes which have been received. <BR></TD></TR></TABLE><p><br>
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.<br>
If this callback function returns FALSE, the transfer is stopped and the value HTTP4U_CANCELLED is returned to the application.<br>
Notes : <br>
<UL><LI>If the parameters szLocalFile and CbkTransmit are both set to NULL, HttpGetFileEx sends a HEAD request instead of the usual GET. Thus the <i>Entity</i> field is not sent by the server.<br>
<LI>The application must have successfully called Tcp4uInit, before calling any Http4u functions.<br>
<LI>Since this function is fully reentrant, it can be safely called simultaneously from different threads or processes.<br>
<LI>This function enables itself to retrieve any file type. Thus it can download HTML files, images, sounds, executables or any other files.<br>
<LI>The buffers szResponse and szHeaders can be safely read from the application once the callback function is called.<br>
</UL> <pre>
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);
</pre>
<pre>
</pre>
<p><tt>Arguments:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">szURL <BR></TD>
<TD colspan=1 align="left">The URL which specify the remote file to be retrieved <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szProxyURL <BR></TD>
<TD colspan=1 align="left">The URL of the proxy server or NULL <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szLocalFile <BR></TD>
<TD colspan=1 align="left">The local file to be written. If this parameter is NULL, the file is not retrieved. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">SzHeaderFile <BR></TD>
<TD colspan=1 align="left">The local file which will contain the header frame <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">CbkTransmit <BR></TD>
<TD colspan=1 align="left">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. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">lUserValue <BR></TD>
<TD colspan=1 align="left">A value which is passed to CbkTransmit. If CbkTransmit is NULL, this value is not used. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">SzResponse <BR></TD>
<TD colspan=1 align="left">A user's buffers which is to be filled with the field <i>Status Code and Reason Phrase</i>. If this value is NULL, the status frame is not returned to the user. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">nResponseSize <BR></TD>
<TD colspan=1 align="left">The size of the previous buffer <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szHeaders <BR></TD>
<TD colspan=1 align="left">A user's buffers which is to be written with the field <i>Response Header</i>. If this value is NULL, the header frame is not returned to the user. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">nHeaderSize <BR></TD>
<TD colspan=1 align="left">The size of the previous buffer <BR></TD></TR></TABLE><p><br>
<tt>Returns:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">HTTP4U_BAD_PARAM <BR></TD>
<TD colspan=1 align="left">An error in the parameters has been detected <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_BAD_REQUEST <BR></TD>
<TD colspan=1 align="left">The HTTP rejects the request <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_BAD_URL <BR></TD>
<TD colspan=1 align="left">Http4u can not process the given URL <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_CANCELLED <BR></TD>
<TD colspan=1 align="left">A blocking call has been canceled by a TcpAbort call or by a user signal. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_FILE_ERROR <BR></TD>
<TD colspan=1 align="left">Http4u can not open the destination file or write into it <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_FORBIDDEN <BR></TD>
<TD colspan=1 align="left">User has no right access to this file <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_INSMEMORY <BR></TD>
<TD colspan=1 align="left">Http4u can not allocate its local buffers (since it does not much memory, this should not happen !) <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_MOVED <BR></TD>
<TD colspan=1 align="left">The HTTP server answers that the requested file is no more at this location <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_NO_CONTENT <BR></TD>
<TD colspan=1 align="left">The received file is empty. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_NOT_FOUND <BR></TD>
<TD colspan=1 align="left">Requested file has not been found <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_OVERFLOW <BR></TD>
<TD colspan=1 align="left">The HTTP server overflows Http4u's buffers <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_PROTOCOL_ERROR <BR></TD>
<TD colspan=1 align="left">Http4u can not process the given answer <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_SUCCESS <BR></TD>
<TD colspan=1 align="left">Http4u has completed the task <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_TCP_CONNECT <BR></TD>
<TD colspan=1 align="left">Http4u can not establish a connection with the remote host <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_TCP_FAILED <BR></TD>
<TD colspan=1 align="left">Tcp4uInit has not been called or an undetermined network error has happened <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">HTTP4U_TIMEOUT <BR></TD>
<TD colspan=1 align="left">A timeout happen during a receive call <BR></TD></TR></TABLE>
<pre>
</pre>
<pre>
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 */
);
</pre>
<pre>
</pre>
</body></html>
<hr size=4>
<table border=1 CELLPADDING=7 align=center><tr>
<td><A HREF="tcp4u.htm">Overview</A></td>
<td><A HREF="tcp4u_p1.htm">Multi purpose func.</A></td>
<td><A HREF="tcp4u_p2.htm">TCP functions</A></td>
<td><A HREF="tcp4u_p3.htm">Telnet related func</A></td>
<td><A HREF="tcp4u_p4.htm">HTTP functions</A></td>
<td><A HREF="tcp4u_p5.htm">UDP functions</A></td>
<td><A HREF="tcp4u_p6.htm">SMTP functions</A></td>
</tr></table>
<font italic size=2>
<table border=0><tr>
<td align=left>Tcp4u version 3.31 by Ph. Jounin and Laurent Le Bras</td>
<td align=right>Last updated: 10th march 1998</td>
<tr>
</table>
</font>
syntax highlighted by Code2HTML, v. 0.9.1