#ifdef __cplusplus
extern "C" {
#endif

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

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.

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


/*
  pvaltree.h

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

  Ron S. 
  27 Oct. 1996
  Revised from valtree.h

  Global behavior: 
  All functions return ERROR upon illegal paramenters or any other error situation.
  Some functions return 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_
#define _PVALTREE_


#include <rvcommon.h>
#include <psyntree.h>


#ifdef _EXAMINE_
#define pvtAddRoot(valH, sinH, value, string)  pvtAddRootFrom((valH), (sinH), (value), (string), (char*) __FILE__, __LINE__)
#define pvtAddRootByPath(valH, sinH, path, value, string)  pvtAddRootByPathFrom((valH), (sinH), (path), (value), (string), (char*) __FILE__, __LINE__)
#endif


DECLARE_OPAQUE(HPVT); /* handler */

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


RVAPI HPVT CALLCONV
pvtConstruct(
	     IN  int stringBufferSize, /* max. bytes for string allocation */
	     IN  int numOfNodes /* max number of nodes in tree */
	     );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtDestruct(
	    IN  HPVT valH
	    );



RVAPI int CALLCONV /* root of tree holding the node. */
pvtGetRoot(
	   IN  HPVT valH,
	   IN  int nodeId
	   );

RVAPI HPST CALLCONV /* associated syntax tree handle  */
pvtGetSynTree(
	      IN  HPVT valH,
	      IN  int nodeId
	      );

RVAPI int CALLCONV /* Number of nodes in value tree forest */
pvtCurSize(HPVT valH);


RVAPI int CALLCONV /* Maximum number of used nodes */
pvtMaxUsage(HPVT valH);


RVAPI int CALLCONV /* reset maxUsage value to 0 */
pvtResetMaxUsage(HPVT valH);


RVAPI int CALLCONV
pvtPoolStatistics(
		  /* Get pool statistics (space is in bytes) */
		  IN  HPVT valH,
		  OUT INT32* poolSize, /* max size of pool */
		  OUT INT32* availableSpace, /* current available space */
		  OUT INT32* maxFreeChunk, /* largest free continous space */
		  OUT INT32* numOfChunks /* number of allocation units in pool */
		  );


RVAPI int CALLCONV /* Number of nodes in tree */
pvtTreeSize(
	    IN  HPVT valH,
	    IN  int parentId
	    );

RVAPI int CALLCONV /* number of childs for parent */
pvtNumChilds(
	     IN  HPVT valH,
	     IN  int parentId
	     );

RVAPI int CALLCONV /* id of parent node of nodeId */
pvtParent(
	  IN  HPVT valH, 
	  IN  int nodeId
	  );

RVAPI int CALLCONV /* next brother id (right) of nodeId */
pvtBrother(
	   IN  HPVT valH,
	   IN  int nodeId
	   );

RVAPI int CALLCONV /* prev brother id (left) of nodeId, or -1 */
pvtLBrother(
	   IN  HPVT valH,
	   IN  int nodeId
	   );

RVAPI int CALLCONV /* child node id or ERROR */
pvtChild(
	 /* return first (leftmost) child node id */
	 IN  HPVT valH,
	 IN  int parentId
	 );

RVAPI int CALLCONV /* node id or ERROR when travel completed */
pvtNext(
	/* return the next node id after location */
	IN  HPVT valH,
	IN  int rootId,
	IN  int location
	);



#ifdef _EXAMINE_

RVAPI int CALLCONV /* new node id or ERROR */
pvtAddRootFrom(
	       /* Add new tree in forest (new message nodeId) */ 
	       IN  HPVT valH,
	       IN  HPST synH,
	       IN  INT32 value, /* if string exists ==> size of string */
	       IN  const char* string, /* NULL if no string */
	       IN  char *fileName,
	       IN  int lineno
	       );


RVAPI int CALLCONV /* new root id or ERROR */
pvtAddRootByPathFrom(
		     /* Add new tree in forest (new message nodeId) */ 
		     IN  HPVT valH,
		     IN  HPST synH,
		     IN  char* syntaxPath, /* path to node from sytax tree root */
		     IN  INT32 value, /* if string exists ==> size of string */
		     IN  char* string, /* NULL if no string */
		     IN  char *fileName,
		     IN  int lineno
		     );
  
#else

RVAPI int CALLCONV /* new node id or ERROR */
pvtAddRoot(
	   /* Add new tree in forest (new message nodeId) */ 
	   IN  HPVT valH,
	   IN  HPST synH,
	   IN  INT32 value, /* if string exists ==> size of string */
	   IN  const char* string /* NULL if no string */
	   );


RVAPI int CALLCONV /* new root id or ERROR */
pvtAddRootByPath(
		 /* Add new tree in forest (new message nodeId) */ 
		 IN  HPVT valH,
		 IN  HPST synH,
		 IN  char* syntaxPath, /* path to node from sytax tree root */
		 IN  INT32 value, /* if string exists ==> size of string */
		 IN  char* string /* NULL if no string */
		 );
#endif



RVAPI int CALLCONV /* new path or ERROR */
pvtAdd(
       /* 
	  Add child node under parentId. 
	  The new node is placed in its relative position according to syntax tree
	  indexing of SEQUENCE fields of structure. 
	  */
       IN  HPVT valH,
       IN  int parentId,
       IN  INTPTR fieldId, /* -1 ==> copy from parent node */
       IN  INT32 value, /* if string exists ==> size of string */
       IN  const char* string, /* NULL if no string. string is allocated and stored in pvt */
       OUT int* index /* index of the new child */
       );


RVAPI int CALLCONV /* TRUE or ERROR */
pvtAddTree(
	   /* Add sub-tree UNDER parent. */
	   IN  HPVT destH,
	   IN  int parentId,
	   IN  HPVT srcH,
	   IN  int rootId /* root of sub-tree to add */
	   );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtAddChilds(
	     /* Add childs of rootId sub-tree UNDER parent. */
	     IN  HPVT destH,
	     IN  int parentId,
	     IN  HPVT srcH,
	     IN  int rootId /* root of sub-tree to add */
	     );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtDelete(
	  /* delete sub-tree */
	  IN  HPVT valH,
	  IN  int subTreeRootId
	  );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtDeleteChilds(
		/* delete all childs of root */
		IN  HPVT valH,
		IN  int subTreeRootId
		);

RVAPI int CALLCONV
pvtDeleteAll(
	     /* delete all nodes in value tree */
	     IN  HPVT valH
	     );


RVAPI int CALLCONV /* TRUE or ERROR */
pvtSetTree(
	   /* Add sub-tree ON parent overwriting parent tree. */
	   IN  HPVT destH,
	   IN  int parentId,
	   IN  HPVT srcH,
	   IN  int rootId /* root of sub-tree to set */
	   );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtMoveTree(
	    /* move sub-tree to another sub-tree */
	    IN  HPVT destH,
	    IN  int destRootId, /* destination root (overwritten) */
	    IN  int srcRootId /* root of sub-tree to move from */
	    );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtShiftTree(
	     /* move sub-tree to another sub-tree and keep src root id */
	     IN  HPVT destH,
	     IN  int destRootId, /* destination root (overwritten) */
	     IN  int srcRootId /* root of sub-tree to move from */
	     );

RVAPI int CALLCONV /* TRUE or ERROR */
pvtAdoptChild(
	     /* Child is adopted by its new family. new brother is a child of new parent. 
		No validity checks. */
	     IN  HPVT valH,
	     IN  int adoptedChildId, /* child to be adopted by the new family */
	     IN  int newParentId, /* parent of adopted child. -1: become root */
	     IN  int newBrotherId /* previously born child (left brother). -1: first born */
	     );

RVAPI int CALLCONV
pvtGet(
       /* get node values */
       IN  HPVT valH,
       IN  int nodeId,
       OUT INTPTR* fieldId, /* Enumeration of field */
       OUT int* synNodeId, /* correlated syntax node */
       OUT INT32* value, /* int value or length of string */
       OUT BOOL* isString /* true if node contains a string (value is its length). 
			    see pvtGetString() */
       ); 

RVAPI INT32 CALLCONV /* real string length or ERROR */
pvtGetString(
	     /* get node string. Ignore if no string available (returns ERROR) */
	     IN  HPVT valH,
	     IN  int nodeId,
	     IN  INT32 stringLength, /* length of string array */
	     OUT char* string /* user allocated memory to hold string */
	     ); 

RVAPI INT32 CALLCONV /* real string length in bits or ERROR */
pvtGetBitString(
	     /* get node string. Ignore if no string available (returns ERROR) */
	     IN  HPVT valH,
	     IN  int nodeId,
	     IN  INT32 stringLength, /* length of string array */
	     OUT char* string /* user allocated memory to hold string */
	     );

RVAPI int CALLCONV
pvtSet(
       /* Set values of existing node (nodeId) */
       IN  HPVT valH,
       IN  int nodeId,
       IN  INTPTR fieldId,
       IN  INT32 value, /* if string exists ==> size of string */
       IN  const char* string /* NULL if no string. string is allocated and stored in pvt */
       );

RVAPI int CALLCONV /* child node id or ERROR */
pvtGetChild(
	    /* get id of child by fieldId */
	    IN  HPVT valH,
	    IN  int parentId,
	    IN  INTPTR fieldId, /* key */
	    OUT int* childNodeId
	    );

RVAPI int CALLCONV /* child node id or ERROR */
pvtGetByIndex(
	      /* get id of child by index */
	      IN  HPVT valH,
	      IN  int parentId,
	      IN  INT32 index, /* of child. >=1 */
	      OUT int* childNodeId
	      );

RVAPI int CALLCONV /* index of node or ERROR */
pvtGetSyntaxIndex(
		  /* get the index of node in parent syntax structure */
		  IN  HPVT valH,
		  IN  int nodeId
		  );

RVAPI int CALLCONV /* TRUE if found, FALSE if not, or ERROR */
pvtSearchPath(
	      /* Search for src path in dest tree.
		 indexing is set to value field on sequence-of nodes in src tree. */
	      IN  HPVT destH,
	      IN  int rootNodeId, /* root of search */
	      IN  HPVT srcH,
	      IN  int srcNodeId, /* beginning of path to search */
	      IN  BOOL checkLeaves /* TRUE: compare leave values, FALSE: do not compare */
	      );

#ifndef NOLOGSUPPORT
RVAPI int CALLCONV
pvtPrint(
	 /* print a tree from parent id */
	 IN  HPVT valH,
	 IN  int parentId,
	 IN  pvtPrintFuncP pFunc, /* print function */
	 IN  int pFuncParam /* parameter for print function */
	 );

RVAPI int CALLCONV
pvtPrintStd(
	 /* print a tree from parent id */
	 IN  HPVT valH,
	 IN  int parentId,
	 IN  int pFuncParam /* parameter for print function */
	 );
#else
#define pvtPrint(a,b,c,d)
#define pvtPrintStd(a,b,c)
#endif
/*---------------------- by path operations ------------------------ */

RVAPI int CALLCONV /* node id or ERROR */
pvtGetNodeIdByPath(
		   /* get node id corresponding to path from the search root node id */
		   IN  HPVT valH,
		   IN  int searchRootNodeId,
		   IN  const char *path  /* from search root. format: "a.b.c" */
		   );

RVAPI int CALLCONV
pvtSetByPath(
	     /*Set node value by its path. The node should already exist. */
	     IN  HPVT valH,
	     IN  int rootId,
	     IN  const char *path,
	     IN  INT32 value,
	     IN  const char* string
	     );

RVAPI int CALLCONV /* last build nodeId or ERROR */
pvtBuildByPath(
	       /*
		 Desc: Set a node in value tree by its path (string).
		 Note: Each node in the path is created if not exist.
		 - Field names in the path should match syntax tree values.
		 - Fields are separated by '.'
		 */
	       IN  HPVT valH,
	       IN  int rootNodeId, /* root node of tree to build */
	       IN  const char *path, /* NULL terminated string. "field.field.field" */
	       IN  INT32 value,  /* length of data if data not NULL */
	       IN  const char* data  /* NULL if no data */
	       );

RVAPI int CALLCONV /* tag of 'relation' child of vNodeId */
pvtGetChildTagByPath(
		     IN  HPVT valH,
		     IN  int nodeId,
		     IN  const char *path, /* from vNodeId */
		     IN  int relation  /* number of descenders from vNodeId */
		     );

RVAPI int CALLCONV /* nodeId or ERROR */
pvtGetByPath(
	     IN  HPVT valH,
	     IN  int nodeId,
	     IN  const char *path,
	     OUT INTPTR* fieldId, /* Enumeration of field */
	     OUT INT32* value,  /* int value or length of string */
	     OUT BOOL* isString /* true if node contains a string (value is its length). 
				   see pvtGetString() */
	     );



#endif
#ifdef __cplusplus
}              
#endif