xpt-http.h

SyncML ToolKits,学习syncml的参考工具包.非常好用.

/*************************************************************************/
/* 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 _cplusplus
extern "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