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 / 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 macroSelector
_PPC$000E

The registers on entry and exit for this routine are
Registers on entry
A0Pointer to a StartSecureParams record
D0Selector code
Registers on exit
D0Result code

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


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996