Dear listers,
you may download an FB^3 "PassWord.incl"-file from the DropBox.
It comes with a demo project and the compiled "PassWord Demo"
application that exmplify the functionality of "PassWord.incl".
You may use "PassWord.incl" (essentially a "stand alone" module) with
your projects ("Appearance" or "UltraLite" compiles). It requires
only a minimum amount of interfacing that is described below and in
its preface.
"PassWord.incl" is real Carbon and runs with OS 9.1.x/9.2.x as well
as with OS X (tested with 10.1.4 and 10.2.8 -- thank you Jan and Joe).
Please note that storage and evaluation of passwords is not part of
"PassWord.incl". "PassWord.incl" deals with the user interfaces only.
In the following details of the interfacing are sketched.
*****************************************************************************
PassWord.incl
*****************************************************************************
* This FB^3 Include File contains code for presenting "Password Dialogs".
* To display the "Password Dialogs" call "FN pwPasswordDialog(...)", after
you've set the appropriate display parameters that are part of the record
named "PasswordRec".
* For a quick and easy integration of the "PassWord.incl" to your code,
you may use the following templates.
(1) Display the dialog for setting a password__________*Easy Approach*
//----------------------------------------------------------------------
CLEAR LOCAL FN YourPasswordSetting // Clearing is necessary !
//----------------------------------------------------------------------
DIM AS OSStatus err
DIM AS PasswordRec @ pwRec
err = FN pwPasswordDialog( @pwRec )
IF ( err ) THEN EXIT FN // you better do some error checking
SELECT pwRec.result // result of the user action
CASE _userCanceledErr
EXIT FN
CASE _noErr
// The password is available as CFStringRef: pwRec.passwordTextRef
// You may want to encrypt and then store away the password.
// Don't forget to release the password when you are done with it
// using CFRelease( pwRec.passwordTextRef ).
CASE _pwOption2
// Here you must remove the password from the storage location as
// well as the protection of whatever you have protected by the
// password. (see "CASE _pwOption1" below)
END SELECT
END FN = err
//----------------------------------------------------------------------
(2) Display the dialog for checking the password_______*Easy Approach*
//----------------------------------------------------------------------
CLEAR LOCAL FN YourPasswordChecking // Clearing is necessary !
//----------------------------------------------------------------------
DIM AS CFStringRef storedPWRef
DIM AS OSStatus err
DIM AS PasswordRec @ pwRec
pwRec.checkMode = _zTrue
err = FN pwPasswordDialog( @pwRec )
IF ( ( err ) OR ( pwRec.result == _userCanceledErr ) ) THEN EXIT FN
// You need to retrieve the store password (storedPWRef).
// Next you compare it with the password just entered by the user.
LONG IF ( FN CFStringCompare( pwRec.passwordTextRef, storedPWRef, 0 ) )
// Tell user that the wrong password has been entered.
EXIT FN
END IF
// Don't forget to release the entered and the retrieved passwords when
// you are done with them using CFRelease( pwRec.passwordTextRef ) and
// CFRelease( storedPWRef ).
SELECT pwRec.result // result of the user action
CASE _noErr
// Here you allow access to whatever you have protected by the
// password.
CASE _pwOption1
err = FN YourPasswordSetting
IF ( err ) THEN EXIT FN // you better do some error checking
// Here you display again the "password setting dialog" to allow
// the user to change the password.
// If no new password has been entered, the old one will be
// removed by the code you have implemented for "CASE _pwOption2"
// in the FN YourPasswordSetting. (see above)
END SELECT
END FN = err
//----------------------------------------------------------------------
* If you prefer to customize the "Password Dialogs", you simply set the
parameters of the record "PasswordRec" to the desired values.
The following templates show all of the options.
(1) Display the dialog for setting a password____**Advanced Approach**
//----------------------------------------------------------------------
CLEAR LOCAL FN YourPasswordSetting // Clearing is necessary !
//----------------------------------------------------------------------
DIM AS OSStatus err
DIM AS PasswordRec @ pwRec
// -- You can specify the object to be protected in the dialog text,
// -- e.g. by setting
pwRec.passwordTextRef = FN CFSTR( "the file" )
// -- You can change the default action button text (Protect), e.g. by
// -- setting
pwRec.actionButtonRef = FN CFSTR( "Set Password" )
err = FN pwPasswordDialog( @pwRec )
IF ( err ) THEN EXIT FN // you better do some error checking
SELECT pwRec.result // result of the user action
CASE _userCanceledErr
EXIT FN
CASE _noErr
// The password is available as CFStringRef: pwRec.passwordTextRef
// You may want to encrypt and then store away the password.
// Don't forget to release the password Ref when you are done with
// it using CFRelease( pwRec.passwordTextRef ).
CASE _pwOption2
// Here you must remove the password from the storage location and
// you must remove the protection of whatever you have protected
// by the password. (see "CASE _pwOption1" below)
END SELECT
END FN = err
//----------------------------------------------------------------------
(2) Display the dialog for checking the password_**Advanced Approach**
//----------------------------------------------------------------------
CLEAR LOCAL FN YourPasswordChecking // Clearing is necessary !
//----------------------------------------------------------------------
DIM AS CFStringRef storedPWRef
DIM AS OSStatus err
DIM AS PasswordRec @ pwRec
// -- You can specify the object to be protected in the dialog text,
// -- e.g. by setting
pwRec.passwordTextRef = FN CFSTR( "This file" )
// -- You can change the default action button text (Open), e.g. by
// -- setting
pwRec.actionButtonRef = FN CFSTR( "Open File" )
// -- You can change the default option button text (Change PW), e.g.
// -- by setting
pwRec.opt1ButtonRef = FN CFSTR( "New Password" )
// -- You can attribute a second function to the "Option" button that
// -- is accessible when the user presses the "Option" key.
// -- It is available if you pass an optional button text, e.g. like
pwRec.opt2ButtonRef = FN CFSTR( "Remove PW" )
// -- For applications where you don't want the user to change or
// -- remove the password, you can set
pwRec.noOptionButton = _zTrue
pwRec.checkMode = _zTrue
err = FN pwPasswordDialog( @pwRec )
IF ( ( err ) OR ( pwRec.result == _userCanceledErr ) ) THEN EXIT FN
// You need to retrieve the store password (storedPWRef).
// Next you compare it with the password just entered by the user.
LONG IF ( FN CFStringCompare( pwRec.passwordTextRef, storedPWRef, 0 ) )
// Tell user that the wrong password has been entered.
EXIT FN
END IF
// Don't forget to release the entered and the retrieved passwords when
// you are done with them using CFRelease( pwRec.passwordTextRef ) and
// CFRelease( storedPWRef ).
SELECT pwRec.result // result of the user action
CASE _noErr
// Here you allow access to whatever you have protected by the
// password.
CASE _pwOption1
err = FN YourPasswordSetting
IF ( err ) THEN EXIT FN // you better do some error checking
// Here you again display the "password setting dialog" to allow
// the user to change the password.
// If the user doesn't enter a new password, the old one will be
// removed by the code you have implemented for "CASE _pwOption2"
// in the FN YourPasswordSetting.
CASE _pwOption2
// -- Do whatever you like to do after the user has left the dialog
// -- by clicking the option button while holding down the option
// -- key.
END SELECT
END FN = err
//----------------------------------------------------------------------
*****************************************************************************
Download the FB source code and the compiled demo app as
"PassWord_Demo.sit.hqx" from the DropBox.
As always, comments are highly welcome!
Best
Herbie
------------------------
<http://www.gluender.de>
(Please send a copy of your remarks directly to me. I'm on List Digest!)