awsp.h

SyncML手册及其编程

 *                                  results.
 *
 *  This method is invoked to retrieve the information that was returned on the resume
 *  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_resume_req().
 *
 *  Note to implementers:
 *  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_resume_cnf(awsp_ConnectionHandle connHandle,
                              awsp_SessionHandle    sessionHandle,
                              char                 *serverHeaders,
                              size_t               *serverHeadersLength);


/*****************************************************************************/
/*****************************************************************************/
/**                                                                         **/
/**                         WSP ConnectionLess Functions                    **/
/**                                                                         **/
/*****************************************************************************/
/*****************************************************************************/


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

/*
 * Method Invoke Request
 *    IN:   connHandle              (required)     A Handle for the initialized service
 *                                                 Access Point - see initializeSAP().
 *          transactionID           (required)     A unique ID to identify this transaction.
 *          method                  (required)     The HTTP method for the request.
 *          requestURI              (required)
 *          requestHeaders          (optional)     If method type includes data, this
 *                                                 is the request header for the data.
 *          requestHeadersLength    (conditional)  The length of the request headers
 *                                                 buffer.  Required if the buffer is not NULL.
 *          requestBody             (conditional)  If method type includes data, this
 *                                                 is the data for the method.
 *          requestBodyLength       (conditional)  Length of Request Body buffer.
 *                                                 Required if buffer is not NULL.
 *
 * This method must block until the server methodResult indicator comes back.
 *
 *  Note to implementers:
 *  The indicator information needs to remain available until the
 *  awsp_get_unit_methodResult_ind() method is invoked to retrieve it.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_unit_methodInvoke_req(awsp_ConnectionHandle connHandle,
                                unsigned long         transactionID,
                                const char           *method,
                                const char           *requestURI,
                                const char           *requestHeaders,
                                size_t                requestHeadersLength,
                                void                 *requestBody,
                                size_t                requestBodyLength);

/*
 * Method Result Indicator
 *    IN:   connHandle              (required)     A Handle for the initialized service
 *                                                 Access Point - see initializeSAP().
 *          transactionID           (required)     A unique ID to identify this transaction.
 *          status                  (required)     An integer reference to receive the
 *                                                 HTTP status of the request
 *          responseHeaders         (conditional)  A buffer to receive the HTTP response
 *                                                 headers, or NULL to query how large
 *                                                 the buffer needs to be.
 *          responseHeadersLength   (conditional)  A reference containing the length of
 *                                                 the response headers buffer.
 *          responseBody            (conditional)  A buffer to receive the HTTP response
 *                                                 body, or NULL to query how large the
 *                                                 buffer needs to be.
 *          responseBodyLength      (conditional)  A reference containing the length of
 *                                                 the response body buffer.
 *   OUT:   status                  (required)     Updated to contain the HTTP response status
 *          responseHeaders         (conditional)  If buffer is large enough to hold response
 *                                                 header, buffer is updated to contain
 *                                                 response header
 *          responseHeadersLength   (conditional)  Length of response header
 *          responseBody            (conditional)  If buffer is large enough to hold response
 *                                                 body, buffer is updated to contain response
 *                                                 body.
 *          responseBodyLength      (conditional)  Length of response body
 *
 * RETURN:  awsp_Rc_t               A return code indicating whether the indication
 *                                  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 unit
 *  method response indication. 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_unit_methodInvoke_req().
 *
 *  Note to implementers:
 *  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_unit_methodResult_ind(awsp_ConnectionHandle connHandle,
                                         unsigned long         transactionID,
                                         awsp_StatusCode_t    *status,
                                         char                 *responseHeaders,
                                         size_t               *responseHeadersLength,
                                         void                 *responseBody,
                                         size_t               *responseBodyLength);



/*
 ******************************************************************************
 *
 * Push Facility
 *       Sends unsolicited data from server to client across session
 *       (no confirmation of data arrival)
 *
 ******************************************************************************
 */

/*
 * Push Indicator    (callback)
 *    IN:   connHandle              (required)    A Handle for the initialized service
 *                                                Access Point - see initializeSAP().
 *          pushID                  (required)    A unique identifier to identify he push
 *          pushHeaders             (conditional) Buffer containing the HTTP push headers
 *          pushHeadersLength       (conditional) Length of push headers buffer
 *          pushBody                (conditional) Buffer containing the push body
 *          pushBodyLength          (conditional) Length of push body buffer.
 *
 * This method is invoked by the WAP stack to notify the client that the server is
 * pushing data to it.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_unit_push_ind(awsp_ConnectionHandle connHandle,
                        unsigned long         pushID,
                        const char           *pushHeaders,
                        size_t                pushHeadersLength,
                        void                 *pushBody,
                        size_t                pushBodyLength);


/*****************************************************************************/
/*****************************************************************************/
/**                                                                         **/
/**      Management Entity Functions for Service Access Point               **/
/**                                                                         **/
/*****************************************************************************/
/*****************************************************************************/

/*
 * Initialize the service access point for use.
 *    IN:
 *          connectionHandle        (required) A reference to a connection handle
 *                                             pointer to receive the connection
 *                                             handle
 *    OUT:
 *          connectionHandle        (required) Updated to contain a pointer to the
 *                                             connection handle for this service
 *                                             access point.
 *
 * RETURN:  awsp_Rc_t               A return code indicating whether the service
 *                                  access point has been successfully initialized.
 *
 *  This method is used to initialize the Service Access Point and prepare it for
 *  establishing a WSP session.  No input parameters are specified, which means the WAP
 *  stack should connect to the default server at the default port, using the
 *  default bearer.  It is assumed that the current client can be determined by the
 *  method, and the default client port should be used.
 */

WSP_EXPORT awsp_Rc_t XPTAPI initializeSAPd(awsp_ConnectionHandle *connectionHandle);

/*
 * Initialize the service access point for use.
 *    IN:
 *          connectionHandle        (required) A reference to a connection handle
 *                                             pointer to receive the connection
 *                                             handle
 *          bearerType              (required) Use DEFAULT type for default bearer
 *          addressType             (required) Use DEFAULT type for default bearer
 *          serverAddress           (optional) Uses addressing scheme of layer
 *                                  below it.  May be MSISDN, X.25, ip address,
 *                                  or other.
 *             MSISDN number = 3 digit country code +
 *                             2 digit national destination code +
 *                    (up to) 10 digit subscriber number
 *             X.25 X.121 #  = 3 digit country code +   \ this is the DNIC and
 *                             1 digit PSN +            / is optional
 *                    (up to) 10 digit NTN
 *             ip address
 *
 *          serverPort              (optional)
 *          clientAddress           (optional)
 *          clientPort              (optional)
 *    OUT:
 *          connectionHandle        (required) Updated to contain a pointer to the
 *                                             connection handle for this service
 *                                             access point.
 *
 * RETURN:  awsp_Rc_t               A return code indicating whether the service
 *                                  access point has been successfully initialized.
 *
 *  This method is used to initialize the Service Access Point and prepare it for
 *  establishing a WSP session.  It allows input parameters to be specified, for the
 *  case where the client application needs to specify access point information.
 */

WSP_EXPORT awsp_Rc_t XPTAPI initializeSAP(awsp_ConnectionHandle *connectionHandle,
                        awsp_BEARER_TYPE       bearerType,
                        awsp_ADDRESS_TYPE      addressType,
                        const char            *serverAddress,
                        unsigned short         serverPort,
                        const char            *clientAddress,
                        unsigned short         clientPort);

/*
 * Close the service access point after usage.
 *    IN:
 *          connectionHandle        (required)
 */
WSP_EXPORT awsp_Rc_t XPTAPI closeSAP(awsp_ConnectionHandle connectionHandle);


#ifdef __cplusplus
}
#endif

#endif