transact.c

SyncML手册及其编程

/*************************************************************************/
/* module:          Communication Services, WSP Transaction Functions    */
/* file:            src/xpt/all/transact.c                               */
/* 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.
 * 
 */

/*
 * Version Label
 *
 * RELEASE ??? CANDIDATE ?
 * 13.06.2000
 */


#include <transact.h>
#include <wspdef.h>     /* For atoi on palm */
#include <wsputil.h>
#include <xptiwsp.h>    /* for getTransactionID */
#include <xpt.h>        /* For SML_ERRs */
#include <xptport.h>

#include <define.h>     /* For __PALM_OS__ definition on the Palm */

#ifdef __PALM_OS__
 #define sprintf StrPrintF
#endif

#include <stdio.h> /* for sprintf */


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

/**
 *  transReadResponseData
 *       - Copies response body from transaction into provided input
 *         buffer.
 *
 *  IN     transaction     A pointer to the transaction structure
 *         pbData          The data buffer into which the body is copied
 *         uDataSize       The size of the data buffer
 *         puDataRead      A pointer to a size field that will be updated
 *                         to indicate how much data was copied into the
 *                         buffer.
 *
 *  OUT    transaction     The transaction has been updated to
 *                         remove all read data from the response cache.
 *         pbData          Response data has been copied into the buffer.
 *         puDataRead      The size field indicates much data was copied
 *                         into the buffer.
 *
 *  RETURN:
 *       An indication of whether the response body was successfully copied.
 **/
unsigned int transReadResponseData(WspTransaction_t *transaction,
                                void *pbData,
                                size_t uDataSize,
                                size_t *puDataRead)
{
   unsigned int rc = SML_ERR_OK;

   XPTDEBUG(("      transReadResponseData(%lx, %lx, %lu, %lu)\n",
             (unsigned long) transaction, (unsigned long) pbData,
             (unsigned long) uDataSize, (unsigned long) puDataRead));

   *puDataRead = 0;

   if ((transaction == NULL) || (pbData == NULL) || (puDataRead == NULL))
      return SML_ERR_A_XPT_INVALID_PARM;

   if (uDataSize <= 0)
      return SML_ERR_A_XPT_INVALID_PARM;

   /**
    * Does this reponse need to distinguish between no data on a get vs.
    * put vs. post?
    **/
   if ((transaction == NULL) || (transaction->rspBody == NULL))
      return rc;                 /* No response data                           */

   /*
    * Copy the data to the provided buffer
    */

   if (uDataSize >= (transaction->rspBodySize)) {
      xppMemcpy(pbData, transaction->rspBody, transaction->rspBodySize);
      *puDataRead = transaction->rspBodySize;
//      return SML_ERR_A_XPT_EOX;  /* Indicate all data successfully read        */
      return SML_ERR_OK;         /* Indicate all data successfully read        */
   } else {                      /* Entire response will not fit in buffer     */
      xppMemcpy(pbData, transaction->rspBody, uDataSize);
      *puDataRead = uDataSize;
      adjustResponseBody(transaction, uDataSize);
      return SML_ERR_OK;         /* Indicate more data to be read              */
   } /* End buffer will not fit entire response body */

//   return SML_ERR_A_XPT_EOX;
   return SML_ERR_OK;         /* Indicate all data successfully read        */
} /* End transReadResponseData() */


/**
 *  transInitialize
 *       - allocates storage for a WSP transaction.
 *       - assigns the transaction id
 *
 *  OUT     transactionPtr    Updated to point to a transaction structure
 *
 *  RETURN
 *       An indicaton of whether the transaction structur was successfully
 *       allocated and initialized.
 *
 **/
unsigned int transInitialize(WspTransaction_t **transactionPtr)
{
   unsigned int  rc          = SML_ERR_OK;
   WspTransaction_t *transaction = NULL;

   XPTDEBUG(("      transInitialize(%lx)\n", (unsigned long) transactionPtr));

   if (transactionPtr == NULL)
      return SML_ERR_A_XPT_INVALID_PARM;

   if (*transactionPtr != NULL) {
      transRelease(*transactionPtr);
   }

   transaction = (WspTransaction_t *) xppMalloc(sizeof(WspTransaction_t));

   if (transaction == NULL)
      return SML_ERR_A_XPT_MEMORY;

   xppMemset(transaction, 0, sizeof(WspTransaction_t));
   transaction->id = getTransactionID();

   *transactionPtr = transaction;

   return rc;
} /* End transInitialize() */

/**
 *  transRelease
 *       - releases all storage associated with the WSP transaction.
 *
 *  IN     transaction     A pointer to a transaction structure
 *
 **/
void transRelease(WspTransaction_t *transaction) {

   XPTDEBUG(("      transRelease(%lx)...\n", (unsigned long) transaction));

   if (transaction == NULL) return;

   releaseDocumentInfo(transaction);
   releaseTransactionRequestData(transaction);
   releaseTransactionResponseData(transaction);

   xppFree(transaction);

} /* End transRelease() */

/**
 *  releaseTransactionRequestData
 *       - releases all storage associated with the WSP transaction request.
 *
 *  IN     transaction     A pointer to the wsp transaction structure
 *
 **/
void releaseTransactionRequestData(WspTransaction_t *transaction) {


   XPTDEBUG(("        releaseTransactionRequestData(%lx)\n", (unsigned long) transaction));

   if (transaction == NULL) return;

/* method contains a static string, nothing to release */
   transaction->method = NULL;

   xppFree(transaction->uri);
   transaction->uri = NULL;

   xppFree(transaction->reqHdr);
   transaction->reqHdr = NULL;
   transaction->reqHdrSize = 0;

   xppFree(transaction->reqBody);
   transaction->reqBody = NULL;
   transaction->reqBodySize = 0;

} /* End releaseTransactioRequestData() */

/**
 *  releaseTransactionResponseData
 *       - releases all storage associated with the WSP transaction response.
 *
 *  IN     transaction     A pointer to the wsp transaction structure
 *
 **/
void releaseTransactionResponseData(WspTransaction_t *transaction) {

   XPTDEBUG(("        releaseTransactionResponseData(%lx)\n", (unsigned long) transaction));

   if (transaction == NULL) return;

   xppFree(transaction->rspHdr);
   transaction->rspHdr = NULL;
   transaction->rspHdrSize = 0;

   xppFree(transaction->rspBody);
   transaction->rspBody = NULL;
   transaction->rspBodySize = 0;

} /* End releaseTransactionResponseData() */


/**
 *  transSendRequestOverSession
 *       - Does an abstract WSP methodInvoke for a session connection
 *       - waits for method result
 *       - responds with method acknowledgement.
 *
 *  IN:    sessionHandle   A pointer to a session handle from the connect
 *         transaction     A pointer to a transaction structure which
 *                         contains the method request parameters.
 *
 *  OUT:   transaction     The transaction structure has been updated to
 *                         contain the method response information.
 *
 *  RETURN:
 *       An indication of whether the method invocation was successful
 **/
unsigned int transSendRequestOverSession(awsp_SessionHandle sessionHandle,
                                         WspTransaction_t  *transaction)
{
   unsigned int rc          = SML_ERR_OK;
   awsp_Rc_t   aRc          = AWSP_RC_OK;

   XPTDEBUG(("      transSendRequestOverSession(%lx, %lx)...\n",
             (unsigned long) sessionHandle, (unsigned long) transaction));

   if ((sessionHandle == NULL) || (transaction == NULL))
      return SML_ERR_A_XPT_INVALID_PARM;

   /* Send WSP request and wait for response                                   */
   aRc = awsp_methodInvoke_req(sessionHandle,
                               transaction->id,
                               transaction->method,
                               transaction->uri,
                               transaction->reqHdr,
                               transaction->reqHdrSize,
                               transaction->reqBody,
                               transaction->reqBodySize);

   if (aRc != AWSP_RC_OK) {
      setLastError(aRc, "WSP Binding awsp method invoke request failed.");
      rc = SML_ERR_A_XPT_COMMUNICATION;
   } else
      rc = getMethodResponse(sessionHandle, transaction);

   /**
    * Need to verify under what conditions the response must be sent, and
    * decide which rc - the method invoke, method response, or method
    * confirmation rc - should be returned from this function...
    **/
   if (rc == SML_ERR_OK)
      /* We don't really care if our confirmation failed...          */
//      aRc = awsp_methodResult_rsp(sessionHandle,
      awsp_methodResult_rsp(sessionHandle,
                            transaction->id,
                            NULL,         /* No acknowledgement hdrs for now */
                            0);

   if (aRc != AWSP_RC_OK) {
      setLastError(aRc, "WSP Binding awsp method result response failed.");
      rc = SML_ERR_A_XPT_COMMUNICATION;
   }

   return rc;
} /* End transSendRequestOverSession() */


unsigned int getMethodResponse(awsp_SessionHandle sessionHandle,
                               WspTransaction_t  *transaction)
{
   unsigned int rc          = SML_ERR_OK;
   awsp_Rc_t   aRc         = AWSP_RC_OK;

   XPTDEBUG(("        getMethodResponse(%lx, %lx)\n",
             (unsigned long) sessionHandle, (unsigned long) transaction));

   if ((sessionHandle == NULL) || (transaction == NULL))
      return SML_ERR_A_XPT_INVALID_PARM;

   /* What if our objects are deleted from under us while we wait???           */
   aRc = awsp_get_methodResult_ind(sessionHandle,
                                   transaction->id,
                                   &(transaction->status),
                                   NULL,
                                   &(transaction->rspHdrSize),
                                   NULL,
                                   &(transaction->rspBodySize));