Host Lookup
[Networking]

Collaboration diagram for Host Lookup:

A set of functions to perform asynchronous host lookups with the help of the I/O Thread. More...


Files
file	hostlookup.c
	Implementation of host lookup functionality.
file	hostlookup.h
	Interface to host lookup functions.
Data Structures
struct	INetAddr_t
	Stores an IPv4 or IPv6 network address. More...
struct	SocketAddr_t
	Stores an IPv4 or IPv6 socket address. More...
Defines
	SocketAddr_t::EqualAddresses(sa1, sa2)
	True if two addresses, sans port, are equal.
#define	EqualAddresses(sa1, sa2)
	True if two addresses, sans port, are equal.
#define	MAX_HOST_LEN 64
	The maximum hostname length supported.
Typedefs
typedef INetAddr_t	INetAddr
typedef SocketAddr_t	SocketAddr
Functions
static void	DoAddrLookup (void *name)
	Performs a lookup for the address of a given hostname on the I/O Thread.
void	DoHostnameLookup (void *)
	An operation for the I/O Thread that attempts to discover the local system's hostname and address.
static void	DoNameLookup (void *address)
	Performs a lookup for the hostname of a given address on the I/O Thread.
int	LookupResult (char name, INetAddr addr)
	Provides the results of a host lookup started by a call to either StartAddrLookup() or StartNameLookup(), or a notice that the operation is in progress.
void	StartAddrLookup (char *name)
	Starts the process of finding the address of a host based on its name.
void	StartNameLookup (SocketAddr addr, char name)
	Starts the process of finding the full hostname of a machine based on its address.
Bool	StartStrNameLookup (char addrstr, char name)
	Starts the process of finding the full hostname of a machine based on its address.
Variables
static struct addrinfo *	addrLookup = NULL
	Stores the results from looking up an address.
static int	conditionCode = 0
	The current condition code used to tell what the lookup code is doing or the result returned by the sockets function used for the lookup.
static INetAddr	hostaddr
	The numeric IP address who's name is sought.
char	localhostAddrStr [INET6_ADDRSTRLEN]
	Stores the address of the local system as a string.
char	localhostName [64]
	Stores the name of the local system.
static char *	lookupName = NULL
	A pointer to where to place the hostname when looking up from an address.
SocketAddr	outgoingAddr
	The socket address of the server that the client is in communication with.

Detailed Description

A set of functions to perform asynchronous host lookups with the help of the I/O Thread.

Only one lookup can be in progress at any given time, and there is no mechanism to queue lookup requests. Generally the results of a lookup can only be retrieved once. These restrictions simply the lookup implementation as well as its public interface. They should not impose problems for most networked games.

The implementation is ment to work with IPv6, but favors IPv4. IPv6 support has not been tested, so this code may fail with IPv6.

Note:: Some platforms, like Windows, do not have an implementation of inet_pton(). A simple implementation is provided for these platforms which uses the older inet_addr() function that does not support IPv6.

Looking up the fully qualified name and address of the local system only works when the system's hostname can be resolved to an address. This usually works on Windows. On Linux, if there is no nameserver with this information, or no such line in /etc/hosts, then the local address will only be resolved to the loopback address. This problem is common on home LANs.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Or visit their website at: http://www.gnu.org/

Author:: Jeff Jackowski

Define Documentation

EqualAddresses	(	sa1,
		sa2		)	`[related, inherited]`

True if two addresses, sans port, are equal.

Parameters:

	sa1	A pointer to a SocketAddr to compare.
	sa2	Another pointer to a SocketAddr to compare.

Author:: Jeff Jackowski

Definition at line 154 of file hostlookup.h.

Referenced by GetSamples(), HandleConnReq(), ValidateClient(), and ValidateServer().

#define EqualAddresses	(	sa1,
		sa2		)	`[related]`

Value:

(((sa1)->addr.sa_family == (sa2)->addr.sa_family) &&               \
    ((((sa2)->addr.sa_family == AF_INET)                               \
    && ((sa2)->ipv4.sin_addr.s_addr == (sa1)->ipv4.sin_addr.s_addr))   \
    || (((sa2)->addr.sa_family == AF_INET6) &&                         \
    IN6_ARE_ADDR_EQUAL(&((sa2)->ipv6.sin6_addr),                       \
    &((sa1)->ipv6.sin6_addr)))))

True if two addresses, sans port, are equal.

Parameters:

	sa1	A pointer to a SocketAddr to compare.
	sa2	Another pointer to a SocketAddr to compare.

Author:: Jeff Jackowski

Definition at line 154 of file hostlookup.h.

#define MAX_HOST_LEN 64

The maximum hostname length supported.

Definition at line 89 of file hostlookup.h.

Referenced by DiscoverConnectServer(), DoHostnameLookup(), DoNameLookup(), and LookupResult().

Typedef Documentation

typedef struct INetAddr_t INetAddr

Definition at line 111 of file hostlookup.h.

typedef struct SocketAddr_t SocketAddr

Definition at line 138 of file hostlookup.h.

Function Documentation

static void DoAddrLookup ( void * name ) [static]

Performs a lookup for the address of a given hostname on the I/O Thread.

For internal use only.

Parameters:

name

A pointer to a character array that holds a NULL-terminated string containing the hostname who's address is sought.

Author:: Jeff Jackowski

Definition at line 87 of file hostlookup.c.

References addrLookup, and conditionCode.

Referenced by DoHostnameLookup(), and StartAddrLookup().

void DoHostnameLookup ( void * )

An operation for the I/O Thread that attempts to discover the local system's hostname and address.

Performs an address lookup of what the system claims to be its name. If the lookup finds a name other than localhost, the new name will be stored in localhostName. Otherwise, the name stored will be the one returned by gethostname(). If the address is not for the loopback interface, a string representation of the address will be stored in localhostAddrStr. Otherwise, the string will have zero length.

Warning:: On Windows, if the local system's IPv6 address is found first, the address string will have zero length.
On Linux (and other UNIX-like syetems?), the address found on many home LANs, and some other LANs, will be the loopback address. To avoid this requires another address listed with the system's name in /etc/hosts, or (maybe?) an entry in a nameserver used by the system.

Author:: Jeff Jackowski

Definition at line 276 of file hostlookup.c.

References addrLookup, conditionCode, DoAddrLookup(), localhostAddrStr, localhostName, and MAX_HOST_LEN.

Referenced by NetInit(), and NetInitSrv().

Here is the call graph for this function:

static void DoNameLookup ( void * address ) [static]

Performs a lookup for the hostname of a given address on the I/O Thread.

For internal use only.

Parameters:

address

An address to lookup, or NULL.

Author:: Jeff Jackowski

Definition at line 109 of file hostlookup.c.

References conditionCode, INetAddr_t::family, hostaddr, INetAddr_t::ipv4, SocketAddr_t::ipv4, INetAddr_t::ipv6, SocketAddr_t::ipv6, SocketAddr_t::length, lookupName, and MAX_HOST_LEN.

Referenced by StartNameLookup(), and StartStrNameLookup().

int LookupResult	(	char *	name,
		INetAddr *	addr
	)

Provides the results of a host lookup started by a call to either StartAddrLookup() or StartNameLookup(), or a notice that the operation is in progress.

After the results are retrived with this function, they will no longer be availble through this interface.

Warning:: Multiple lookup requests are not supported and are not queued.

Parameters:

	name	For name lookups, this is ignored. For address lookups, (StartAddrLookup(), lookup by name) this provides a place to store the fully qualified name. The name pointer must point to an array MAX_HOST_LEN bytes long, or be NULL.
	addr	If non-NULL, the indicated address struct will be filled with the address in network byte order.