xpt.h

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

/**
 * FUNCTION: xptOpenCommunication
 *  Establishes a communication using the protocol service with the given id.
 *
 * PRE-Condition:
 *  A protocol service id has been obtained by calling xptSelectProtocol().
 *
 * POST-Condition:
 *   The communication role can be specified as either REQUEST_SENDER or
 *   REQUEST_RECEIVER.  A request sender is expected subsequently to send a
 *   request, then receive a response.  A request receiver is expected to
 *   receive a request, then send a response.  See the prologue comments for
 *   more information on the expected sequence of calls.
 *
 * IN:     id, Protocol Service ID
 *         role, Communication mode.  One of:
 *               XPT_REQUEST_SENDER    - indicates that the caller will send a
 *                                       document, and then receive one.
 *               XPT_REQUEST_RECEIVER  - indicates that the caller will receive
 *                                       a document, and then send one.
 *
 * IN/OUT:
 *
 * OUT:    pConn, pointer to a connection instance handle
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptOpenCommunication(XptServiceID_t id,
                                              int role,
                                              XptCommunicationIDPtr_t pConn) XPT_SECTION;

/**
 * FUNCTION: xptCloseCommunication
 *  Closes a previously opened communication
 *
 * PRE-Condition:
 *  An open connection exists, the transmission of the data has been either completed,
 *  or it is desired to cancel the (incomplete) transmission
 *
 * POST-Condition:
 *  The connection instance is closed.  It cannot be used any more.
 *
 * IN:     conn, connection instance handle
 *
 * OUT:
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptCloseCommunication(XptCommunicationID_t conn) XPT_SECTION;


/**
 * FUNCTION: xptBeginExchange
 *  Prepares to begin a new exchange of documents.
 *
 * PRE-Condition:
 *  An active connection exists.
 *
 * POST-Condition:
 *  If the connection was opened with the XPT_REQUEST_SENDER flag, then this
 *  call allows the transport binding implementation to prepare for a sending a
 *  document and then receiving one.  If the connection was opened with the
 *  XPT_REQUEST_RECEIVER flag, then this call allows the transport binding
 *  implementation to prepare for receiving a document and then sending one.
 *
 * IN:     conn, connection instance handle
 *
 * OUT:
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */
XPTDECLEXP1 Ret_t XPTAPI xptBeginExchange(XptCommunicationID_t conn) XPT_SECTION;


/**
 * FUNCTION: xptEndExchange
 *  Completes an exchange of documents.
 *
 * PRE-Condition:
 *  An active connection exists
 *
 * POST-Condition:
 *  This call allows the transport binding implementation to clean up after a
 *  document exchange.
 *
 * IN:     conn, connection instance handle
 *
 * OUT:
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */
XPTDECLEXP1 Ret_t XPTAPI xptEndExchange(XptCommunicationID_t conn) XPT_SECTION;


/**
 * FUNCTION: xptReceiveData
 *  Read data across a connection
 *
 * PRE-Condition:
 *  The connection has been opened with a call of xptOpenCommunication
 *
 * POST-Condition:
 *  This call blocks until at least one byte of data is available, or until no
 *  more bytes will become available.  It returns when one or more bytes are
 *  read, or when the end of the document is reached.  It may return before
 *  bufferLen bytes are read.  If the earlier call to xptGetDocumentInfo()
 *  returned a document length, the caller can either read just that many
 *  bytes or read until the end of the document is reached.
 *
 * IN:     connection, connection instance handle.
 *         buffer,     pointer to a buffer to hold the data.
 *         bufferLen,  size of the data buffer, in bytes.
 *         dataLen,    pointer to a field that on return will contain the
 *                     length of the received data.
 *
 * OUT:    *dataLen, set to the length of the received data.  If the length is
 *         zero, the end of the document has been reached.
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptReceiveData(XptCommunicationID_t connection,
                                        void *buffer, size_t bufferLen,
                                        size_t *dataLen) XPT_SECTION;


/**
 * FUNCTION: xptSendData
 *  Send data across a connection
 *
 * PRE-Condition:
 *  The connection has been opened with a call of xptOpenCommunication
 *
 * POST-Condition:
 *  This call blocks until at least one byte of data is sent.
 *  It returns when one or more bytes are sent,
 *  but it may return before bufferLen bytes are sent.  If the caller
 *  previously provided a document length in the call to xptSetDocumentInfo(),
 *  then it must not attempt to write more than that many bytes.  Doing so will
 *  result in an error.  After calling xptSendData() one or more times to send
 *  the document body, the application must call xptSendComplete() to indicate
 *  that sending is finished.
 *
 * IN:     connection, connection instance handle.
 *         buffer, pointer to the data to be sent.
 *         bufferLen, size of the data block to be transmitted, in bytes.
 *
 * IN/OUT:
 *         *bytesSent, set to the actual number of bytes sent
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptSendData(XptCommunicationID_t connection,
                                     const void *buffer, size_t bufferLen,
                                     size_t *bytesSent) XPT_SECTION;


/**
 * FUNCTION: xptSendComplete
 *  Indicate that sending of a document is complete.
 *
 * PRE-Condition:
 *  The document body was sent using one or more calls to xptSendData().
 *
 * POST-Condition:
 *  This call is used to indicate that the complete document body has been
 *  written.  If the application previously supplied a document length in
 *  its call to xptSetDocumentInfo(), then the number of bytes written before
 *  calling xptSendComplete() must match that length.  Otherwise an error will
 *  be returned from xptSendComplete().
 *
 * IN:     connection, connection instance handle.
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptSendComplete(XptCommunicationID_t connection) XPT_SECTION;



/**
 * FUNCTION: xptSetDocumentInfo
 *  Provide document information for an outgoing document.
 *
 * PRE-Condition:
 *  The connection has been opened with a call of xptOpenCommunication
 *
 *
 * POST-Condition:
 *  The transport protocol uses the provided document information in a
 *  protocol-dependent way.  Generally, it is used to set document name and
 *  length headers.  The caller is expected to subsequently call xptSendData()
 *  to send the document body.
 *
 *  All fields of the XptCommunicationInfo_t structure must be filled in.  If
 *  the caller doesn't know the document length in advance, it is permitted to
 *  set the cbLength field to (size_t) -1 to indicate that the document length
 *  is unknown.
 *
 *
 * IN:     conn, connection instance handle
 *         pDoc, Pointer to a structure that contains some information about the
 *               data to be transmitted.
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptSetDocumentInfo(XptCommunicationID_t conn,
                                            const XptCommunicationInfo_t *pDoc) XPT_SECTION;

/**
 * FUNCTION: xptGetDocumentInfo
 *  Retrieve the document information associated with an incoming document.
 *
 * PRE-Condition:
 *  The connection has been opened with a call of xptOpenCommunication
 *
 *
 * POST-Condition:
 *  The transport protocol provides the document information for the incoming
 *  request.  The caller is expected to subsequently call xptReceiveData()
 *  to receive the document body.
 *
 *  All fields of the XptCommunicationInfo_t structure will be filled in.  If
 *  the transport doesn't know the document length at this time, it will
 *  set the cbLength field to (size_t) -1 to indicate that the document length
 *  is unknown.  In that case, the application must allocate storage
 *  dynamically and make xptReceiveData() calls until an end-of-document
 *  indication is returned.
 *
 * IN:     conn, connection instance handle
 *         pDoc, Pointer to a structure that is filled in with information
 *               about the data being transmitted.
 *
 * IN/OUT:
 *
 * RETURN: Ret_t, Return code. Refer to the return code list above for details.
 *
 */

XPTDECLEXP1 Ret_t XPTAPI xptGetDocumentInfo(XptCommunicationID_t conn,
                                            XptCommunicationInfo_t *pDoc) XPT_SECTION;

/**
 * FUNCTION: xptGetLastError
 *  Get information about the last error
 *
 * PRE-Condition:
 *  A call to some other xpt function failed.  If the platform is a
 *  multithreaded platform, the earlier call must have taken place on the same
 *  thread making the call to xptGetLastError().  The application calls this
 *  function to get information about the cause of the error, including an
 *  error message that might be useful to display.
 *
 *  If the platform is multithreaded, error information is maintained
 *  separately for each thread.
 *
 * POST-Condition:
 *  Information about the last communication error is returned in a structure.
 *  The caller should treat this structure as read-only storage, and not attempt
 *  the free it.  The storage will be maintained by xptGetLastError().
 *
 * IN:
 *
 * IN/OUT:
 *
 * RETURN: A structure that describes the last error encountered.
 *         For multithreaded platforms, it describes the last error encountered
 *         on this thread.
 */
XPTDECLEXP1 const XptErrorInformation_t * XPTAPI xptGetLastError(void) XPT_SECTION;

/* For EPOC OS */
#ifdef __EPOC_OS__

XPTDECLEXP1 int xptOpenTLS();

XPTDECLEXP1 void xptCloseTLS();

#endif

#ifdef __cplusplus
}
#endif

#endif