Legacy Document

Inside Macintosh: Networking /

Chapter 3 - Name-Binding Protocol (NBP) / NBP Reference

Routines / Registering an Entity

PRegisterName

The PRegisterName function adds a unique names table entry to the local node's NBP names table.

FUNCTION PRegisterName (thePBptr: MPPPBPtr; async: Boolean): OSErr;

thePBptr

A pointer to an MPP parameter block.

async

A Boolean that indicates whether the function should be executed asyn-
chronously or synchronously. Specify TRUE for asynchronous execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
-->	ioRefNum	Integer	The .MPP driver reference number.
-->	csCode	Integer	Always registerName.
-->	interval	Byte	The retry interval.
<->	count	Byte	The retry count.
-->	entityPtr	Ptr	A pointer to a names table entry.
-->	verifyFlag	Byte	A flag to indicate whether NBP is to verify NBP names as unique.

Field Description

ioCompletion

A pointer to a completion routine that you can provide. When you execute a function asynchronously, the .MPP driver calls your completion routine when it completes execution of the function if you specify a pointer to the routine as the value of this field. Specify NIL for this field if you do not wish to provide a completion routine. If you execute a function synchronously, the .MPP driver ignores the ioCompletion field. For information about completion routines, see the chapter "Introduction to AppleTalk" in this book.

ioResult

The result of the function. When you execute the function asynchro-
nously, the function sets this field to 1 and returns a function
result of noErr as soon as the function begins execution. When
the function completes execution, it sets the ioResult field to the actual result code.

ioRefNum

The .MPP driver reference number. The MPW interface fills in
this field.

csCode

The command code of the .MPP command to be executed. The MPW interface fills in this field.

interval

The retry interval to be used by NBP when it verifies the uniqueness of the name. The retry interval value specifies how long the function is to wait between retries in 8-tick units. A value of 7 for the interval field is usually sufficient (7 8 = 56 ticks equals approximately 1 second).

count

On input, the retry count to be used by NBP when it verifies the uniqueness of the name. Its value tells the PRegisterName function how many times to retry. A retry count of 5 is usually sufficient. On return, the number of times that NBP actually attempted to verify the uniqueness of the name.

entityPtr

A pointer to a names table entry. You can use the NBPSetNTE procedure to create a names table entry.You cannot use wildcard characters in the object name and type name fields of the names table entry, but you must use an asterisk (*)--indicating the local zone--for the zone name field.

verifyFlag

A flag that determines whether NBP attempts to verify that the name you are adding to the names table is unique. Set this flag to a nonzero number to have NBP verify the name. You can set this flag to zero during program development, but to avoid confusion caused by duplicate names on a network, you should always set the verifyFlag parameter to a nonzero number in released software.

DESCRIPTION

Before another entity can send information to your entity over AppleTalk, it must have your entity's internet socket address. Also, for users to be able to select your application, the entity must be made visible throughout the network.

The PRegisterName function adds an entry for a network entity to the node's NBP names table, making it possible for a user or another process to locate that entity through its NBP name (consisting of object, type, and zone names). The process whose name is registered with NBP is referred to as a network-visible entity.

Because the object, type, and zone names in a names table entry are of arbitrary length, you cannot create this record in Pascal (which requires you to declare the length of character strings when you define the record). Use the NBPSetNTE procedure to create the names table entry. If you execute the function asynchronously and you do not specify a completion routine, your process can poll the ioResult field to determine when the function completes execution.

You can assign any number of names to a single socket. If you use a single socket for more than one process, you must provide a socket listener.

If you use the PKillNPB function to cancel the PRegisterName function and the cancel request is successful, PRegisterName returns a function result of reqAborted.

SPECIAL CONSIDERATIONS

The names table entry that you provide remains the property of NBP until you use the PRemoveName function to remove the entry from the names table. You must allocate a nonrelocatable block for the names table entry, or lock any relocatable block that you use for it until you are ready to remove the entry.

ASSEMBLY-LANGUAGE INFORMATION

To execute the PRegisterName function from assembly language, call the _Control trap macro with a value of registerName in the csCode field of the parameter block. To execute the _Control trap asynchronously, include the value ,ASYNC in the operand field. To execute this function from assembly language, you must also specify the driver reference number.

RESULT CODES

noErr	0	No error
nbpDuplicate	-1027	Name already exists
tooManyReqs	-1097	Too many concurrent requests; wait a few minutes, then try the request again
reqAborted	-1105	Request canceled

SEE ALSO

To create a names table entry, use the NBPSetNTE procedure, described on page 3-22.

For the names table entry record format, see Figure 3-2 on page 3-5.

For the NamesTableEntry data type declaration, see "Names Table Entry Record" on page 3-19.

To cancel a name registration request, use the PKillNBP function, described on page 3-36.

For information about socket listeners, see the chapter "Datagram Delivery Protocol (DDP)" in this book.