Inside Macintosh: Open Transport /

Chapter 4 - Mappers / Mappers Reference

Functions / Looking Up Names

OTLookupName

Finds and returns all addresses that correspond to a particular name or name pattern, or confirms that a name is registered.

C INTERFACE

OSErr OTLookupName (MapperRef ref, TLookupRequest* req, 
                    TLookupReply* reply);

C++ INTERFACES

OSErr TMapper::LookupName (TLookupRequest* req, 
                           TLookupReply* reply);

PARAMETERS

ref

A mapper reference.

req

A TLookupRequest structure (page 4-13) that specifies the name to be looked up as well as some additional values that the mapper provider can use to circumscribe the search.

reply

A TLookupReply structure (page 4-14) that specifies the size and location of a buffer containing the names found, and the number of names found.

DESCRIPTION

You can use the OTLookupName function to find out whether a name is registered and what address is associated with that name. You use the req parameter to supply the information needed for the search: what name should be looked up and, optionally, what node contains that information, how many matches you expect to find, and how long the search should continue before the function returns. On return, the reply parameter contains the names field that points to the buffer where the matching entries are stored and the rspcount field that specifies the number of matching entries.

For each registered name found, the OTLookupName function stores the following information in the buffer referenced by the names field of the reply parameter:

unsigned short addrLen; /* length of address that follows*/
unsigned short nameLen; /* length of name that follows */
unsigned char addr[];   /* address */
unsigned char name[];   /* name, padded to quad-word boundary*/

If you are searching for names using a name pattern and you expect that more than one name will be returned to you, you need to parse the reply buffer to extract the matching names.

If you call the OTLookupName function asynchronously, the mapper provider calls your notifier function passing one of two completion codes for the code parameter (T_LKUPNAMERESULT or T_LKUPNAMECOMPLETE) and passing the reply parameter in the cookie parameter. The mapper provider passes the T_LKUPNAMERESULT code each time it stores a name in the reply buffer, and it passes the T_LKUPNAMECOMPLETE code when it is done. When you receive this event, examine the rspcount field to determine whether there is a last name to retrieve from the reply buffer. The use of both codes is a feature that gives you a choice about how to process multiple names when searching for names matching a pattern.

• If you decide to allocate a buffer that is large enough to contain all the names returned, you can ignore the T_LKUPNAMERESULT code and call a function that parses the buffer once the OTLookupName function has completed--that is, once the provider calls your notifier function using the T_LKUPNAMECOMPLETE event.
• If you want to save memory or if you don't know how large a buffer to allocate, you can use the following method to process the names returned. Each time that the T_LKUPNAMERESULT event is passed, you must do something with the reply from the reply buffer. You can copy it somewhere, or you can delete it if it isn't a name you're interested in. Then, from inside your notifier you must set the reply->names.len field or the reply->rspcount field back to 0 (thus allowing the mapper provider to overwrite the original name). This tells the mapper provider that you are ready to receive another name. Accordingly, when the mapper provider has inserted another name into your reply buffer, it calls your notifier passing the T_LKUPNAMERESULT code, and you can process the new entry as you have processed the first entry. This method also saves you the trouble of having to parse through the buffer to extract name and address information.

The cookie parameter to the notifier contains the reply parameter.

The format of the names and protocol addresses are specific to the underlying protocol. Consult the documentation supplied for your protocol for more information.

COMPLETION EVENT CODES

T_LKUPNAMECOMPLETE

0x2000000F

The OTLookupName function has completed. The cookie parameter of the notifier function points to the reply parameter.

SEE ALSO

You use the OTDeleteName function (page 4-22) or the OTDeleteNameByID function, (page 4-24) to delete a registered name.

A sample program that parses the reply buffer to extract matching names is shown in the section "Searching for Names," beginning on page 4-7.

For information on how to use this function with a TCP/IP protocol, see page 8-20 in the TCP/IP chapter.

Notifier functions are described in the chapter "Providers" in this book.