Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 11 - Program-to-Program Communications Toolbox / PPC Toolbox Reference

PPC Toolbox Routines / Starting and Ending a Session

StartSecureSession

The StartSecureSession function prompts for user name and password and calls PPCStart--all in one synchronous procedure call. Use the StartSecureSession function whenever a port destination requires authentication.

FUNCTION StartSecureSession (pb: PPCStartPBPtr; 
                             VAR userName: Str32; 
                             useDefault: Boolean; 
                             allowGuest: Boolean; 
                             VAR guestSelected: Boolean; 
                             prompt: Str255): OSErr;

pb

A pointer to a PPCStart parameter block.

userName

A pointer to a 32-byte character string to be displayed as the user's name.

useDefault

A Boolean value that indicates whether you want the StartSecureSession function to use the default user identity (and possibly prevent the user identity dialog box from appearing). If so, specify TRUE; otherwise, specify FALSE.

allowGuest

A Boolean value that determines whether the Guest radio button in the user identity dialog box is active (TRUE) or inactive (FALSE).

guestSelected

Returns TRUE if the user has logged on as a guest.

prompt

A line of text that the dialog box displays in place of the default prompt. Specify NIL or an empty string to use the default prompt.

DESCRIPTION

Your program fills out a parameter block just as though it were calling the PPCStart function. You specify all input fields in the parameter block except for the userRefNum field. The userRefNum field is returned when the StartSecureSession function successfully completes.

The userName parameter is a pointer to a 32-byte character string to be displayed as the user's name. If the Pascal string length is 0, the default user name is used. The default user name is the name specified in the Sharing Setup control panel. The default user name is returned in the userName buffer.

Set the useDefault parameter to TRUE if you want the StartSecureSession function to use the default user identity (and possibly prevent the user identity dialog box from appearing). The allowGuest parameter specifies whether the Guest radio button in the user identity dialog box is active. You usually set it to the inverse of the authRequired field in the port information record. For example, if authRequired is TRUE, then allowGuest should be set to FALSE.

The guestSelected parameter returns TRUE if the user has logged on as a guest. The prompt parameter of the StartSecureSession function allows you to specify a line of text that the dialog box can display. Specify NIL or an empty string for the prompt parameter to enable the PPC Toolbox to use the default prompt. The PPC Toolbox uses the default string "Link to <port name> on <object string> as:". The port name is obtained from the name string of the port name, and the object string is obtained from the object string of the location name.

Note

Do not call the StartSecureSession function from an application that is running in the background, because the function displays several dialog boxes on the user's screen.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the StartSecureSession function are

Trap macro	Selector
_PPC	$000E

The registers on entry and exit for this routine are

Registers on entry
A0	Pointer to a StartSecureParams record
D0	Selector code

Registers on exit
D0	Result code

RESULT CODES

noErr	0	No error
userCanceledErr	-128	User decided not to conduct a session
notInitErr	-900	PPC Toolbox has not been initialized yet
nameTypeErr	-902	locationKindSelector is not ppcNBPLocation or ppcNoLocation
noPortErr	-903	Bad port reference number
noGlobalsErr	-904	System unable to allocate memory, critical error
localOnlyErr	-905	Network activity is currently disabled
destPortErr	-906	Port does not exist at destination
sessTableErr	-907	PPC Toolbox is unable to create a session
noResponseErr	-915	Unable to contact application
portClosedErr	-916	The port was closed
badPortNameErr	-919	PPC port record is invalid
noUserRefErr	-924	Unable to create a new user reference number
networkErr	-925	An error has occurred in the network
noInformErr	-926	PPCStart failed because target application did not have an inform pending
badServiceMethodErr	-930	Service method is other than ppcServiceRealTime
guestNotAllowedErr	-932	Destination port requires authentication

SEE ALSO

For an example of the use of the StartSecureSession function, see "Initiating a PPC Session" beginning on page 11-29.