Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Chapter 2 - AppleTalk Utilities / AppleTalk Utilities Reference

Routines / Obtaining Information About the .MPP Driver and the Current Network Environment

PGetAppleTalkInfo
The PGetAppleTalkInfo function returns information about the currently installed version of the .MPP driver and the network environment.
FUNCTION PGetAppleTalkInfo (thePBptr: MPPPBPtr; async:
                              Boolean): OSErr;
thePBptr
A pointer to an MPP parameter block.
async
A Boolean that specifies whether the function should be executed asynchronously. Specify TRUE for asynchronous execution.

--> ioCompletion ProcPtr A pointer to a completion routine.
<-- ioResult OSerr The result code.
--> ioRefNum Integer The .MPP driver reference number.
--> csCode Integer Always GetATalkInfo.
--> version Integer The version of the function.
<-- varsPtr Ptr A pointer to the MPP globals.

<-- DCEPtr Ptr A pointer to DCE for the .MPP driver.
<-- portID Integer The port number.
<-- configuration LongInt The configuration flags.
<-- selfSend Integer Nonzero if self-sending is enabled.
<-- netLo Integer The low value of the network range.
<-- netHi Integer The high value of the network range.
<-- ourAddr LongInt The local 24-bit AppleTalk address.
<-- routerAddr LongInt The 24-bit address of the router.
<-- numOfPHs Integer The maximum number of protocol handlers.
<-- numOfSkts Integer The maximum number of static sockets.
<-- numNBPEs Integer The maximum concurrent NBP requests.
<-- ntQueue Ptr A pointer to registered names table.
<-> LAlength Integer The length in bytes of data-link address (extended networks only).
--> linkAddr Ptr A pointer to data-link address buffer (extended networks only).
--> zoneName Ptr A pointer to zone name buffer.

Field Description

version
The version number of the PGetAppleTalkInfo function you are calling. For version number 53 and greater of the .MPP driver, this number is always 1.
varsPtr
A pointer to the MPP global variables. This parameter is reserved for the use of Apple Computer, Inc.; you cannot rely on the validity of the variables pointed to by this parameter.
DCEPtr
A pointer to the device control entry (DCE) data structure for the .MPP driver. For information about the DCE, see the chapter "Device Manager" in Inside Macintosh: Devices.
portID
The port number for the .MPP driver. The port number is always 0 unless you are requesting information for an .MPP driver being used by a router.
configuration
A 32-bit longword of configuration flags. The following flags are currently defined:
Bit Flag Description
31 SrvAdrBit TRUE (equal to 1) if the routine that opened the .MPP driver requested
a server node number. For more information on server nodes, see "Selecting a Node in the Server Range" on page 2-7. This flag indicates only that the server node number was requested, not that it was returned. Some AppleTalk data links, such as EtherTalk, TokenTalk, and FDDITalk, do not honor a request for a server node number.

30 RouterBit TRUE (equal to 1) if an AppleTalk internet router was loaded at system startup (that is, there's a router operating on the same node as your application). A router can be loaded and not active.
15 ExtendedBit TRUE (equal to 1) if the node is on an extended network. Testing this bit is the only way to determine whether you are on an extended network.
7 BadZoneHintBit TRUE (equal to 1) if the zone name of the node you are on was not the same as the zone name stored in parameter RAM (sometimes referred to as the zone name hint) when the .MPP driver was opened. If the zone name hint is invalid, then the AppleTalk Manager uses the default zone for the network. The default zone is defined by the network administrator.
6 OneZoneBit TRUE (equal to 1) if only one zone is assigned to your extended network or if you are not on an extended network. Use the ExtendedBit flag to determine whether you are on an extended network.

selfSend
The ability of a node to send packets to itself. This feature, called intranode delivery, is enabled when this parameter is nonzero.
Use the PSetSelfSend function, which is described beginning
on page 2-15, to enable or disable this feature.
netLo
The low value of the range of network numbers on the local cable. Only extended networks can have a range of network numbers. For a nonextended network, this parameter returns the network number.
netHi
The high value of the range of network numbers on the local cable. Only extended networks can have a range of network numbers. For a nonextended network, this parameter returns the network number.
ourAddr
The 24-bit AppleTalk network address of the node you are on. The least significant byte of the longword is the node ID. The middle
16 bits are the network number. The most significant byte of the longword is reserved for use by Apple Computer, Inc.
routerAddr
The 24-bit AppleTalk network address of the last router from which your node heard traffic. The least significant byte of the longword
is the node ID. The middle 16 bits are the network number. The most significant byte of the longword is reserved for use by Apple Computer, Inc. You should always use this address when you want to communicate with a router.
numOfPHs
The maximum number of protocol handlers that this .MPP
driver allows.
numOfSkts
The maximum number of statically assigned sockets that this .MPP driver allows. Statically assigned sockets are described in Inside AppleTalk, second edition. For more information about sockets, see the chapter "Datagram Delivery Protocol (DDP)" in this book.
numNBPEs
The maximum number of concurrent requests to NBP that this .MPP driver allows.
ntQueue
A pointer to the first entry in the names table for the local node. You can use NBP routines to look up and register names in the names table. The names table is described in the chapter "Name-Binding Protocol (NBP)" in this book.
LAlength
The number of bytes of the data-link address that the function should place in the buffer pointed to by the LinkAddr parameter. You use this parameter when you call the PGetAppleTalkInfo function on a node on an extended network. If you request more bytes than the total number of bytes in the address, then the function returns in the LAlength parameter the actual number of bytes it placed in the buffer. If the address is longer than the size of the buffer, then the PGetAppleTalkInfo function fills the buffer and returns in the LAlength parameter the actual length of the address, not the number of bytes returned. The function does not return an error when the buffer is too large or too small for the address. A value of 6 bytes for LAlength is sufficient for most purposes.
linkAddr
A pointer to a buffer for the data-link address returned for extended networks only. You use the LAlength parameter to specify the number of bytes of the address that you want placed in this buffer. You must allocate a buffer large enough to hold the number of bytes you specify. Specify NIL for this parameter if you do not want the function to provide a data-link address.
zoneName
A pointer to a buffer into which the PGetAppleTalkInfo function places the local node's zone name. You must allocate a buffer of at least 33 bytes to hold this data, or you must specify NIL for the zoneName parameter if you do not want to obtain the zone name. This field is returned only if the node is on an extended network.

DESCRIPTION
The PGetAppleTalkInfo function returns a variety of information about the current networking environment. For example, it returns information telling you whether or not applications running on the node can send packets to themselves or to other applica-
tions or processes on the same node. An application can call PGetAppleTalkInfo to determine if the node on which it is running has an ID that falls within the server node ID range. It can also obtain the address of the last router that the node communicated with and the node's own address.
You must allocate memory for and define a parameter block of type MPPParmType and pass that parameter block's pointer to PGetAppleTalkInfo when you call the function. You must also allocate memory for and provide pointers to the data buffers into which the PGetAppleTalkInfo function returns the data-link address and zone name.
You pass a pointer to the buffer for the returned data-link address as the value of the linkAddr field. You pass a pointer to the buffer for the returned zone name as the
value of the zoneName parameter block field.

SPECIAL CONSIDERATIONS
If the node on which your application is running happens also to be running AppleTalk internet router software in the background, more than one set of MPP global variables may be in RAM. To make sure you obtain information about the .MPP driver that handles application software, always use the PGetAppleTalkInfo function rather than the Device Manager's PBControl function. However, if you want to use the PBControl function, you must use a device driver reference number of -10 for the .MPP driver.
The memory that you allocated for the parameter block and data buffers belongs to the .MPP driver until the PGetAppleTalkInfo function completes execution. The memory must be nonrelocatable. After the PGetAppleTalkInfo function completes execution, you can reuse the memory or release it.

ASSEMBLY-LANGUAGE INFORMATION
If you use assembly language to call this function, you must use a device driver reference number of -10 for the .MPP driver.

RESULT CODES
noErr 0 No error
paramErr -50 Version number is too high

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSerr	The result code.
-->	ioRefNum	Integer	The .MPP driver reference number.
-->	csCode	Integer	Always `GetATalkInfo`.
-->	version	Integer	The version of the function.
<--	varsPtr	Ptr	A pointer to the MPP globals.

<--	DCEPtr	Ptr	A pointer to DCE for the .MPP driver.
<--	portID	Integer	The port number.
<--	configuration	LongInt	The configuration flags.
<--	selfSend	Integer	Nonzero if self-sending is enabled.
<--	netLo	Integer	The low value of the network range.
<--	netHi	Integer	The high value of the network range.
<--	ourAddr	LongInt	The local 24-bit AppleTalk address.
<--	routerAddr	LongInt	The 24-bit address of the router.
<--	numOfPHs	Integer	The maximum number of protocol handlers.
<--	numOfSkts	Integer	The maximum number of static sockets.
<--	numNBPEs	Integer	The maximum concurrent NBP requests.
<--	ntQueue	Ptr	A pointer to registered names table.
<->	LAlength	Integer	The length in bytes of data-link address (extended networks only).
-->	linkAddr	Ptr	A pointer to data-link address buffer (extended networks only).
-->	zoneName	Ptr	A pointer to zone name buffer.

Bit	Flag	Description
31	SrvAdrBit	`TRUE` (equal to 1) if the routine that opened the .MPP driver requested a server node number. For more information on server nodes, see "Selecting a Node in the Server Range" on page 2-7. This flag indicates only that the server node number was requested, not that it was returned. Some AppleTalk data links, such as EtherTalk, TokenTalk, and FDDITalk, do not honor a request for a server node number.

30	RouterBit	`TRUE` (equal to 1) if an AppleTalk internet router was loaded at system startup (that is, there's a router operating on the same node as your application). A router can be loaded and not active.
15	ExtendedBit	`TRUE` (equal to 1) if the node is on an extended network. Testing this bit is the only way to determine whether you are on an extended network.
7	BadZoneHintBit	`TRUE` (equal to 1) if the zone name of the node you are on was not the same as the zone name stored in parameter RAM (sometimes referred to as the zone name hint) when the .MPP driver was opened. If the zone name hint is invalid, then the AppleTalk Manager uses the default zone for the network. The default zone is defined by the network administrator.
6	OneZoneBit	`TRUE` (equal to 1) if only one zone is assigned to your extended network or if you are not on an extended network. Use the `ExtendedBit` flag to determine whether you are on an extended network.

Legacy Document

PGetAppleTalkInfo

Field Description

DESCRIPTION

SPECIAL CONSIDERATIONS

ASSEMBLY-LANGUAGE INFORMATION

RESULT CODES noErr0No error paramErr-50Version number is too high

RESULT CODES
noErr 0 No error
paramErr -50 Version number is too high