Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 11 - Program-to-Program Communications Toolbox / PPC Toolbox Reference

PPC Toolbox Routines / Receiving, Accepting, and Rejecting a Session

PPCInform

As long as a port has been opened, you can call the PPCInform function at any time. You can have any number of outstanding PPCInform functions.

FUNCTION PPCInform (pb: PPCInformPBPtr; async: Boolean): OSErr;

pb

A pointer to a PPCInform parameter block.

async

A value that specifies whether the function is to be executed asynchronously (TRUE) or synchronously (FALSE). You should execute the PPCInform function asynchronously.

-->	ioCompletion	PPCCompProcPtr	Address of a completion routine
<--	ioResult	OSErr	Result code
-->	portRefNum	PPCPortRefNum	Port reference number of this session
<--	sessRefNum	PPCSessRefNum	Session reference number of this session
<--	serviceType	PPCServiceType	Service type of this session
-->	autoAccept	Boolean	If TRUE, session is accepted automatically
-->	portName	PPCPortPtr	Pointer to PPCPortRec, may be NIL
-->	locationName	LocationNamePtr	Pointer to LocationNameRec, may be NIL
	userName	StringPtr	Pointer to Str32, may be NIL
<--	userData	LongInt	Application-specific data
<--	requestType	PPCSessionOrigin	Network or local request

DESCRIPTION

If your application calls the PPCInform function asynchronously, you must specify in the ioCompletion field either the address of a completion routine or NIL. If you set ioCompletion to NIL, you should poll the ioResult field of the PPC parameter block (from your application's main event loop) to determine whether the PPC Toolbox has completed the requested operation. A value in the ioResult field other than 1 indicates that the call is complete. Note that it is unsafe to poll the ioResult field at interrupt time since the PPC Toolbox may be in the process of completing a call. See "PPC Toolbox Calling Conventions" beginning on page 11-14 for detailed information.

If you call the PPCInform function asynchronously, you must not change any of the fields in the parameter block until the call completes. The port name, location name, user name, and buffer pointed to by the record of type PPCInformPBRec are owned by the PPC Toolbox until the call completes. These objects must not be deallocated or moved in memory while the call is in progress.

You provide the PPC port identifier in the portRefNum field. A PPCOpen function returns the port identifier. The sessRefNum field returns a session identifier.

The serviceType field indicates the service type. For system software version 7.0, this field always returns the ppcServiceRealTime constant.

If you set the autoAccept field to TRUE, session requests are automatically accepted as they are received. When the PPCInform function completes execution with a noErr result code and you set the autoAccept field to FALSE, you need to accept or reject the session.

WARNING

If the PPCInform function (with the autoAccept parameter set to FALSE) returns a noErr result code, you must call either the PPCAccept function or the PPCReject function. The computer trying to initiate a session using the StartSecureSession function or the PPCStart function waits (hangs) until the session attempt is either accepted or rejected, or until an error occurs.

The portName field must contain NIL or a pointer to a PPC port record. If the portName field contains NIL, then the name of the PPC port that initiated the session is not returned. If the portName field points to a PPC port record, then the PPC port record is filled with the name of the PPC port that initiated the session when the PPCInform function completes.

The locationName field must contain NIL or a pointer to a location name record. If the locationName field contains NIL, then the location of the PPC port that initiated the session is not returned. If the locationName field points to a location name record, then the location name record is filled with the location of the PPC port that initiated the session when the PPCInform function completes. If the locationKindSelector field of the location name record returned is ppcNoLocation, then the location is the local machine. If the locationKindSelector field of the location name record returned is ppcNBPLocation, then the location is a remote machine designated by the location name record's nbpEntity field.

The userName field must contain NIL or a pointer to a 32-byte character string. If the userName field contains NIL, then the user name string is not returned. If the userName field points to a 32-byte character string, then the 32-byte character string is filled with the name of the user making the session request (if authenticated) when the PPCInform function completes.

When the PPCInform function completes, the userData field contains the user data provided by the application making the session request. This field is transparent to the PPC Toolbox. The application can send any data in this field.

When the PPCInform function completes, the requestType field contains either ppcRemoteOrigin or ppcLocalOrigin, depending on whether the session request is initiated by a computer across the network or by a port on the same computer.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the PPCInform function are

Trap macro	Selector
_PPC	$0003

The registers on entry and exit for this routine are

Registers on entry
A0	Pointer to a parameter block
D0	Selector code

Registers on exit
D0	Result code

RESULT CODES

noErr	0	No error
notInitErr	-900	PPC Toolbox has not been initialized yet
noPortErr	-903	Unable to open port or bad port reference number
noGlobalsErr	-904	System unable to allocate memory, critical error
portClosedErr	-916	The port was closed

SEE ALSO

For an example of the use of the PPCInform function, see Listing 11-8 on page 11-36.