ema.h

基于h323协议的软phone

/*
***********************************************************************************

NOTICE:
This document contains information that is proprietary to RADVISION LTD..
No part of this publication may be reproduced in any form whatsoever without
written prior approval by RADVISION LTD..

RADVISION LTD. reserves the right to revise this publication and make changes
without obligation to notify any person of such revisions or changes.

***********************************************************************************
*/

/*
  ema.h

  RADVISION static array implementation.

  The EMA module provides the Enhanced Memory Allocation services that RA provides, with
  several additional features:

  1. Knowledge about the type of handle in EMA.
     An EMA element can be checked for its type using emaGetType()
  2. Reference counts
     Each element has a reference count that can be accessed through emaIncRefCount() and
     emaDefRefCount().
  3. Auto-lock
     EMA will automatically lock itself on functions that need thread-safety (such as
     emaAdd).
  4. Explicit element locks

  EMA can also be used to link elements from different types to the same locks are reference
  counts. It is done in CM to link the channels of the call to the call, allowing easier
  locking and reference counting mechanisms.

  Written by Tsahi Levent-Levi

*/


#ifndef _EMA_H
#define _EMA_H

#ifdef __cplusplus
extern "C" {
#endif

#include "rvwatchdog.h"
#include "ra.h"

#if defined(RV_DEBUG)
#define RV_EMA_DEBUG
#endif


/* Handle to an EMA object */
RV_DECLARE_HANDLE(HEMA);


/* EMA element pointer declaration */
typedef void *EMAElement;



/************************************************************************
 * emaStatistics struct
 * elems        - Statistics about the elements inside EMA
 * numMarked    - Number of items that are marked and deleted, not released
 *                yet.
 ************************************************************************/
typedef struct
{
    RvRaStatistics    elems;
    RvUint32            numMarked;
} emaStatistics;


/************************************************************************
 * emaLockType enum
 * emaNoLocks       - EMA is not using locks at all. It does use referece
 *                    counts. It will only use a general lock to lock when
 *                    adding and deleting elements
 * emaNormalLocks   - EMA uses locks and reference counts in a "normal" way
 * emaLinkedLocks   - EMA's locks and reference counts are linked to another
 *                    EMA object, which holds different types of information.
 ************************************************************************/
typedef enum
{
    emaNoLocks,
    emaNormalLocks,
    emaLinkedLocks
} emaLockType;


/************************************************************************
 * EMAFunc
 * purpose: Definition of a general function on an EMA element
 * input  : elem    - Element to function on
 *          param   - Context to use for it
 * output : none
 * return : Pointer for the context to use on the next call to this
 *          EMAFunc.
 ************************************************************************/
typedef void*(*EMAFunc)(EMAElement elem, void *param);




/************************************************************************
 * emaConstruct
 * purpose: Create an EMA object
 * input  : elemSize            - Size of elements in the EMA in bytes
 *          maxNumOfElements    - Number of elements in EMA
 *          lockType            - Type of locking mechanism to use
 *          name                - Name of EMA (used in log messages)
 *          type                - Integer representing the type of objects
 *                                stored in this EMA.
 *          userData            - User related information associated with
 *                                this EMA object.
 *          instance            - Instance associated with this EMA object.
 * output : none
 * return : Handle to RA constructed on success
 *          NULL on failure
 ************************************************************************/
HEMA emaConstruct(
    IN int          elemSize,
    IN int          maxNumOfElements,
    IN emaLockType  lockType,
    IN const char*  name,
    IN RvUint32     type,
    IN void*        userData,
    IN void const*  instance);


/************************************************************************
 * emaDestruct
 * purpose: Free an EMA object, deallocating all of its used memory
 * input  : emaH   - Handle of the EMA object
 * output : none
 * return : none
 ************************************************************************/
void emaDestruct(IN HEMA emaH);


/************************************************************************
 * emaAdd
 * purpose: Allocate an element in EMA for use, without initializing its
 *          value.
 *          This automatically locks the EMA object.
 * input  : emaH        - Handle of the EMA object
 *          appHandle   - Application's handle for the element
 * output : none
 * return : Pointer to element added on success
 *          NULL on failure
 ************************************************************************/
EMAElement emaAdd(IN HEMA emaH, IN void* appHandle);


/************************************************************************
 * emaDelete
 * purpose: Delete an element from EMA
 * input  : elem    - Element to delete
 * return : Negative value on failure
 ************************************************************************/
int emaDelete(IN EMAElement elem);


/************************************************************************
 * emaLinkToElement
 * purpose: Link an EMA element to another element, from a different
 *          EMA construct. This function should be used when the EMA we're
 *          dealing with was created with emaLinkedLocks. This function
 *          allows the element to use a different element's lock.
 *          This function will only work if the element has no reference
 *          count at present.
 * input  : elem        - Element to link
 *          otherElem   - Element we're linking to. Should be constructed
 *                        with emaNormalLocks or linked to such element.
 * output : none
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
int emaLinkToElement(IN EMAElement elem, IN EMAElement otherElem);


/************************************************************************
 * emaLock
 * purpose: Lock an element in EMA for use from the executing thread only
 *          This function will succeed only if the element exists
 * input  : elem    - Element to lock
 * output : none
 * return : RV_TRUE    - When the element exists and was locked
 *          RV_FALSE   - When the element doesn't exist (NULL are was deleted)
 *                    In this case, there's no need to call emaUnlock().
 ************************************************************************/
RvBool emaLock(IN EMAElement elem);


/************************************************************************
 * emaUnlock
 * purpose: Unlock an element in EMA that were previously locked by
 *          emaLock() from the same thread
 * input  : elem    - Element to unlock
 * output : none
 * return : RV_TRUE    if element still exists
 *          RV_FALSE   if element was deleted and is not valid anymore
 *          Negative value on failure
 ************************************************************************/
int emaUnlock(IN EMAElement elem);


/************************************************************************
 * emaMark
 * purpose: Mark an element in EMA for use, not letting anyone delete
 *          this element until it is release.
 *          This automatically locks the EMA object.
 * input  : elem    - Element to mark
 * output : none
 * return : Negative value on failure
 ************************************************************************/
int emaMark(IN EMAElement elem);


/************************************************************************
 * emaRelease
 * purpose: Release an element in EMA after it was marked using
 *          emaMark(), returning an indication if this element
 *          still exists.
 *          This automatically locks the EMA object.
 * input  : elem    - Element to mark
 * output : none
 * return : RV_TRUE    if element still exists
 *          RV_FALSE   if element was deleted and is not valid anymore
 *          Negative value on failure
 ************************************************************************/
int emaRelease(IN EMAElement elem);


/************************************************************************
 * emaWasDeleted
 * purpose: Check if an element in EMA was deleted after a call to
 *          emaMark().
 * input  : elem    - Element to mark