Important: The information in this document is obsolete and should not be used for new development.
GetZoneList
TheGetZoneList
function returns a complete list of all the zone names on the internet.
FUNCTION GetZoneList (thePBptr: XPPParmBlkPtr; async: Boolean): OSErr;
thePBptr
- A pointer to an XPP parameter block.
async
- A Boolean that indicates whether the function should be executed asynchronously or synchronously. Specify
TRUE
for asynchronous execution.
--> ioCompletion ProcPtr A pointer to a completion routine. <-- ioResult OSErr The function result. --> csCode Integer Always xCall
for this function.--> xppSubCode Integer Always zipGetZoneList
for this function.--> xppTimeout Byte The retry interval in seconds. --> xppRetry Byte The retry count. --> zipBuffPtr Ptr A pointer to data buffer. <-- zipNumZones Integer
The number of names returned. <-- zipLastFlag Byte
A flag that is nonzero if there are no more names. --> zipInfoField PACKED ARRAY
A data buffer for use by ZIP; first word set to 0.
Field Description
xppSubCode
- A routine selector. This field is automatically set by the MPW interface to
zipGetZoneList
for this function.- xppTimeout
- The amount of time, in seconds, that the .ATP driver should wait between attempts to obtain the data. A value of 3 or 4 seconds for the
xppTimeout
field generally gives good results.- xppRetry
- The number of times the .ATP driver should attempt to obtain the data before returning the request failed (
reqFailed
) result code.
A value of 3 or 4 is usually sufficient.- zipBuffPtr
- A pointer to a 578-byte data buffer that you must allocate. ZIP returns the zone names into this buffer as a packed array of
Pascal strings.zipNumZones
- The number of zone names that ZIP placed in the data buffer.
zipLastFlag
- A value that indicates if there are more zone names for your network beyond those that ZIP returned in the
zipBuffPtr
field. The .XPP driver sets this field to 1 if there are no more zone names for your network.- zipInfoField
- A 70-byte data buffer that you must allocate for use by ZIP. Typically, you call
GetZoneList
repeatedly from within a loop. You must set the first word of this buffer to 0 before you call theGetZoneList
function the first time through the loop, and you must not change the contents of this field thereafter.DESCRIPTION
TheGetZoneList
function returns a complete list of all the zone names on the internet to which the local network of the node running your application belongs. TheGetZoneList
function uses ATP to retrieve the zone information. The buffer that you allocate to hold the returned zone names is the size of a single ATP response. You must call theGetZoneList
function repeatedly until all of the zones for the local network have been returned.Your application must check the
zipLastFlag
field to determine if there are more zone names for your network. If the value of this field is 1, there are no more zone names for your local network. If the value of this field is still 0 when theGetZoneList
function completes execution, you must empty the data buffer pointed to by thezipBuffPtr
parameter and immediately call theGetZoneList
function again without changing the value in thezipInfoField
parameter.If you receive a
GetZoneList
function result oftooManyReqs
, wait a minute or so, and then try again; some transactions can take up to 30 seconds to complete.To obtain a list of only the zone names on the local network, use the
GetLocalZones
function instead. If you use theGetZoneList
function on a nonextended network, the function returns thereqFailed
result code.SPECIAL CONSIDERATIONS
The memory that you allocate for the parameter block and the two buffers required by theGetZoneList
function belongs to the .XPP driver until the function completes execution. You can reuse the memory or dispose of it after the operation completes.ASSEMBLY-LANGUAGE INFORMATION
To execute theGetZoneList
function from assembly language, call the_Control
trap macro with a value ofxCall
in thecsCode
field of the parameter block and a value ofzipGetZoneList
in thexppSubCode
field of the parameter block. To execute this function from assembly language, you must also specify the .XPP driver reference number.RESULT CODES
noErr 0 No error noBridgeErr -93 No router is available reqFailed -1096 Request to contact router failed; retry count exceeded tooManyReqs -1097 Too many concurrent requests noDataArea -1104 Too many outstanding ATP calls SEE ALSO
For theXPPParamBlock
data type, see "The XPP Parameter Block for ZIP" beginning on page 4-10.To get the correct reference number for the .XPP driver, you can use the Device Manager's
OpenDriver
function, which returns the driver reference number. For information about theOpenDriver
function, see the chapter "Device Manager" in
Inside Macintosh: Devices.