xpt-http.h

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

 *     can be retrieved with the httpGetError() service;
 *
 *
 */

HttpRc_t httpClose (HttpHandle_t p);

/**
 * FUNCTION: httpRead
 *
 *  Read 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: AFTER httpWait() has been invoked
 *  HTTP Server: BEFORE httpReply () has been invoked
 *
 *
 * POST-Condition:
 *  A part of the receiving document is copied to the specified data buffer.
 *  The size of the received data buffer is returned in the variable that
 *  is referenced with the pointer 'pcbDataRead'.
 *
 * IN: p, instance handle
 *     pchDataBuffer, pointer to a block of allocated memory for the received data
 *     cbDataBufferSize, size of the memory block above
 *
 * 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 httpRead  (HttpHandle_t p,
                    DataBuffer_t pbDataBuffer,
                    BufferSize_t cbDataBufferSize,
                    BufferSizePtr_t pcbDataRead);

/**
 * FUNCTION: httpWait
 *
 *  Wait for the HTTP server response
 *
 * PRE-Condition:
 *  The HTTP instance has been opened in a client mode. A HTTP request has been
 *  selected that expects a response document from the server.
 *  This is in case of "RECEIVE" requests, immediately after httpOpen() has
 *  been invoked, or in case of "EXCHANGE" requests, after the posted document
 *  has been entirely transmitted to the server using the httpWrite() service. The application
 *  nust invoke the httpWait() function to wait for the response document.
 *
 * POST-Condition:
 *  When the function returns, the server started sending the response document.
 *  The document context (i.e. document length, creation date, MIME type) is returned
 *  to the caller in the pSettings parameter.
 *
 * IN: p, instance handle
 *     pSettings, response document properties.
 *
 * OUT: pSettings, response document properties.
 *      pAuth, pointer to an allocated authentication info structure, or NULL, if
 *             the caller does not want to examine the server's authentication
 *             data.
 *
 * 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 httpWait  (HttpHandle_t p,
                    HttpDocumentContextPtr_t pSettings,
                    HttpAuthenticationPtr_t pAuth);

/**
 * FUNCTION: httpReply
 *
 *  Reply to a client HTTP request
 *
 * PRE-Condition:
 *  The HTTP instance has been opened in the server mode. A HTTP request has been
 *  initiated by the client. The service httpReply() is invoked after the client
 *  HTTP request has been completely received. Dependend on the type of request,
 *  This service issues the transmission of the HTTP response header.
 *
 * POST-Condition:
 *  Dependent on the type of HTTP request, the client expects a response document.
 *  If this is the case, the application can now start sending the document with
 *  the httpWrite() service.
 *
 * IN: p, instance handle
 *     rcDocument, HTTP return code of the request (i.e. 200 for OK)
 *     pSettings, response document properties. Dependent on the type of request,
 *                the structure elements can be filled:
 *                pszTime - creation date of the response document
 *                          ("RECEIVE", "EXCHANGE" requests, optional)
 *                pszType - MIME type of the response document
 *                          ("RECEIVE", "EXCHANGE" request, optional)
 *                cbLength - Length of the response document
 *                           (must be 0 for "SEND" requests, otherwise optional)
 *                rcDocument - HTTP return code of the request (i.e. 200 for OK)
 *     pAuth, pointer to a structure that contains authentication info (optional)
 *            The authentication structure contains the following elements:
 *            cbSize - size of dataauth structure.
 *            pbData, pointer to an allocated block of data that contains the
 *                    authentication data to be sent to the client.
 *            fType, authentication type, must be 0.
 *            cbDataLength, size of the data block above.
 *
 * 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 httpReply (HttpHandle_t p,
                    int rcDocument,
                    const HttpReplyBufferPtr_t pSettings,
                    const HttpAuthenticationPtr_t pAuth);

/**
 * FUNCTION: httpGetError
 *
 *  Return the return code of the last error, that a TCP/IP protocol service returned.
 *
 * PRE-Condition:
 *  The previous HTTP protocol service function failed with the return value
 *  HTTP_RC_COMMUNICATION. The caller invokes this function to retrieve
 *  the return code TCP/IP service that failed.
 *
 * POST-Condition:
 *  -
 *
 *
 * IN: p, instance handle
 *
 * RETURN: TcpRc_t, Return code of the failing TCP/IP service
 *
 *
 */

TcpRc_t  httpGetError (HttpHandle_t p);

/**
 * FUNCTION: httpGetServerStatus
 *
 *  Return the HTTP return code in the HTTP response header.
 *
 * PRE-Condition:
 *  The previous HTTP protocol service function failed with the return value
 *  HTTP_RC_SERVER. The caller invokes this function to retrieve
 *  the HTTP return code. (i.e. rc=404 means "resource not found")
 *
 * POST-Condition:
 *  -
 *
 *
 * IN: p, instance handle
 *
 * RETURN: int Return code of the failing HTTP request
 *
 *
 */

int  httpGetServerStatus (HttpHandle_t p);

/**
 * FUNCTION: httpGetBufferSize
 *
 *  Return the number of Bytes that is required for the instance object
 *
 * PRE-Condition:
 *  -
 *
 * POST-Condition:
 *  The function returns the size of the data buffer that the caller must
 *  allocate for the object instance memory, that is required to call httpOpen().
 *
 * IN: -
 *
 * RETURN: required size of the HTTP instance handle in Bytes.
 *
 *
 */

BufferSize_t httpGetBufferSize (void);


/**
 * FUNCTION: httpIsEox
 *
 *  Check wether the HTTP document has been received completely.
 *
 * PRE-Condition:
 *  the HTTP communication has been opened via httpOpen(), and the protocol
 *  is in a state where incoming data is expected:
 *  HTTP clients: AFTER httpWait() has been invoked
 *  HTTP Server: BEFORE httpReply () has been invoked
 *
 *
 * POST-Condition:
 *  The caller uses the function to get the exit conditions for a while loop
 *  that receives an incoming HTTP document, for example:
 *    while (!httpIsEox (http_handle))  {
 *        httpRead (...);
 *
 *        // do something interesting
 *        }
 *
 * IN: p, instance handle
 *
 * RETURN: true, if the document has been read entirely. false if
 * further receive packets are expected.
 *
 */

Bool_t httpIsEox (HttpHandle_t p);


#ifdef _cplusplus
}
#endif

#endif