checkAPIs.pl: support for new-style dissectors in check_hf_entries
[metze/wireshark/wip.git] / epan / address.h
1 /* address.h
2  * Definitions for structures storing addresses, and for the type of
3  * variables holding port-type values
4  *
5  * Wireshark - Network traffic analyzer
6  * By Gerald Combs <gerald@wireshark.org>
7  * Copyright 1998 Gerald Combs
8  *
9  * SPDX-License-Identifier: GPL-2.0-or-later
10  */
11
12 #ifndef __ADDRESS_H__
13 #define __ADDRESS_H__
14
15 #include <string.h>     /* for memcmp */
16
17 #include "tvbuff.h"
18 #include "wmem/wmem.h"
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif /* __cplusplus */
23
24 /* Types of "global" addresses Wireshark knows about. */
25 /* Address types can be added here if there are many dissectors that use them or just
26  * within a specific dissector.
27  * If an address type is added here, it must be "registered" within address_types.c
28  * For dissector address types, just use the address_type_dissector_register function
29  * from address_types.h
30  */
31 typedef enum {
32     AT_NONE,               /* no link-layer address */
33     AT_ETHER,              /* MAC (Ethernet, 802.x, FDDI) address */
34     AT_IPv4,               /* IPv4 */
35     AT_IPv6,               /* IPv6 */
36     AT_IPX,                /* IPX */
37     AT_FC,                 /* Fibre Channel */
38     AT_FCWWN,              /* Fibre Channel WWN */
39     AT_STRINGZ,            /* null-terminated string */
40     AT_EUI64,              /* IEEE EUI-64 */
41     AT_IB,                 /* Infiniband GID/LID */
42     AT_AX25,               /* AX.25 */
43     AT_VINES,              /* Banyan Vines address */
44
45     AT_END_OF_LIST         /* Must be last in list */
46 } address_type;
47
48 typedef struct _address {
49     int           type;         /* type of address */
50     int           len;          /* length of address, in bytes */
51     const void   *data;         /* pointer to address data */
52
53     /* private */
54     void         *priv;
55 } address;
56
57 #define ADDRESS_INIT(type, len, data) {type, len, data, NULL}
58 #define ADDRESS_INIT_NONE ADDRESS_INIT(AT_NONE, 0, NULL)
59
60 static inline void
61 clear_address(address *addr)
62 {
63     addr->type = AT_NONE;
64     addr->len  = 0;
65     addr->data = NULL;
66     addr->priv = NULL;
67 }
68
69 /** Initialize an address with the given values.
70  *
71  * @param addr [in,out] The address to initialize.
72  * @param addr_type [in] Address type.
73  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
74  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
75  * @param addr_data [in] Pointer to the address data.
76  */
77 static inline void
78 set_address(address *addr, int addr_type, int addr_len, const void *addr_data) {
79     if (addr_len == 0) {
80         /* Zero length must mean no data */
81         g_assert(addr_data == NULL);
82     } else {
83         /* Must not be AT_NONE - AT_NONE must have no data */
84         g_assert(addr_type != AT_NONE);
85         /* Make sure we *do* have data */
86         g_assert(addr_data != NULL);
87     }
88     addr->type = addr_type;
89     addr->len  = addr_len;
90     addr->data = addr_data;
91     addr->priv = NULL;
92 }
93
94 /** Initialize an address from TVB data.
95  *
96  * Same as set_address but it takes a TVB and an offset. This is preferred
97  * over passing the return value of tvb_get_ptr() to set_address().
98  *
99  * This calls tvb_get_ptr() (including throwing any exceptions) before
100  * modifying the address.
101  *
102  * @param addr [in,out] The address to initialize.
103  * @param addr_type [in] Address type.
104  * @param tvb [in] Pointer to the TVB.
105  * @param offset [in] Offset within the TVB.
106  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
107  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
108  */
109 static inline void
110 set_address_tvb(address *addr, int addr_type, int addr_len, tvbuff_t *tvb, int offset) {
111     const void *p;
112
113     if (addr_len != 0) {
114         /* Must not be AT_NONE - AT_NONE must have no data */
115         g_assert(addr_type != AT_NONE);
116         p = tvb_get_ptr(tvb, offset, addr_len);
117     } else
118         p = NULL;
119     set_address(addr, addr_type, addr_len, p);
120 }
121
122 /** Initialize an address with the given values, allocating a new buffer
123  * for the address data using wmem-scoped memory.
124  *
125  * @param scope [in] The lifetime of the allocated memory, e.g., wmem_packet_scope()
126  * @param addr [in,out] The address to initialize.
127  * @param addr_type [in] Address type.
128  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
129  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
130  * @param addr_data [in] Pointer to the address data.
131  */
132 static inline void
133 alloc_address_wmem(wmem_allocator_t *scope, address *addr,
134                         int addr_type, int addr_len, const void *addr_data) {
135     g_assert(addr);
136     clear_address(addr);
137     addr->type = addr_type;
138     if (addr_len == 0) {
139         /* Zero length must mean no data */
140         g_assert(addr_data == NULL);
141         /* Nothing to copy */
142         return;
143     }
144     /* Must not be AT_NONE - AT_NONE must have no data */
145     g_assert(addr_type != AT_NONE);
146     /* Make sure we *do* have data to copy */
147     g_assert(addr_data != NULL);
148     addr->data = addr->priv = wmem_memdup(scope, addr_data, addr_len);
149     addr->len = addr_len;
150 }
151
152 /** Allocate an address from TVB data.
153  *
154  * Same as alloc_address_wmem but it takes a TVB and an offset.
155  *
156  * @param scope [in] The lifetime of the allocated memory, e.g., wmem_packet_scope()
157  * @param addr [in,out] The address to initialize.
158  * @param addr_type [in] Address type.
159  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
160  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
161  * @param tvb [in] Pointer to the TVB.
162  * @param offset [in] Offset within the TVB.
163  */
164 static inline void
165 alloc_address_tvb(wmem_allocator_t *scope, address *addr,
166                     int addr_type, int addr_len,  tvbuff_t *tvb, int offset) {
167     const void *p;
168
169     p = tvb_get_ptr(tvb, offset, addr_len);
170     alloc_address_wmem(scope, addr, addr_type, addr_len, p);
171 }
172
173 /** Compare two addresses.
174  *
175  * @param addr1 [in] The first address to compare.
176  * @param addr2 [in] The second address to compare.
177  * @return 0 if the addresses are equal,
178  *  A positive number if addr1 > addr2 in some nondefined metric,
179  *  A negative number if addr1 < addr2 in some nondefined metric.
180  */
181 static inline int
182 cmp_address(const address *addr1, const address *addr2) {
183     if (addr1->type > addr2->type) return 1;
184     if (addr1->type < addr2->type) return -1;
185     if (addr1->len  > addr2->len) return 1;
186     if (addr1->len  < addr2->len) return -1;
187     if (addr1->len == 0) {
188         /*
189          * memcmp(NULL, NULL, 0) is *not* guaranteed to work, so
190          * if both addresses are zero-length, don't compare them
191          * (there's nothing to compare, so they're equal).
192          */
193         return 0;
194     }
195     return memcmp(addr1->data, addr2->data, addr1->len);
196 }
197
198 /** Check two addresses for equality.
199  *
200  * Given two addresses, return "true" if they're equal, "false" otherwise.
201  * Addresses are equal only if they have the same type and length; if the
202  * length is zero, they are then equal, otherwise the data must be the
203  * same.
204  *
205  * @param addr1 [in] The first address to compare.
206  * @param addr2 [in] The second address to compare.
207  * @return TRUE if the addresses are equal, FALSE otherwise.
208  */
209 static inline gboolean
210 addresses_equal(const address *addr1, const address *addr2) {
211     /*
212      * memcmp(NULL, NULL, 0) is *not* guaranteed to work, so
213      * if both addresses are zero-length, don't compare them
214      * (there's nothing to compare, so they're equal).
215      */
216     if (addr1->type == addr2->type &&
217         addr1->len == addr2->len &&
218         (addr1->len == 0 ||
219          memcmp(addr1->data, addr2->data, addr1->len) == 0))
220         return TRUE;
221     return FALSE;
222 }
223
224 /** Check the data of two addresses for equality.
225  *
226  * Given two addresses, return "true" if they have the same length and,
227  * their data is equal, "false" otherwise.
228  * The address types are ignored. This can be used to compare custom
229  * address types defined with address_type_dissector_register.
230  *
231  * @param addr1 [in] The first address to compare.
232  * @param addr2 [in] The second address to compare.
233  * @return TRUE if the addresses are equal, FALSE otherwise.
234  */
235 static inline gboolean
236 addresses_data_equal(const address *addr1, const address *addr2) {
237     if ( addr1->len == addr2->len
238             && memcmp(addr1->data, addr2->data, addr1->len) == 0
239             ) return TRUE;
240     return FALSE;
241 }
242
243 /** Perform a shallow copy of the address (both addresses point to the same
244  * memory location).
245  *
246  * @param to [in,out] The destination address.
247  * @param from [in] The source address.
248  *
249  * \warning Make sure 'from' memory stays valid for the lifetime of this object.
250  * Also it's strongly recommended to use this function instead of copy-assign.
251  */
252 static inline void
253 copy_address_shallow(address *to, const address *from) {
254     set_address(to, from->type, from->len, from->data);
255 }
256
257 /** Copy an address, allocating a new buffer for the address data
258  *  using wmem-scoped memory.
259  *
260  * @param scope [in] The lifetime of the allocated memory, e.g., wmem_packet_scope()
261  * @param to [in,out] The destination address.
262  * @param from [in] The source address.
263  */
264 static inline void
265 copy_address_wmem(wmem_allocator_t *scope, address *to, const address *from) {
266     alloc_address_wmem(scope, to, from->type, from->len, from->data);
267 }
268
269 /** Copy an address, allocating a new buffer for the address data.
270  *
271  * @param to [in,out] The destination address.
272  * @param from [in] The source address.
273  */
274 static inline void
275 copy_address(address *to, const address *from) {
276     copy_address_wmem(NULL, to, from);
277 }
278
279 /** Free an address allocated with wmem-scoped memory.
280  *
281  * @param scope [in] The lifetime of the allocated memory, e.g., wmem_packet_scope()
282  * @param addr [in,out] The address whose data to free.
283  */
284 static inline void
285 free_address_wmem(wmem_allocator_t *scope, address *addr) {
286     /* Because many dissectors set 'type = AT_NONE' to mean clear we check for that */
287     if (addr->type != AT_NONE && addr->len > 0 && addr->priv != NULL) {
288         /* Make sure API use is correct */
289         /* if priv is not null then data == priv */
290         g_assert(addr->data == addr->priv);
291         wmem_free(scope, addr->priv);
292     }
293     clear_address(addr);
294 }
295
296 /** Free an address.
297  *
298  * @param addr [in,out] The address whose data to free.
299  */
300 static inline void
301 free_address(address *addr) {
302     free_address_wmem(NULL, addr);
303 }
304
305 /** Hash an address into a hash value (which must already have been set).
306  *
307  * @param hash_val The existing hash value.
308  * @param addr The address to add.
309  * @return The new hash value.
310  */
311 static inline guint
312 add_address_to_hash(guint hash_val, const address *addr) {
313     const guint8 *hash_data = (const guint8 *)(addr)->data;
314     int idx;
315
316     for (idx = 0; idx < (addr)->len; idx++) {
317         hash_val += hash_data[idx];
318         hash_val += ( hash_val << 10 );
319         hash_val ^= ( hash_val >> 6 );
320     }
321     return hash_val;
322 }
323
324 /** Hash an address into a hash value (which must already have been set).
325  *  64-bit version of add_address_to_hash().
326  *
327  * @param hash_val The existing hash value.
328  * @param addr The address to add.
329  * @return The new hash value.
330  */
331 static inline guint64
332 add_address_to_hash64(guint64 hash_val, const address *addr) {
333     const guint8 *hash_data = (const guint8 *)(addr)->data;
334     int idx;
335
336     for (idx = 0; idx < (addr)->len; idx++) {
337         hash_val += hash_data[idx];
338         hash_val += ( hash_val << 10 );
339         hash_val ^= ( hash_val >> 6 );
340     }
341     return hash_val;
342 }
343
344 WS_DLL_PUBLIC guint address_to_bytes(const address *addr, guint8 *buf, guint buf_len);
345
346 /* Types of port numbers Wireshark knows about. */
347 typedef enum {
348     PT_NONE,            /* no port number */
349     PT_SCTP,            /* SCTP */
350     PT_TCP,             /* TCP */
351     PT_UDP,             /* UDP */
352     PT_DCCP,            /* DCCP */
353     PT_IPX,             /* IPX sockets */
354     PT_DDP,             /* DDP AppleTalk connection */
355     PT_IDP,             /* XNS IDP sockets */
356     PT_USB,             /* USB endpoint 0xffff means the host */
357     PT_I2C,
358     PT_IBQP,            /* Infiniband QP number */
359     PT_BLUETOOTH
360 } port_type;
361
362 #ifdef __cplusplus
363 }
364 #endif /* __cplusplus */
365
366 #endif /* __ADDRESS_H__ */
367
368 /*
369  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
370  *
371  * Local variables:
372  * c-basic-offset: 4
373  * tab-width: 8
374  * indent-tabs-mode: nil
375  * End:
376  *
377  * vi: set shiftwidth=4 tabstop=8 expandtab:
378  * :indentSize=4:tabSize=8:noTabs=true:
379  */