From 1fb551a7ba2abb2de301022bdff7c6d0c7d6be69 Mon Sep 17 00:00:00 2001 From: Jaap Keuter Date: Tue, 20 May 2008 06:28:12 +0000 Subject: Clean up PTV cursor documentation. svn path=/trunk/; revision=25321 --- doc/README.developer | 63 +++++++++++++++++++++++++++------------------------- epan/ptvcursor.h | 37 ++++++++++++++++-------------- 2 files changed, 53 insertions(+), 47 deletions(-) diff --git a/doc/README.developer b/doc/README.developer index c4fca682d9..59b9348b22 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -3530,13 +3530,13 @@ instead, the API description here should be good enough. 2.8.1 ptvcursor API. ptvcursor_t* -ptvcursor_new(proto_tree*, tvbuff_t*, gint offset) +ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset) This creates a new ptvcursor_t object for iterating over a tvbuff. You must call this and use this ptvcursor_t object so you can use the ptvcursor API. proto_item* -ptvcursor_add(ptvcursor_t*, int hf, gint length, gboolean endianness) +ptvcursor_add(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness) This will extract 'length' bytes from the tvbuff and place it in the proto_tree as field 'hf', which is a registered header_field. The pointer to the proto_item that is created is passed back to you. Internally, @@ -3545,60 +3545,63 @@ starts where this call finished. The 'endianness' parameter matters for FT_UINT* and FT_INT* fields. proto_item* -ptvcursor_add_no_advance(ptvcursor_t*, int hf, gint length, gboolean endianness) +ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness) Like ptvcursor_add, but does not advance the internal cursor. void -ptvcursor_advance(ptvcursor_t*, gint length) +ptvcursor_advance(ptvcursor_t* ptvc, gint length) Advances the internal cursor without adding anything to the proto_tree. void -ptvcursor_free(ptvcursor_t*) +ptvcursor_free(ptvcursor_t* ptvc) 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) +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. +one and sets this one as the working tree. void -ptvcursor_pop_subtree(ptvcursor_t *ptvc); +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, +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. +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* -ptvcursor_tvbuff(ptvcursor_t*) - returns the tvbuff associated with the ptvcursor +ptvcursor_tvbuff(ptvcursor_t* ptvc) + Returns the tvbuff associated with the ptvcursor. gint -ptvcursor_current_offset(ptvcursor_t*) - returns the current offset +ptvcursor_current_offset(ptvcursor_t* ptvc) + Returns the current offset. proto_tree* -ptvcursor_tree(ptvcursor_t*) - returns the proto_tree associated with the ptvcursor +ptvcursor_tree(ptvcursor_t* ptvc) + Returns the proto_tree associated with the ptvcursor. void -ptvcursor_set_tree(ptvcursor_t*, proto_tree *) - sets a new proto_tree for the ptvcursor +ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree) + Sets a new proto_tree for the ptvcursor. + +proto_tree* +ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree); + Creates a subtree and adds it to the cursor as the working tree but does +not save the old working tree. diff --git a/epan/ptvcursor.h b/epan/ptvcursor.h index 9080a8b5be..d90d8dd8f9 100644 --- a/epan/ptvcursor.h +++ b/epan/ptvcursor.h @@ -39,20 +39,20 @@ typedef struct ptvcursor ptvcursor_t; /* Allocates an initializes a ptvcursor_t with 3 variables: - * proto_tree, tvbuff, and offset. */ + * proto_tree, tvbuff, and offset. */ ptvcursor_t* -ptvcursor_new(proto_tree*, tvbuff_t*, gint); +ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset); /* Gets data from tvbuff, adds it to proto_tree, increments offset, * and returns proto_item* */ proto_item* -ptvcursor_add(ptvcursor_t*, int hf, gint length, gboolean endianness); +ptvcursor_add(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness); /* Gets data from tvbuff, adds it to proto_tree, *DOES NOT* increment * offset, and returns proto_item* */ proto_item* -ptvcursor_add_no_advance(ptvcursor_t*, int hf, gint length, gboolean endianness); +ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness); /* Advance the ptvcursor's offset within its tvbuff without * adding anything to the proto_tree. */ @@ -61,15 +61,15 @@ ptvcursor_advance(ptvcursor_t* ptvc, gint length); /* Frees memory for ptvcursor_t, but nothing deeper than that. */ void -ptvcursor_free(ptvcursor_t*); +ptvcursor_free(ptvcursor_t* ptvc); /* Returns tvbuff. */ tvbuff_t* -ptvcursor_tvbuff(ptvcursor_t*); +ptvcursor_tvbuff(ptvcursor_t* ptvc); /* Returns current offset. */ gint -ptvcursor_current_offset(ptvcursor_t*); +ptvcursor_current_offset(ptvcursor_t* ptvc); /* Returns the proto_tree* */ proto_tree* @@ -77,34 +77,37 @@ ptvcursor_tree(ptvcursor_t* ptvc); /* Sets a new proto_tree* for the ptvcursor_t */ void -ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree); +ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree* tree); /* push a subtree in the tree stack of the cursor */ -proto_tree* -ptvcursor_push_subtree(ptvcursor_t *ptvc, proto_item *it, gint ett_subtree); +proto_tree* +ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree); /* pop a subtree in the tree stack of the cursor */ -void ptvcursor_pop_subtree(ptvcursor_t *ptvc); +void +ptvcursor_pop_subtree(ptvcursor_t* ptvc); /* Add an item to the tree and create a subtree * If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH. * In this case, when the subtree will be closed, the parent item length will * be equal to the advancement of the cursor since the creation of the subtree. */ -proto_tree* ptvcursor_add_with_subtree(ptvcursor_t * ptvc, int hfindex, gint length, -gboolean little_endian, gint ett_subtree); +proto_tree* +ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, gint length, + gboolean little_endian, gint ett_subtree); /* 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, when the subtree will be closed, 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, ...); +proto_tree* +ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, gint length, + gint ett_subtree, const char* format, ...); /* Creates a subtree and adds it to the cursor as the working tree but does not * save the old working tree */ -proto_tree* -ptvcursor_set_subtree(ptvcursor_t *ptvc, proto_item *it, gint ett_subtree); +proto_tree* +ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree); #endif /* __PTVCURSOR_H__ */ -- cgit v1.2.3