awsp.h

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

 *          sessionHandle           (required)  A pointer to receive the handle that
 *                                              represents the session created by this
 *                                              connection.
 *          clientHttpHeaders       (optional)  Static HTTP client headers that will
 *                                              apply to every client transaction
 *                                              during the session.  NULL if no static
 *                                              headers are defined for this session.
 *                                              Header should be in standard HTTP header
 *                                              format (i.e. tags are separated by CRLF,
 *                                              header ends with CRLF CRLF).
 *          clientHttpHeadersLength (optional)  Length of the clientHttpHeaders buffer.
 *                                              Required if clientHttpHeaders is not NULL.
 *          requestedCapabilities   (optional)  Capabilites Negotiation object containing
 *                                              capabilities requested for the session.
 *                                              NULL if no extended capabilities are needed.
 *  OUT:    sessionHandle                       A pointer to the handle that
 *                                              represents the session created by this
 *                                              connection.
 *
 * RETURN:  awsp_Rc_t               A return code indicating whether the connection
 *                                  was successful (i.e. is the session established or not).
 *
 * This method must block until the connect confirmation comes back from the server.
 *
 * Note to implementers:
 * The connect confirmation information needs to remain available until the
 * awsp_get_connect_cnf() method is invoked to retrieve it.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_connect_req(awsp_ConnectionHandle connHandle,
                           awsp_SessionHandle   *sessionHandle,
                           const char           *clientHttpHeaders,
                           const size_t          clientHttpHeadersLength,
                           awsp_Capabilities    *requestedCapabilities);

/*
 * Get Connect Confirmation Information
 *    IN:   sessionHandle                       The handle that represents the
 *                                              session.
 *          serverHttpHeaders                   A buffer to receive whatever static HTTP
 *                                              server headers that were returned with the
 *                                              connect confirmation.
 *                                              A NULL value should cause the method to return
 *                                              an 'insufficient buffer size' error, and
 *                                              serverHttpHeadersLength will have been updated
 *                                              to contain the required buffer size.
 *          serverHttpHeadersLength             Reference to a size_t variable that contains
 *                                              the length of the serverHttpHeaders buffer.
 *          negotiatedCapabilities              The address of a pointer to a Capabilities object.
 *                                              Required only when connect request included
 *                                              capabilities request.
 *
 *   OUT:   serverHttpHeaders                   The static HTTP server headers that will apply
 *                                              to every server transaction during the
 *                                              session.  NULL if no static headers were
 *                                              returned on the confirmation. Header should be
 *                                              in standard HTTP header format (i.e. tags are
 *                                              separated by CRLF, header ends with CRLF CRLF).
 *          serverHttpHeadersLength             Reference to a size_t variable that contains
 *                                              the length of the data returned in
 *                                              the serverHttpHeaders buffer.
 *          negotiatedCapabilities              The address has been updated to contain a
 *                                              pointer to the negotiated capabilities
 *                                              object containing what the server has
 *                                              agreed to for the session.
 *
 * RETURN:  awsp_Rc_t               A return code indicating whether the confirmation
 *                                  information has been returned in the passed parameters.
 *                                  Returns a 'buffer too small' response if the provided
 *                                  buffers are NULL, or are too small to receive the
 *                                  results.
 *
 *  This method is invoked to retrieve the information that was returned on the connect
 *  confirmation.  It is a non-blocking call - either the information is available
 *  or it is not.  This method should be invoked following successful return from
 *  awsp_connect_req().
 *  If the initial invocation of the method results in a 'buffer too small' error, the
 *  method should be able to be invoked again for the same transaction with the correct
 *  buffer sizes to retrieve the information.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_get_connect_cnf(awsp_SessionHandle    sessionHandle,
                               const char           *serverHttpHeaders,
                               size_t               *serverHttpHeadersLength,
                               awsp_Capabilities **negotiatedCapabilities);


/*
 * Disconnect Request
 *    IN:   sessionHandle           (required)        A Handle for the session that this
 *                                                    connection represents.
 *          reasonCode              (required)        Cause of the disconnection -
 *                                                    either a reason code or a status code
 *          redirectSecurity        (conditional)     Indicates if existing secure session
 *                                                    can be reused for redirection to new
 *                                                    server.
 *                                                    TRUE  = secure session can be reused.
 *                                                    FALSE = secure session cannot be reused,
 *                                                            new secure session must be
 *                                                            established with new server.
 *          redirectAddresses       (conditional)     Alternate address(es) to redirect
 *                                                    the request to
 *          errorHeaders            (optional)        HTTP 1.1 headers for the error
 *                                                    body information.  Optional, use only
 *                                                    if an Error Body will be provided to
 *                                                    expand upon the reason for the
 *                                                    disconnect.
 *          errorHeadersLength      (optional)        Length of Error Headers buffer.
 *                                                    Required if Error Headers is not NULL.
 *          errorBody               (optional)        Info to expand on reason code.
 *                                                    Required if Error Headers is not NULL
 *          errorBodyLength         (optional)        Length of Error Body buffer.
 *                                                    Required if Error Body is not NULL.
 *
 * RETURN:  awsp_Rc_t               A return code indicating whether the disconnect has
 *                                  been successfully sent to the server.
 *
 *  The client uses this method to request that the session be terminated..
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_disconnect_req(awsp_SessionHandle sessionHandle,
                              int                reasonCode,
                              awsp_BOOL          redirectSecurity,
                              const char        *redirectAddresses[],
                              const char        *errorHeaders,
                              size_t             errorHeadersLength,
                              void              *errorBody,
                              size_t             errorBodyLength);

/*
 * Disconnect Indicator in response to Request (callback)
 *    IN:   connHandle              (required)        A Handle for the initialized service
 *                                                    Access Point - see initializeSAP().
 *          reasonCode              (required)        Cause of the disconnection -
 *                                                    either a reason code or a status code
 *          redirectSecurity        (conditional)     Indicates if existing secure session
 *                                                    can be reused for redirection to new
 *                                                    server.
 *                                                    TRUE  = secure session can be reused.
 *                                                    FALSE = secure session cannot be reused,
 *                                                            new secure session must be
 *                                                            established with new server.
 *          redirectAddresses       (conditional)     Alternate address(es) to redirect
 *                                                    the request to
 *          errorHeaders            (optional)        HTTP 1.1 headers for the error
 *                                                    body information.
 *          errorHeadersLength      (optional)        Length of Error Headers buffer.
 *                                                    Required if Error Headers is not NULL.
 *          errorBody               (optional)        Info to expand on reason code.
 *                                                    Required if Error Headers is not NULL
 *          errorBodyLength         (optional)        Length of Error Body buffer.
 *                                                    Required if Error Body is not NULL.
 *
 *
 * This method would be invoked by the WAP stack to notify us, the client, that the server
 * has requested that our session be disconnected.
 *
 * It is here as a callback as a place-holder, since we need to be able to receive the
 * notification.  However, if callbacks are not feasible from the WAP implementations, or
 * on the Palm (single-threaded platform), then an alternative technique will be required.
 *
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_disconnect_ind(awsp_ConnectionHandle connHandle,
                         int                   reasonCode,
                         awsp_BOOL             redirectSecurity,
                         const char           *redirectAddresses[],
                         const char           *errorHeaders,
                         size_t                errorHeadersLength,
                         void                 *errorBody,
                         size_t                errorBodyLength);

/*
 ******************************************************************************
 *
 * Method Invocation Facility
 *       HTTP Methods and user-defined request/response model operations
 *
 ******************************************************************************
 */

/*
 * Method Invoke Request
 *    IN:   sessionHandle           (required)     A Handle for the session that this
 *                                                 transaction is executing in.
 *          clientTransactionID     (required)     Unique ID to distinguish between pending transactions
 *          method                  (required)     HTTP method or one of negotiated extended methods
 *          requestURI              (required)     The entity to which the operation applies -
 *          requestHeaders          (optional)     HTTP 1.1 headers
 *          requestHeadersLength    (optional)     Length of Request Headers buffer.  Required
 *                                                 if Request Headers is not NULL.
 *          requestBody             (conditional)  If Method transmits data, this contains
 *                                                 the data to be transmitted (i.e. for
 *                                                 PUT/POST, this is the SyncML message).
 *                                                 If method does not transmit data (i.e. GET)
 *                                                 then this should be NULL.
 *          requestBodyLength       (conditional)  Length of the Request Body buffer.  Required
 *                                                 if Request Body is not NULL.
 *
 *  This method must block until the server responds with the method result indication.
 *
 *  Note to implementers:
 *  The result information needs to remain available until the awsp_get_methodResult_ind()
 *  method is invoked to retrieve it.
 *
 *  Note:  The WAP specification allows new requests to be made before responses to existing
 *         requests are returned, and the responses are not required to come back in the
 *         same order as the requests were sent.  Based on this, it seems incorrect to make
 *         this API block and wait for the response.  This synchronous technique was chosen
 *         because of the Palm threading model, which we believe may be incapable of
 *         handling the multiple asynchronous request model.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_methodInvoke_req(awsp_SessionHandle sessionHandle,
                           unsigned long      clientTransactionID,
                           const char        *method,
                           const char        *requestURI,
                           const char        *requestHeaders,
                           size_t             requestHeadersLength,
                           void              *requestBody,
                           size_t             requestBodyLength);

/*
 * Get Method Result Indicator Information
 *    IN:   sessionHandle           (required)    A Handle for the session that this
 *                                                transaction is executing in.
 *          clientTransactionID     (required)    Unique ID to distinguish between pending transactions
 *          status                  (required)    A reference to an int field to receive the
 *                                                HTTP 1.1 status code
 *          responseHeaders         (conditional) A buffer to receive the HTTP 1.1 header, or
 *                                                NULL to query the buffer size needed to
 *                                                receive the header.
 *          responseHeadersLength   (conditional) Reference to a size_t variable that contains
 *                                                the length of the Response Headers buffer.
 *          responseBody            (conditional) A buffer to receive the Response data, or
 *                                                NULL to query the buffer size needed to
 *                                                receive the body.
 *          responseBodyLength      (conditional) Reference to a size_t variable that contains
 *                                                the length of the Reponse Body buffer.
 *   OUT:   status                  (required)    HTTP 1.1 status code
 *          responseHeaders         (conditional) If status includes response information,
 *                                                buffer has been updated to contain the
 *                                                HTTP 1.1 response header
 *          responseHeadersLength   (conditional) Updated to contain the length of the
 *                                                response header, or 0 if no response
 *                                                is available for this status.