epan/ptvcursor.h

   1 /** @file
   2  *
   3  * Proto Tree TVBuff cursor
   4  * Gilbert Ramirez <gram@alumni.rice.edu>
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 2000 Gerald Combs
   9  *
  10  * SPDX-License-Identifier: GPL-2.0-or-later
  11  */
  12
  13 #ifndef __PTVCURSOR_H__
  14 #define __PTVCURSOR_H__
  15
  16 #include <epan/packet.h>
  17 #include "ws_symbol_export.h"
  18
  19 #define SUBTREE_UNDEFINED_LENGTH -1
  20
  21 typedef struct ptvcursor ptvcursor_t;
  22
  23 /* Allocates an initializes a ptvcursor_t with 3 variables:
  24  * proto_tree, tvbuff, and offset. */
  25 WS_DLL_PUBLIC
  26 ptvcursor_t*
  27 ptvcursor_new(wmem_allocator_t *scope, proto_tree* tree, tvbuff_t* tvb, int offset);
  28
  29 /* Gets data from tvbuff, adds it to proto_tree, increments offset,
  30  * and returns proto_item* */
  31 WS_DLL_PUBLIC
  32 proto_item*
  33 ptvcursor_add(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding);
  34
  35 /* Gets data from tvbuff, adds it to proto_tree, increments offset,
  36  * and returns proto_item* and uint value retrieved*/
  37 WS_DLL_PUBLIC
  38 proto_item*
  39 ptvcursor_add_ret_uint(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, uint32_t *retval);
  40
  41 /* Gets data from tvbuff, adds it to proto_tree, increments offset,
  42  * and returns proto_item* and int value retrieved */
  43 WS_DLL_PUBLIC
  44 proto_item*
  45 ptvcursor_add_ret_int(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, int32_t *retval);
  46
  47 /* Gets data from tvbuff, adds it to proto_tree, increments offset,
  48  * and returns proto_item* and string value retrieved */
  49 WS_DLL_PUBLIC
  50 proto_item*
  51 ptvcursor_add_ret_string(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, wmem_allocator_t *scope, const uint8_t **retval);
  52
  53 /* Gets data from tvbuff, adds it to proto_tree, increments offset,
  54  * and returns proto_item* and boolean value retrieved */
  55 WS_DLL_PUBLIC
  56 proto_item*
  57 ptvcursor_add_ret_boolean(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, bool *retval);
  58
  59 /* Gets data from tvbuff, adds it to proto_tree, *DOES NOT* increment
  60  * offset, and returns proto_item* */
  61 WS_DLL_PUBLIC
  62 proto_item*
  63 ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding);
  64
  65 /* Advance the ptvcursor's offset within its tvbuff without
  66  * adding anything to the proto_tree. */
  67 WS_DLL_PUBLIC
  68 void
  69 ptvcursor_advance(ptvcursor_t* ptvc, int length);
  70
  71 /* Frees memory for ptvcursor_t, but nothing deeper than that. */
  72 WS_DLL_PUBLIC
  73 void
  74 ptvcursor_free(ptvcursor_t* ptvc);
  75
  76 /* Returns tvbuff. */
  77 WS_DLL_PUBLIC
  78 tvbuff_t*
  79 ptvcursor_tvbuff(ptvcursor_t* ptvc);
  80
  81 /* Returns current offset. */
  82 WS_DLL_PUBLIC
  83 int
  84 ptvcursor_current_offset(ptvcursor_t* ptvc);
  85
  86 /* Returns the proto_tree* */
  87 WS_DLL_PUBLIC
  88 proto_tree*
  89 ptvcursor_tree(ptvcursor_t* ptvc);
  90
  91 /* Sets a new proto_tree* for the ptvcursor_t */
  92 WS_DLL_PUBLIC
  93 void
  94 ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree* tree);
  95
  96 /* push a subtree in the tree stack of the cursor */
  97 WS_DLL_PUBLIC
  98 proto_tree*
  99 ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, int ett_subtree);
 100
 101 /* pop a subtree in the tree stack of the cursor */
 102 WS_DLL_PUBLIC
 103 void
 104 ptvcursor_pop_subtree(ptvcursor_t* ptvc);
 105
 106 /* Add an item to the tree and create a subtree
 107  * If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
 108  * In this case, when the subtree will be closed, the parent item length will
 109  * be equal to the advancement of the cursor since the creation of the subtree.
 110  */
 111 WS_DLL_PUBLIC
 112 proto_tree*
 113 ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, int length,
 114     const unsigned encoding, int ett_subtree);
 115
 116 /* Add a text node to the tree and create a subtree
 117  * If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
 118  * In this case, when the subtree will be closed, the item length will be equal
 119  * to the advancement of the cursor since the creation of the subtree.
 120  */
 121 WS_DLL_PUBLIC
 122 proto_tree*
 123 ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, int length,
 124     int ett_subtree, const char* format, ...)
 125     G_GNUC_PRINTF(4, 5);
 126
 127 /* Creates a subtree and adds it to the cursor as the working tree but does not
 128  * save the old working tree */
 129 WS_DLL_PUBLIC
 130 proto_tree*
 131 ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, int ett_subtree);
 132
 133 #endif /* __PTVCURSOR_H__ */