Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials: Chapter 13 - AppleTalk Addressing

Using AppleTalk Addressing
This section explains how you use AppleTalk addressing formats to identify an endpoint and how you use various Open Transport AppleTalk functions to

initialize an address
compare two DDP addresses
register the name of your endpoint
look up names and addresses to find a specific applicaiton or user name
manipulate NBP names by using NBP entity structures
initialize NBP entities
set and extract the name, type, or zone parts of an NBP name
unregister an NBP name prior to closing an AppleTalk endpoint

Specifying a DDP Address
The primary address format is the DDP address format, which is the most commonly used. It identifies the network address for your endpoint. Data transmission is fastest for those functions that use this address format because no lookup or conversion is necessary for Open Transport to find the specified location. Functions that use the NBP address format, for example, have to look up the mapping of the NBP name to its address, and this extra step slows down communications.
Functions such as OTBind, OTGetProtAddress, and OTResolveAddress return an address in this format. DDP addresses use the DDP address structure (defined by the DDPAddress data type), which includes the following fields:

Field Meaning
Address type The type of address format, in this case AF_ATALK_DDP.
Network number The endpoint's network.
Node ID The endpoint's node.
Socket number The endpoint's socket.
DDP type A DDP endpoint's type of protocol.

Permissible values for these fields are given in the section "The DDP Address Structure". Since the DDP type field is ignored by all protocols other than DDP, set this field to 0 unless you plan to use the DDP protocol. For more information on DDP types, see the chapter "Datagram Delivery Protocol (DDP)" in this book.
The combination of the network number, the node ID, and the socket number creates a unique identifier for any socket in the AppleTalk internet so that AppleTalk's delivery protocol, DDP, can deliver packets to the correct destination. When you bind an AppleTalk endpoint, you typically specify a network number of 0 and a node ID of 0. This allows the network layer to choose an appropriate address.
In using Open Transport functions to send or receive data, you use a TNetbuf structure to point to a buffer that holds data for a specific Open Transport function. Listing 13-1 shows how you set up the fields of a DDP address and how you set up a TNetbuf structure for it.
Listing 13-1 Setting up a DDP Address
void DoCreateDDPAddress(TNetbuf *theNetBuf, long net, short node, 
                   short socket)
{
   DDPAddress *ddpAddress;

   /* Allocate memory for the DDPAddress structure. */
   ddpAddress = (DDPAddress*) OTAllocMem(sizeof(DDPAddress));

   /* Set up a DDPAddress structure. */
   ddpAddress->fAddressType   = AF_ATALK_DDP;
   ddpAddress->fNetwork       = net;
   ddpAddress->fNode          = node;
   ddpAddress->fSocket        = socket;
   ddpAddress->fDDPType       = 0;
   ddpAddress->fPad           = 0;

   /* Set the TNetbuf to point to it. */
   theNetbuf->len       = sizeof(DDPAddress);
   theNetbuf->maxlen    = sizeof(DDPAddress);
   theNetbuf->buf       = (void*)ddpAddress;
} 
Specifying an NBP Address
You can use the NBP address format to identify an endpoint when you know the user-defined name of an endpoint but not its network address. Applications that run on an Open Transport AppleTalk network can display these user-friendly NBP names to users while using the DDP addresses internally to locate and address entities. See the section "Looking Up Names and Addresses" for more information on how Open Transport translates an NBP name into a network address.
The NBP address format is defined by the NBP address structure, which includes the following fields:

Field Meaning
Address type The type of address format, in this case AF_ATALK_NBP.
NBP name buffer A text string giving the endpoint's NBP name.

The values for these fields are discussed more fully in the section "The NBP Address Structure".
An NBP name consists of these three fields: name, type, and zone. The value for each of these fields is an alphanumeric string of up to 32 characters. The NBP name is not case sensitive. When you bind an endpoint with an NBP address, you must specify a value for the name and type fields, but you don't have to specify the zone. The NBP name string is neither a C nor a Pascal string; its length is determined by the TNetBuf structure in which it's enclosed. It has the form
name:type@zone
The name field typically identifies the name of the entity on the network; for example, the name of a file server or printer. Another example might be the use of the name in personal file sharing, where the name field is used to register the computer name. Clients can use that name to identify the computer they're logging into.
The type field generally identifies the type of service that the entity provides, for example, "Mailbox" for an electronic mailbox on a server. Applications offering similar services can find one another and identify potential partners by looking up only those addresses with a specific type. You could request the mapper provider to return the names of all of the registered entities of a certain type, for example, all file servers or laser printers.
The zone field identifies the zone within the network to which the node belongs. To indicate the current zone (or no zone, as in the case of a simple network configuration not divided into zones), you can leave this field blank (the preferred method) or you can specify an asterisk (*). To Open Transport, these two methods are equivalent; thus, the strings "MyName:MBOX@*" and "MyName:MBOX" identify the same zone. There are several functions for getting zone information; these are described in the chapter "AppleTalk Service Providers" in this book.
You may not use the AppleTalk NBP wildcard characters as part of the NBP name, type, or zone. When you use an NBP structure to define an NBP address format, you copy the string specifying the NBP name into the NBP name buffer.
You can use the backslash (\) character in an NBP name to include the colon (:), at sign (@), and the backslash (\) characters in the name. For example, if you wanted to use the name "My\Machine," the type "My:Server" and the zone "My@Zone," you would express it in the following way:
My\\Machine:My\:Server@My\@Zone
The maximum size of the NBP name buffer is currently defined to be 105 bytes. This permits a string whose name, type, and zone fields each contain the maximum 32 characters, plus 2 bytes for the separator characters (: and @) and 7 bytes for escape characters--that is, combinations of backslash-colon (\:), backslash-at sign (\@), or backslash-backslash (\\).
If you specify an NBP address structure when binding an endpoint, Open Transport assigns a dynamic socket number to the DDP address of the endpoint (because the NBP address cannot supply any socket number) and registers the NBP name you specified for your application.
Listing 13-2 shows how you set up the fields of an NBP address. The statements used to set the size of the len field of the TNetbuf structure simply add the size of the two fields of the NBP address structure: the size of the constant name plus the length of the string equals the length of data stored in the buffer.
Listing 13-2 Setting up an NBP address
void DoCreateNBPAddress(TNetbuf *theNetBuf, char* nbpName)
{
   NBPAddress *nbpAddress;
   short nbpSize;

   /* Allocate memory for an NBP structure. */
   nbpSize = sizeof(OTAddressType) + OTStrLength(nbpName);
   nbpAddress = (NBPAddress*) OTAllocMem(nbpSize);

   /* Set the TNetbuf to point to it. */
   theNetbuf->len       = OTInitNBPAddress(nbpAddress, nbpName);
   theNetbuf->buf       = (void*)nbpAddress;
} 
Specifying a Combined DDP-NBP Address
You use the combined DDP-NBP address format (AF_ATALK_DDPNBP) when you want to bind an endpoint with a specific NBP name to a specific socket. As the name suggests, this format combines the DDP address and the NBP address. Its data structure begins, as do all of the address structures, with a constant defining which address format to use; then it includes all the standard DDP address fields and ends with the standard NBP name buffer field. See the previous two subsections, "Specifying a DDP Address" and "Specifying an NBP Address," and the section "The Combined DDP-NBP Address Structure" for discussion of these fields, and also refer to Inside AppleTalk, second edition.

Specifying and Using a Multinode Address
You use the multinode address format (AF_ATALK_MNODE) for multinode applications that want to bind several multinode endpoints to the same socket using different node IDs for each. The multinode address format is identical to the DDP address format except that you use a different constant to identify it. See the section "Specifying a DDP Address" and the section "The Multinode Address Structure" for discussion of these fields.
The significant fields for the multinode address format are the network number and node ID. DDP ignores the other fields. You can request specific values for the network number and node ID when binding an endpoint, although the address returned by the OTBind function contains the actual network and node values that the endpoint has been bound to.
DDP delivers any packet addressed to the bound multinode address whether or not a specific socket or DDP type is specified for the destination address of the packet. Applications that have opened multinode endpoints must perform their own filtering if the socket or DDP type values are important.

Registering Your Endpoint's Name
In order for you to make the name of your AppleTalk endpoint visible to other applications on a network, you have to register its name. There are two ways to do this. The easiest way is for you to simply use the OTBind function to bind your endpoint with the NBP address format or the combined DDP-NBP address format. If you use the NBP address format, during the binding process Open Tranport registers your endpoint's name and dynamically assigns a physical socket to your endpoint. If you use the combined DDP-NBP address format, you can specify the socket you want to bind the endpoint to. The OTBind function is discussed in the chapter "Endpoints" in this book.
The other way to register an endpoint's name involves several additional steps. You have to first bind your endpoint to a DDP address, open an NBP mapper provider, use the Open Transport name-registration function, OTRegisterName, as a separate step, and then close the NBP mapper provider. You must use this more complex method if you want to register more than one endpoint on the same socket.
In either case, Open Transport uses NBP to associate the endpoint's name with its physical address. Once your endpoint is registered, it is a network-visible entity that other applications can locate.
When you register a name with the OTRegisterName function, the function returns a unique identifier for the registered name. If you later want to delete the name, you can use this identifier to delete it with the OTDeleteNameByID function. This method is sometimes more convenient than the alternative OTDeleteName function. The OTRegisterName, OTDeleteName, and OTDeleteNameByID functions are discussed in the chapter "Endpoints" in this book. Table 13-1 provides a summary of the Open Transport name-registration functions.
Table 13-1 Open Transport name-registration functions
Function Provider   Use
OTBind Endpoint Registers the specified NBP name when you bind with the NBP address or the combined DDP-NBP address formats.
OTRegisterName Mapper Registers the specified name.
OTDeleteName Mapper Removes a name that was previously registered with OTRegisterName.
OTDeleteNameByID   Mapper Given ints identifier, removes a name that was previously registered with OTRegisterName.

Looking Up Names and Addresses
To communicate with an endpoint, Open Transport needs its DDP address. There are endpoint and mapper functions you can use to obtain this address, two of which allow you to specify the endpoint's NBP name. In these instances, Open Transport performs a name lookup that resolves the NBP name into a DDP address that it can use to locate the endpoint you want. Table 13-2 provides a summary of the Open Transport functions that create or return endpoint name and address information.
You can improve performance in certain circumstances if you use the endpoint OTResolveAddress function instead of the mapper OTLookUpName function. Calling OTResolveAddress resolves the name into a DDP address by using information that is maintained in the current node whereas the OTLookUpName function has to go out over the network to look up its information. For example, if you are going to use an NBP address structure repeatedly to specify a remote endpoint in a connectionless or transaction-based service, you can speed up your processing if you first use the OTResolveAddress function to resolve the NBP address into a DDP address and then subsequently use only that DDP address to specify the remote endpoint. Otherwise, an NBP lookup could occur on the network for every packet and slow down communications.
Table 13-2 Open Transport name and address functions
Function Provider   Use
OTGetProtAddress   Endpoint Obtains your endpoint's DDP address. For connection-oriented endpoints that are connected to another endpoint, it also obtains the remote endpoint's DDP address.
OTResolveAddress Endpoint Obtains the DDP address that corresponds to the specified NBP name.
OTLookUpName Mapper Obtains the DDP address for the specified name or a list of addresses for the specified NBP name pattern.
You can also use this function to verify that a specified name is still available on the network and that it is associated with a specified address.
OTATalkGetInfo AppleTalk service    Obtains addressing information about the current environment of an AppleTalk node.

When you call the OTLookUpName function to obtain the DDP address associated with an NBP name, you can specify a name pattern rather than a complete name, by using wildcard operators for the variable parts of the name. Table 13-3 shows the wildcard operators that you can use to specify a name pattern for a name specified as a partial name.
Table 13-3 Wildcard operators

Character Meaning
= All possible values. You can use the equal sign (=) alone in the name or type field.
Any or no characters in this position. You can use the double tilde () to obtain matches for name or type fields. For example, "pal" matches "pal," "paul," and "paper ball." You can use only one double tilde in any string. If you use the double tilde alone, it has the same meaning as the equal sign (=). Press Option-X to type the double tilde character () on a Macintosh keyboard.
* Your local zone. You can leave this blank (preferred method) or use the asterisk (*) to indicate the zone to which this node belongs.

Depending on how you structure the name pattern with wildcards, the OTLookUpName function can return a list of names if more than one name matches the specified pattern. For example, if you want to retrieve the names and addresses of all the applications defined with a given type, such as mailboxes, in the same zone as the one in which your process is running, you can set the name field to the equal sign (=), set the type field to "Mailbox," and leave the zone field blank. The OTLookUpName function returns the NBP names and DDP addresses of all mailboxes in that zone.

Manipulating an NBP Name
If you need to store or manipulate the name, type, or zone part of an NBP name separately, you need to use an NBP entity structure, which is a data structure that Open Transport provides for this purpose. Open Transport also provides several utility functions to transfer data between NBP entities and NBP names.
The NBP entity structure holds an NBP name in the form name:type@zone, with each part containing the maximum 32 characters plus a length byte, for a total possible length of 99 bytes. The NBP entity itself does not contain escape characters, but the NBP entity extraction functions insert a backslash (\) in front of any backslash, colon (:), or at sign (@) they find in an NBP name so that mapper functions can use a correctly formatted NBP name.
You can initialize an NBP entity and then load it with the name, type, and zone of an NBP name individually, by using OTSetNBPName, OTSetNBPType, and OTSetNBPZone functions, or you can load an NBP entity with an entire NBP address at one time with the OTSetNBPEntityFromAddress function. Once you have loaded an NBP entity, you can find out how much buffer space it actually uses for the NBP name it holds with the OTGetNBPEntityLengthAsAddress function. You can then extract each individual NBP name part one at a time by using the OTExtractNBPName, OTExtractNBPType, and OTExtractNBPZone functions, or you can copy the entire NBP entity into an NBP address structure wirhthe OTSetAddressFromNBPEntity function.
When you no longer need a specific NBP name to be associated with an endpoint, you can use the OTDeleteName function or the OTDeleteNameByID function to unregister the name.

Subtopics
Specifying a DDP Address

Specifying an NBP Address

Specifying a Combined DDP-NBP Address

Specifying and Using a Multinode Address

Registering Your Endpoint's Name

Looking Up Names and Addresses

Manipulating an NBP Name

Field	Meaning
Address type	The type of address format, in this case `AF_ATALK_DDP.`
Network number	The endpoint's network.
Node ID	The endpoint's node.
Socket number	The endpoint's socket.
DDP type	A DDP endpoint's type of protocol.

Field	Meaning
Address type	The type of address format, in this case `AF_ATALK_NBP.`
NBP name buffer	A text string giving the endpoint's NBP name.

Function	Provider	Use
`OTBind`	Endpoint	Registers the specified NBP name when you bind with the NBP address or the combined DDP-NBP address formats.
`OTRegisterName`	Mapper	Registers the specified name.
`OTDeleteName`	Mapper	Removes a name that was previously registered with `OTRegisterName`.
`OTDeleteNameByID`	Mapper	Given ints identifier, removes a name that was previously registered with `OTRegisterName`.

Function	Provider	Use
`OTGetProtAddress`	Endpoint	Obtains your endpoint's DDP address. For connection-oriented endpoints that are connected to another endpoint, it also obtains the remote endpoint's DDP address.
`OTResolveAddress`	Endpoint	Obtains the DDP address that corresponds to the specified NBP name.
`OTLookUpName`	Mapper	Obtains the DDP address for the specified name or a list of addresses for the specified NBP name pattern. You can also use this function to verify that a specified name is still available on the network and that it is associated with a specified address.
`OTATalkGetInfo`	AppleTalk service	Obtains addressing information about the current environment of an AppleTalk node.

Character	Meaning
=	All possible values. You can use the equal sign (=) alone in the name or type field.
	Any or no characters in this position. You can use the double tilde () to obtain matches for name or type fields. For example, "pal" matches "pal," "paul," and "paper ball." You can use only one double tilde in any string. If you use the double tilde alone, it has the same meaning as the equal sign (=). Press Option-X to type the double tilde character () on a Macintosh keyboard.
*	Your local zone. You can leave this blank (preferred method) or use the asterisk (*) to indicate the zone to which this node belongs.