obex.h

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

#ifndef OBEX_H
#define OBEX_H

/*
 * Copyright Notice
 * Copyright (c) Ericsson, IBM, Lotus, Matsushita Communication 
 * Industrial Co., Ltd., Motorola, Nokia, Openwave Systems, Inc., 
 * Palm, Inc., Psion, Starfish Software, Symbian, Ltd. (2001).
 * All Rights Reserved.
 * Implementation of all or part of any Specification may require 
 * licenses under third party intellectual property rights, 
 * including without limitation, patent rights (such a third party 
 * may or may not be a Supporter). The Sponsors of the Specification 
 * are not responsible and shall not be held responsible in any 
 * manner for identifying or failing to identify any or all such 
 * third party intellectual property rights.
 * 
 * THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN ARE PROVIDED 
 * ON AN "AS IS" BASIS WITHOUT WARRANTY OF ANY KIND AND ERICSSON, IBM, 
 * LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO. LTD, MOTOROLA, 
 * NOKIA, PALM INC., PSION, STARFISH SOFTWARE AND ALL OTHER SYNCML 
 * SPONSORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 
 * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 
 * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT 
 * SHALL ERICSSON, IBM, LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO., 
 * LTD, MOTOROLA, NOKIA, PALM INC., PSION, STARFISH SOFTWARE OR ANY 
 * OTHER SYNCML SPONSOR BE LIABLE TO ANY PARTY FOR ANY LOSS OF 
 * PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF 
 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 
 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH 
 * THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED 
 * OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.
 * 
 * The above notice and this paragraph must be included on all copies 
 * of this document that are made.
 * 
 */

/*
**************************************************************************
**
** Defines public API's and constants for the Raw OBEX transport.
**
** See also:
**    obex/constants.h  : for command/response constants and public structures.
**    obex/errors.h     : for error codes.
**
**************************************************************************
*/
#include <obex/constants.h>
#include <obex/error.h>

/*
#ifdef _WIN32
 // luz %%%: seems to be needed
 #ifdef LINK_TRANSPORT_STATICALLY
  #define OBEX_EXPORT
 #else
  #ifdef EXPORT_OBEX_FUNCTIONS
   #define OBEX_EXPORT __declspec(dllexport)
  #else
   #define OBEX_EXPORT __declspec(dllimport)
  #endif
#else
 #define OBEX_EXPORT
#endif
*/
#define OBEX_EXPORT  /* we use .def files as dllim/export is a windows feature */

#ifdef __cplusplus
extern "C" {
#endif

/*
**************************************************************************
**
** Initialization.
**
**    This will take care of setting up any conversation independent aspects of Obex.
**************************************************************************
*/
OBEX_EXPORT void           ObxInit();

/*
**************************************************************************
**
** Handle manipulation.
**
** Routines in this group allow users to obtain and destroy an ObxHandle.
**
** ObxHandleNew():
**    Requests that a handle be returned.  Handles are used throughout the
**    various calls.
**
** ObxHandleFree():
**    Requests that the handle be cleaned up and disposed of.
**************************************************************************
*/
OBEX_EXPORT ObxHandle*     ObxHandleNew();
OBEX_EXPORT void           ObxHandleFree( ObxHandle *handle );

/*
**************************************************************************
**
** Obex Transport Interactions
**
** Routines in this group provide some direct interaction with the transport layer
** that was registered with the handle.  Although not confined to sockets, the transport
** API is based on sockets.  The expected behaviour is also based on the behaviour
** exhibited by sockets.  Implementers of custom transports should map the environment
** they are supporting to an API that satisfies the following.
**
** ObxTransportGet()
**    Returns a pre-defined transport.  See obex/constants.h for a list of available
**    transports.
**
** ObxTransportFree()
**    Disposes of a transport structure.
**
** ObxTransportRegister():
**    Define the transport structure to be used in operations on this handle.  This can be
**    a predefined transport that has been obtained via ObxTransportGet() or a custom transport
**    that conforms to the requirements specified in obxTransport.h.
**
** ObxTransportInitialize()
**    Calls through to the initialize() function call defined within the transport layer.
**    Use the passed meta data to initialize the transport associated with the passed
**    handle.  The format of the meta data will differ with each transport.
**
** ObxTransportOpen():
**    Calls through to the open() function call defined within the transport layer.
**    It's expected that general initialization tasks would be preformed in this call.
**    (Appropriate when acting as a client or server)
**
** ObxTransportClose():
**    Calls through to the close() function call defined within the transport layer.
**    It's expected that general termination tasks would be preformed in this call.
**    (Appropriate when acting as a client or server)
**
** ObxTransportListen()
**    Calls through to the listen() function call defined within the transport layer.
**    (Appropriate when acting as a server)
**
** ObxTransportAccept()
**    Calls through to the accept() function call defined within the transport layer.
**    It blocks, awaiting activity from a peer Obex.
**    (Appropriate when acting as a server)
**
** ObxTransportConnect()
**    Calls through to the connect() function call defined within the transport layer.
**    It initiates any connection activity with the remote peer.
**    (Appropriate when acting as a client)
**
** ObxTransportTerminate()
**    Calls through to the terminate() function call defined within the transport layer.
**    Allows the transport to clean up after itself.
**
**************************************************************************
*/
OBEX_EXPORT ObxTransport  *ObxTransportGet( short preDefinedTransportId );
OBEX_EXPORT void           ObxTransportFree( ObxTransport *transport );

OBEX_EXPORT ObxRc          ObxTransportRegister( ObxHandle *handle, ObxTransport *transport );

OBEX_EXPORT ObxRc          ObxTransportInitialize( ObxHandle *handle, const char *meta );

OBEX_EXPORT ObxRc          ObxTransportOpen( ObxHandle *handle );
OBEX_EXPORT ObxRc          ObxTransportClose( ObxHandle *handle );

OBEX_EXPORT ObxRc          ObxTransportListen( ObxHandle *handle );
OBEX_EXPORT ObxRc          ObxTransportAccept( ObxHandle *handle );

OBEX_EXPORT ObxRc          ObxTransportConnect( ObxHandle *handle );

OBEX_EXPORT ObxRc          ObxTransportTerminate( ObxHandle *handle );

/*
**************************************************************************
**
** Operations.
**
** Routines in this group allow for the flowing of requests to the peer and
** the handling of requests from the peer.
**
** ObxObjectSend():
**    Flows the passed object using the transport layer associated with the passed
**    handle to the peer.  The caller is responsible for ensuring that any responses
**    are handled (probably via a call to ObxObjectRecv()) that may be returning.
**    Note that this call can return OBX_RC_ERR_OBJ_FRAGMENTED_SEND which indicates
**    that only part of the object was sent.  The caller should call ObxObjectSend()
**    again after processing the response from the peer.
**
** ObxObjectRecv():
**    Wait for inbound request/response from the peer.  This could be a response
**    from a previously flowed response.. or something being initiated from a peer.
**    On success, the passed in ObxObject() is populated.
**
** ObxSendTransaction()
**    Warning: GET not supported at this time.  Attempts to send a GET will result in an
**             invalid return code, OBX_RC_ERR_INAPPROPRIATE.
**    Since a single 'transaction' may require numerous send/receives of objects,
**    this routine is designed to handle an entire transaction.
**    Takes care of flowing an entire, fully populated, request to the peer.  This
**    routine will not return until the entire transaction has taken place or an error
**    has occurred.
**    Contrast this with ObxObjectSend() which requires the caller to take care of
**    'continue responses' and other interactions with the peer that may have occurred.
**
**    -  The 'request' ObxObject is a request object, ready to flow to the peer.
**    -  The 'response' ObxObject is an object, provided by the caller, that will be populated
**       with the final response packet from the peer.  If not required, the caller can
**       pass a NULL pointer.  This will instruct the underlying infrastructure to not wait
**       for a response from the peer.  This is useful when flowing a DISCONNECT to the peer.
**    -  Errors will be returned via the ObxRc return.
**    -  The negotiated MTU returned on a CONNECT response is handled for the caller (it's
**       set into the handle for subsequent use).
**
** ObxRecvTransaction()
**    Warning: GET not supported at this time.  If an inbound transaction is found to be a GET,
**             this routine returns OBX_RC_ERR_NO_GET_SUPPORT and places the inbound request in
**             'request' but does no responses to the peer.  It's up to the application to deal
**             with this transaction with ObxObjectSend() and ObxObjectRecv().
**    Since a single 'transaction' may require numerous receive/replies of objects,
**    this routine is designed to handle an entire transaction.
**    Takes care of receiving an entire, fully populated, request from the peer.  This
**    routine will not return until the entire transaction has taken place or an error has
**    occurred.
**    Contrast this with ObxObjectRecv() which requires the caller to take care of creating
**    'continue responses' and other interactions with the peer that may have occurred.
**
**    -  The 'request' ObxObject is a request object, populated by interaction with the
**       peer.  It has been fully populated by the call.
**    -  Errors will be returned via the ObxRc return.
**
**    Setting coalesce to TRUE causes BODY/END_OF_BODY headers to be combined into a
**    single BODY header containing all information.  If this is false, all data will exist
**    within the returned object but there may be multiple BODY tags (and a single END_OF_BODY)
**    tag.  They will, of course, be in the order received from the peer.
**
**
**    The difference between ObxObjectSend()/ObxObjectRecv() and ObxSendTransaction()/
**    ObxRecvTransaction() can be represented with the following example:
**
**                    / ObxObjectSend() --- PUT (!final) ---> ObxObjectRecv() \
**                   /  ObxObjectRecv() <----- continue ----- ObxObjectSend()  \
**                  /   ObxObjectSend() --- PUT (!final) ---> ObxObjectRecv()   \
** ObxSendTransaction() ObxObjectRecv() <----- continue ----- ObxObjectSend() ObxRecvTransaction()
**                  \   ObxObjectSend() --- PUT (!final) ---> ObxObjectRecv()   /
**                   \  ObxObjectRecv() <----- continue ----- ObxObjectSend()  /
**                    \ ObxObjectSend() --- PUT (final)  ---> ObxObjectRecv() /
**                     \ObxObjectRecv() <----- success ------ ObxObjectSend()/
**
**
**************************************************************************
*/
OBEX_EXPORT ObxRc          ObxObjectSend( ObxHandle *handle, ObxObject *object );
OBEX_EXPORT ObxRc          ObxObjectRecv( ObxHandle *handle, ObxObject *object );

#ifndef RAW_API_ONLY
OBEX_EXPORT ObxRc ObxGetSend(ObxHandle *handle, ObxObject *getAnswer, char *mimeType);
OBEX_EXPORT ObxRc ObxGetRecv(ObxHandle *handle, ObxObject *request, ObxObject *responseOut );

OBEX_EXPORT ObxRc          ObxTransactionSend( ObxHandle *handle, ObxObject *request, ObxObject *response );
OBEX_EXPORT ObxRc          ObxTransactionRecv( ObxHandle *handle, ObxObject *request, short coalesce );
#endif

/*
**
** ObxStreamNew()
**    Returns a new stream object.
**    The ObxStream object, returned from this call, must be used on subsequent calls
**    involving the stream.
**
** ObxStreamingSend()
**    Warning: GET not supported at this time.  Attempts to send a GET will result in an
**             invalid return code, OBX_RC_ERR_INAPPROPRIATE.
**    Initiates a 'send' (i.e. PUT) to the remote peer.  The transaction is not
**    completed, thus allowing subsequent writes of data to be done.
**    Calls to ObxStreamSend() (after this call returns) can be used to send
**    additional data to the peer.  This data will be encoded in OBEX_HEADER_BODY
**    structures as it is sent.  Thus all headers, except BODY headers, must
**    be present in the initial, passed in, request object.  It is a requirement that
**    all non-body headers fit within a single MTU for this implementation.
**    This calls is only appropriate for OBEX_CMD_PUT requests that are initiated on
**    the local machine.  Other request types will result in an error return.
**       request  - A request containing initial headers to be sent to the peer.
**       stream   - A stream object that will be populated during the send.  Pass this token
**                  on all subsequent calls involving this transaction.
**
** ObxStreamingRecv()
**    Warning: GET not supported at this time.  If an inbound transaction is found to be a GET,
**             this routine returns OBX_RC_ERR_NO_GET_SUPPORT and places the inbound request in
**             'request' but does not respond to the peer.  It's up to the application to deal
**             with this transaction with ObxObjectSend() and ObxObjectRecv().
**    Waits for an inbound request from a peer.  When one comes in, all initial headers are
**    used to populate the passed 'request' object and the call returns.  Additional inbound
**    headers may be obtained via calls to ObxStreamRecv().
**    Returns
**       OBX_RC_OK         -  Success but more data is expected.  User should call ObxStreamRecv()
**                            to continue to accept data.
**       OBX_RC_STREAM_EOF -  Success, final bit from peer, no more data expected on stream.
**                            (i.e. it all fit within a single transmission).
**       OBX_RC_ERR_NO_GET_SUPPORT
**                         -  Inbound GET detected.
**
** ObxStreamSend()
**    Writes data into the stream.  Buffering may occur on the local side prior to actual sending
**    of data.
**
** ObxStreamRecv()
**    The passed list is appended with new, inbound headers, in the order received, from the peer.
**    Any existing data in the list is unmolested.  Note that this call can return after having