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 / Using the Program Linking Dialog Box


PPCBrowser

Use the PPCBrowser function to display the program linking dialog box, which allows a user to select a port to communicate with.

FUNCTION PPCBrowser (prompt: Str255; applListLabel: Str255; 
                     defaultSpecified: Boolean; 
                     VAR theLocation: LocationNameRec; 
                     VAR thePortInfo: PortInfoRec; 
                     portFilter: PPCFilterProcPtr; 
                     theLocNBPType: Str32): OSErr; 
prompt
A line of text that the PPCBrowser function displays as a prompt in the program linking dialog box. If you specify NIL or an empty string is passed, the default prompt "Choose a program to link to:" is used.
applListLabel
The title of the list of PPC ports. If you specify NIL or an empty string is passed, the default title "Programs" is used.
defaultSpecified
A value that determines which port is initially selected in the program linking dialog box. If you specify TRUE, you must provide information in the parameters theLocation and thePortInfo. In this case, the PPCBrowser function tries to select the PPC port specified by the parameters theLocation and thePortInfo when the program linking dialog box first appears. If you specify FALSE, the PPCBrowser function selects the first port in the list and you can leave the location name record and the port information record (in the parameters theLocation and thePortInfo) uninitialized.
theLocation
The port location. For information on this data structure, see "The Location Name Record" on page 11-50.
thePortInfo
The port name. For information on this data structure, see "The Port Information Record" on page 11-51.
portFilter
Determines how the list of PPC ports is filtered. If this parameter is NIL, the names of all existing PPC ports are displayed. If this parameter isn't NIL, it must be a pointer to a port filter function.
theLocNBPType
The NBP type passed to NBPLookup to generate the list of computers. If you specify NIL or an empty string is passed, the default, "PPCToolBox", is used.
DESCRIPTION
The PPCBrowser function builds the list of ports and then displays the program linking dialog box.

If you set the defaultSpecified parameter to TRUE, the PPCBrowser function tries to select the PPC port specified by the parameters theLocation and thePortInfo when the program linking dialog box first appears. The locationKindSelector field in the location name record must be set to the ppcNoLocation constant (which specifies the local computer) or the ppcNBPLocation constant (which specifies the NBP object and NBP zone). The ppcNBPTypeLocation constant is not supported for matching. When matching the location, only the object string and the zone string of the entity name are used--the type string is ignored. When matching the port, the entire PPC port record (script, name, and port type) is used in the port information record. The authRequired field of the port information record is ignored.

The parameter theLocNBPType of the PPCBrowser function specifies the NBP type passed to NBPLookup to generate the list of computers. If you specify NIL or an empty string is passed, the default, "PPCToolBox", is used. Note that the current computer is always included in the list of computers (even if a location with the specified type does not exist for it). If the parameter theLocNBPType contains either of the NBP wildcard characters (= or \xE2), the PPCBrowser function returns a paramErr result code.

If the PPCBrowser function returns noErr, the parameters theLocation and thePortInfo specify the port chosen by the user. If the PPCBrowser function returns a userCanceledErr result code, the user clicked the Cancel button, and no port was selected. If the function returns a memFullErr result code, there was not enough memory to load the PPCBrowser package, and the dialog box did not appear.

Note
You must not call the PPCBrowser function from an application that is running in the background, since this function displays a dialog box on the user's screen.
RESULT CODES
noErr0No error
paramErr-50Illegal parameter
memFullErr-108Not enough memory to load PPCBrowser package
userCanceledErr-128User decided not to conduct a session
SEE ALSO
For an example of the use of the PPCBrowser function, see Listing 11-4 on page 11-26. For an example of the program linking dialog box, see
Figure 11-12 on page 11-22. For information on port filter functions,
see page 11-79.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996