Legacy Document

Inside Macintosh: Interapplication Communication /

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

PPC Toolbox Routines / Starting and Ending a Session

PPCStart

The PPCStart function initiates a session with the destination port specified in the name and location fields.

FUNCTION PPCStart (pb: PPCStartPBPtr; async: Boolean): OSErr;

pb

A pointer to a PPCStart parameter block.

async

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

-->	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 requested--must be ppcServiceRealTime
-->	resFlag	SignedByte	Reserved field--must be 0
-->	portName	PPCPortPtr	Pointer to a PPCPortRec
-->	locationName	LocationNamePtr	Pointer to a LocationNameRec
<--	rejectInfo	LongInt	Value from PPCReject if session was rejected
-->	userData	LongInt	Application-specific data
-->	userRefNum	LongInt	User reference number

DESCRIPTION

If your application calls the PPCStart 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 PPCStart function asynchronously, you must not change any of the fields in the parameter block until the call completes. The port name and location name pointed to by the PPCStart parameter block record 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 specify the PPC port identifier in the portRefNum field. The port reference number is a reference number for the port through which you are requesting a session. The value you specify must correspond to the port reference number returned from the PPCOpen function.

The sessRefNum field returns a session identifier. This number, which is provided by the PPC Toolbox, is used while data is being exchanged to identify a particular session. You must set the serviceType field to indicate that the session is to be connected in real time. For System 7, this field must always be set to the ppcServiceRealTime constant. You must set the resFlag field to 0.

The portName field must contain a pointer to a PPC port record. The locationName field should contain a pointer to a location name record or NIL. The PPC port record and the location name record specify the name and location of the PPC port to initiate a session with, and they are usually obtained from the PPCBrowser function. If the locationKindSelector field in the location name record is ppcNoLocation or if the locationName pointer is NIL, then the location is the local machine. If the locationKindSelector field in the location name record is ppcNBPLocation, then the location is a remote machine designated by the location name record's nbpEntity field.

If the ioResult field of the PPC parameter block returns a userRejectErr result code, the rejectInfo field contains the same value as the rejectInfo field in the PPCReject parameter block. The rejectInfo field is defined by your application.

The initiating port can specify any information in the userData field. The PPCInform function reports this data to the responding port upon its completion.

The userRefNum field specifies an authenticated user. The authentication mechanism of the PPC Toolbox identifies each user through an assigned name and a password. A user reference number of 0 indicates that you want to specify a guest.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the PPCStart function are

Trap macro	Selector
_PPC	$0002

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
nameTypeErr	-902	locationKindSelector is not ppcNBPLocation or ppcNoLocation
noPortErr	-903	Bad port reference number
noGlobalsErr	-904	System unable to allocate memory, critical error
localOnlyErr	-905	Network activity is currently disabled
destPortErr	-906	Port does not exist at destination
sessTableErr	-907	PPC Toolbox is unable to create a session
noUserNameErr	-911	User name unknown on destination machine
userRejectErr	-912	Destination rejected the session request
noResponseErr	-915	Unable to contact application
portClosedErr	-916	The port was closed
badPortNameErr	-919	PPC port record is invalid
networkErr	-925	An error has occurred in the network
noInformErr	-926	PPCStart failed because target application did not have an inform pending
authFailErr	-927	User's password is wrong
noUserRecErr	-928	Invalid user reference number
badServiceMethodErr	-930	Service method is other than ppcServiceRealTime
guestNotAllowedErr	-932	Destination port requires authentication

SEE ALSO

For an example of the use of the PPCStart function, see Listing 11-7 on page 11-34.