/*************************************************************************//* module:          Communication Services, HTTP functions               *//* file:            /src/xpt/all/xpt-http.h                              *//* target system:   all                                                  *//* target OS:       all                                                  *//*************************************************************************//* * Copyright Notice * Copyright (c) Ericsson, IBM, Lotus, Matsushita Communication  * Industrial Co., LTD,Motorola, Nokia, Palm, Inc., Psion,  * Starfish Software (2001). * All Rights Reserved. * Implementation of all or part of any Specification may require  * licenses under third party intellectual property rights,  * including without limitation, patent rights (such a third party  * may or may not be a Supporter). The Sponsors of the Specification  * are not responsible and shall not be held responsible in any  * manner for identifying or failing to identify any or all such  * third party intellectual property rights. *  * THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN ARE PROVIDED  * ON AN "AS IS" BASIS WITHOUT WARRANTY OF ANY KIND AND ERICSSON, IBM,  * LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO. LTD, MOTOROLA,  * NOKIA, PALM INC., PSION, STARFISH SOFTWARE AND ALL OTHER SYNCML  * SPONSORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING  * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION  * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF  * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT  * SHALL ERICSSON, IBM, LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO.,  * LTD, MOTOROLA, NOKIA, PALM INC., PSION, STARFISH SOFTWARE OR ANY  * OTHER SYNCML SPONSOR BE LIABLE TO ANY PARTY FOR ANY LOSS OF  * PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF  * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL,  * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH  * THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED  * OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. *  * The above notice and this paragraph must be included on all copies  * of this document that are made. *  *//** * HTTP protocol services, function prototypes and return codes * * */#ifndef XPT_HTTP_H#define XPT_HTTP_H/*********************//* Required includes *//*********************/#include "xpt.h"#include "xpttypes.h"#include "xpt-tcp.h"#ifdef _cplusplusextern "C" {#endif#define UNDEFINED_CONTENT_LENGTH  0x7FFFFFFFL/*****************************//* Types and Data structures *//*****************************/typedef void * HttpHandle_t;   // instance handle/********************************************************//* Authentication info, Basic and Digest authentication *//********************************************************/#include "xpt-auth.h"typedef struct                   // document context   {   BufferSize_t cbSize;          // size of this structure   CString_t pszURL;             // document name   CString_t pszType;            // document MIME type   CString_t pszHost;            // host name (optional)   BufferSize_t cbLength;        // document length   CString_t pszReferer;         // referenced URL (optional)   CString_t pszRequest;         // type of the HTTP request   CString_t pszFrom;            // sender of the document   CString_t pszProxy;           // Proxy IP address   XptHmacInfoPtr_t pXSyncmlHmac; // digest values for transport header field   // %%% luz:2002-05-23: Auth support added   HttpAuthenticationPtr_t auth;  // auth structure created by authInit()   } HttpDocumentContext_t, *HttpDocumentContextPtr_t;typedef struct                   // HTTP document reply   {   BufferSize_t cbSize;          // size of this structure   CString_t pszTime;            // creation date of the replied document   CString_t pszType;            // document MIME type   BufferSize_t cbLength;        // document length   HttpAuthenticationPtr_t auth; // authentication info   XptHmacInfoPtr_t pXSyncmlHmac; // digest values for transport header field   } HttpReplyBuffer_t, * HttpReplyBufferPtr_t;/**************************//* Function return values *//**************************/typedef enum   {   HTTP_RC_RETRY         = -3,  // authentication required: resend the document   HTTP_RC_HTTP          = -2,  // server error   HTTP_RC_EOF           = -1,  // end of transmission   HTTP_RC_OK            =  0,   HTTP_RC_COMMUNICATION =  1,  // communication problem, reported by TCP/IP   HTTP_RC_PARAMETER     =  2,  // one of the parameters was invalid   HTTP_RC_NOT_ALLOWED   =  3,  // this function call is not allowed in this context   // %%%luz:2003-04-17 added these extra codes   HTTP_RC_TIMEOUT       =  4,  // timeout   HTTP_RC_CERT_EXPIRED  =  5,  // https: certificate expired   HTTP_RC_CERT_INVALID  =  6   // https: certificate invalid   } HttpRc_t;/** * FUNCTION: httpOpen * *  Opens a HTTP connection * * PRE-Condition: * *  The function is invoked if a client or server decides to process a HTTP request. * *  The TCP/IP socket that is passed to the service must have been opened via *  tcpOpen(), and the socket must be in the right mode: If a "SERVER" request *  is selected, this must be a server socket, if a "SEND", "RECEIVE", or "EXCHANGE" *  request is selected, a client socket must be passed to the function. *  Although the HTTP services utilize this socket, the socket itself must *  be opened and closed by the caller. * * POST-Condition: *  HTTP Clients: The HTTP header is transmitted to the server. If a "SEND" or "EXCHANGE" *     request was selected, the document that is specified in the 'settings' *     parameter can be transmitted to the host, using httpWrite(). *     if a "RECEIVE" request was selected, no document is transmitted to the server. *     The application can directly call httpWait () to wait for the requested *     document. * *  HTTP Server: The client's request type (either "SEND", "EXCHANGE" or "RECEIVE" *     are expected) as well as the document properties that are sent from the *     client to the server ("EXCHANGE" and "SEND" requests) are returned in the *     document context structure that is referenced by the 'settings' parameter. *     If a pointer to an authentication information structure is passed to the *     function, the structure is updated with the client's authorization *     information (userID: passphrase). * * IN: p, instance handle *     pSession, potiner to an open TCP/IP socket. *     pszMode, HTTP request type. *              "SEND", "EXCHANGE", "RECEIVE" for HTTP clients *              "SERVER" for HTTP servers * IN/OUT: *      settings, pointer to a structure that denotes the properties of the document *                to be sent or being received. *      auth, authorization info, may ne NULL. * * RETURN: HttpRc_t, return code. Refer to the type definition above for details. *     If the return value is HTTP_RC_COMMUNICATION, further error information *     can be retrieved with the httpGetError() service; * */HttpRc_t httpOpen (HttpHandle_t p,                   SocketPtr_t pSession,                   CString_t pszMode,                   HttpDocumentContextPtr_t settings,                   HttpAuthenticationPtr_t auth);/** * FUNCTION: httpWrite * *  Write a chunk of data * * PRE-Condition: *  the HTTP communication has been opened via httpOpen(), and the protocol *  is in a state where incoming data is expected: *  HTTP clients: BEFORE httpWait() has been invoked *  HTTP Server:  AFTER httpReply () has been invoked * * POST-Condition: *  The data is transmitted to the communication partner. * * IN: p, instance handle *     pchDataBuffer, pointer to a block of allocated memory for the received data *     cbDataBufferSize, size of the memory block above *     bFinal, flag indicating if input buffer is the last block to send! * * OUT: pcbDataRead, pointer to a variable that is updated with the size of the *      received data block. * * RETURN: HttpRc_t, return code. Refer to the type definition above for details. *     If the return value is HTTP_RC_COMMUNICATION, further error information *     can be retrieved with the httpGetError() service; * */HttpRc_t httpWrite (HttpHandle_t p,                    DataBuffer_t pbBuffer,                    BufferSize_t cbBufferSize,                    Bool_t bFinal);/** * FUNCTION: httpClose * *  Close an open HTTP communication * * PRE-Condition: *  A HTTP communication has been opened via httpOpen(), and the data exchange *  has been done. * * POST-Condition: *  The HTTP instance handle is invalidated, and all secondary storage and *  system resources are freed. The TCP/IP socked remains open. * * IN: p, instance handle * * RETURN: HttpRc_t, return code. Refer to the type definition above for details. *     If the return value is HTTP_RC_COMMUNICATION, further error information