mgrinstancemgr.c

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

/*************************************************************************/
/* module:          Managing SyncML Instances                            */
/*                                                                       */   
/* file:            mgrinstancemgr.c                                     */
/* target system:   all                                                  */
/* target OS:       all                                                  */   
/*                                                                       */   
/* Description:                                                          */   
/* Core module for managing creation and usage of instances              */
/*************************************************************************/

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


/*************************************************************************
 *  Definitions
 *************************************************************************/

#include "syncml_tk_prefix_file.h" // %%% luz: needed for precompiled headers in eVC++

/* Include Headers */
#include <smldef.h>
#include <sml.h>
#include <smlerr.h>
#include "libmem.h"
#include "libstr.h"
#include "liblock.h"
#include "wsm.h"
#include "mgr.h"



/* Used external functions */
#ifndef NOWSM
  #ifndef __SML_LITE__  /* Only ONE instance is supported in the Toolkit lite version */
    extern Ret_t addInfo(InstanceInfoPtr_t pInfo);
    extern InstanceInfoPtr_t findInfo(InstanceID_t id);
    extern Ret_t removeInfo(InstanceID_t id);
  #endif
  SyncMLInfoPtr_t mgrGetSyncMLAnchor(void);
#endif

/* Prototypes of exported SyncML API functions */
SML_API Ret_t smlInitInstance(SmlCallbacksPtr_t callbacks, SmlInstanceOptionsPtr_t pOptions, VoidPtr_t pUserData, InstanceID_t *pInstanceID);
SML_API Ret_t smlTerminateInstance (InstanceID_t id);
SML_API Ret_t smlLockReadBuffer(InstanceID_t id, MemPtr_t *pReadPosition, MemSize_t *usedSize);
SML_API Ret_t smlUnlockReadBuffer(InstanceID_t id, MemSize_t processedBytes);
#ifdef NOWSM
SML_API Ret_t smlSetMaxOutgoingSize(InstanceID_t id, MemSize_t maxOutgoingSize);
SML_API Ret_t smlSetOutgoingBegin(InstanceID_t id);
#endif
SML_API Ret_t smlLockWriteBuffer(InstanceID_t id, MemPtr_t *pWritePosition, MemSize_t *freeSize);
SML_API Ret_t smlUnlockWriteBuffer(InstanceID_t id, MemSize_t writtenBytes);
SML_API Ret_t smlSetCallbacks (InstanceID_t id, SmlCallbacksPtr_t pCallbacks);
SML_API Ret_t smlSetUserData (InstanceID_t id, VoidPtr_t pUserData);
// added by luz %%%:
SML_API Ret_t smlGetUserData(InstanceID_t id, VoidPtr_t *ppUserData);
SML_API Ret_t smlGetEncoding(InstanceID_t id, SmlEncoding_t *pEncoding);
#ifndef __SML_LITE__  /* these API calls are NOT included in the Toolkit lite version */
  SML_API Ret_t smlSetEncoding (InstanceID_t id, SmlEncoding_t encoding);
#endif



/* Private function prototypes */
Ret_t freeInstanceOptions (InstanceInfoPtr_t pInstanceInfo);
static Ret_t freeInstanceInfo (InstanceInfoPtr_t pInfo);
Ret_t mgrResetWorkspace (InstanceID_t id);
Ret_t setInstanceOptions (InstanceID_t id, SmlInstanceOptionsPtr_t pOptions);


/*************************************************************************
 *  Public SyncML API Functions
 *************************************************************************/


/**
 * FUNCTION:   smlInitInstance
 *
 * Creates a SyncML instance and assigns a corresponding workspace buffer in
 * which XML documents are assembled or parsed.
 * All callback functions implemented by a particular application are defined.
 * Instance specific options can be passed. This function has to be called 
 * before the first synchronization tasks can be performed. A reference valid
 * for a SyncML instance is returned.
 * An instance is active when processing a synchronization request
 * otherwise it is idle. An instance is terminated when smlTerminateInstance 
 * is called.
 *
 * IN:              SmlCallbacks_t
 *                  A structure holding references to the callback functions
 *                  implemented by the application
 *
 * IN:              SmlInstanceOptionsPtr_t
 *                  Option settings of a particular SyncML instance
 *
 * IN:              VoidPtr_t
 *                  UserData is a pointer to a void structure the application 
 *                  can pass into the SyncML Toolkit instance info. 
 *                  It will be returned to the application with every called 
 *                  callback function call!
 *                  NOTE: This is only a pointer, the memory object itself 
 *                  remains within the responsibility of the calling application.
 *                  The memory object will not be copied, moved or freed by the 
 *                  Toolkit.
 *
 * OUT:             InstanceID_t
 *                  Instance ID assigned to the initialized instance
 *
 * RETURN:          Ret_t
 *                  Error Code
 */
SML_API Ret_t smlInitInstance(SmlCallbacksPtr_t pCallbacks, SmlInstanceOptionsPtr_t pOptions, VoidPtr_t pUserData, InstanceID_t *pInstanceID)
{

  /* --- Definitions --- */
  InstanceInfoPtr_t pInstanceInfo;
  Ret_t             rc;


  #ifndef NOWSM
    /* --- Check pOptions, which have been passed by the application --- */
    if (!pOptions || !pOptions->workspaceName)
  	  return SML_ERR_WRONG_USAGE;

    #ifdef __SML_LITE__  /* Only ONE instance is supported in the Toolkit lite version */
      /* if ONE instance is already initialized */
      if (mgrGetInstanceListAnchor()!=NULL) 
        return SML_ERR_WRONG_USAGE;
    #endif 

    /* --- check wether we already know about this instance --- */
    #ifdef __SML_LITE__  /* Only ONE instance is supported in the Toolkit lite version */
      pInstanceInfo = mgrGetInstanceListAnchor();
    #else
      pInstanceInfo = (InstanceInfoPtr_t) findInfo(*pInstanceID);
    #endif

    /* --- bail outh when we already have a instance with that id --- */
    if (pInstanceInfo != NULL) return SML_ERR_WRONG_USAGE;


    /* --- Create a workspace for this instance --- */
    LOCKTOOLKIT("smlInitInstance"); 
    if ((rc = wsmCreate(pOptions->workspaceName, pOptions->workspaceSize, pInstanceID)) != SML_ERR_OK) {
    	RELEASETOOLKIT("smlInitInstance after wsmCreate failure");
    	return rc;
    }
    RELEASETOOLKIT("smlInitInstance");
  #else // NOWSM
    /* --- Check pOptions, which have been passed by the application --- */
    if (!pOptions || !pOptions->workspaceSize)
  	  return SML_ERR_WRONG_USAGE;
  	// ok so far
  	rc=SML_ERR_OK;
  #endif
  
  /* --- Create an instance info memory object --- */
  pInstanceInfo = (InstanceInfoPtr_t)smlLibMalloc((MemSize_t)sizeof(InstanceInfo_t));
  if (pInstanceInfo==NULL) {
    #ifndef NOWSM
    wsmDestroy(pOptions->workspaceName);   
    return SML_ERR_NOT_ENOUGH_SPACE;
    #endif
  }
  #ifdef NOWSM
  else {
    // instance info created, return pointer as instanceID
    *pInstanceID = (InstanceID_t)pInstanceInfo;
  }
  #endif
   
  smlLibMemset(pInstanceInfo,0,(MemSize_t)sizeof(InstanceInfo_t));



  /* --- Set mandatory instance infos for this instance to defaults --- */
  pInstanceInfo->status=MGR_IDLE;
  pInstanceInfo->encoderState=NULL;                  // no encoding in progress, currently not used
  pInstanceInfo->decoderState=NULL;                  // no decoding in progress, currently not used
  #ifndef NOWSM
  pInstanceInfo->id=*pInstanceID;
  pInstanceInfo->workspaceState=NULL;                // to do: some workspace status info
  pInstanceInfo->nextInfo=NULL;
  #else
  // create a instance buffer
  pInstanceInfo->instanceBufSiz=pOptions->workspaceSize; // get requested size for the buffer
  pInstanceInfo->maxOutgoingSize=pOptions->maxOutgoingSize; // set max outgoing message size
  pInstanceInfo->instanceBuffer=smlLibMalloc(pInstanceInfo->instanceBufSiz);
  if (pInstanceInfo->instanceBuffer==NULL)
    return SML_ERR_NOT_ENOUGH_SPACE;
  // init buffer pointers
  pInstanceInfo->readPointer=pInstanceInfo->instanceBuffer;
  pInstanceInfo->writePointer=pInstanceInfo->instanceBuffer;
  pInstanceInfo->readLocked=0;
  pInstanceInfo->writeLocked=0;
  pInstanceInfo->outgoingMsgStart=NULL;
  #endif


  #ifndef NOWSM
    /* --- Add instance infos memory object to the instance info list --- */
    #ifdef __SML_LITE__  /* Only ONE instance is supported in the Toolkit lite version */
      mgrSetInstanceListAnchor(pInstanceInfo);
    #else
      rc = addInfo( pInstanceInfo );
      if (rc!=SML_ERR_OK) return rc;
    #endif 
  #endif


  /* --- Set the values of instance Infos as defined by the calling application ---*/

  /* Set user data pointer */
  pInstanceInfo->userData=pUserData;
  /* Set callback functions implemented by applications */
  if (smlSetCallbacks(*pInstanceID, pCallbacks) != SML_ERR_OK) {
    #ifndef NOWSM
	  wsmDestroy(pOptions->workspaceName);
	  #endif
	  return rc;
  }

  // luz: %%% this was called twice, probably this is a bug, so I disabled the second call
  //smlSetCallbacks(*pInstanceID, pCallbacks);

  /* Set other application defined options for that instance */
  if (setInstanceOptions (*pInstanceID, pOptions) != SML_ERR_OK) {
    #ifndef NOWSM
 	  wsmDestroy(pOptions->workspaceName);
 	  #endif
 	  return rc;
  }

  return SML_ERR_OK;
  
}



/**
 * FUNCTION:   smlTerminateInstance
 *
 * Terminates a SyncML instance. The instance info is removed from the instances
 * list. Allmemory allocated for the workspace and the options variables is freed.
 *
 * IN:              InstanceID_t
 *                  ID of the instance to be terminated
 *
 * RETURN:          Ret_t
 *                  Error Code
 */
SML_API Ret_t smlTerminateInstance (InstanceID_t id)
{

  /* --- Definitions --- */
  InstanceInfoPtr_t pInstanceInfo;

  #ifdef NOWSM
    pInstanceInfo = (InstanceInfoPtr_t)id; // ID is the instance info pointer
  #else  
    Ret_t             rc;
    
    /* --- Find that instance --- */
    #ifdef __SML_LITE__  /* Only ONE instance is supported in the Toolkit lite version */
      pInstanceInfo = mgrGetInstanceListAnchor();
    #else
      pInstanceInfo = (InstanceInfoPtr_t) findInfo(id);
    #endif
  #endif
  
  if (pInstanceInfo==NULL) return SML_ERR_MGR_INVALID_INSTANCE_INFO;

  #ifndef NOWSM
    /* --- Close the workspace --- */
    if (pInstanceInfo->instanceOptions != NULL) {
  		LOCKTOOLKIT("smlTerminateInstance");
    	rc = wsmDestroy(pInstanceInfo->instanceOptions->workspaceName);
    	RELEASETOOLKIT("smlTerminateInstance");
    	if (rc!=SML_ERR_OK) {
      	//	  freeInstanceInfo(pInstanceInfo);  
    		return rc;
    	}
    }	
      
    /* --- Delete instance info and options --- */
    #ifdef __SML_LITE__  /* Only ONE instance is supported in the Toolkit lite version */
      mgrSetInstanceListAnchor(NULL);
    #else
      removeInfo(id);
    #endif
  #endif
  
  freeInstanceInfo (pInstanceInfo);
  
  return SML_ERR_OK;
}



/**
 * FUNCTION:  smlSetCallbacks
 *
 * Sets new callback functions to an instance
 *
 * IN:        InstanceID_t              
 *            ID of the Instance
 *
 * IN:        SmlCallbacksPtr_t
 *            A structure holding references to the callback functions
 *            implemented by the application
 *
 * RETURN:    Return value,            
 *            SML_ERR_OK if successful
 */
SML_API Ret_t smlSetCallbacks(InstanceID_t id, SmlCallbacksPtr_t pCallbacks)
{

  /* --- Definitions --- */
  InstanceInfoPtr_t	pInstanceInfo;
  SmlCallbacksPtr_t    pCallbacksCopy;

  /* --- Check pCallbacks, which have been passed by the application --- */
  if (!pCallbacks)
    return SML_ERR_WRONG_USAGE;