Legacy Document

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

noErr	0	No error
paramErr	-50	Illegal parameter
memFullErr	-108	Not enough memory to load PPCBrowser package
userCanceledErr	-128	User 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.