awsp.h

SyncML手册及其编程

 *          responseBody            (conditional) If status includes response information,
 *                                                buffer has been updated to contain the
 *                                                response data (or error info).
 *          responseBodyLength      (conditional) Updated to contain the length of the
 *                                                response body, or 0 if no response
 *                                                is available for this status.
 *
 * 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 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_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.
 *
 *  Both the responseHeaders and responseBody buffers need to be valid and large enough
 *  to accomodate the data in order for any result data to be returned.  If either is
 *  missing or invalid, it should be assumed that this is a request for buffer size
 *  information.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_get_methodResult_ind(awsp_SessionHandle  sessionHandle,
                                    unsigned long       clientTransactionID,
                                    awsp_StatusCode_t  *status,
                                    char               *responseHeaders,
                                    size_t             *responseHeadersLength,
                                    void               *responseBody,
                                    size_t             *responseBodyLength);



/*
 * Method Result Response
 *    IN:   sessionHandle                  (required) A Handle for the session that this
 *                                                    transaction is executing in.
 *          clientTransactionID            (required) The transaction ID
 *          acknowledgementHeaders         (optional) Used to return info to the server.
 *          acknowledgementHeadersLength   (optional) Length of the acknowledgement
 *                                                    headers buffer.  Required if
 *                                                    buffer is not NULL.
 *
 * This method is invoked by the client to acknowledge that it has received the
 * server response to it's method invoke request.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_methodResult_rsp(awsp_SessionHandle sessionHandle,
                           unsigned long      clientTransactionID,
                           void              *acknowledgementHeaders,
                           size_t             acknowledgementHeadersLength);

/*
 * Method Abort Indicator (callback)
 *    IN:   sessionHandle           (required)     A Handle for the session that this
 *                                                 transaction is executing in.
 *          transactionID           (required)     A unique ID to identify this transaction.
 *          reasonCode              (required)     Reason for the abort
 *
 * This method is invoked by the WAP stack to notify the client that the
 * server has aborted the method invocation request.
 *
 * Again, it is unclear if/how the Palm and Wap stacks can handle callbacks.  This
 * is a placeholder for our need to be able to handle these notifications.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_methodAbort_ind(awsp_SessionHandle sessionHandle,
                          unsigned long      transactionID,
                          awsp_ReasonCode_t  reasonCode);


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

/*
 * Push Indicator (callback)
 *    IN:   sessionHandle           (required)     A Handle for the session that this
 *                                                 transaction is executing in.
 *          pushHeaders             (conditional)  HTTP 1.1 headers
 *          pushHeadersLength       (conditional)  The length of the push headers
 *                                                 buffer.  Required if push headers is
 *                                                 not NULL.
 *          pushBody                (conditional)  Pushed data.
 *          pushBodyLength          (conditional)  The length of the Push Body buffer.
 *                                                 Required if push body is not NULL.
 *
 * This method is invoked by the WAP stack to notify the client that the
 * server is pushing data to it.
 *
 * Again, it is unclear if/how the Palm and Wap stacks can handle callbacks.  This
 * is a placeholder for our need to be able to handle these notifications.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_push_ind(awsp_SessionHandle sessionHandle,
                   const char        *pushHeaders,
                   size_t             pushHeadersLength,
                   void              *pushBody,
                   size_t             pushBodyLength);


/*
 ******************************************************************************
 *
 * Confirmed Push Facility
 *       Sends unsolicited data from server to client across session
 *       (confirms client receipt of the data)
 *
 ******************************************************************************
 */

/*
 * Confirmed Push Indicator (callback)
 *    IN:   sessionHandle           (required)     A Handle for the session that this
 *                                                 transaction is executing in.
 *          clientPushID            (required)     Unique identifier for this push transaction
 *          pushHeaders             (conditional)  HTTP 1.1 headers
 *          pushHeadersLength       (conditional)  The length of the push headers
 *                                                 buffer.  Required if push headers is
 *                                                 not NULL.
 *          pushBody                (conditional)  Pushed data.
 *          pushBodyLength          (conditional)  The length of the Push Body buffer.
 *                                                 Required if push body is not NULL.
 *
 * This method is invoked by the WAP stack to notify the client that the
 * server is pushing data to it.
 *
 * Again, it is unclear if/how the Palm and Wap stacks can handle callbacks.  This
 * is a placeholder for our need to be able to handle these notifications.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_confirmedPush_ind(awsp_SessionHandle sessionHandle,
                            unsigned long      clientPushID,
                            const char        *pushHeaders,
                            size_t             pushHeadersLength,
                            void              *pushBody,
                            size_t             pushBodyLength);

/*
 * Confirmed Push Response
 *    IN:   sessionHandle           (required)        A Handle for the session that this
 *                                                    transaction is executing in.
 *          clientPushID            (required, equal) Unique Identified for this push transaction
 *          acknowledgementHeaders  (optional)        HTTP 1.1 headers to return data to server
 *          acknowledgementHeadersLength   (optional) Length of the Acknowledgement Headers
 *                                                    buffer.  Required if buffer is not NULL.
 *
 * This method is invoked by the client to acknowledge receipt of the pushed data from the
 * server.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_confirmedPush_rsp(awsp_SessionHandle sessionHandle,
                            unsigned long      clientPushID,
                            void              *acknowledgementHeaders,
                            size_t             acknowledgementHeadersLength);

/*
 ******************************************************************************
 *
 * Session Resume Facility
 *       Allows suspension and resumption of a session.  Can be used to
 *       switch to an alternate bearer network.
 *
 ******************************************************************************
 */

/*
 * Suspend Request
 *    IN:   sessionHandle           (required)  A Handle for the session that this
 *                                              transaction is executing in.
 *
 * RETURN:     awsp_Rc_t   indicates whether the suspend completed successfully.
 *
 * This method is invoked by the client to suspend the current session.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_suspend_req(awsp_SessionHandle sessionHandle);

/*
 * Suspend Indicator  (callback)
 *    IN:   sessionHandle           (required)  A Handle for the session that this
 *                                              transaction is executing in.
 *          reason                  (required)  The reason the session was suspended
 *
 * This method is invoked by the WAP stack to notify the client that the server
 * has requested that the session be suspended.
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_suspend_ind(awsp_SessionHandle sessionHandle,
                      awsp_ReasonCode_t  reason);

/*
 * Resume Request
 *    IN:   connHandle              (required)  A Handle for the initialized service
 *                                              Access Point - see initializeSAP().
 *          clientHeaders           (optional)  HTTP 1.1 Headers to use throughout session
 *          clientHeadersLength     (optional)  Length of Client Headers buffer.  Required
 *                                              if buffer is not NULL.
 *
 * RETURN:  awsp_Rc_t               an indication of whether the resume was successful.
 *
 * This method is invoked by the client to resume a suspended session.
 * This method must block until the server confirmation that the session has resumed.
 *
 *  Note to implementers:
 *  The confirmation information needs to remain available until the awsp_get_resume_cnf()
 *  method is invoked to retrieve it.
 *
 */
WSP_EXPORT awsp_Rc_t XPTAPI awsp_resume_req(awsp_ConnectionHandle connHandle,
                          const char           *clientHeaders,
                          size_t                clientHeadersLength);

/*
 * Get Resume Confirmation information.
 *
 *    IN:  connHandle              (required)    A Handle for the initialized service
 *                                               Access Point - see initializeSAP().
 *         sessionHandle           (required)    A pointer to receive the handle for
 *                                               the session that is being resumed.
 *         serverHeaders           (conditional) A buffer to receive the HTTP 1.1 static
 *                                               headers that the server wants to use
 *                                               for every request in the session.
 *                                               NULL to query the size the buffer needs
 *                                               to be
 *         serverHeadersLength     (conditional) A reference containing the length of the
 *                                               server headers buffer.
 *  OUT:   sessionHandle           (required)    A Handle for the session that is resumed.
 *         serverHeaders           (conditional) If buffer is sufficient for data, updated
 *                                               to contain the server headers.
 *         serverHeadersLength     (conditional) Updated to contain the length of the
 *                                               Server Headers data.
 *
 * 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