Important: The information in this document is obsolete and should not be used for new development.
StartSecureSession
TheStartSecureSession
function prompts for user name and password and callsPPCStart
--all in one synchronous procedure call. Use theStartSecureSession
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, specifyTRUE
; otherwise, specifyFALSE
.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 thePPCStart
function. You specify all input fields in the parameter block except for theuserRefNum
field. TheuserRefNum
field is returned when theStartSecureSession
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 theuserName
buffer.Set the
useDefault
parameter toTRUE
if you want theStartSecureSession
function to use the default user identity (and possibly prevent the user identity dialog box from appearing). TheallowGuest
parameter specifies whether the Guest radio button in the user identity dialog box is active. You usually set it to the inverse of theauthRequired
field in the port information record. For example, ifauthRequired
isTRUE
, thenallowGuest
should be set toFALSE
.The
guestSelected
parameter returnsTRUE
if the user has logged on as a guest. Theprompt
parameter of theStartSecureSession
function allows you to specify a line of text that the dialog box can display. SpecifyNIL
or an empty string for theprompt
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 theStartSecureSession
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
recordD0 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 notppcNBPLocation
orppcNoLocation
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 pendingbadServiceMethodErr -930 Service method is other than ppcServiceRealTime
guestNotAllowedErr -932 Destination port requires authentication SEE ALSO
For an example of the use of theStartSecureSession
function, see "Initiating a PPC Session" beginning on page 11-29.