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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 #include "ws_symbol_export.h"
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif /* __cplusplus */
  44
  45 #ifndef MAXNAMELEN
  46 #define MAXNAMELEN      64      /* max name length (hostname and port name) */
  47 #endif
  48
  49 typedef struct _e_addr_resolve {
  50   gboolean mac_name;
  51   gboolean network_name;
  52   gboolean transport_name;
  53   gboolean concurrent_dns;
  54   gboolean use_external_net_name_resolver;
  55   gboolean load_hosts_file_from_profile_only;
  56 } e_addr_resolve;
  57
  58
  59 typedef struct hashether {
  60   guint             status;  /* (See above) */
  61   guint8            addr[6];
  62   char              hexaddr[6*3];
  63   char              resolved_name[MAXNAMELEN];
  64 } hashether_t;
  65
  66 typedef struct serv_port {
  67   gchar            *udp_name;
  68   gchar            *tcp_name;
  69   gchar            *sctp_name;
  70   gchar            *dccp_name;
  71 } serv_port_t;
  72
  73 /*
  74  * Flag controlling what names to resolve.
  75  */
  76 WS_DLL_PUBLIC e_addr_resolve gbl_resolv_flags;
  77
  78 /* global variables */
  79
  80 extern gchar *g_ethers_path;
  81 extern gchar *g_ipxnets_path;
  82 extern gchar *g_pethers_path;
  83 extern gchar *g_pipxnets_path;
  84
  85 /* Functions in addr_resolv.c */
  86
  87 /*
  88  * get_udp_port() returns the port name corresponding to that UDP port,
  89  * or the port number as a string if not found.
  90  */
  91 WS_DLL_PUBLIC gchar *get_udp_port(guint port);
  92
  93 /*
  94  * get_tcp_port() returns the port name corresponding to that TCP port,
  95  * or the port number as a string if not found.
  96  */
  97 WS_DLL_PUBLIC gchar *get_tcp_port(guint port);
  98
  99 /*
 100  * get_dccp_port() returns the port name corresponding to that DCCP port,
 101  * or the port number as a string if not found.
 102  */
 103 extern gchar *get_dccp_port(guint port);
 104
 105 /*
 106  * get_sctp_port() returns the port name corresponding to that SCTP port,
 107  * or the port number as a string if not found.
 108  */
 109 WS_DLL_PUBLIC gchar *get_sctp_port(guint port);
 110
 111 /* get_addr_name takes as input an "address", as defined in address.h */
 112 /* it returns a string that contains: */
 113 /*  - if the address is of a type that can be translated into a name, and the user */
 114 /*    has activated name resolution, the translated name */
 115 /*  - if the address is of type AT_NONE, a pointer to the string "NONE" */
 116 /*  - if the address is of any other type, the result of ep_address_to_str on the argument, */
 117 /*    which should be a string representation for the answer -e.g. "10.10.10.10" for IPv4 */
 118 /*    address 10.10.10.10 */
 119
 120 WS_DLL_PUBLIC
 121 const gchar *get_addr_name(const address *addr);
 122 const gchar *se_get_addr_name(const address *addr);
 123
 124 /* get_addr_name_buf solves an address in the same way as get_addr_name above */
 125 /* The difference is that get_addr_name_buf takes as input a buffer, into which it puts */
 126 /* the result which is always NUL ('\0') terminated. The buffer should be large enough to */
 127 /* contain size characters including the terminator */
 128
 129 void get_addr_name_buf(const address *addr, gchar *buf, gsize size);
 130
 131
 132 /*
 133  * Asynchronous host name lookup initialization, processing, and cleanup
 134  */
 135
 136 /* Setup name resolution preferences */
 137 struct pref_module;
 138 extern void addr_resolve_pref_init(struct pref_module *nameres);
 139
 140 /** If we're using c-ares or ADNS, process outstanding host name lookups.
 141  *  This is called from a GLIB timeout in Wireshark and before processing
 142  *  each packet in TShark.
 143  *
 144  * @return True if any new objects have been resolved since the previous
 145  * call. This can be used to trigger a display update, e.g. in Wireshark.
 146  */
 147 WS_DLL_PUBLIC gboolean host_name_lookup_process(void);
 148
 149 /* get_hostname returns the host name or "%d.%d.%d.%d" if not found */
 150 WS_DLL_PUBLIC const gchar *get_hostname(const guint addr);
 151
 152 /* get_hostname6 returns the host name, or numeric addr if not found */
 153 struct e_in6_addr;
 154 WS_DLL_PUBLIC const gchar* get_hostname6(const struct e_in6_addr *ad);
 155
 156 /* get_ether_name returns the logical name if found in ethers files else
 157    "<vendor>_%02x:%02x:%02x" if the vendor code is known else
 158    "%02x:%02x:%02x:%02x:%02x:%02x" */
 159 WS_DLL_PUBLIC gchar *get_ether_name(const guint8 *addr);
 160
 161 /* get_ether_name returns the logical name if found in ethers files else NULL */
 162 gchar *get_ether_name_if_known(const guint8 *addr);
 163
 164 /*
 165  * Given a sequence of 3 octets containing an OID, get_manuf_name()
 166  * returns the vendor name, or "%02x:%02x:%02x" if not known.
 167  */
 168 extern const gchar *get_manuf_name(const guint8 *addr);
 169
 170 /*
 171  * Given a sequence of 3 octets containing an OID, get_manuf_name_if_known()
 172  * returns the vendor name, or NULL if not known.
 173  */
 174 WS_DLL_PUBLIC const gchar *get_manuf_name_if_known(const guint8 *addr);
 175
 176 /*
 177  * Given an integer containing a 24-bit OID, uint_get_manuf_name()
 178  * returns the vendor name, or "%02x:%02x:%02x" if not known.
 179  */
 180 extern const gchar *uint_get_manuf_name(const guint oid);
 181
 182 /*
 183  * Given an integer containing a 24-bit OID, uint_get_manuf_name_if_known()
 184  * returns the vendor name, or NULL if not known.
 185  */
 186 extern const gchar *uint_get_manuf_name_if_known(const guint oid);
 187
 188 /*
 189  * Given a tvbuff and an offset in that tvbuff for a 3-octet OID,
 190  * tvb_get_manuf_name() returns the vendor name, or "%02x:%02x:%02x"
 191  * if not known.
 192  */
 193 WS_DLL_PUBLIC const gchar *tvb_get_manuf_name(tvbuff_t *tvb, gint offset);
 194
 195 /*
 196  * Given a tvbuff and an offset in that tvbuff for a 3-octet OID,
 197  * tvb_get_manuf_name_if_known() returns the vendor name, or NULL
 198  * if not known.
 199  */
 200 WS_DLL_PUBLIC const gchar *tvb_get_manuf_name_if_known(tvbuff_t *tvb, gint offset);
 201
 202 /* get_eui64_name returns "<vendor>_%02x:%02x:%02x:%02x:%02x:%02x" if the vendor code is known
 203    "%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x" */
 204 extern const gchar *get_eui64_name(const guint64 addr);
 205
 206 /* get_eui64_name_if_known returns "<vendor>_%02x:%02x:%02x:%02x:%02x:%02x" if the vendor code is known else NULL */
 207 extern const gchar *get_eui64_name_if_known(const guint64 addr);
 208
 209
 210 /* get_ipxnet_name returns the logical name if found in an ipxnets file,
 211  * or a string formatted with "%X" if not */
 212 extern const gchar *get_ipxnet_name(const guint32 addr);
 213
 214 /* returns the ethernet address corresponding to name or NULL if not known */
 215 extern guint8 *get_ether_addr(const gchar *name);
 216
 217 /* returns the ipx network corresponding to name. If name is unknown,
 218  * 0 is returned and 'known' is set to FALSE. On success, 'known'
 219  * is set to TRUE. */
 220 guint32 get_ipxnet_addr(const gchar *name, gboolean *known);
 221
 222 /* adds a hostname/IPv4 in the hash table */
 223 WS_DLL_PUBLIC void add_ipv4_name(const guint addr, const gchar *name);
 224
 225 /* adds a hostname/IPv6 in the hash table */
 226 WS_DLL_PUBLIC void add_ipv6_name(const struct e_in6_addr *addr, const gchar *name);
 227
 228 /** Add an additional "hosts" file for IPv4 and IPv6 name resolution.
 229  *
 230  * The file can be added before host_name_lookup_init() is called and
 231  * will be re-read each time host_name_lookup_init() is called.
 232  *
 233  * @param hosts_file Absolute path to the hosts file.
 234  *
 235  * @return TRUE if the hosts file can be read.
 236  */
 237 WS_DLL_PUBLIC gboolean add_hosts_file (const char *hosts_file);
 238
 239 /* adds a hostname in the hash table */
 240 WS_DLL_PUBLIC gboolean add_ip_name_from_string (const char *addr, const char *name);
 241
 242 /** Get a list of host name to address mappings we know about.
 243  *
 244  * Each list element is an addrinfo struct with the following fields defined:
 245  *   - ai_family: 0, AF_INET or AF_INET6
 246  *   - ai_addrlen: Length of ai_addr
 247  *   - ai_canonname: Host name or NULL
 248  *   - ai_addr: Pointer to a struct sockaddr or NULL (see below)
 249  *   - ai_next: Next element or NULL
 250  * All other fields are zero-filled.
 251  *
 252  * If ai_family is 0, this is a dummy entry which should only appear at the beginning of the list.
 253  *
 254  * If ai_family is AF_INET, ai_addr points to a struct sockaddr_in with the following fields defined:
 255  *   - sin_family: AF_INET
 256  *   - sin_addr: Host IPv4 address
 257  * All other fields are zero-filled.
 258  *
 259  * If ai_family is AF_INET6, ai_addr points to a struct sockaddr_in6 with the following fields defined:
 260  *   - sin6_family: AF_INET6
 261  *   - sin6_addr: Host IPv6 address
 262  * All other fields are zero-filled.
 263  *
 264  * The list and its elements MUST NOT be modified or freed.
 265  *
 266  * @return The first element in our list of known addresses. May be NULL.
 267  */
 268 WS_DLL_PUBLIC struct addrinfo *get_addrinfo_list(void);
 269
 270 /* add ethernet address / name corresponding to IP address  */
 271 extern void add_ether_byip(const guint ip, const guint8 *eth);
 272
 273 /** Translates a string representing a hostname or dotted-decimal IPv4 address
 274  *  into a numeric IPv4 address value in network byte order. If compiled with
 275  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
 276  *  Otherwise the wait time will be system-dependent, ususally much longer.
 277  *  Immediately returns FALSE for hostnames if network name resolution is
 278  *  disabled.
 279  *
 280  * @param[in] host The hostname.
 281  * @param[out] addrp The numeric IPv4 address in network byte order.
 282  * @return TRUE on success, FALSE on failure, timeout.
 283  */
 284 WS_DLL_PUBLIC
 285 gboolean get_host_ipaddr(const char *host, guint32 *addrp);
 286
 287 /** Translates a string representing a hostname or colon-hex IPv6 address
 288  *  into a numeric IPv6 address value in network byte order. If compiled with
 289  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
 290  *  Otherwise the wait time will be system-dependent, usually much longer.
 291  *  Immediately returns FALSE for hostnames if network name resolution is
 292  *  disabled.
 293  *
 294  * @param[in] host The hostname.
 295  * @param[out] addrp The numeric IPv6 address in network byte order.
 296  * @return TRUE on success, FALSE on failure or timeout.
 297  */
 298 WS_DLL_PUBLIC
 299 gboolean get_host_ipaddr6(const char *host, struct e_in6_addr *addrp);
 300
 301 /*
 302  * Find out whether a hostname resolves to an ip or ipv6 address
 303  * Return "ip6" if it is IPv6, "ip" otherwise (including the case
 304  * that we don't know)
 305  */
 306 WS_DLL_PUBLIC
 307 const char* host_ip_af(const char *host);
 308
 309 WS_DLL_PUBLIC
 310 GHashTable *get_manuf_hashtable(void);
 311
 312 WS_DLL_PUBLIC
 313 GHashTable *get_wka_hashtable(void);
 314
 315 WS_DLL_PUBLIC
 316 GHashTable *get_eth_hashtable(void);
 317
 318 WS_DLL_PUBLIC
 319 GHashTable *get_serv_port_hashtable(void);
 320
 321 /*
 322  * private functions (should only be called by epan directly)
 323  */
 324
 325 WS_DLL_LOCAL
 326 void name_resolver_init(void);
 327
 328 /* (Re)Initialize hostname resolution subsystem */
 329 WS_DLL_LOCAL
 330 void host_name_lookup_init(void);
 331
 332 /* Clean up only hostname resolutions (so they don't "leak" from one
 333  * file to the next).
 334  */
 335 WS_DLL_LOCAL
 336 void host_name_lookup_cleanup(void);
 337
 338 WS_DLL_LOCAL
 339 void addr_resolv_init(void);
 340
 341 WS_DLL_LOCAL
 342 void addr_resolv_cleanup(void);
 343
 344 #ifdef __cplusplus
 345 }
 346 #endif /* __cplusplus */
 347
 348 #endif /* __RESOLV_H__ */