Inside Macintosh: Open Transport /

Chapter 11 - AppleTalk Service Providers / AppleTalk Service Provider Reference

Functions / Obtaining Information About Zones

OTATalkGetLocalZones

Obtains a list of the zones available on your network.

C INTERFACE

OSStatus OTATalkGetLocalZones(ATSvcRef ref, TNetbuf* zones);

C++ INTERFACE

TAppleTalkServices::GetLocalZones(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 the local zone names.

DESCRIPTION

The OTATalkGetLocalZones function returns a list of the zone names in your application's network if it is an extended network. These are all the zones to which your node can belong. If your application is in a nonextended network, this function returns only one zone name, the same one returned by the OTATalkGetMyZone function.

If you execute this function asynchronously, Open Transport calls your notifier function with a T_GETLOCALZONESCOMPLETE 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 stored as 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 there can be a maximum of 254 zones on an extended network, the maximum size of the buffer is 8382 bytes. Because zone names are often less than 32 characters long and AppleTalk service providers don't pad short names, 6 KB bytes is likely to be a safe value for the buffer's size, defined by the TNetbuf->maxlen field.

COMPLETION EVENT CODES

T_GETLOCALZONESCOMPLETE

0x23010002

The OTATalkGetLocalZones 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 zones on the AppleTalk internet, use the OTATalkGetZoneList function (page 11-18).