Legacy Document

Inside Macintosh: Networking /

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

Routines / Handling Name and Address Requests

PRemoveName

The PRemoveName function removes a previously registered name from the NBP
names table.

FUNCTION PRemoveName (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 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 removeName.
-->	entityPtr	Ptr	A pointer to an entity name.

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.

entityPtr

A pointer to the name of the network-visible entity that you wish
to remove from the names table. The name must be in the format shown in Figure 3-5 on page 3-11. You cannot use any wildcard characters in the name.

DESCRIPTION

When you close a socket or terminate an application or process that you registered in the NBP names table as a network-visible entity, you must use the PRemoveName function to remove the name from the names table.

To remove the names table entry, you assign to the entityPtr field of the parameter block a pointer to a fully qualified entity name. The entity name is a packed array of Pascal strings. Because the object, type, and zone names in this format 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). You can use the NBPSetEntity procedure to create this record, or you can provide PRemoveName with a pointer to the names table entry record that you used to register the name.

SPECIAL CONSIDERATIONS

Memory used for the buffer containing the entity name belongs to the PRemoveName function until the function completes execution and must be nonrelocatable. After you remove the names table entry, you can reuse the memory or release it.

ASSEMBLY-LANGUAGE INFORMATION

To execute the PRemoveName function from assembly language, call the _Control trap macro with a value of removeName 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
nbpNotFound	-1028	Name not found
reqAborted	-1105	Request canceled

SEE ALSO

To create an entity name record of the form required by the PRemoveName function, use the NBPSetEntity procedure, described on page 3-27.