From Harald Welte:
[obnox/wireshark/wip.git] / epan / addr_resolv.h
1 /* addr_resolv.h
2  * Definitions for network object lookup
3  *
4  * $Id$
5  *
6  * Laurent Deniel <laurent.deniel@free.fr>
7  *
8  * Wireshark - Network traffic analyzer
9  * By Gerald Combs <gerald@wireshark.org>
10  * Copyright 1998 Gerald Combs
11  *
12  * This program is free software; you can redistribute it and/or
13  * modify it under the terms of the GNU General Public License
14  * as published by the Free Software Foundation; either version 2
15  * of the License, or (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program; if not, write to the Free Software
24  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
25  */
26 /* The buffers returned by these functions are all allocated with a
27  * packet lifetime and does not have have to be freed.
28  * However, take into account that when the packet dissection
29  * completes, these buffers will be automatically reclaimed/freed.
30  * If you need the buffer to remain for a longer scope than packet lifetime
31  * you must copy the content to an se_alloc() buffer.
32  */
33
34 #ifndef __RESOLV_H__
35 #define __RESOLV_H__
36
37 #include <epan/address.h>
38 #include <epan/tvbuff.h>
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif /* __cplusplus */
43
44 #ifndef MAXNAMELEN
45 #define MAXNAMELEN      64      /* max name length (hostname and port name) */
46 #endif
47
48 /*
49  * Flag controlling what names to resolve.
50  */
51 WS_VAR_IMPORT guint32 gbl_resolv_flags;
52
53 /* 32 types are sufficient (as are 640k of RAM) */
54 /* FIXME: Maybe MANUF/m, IP/i, IP6/6, IPX/x, UDP+TCP/t etc would be
55    more useful/consistent */
56 #define RESOLV_NONE             0x0
57 #define RESOLV_MAC              0x1
58 #define RESOLV_NETWORK          0x2
59 #define RESOLV_TRANSPORT        0x4
60 #define RESOLV_CONCURRENT       0x8
61
62 #define RESOLV_ALL_ADDRS        (RESOLV_MAC|RESOLV_NETWORK|RESOLV_TRANSPORT)
63 #define RESOLV_ALL              0xFFFFFFFF
64
65 /* global variables */
66
67 extern gchar *g_ethers_path;
68 extern gchar *g_ipxnets_path;
69 extern gchar *g_pethers_path;
70 extern gchar *g_pipxnets_path;
71
72 /* Functions in resolv.c */
73
74 /* Set the flags controlling what names to resolve */
75 extern void resolv_set_flags(guint32 flags);
76
77 /*
78  * get_udp_port() returns the port name corresponding to that UDP port,
79  * or the port number as a string if not found.
80  */
81 extern gchar *get_udp_port(guint port);
82
83 /*
84  * get_tcp_port() returns the port name corresponding to that TCP port,
85  * or the port number as a string if not found.
86  */
87 extern gchar *get_tcp_port(guint port);
88
89 /*
90  * get_dccp_port() returns the port name corresponding to that DCCP port,
91  * or the port number as a string if not found.
92  */
93 extern gchar *get_dccp_port(guint port);
94
95 /*
96  * get_sctp_port() returns the port name corresponding to that SCTP port,
97  * or the port number as a string if not found.
98  */
99 extern gchar *get_sctp_port(guint port);
100
101 /* get_addr_name takes as input an "address", as defined in address.h */
102 /* it returns a string that contains: */
103 /*  - if the address is of a type that can be translated into a name, and the user */
104 /*    has activated name resolution, the translated name */
105 /*  - if the address is of type AT_NONE, a pointer to the string "NONE" */
106 /*  - if the address is of any other type, the result of ep_address_to_str on the argument, */
107 /*    which should be a string representation for the answer -e.g. "10.10.10.10" for IPv4 */
108 /*    address 10.10.10.10 */
109
110 const gchar *get_addr_name(const address *addr);
111 const gchar *se_get_addr_name(const address *addr);
112
113 /* get_addr_name_buf solves an address in the same way as get_addr_name above */
114 /* The difference is that get_addr_name_buf takes as input a buffer, into which it puts */
115 /* the result which is always NUL ('\0') terminated. The buffer should be large enough to */
116 /* contain size characters including the terminator */
117
118 void get_addr_name_buf(const address *addr, gchar *buf, gsize size);
119
120
121 /*
122  * Asynchronous host name lookup initialization, processing, and cleanup
123  */
124
125 /* host_name_lookup_init fires up an ADNS socket if we're using ADNS */
126 extern void host_name_lookup_init(void);
127
128 /** If we're using c-ares or ADNS, process outstanding host name lookups.
129  *  This is called from a GLIB timeout in Wireshark and before processing
130  *  each packet in TShark.
131  *
132  * @param data Ignored.
133  * @return True if any new objects have been resolved since the previous
134  * call. This can be used to trigger a display update, e.g. in Wireshark.
135  */
136 extern gboolean host_name_lookup_process(gpointer data);
137
138 /* host_name_lookup_cleanup cleans up an ADNS socket if we're using ADNS */
139 extern void host_name_lookup_cleanup(void);
140
141 /* get_hostname returns the host name or "%d.%d.%d.%d" if not found */
142 extern const gchar *get_hostname(const guint addr);
143
144 /* get_hostname6 returns the host name, or numeric addr if not found */
145 struct e_in6_addr;
146 extern const gchar* get_hostname6(const struct e_in6_addr *ad);
147
148 /* get_ether_name returns the logical name if found in ethers files else
149    "<vendor>_%02x:%02x:%02x" if the vendor code is known else
150    "%02x:%02x:%02x:%02x:%02x:%02x" */
151 extern gchar *get_ether_name(const guint8 *addr);
152
153 /* get_ether_name returns the logical name if found in ethers files else NULL */
154 extern gchar *get_ether_name_if_known(const guint8 *addr);
155
156 /* get_manuf_name returns the vendor name or "%02x:%02x:%02x" if not known */
157 extern const gchar *get_manuf_name(const guint8 *addr);
158
159 /* get_manuf_name returns the vendor name or NULL if not known */
160 extern const gchar *get_manuf_name_if_known(const guint8 *addr);
161
162 /* get_manuf_name directly from a TVB; returns the vendor name or "%02x:%02x:%02x" if not known */
163 extern const gchar *tvb_get_manuf_name(tvbuff_t *tvb, gint offset);
164
165 /* get_manuf_name returns the vendor name or NULL if not known */
166 extern const gchar *tvb_get_manuf_name_if_known(tvbuff_t *tvb, gint offset);
167
168 /* get_eui64_name returns "<vendor>_%02x:%02x:%02x:%02x:%02x:%02x" if the vendor code is known
169    "%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x" */
170 extern const gchar *get_eui64_name(const guint64 addr);
171
172 /* get_eui64_name_if_known returns "<vendor>_%02x:%02x:%02x:%02x:%02x:%02x" if the vendor code is known else NULL */
173 extern const gchar *get_eui64_name_if_known(const guint64 addr);
174
175
176 /* get_ipxnet_name returns the logical name if found in an ipxnets file,
177  * or a string formatted with "%X" if not */
178 extern const gchar *get_ipxnet_name(const guint32 addr);
179
180 /* returns the ethernet address corresponding to name or NULL if not known */
181 extern guint8 *get_ether_addr(const gchar *name);
182
183 /* returns the ipx network corresponding to name. If name is unknown,
184  * 0 is returned and 'known' is set to FALSE. On success, 'known'
185  * is set to TRUE. */
186 guint32 get_ipxnet_addr(const gchar *name, gboolean *known);
187
188 /* adds a hostname/IPv4 in the hash table */
189 extern void add_ipv4_name(const guint addr, const gchar *name);
190
191 /* adds a hostname/IPv6 in the hash table */
192 extern void add_ipv6_name(const struct e_in6_addr *addr, const gchar *name);
193
194 /* read a "hosts" file and add its entries to the IPv4 & IPv6 hash tables */
195 extern gboolean read_hosts_file (const char *hostspath);
196
197 /* adds a hostname in the hash table */
198 extern gboolean add_ip_name_from_string (const char *addr, const char *name);
199
200 /** Get a list of host name to address mappings we know about.
201  *
202  * Each list element is an addrinfo struct with the following fields defined:
203  *   - ai_family: 0, AF_INET or AF_INET6
204  *   - ai_addrlen: Length of ai_addr
205  *   - ai_canonname: Host name or NULL
206  *   - ai_addr: Pointer to a struct sockaddr or NULL (see below)
207  *   - ai_next: Next element or NULL
208  * All other fields are zero-filled.
209  *
210  * If ai_family is 0, this is a dummy entry which should only appear at the beginning of the list.
211  *
212  * If ai_family is AF_INET, ai_addr points to a struct sockaddr_in with the following fields defined:
213  *   - sin_family: AF_INET
214  *   - sin_addr: Host IPv4 address
215  * All other fields are zero-filled.
216  *
217  * If ai_family is AF_INET6, ai_addr points to a struct sockaddr_in6 with the following fields defined:
218  *   - sin6_family: AF_INET6
219  *   - sin6_addr: Host IPv6 address
220  * All other fields are zero-filled.
221  *
222  * The list and its elements MUST NOT be modified or freed.
223  *
224  * @return The first element in our list of known addresses. May be NULL.
225  */
226 extern struct addrinfo *get_addrinfo_list(void);
227
228 /* add ethernet address / name corresponding to IP address  */
229 extern void add_ether_byip(const guint ip, const guint8 *eth);
230
231 /** Translates a string representing a hostname or dotted-decimal IPv4 address
232  *  into a numeric IPv4 address value in network byte order. If compiled with
233  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
234  *  Otherwise the wait time will be system-dependent, ususally much longer.
235  *  Immediately returns FALSE for hostnames if network name resolution is
236  *  disabled.
237  *
238  * @param[in] host The hostname.
239  * @param[out] addrp The numeric IPv4 address in network byte order.
240  * @return TRUE on success, FALSE on failure, timeout.
241  */
242 gboolean get_host_ipaddr(const char *host, guint32 *addrp);
243
244 /** Translates a string representing a hostname or colon-hex IPv6 address
245  *  into a numeric IPv6 address value in network byte order. If compiled with
246  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
247  *  Otherwise the wait time will be system-dependent, usually much longer.
248  *  Immediately returns FALSE for hostnames if network name resolution is
249  *  disabled.
250  *
251  * @param[in] host The hostname.
252  * @param[out] addrp The numeric IPv6 address in network byte order.
253  * @return TRUE on success, FALSE on failure or timeout.
254  */
255 gboolean get_host_ipaddr6(const char *host, struct e_in6_addr *addrp);
256
257 /*
258  * Find out whether a hostname resolves to an ip or ipv6 address
259  * Return "ip6" if it is IPv6, "ip" otherwise (including the case
260  * that we don't know)
261  */
262 const char* host_ip_af(const char *host);
263
264 #ifdef __cplusplus
265 }
266 #endif /* __cplusplus */
267
268 #endif /* __RESOLV_H__ */