Inside Macintosh: Open Transport /

Chapter 11 - AppleTalk Service Providers / AppleTalk Service Provider Reference

Functions / Obtaining Information About Zones

OTATalkGetZoneList

Obtains a list of all the zones available on the AppleTalk internet.

C INTERFACE

OSStatus OTATalkGetZoneList(ATSvcRef ref, TNetbuf* zones);

C++ INTERFACE

TAppleTalkServices::GetZoneList(TNetbuf* zones);

PARAMETERS

ref

The reference value of your AppleTalk service provider.

zones

A pointer to a TNetbuf structure that you use to get a list of all the zones on your current AppleTalk internet.

DESCRIPTION

The OTATalkGetZoneList function returns a list of all the zones on the AppleTalk internet to which your network belongs.

If you execute this function asynchronously, Open Transport calls your notifier function with a T_GETZONELISTCOMPLETE completion event to signal the function's completion and uses your notifier's cookie parameter for the list of zones. The cookie parameter actually holds a pointer to a TNetbuf structure, which points to a buffer containing a list of zone names, each of which is a Pascal-style string. Using a Pascal-style string for the zone name is redundant since you can determine the length of the string from the maxlen field of the TNetbuf structure, but the other zone-related calls use Pascal-style strings, so this call also uses them for consistency.

Each string can be up to 32 characters in length, and if you add a length byte, each can have a maximum size of 33 bytes. As AppleTalk internets can have a number of extended networks, you need to allocate a buffer (using the TNetbuf->maxlen field) that holds as much as 64 KB of memory. To keep the buffer size as small and efficient as possible, you can set up a large buffer, test for the kOTBufferOverflowErr error, and then increase the size of the buffer and reissue the call if this error is returned.

COMPLETION EVENT CODES

T_GETZONELISTCOMPLETE

0x23010003

The OTATalkGetZoneList function has completed.

SEE ALSO

To obtain the zone name for the node your process is running on, use the OTATalkGetMyZone function (page 11-16).

To obtain a list of all local zones, use the OTATalkGetLocalZones function (page 11-17).