- new ptvcursor subtrees management functions :

  * ptvcursor_push_subtree(), ptvcursor_pop_subtree() for pushing/popping
    subtrees. Multiple levels of subtrees (256 max.), allocation per 8 levels.
  * Two new functions creating an item in the tree and pushing a subtree at the
    same time. These two functions accept an undefined length
    (SUBTREE_UNDEFINED_LENGTH). The length of the item is set at the next pop.
        1) ptvcursor_add_with_subtree
	2) ptvcursor_add_text_with_subtree
- get rid of potential memory leaks with g_new in ptvcursor_new().

- Documentation of the new ptvcursor functions in README.developer


svn path=/trunk/; revision=21276

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/README.developer b/doc/README.developer
index b3b025ba4c..bcd06b1b69 100644
--- a/doc/README.developer
+++ b/doc/README.developer
@@ -3395,6 +3395,17 @@ The three steps for a simple protocol are:
     2. Add fields with multiple calls of ptvcursor_add()
     3. Delete the ptvcursor with ptvcursor_free()
 
+ptvcursor offers the possibility to add subtrees in the tree as well. It can be
+done in very simple steps :
+    1. Create a new subtree with ptvcursor_push_subtree(). The old subtree is
+       pushed in a stack and the new subtree will be used by ptvcursor.
+    2. Add fields with multiple calls of ptvcursor_add(). The fields will be
+       added in the new subtree created at the previous step.
+    3. Pop the previous subtree with ptvcursor_pop_subtree(). The previous
+       subtree is again used by ptvcursor.
+Note that at the end of the parsing of a packet you must have popped each
+subtree you pushed. If it's not the case, the dissector will generate an error.
+
 To use the ptvcursor API, include the "ptvcursor.h" file. The PGM dissector
 is an example of how to use it. You don't need to look at it as a guide;
 instead, the API description here should be good enough.
@@ -3429,6 +3440,34 @@ ptvcursor_free(ptvcursor_t*)
     Frees the memory associated with the ptvcursor. You must call this
 after your dissection with the ptvcursor API is completed.
 
+
+proto_tree* 
+ptvcursor_push_subtree(ptvcursor_t *ptvc, proto_item *it, gint ett_subtree)
+    Pushes the current subtree in the tree stack of the cursor, creates a new
+    one and sets this one as the working tree.
+
+void 
+ptvcursor_pop_subtree(ptvcursor_t *ptvc);
+    Pops a subtree in the tree stack of the cursor 
+
+proto_tree* 
+ptvcursor_add_with_subtree(ptvcursor_t * ptvc, int hfindex, gint length,  
+			    gboolean little_endian, gint ett_subtree);
+    Adds an item to the tree and creates a subtree. 
+    If the length is unknown, length may be defined as
+    SUBTREE_UNDEFINED_LENGTH.  In this case, at the next pop, the item length
+    will be equal to the advancement of the cursor since the creation of the
+    subtree.
+
+proto_tree * 
+ptvcursor_add_text_with_subtree(ptvcursor_t * ptvc, gint length, 
+				gint ett_subtree, const char *format, ...);
+    Add a text node to the tree and create a subtree
+    If the length is unknown, length may be defined as
+    SUBTREE_UNDEFINED_LENGTH.  In this case, at the next pop, the item length
+    will be equal to the advancement of the cursor since the creation of the
+    subtree.
+
 2.8.2 Miscellaneous functions.
 
 tvbuff_t*