pvaltree.h

基于h323协议的软phone

/***********************************************************************
        Copyright (c) 2002 RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Ltd.. No part of this document may be reproduced in any
form whatsoever without written prior approval by RADVISION Ltd..

RADVISION Ltd. reserve the right to revise this publication and make
changes without obligation to notify any person of such revisions or
changes.
***********************************************************************/

/*
  pvaltree.h

  Tree manipulation.
  Holds message values according to syntax structure.
  Support multiple messages (trees) within a single instance.

  Global behavior:
  All functions return negative values upon illegal paramenters or any other error situation.
  Some functions return RV_TRUE on normal conditions.
  OUT pointer parameters may be NULL if there is no need for them.

  Handlers:
   - HPVT: value tree instance handler.
   - nodeId: single message (tree) identifier.

  Function parameters:
   - parentId: Id of parent node. Unique node identifier.
   - fieldId: enumeration of field as in the message.
   - value: integer value of node.
   - index: of child under parent. >=1
   - path: string description by dotted notation of node location in tree.
          e.g. root.colors.white
  */

#ifndef _PVALTREE_H
#define _PVALTREE_H

#include "rvtypes.h"
#include "rverror.h"
#include "psyntree.h"

#ifdef __cplusplus
extern "C" {
#endif


/* handler */
RV_DECLARE_HANDLE(HPVT);

/* print function prototype */
typedef void (*pvtPrintFuncP)(IN void* type, IN const char* line, ...);


/* Node Id definition */
typedef RvInt RvPvtNodeId;


/* An indication of an invalid node id */
#define RV_PVT_INVALID_NODEID (RvPvtNodeId)-1

/* Macro definition indicating if a node id is valid or not */
#define RV_PVT_NODEID_IS_VALID(_nodeId) ((RvInt)(_nodeId) >= 0)



/* Defined here to remove dependency of this API header from rvlog.h */
#define RV_PVT_LOGDEBUG 0x10



/************************************************************************
 *
 *                      Field ID macros
 *
 ************************************************************************/

/* Macros for nice access to paths by field ids */
#ifndef LAST_TOKEN
#define LAST_TOKEN (-5) /* Last token in fieldPath parameters */
#endif

#ifndef MAX_TOKEN
#define MAX_TOKEN  100 /* maximal elements in a path */
#endif

/* Macros used to specify any value of the given choice - they are the equivalent of '*' in
   their string functions */
#define _anyField (-1),
#define __anyField (-1)

/* Used to specify the index of the value inside a SEQUENCE OF */
#define _nul(_a) -(_a)-100,
#define __nul(_a) -(_a)-100


/* Macros that allow easier access to the fields through the pvtXXXByFieldIds */
#define __pvtGetByFieldIds(_res, _valH, _nodeId, _path, _fieldId, _value, _isString) \
    { static RvInt16 fieldPath[] = _path; \
      _res = pvtGetByFieldIds(_valH, _nodeId, fieldPath, _fieldId, _value, _isString); \
    }
#define __pvtGetNodeIdByFieldIds(_res, _valH, _nodeId, _path) \
    { static RvInt16 fieldPath[] = _path; \
      _res = pvtGetNodeIdByFieldIds(_valH, _nodeId, fieldPath); \
    }
#define __pvtBuildByFieldIds(_res, _valH, _rootNodeId, _path, _value, _strValue) \
    { static RvInt16 fieldPath[] = _path; \
      _res = pvtBuildByFieldIds(_valH, _rootNodeId, fieldPath, _value, _strValue); \
    }






/************************************************************************
 * pvtConstruct
 * purpose: Construct a pool of PVT nodes.
 * input  : stringBufferSize    - Not used
 *          numOfNodes          - The maximum number of nodes to be allowed
 *                                in the tree
 * output : none
 * return : Handle to PVT constructed on success
 *          NULL on failure
 ************************************************************************/
RVAPI HPVT RVCALLCONV
pvtConstruct(
        IN  int stringBufferSize,
        IN  int numOfNodes);


/************************************************************************
 * pvtDestruct
 * purpose: Destruct a pool of PVT nodes.
 * input  : valH    - The PVT handle
 * output : none
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtDestruct(IN  HPVT valH);



/************************************************************************
 * pvtGetRoot
 * purpose: Returns the Node ID of the root of a Value Tree to which a
 *          specified node belongs
 * input  : valH    - The PVT handle
 *          nodeId  - The ID of the node inside a tree
 * output : none
 * return : Root node ID of the given node ID on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetRoot(
       IN  HPVT         valH,
       IN  RvPvtNodeId  nodeId);


/************************************************************************
 * pvtGetSynTree
 * purpose: Returns a handle to the structure (Syntax Tree) definition of
 *          a specified node
 * input  : valH    - The PVT handle
 *          nodeId  - The ID of the node the syntax of which is returned
 * output : none
 * return : A handle to the structure (Syntax Tree) definition on success
 *          NULL on failure
 ************************************************************************/
RVAPI HPST RVCALLCONV
pvtGetSynTree(
          IN  HPVT          valH,
          IN  RvPvtNodeId   nodeId);


/************************************************************************
 * pvtCurSize
 * purpose: Gets the number of nodes currently used in the Value Tree forest
 * input  : valH    - The PVT handle
 * output : none
 * return : The number of nodes in the Value Tree forest on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtCurSize(IN HPVT valH);


/************************************************************************
 * pvtMaxUsage
 * purpose: Gets the highest number of nodes used in the Value Tree forest
 *          since the cmInitialize() function was called.
 * input  : valH    - The PVT handle
 * output : none
 * return : The maximum number of nodes used in the Value Tree forest on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtMaxUsage(IN HPVT valH);


/************************************************************************
 * pvtMaxSize
 * purpose: Gets the highest number of nodes that cab be used in the Value Tree forest
 * input  : valH    - The PVT handle
 * output : none
 * return : The maximum number of nodes in the Value Tree forest on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtMaxSize(IN HPVT valH);



/************************************************************************
 * pvtPoolStatistics
 * purpose: Get pool statistics (space is in bytes)
 * input  : valH            - The PVT handle
 * output : poolSize        - Maximum size of pool
 *          availableSpace  - Current available space
 *          maxFreeChunk    - Always returned as 0
 *          numOfChunks     - Always returned as 0
 *          If any output parameter is set to NULL, it will be discarded
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtPoolStatistics(
          IN  HPVT   valH,
          OUT RvInt32* poolSize,
          OUT RvInt32* availableSpace,
          OUT RvInt32* maxFreeChunk,
          OUT RvInt32* numOfChunks);


/************************************************************************
 * pvtTreeSize
 * purpose: Returns the number of nodes included in a Value Tree root
 * input  : valH        - The PVT handle
 *          parentId    - The ID of any node
 * output : none
 * return : The number of nodes included in a Value Tree on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtTreeSize(
        IN  HPVT        valH,
        IN  RvPvtNodeId parentId);


/************************************************************************
 * pvtNumChilds
 * purpose: Returns the number of the dependents (children) of a parent tree
 * input  : valH        - The PVT handle
 *          parentId    - The ID of any node
 * output : none
 * return : The number of immediate nodes under the given node on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtNumChilds(
        IN  HPVT        valH,
        IN  RvPvtNodeId parentId);


/************************************************************************
 * pvtParent
 * purpose: Returns the ID of the parent node of a specified node
 * input  : valH        - The PVT handle
 *          nodeId      - The ID of any node
 * output : none
 * return : The parent ID of the given node on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtParent(
      IN  HPVT          valH,
      IN  RvPvtNodeId   nodeId);


/************************************************************************
 * pvtBrother
 * purpose: Returns the Node ID of a specified node's brother (right).
 * input  : valH        - The PVT handle
 *          nodeId      - The ID of any node
 * output : none
 * return : The node ID of the given node's brother on success
 *          Negative value on failure
 * The function returns the next child (rightward). Use pvtChild() to get
 * the first dependent, and then use pvtBrother() to get to the next brother.
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtBrother(
       IN  HPVT         valH,
       IN  RvPvtNodeId  nodeId);


/************************************************************************
 * pvtLBrother
 * purpose: Gets the ID of the node before (left) a particular node
 * input  : valH        - The PVT handle
 *          nodeId      - The ID of any node
 * output : none
 * return : The node ID of the previous node on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtLBrother(
       IN  HPVT         valH,
       IN  RvPvtNodeId  nodeId);


/************************************************************************
 * pvtChild
 * purpose: Returns the Node ID of the first (leftmost) child of a parent.
 * input  : valH        - The PVT handle
 *          parentId    - The ID of any node
 * output : none
 * return : The Node ID of the first (leftmost) child of a parent on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtChild(
     IN  HPVT   valH,
     IN  RvPvtNodeId    parentId);


/************************************************************************
 * pvtNext
 * purpose: Returns the ID of a node located after a specified node.
 * input  : valH    - The PVT handle
 *          rootId  - The ID of the root node of the current Value Tree
 *          location- A Node ID inside the given root
 * output : none
 * return : The Node ID of the next node in the tree on success - this
 *          value should be given as the location on the next call.
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtNext(
    IN  HPVT            valH,
    IN  RvPvtNodeId     rootId,
    IN  RvPvtNodeId     location);



/************************************************************************
 * pvtAddRoot
 * purpose: Adds a new node that constitutes the root of a new tree.
 * input  : valH    - PVT handle to use