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 2 - Open Transport Reference

Chapter 24 - Mappers Reference / Functions

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

C INTERFACE
OSStatus OTLookupName(MapperRef ref, 
                     TLookupRequest* req, 
                     TLookupReply* reply);
C++ INTERFACE
OSStatus TMapper::LookupName(TLookupRequest* req, 
                                         TLookupReply* reply);
PARAMETERS

ref
A mapper reference.
req
A TLookupRequest structure 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 that specifies the size and location of a buffer to hold the names found, and returns the number of names found.
function result
An error code. See Appendix B for more information.

DISCUSSION
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 operation completes. On completion, the reply parameter's names field points to the buffer where the matching entries are stored and the rspcount field specifies the number of matching entries.
For each registered name found, the OTLookupName function stores information in the buffer referenced by the names field of the reply parameter. See Figure 6-1 for the format of this information.
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. A sample program that shows the use of mapper function is Listing 6-1 .
If the mapper is in synchronous mode, the function does not return until the operation is complete. If you call the OTLookupName function asynchronously, the mapper provider calls your notifier function passing one of two completion event codes for the code parameter (T_LKUPNAMERESULT or T_LKUPNAMECOMPLETE) and passing the reply parameter in the cookie parameter. The mapper provider sends the T_LKUPNAMERESULT event each time it stores a name in the reply buffer, and it sends the T_LKUPNAMECOMPLETE event 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 operation 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 ignore it if it isn't a name you're interested in. Then, from inside your notifier you set the reply->names.len field or the reply->rspcount field back to 0 (thus allowing the mapper provider to overwrite the original 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. For more information on notifier functions and event codes see "Using Notifier Functions" and "Event Codes".
The cookie parameter to the notifier contains the reply parameter to the OTLookupName function.
The format of the names and protocol addresses are specific to the underlying protocol. Consult the documentation supplied for your protocol for more information.

SEE ALSO
The OTDeleteName function.
The OTDeleteNameByID function.