Important: The information in this document is obsolete and should not be used for new development.
PPCStart
ThePPCStart
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 thePPCStart
function asynchronously, you must specify in theioCompletion
field either the address of a completion routine orNIL
. If you setioCompletion
toNIL
, you should poll theioResult
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 theioResult
field other than 1 indicates that the call is complete. Note that it is unsafe to poll theioResult
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 thePPCStart
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 thePPCOpen
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 theserviceType
field to indicate that the session is to be connected in real time. For System 7, this field must always be set to theppcServiceRealTime
constant. You must set theresFlag
field to 0.The
portName
field must contain a pointer to a PPC port record. ThelocationName
field should contain a pointer to a location name record orNIL
. 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 thePPCBrowser
function. If thelocationKindSelector
field in the location name record isppcNoLocation
or if thelocationName
pointer isNIL
, then the location is the local machine. If thelocationKindSelector
field in the location name record isppcNBPLocation
, then the location is a remote machine designated by the location name record'snbpEntity
field.If the
ioResult
field of the PPC parameter block returns auserRejectErr
result code, therejectInfo
field contains the same value as therejectInfo
field in thePPCReject
parameter block. TherejectInfo
field is defined by your application.The initiating port can specify any information in the
userData
field. ThePPCInform
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 thePPCStart
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 notppcNBPLocation
orppcNoLocation
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 pendingauthFailErr -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 thePPCStart
function, see Listing 11-7 on page 11-34.