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 14 - AppleTalk Service Providers

Using AppleTalk Service Providers
This section explains how you open an AppleTalk service provider and how you use its functions to obtain

the name of the zone for your application's node
the names of the zones in your local network or AppleTalk internet
information about your current AppleTalk environment

You can use AppleTalk service provider functions to get the name of your node's zone. If you are running on a node that belongs to an extended network, you can call an AppleTalk service provider function to get a list of all the zone names associated with that network. For example, the AppleTalk control panel calls the OTATalkGetLocalZones function to provide the user with a list of local zones.
You can also use AppleTalk service provider functions in conjunction with mapper functions (described in the chapter "Mappers". For example, you can use an AppleTalk service provider to look up all the zones on the network, then use the mapper function OTLookUpName to look up the names in each zone.

Creating AppleTalk Service Providers
In order to use the zone and network information functions, you must open an AppleTalk service provider. As with other Open Transport providers, you can open these providers synchronously or asynchronously, and in many ways they behave similarly to endpoint and mapper providers. For example, you open an AppleTalk service provider by calling either the OTOpenAppleTalkServices function or the OTAsyncOpenAppleTalkServices function, both of which return an AppleTalk service provider reference to identify the provider you just opened. You use this reference in AppleTalk service provider functions just as you use an endpoint reference in most endpoint provider functions. If you open more than one AppleTalk service provider, the AppleTalk service provider reference lets you to distinguish one provider from another.
If you open the AppleTalk service provider asynchronously, you need to specify a notifier function that the provider can use to send you completion events and other function-specific information. This notifier API is the same as the one you need to use for asynchronous endpoints.
When you are done using the functions provided by the AppleTalk service provider, you must explicitly close the provider with the generic Open Transport function, OTCloseProvider, to release the memory it uses. The OTCloseProvider function is described in the chapter "Providers".

Working With AppleTalk Zones
The NBP name used in the NBP address format has three parts, one of which is the zone name. A zone is a logical grouping of nodes within an AppleTalk network. You do not specify the zone when you bind an endpoint; you obtain this value from the system.
Note that the functions, OTATalkGetMyZone, OTATalkGetLocalZones, and OTATalkGetZoneList, return data to you using the TNetbuf structure. This means that you have to define your buffer size in the maxlen field of the TNetbuf structure.
An AppleTalk zone name is stored as a Pascal string that contains a maximum of 32 characters. When you add a length byte, you have a string that can have a maximum of 33 bytes. You need to calculate the amount of buffer space you need based on this maximum string size.
The OTATalkGetMyZone function only returns one zone name, so an appropriate buffer size would be 33 bytes. The OTATalkGetLocalZones function, however, returns all the zone names in an extended network, which can hold up to 254 zones, so a maximum buffer size for this function would be 8382 bytes. Because zone names often use less than 32 characters and AppleTalk service providers don't pad short names, 6 KB is likely to be a safe value for this buffer's size.
A much larger buffer would be needed for the OTATalkGetZoneList function, which returns all the zones in all the networks in your AppleTalk internet. You can end up with up to 64 KB of data. To keep the buffer 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.
For more information about using zones in NBP names and addresses, see the chapters "Introduction to AppleTalk" and "AppleTalk Addressing".

Getting the Name of an Application's Zone
You can get the name of your application's zone by calling the OTATalkGetMyZone function. If you call this function asynchronously, the event T_GETMYZONECOMPLETE signals the completion of the function, and your notifier's cookie parameter points to the zone name with the zone parameter.
Listing 14-1 shows the synchronous application-defined DoGetMyZone function, which opens an AppleTalk service provider and calls the OTATalkGetMyZone function. Note that the length of the buffer, a TNetbuf structure, is set to 0. Open Transport adjusts it to the actual length of the zone name when the function returns. Note also that the function adds a NULL character to the zone name. This is optional, but adding the NULL character turns the string into a C string and makes it easier to handle if you have further use for this string.
Another item to note is that the listing uses the recommended configuration string, the constant kDefaultAppleTalkServicesPath. Open Transport recommends using this string, not the kZIPName constant.
Listing 14-1 Using the DoGetMyZone function synchronously
OSStatus DoGetMyZone (char* zoneName)
{
   OSStatus result;
   ATSvcRef svcRef;
   TNetbuf  zoneNetbuf;

   svcRef = OTOpenAppleTalkServices
                  (kDefaultAppleTalkServicesPath, 0, &result);
   if (result == noErr)
   {
      zoneNetbuf.maxlen = 33;
      zoneNetbuf.len = 0;
      zoneNetbuf.buf = zoneName;
      result = OTATalkGetMyZone(svcRef, &zoneNetbuf);
      zoneName[zoneNetBuf.len] = '\0';
      OTCloseProvider(svcRef);
   }
   return result;
}
Getting a List of Zone Names
If you are on an AppleTalk extended network, you can get a list of the names of all the zones in your local network by calling the OTATalkGetLocalZones function. If you are on a nonextended network, your network is all on the same zone, and this function returns the name of the zone, which is the same result as you would get from using the OTATalkGetMyZone function.
If you call the OTATalkGetLocalZones function asynchronously, the event T_GETLOCALZONESCOMPLETE signals the completion of the function, and your notifier's cookie parameter points to a list of zone names with the zones parameter.
If you are on a network that is part of an AppleTalk internet, you can also use the OTATalkGetZoneList function to obtain a list of all the zones in the AppleTalk internet to which your node's network belongs. As with the OTATalkGetLocalZones function, if you call the OTATalkGetZoneList function asynchronously, Open Transport sends your notifier a completion event, in this case the T_GETZONELISTCOMPLETE event, to signal the completion of the function, and your notifier's cookie parameter points to a list of zone names with the zones parameter.
It is your responsibility to allocate a buffer that is large enough to hold the list of zone names returned. See the section "Working With AppleTalk Zones" for more information about buffer sizes.

Getting Information About the Current AppleTalk Environment
You can use the function OTATalkGetInfo to access an AppleTalk information structure (of type AppleTalkInfo) that contains information about the AppleTalk environment for the node on which your application is running. This information can be useful if you are configuring a network or checking that a network has been configured correctly.
If your application's network is extended or nonextended, this function provides your application's network address and the address of a local router. If your application's network is extended, this function also sets a flag indicating that it's an extended network and provides the current network range for the extended network to which your node belongs.
In either case, this function can also set two other flags: one that indicates that there is a router on the same network, and one that indicates that the network only has one zone.
If you call this function synchronously, the AppleTalk service provider uses the info parameter to provide information about your current network environment. If you call this function asynchronously, the event T_GETATALKINFOCOMPLETE signals the completion of the function, and your notifier's cookie parameter points to the AppleTalk environment information with the info parameter.
If the node is multihoming--that is, if multiple network numbers and node numbers are associated with the same node--the OTATalkGetInfo function returns information about the node whose network number and node ID are selected in the AppleTalk control panel.

Subtopics
Creating AppleTalk Service Providers

Working With AppleTalk Zones

Getting the Name of an Application's Zone

Getting a List of Zone Names

Getting Information About the Current AppleTalk Environment