Important: The information in this document is obsolete and should not be used for new development.
PPCOpen
You open a port using thePPCOpen
function.
FUNCTION PPCOpen (pb: PPCOpenPBPtr; async: Boolean): OSErr;
pb
- A pointer to a
PPCOpen
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 port opened --> 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
--> networkVisible Boolean Make this port network visible <-- nbpRegistered Boolean Port location was registered on the network DESCRIPTION
If your application calls thePPCOpen
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
PPCOpen
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 thePPCOpen
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.The
portRefNum
field returns the PPC port identifier. Use this port reference number to initiate a session for this particular port. Set theserviceType
field to indicate that this port accepts sessions 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 that specifies the name of the PPC port to be opened.The
locationName
field should contain a pointer to a location name record that designates the location of the PPC port to be opened. If thelocationName
pointer isNIL
, then the default name PPC Toolbox is used. If a location name record is used, then thelocationKindSelector
field in the location name record must beppcNBPTypeLocation
, and an alias location name specified by the location name record'snbpType
field is used.The
networkVisible
field indicates whether the port should be made visible (for browsing as well as incoming network requests). If you specifyFALSE
, this port is not visible in the listing of available ports across a network (although it is still included within the local machine's listing of available ports).The
nbpRegistered
field returnsTRUE
if the location name specified was registered on the network.ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for thePPCOpen
function are
Trap macro Selector _PPC $0001 The registers on entry and exit for this routine are
Registers on entry A0 Pointer to a parameter block D0 Selector (1)
Registers on exit D0 Result code RESULT CODES
noErr 0 No error notInitErr -900 PPC Toolbox has not been initialized yet nameTypeErr -902 Invalid or inappropriate locationKindSelector
in location namenoPortErr -903 Unable to open port or bad port reference number noGlobalsErr -904 System unable to allocate memory, critical error badReqErr -909 Bad parameter or invalid state for this operation portNameExistsErr -910 Another port is already open with this name badPortNameErr -919 PPC port record is invalid badServiceMethodErr -930 Service method is other than ppcServiceRealTime
badLocNameErr -931 Location name is invalid nbpDuplicateName -1027 Location name represents a duplicate on this computer SEE ALSO
For an example of the use of thePPCOpen
function, see Listing 11-2 on page 11-21.