ema.h

基于h323协议的软phone

 * output : none
 * return : RV_TRUE    if element was deleted
 *          RV_FALSE   if element still exists
 ************************************************************************/
RvBool emaWasDeleted(IN EMAElement elem);


/************************************************************************
 * emaPrepareForCallback
 * purpose: Prepare an element in EMA for use in a callback to the app.
 *          This function will make sure the element is unlocked the necessary
 *          number of times, and then marked once (so the app won't delete
 *          this element).
 *          emaReturnFromCallback() should be called after the callback,
 *          with the return value of this function.
 * input  : elem    - Element to prepare
 * output : none
 * return : Number of times the element was locked on success
 *          Negative value on failure
 ************************************************************************/
int emaPrepareForCallback(IN EMAElement elem);


/************************************************************************
 * emaReturnFromCallback
 * purpose: Make sure the EMA element knows it has returned from a
 *          callback. This function will ensure that the element is
 *          locked again with the specified number of times. It will also
 *          release the element, and if timersLocked==0, and the element
 *          was deleted by the app in the callback, the element will also
 *          be permanently deleted.
 * input  : elem    - Element to prepare
 * 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 emaReturnFromCallback(IN EMAElement elem, IN int timesLocked);


/************************************************************************
 * emaSetApplicationHandle
 * purpose: Set the application handle of an element in EMA
 * input  : elem        - Element in EMA
 *          appHandle   - Application's handle for the element
 * output : none
 * return : Negative value on failure
 ************************************************************************/
int emaSetApplicationHandle(IN EMAElement elem, IN void* appHandle);


 /************************************************************************
 * emaGetApplicationHandle
 * purpose: Get the application's handle of an element in EMA
 * input  : elem        - Element in EMA
 * output : appHandle   - Application's handle for the element
 * return : Pointer to the application handle
 *          NULL on failure
 ************************************************************************/
void* emaGetApplicationHandle(IN EMAElement elem);


/************************************************************************
 * emaGetType
 * purpose: Return the type of the element inside the EMA object.
 *          This is the type given in emaConstruct().
 * input  : elem    - Element in EMA
 * output : none
 * return : The element's type on success
 *          0 on failure
 ************************************************************************/
RvUint32 emaGetType(IN EMAElement elem);


/************************************************************************
 * emaGetUserData
 * purpose: Return the user related data of the element inside the EMA
 *          object. This is the userData given in emaConstruct().
 * input  : elem    - Element in EMA
 * output : none
 * return : The element's user data pointer on success
 *          NULL on failure
 ************************************************************************/
void* emaGetUserData(IN EMAElement elem);

/************************************************************************
 * emaGetUserDataByInstance
 * purpose: Return the user related data inside the EMA object, by the
 *          EMA instance returned by emaConstruct().
 *          This is the userData given in emaConstruct().
 * input  : emaH   - handle to the EMA
 * output : none
 * return : The user data pointer on success
 *          NULL on failure
 ************************************************************************/
void* emaGetUserDataByInstance(IN HEMA emaH);

/************************************************************************
 * emaGetInstance
 * purpose: Return the instance of this EMA element.
 *          This is the instance given in emaConstruct().
 * input  : elem    - Element in EMA
 * output : none
 * return : The element's instance on success
 *          NULL on failure
 ************************************************************************/
void const* emaGetInstance(IN EMAElement elem);


/************************************************************************
 * emaGetObject
 * purpose: Return the EMA object this element is in
 * input  : elem    - Element in EMA
 * output : none
 * return : The element's EMA object on success
 *          NULL on failure
 ************************************************************************/
HEMA emaGetObject(IN EMAElement elem);


/************************************************************************
 * emaDoAll
 * purpose: Call a function on all used elements in EMA
 * input  : emaH        - Handle of the EMA object
 *          func        - Function to execute on all elements
 *          param       - Context to use when executing the function
 * output : none
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
int emaDoAll(
    IN HEMA     emaH,
    IN EMAFunc  func,
    IN void*    param);


/************************************************************************
 * emaGetNext
 * purpose: Get the next used element in EMA.
 *          This function can be used to implement search or "doall"
 *          functions on EMA.
 * input  : emaH        - Handle of the EMA object
 *          cur         - Current EMA element whose next we're looking for
 *                        If NULL, then emaGetNext() will return the first
 *                        used element.
 * output : none
 * return : Pointer to the next used element on success
 *          NULL when no more used elements are left
 ************************************************************************/
EMAElement emaGetNext(
    IN HEMA         emaH,
    IN EMAElement   cur);


/************************************************************************
 * emaGetIndex
 * purpose: Returns the index of the element in the ema
 * input  : elem    - Element in EMA
 * output : none
 * return : The element's index on success
 *          Negative value on failure
 ************************************************************************/
int emaGetIndex(IN EMAElement elem);


/************************************************************************
 * emaGetStatistics
 * purpose: Get statistics information about EMA.
 *          The number of used items also includes those deleted, but still
 *          marked.
 * input  : emaH        - Handle of the EMA object
 * output : stats       - Statistics information
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
int emaGetStatistics(IN HEMA emaH, OUT emaStatistics* stats);


/************************************************************************
 * emaIsVacant
 * purpose: Returns whether the given object is free for allocation
 * input  : elem    - Element in EMA
 * output : none
 * return : RV_TRUE  - if the elemnt is not allocated
 *          RV_FALSE - otherwise
 ************************************************************************/
int emaIsVacant(IN EMAElement elem);


/******************************************************************************
 * emaAddWatchdogResource
 * ----------------------------------------------------------------------------
 * General: Add an EMA instance as a resource handled by the watchdog.
 *
 * Return Value: RV_OK  - if successful.
 *               Other on failure
 * ----------------------------------------------------------------------------
 * Arguments:
 * Input:  emaH         - EMA instance handle.
 *         watchdog     - The watchdog instance to add this EMA to.
 *         name         - Name of resource to use.
 *         group        - Group name for this resource.
 *         description  - Short description about this resource.
 *****************************************************************************/
RvStatus emaAddWatchdogResource(
    IN HEMA         emaH,
    IN RvWatchdog   *watchdog,
    IN const char   *name,
    IN const char   *group,
    IN const char   *description);




#ifdef RV_EMA_DEBUG

#define emaLock(elem) emaLockDebug(elem, __FILE__, __LINE__)
#define emaUnlock(elem) emaUnlockDebug(elem, __FILE__, __LINE__)
#define emaMark(elem) emaMarkDebug(elem, __FILE__, __LINE__)
#define emaRelease(elem) emaReleaseDebug(elem, __FILE__, __LINE__)
#define emaPrepareForCallback(elem) emaPrepareForCallbackDebug(elem, __FILE__, __LINE__)
#define emaReturnFromCallback(elem, timesLocked) emaReturnFromCallbackDebug(elem, timesLocked, __FILE__, __LINE__)
#define emaDelete(elem) emaDeleteDebug(elem, __FILE__, __LINE__)

RvBool emaLockDebug(IN EMAElement elem, IN const char* filename, IN int lineno);
int emaUnlockDebug(IN EMAElement elem, IN const char* filename, IN int lineno);
int emaMarkDebug(IN EMAElement elem, IN const char* filename, IN int lineno);
int emaReleaseDebug(IN EMAElement elem, IN const char* filename, IN int lineno);
int emaPrepareForCallbackDebug(IN EMAElement elem, IN const char* filename, IN int lineno);
int emaReturnFromCallbackDebug(IN EMAElement elem, IN int timesLocked, IN const char* filename, IN int lineno);
int emaDeleteDebug(IN EMAElement elem, IN const char* filename, IN int lineno);

#endif  /* RV_EMA_DEBUG */




#ifdef __cplusplus
}
#endif

#endif  /* _EMA_H */