protocol.c

SyncML手册及其编程

/*
 * 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.
 * 
 */
/*
 * Version Label
 *
 * RELEASE ??? CANDIDATE ?
 * 13.06.2000
 */

#include <protocol.h>
#include <wsphttp.h>

#include <xptport.h>

/**
 * Eyecatcher to validate WspProtocolHandle_t structure
 **/
#define WSP_PROTOCOL_HANDLE_VALID_FLAG 0x50535741L    // 'AWSP'

/*****************************************************************************/
/*****************************************************************************/
/**                                                                         **/
/**                         Private Implementation Methods                  **/
/**                                                                         **/
/*****************************************************************************/
/*****************************************************************************/


Ret_t protocolCreateSession(WspProtocolHandle_t *pid) {

   Ret_t rc = SML_ERR_OK;

   XPTDEBUG(("protocolCreateSession(%lx)\n", (unsigned long) pid));

   if (pid == NULL)
      return SML_ERR_A_XPT_INVALID_PARM;

   /**
    *    Connection-mode (session or connectionless) must be specified in szSettings?
    *    If connection-mode:
    */
   if ((pid->protocolSettings != NULL) &&
       (pid->protocolSettings->createSession == AWSP_TRUE))

      rc = sessionCreate(pid->connHandle,
                         pid->protocolSettings->requestedCapabilities,
                         httpGetStaticRequestHdrs(pid->protocolSettings->httpParms),
                         &(pid->session));

   /*
    * If the RC from sessionCreate is invalid_parm then we should convert it
    * to something else, since the parm to protocolCreateSession was ok
    */
   if (rc == SML_ERR_A_XPT_INVALID_PARM)
      rc = SML_ERR_A_XPT_COMMUNICATION;

   return rc;
}  /* End of protocolCreateSession() */

/**
 *  protocolTerminateSession
 *       - disconnects the active session and releases its associated storage
 *
 *  IN:    pid             A pointer to a protocol handle structure
 *
 **/
Ret_t protocolTerminateSession(WspProtocolHandle_t *pid) {

   Ret_t rc = SML_ERR_OK;

   XPTDEBUG(("protocolTerminateSession(%lx)\n", (unsigned long) pid));

   if (pid == NULL)
      return SML_ERR_A_XPT_INVALID_PARM;

   /**
    * The syncml spec doesn't indicate that we are supporting methodAbort
    * requests from the client...
    *
    * Wait for a response to the pending transaction(s)
    * If (method(s) pending) && (!methodResult_ind(s) received)
    *    Invoke s_methodAbort_req
    *    Parameters:
    *       Transaction ID    - (from Method Request)
    *
    **/
   rc = sessionDisconnect(pid->session);

   if (rc != SML_ERR_OK) {
      /*
       * Since the disconnect cleans up the session regardless of the rc (i.e.
       * end result if no session), maybe we should just return OK
       */
   }

   pid->session = NULL;

   return rc;
} /* End of protocolTerminateSession() */

/**
 *  protocolSuspendSession
 *       - suspends the active session, if it exists, and indicates it has
 *         been suspended.
 *
 *  IN:    pid             A pointer to a protocol handle structure
 *
 *  RETURN:
 *       An indication of whether or not the suspension was successful.
 *
 **/
Ret_t protocolSuspendSession(WspProtocolHandle_t *pid) {

   Ret_t rc = SML_ERR_OK;

   XPTDEBUG(("protocolSuspendSession(%lx)\n", (unsigned long) pid));

   if (pid == NULL)
      return SML_ERR_A_XPT_INVALID_PARM;
   /**
    * Wait for a response to the pending transaction(s)
    * If (method pending) && (!methodResult_ind received)
    *    Invoke s_methodAbort_req
    *    Parameters:
    *       Transaction ID    - (from Method Request)
    * Else
    *    <do nothing - no further transaction stuff pending>
    **/

   rc = sessionSuspend(pid->session);

   if (rc == SML_ERR_A_XPT_INVALID_PARM)
      rc = SML_ERR_A_XPT_COMMUNICATION;

   return rc;
}  /* End of protocolSuspendSession() */

Ret_t protocolResumeSession(WspProtocolHandle_t *pid)
{
   Ret_t rc = SML_ERR_OK;

   XPTDEBUG(("protocolResumeSession(%lx)\n", (unsigned long) pid));

   if (pid == NULL)
      return SML_ERR_A_XPT_INVALID_PARM;

   if (pid->session->sessionSuspended == AWSP_FALSE) {
      /**
       * Return 'session already active'?  Or 'OK', since goal was to
       * have a session and we've got one?
       **/
   } else
      rc = sessionResume(pid->connHandle, pid->session);

   return rc;
}   /* End of protocolResumeSession() */

awsp_BOOL protocolIsHandleValid(WspProtocolHandle_t *handle) {

   XPTDEBUG(("protocolIsHandleValid(%lx)\n", (unsigned long) handle));

   if (handle == NULL)
      return AWSP_FALSE;

   if (handle->valid != WSP_PROTOCOL_HANDLE_VALID_FLAG)
      return AWSP_FALSE;

   return AWSP_TRUE;
}

/**
 *  protocolInitializeHandle
 *       - Allocates storage for protocol handle
 *       - Parses input settings and allocates the protocolSettings in the
 *         protocol handle structure.
 *
 *  IN:    szSettings      A string containing WSP settings parameters
 *         mode            An indication of whether this protocol instance
 *                         is operating as a client or a server.
 *
 *  OUT:   protocolHandle  Contains a handle to the WSP Protocol structure,
 *                         Unaltered if error occurs.
 *
 *  RETURN:
 *       A return code indicating whether the WSP protocol handle was
 *       successfully initialized.
 **/
Ret_t protocolInitializeHandle(const char *szSettings,
                               unsigned int mode,
                               void **protocolHandle) {

   Ret_t rc = SML_ERR_OK;
   WspProtocolHandle_t *pid = NULL;

   XPTDEBUG(("protocolInitializeHandle(%s, %u, %lx)\n", szSettings,
             mode, (unsigned long) protocolHandle));

   if (protocolHandle == NULL)
      return SML_ERR_A_XPT_INVALID_PARM;

   pid = (void *) xppMalloc(sizeof(WspProtocolHandle_t));

   if (pid == NULL)
      return SML_ERR_A_XPT_MEMORY;

   xppMemset(pid, 0, sizeof(WspProtocolHandle_t));
   pid->valid = WSP_PROTOCOL_HANDLE_VALID_FLAG;
   pid->mode  = mode;

   rc = settingsInitialize(szSettings, (&(pid->protocolSettings)));

   if (rc == SML_ERR_OK)
      *protocolHandle = (void *) pid;
   else
      xppFree(pid);

   return rc;
} /* End of protocolInitializeHandle() */

/**
 *  protocolReleaseHandle
 *       - releases all storage associate with the protocol - the settings,
 *         the session, the connection, and the protocol structure itself.
 *       - closes the connection if required.
 *
 *  IN     pid             A pointer to a protocol handle structure
 *
 *  OUT    pid             The pointer to the handle has been nullified.
 *
 **/
void protocolReleaseHandle(WspProtocolHandle_t *pid) {

   XPTDEBUG(("protocolReleaseHandle(%lx)\n", (unsigned long) pid));

   if (pid == NULL) return;

   transRelease(pid->transaction);
   settingsRelease(pid->protocolSettings);
   sessionRelease(pid->session);
   protocolReleaseConnection(pid);
   pid->valid=0;              /* In case they try to reuse the freed pid */

   xppFree(pid);

} /* End of protocolReleaseHandle() */

/**
 *  protocolInitializeConnection
 *       - initializes the Service Access Point and obtains a connection
 *         handle to it.
 *       - updates the protocol structure to contain the connection handle.
 *
 *  IN:    pid             A pointer to a protocol handle structure
 *
 *  RETURN:
 *       An indication of whether or not the service access point, and therefore
 *       the physical connection, has been successfully established.
 **/
Ret_t protocolInitializeConnection(WspProtocolHandle_t *pid) {

   Ret_t rc = SML_ERR_OK;
   SapParameters *sapParmsPtr = NULL;

   XPTDEBUG(("protocolInitializeConnection(%lx)\n", (unsigned long) pid));

   if (pid == NULL) return SML_ERR_A_XPT_INVALID_PARM;