HTTPClientOpenRequest
The HTTPClientOpenRequest function initializes a new HTTP request.

HTTP_SESSION_HANDLE HTTPClientOpenRequest(
    HTTP_CLIENT_SESSION_FLAGS Flags
);

Returned values
Upon success the function returns a valid pointer to the HTTP session structure. Otherwise a null pointer is returned.

Remarks
Any other request to the HTTP API should pass the pointer that was received from this call. When the operation is over a call to HTTPClientReleaseRequest() should be made in order to free the allocated pointer.

This call may fail if there are no available connections.

Example Code
The following example demonstrates the use of the HTTPClientOpenRequest function.

#include <HTTPClient.h>
int main(int argc, char *argv[]) 
{
    HTTP_SESSION_HANDLE pHTTP = 0;
	pHTTP = HTTPClientOpenRequest(0);
          if(!pHTTP)
	{	
		Return -1;
	}
	// ..
}

HTTPClientCloseRequest
The HTTPClientCloseRequest function releases an HTTP session that was created previously by calling to HTTPClientOpenRequest and free any allocated memory that this session may have used.

UINT32 HTTPClientCloseRequest(
  P_HTTP_REQUEST pRequest 
);

Parameters
pRequest

    [in] a pointer to the HTTP session.

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.

Remarks
The authentication schema that was set using this function must much one of the authentication methods offered by the web server. If this is not the case and for example the caller stated Basic authentication to be used while the server did not require any authentication, the API will later fail the request with the appropriate error.

Example Code
The following example demonstrates the use of the HTTPClientSetAuth function.

#include <HTTPClient.h>
int main(int argc, char *argv[]) 
{
    HTTP_SESSION_HANDLE pHTTP = 0;
    pHTTP = HTTPClientOpenRequest(0);
    if(!pHTTP)
    {	
        Return -1;
    }
    HTTPClientCloseRequest(pHTTP);
    Return 0;
}

HTTPClientSetAuth
The HTTPClientSetAuth function sets the authentication method to be used with the newly created HTTP session. The authentication method could be Digest or Basic (future versions may support more methods).

UINT32 HTTPClientSetAuth (
    HTTP_SESSION_HANDLE pSession,
    HTTP_AUTH_SCHEMA AuthSchema, 
    void *pReserved)
);

Parameters
pSession

   [in] a pointer to the HTTP session.

HTTP_AUTH_SCHEMA

   [in] the required authentication schema.

*pReserved

   [in] for future use, must be NULL.

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.
HTTP_CLIENT_ERROR_BAD_AUTH	Authentication schema is not supported.

Remarks
When an application is done with the HTTP API it should call HTTPClientCloseRequest() in order to free the allocated pointer and be ready for any other new HTTP request.

Example Code
The following example demonstrates the use of the HTTPClientCloseRequest function.

#include <HTTPClient.h>
int main(int argc, char *argv[]) 
{
    HTTP_SESSION_HANDLE pHTTP = 0;
    INT32               nRetCode;
    
    pHTTP = HTTPClientOpenRequest(0);
    if(!pHTTP)
    {	
        Return -1;
    }
    nRetCode = HTTPClientSetAuth(pHTTP, AuthSchemaBasic,NULL);
    // …
}

HTTPClientSetCredentials
The HTTPClientSetCredentials function sets the credentials to be used when the web resource is protected and one of the supported authentication schemas was set.

UINT32 HTTPClientSetCredentials (
    HTTP_SESSION_HANDLE pSession,
    CHAR *pUserName,
    CHAR *pPassword
);

Parameters
pSession

   [in] a pointer to the HTTP session.

pUserName

   [in] a null terminated string containing the user name.

pPassword

   [in] a null terminating string containing the password.

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.
HTTP_CLIENT_ERROR_LONG_INPUT	A function received a parameter that was too large.

Remarks
Only when an authentication schema is stated the API flow will actually attempt to use the supplied credentials.

Example Code
The following example demonstrates the use of the HTTPClientCloseRequest function.

HTTPClientSetProxy
Sets Proxy server host and credentials to be used for ongoing HTTP session.

UINT32 HTTPClientSetAuth (
    HTTP_SESSION_HANDLE pSession,
    CHAR *pProxyHost
    UINT16 nPort,   
    CHAR *pUserName,
    CHAR *pPassword
);

Parameters
pSession

   [in] a pointer to the HTTP session.

pProxyHost

   [in] the host name of the proxy server.

nPort

   [in] TCP port number of the proxy server (usuaaly 8080)

pUserName

   [in] a null terminated string containing the user name (for proxy authentication).

pPassword

   [in] a null terminating string containing the password (for proxy authentication).

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.

Example Code
The following example demonstrates the use of the HTTPClientSetProxy function.

#include <HTTPClient.h>
int main(int argc, char *argv[]) 
{
    // ..
    nRetCode = HTTPClientSetProxy(pHTTP,’www.proxy.com’,8080,NULL,NULL) ;                
    // …
}

HTTPClientSetVerb
Sets the desired HTTP verb for the operation.

UINT32 HTTPClientSetVerb (
    HTTP_SESSION_HANDLE pSession,
    HTTP_VERB HttpVerb
);

Parameters
pSession

   [in] a pointer to the HTTP session.

HttpVerb

   [in] the requested verb (VerbGet, VerbPos, VerbHead)

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.
HTTP_CLIENT_ERROR_BAD_VERB	Bad or not supported HTTP verb was passed to a function

Remarks
As of version 1.0 this API supports only Get, Post and Head verbs.

HTTPClientAddRequestHeaders
Add custom headers to the outgoing HTTP request.

UINT32 HTTPClientAddRequestHeaders (
    HTTP_SESSION_HANDLE pSession,
    CHAR *pHeaderName,
    CHAR *pHeaderData,
    BOOL nInsert
);

Parameters
pSession

   [in] a pointer to the HTTP session.

pHeaderName

   [in] a null terminated string containing the headers name.

pHeaderData

   [in] a null terminated string containing the headers content.

bInsert

   [in] reserved, could be any.

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.
HTTP_CLIENT_ERROR_NO_MEMORY	Buffer too small or a failure while in memory allocation

Remarks
The agnt-name header is being automatically inserted. This header is defind in HTTPClient.h (HTTP_CLIENT_DEFAULT_AGENT)

HTTPClientSendRequest
Sends an HTTP request to the remote server.

UINT32 HTTPClientSendRequest (
    HTTP_SESSION_HANDLE pSession,
    CHAR    *pUrl,
    VOID    *pData,
    UINT32  nDataLength,
    BOOL    TotalLength,
    UINT32  nTimeout,
    UINT32  nClientPort
);

Parameters
pSession

   [in] a pointer to the HTTP session.

pUrl

   [in] a null terminated string containing remote url

pData

   [in] a pointer to a buffer containing the data to be sent.
    This parameter could be null when no data is sent to the remote server (such as the case with Get operations)

nDataLength

   [in] the length of pData in bytes. Shoud be 0 when pData is null.

nTimeout

   [in] Timeout in seconds for the operation.

nClientPort

   [in] If client side binding is required this parameter sould be non 0 and set to contain the client (source) TCP port.

Returned values
Upon success the function should return an HTTP_CLIENT_SUCCESS value. Otherwise one of the following errors should be returned:

Error code	Meaning
HTTP_CLIENT_ERROR_INVALID_HANDLE	An invalid handle was passed to the function.

For other errors being returned from this call refer to HTTPClientCommon.h file.