The Private Eye Library (PE) is a share library for PDA Toolbox applications.  It provides security, encryption, and registration related functionality.  The Private Eye library is compatible with both PDAT/Advanced and PDA Toolbox 6.0 Professional.

Many of the actions of the Private Eye Library are based on the idea that buttons or menus in your application have multiple actions defined.  Usually, if an PE action fails, then the actions following the PE are ignored.  For instance, if you wanted to password protect a form, you might have the actions for the button defined as 

pe.AskHardPswd "123",PIN
GotoForm 1500

In this case, if the PIN is not entered, then the action fails and the $GotoForm will not take place.  If successful, then the user goes to form 1500.

Registration actions consist of three pieces: An initialization, registration dialog, a test actions.  For PDA Toolbox versions prior to 5.x there is no "Startup" actions in PDA Toolbox, it's recommended that you have some kind of "splash" screen that handles your registration initialization to force the user to perform it.  For instance, the [OK] or [Start] buttons on a splash screen would actually have something similar to:

pe.HardRegInit "BlueBell"
GotoForm 1100

This way, when the user taps the OK button, the above code is executed and the user proceeds to the "first" actual form.

For versions of PDA Toolbox 5.x and higher, the INIT actions are recommended to be placed in the Startup Script.

It is also used as a "Plug-In" to PDAT/Advanced to provide additional Actions to your PDA Toolbox programs.  PDAT 6.0 Pro requires the Windows "Plug-In" to support the Script Editor.

This manual assumes the reader has familiarity with the PDAT/Advanced application or the PDAT 6.0 Pro Script Editor.

The Private Eye Library is a Shareware Library for the Palm OS 3.1 and above.  This library requires approx. 23k of memory storage.  For more information click here.

The Actions provided by this library are divided into four categories of functionality: Password Protection, Shareware Registration Models, Registration Test Methods, and Other Security Routines.

Password Protection

With these actions, you can create password protected applications.  You can protect the application, entry to a specific form, or a specific function.  As the developer, you can allow the user to change the password or have a "hard-wired" password set by you.  Passwords can be alpha-numeric and entered with a dialog or can be set as a PIN-Keypad style password.

• pe.AskPswd, pe.ChangePswd, pe.ChangePIN,  pe.UserPswd
• pe.AskHardPswd

Shareware Registration Models

There are four Shareware registration models included with this library.  There is a "Classic" ShellReg-compatible model is used for upgrades from a ShellMaker application.  ShellReg is used to generate the keys as normal.  You can also have "hard-wired" model.  This is used to have a single registration key sent to the user.  This key can be issued to the Seller to be issued to the User when a purchase is made.  With the hard-wired model, administration is easy, but security is rather low.  There is a general purpose registration method where the registration keys can be generated on the Windows Desktop.  There are several variations of this model which allow for unique registration keys to be generated.   Finally, another general purpose method has been added to support dynamic generation of keys at PalmGear, Handango, eSellerate, and other online stores.  This method uses the process defined at Handango on the developer's pages.  An annotated copy of the document is included called PEDyn16RegInfo.pdf which helps explain the details of how to use it.

All the registration models, when a success registration is entered, will automatically turn off PDA Toolbox's 30-Demo Mode.  This allows you to optionally send out apps with the 30 day demo, but not have to send "Non-Demo" apps upon registration -- a real time saver!

• pe.ShellRegInit, pe.ShellRegDialog
• pe.HardRegInit, pe.HardRegDialog
• pe.RegInit,  pe.RegDialog
• pe.Dyn16RegInit, pe.Dyn16RegDialog

Registration Test Methods

All the shareware registration methods are able to be tested with these actions.  Each of these test methods tests if the user has registered the app.  If so, then the actions following the test are executed as normal.  If not, then the actions following the test may be ignored.  You can show a "nag" alert and continue execution or you can show the "nag" and stop.  there are three tests available: Test for registration, test if a certain number of database records has been reached, and test if a certain number of runs has been reached.

• pe.IsReg
• pe.DayLimit
• pe.DBLimit
• pe.RunLimit
• pe.TestReg, pe.TestNotReg, pe.TestRegEx

Other Security Routines

With these actions, you can test a variety of additional situations:  Test if your application has been un-beam protected by the user, tests if your app is running on a minimum OS platform, and tests if the user's device is color or black&white.  If any of these fail, then a message is displayed and the following actions may be ignored.

• pe.BeamProtected
• pe.MinOS
• pe.IsScreen
• pe.StartForm

Database Encryption

Before you can use the actions contained in this library, you must first "plug" it into PDAT/Advanced.  Once plugged in and registered, you will be able to use and distribute this library freely.

1. First, install the "PDATPELib.prc" file onto your development handheld.  This should also have a copy of PDAT/Advanced.
2. At PDAT/Advanced's Open Screen, tap the menu and choose from the Advanced menu "Manage Libraries".
3. Next, if the "Private Eye Library" is not shown in the list, tap the "Add" button.
4. In the "Add Library" dialog, enter in the Library ID of "PEye" (without the quotes).
5. Next, enter the license information you received when you registered.
6. Lastly, tap the "Done" button.

After successful registration, when you are editing actions, you'll have a second button named "Lib" which pops up a list of all the commands available to you.

Using With PDA Toolbox 6.0 Pro Script Editor

To use this library with the Pro Script Editor, you need to download the PDA Toolbox Windows Plug-In for Private Eye.  This is available at www.SandsUSA.com/PDAT.  Follow the installation instructions contained within the archive.

The primary difference between using these actions with PDAT/Advanced and the Pro Script Editor is that the Script Editor does not require the leading "$" for each action.  In addition, in PDAT/Advanced, you can can wrap your action statements with carriage-returns and in the Script Editor, you must use the "_" line continuation character.

The file "PDATPELib.prc" must be distributed with any application that uses this library.  Since you are distributing multiple PRC files that must be installed on the hand-held device, you may want to check out Ecamm's NutShell for the Palm OS at http://www.ecamm.com/palm/nutshell.  Nutshell is a unique installer solution, which allows users distribute multiple Palm files and data as a single self-expanding PRC file.  With this tool, the user installs a single file onto their hand-held and the first time your app is run, all the libraries, databases, and sub-programs are automatically unpacked and your app runs.  A very good solution to a sticky problem.

Each Action in the library will be described here.

To use, insert this action before the feature you want to protect.  If the password fails or is canceled, the actions following the password action will not be executed.  If the password is correct, then the following actions will take place.  The protected actions will always have to have a password entered before the actions will execute.

Hard-wired passwords appear the same as a user-password that can't be changed.  However, a hard-wired password can be changed with each compilation of your application and the value stored in your app will be used each time.  With a user-password, once the initial password is given, it is up to the user to maintain it - even if you re-issue your application. 

Alpha-numeric passwords are limited to 20 characters and PINs are limited to 12.  All passwords are case-sensitive.

Alpha-Numeric Password Dialog Any kind of password may be used since passwords are entered by Grafitti. Examples: "Test", "test", "123test", and "5000".

PIN-Keypad Style Password Dialog Only numbers, dash, and a dot may be used as PINs.  Note, the user can also Grafitti in the PIN at the top of the dialog. Corrections can also be done there.  As the user taps buttons, the PIN appears at the top of the dialog. Examples: "123", "123.54.1232", "123-45-678"

PDA Toolbox 6.0 Professional SP5 and higher supports a wakeup event that is executed whenever your application is running and the device is turned on.  You can use the password actions to prevent unauthorized access.

Example of Wakeup Protection (PDAT 6.0 Script):

Action eventWakeup
   pe.AskHardPswdEx "123", PIN, NOT, NOMSG
   ExitApp
EndAction

The NOT tells the action to stop processing the script if the password succeeds.  This way, if it fails, the ExitApp action occurs.  The NOMSG parameter suppresses the failed password message since there may be sensitive info on the screen.

To use, insert this action before the feature you want to protect.  If the password fails or is canceled, the actions following the password action will not be executed.  If the password is correct, then the following actions will take place.  The protected actions will always have to have a password entered before the actions will execute.

Passwords set with this action can be changed by the user with the pe.ChangePswd action.  Passwords cannot be recovered - the user must delete the application and re-enter the password, so make sure you emphasize the need for them to remember it.

Alpha-numeric passwords are limited to 20 characters and PINs are limited to 12.  All passwords are case-sensitive.

Alpha-Numeric Password Dialog Any kind of password may be used since passwords are entered by Grafitti. Examples: "Test", "test", "123test", and "5000".

PIN-Keypad Style Password Dialog Only numbers, dash, and a dot may be used as PINs.  Note, the user can also Grafitti in the PIN at the top of the dialog. Corrections can also be done there.  As the user taps buttons, the PIN appears at the top of the dialog. Examples: "123", "123.54.1232", "123-45-678"

PDA Toolbox 6.0 Professional SP5 and higher supports a wakeup event that is executed whenever your application is running and the device is turned on.  You can use the password actions to prevent unauthorized access.

Example of Wakeup Protection (PDAT 6.0 Script):

Action eventWakeup
   pe.AskPswdEx "123", PIN, checked, NOT, NOMSG, APPTITLE
   ExitApp
EndAction

The NOT tells the action to stop processing the script if the password succeeds.  This way, if it fails, the ExitApp action occurs.  The NOMSG parameter suppresses the failed password message since there may be sensitive info on the screen.  The APPTITLE parameter forces the password dialog to display the app name.

A pretty easy action, this should be on a splash screen or upon entry to an important segment of your application.

It is recommended that you change normal passwords using the pe.ChangePswd action, and change PINs using the pe.ChangePIN.  Although both will change passwords for the other, the .ChangePIN prevents a user from entering letters and locking themselves out of their application.

Alpha-numeric passwords are limited to 20 characters and PINs are limited to 10.  All passwords are case-sensitive.

Change Password and PIN Dialog The user must know their existing password before it will change the password to the new password. The user may also choose to turn off password prompting entirely by checking the "Don't ask for a password" checkbox.

This is a good replacement for PDA Toolbox's built-in "30 Day Demo Mode."  The primary advantage is that when the number of days is reached, the user still has the opportunity to enter a registration code.  With the standard demo mode, you have to send out a new, "release" PRC in order for them to continue.

The message text of the Talt may have two parameters filled in for you to indicate the remaining and total.  This should be similar to "You have ^1 days remaining of ^2."  The ^1 will be filled in with the "remaining days" value, and the ^2 is filled in from the "total days allowed" value.

The Talt that you are required to make can be added to your application's PFA file on the handheld.  When PDAT/Advanced compiles an application, it copies all of the non-pSTR resources into your application.   

Intended to be on an application's primary database, this action will test if the record count is greater than what the developer specifies.  When the user registers, they may then continue to add records to the database.  This can be a good technique to give full functionality but limit the capacity until registered.

The message text of the Talt may have two parameters filled in for you to indicate the remaining and total.  This should be similar to "You have ^1 records remaining out of ^2 records available."  The ^1 will be filled in with the "remaining records" value, and the ^2 is filled in from the "total records allowed" value.

The Talt that you are required to make can be added to your application's PFA file on the handheld.  When PDAT/Advanced compiles an application, it copies all of the non-pSTR resources into your application.

These actions will encrypt or decrypt the entire database.  Encryption is lightweight, however it is based on a 512 bit key generated randomly every time a database is encrypted.  Data integrity is maintained so if an app crashes while databases are unencrypted, when the application starts, it will not attempted to decode data that is already decoded.  Likewise, it will not try to encode data that is already encoded.

Recommended usage: In the startup script, after any Memory Storage Library calls, place your DECRYPT actions for each database.  In the termination script, before any Memory Storage Library calls, place your ENCRYPT actions.

These actions will encrypt or decrypt the entire database.  This encryption must be used in combination with one of the User Password actions or the databases will not be encrypted.  Pro Branching is required.

Recommended usage: In the startup script, after any Memory Storage Library calls, place your DECRYPT actions for each database.  In the termination script, before any Memory Storage Library calls, place your ENCRYPT actions.

pe.DecryptEx returns the following based on if the passwords could unlock all encrypted databases:

• If all databases were decrypted, it will continue to the following action.
• If any databases failed to match the password, it will continue to second action following.

For example:

Action eventStartup
   pe.AskPswdEx "123", PIN, Unchecked
   Goto +2
   Goto +3 
   pe.DecryptEx "MyApp-Data"
   Goto +2 'Success
   ExitApp
EndAction

This will create dynamic keys based on a name.  The exact rpn-expression controls what values your registration code will have.  All registration codes result in a 5 digit number (may have leading zeros).  This is the model used by Handango but, with a minor amount of work, is easily used on PalmGear, eSellerate, and other retail sites that support dynamic code generation.

In Visual Basic, the following routine will generate a code based on a name.  This code can be translated to a variety of languages.

Private Function GenCode(ByVal UserName As String) As String
    Dim I As Integer
    Dim C As Integer
    Dim Key As Long
    Key = 0
    'If the name is longer than 10, then take first and last 5 characters.
    If Len(UserName) > 10 Then
        UserName = Left(UserName, 5) & Right(UserName, 5)
    End If
    'The loop is always zero based.
    For I = 0 To Len(UserName) - 1
        'C is always the ascii value of the character (A = 65)
        C = Asc(Mid(UserName, I + 1, 1))
        'Your formula in algebraic format. Example's RPN = "k c i * +"
        Key = Key + (C * I)
    Next
    'Take the lower 16 bits and pad out with leading "0"
    GenCode = Right("00000" & (Key And &HFFFF), 5)
End Function

NOTE: If you change the rpn-expression, your registration key generation will change and you will have to re-issue your registration code to your users.

Each of these actions should have a corresponding RegInit action of the correct type (e.g. pe.HardRegDialog goes with pe.HardRegInit).  You can only have one registration method per application as they all are tested with the same actions.

Before you can use this routine, the corresponding INIT action must be called first. 

It's recommended that these actions should be attached to a menu item, button, or a button on an About screen. 

This is used to have a single registration key for all users.  This key can be issued to the Seller (e.g. PalmGear or Handango) to be issued to the User when a purchase is made.  With the hard-wired model, administration is easy, but security is rather low.

This tests the app if the user has a password.

To support the branching ability in PDA Toolbox 6.0 Professional Service Pack 6 (SP6), the pe.HasPassword will test and branch based on the following conditions:

• If password, it will continue to the following action.
• If no password, it will continue to second action following.

For example:

Action TestPassword
   pe.HassPassword
   Goto @Yes
   Goto @No

@Yes:
   au.Alert "Password Defined."
   Goto @Continue

@No:
   au.Alert "Password NOT Defined."
   Goto @Continue:

@Continue:

EndAction

This action is used anywhere you want to either nag or prevent a user from functionality in your program.

The Talt that you are required to make can be added to your application's PFA file on the handheld.  When PDAT/Advanced compiles an application, it copies all of the non-pSTR resources into your application.

This is useful if you distribute both a B&W and a Color version, you can alert the user that the version they are running is the wrong one if they are running a B&W version on a color device.  Set second parameter to "Gray" if you want to allow gray-scales.

The message text of the Talt does not take any parameters.  You may have whatever you want it in.

The Talt that you are required to make can be added to your application's PFA file on the handheld.  When PDAT/Advanced compiles an application, it copies all of the non-pSTR resources into your application.   

The message text of the Talt does not take any parameters.  You may have whatever you want it in.

The Talt that you are required to make can be added to your application's PFA file on the handheld.  When PDAT/Advanced compiles an application, it copies all of the non-pSTR resources into your application.   

This is a general purpose Name/Key registration model.  Keys can be generated on the Windows Desktop.  You can key the codes to the device HotSyncID or an arbitrary name.  The advantage of the HotSyncID is that the key will only work with devices with the HotSyncID name so it's harder to copy to other devices.  The advantage of the arbitrary name is that you'll have less support problems if a user gives you the wrong HotSyncID or with the wrong case (e.g. "Bob" is not the same as "BOB"). 

NOTE: If you change the prefix, key, or method, your registration key generation will change and you will have to re-issue your registration code to your users.

To be more accurate, this limits the number of times the action pe.RunLimit executes.  If programmed correctly, then this value will tend to follow the number of times the application is executed.

The message text of the Talt may have two parameters filled in for you to indicate the remaining and total.  This should be similar to "You have ^1 runs remaining out of ^2 runs available."  The ^1 will be filled in with the "remaining runs" value, and the ^2 is filled in from the "total runs allowed" value.

The Talt that you are required to make can be added to your application's PFA file on the handheld.  When PDAT/Advanced compiles an application, it copies all of the non-pSTR resources into your application.   

If you are upgrading your application from using the ShellMaker model to using the new PDA Toolbox and PDAT/Advanced models, then you should at least start with this model of registration in order to stay compatible with your existing users.

Keys are generated only with the ShellReg utility.

This will set the startup form for your application so you can bypass splash or nag screens after registration, or if a registered version is beamed.  This routine must be called after one of the INIT routines.

PDAT STANDARD NOTE: If a registered version is beamed, the user may get in "as registered" the first time, but after this action has been executed, it will be set back to the unregistered mode.  This does not affect the PDAT Professional version.

This tests the app if it is registered (.TestReg) or unregistered (.TestNotReg) and halts execution if the test fails.

In the examples, if the app is registered then pe.TestReg will succeed and display the alert.  If the app is registered then the pe.TestNotReg will fail and the alert will not display.  

If the app is not registered then pe.TestReg will fail and not display the alert.  If the app is not registered then the pe.TestNotReg will succeed and display the alert.

To support the branching ability in PDA Toolbox 6.0 Professional Service Pack 6 (SP6), the pe.TestRegEx will test and branch based on the following conditions:

• If registered, it will continue to the following action.
• If not registered, it will continue to second action following.

For example:

Action TestRegDemo
   pe.TestRegEx
   Goto +2
   Goto +3
   au.Alert "It is registered."
   Goto +2
   au.Alert "It is not registered."
EndAction

Although the user normally controls whether they want a password prompt or not, this command can be useful under certain situations. 

This program is not Freeware.  It is Demoware.  This means that you can, and should, try the demo out before buying.  Shortly after you register via PayPal, PalmGear, or Handango, you will receive an unlock key that will enable developing with this library.

 The cost of this package is US$20.00.  Registered users receive the following:

• DeskReg for Windows: A Windows Registration key generator and management utility compatible with the DeskReg actions.
• ShellReg for the Palm OS: A key generator for the ShellReg actions.
• MyName for the Palm OS: A customizable diagnostic utility you can send your users if they are having trouble determining their HotSync User IDs.

The Official Support Site for the Private Eye Library is at www.PDATNutsAndBolts.com.

You can always contact me at:

email: Rick@SandsUSA.com or at my site http://www.SandsUSA.com.

"The Software" is "Private Eye Library" aka "PDATPELib.prc" by Richard R. Sands dba Sands USA.

DISCLAIMER #1 - MUST READ

This product is an "After-Market" utility for PDA Toolbox(tm) and as such, is subject to obsolescence by changes in PDA Toolbox or the Palm OS(tm) itself.  This cannot be prevented.  I may choose to stop or limit development and support of this product if such situation occurs. 

USER LICENSE AGREEMENT

This Agreement sets forth your licensed rights to use "The Software" and is granted to you upon condition that you accept the terms of this license. Your electronic indication of agreement, or your use of the program constitute acceptance of all of the terms of this license.

The program copy and documentation are furnished to make "The Software" available for your use and remain the property of Sands USA.

IF YOU DO NOT AGREE WITH ANY PART OF THIS LICENSE, DO NOT USE THIS SOFTWARE. Delete "The Software" and all associated files from all media on which it has been copied. 

LICENSE TERMS AND CONDITIONS

THE LICENSED PRODUCT
"The Software" comprises copyrighted computer programs and utilities for the reporting of Palm OS(tm) application databases (PRC) created by the PDA Toolbox(tm) Application Generator. The Licensed Product in its entirety is protected by US and foreign copyright.  YOU MAY NOT DISTRIBUTE THE LICENSE CODE provided to you.

YOUR USE OF THE LICENSED PRODUCT
General Use. You have the right to use "The Software" with PDAT/Advanced and to distribute the library file "PDATPELib.prc" but not documentation, license codes, or other information about this library.  For those purposes, you have the right to install the "The Software" and any associated files on one (1) computer. Use of "The Software" on a network or any other arrangement by which its functions are accessible to more than one user at a time is not permitted. 

LIMITATIONS ON USE
General Use Limitations. You have no right to reproduce, transfer, publish or otherwise distribute either the "The Software" software, or any components or documentation provided.

ALL RIGHTS NOT SPECIFICALLY GRANTED BY THIS LICENSE ARE RESERVED BY SANDS USA. 

WARRANTIES, WARNING, DISCLAIMER

Warning and Disclaimer of All Warranties. THE PROGRAM IS FURNISHED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, IN ALL JURISDICTIONS WHERE ALL WARRANTIES MAY BE DISCLAIMED IN THE LICENSING OF INTELLECTUAL PROPERTY.

PDAT/Advanced, ShellReg, ShellMaker, DeskReg, and MyName is Copyrighed by Richard R. Sands dba Sands USA

PDAT Toolbox is Copyrighted by PDAToolbox.com

Nutshell executable and documentation are Copyright ©2002 by Ecamm Network. All rights reserved.

RsrcEdit is apparently not copyrighted by Quartus, but they are the caretakers of RsrcEdit.

Windows is a Trademark of Microsoft Corporation

Documentation Copyright (C) 2002-2006 Richard R. Sands dba Sands USA
All Rights Reserved

And Finally, ...

Palm, PalmSource, Palm1One, Palm OS, Palm Computing, HandFAX, HandSTAMP, HandWEB, Graffiti, HotSync, iMessager, MultiMail, Palm.Net, PalmPak, PalmConnect, PalmGlove, PalmModem, PalmPoint, PalmPrint, and PalmSource are registered trademarks of Palm, Inc.  Palm, the Palm logo, MyPalm, PalmGear, PalmPix, PalmPower, AnyDay, EventClub, HandMAIL, the HotSync logo, PalmGlove, Palm Powered, the Palm trade dress, Smartcode, Simply Palm, WeSync, and Wireless Refresh are trademarks of Palm, Inc.