checkAPIs.pl: support for new-style dissectors in check_hf_entries
[metze/wireshark/wip.git] / epan / to_str.h
1 /* to_str.h
2  * Definitions for utilities to convert various other types to strings.
3  *
4  * Wireshark - Network traffic analyzer
5  * By Gerald Combs <gerald@wireshark.org>
6  * Copyright 1998 Gerald Combs
7  *
8  * SPDX-License-Identifier: GPL-2.0-or-later
9  */
10
11 #ifndef __TO_STR_H__
12 #define __TO_STR_H__
13
14 #include <glib.h>
15
16 #include "wsutil/nstime.h"
17 #include <wsutil/inet_addr.h>
18 #include "time_fmt.h"
19 #include <epan/packet_info.h>
20 #include <epan/ipv6.h>
21 #include "ws_symbol_export.h"
22 #include "wmem/wmem.h"
23
24 #define GUID_STR_LEN     37
25 #define MAX_ADDR_STR_LEN 256
26 #define VINES_ADDR_LEN   6
27 #define EUI64_STR_LEN    24
28 #define AX25_ADDR_LEN    7
29 #define FCWWN_ADDR_LEN   8
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif /* __cplusplus */
34
35 /*
36  * These are utility functions which convert various types to strings,
37  * but for which no more specific module applies.
38  */
39
40 WS_DLL_PUBLIC gchar* address_to_str(wmem_allocator_t *scope, const address *addr);
41 WS_DLL_PUBLIC gchar* address_with_resolution_to_str(wmem_allocator_t *scope, const address *addr);
42 WS_DLL_PUBLIC gchar* tvb_address_with_resolution_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, int type, const gint offset);
43
44 /*
45  * address_to_name takes as input an "address", as defined in address.h.
46  *
47  * If the address is of a type that can be translated into a name, and the
48  * user has activated name resolution, and the name can be resolved, it
49  * returns a string containing the translated name.
50  *
51  * Otherwise, it returns NULL.
52  */
53 WS_DLL_PUBLIC const gchar *address_to_name(const address *addr);
54
55 /*
56  * address_to_display takes as input an "address", as defined in address.h .
57  *
58  * If the address is of a type that can be translated into a name, and the
59  * user has activated name resolution, and the name can be resolved, it
60  * returns a string containing the translated name.
61  *
62  * Otherwise, if the address is of type AT_NONE, it returns "NONE".
63  *
64  * Otherwise, it returns a string containing the result of address_to_str
65  * on the argument, which should be a string representation for the address,
66  * e.g. "10.10.10.10" for IPv4 address 10.10.10.10.
67  */
68 WS_DLL_PUBLIC
69 gchar *address_to_display(wmem_allocator_t *allocator, const address *addr);
70
71 WS_DLL_PUBLIC void     address_to_str_buf(const address *addr, gchar *buf, int buf_len);
72
73 #define tvb_ether_to_str(tvb, offset) tvb_address_to_str(wmem_packet_scope(), tvb, AT_ETHER, offset)
74 #define tvb_ip_to_str(tvb, offset) tvb_address_to_str(wmem_packet_scope(), tvb, AT_IPv4, offset)
75 #define tvb_ip6_to_str(tvb, offset) tvb_address_to_str(wmem_packet_scope(), tvb, AT_IPv6, offset)
76 #define tvb_fcwwn_to_str(tvb, offset) tvb_address_to_str(wmem_packet_scope(), tvb, AT_FCWWN, offset)
77 #define tvb_fc_to_str(tvb, offset) tvb_address_to_str(wmem_packet_scope(), tvb, AT_FC, offset)
78 #define tvb_eui64_to_str(tvb, offset) tvb_address_to_str(wmem_packet_scope(), tvb, AT_EUI64, offset)
79
80 void    ip_to_str_buf(const guint8 *ad, gchar *buf, const int buf_len);
81
82 /* Returns length of the result. */
83 int ip6_to_str_buf(const ws_in6_addr *ad, gchar *buf, int buf_size);
84
85 /* Returns length of the result. Takes a prefix to be inserted before the address. */
86 int ip6_to_str_buf_with_pfx(const ws_in6_addr *ad, gchar *buf, int buf_size, const char *prefix);
87
88 extern gchar*   ipxnet_to_str_punct(wmem_allocator_t *scope, const guint32 ad, const char punct);
89 WS_DLL_PUBLIC gchar*    eui64_to_str(wmem_allocator_t *scope, const guint64 ad);
90
91 WS_DLL_PUBLIC gchar*    abs_time_to_str(wmem_allocator_t *scope, const nstime_t*, const absolute_time_display_e fmt,
92     gboolean show_zone);
93 WS_DLL_PUBLIC gchar*    abs_time_secs_to_str(wmem_allocator_t *scope, const time_t, const absolute_time_display_e fmt,
94     gboolean show_zone);
95 WS_DLL_PUBLIC void      display_epoch_time(gchar *, int, const time_t,  gint32, const to_str_time_res_t);
96
97 WS_DLL_PUBLIC void      display_signed_time(gchar *, int, const gint32, gint32, const to_str_time_res_t);
98
99 WS_DLL_PUBLIC gchar*    signed_time_secs_to_str(wmem_allocator_t *scope, const gint32 time_val);
100 WS_DLL_PUBLIC gchar*    unsigned_time_secs_to_str(wmem_allocator_t *scope, const guint32);
101 WS_DLL_PUBLIC gchar*    signed_time_msecs_to_str(wmem_allocator_t *scope, gint32 time_val);
102
103 WS_DLL_PUBLIC void guint32_to_str_buf(guint32 u, gchar *buf, int buf_len);
104 WS_DLL_PUBLIC void guint64_to_str_buf(guint64 u, gchar *buf, int buf_len);
105
106 WS_DLL_PUBLIC gchar*    rel_time_to_str(wmem_allocator_t *scope, const nstime_t*);
107 WS_DLL_PUBLIC gchar*    rel_time_to_secs_str(wmem_allocator_t *scope, const nstime_t*);
108 WS_DLL_PUBLIC gchar*    guid_to_str(wmem_allocator_t *scope, const e_guid_t*);
109 gchar*  guid_to_str_buf(const e_guid_t*, gchar*, int);
110
111 WS_DLL_PUBLIC char *decode_bits_in_field(const guint bit_offset, const gint no_of_bits, const guint64 value);
112
113 WS_DLL_PUBLIC const gchar* port_type_to_str (port_type type);
114
115 /** Turn an address type retrieved from a tvb into a string.
116  *
117  * @param scope memory allocation scheme used
118  * @param tvb tvbuff to retrieve address
119  * @param type address type to retrieve
120  * @param offset offset into tvb to retrieve address
121  * @return A pointer to the formatted string
122  *
123  */
124 WS_DLL_PUBLIC gchar* tvb_address_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, int type, const gint offset);
125
126 /** Turn an address type retrieved from a tvb into a string.
127  *
128  * @param scope memory allocation scheme used
129  * @param tvb tvbuff to retrieve address
130  * @param type address type to retrieve
131  * @param offset offset into tvb to retrieve address
132  * @param length The length of the string
133  * @return A pointer to the formatted string
134  *
135  */
136 WS_DLL_PUBLIC gchar* tvb_address_var_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, address_type type, const gint offset, int length);
137
138 /**
139  * guint8_to_hex()
140  *
141  * Output guint8 hex represetation to 'out', and return pointer after last character (out + 4).
142  * It always output full representation (padded with 0).
143  *
144  * String is not NUL terminated by this routine.
145  * There needs to be at least 2 bytes in the buffer.
146  */
147 WS_DLL_PUBLIC char *guint8_to_hex(char *out, guint8 val);
148
149 /**
150  * word_to_hex()
151  *
152  * Output guint16 hex represetation to 'out', and return pointer after last character (out + 4).
153  * It always output full representation (padded with 0).
154  *
155  * String is not NUL terminated by this routine.
156  * There needs to be at least 4 bytes in the buffer.
157  */
158 WS_DLL_PUBLIC char *word_to_hex(char *out, guint16 word);
159
160 /**
161  * dword_to_hex()
162  *
163  * Output guint32 hex represetation to 'out', and return pointer after last character.
164  * It always output full representation (padded with 0).
165  *
166  * String is not NUL terminated by this routine.
167  * There needs to be at least 8 bytes in the buffer.
168  */
169 WS_DLL_PUBLIC char *dword_to_hex(char *out, guint32 dword);
170
171 /** Turn an array of bytes into a string showing the bytes in hex.
172  *
173  * @param scope memory allocation scheme used
174  * @param bd A pointer to the byte array
175  * @param bd_len The length of the byte array
176  * @return A pointer to the formatted string
177  */
178 WS_DLL_PUBLIC char *bytes_to_str(wmem_allocator_t *scope, const guint8 *bd, int bd_len);
179
180 /** Turn an array of bytes into a string showing the bytes in hex,
181  *  separated by a punctuation character.
182  *
183  * @param scope memory allocation scheme used
184  * @param ad A pointer to the byte array
185  * @param len The length of the byte array
186  * @param punct The punctuation character
187  * @return A pointer to the formatted string
188  *
189  * @see bytes_to_str()
190  */
191 WS_DLL_PUBLIC gchar *bytestring_to_str(wmem_allocator_t *scope, const guint8 *ad, const guint32 len, const char punct);
192
193 /**
194  * bytes_to_hexstr()
195  *
196  * Output hex represetation of guint8 ad array, and return pointer after last character.
197  * It always output full representation (padded with 0).
198  *
199  * String is not NUL terminated by this routine.
200  * There needs to be at least len * 2 bytes in the buffer.
201  */
202 WS_DLL_PUBLIC char *bytes_to_hexstr(char *out, const guint8 *ad, guint32 len);
203
204 /**
205  * uint_to_str_back()
206  *
207  * Output guint32 decimal representation backward (last character will be written on ptr - 1),
208  * and return pointer to first character.
209  *
210  * String is not NUL terminated by this routine.
211  * There needs to be at least 10 bytes in the buffer.
212  */
213 WS_DLL_PUBLIC char *uint_to_str_back(char *ptr, guint32 value);
214
215 #ifdef __cplusplus
216 }
217 #endif /* __cplusplus */
218
219 #endif /* __TO_STR_H__  */