Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Interapplication Communication /
Chapter 11 - Program-to-Program Communications Toolbox / PPC Toolbox Reference
PPC Toolbox Routines / Opening and Closing a Port


PPCOpen

You open a port using the PPCOpen 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).
-->ioCompletionPPCCompProcPtrAddress of a completion routine
<--ioResultOSErrResult code
<--portRefNumPPCPortRefNumPort reference number of port opened
-->serviceTypePPCServiceTypeService type requested--must be ppcServiceRealTime
-->resFlagSignedByteReserved field--must be 0
-->portNamePPCPortPtrPointer to a PPCPortRec
-->locationNameLocationNamePtrPointer to a LocationNameRec
-->networkVisibleBooleanMake this port network visible
<--nbpRegisteredBooleanPort location was registered on the network

DESCRIPTION
If your application calls the PPCOpen 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 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 the PPCOpen 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 the serviceType field to indicate that this port accepts sessions 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 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 the locationName pointer is NIL, then the default name PPC Toolbox is used. If a location name record is used, then the locationKindSelector field in the location name record must be ppcNBPTypeLocation, and an alias location name specified by the location name record's nbpType field is used.

The networkVisible field indicates whether the port should be made visible (for browsing as well as incoming network requests). If you specify FALSE, 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 returns TRUE if the location name specified was registered on the network.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the PPCOpen function are
Trap macroSelector
_PPC$0001

The registers on entry and exit for this routine are
Registers on entry
A0Pointer to a parameter block
D0Selector (1)
Registers on exit
D0Result code

RESULT CODES
noErr0No error
notInitErr-900PPC Toolbox has not been initialized yet
nameTypeErr-902Invalid or inappropriate locationKindSelector in location name
noPortErr-903Unable to open port or bad port reference number
noGlobalsErr-904System unable to allocate memory, critical error
badReqErr-909Bad parameter or invalid state for this operation
portNameExistsErr-910Another port is already open with this name
badPortNameErr-919PPC port record is invalid
badServiceMethodErr-930Service method is other than ppcServiceRealTime
badLocNameErr-931Location name is invalid
nbpDuplicateName-1027Location name represents a duplicate on this computer
SEE ALSO
For an example of the use of the PPCOpen function, see Listing 11-2 on page 11-21.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996