Legacy Document

Inside Macintosh: Networking /

Chapter 4 - Zone Information Protocol (ZIP) / Using ZIP

Getting a List of Zone Names for Your Local Network
or Its Internet

If your application is running on a node that belongs to an extended network, the application can use the GetLocalZones function to obtain a list of the names of the zones in its node's local network. An application running on a node that belongs to an extended network can also use the GetZoneList function to obtain a list of the names of the zones throughout the AppleTalk internet to which its node's local network belongs. These functions behave similarly.

ZIP returns a single ATP response per request. Because the complete list of zone
names may not fit in a single ATP response, you need to make repeated calls to either GetLocalZones or GetZoneList until you receive all of the zone names. You must allocate a buffer to hold the zone names data that the ZIP function returns and point
to that buffer from the function's zipBuffPtr parameter block field. This buffer must be 578 bytes in size, large enough to hold an entire ATP response. ZIP returns the zone names into this buffer as a packed array of packed Pascal strings.

The zipNumZones field returns the actual number of zone names that ZIP placed in the buffer. You must set the zipLastFlag field to 0 before you execute the GetZoneList or GetLocalZones function. If the zipLastFlag parameter is still 0 when the command has completed execution, then ZIP is waiting to return more zone names. In this case you must empty the buffer, or allocate a new one, and call the GetZoneList or GetLocalZones function again immediately. When there are no more zone names to return, ZIP sets the zipLastFlag field to a nonzero value. The zipInfoField field is a 70-byte data buffer that you must allocate for use by ZIP. The first time you call any of these functions, you must set the first word of this field to 0. You must not change any values in this field subsequently.

Listing 4-2 shows the application-defined DoGetZoneList function, which illustrates how to use the GetZoneList function. The GetLocalZones function operates in exactly the same fashion.

This DoGetZoneList function allocates a buffer for zone names and repeatedly calls the GetZoneList function to get a list of zone names. If GetZoneList returns a function result of noErr, then the DoGetZoneList code calls the application-defined MyZIPExtract function, shown in Listing 4-3, to remove a zone name from the GetZoneList buffer and place it in the application's buffer. The DoGetZoneList code in Listing 4-2 does not show the application-defined MyAddToZoneList that writes the zone name to the application's buffer.

Listing 4-2 Using GetZoneList to retrieve names of zones throughout the AppleTalk internet

FUNCTION DoGetZoneList: OSErr;
CONST
   kZoneBufferSize = 578;              {required size of zone list buffer}
VAR
   xppPB: XPPParamBlock;
   result: OSErr;
   zoneBuffer: Ptr;
   index: Integer;
   zoneName: Str32;
BEGIN
      {Allocate buffer for returned zone names.}
   zoneBuffer := NewPtr(kZoneBufferSize);
   IF zoneBuffer = NIL THEN
      result := MemError
   ELSE
   BEGIN
      WITH xppPB DO
      BEGIN
         xppTimeout := 3;              {timeout interval}
         xppRetry := 4;                {retry count}
         zipBuffPtr := zoneBuffer;     {zone names returned here}
         zipLastFlag := 0;             {set to 0 first time through}
         zipInfoField[1] := 0;         {first word of zipInfoField must be }
         zipInfoField[2] := 0;         { initialized to 0 the first time}
      END;

      {Loop to get all of the zone names.}
      REPEAT
         result := GetZoneList(@xppPB, FALSE);
         IF (result = noErr) THEN
            FOR index := 1 TO xppPB.zipNumZones DO
               IF MyZIPExtract(zoneBuffer, xppPB.zipNumZones, index, 
                            zoneName) = noErr THEN
                  MyAddToZoneList(zoneName);
      UNTIL (xppPB.zipLastFlag <> 0) OR (result <> noErr);
      DisposPtr(zoneBuffer);           {release memory}
   END;
   DoGetZoneList := result;
END;

When you call the GetZoneList function or the GetLocalZones function to obtain a list of zone names, ZIP returns the zone names as a packed array of packed Pascal strings. Your application must include a routine to extract the zone names that you want from the buffer.

Listing 4-3 shows an application-defined function called MyZipExtract that extracts
a particular zone name from the buffer of packed zone names returned by either GetZoneList or GetLocalZones.

The MyZipExtract function takes a numInBuf input parameter that specifies the number of zone names in the buffer pointed to by the theBuffer parameter. For the numInBuf parameter, you specify the value that ZIP returned in the zipNumZones field of the XPP parameter block used for the GetZoneList or GetLocalZones function.

You use the whichOne input parameter to identify the zone name to extract. The MyZIPExtract function returns the zone name in the zoneName string parameter.

The MyZIPExtract function returns a result of paramErr if whichOne is 0 or whichOne is greater than the number of zones in the buffer. Otherwise, the function returns a function result of noErr.

Listing 4-3 Extracting a zone name from the list of zone names returned in the buffer

FUNCTION MyZIPExtract (theBuffer: Ptr; numInBuf: Integer; whichOne: Integer;
                     VAR zoneName: Str32): OSErr;
VAR
   result: OSErr;
   zonePtr: Ptr;
BEGIN
   {preflight the input parameters}
   IF (whichOne = 0) OR (whichOne > numInBuf) THEN
      result := paramErr
   ELSE
   BEGIN
      zonePtr := theBuffer;
      {Look for whichOne}
      REPEAT
         whichOne := whichOne - 1;
         IF whichOne <> 0 THEN
               {move pointer to next zone name}
            zonePtr := Ptr(ORD4(zonePtr) + 
               Length(StringPtr(zonePtr)^) + 1);
      UNTIL whichOne = 0;
               {return the zone name}
      BlockMove(zonePtr, @zoneName, 
               Length(StringPtr(zonePtr)^) + 1);
      result := noErr;
   END;
   MyZIPExtract := result;
END;