3.2 The ACE_Addr and ACE_INET_Addr Classes

I l @ ve RuBoard

Motivation

Network addressing is a trouble spot in the Socket API. Socket API network addressing mechanisms use C structures and typecasts , which are tedious and error-prone to program. The address family is the first member of the generic addressing structure, sockaddr . Other address structures, such as sockaddr_in for Internet-domain addresses and sockaddr_un for UNIX-domain addresses, also have an address family member that occupies the same position and size as in the sockaddr struct . Applications use these specific address family structures by

1. Allocating a structure for the desired address family, for example, struct sockaddr_in

2. Filling in the address family member to indicate to the Socket API just what type it really is

3. Supplying addresses, such as IP and port numbers , and

4. Casting the type to sockaddr * to pass to Socket API functions.

Sidebar 4: Displaying ACE Classes and C++ Code

We generally provide a UML diagram and a table that describe the key methods for each ACE C++ class used in this book. Complete C++ class interfaces for ACE are available online at http://ace.ece.uci.edu and http://www.riverace.com. Complete C++ class implementations and networked logging service examples are available in the $ACE_ROOT/ace and $ACE_ROOT/examples/C++NPv1 directories, respectively. We recommend that you keep a copy of the ACE source code handy for quick reference.

To save space in the book, our UML class diagrams focus on attributes and operations that are used in our code examples. Class diagrams don't show an attributes section when none of that class's attributes are directly pertinent to our discussions. If you need a quick UML introduction or refresher, we recommend UML Distilled [wKS00].

To further save space, we use some programming shortcuts that aren't used in ACE; for example:

• We've omitted much of the error-handling code in our C++ examples. Naturally, ACE always checks for error conditions and takes corrective action, just as your applications should.

• Some of our C++ examples implement methods within the class definition. We don't do this in ACE itself, however, since it clutters class interfaces and slows down compilation.

The ACE programming guidelines are located in $ACE_ROOT/docs/ACE-guidelines.html .

To minimize the complexity of all these low-level details, ACE defines a hierarchy of classes that provide a uniform interface for all ACE network addressing objects.

Class Capabilities

The ACE_Addr class is the root of the ACE network addressing hierarchy. The interface of this class is shown in Figure 3.4 and its key methods provide the following capabilities that are common to all the ACE network addressing classes:

Method	Description
operator==()	Compares addresses for equality.
operator!=()	Compares addresses for inequality.
hash()	Computes a hash value for an address.

Figure 3.4. The ACE_Addr and ACE_INET_Addr Class Diagrams

The ACE_Addr class also defines a sap_any static data member that both client and server applications can use as a "wildcard" if they don't care what address they're assigned. For example,

• Client applications can use sap_any to create temporary OS-assigned port numbers, known as "ephemeral ports," which are recycled by the OS after connections are closed.

• Server applications can use sap_any to select their port numbers, as long as they export the assigned numbers to clients via some type of location discovery mechanism, such as a naming or trading service.

Concrete address classes for each IPC mechanism, such as Internet-domain sockets and UNIX-domain sockets, derive from ACE_Addr and add their addressing needs. For example, TCP/IP and UDP/IP addressing information is represented in the ACE_INET_Addr class shown in Figure 3.4. In addition to implementing the ACE_Addr base interface, ACE_INET_Addr provides the following key methods:

Method	Description
ACE_INET_Addr() set()	Initialize an ACE_INET_Addr with hostnames, IP ad dresses, and/or port numbers.
string_to_addr()	Converts a string to an ACE_INET_Addr .
addr_to_string()	Converts an ACE_INET_Addr to a string.
get_port_number()	Returns the port number in host byte order.
get_host_name()	Returns the host name .

The use of the ACE Socket wrapper facades for network addressing avoids common traps and pitfalls that can arise when using the C sockaddr family of data structures. For example, consider the ACE_INET_Addr constructor shown in Figure 3.4. This constructor creates an ACE_INET_ Addr from a port number and host name, thereby eliminating common programming errors by

• Initializing all bytes in the underlying sockaddr_in to 0 and

• Converting the port number and IP address to network byte order

ACE_INET_Addr allows developers to write networked applications without concern for low-level address initialization details. There are many other overloaded constructors and set() methods in ACE _INET_Addr that can be used to initialize Internet-domain network address objects using various combinations of host names, IP addresses, and/or TCP/UDP port names and numbers.

I l @ ve RuBoard