xpttransport.h

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

/*****************************************************************************/
/* module:         SyncML Communication Protocol Transport Binding header    */
/* file:           src/xpt/inc/xptTransport.h                                */
/* target system:  all                                                       */
/* target OS:      all                                                       */
/*****************************************************************************/


/*
 * 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.
 * 
 */


/**
 * This include file contains the API specifications for pluggable transport
 * bindings for the SyncML Communication Services.
 */

#ifndef XPTTRANSPORT_H
#define XPTTRANSPORT_H

#include <xptdef.h>
#include <xpt.h>
#include <smldef.h>


#define XPT_ID SML_ERR_A_XPT_ERROR  // Starting trace message number

#ifndef TRACE_TO_STDOUT
 #include <libutil.h>               // For smlLibPrint() prototype
#endif

/*---------------------------------------------------------------------*/
/* 1.st exclude everything */
// %%% luz 2002-04-16: moved defines and undefs to below

/* And now lets define what we really whant. */
/* Currently only Windows (32-Bit) and Linux 
 * allow for dynamic loading. 
 * Dynamicbinding requires a file 'dynamicTransports' beeing
 * present which lists all DLL's to load (without the DLL suffix).
 * Empty lines or lines starting with a hash mark '#' are ignored.
 * Insert one transport dll per line only.
 */
// %%% luz 2002-04-16: added checking LINK_TRANSPORT_STATICALLY to allow for
//     statically linked transports even on Win/Linux
#if (defined (WIN32) || defined(linux)) && !defined(LINK_TRANSPORT_STATICALLY)
    #define INCLUDE_TRANSPORTS_DYNAMICALLY
    // %%% luz 2002-04-16: moved undefs here to allow INCLUDE_xxx predefs outside
    //     this file
    #undef INCLUDE_HTTP_STATICALLY
    #undef INCLUDE_OBEX_STATICALLY
    #undef INCLUDE_WSP_STATICALLY
#else
    #undef INCLUDE_TRANSPORTS_DYNAMICALLY
    // %%% luz 2002-04-16: disabled static defines, must be predefined
    /*    
    #define INCLUDE_HTTP_STATICALLY
    #define INCLUDE_OBEX_STATICALLY
    #define INCLUDE_WSP_STATICALLY
    */
#endif

#ifdef __cplusplus
extern "C" {
#endif

struct xptTransportDescription {
   const char *shortName;        // Short name of protocol.  E.g., "HTTP" or "OBEX/IR"
   const char *description;      // Summary of protocol, suitable for display
                                 // E.g., "OBEX over infrared"
   unsigned int flags;           // Flags.  Any of XPT_CLIENT and/or XPT_SERVER
   void *privateTransportInfo;   // Field of use to the transport binding.
      // The only use the xpt service makes of this field is to pass it on
      // subsequent calls to functions of the transport binding to identify the
      // transport binding.  It is expected that the transport binding will set
      // this field to the address of a structure containing internal transport
      // binding information.


   // Each of the following function pointers are functions that must be
   // implemented by the transport binding.  In general, they correspond to
   // public function definitions in xpt.h.  The transport-specific function
   // is called by the xpt service when the public xpt function is called by
   // the application.  Since the public functions are described in xpt.h, the
   // arguments which are simply passed through from those calls are not
   // described again here.

   /**
    * FUNCTION: Called when xptSelectProtocol() is called, selecting this
    *           transport binding.
    *
    *  Select the communication protocol to start the communication
    *
    * IN: privateTransportInfo, pointer to the transport binding's private
    *         information about the transport, the value given in the
    *         privateTransportInfo field of the xptTransportDescription struct
    *         when the transport binding was registered.
    *
    *     metaInformation, passed directly from the xptSelectProtocol() call.
    *         Beware that a null pointer may have been specified to indicate
    *         that no meta information was provided.
    *
    *     flags, passed directly from the xptSelectProtocol() call.
    *
    * OUT: *pPrivateServiceInfo, pointer to the transport binding's private
    *         information for the newly allocated service instance.  This
    *         pointer will be passed on subsequent calls to the transport's
    *         functions to identify this service instance to the transport.
    */
   Ret_t (XPTAPI *selectProtocol)(void *privateTransportInfo,
                                  const char *metaInformation,
                                  unsigned int flags,
                                  void **pPrivateServiceInfo);


   /**
    * FUNCTION: Called when xptDeselectProtocol() is called, deselecting this
    *           transport binding.
    *
    *  Stop a communication service instance.
    *
    * IN: privateServiceInfo, pointer to the transport binding's private
    *         information about the service instance.  This is the same value
    *         that was returned by the "selectProtocol" function when the
    *         service instance was created.
    */
   Ret_t (XPTAPI *deselectProtocol)(void *privateServiceInfo);


   /**
    * FUNCTION: Called when xptOpenCommunication() is called, creating a
    *           connection instance.
    *
    *  Create a connection instance for the given service id.
    *
    * IN: privateServiceInfo, pointer to the transport binding's private
    *         information about the service instance.  This is the same value
    *         that was returned by the "selectProtocol" function when the
    *         service instance was created.
    *
    *     role, passed directly from the xptOpenCommunication() call.
    *
    * OUT: *pPrivateConnectionInfo, pointer to the transport binding's private
    *         information for the newly allocated connection instance.  This
    *         pointer will be passed on subsequent calls to the transport's
    *         functions to identify this connection instance to the transport.
    */
   Ret_t (XPTAPI *openCommunication)(void *privateServiceInfo,
                                     int role,
                                     void **pPrivateConnectionInfo);

   /**
    * FUNCTION: Called when xptCloseCommunication() is called, closing a
    *           connection instance.
    *
    *  Close a connection instance.
    *
    * IN: privateConnectionInfo, pointer to the transport binding's private
    *         information about the connection instance.  This is the same
    *         value that was returned by the "openCommunication" function when
    *         the connection instance was created.
    */
   Ret_t (XPTAPI *closeCommunication)(void *privateConnectionInfo);


   /**
    * FUNCTION: Called when xptBeginExchange() is called
    *
    *  Prepare for a document exchange.
    *
    * IN: privateConnectionInfo, pointer to the transport binding's private
    *         information about the connection instance.  This is the same
    *         value that was returned by the "openCommunication" function when
    *         the connection instance was created.
    */
   Ret_t (XPTAPI *beginExchange)(void *privateConnectionInfo);


   /**
    * FUNCTION: Called when xptEndExchange() is called
    *
    *  Clean up after a document exchange.
    *
    * IN: privateConnectionInfo, pointer to the transport binding's private
    *         information about the connection instance.  This is the same
    *         value that was returned by the "openCommunication" function when
    *         the connection instance was created.
    */
   Ret_t (XPTAPI *endExchange)(void *privateConnectionInfo);

   /**
    * FUNCTION: Called when xptReceiveData() is called
    *
    *  Read data
    *
    * IN: privateConnectionInfo, pointer to the transport binding's private
    *         information about the connection instance.  This is the same
    *         value that was returned by the "openCommunication" function when
    *         the connection instance was created.
    *
    *     buffer, passed directly from the xptReceiveData() call.
    *
    *     bufferLen, passed directly from the xptReceiveData() call.
    *
    * OUT:
    *     dataLen, passed directly from the xptReceiveData() call.
    *
    * NOTES:
    *
    *  If the transport provided a document length in the earlier call to
    *  xptGetDocumentInfo(), then the xpt interface layer will ensure that the
    *  application does not attempt to read more bytes than are available in
    *  the document.  A transport implementation that always returns the length
    *  does not, therefore, need to return any sort of "end of transmission"
    *  indication.
    *
    *  On the other hand, if the transport didn't provide a length in the
    *  earlier call to xptGetDocumentInfo(), then the xpt interface layer will
    *  simply pass the xptReceiveData() calls through to the transport, and the
    *  transport is responsible for indicating end-of-document by returning a
    *  dataLen of zero.  The xpt interface layer will ensure no subsequent
    *  calls to the receiveData function are made after the end of the document
    *  is reached.
    */
   Ret_t (XPTAPI *receiveData)(void *privateConnectionInfo,
                               void *buffer, size_t bufferLen,
                               size_t *dataLen);

   /**
    * FUNCTION: Called when xptSendData() is called
    *
    *  Send data
    *
    * IN: privateConnectionInfo, pointer to the transport binding's private
    *         information about the connection instance.  This is the same
    *         value that was returned by the "openCommunication" function when
    *         the connection instance was created.
    *
    *     buffer, passed directly from the xptSendData() call.
    *
    *     bufferLen, passed directly from the xptSendData() call.
    *
    *     bytesSent, passed directly from the xptSendData() call.
    *
    * NOTES:
    *
    *  If the application provided the document length in its earlier call to
    *  xptSetDocumentInfo(), the xpt interface layer will ensure that the
    *  application does not attempt to write more bytes than it said were in
    *  the document.  In this case, therefore, the transport implementation
    *  does not need to check for that overflow condition.
    *
    *  If the application did not provide the document length in its earlier
    *  call to xptSetDocumentInfo(), the xpt interface layer will simply pass
    *  through xptSendData() calls, and the transport is responsible for