1berry/wireshark
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up PTV cursor documentation.

Browse Source 
svn path=/trunk/; revision=25321
This commit is contained in:
Jaap Keuter 2008-05-20 06:28:12 +00:00
parent 476fa1e315
commit 1fb551a7ba
2 changed files with 52 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
doc/README.developer
View File

@ -3530,13 +3530,13 @@ instead, the API description here should be good enough.
2.8.1 ptvcursor API. 2.8.1 ptvcursor API.
ptvcursor_t* 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. 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 You must call this and use this ptvcursor_t object so you can use the
ptvcursor API. ptvcursor API.
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)
This will extract 'length' bytes from the tvbuff and place it in 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 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, 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. FT_UINT* and FT_INT* fields.
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)
Like ptvcursor_add, but does not advance the internal cursor. Like ptvcursor_add, but does not advance the internal cursor.
void 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. Advances the internal cursor without adding anything to the proto_tree.
void void
ptvcursor_free(ptvcursor_t*) ptvcursor_free(ptvcursor_t* ptvc)
Frees the memory associated with the ptvcursor. You must call this Frees the memory associated with the ptvcursor. You must call this
after your dissection with the ptvcursor API is completed. after your dissection with the ptvcursor API is completed.
proto_tree* 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 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 void
ptvcursor_pop_subtree(ptvcursor_t *ptvc); ptvcursor_pop_subtree(ptvcursor_t* ptvc);
Pops a subtree in the tree stack of the cursor Pops a subtree in the tree stack of the cursor
proto_tree* 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); gboolean little_endian, gint ett_subtree);
Adds an item to the tree and creates a subtree. Adds an item to the tree and creates a subtree.
If the length is unknown, length may be defined as If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
SUBTREE_UNDEFINED_LENGTH. In this case, at the next pop, the item length In this case, at the next pop, the item length will be equal to the advancement
will be equal to the advancement of the cursor since the creation of the of the cursor since the creation of the subtree.
subtree.
proto_tree * proto_tree*
ptvcursor_add_text_with_subtree(ptvcursor_t * ptvc, gint length, ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, gint length,
gint ett_subtree, const char *format, ...); gint ett_subtree, const char* format, ...);
Add a text node to the tree and create a subtree Add a text node to the tree and create a subtree.
If the length is unknown, length may be defined as If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
SUBTREE_UNDEFINED_LENGTH. In this case, at the next pop, the item length In this case, at the next pop, the item length will be equal to the advancement
will be equal to the advancement of the cursor since the creation of the of the cursor since the creation of the subtree.
subtree.
2.8.2 Miscellaneous functions. 2.8.2 Miscellaneous functions.
tvbuff_t* tvbuff_t*
ptvcursor_tvbuff(ptvcursor_t*) ptvcursor_tvbuff(ptvcursor_t* ptvc)
returns the tvbuff associated with the ptvcursor Returns the tvbuff associated with the ptvcursor.
gint gint
ptvcursor_current_offset(ptvcursor_t*) ptvcursor_current_offset(ptvcursor_t* ptvc)
returns the current offset Returns the current offset.
proto_tree* proto_tree*
ptvcursor_tree(ptvcursor_t*) ptvcursor_tree(ptvcursor_t* ptvc)
returns the proto_tree associated with the ptvcursor Returns the proto_tree associated with the ptvcursor.
void void
ptvcursor_set_tree(ptvcursor_t*, proto_tree *) ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree)
sets a new proto_tree for the ptvcursor 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.

31
epan/ptvcursor.h
View File

@ -41,18 +41,18 @@ typedef struct ptvcursor ptvcursor_t;
/* Allocates an initializes a ptvcursor_t with 3 variables: /* Allocates an initializes a ptvcursor_t with 3 variables:
* proto_tree, tvbuff, and offset. */ * proto_tree, tvbuff, and offset. */
ptvcursor_t* 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, /* Gets data from tvbuff, adds it to proto_tree, increments offset,
* and returns proto_item* */ * and returns proto_item* */
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 /* Gets data from tvbuff, adds it to proto_tree, *DOES NOT* increment
* offset, and returns proto_item* */ * offset, and returns proto_item* */
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 /* Advance the ptvcursor's offset within its tvbuff without
* adding anything to the proto_tree. */ * 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. */ /* Frees memory for ptvcursor_t, but nothing deeper than that. */
void void
ptvcursor_free(ptvcursor_t*); ptvcursor_free(ptvcursor_t* ptvc);
/* Returns tvbuff. */ /* Returns tvbuff. */
tvbuff_t* tvbuff_t*
ptvcursor_tvbuff(ptvcursor_t*); ptvcursor_tvbuff(ptvcursor_t* ptvc);
/* Returns current offset. */ /* Returns current offset. */
gint gint
ptvcursor_current_offset(ptvcursor_t*); ptvcursor_current_offset(ptvcursor_t* ptvc);
/* Returns the proto_tree* */ /* Returns the proto_tree* */
proto_tree* proto_tree*
@ -77,34 +77,37 @@ ptvcursor_tree(ptvcursor_t* ptvc);
/* Sets a new proto_tree* for the ptvcursor_t */ /* Sets a new proto_tree* for the ptvcursor_t */
void 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 */ /* push a subtree in the tree stack of the cursor */
proto_tree* 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);
/* pop a subtree in the tree stack of the cursor */ /* 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 /* Add an item to the tree and create a subtree
* If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH. * 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 * 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. * 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, proto_tree*
gboolean little_endian, gint ett_subtree); 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 /* Add a text node to the tree and create a subtree
* If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH. * 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 * 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. * to the advancement of the cursor since the creation of the subtree.
*/ */
proto_tree * ptvcursor_add_text_with_subtree(ptvcursor_t * ptvc, gint length, proto_tree*
gint ett_subtree, const char *format, ...); 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 /* Creates a subtree and adds it to the cursor as the working tree but does not
* save the old working tree */ * save the old working tree */
proto_tree* proto_tree*
ptvcursor_set_subtree(ptvcursor_t *ptvc, proto_item *it, gint ett_subtree); ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree);
#endif /* __PTVCURSOR_H__ */ #endif /* __PTVCURSOR_H__ */