Important: The information in this document is obsolete and should not be used for new development.
IPCListPorts
Use theIPCListPorts
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
).
--> ioCompletion PPCCompProcPtr Address of a completion routine <-- ioResult OSErr Result code --> startIndex Integer Index to the port entry list --> requestCount Integer Number of port names requested <-- actualCount Integer Number of port names returned --> portName PPCPortPtr Pointer to a PPCPortRec
--> locationName LocationNamePtr Pointer to a LocationNameRec
--> bufferPtr PortInfoArrayPtr Pointer to an array of PortInfoRec
DESCRIPTION
If your application calls theIPCListPorts
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
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 byIPCListPortsPBRec
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 thestartIndex
field to 0. TherequestCount
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 theIPCListPorts
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 specifyFALSE
for thenetworkVisible
field in thePPCOpen
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 theportTypeStr
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 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.The
IPCListPorts
function returns an array (list) of port information records in the area of memory pointed to bybufferPtr
. Make sure that the buffer pointed to by thebufferPtr
field is at leastsizeof(PortInfoRec) * requestCount
.ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for theIPCListPorts
function are
Trap macro Selector _PPC $000A 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 Invalid or inappropriate locationKindSelector
in location namenoGlobalsErr -904 System unable to allocate memory, critical error localOnlyErr -905 Network activity is currently disabled sessTableErr -907 PPC Toolbox is unable to create a session noResponseErr -915 Unable to contact application badPortNameErr -919 PPC port record is invalid networkErr -925 An error has occurred in the network badLocNameErr -931 Location name is invalid SEE ALSO
For an example of the use of theIPCListPorts
function, see Listing 11-5 on page 11-28.