pvaltree.h

基于h323协议的软phone

 * pvtGetChildByFieldId
 * purpose: Returns the child's value based on its field ID
 * input  : valH        - PVT handle to use
 *          parentId    - The Node ID of the immediate parent
 *          fieldId     - The field ID of the node that the function is
 *                        expected to locate
 * output : value       - Value of the root node, or length of the value if
 *                        value is a string
 *          isString    - RV_TRUE if node contains a string - see pvtGetString()
 * return : Child's node id on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetChildByFieldId(
    IN  HPVT            valH,
    IN  RvPvtNodeId     nodeId,
    IN  RvPstFieldId    fieldId,
    OUT RvInt32*        value,
    OUT RvBool*         isString);


/************************************************************************
 * pvtGetByIndex
 * purpose: Returns the ID of a child node based on the child's index
 * input  : valH        - PVT handle to use
 *          parentId    - The Node ID of the immediate parent
 *          index       - The index of the child, as determined by pvtAdd().
 *                        This index is 1-based.
 * output : childNodeId - The ID of the node that is found, or negative value on failure
 *                        If set to NULL, it will be discarded
 * return : Child's node id on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetByIndex(
    IN  HPVT            valH,
    IN  RvPvtNodeId     parentId,
    IN  RvInt32         index,
    OUT RvPvtNodeId*    childNodeId);


/************************************************************************
 * pvtGetSyntaxIndex
 * purpose: Gets the index of the node in the parent syntax structure.
 * input  : valH    - PVT handle to use
 *          nodeId  - The PVT Node ID
 * output : none
 * return : The index of the specified node in the parent syntax
 *          structure on success (this is 1-based)
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtGetSyntaxIndex(
    IN  HPVT        valH,
    IN  RvPvtNodeId nodeId);


/************************************************************************
 * pvtSearchPath
 * purpose: Searches for a specified path, value or both in a specified tree
 * input  : destH       - PVT handle of the search tree
 *          rootNodeId  - Root ID of the search tree
 *          srcH        - PVT handle of path to be searched in
 *          srcNodeId   - Node ID of the beginning of the path to be searched in
 *          checkLeaves - If RV_TRUE, Compare the values in the lowest level nodes (leaves)
 *                        Use RV_FALSE if the tree syntax contains choices.
 * output : none
 * return : RV_TRUE if found, RV_FALSE if not
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtSearchPath(
    IN  HPVT        destH,
    IN  RvPvtNodeId rootNodeId,
    IN  HPVT        srcH,
    IN  RvPvtNodeId srcNodeId,
    IN  RvBool      checkLeaves);





/************************************************************************
 * pvtPrint
 * purpose: Print a tree from a given node, using a specified printing
 *          function
 * input  : valH        - Value Tree handle
 *          parentId    - node ID to start printing from
 *          pFunc       - The function called for the printing itself
 *          pFuncParam  - The context to pass to the print function
 *                        on each printed line
 * output : none
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
RVAPI
int RVCALLCONV pvtPrint(
    IN  HPVT            valH,
    IN  RvPvtNodeId     parentId,
    IN  pvtPrintFuncP   pFunc,
    IN  void *          pFuncParam);


/************************************************************************
 * pvtPrintStd
 * purpose: Print a tree from a given node
 * input  : valH        - Value Tree handle
 *          parentId    - node ID to start printing from
 *          logHandle   - Log source to print to
 * output : none
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
RVAPI
int RVCALLCONV pvtPrintStd(
    IN  HPVT        valH,
    IN  RvPvtNodeId parentId,
    IN  int         logHandle);






/*---------------------- by path operations ------------------------ */


/************************************************************************
 * pvtGetNodeIdByPath
 * purpose: Returns the ID of a node based on a path that starts from a
 *          specified root
 * input  : valH                - Value Tree handle
 *          searchRootNodeId    - The ID of the node from which the search starts from
 *          path                - The path to the searched node. format: "a.b.c"
 * output : none
 * return : Node ID we've reached on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetNodeIdByPath(
    IN  HPVT        valH,
    IN  RvPvtNodeId searchRootNodeId,
    IN  const char* path);


/************************************************************************
 * pvtSetByPath
 * purpose: Modifies the value stored in a node. The function first locates
 *          the node based on a path. The function will fail if "path" doesn't exist
 * input  : valH    - Value Tree handle
 *          rootId  - The ID of the node from which the search starts from
 *          path    - The path to the searched node. format: "a.b.c"
 *          value   - Value of the root node, or length of the value if
 *                    value is a string
 *          string  - String value of the node, or NULL if not a string
 *                    The string is allocated and stored in the PVT.
 * output : none
 * return : Non-negative value on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtSetByPath(
    IN  HPVT        valH,
    IN  RvPvtNodeId rootId,
    IN  const char* path,
    IN  RvInt32     value,
    IN  const char* string);


/************************************************************************
 * pvtBuildByPath
 * purpose: Modifies the value stored in a node. The function first builds
 *          the path to the node, if the path does not exist.
 * input  : valH    - Value Tree handle
 *          rootId  - The ID of the node from which the search starts from
 *          path    - The path to the searched node. format: "a.b.c"
 *          value   - Value of the root node, or length of the value if
 *                    value is a string
 *          string  - String value of the node, or NULL if not a string
 *                    The string is allocated and stored in the PVT.
 * output : none
 * return : Last built node ID on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtBuildByPath(
    IN  HPVT        valH,
    IN  RvPvtNodeId rootId,
    IN  const char* path,
    IN  RvInt32     value,
    IN  const char* string);


/************************************************************************
 * pvtGetChildTagByPath
 * purpose: Gets the tag value of the node specified in the path format
 * input  : valH    - Value Tree handle
 *          nodeId  - The ID of the node
 *          path    - The path of the child node from the node specified in
 *                    the nodeId parameter
 *          relation- The number of levels down the tree from the node specified
 *                    in the nodeId parameter
 * output : none
 * return : The tag value of the specified node on success
 *          Negative value on failure
 ************************************************************************/
RVAPI int RVCALLCONV
pvtGetChildTagByPath(
    IN  HPVT        valH,
    IN  RvPvtNodeId nodeId,
    IN  const char* path,
    IN  int         relation);


/************************************************************************
 * pvtGetByPath
 * purpose: This function returns the value in a node of the Value Tree.
 *          As input to the function, you need to provide the starting point
 *          Node ID and the path to the node.
 * input  : valH    - Value Tree handle
 *          nodeId  - The ID of the node
 *          path    - The path of the child node from the node specified in
 *                    the nodeId parameter
 * output : fieldId     - The returned field ID of the node. You can then
 *                        use the pstGetFieldName() function to obtain the field name
 *          value       - Value of the root node, or length of the value if
 *                        value is a string
 *          isString    - RV_TRUE if node contains a string - see pvtGetString()
 * return : Node ID we've reached on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetByPath(
    IN  HPVT            valH,
    IN  RvPvtNodeId     nodeId,
    IN  const char*     path,
    OUT RvPstFieldId*   fieldId,
    OUT RvInt32*        value,
    OUT RvBool*         isString);


/**************************************************************************************
 * pvtGetNodeIdByFieldIds
 *
 * Purpose: find node id by traversing both value and syntax trees according to a path
 *          of filed Ids.
 *              - Field Ids in the path should be existant Field Ids.
 *              - Child indexes should be negetive values starting from -101.
 *              - for '*' -1 is used
 *              - to add element to SEQUENCE OF -100 may be used or the last element index + 1
 *              - The list should end with LAST_TOKEN value
 *
 * Input:   val H       - vtStruct of val tree
 *          nodeId      - The start of the val sub tree.
 *          path        - An array of fieldIds, ending with LAST_TOKEN
 *                        from search root. format: {a,b,c,LAST_TOKEN}
 *
 *
 * Return value: The found node id or negative value on failure
 **************************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetNodeIdByFieldIds(
    IN  HPVT            valH,
    IN  RvPvtNodeId     searchRootNodeId,
    IN  const RvInt16*  path);


/**************************************************************************************
 * pvtGetByFieldIds
 *
 * Purpose: Get the data of a node pointed by a given path of field ids
 *
 * Input:   valH        - vtStruct of val tree
 *          nodeId      - The root of the value sub tree
 *          path        - An array of fieldIds, ending with LAST_TOKEN
 *
 * Output:  fieldId     - field id of the element
 *          value       - The value of the element (or string length if any)
 *          isSstring   - whether value string or not
 *
 * Return value: negative value on failure or node id
 **************************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtGetByFieldIds(
    IN  HPVT            valH,
    IN  RvPvtNodeId     nodeId,
    IN  RvInt16*        path,
    OUT RvPstFieldId*   fieldId,
    OUT RvInt32*        value,
    OUT RvBool*         isString);


/************************************************************************
 * pvtBuildByFieldIds
 * purpose: Modifies the value stored in a node. The function first builds
 *          the path to the node, if the path does not exist.
 *          This function works faster than pvtBuildByPath
 * input  : valH    - Value Tree handle
 *          rootId  - The ID of the node from which the search starts from
 *          path    - The path to the searched node. format: {a,b,c,LAST_TOKEN}
 *          value   - Value of the root node, or length of the value if
 *                    value is a string
 *          string  - String value of the node, or NULL if not a string
 *                    The string is allocated and stored in the PVT.
 * output : none
 * return : Last built node ID on success
 *          Negative value on failure
 ************************************************************************/
RVAPI RvPvtNodeId RVCALLCONV
pvtBuildByFieldIds(
    IN  HPVT        valH,
    IN  RvPvtNodeId rootId,
    IN  RvInt16*    path,
    IN  RvInt32     value,
    IN  char*       string);


/* todo: What about these? */
#define pvtGetChild2(hVal,nodeId,fieldId1,fieldId2) \
    pvtGetChild((hVal),(pvtGetChild((hVal),(nodeId),(fieldId1),NULL)),(fieldId2),NULL)

#define pvtGetChildValue pvtGetChildByFieldId
#define pvtGetChildValue2(hVal,nodeId,fieldId1,fieldId2,value,svalue) \
    pvtGet((hVal),pvtGetChild2((hVal),(nodeId),(fieldId1),(fieldId2)),NULL,NULL,(value),(svalue))

#define pvtAddBranch(hVal,nodeId,fieldId) \
    pvtAdd((hVal),(nodeId),(fieldId),0,NULL,NULL)
#define pvtAddBranch2(hVal,nodeId,fieldId1,fieldId2) \
    pvtAddBranch((hVal),(pvtAddBranch((hVal),(nodeId),(fieldId1))),(fieldId2))


/************************************************************************
 * This part is here for debugging purposes only.
 * The function declarations here are not part of the API and might not
 * be supported in future versions.
 * These functions should not be called directly.
 ************************************************************************/
#if (RV_LOGMASK_COMPILEMASK & RV_PVT_LOGDEBUG)
#define pvtAddRoot(hVal,hSyn,value,string)                  pvtAddRootFromInt(hVal,hSyn,RV_PST_INVALID_NODEID,value,(char *)string,__FILE__,__LINE__)
#define pvtAddRootByPath(hVal,hSyn,syntaxPath,value,string) pvtAddRootFromInt(hVal,hSyn,pstGetNodeIdByPath(hSyn,(const char*)syntaxPath),value,string,__FILE__,__LINE__)
RVAPI RvPvtNodeId RVCALLCONV pvtAddRootFromInt(IN HPVT hVal, IN HPST hSyn, IN RvPstNodeId nodePath, IN RvInt32 value, IN const char* string, IN const char* fileName, IN int lineno);
RVAPI void RVCALLCONV pvtPrintRootNodes(IN HPVT hVal, IN RvBool printOnlyRoot, IN void * msa);
#endif


#ifdef __cplusplus
}
#endif

#endif  /* _PVALTREE_H */