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 / Obtaining a List of Ports


IPCListPorts

Use the IPCListPorts function to generate a list of existing ports without displaying a dialog box.

FUNCTION IPCListPorts (pb: IPCListPortsPBPtr; 
                       async: Boolean): OSErr; 
pb
A pointer to an IPCListPorts 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
-->startIndexIntegerIndex to the port entry list
-->requestCountIntegerNumber of port names requested
<--actualCountIntegerNumber of port names returned
-->portNamePPCPortPtrPointer to a PPCPortRec
-->locationNameLocationNamePtrPointer to a LocationNameRec
-->bufferPtrPortInfoArrayPtrPointer to an array of PortInfoRec

DESCRIPTION
If your application calls the IPCListPorts 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 IPCListPorts function asynchronously, you must not change any of the fields in the parameter block until the call completes. The port name, location name, and buffer pointed to by IPCListPortsPBRec 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 startIndex field specifies the index to the list of ports on the remote machine from which the PPC Toolbox begins to get the list. In most cases, you'll want to start at the beginning, so set the startIndex field to 0. The requestCount field specifies the maximum number of port information records that can fit into your buffer.

The actualCount field returns the actual number of entries returned. Your program can use the IPCListPorts function repeatedly to obtain the entire list of ports. Ports that are not visible to the network are not included in the ports listing on a remote machine. (If you specify FALSE for the networkVisible field in the PPCOpen function, the port is not included in the listing of available ports across a network.)

The portName field must contain a pointer to a PPC port record that specifies which PPC ports to list. You can specify particular values in the PPC port record or you can use an equal sign (=) in the name or the portTypeStr fields as a wildcard to match all port names or port types.

The locationName field should contain a pointer to a location name record that designates the computer that contains the PPC ports you want returned. 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.

The IPCListPorts function returns an array (list) of port information records in the area of memory pointed to by bufferPtr. Make sure that the buffer pointed to by the bufferPtr field is at least sizeof(PortInfoRec) * requestCount.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the IPCListPorts function are
Trap macroSelector
_PPC$000A

The registers on entry and exit for this routine are
Registers on entry
A0Pointer to a parameter block
D0Selector code
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
noGlobalsErr-904System unable to allocate memory, critical error
localOnlyErr-905Network activity is currently disabled
sessTableErr-907PPC Toolbox is unable to create a session
noResponseErr-915Unable to contact application
badPortNameErr-919PPC port record is invalid
networkErr-925An error has occurred in the network
badLocNameErr-931Location name is invalid
SEE ALSO
For an example of the use of the IPCListPorts function, see Listing 11-5 on page 11-28.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996