Let Me In: Pocket PC User Interface Password Redirect Sample

This article describes what to do to implement a custom password tool (redirect) for a Pocket PC device, and provides sample code to demonstrate the concept.

NOTE: The power-on password functionality may not function predictably on some devices. This is because the original equipment manufacturer of the device may change the StartUI component in some ways, which may change the behavior of the component or your ability to modify it.

The "Let Me In" sample replaces the standard Pocket PC password user interface with a doodle grid. The user can specify a pattern that connects the grid points by drawing on the grid in the Settings tool. After the password tool is enabled, and after the device is powered-on, the user must enter the pattern before any other tasks can be performed.

NOTE: Although the user sees the password tool in Settings, you (the developer) see the tool in the control panel.


MORE INFORMATION

Creating a Password Tool

To create a password tool (also known as applet), follow these steps:
1. Create a DLL project that outputs a module named Password.cpl.
2. Implement and export the CPlApplet() function to create the new tool.

Use the CheckPassword function, the SetPassword function, and the SetPasswordActive function to set the platform password settings. Use this password for two things that must be considered:

a. The ActiveSync desktop component can request this password when the device tries to connect.
b. The device can request this password during power-on before any other operations can be performed.
3. Implement and export the PromptForPasswd() function. This function displays the power-on password interface.
4. Create a .cpl file association in the device registry. This is required for some other critical registry keys to work correctly:
[HKCR\.cpl]
(default) = "cplfile"

[HKCR\cplfile\Shell\Open\Command]
(default) = "\Windows\ctlpnl.exe %1"
Microsoft also recommends the following optional keys for completeness:
[HKCR\cplfile]
(default) = ""

[HKCR\cplfile\DefaultIcon]
(default) = ","
5. Set the location of the redirect password module in the device registry.
[HKLM\ControlPanel\Password]
"Redirect" = "\windows\password.cpl"
NOTE: You must name the module Password.cpl for the module to be backward compatible with earlier versions of the Pocket PC platform.
6. NEW TO POCKET PC 2002: set the password request timeout policy in the device registry:
[HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Shell]
"ActivePeriod"=DWORD:
This minutes value determines how long the device must be off continuously before power-on prompts for the password. A value of 0 (zero) indicates that the device always prompts for the password. That is, if this value is not 0 (zero), and the device is not turned off for the specified period of time, the password dialog does not appear when you resume the device. The control panel tool can provide a user interface to make this user-configurable.

Special Functions

The SetPassword Function

This Pocket PC function sets the system password to a new string.

BOOL SetPassword(
LPWSTR lpszOldPassword,
LPWSTR lpszNewPassword );


Parameters

lpszOldPassword. The current device password. This determines whether the user or program has permission to call this function. Specify NULL if there currently is no password set.

lpszNewPassword. The new password that you want. Specify NULL to remove the current password without setting a new one.

Return Values

TRUE indicates that the change of password was successful.
FALSE indicates that the change of password was not successful.
The SetPasswordActive Function
This Pocket PC function enables or disables the password.

BOOL SetPasswordActive(
BOOL bActive,
LPWSTR lpszPassword );


Parameters

bActive. TRUE enables the password. FALSE disables the password.

lpszPassword. The current device password. This determines whether the user or program has permission to call this function.

Return Values

TRUE indicates that activation of the password was successful.
FALSE indicates that activation of the password was not successful.

When active, this password can be used by the StartUI component and ActiveSync to control access to the device. In the case of ActiveSync, this function results in a password prompt that appears on the desktop. The StartUI component prompts for this password if the power-on password is enabled by means of the following registry setting:

[HKCU\ControlPanel\Owner]
"PowrPass"=REG_BINARY:
A flag-byte value of 0x01 enables the power-on prompt. A value of 0x00 disables the power-on prompt.
The GetPasswordActive Function
This Pocket PC function indicates whether the current password is active.

BOOL GetPasswordActive( void );


Return Values

TRUE indicates that the password is active.
FALSE indicates that the password is not active.

The PromptForPasswd Function
This function is implemented by the password redirect module and is called by the operating system to prompt the user for a password.

LPTSTR PromptForPasswd(
HWND hwndParent,
BOOL fTightSecurity );


Parameters

hwndParent. The handle of the parent window. Make any password window a descendant of this window.

fTightSecurity. Always set this to TRUE. This parameter is currently reserved.

Return Values

A password string that will be validated by the operating system. This string must be allocated with LocalAlloc and will be freed by the operating system.

Back to the top
The LetMeIn.exe Download
NOTE: To make the code easier to read in the sample, error checking in the sample is not comprehensive.

The following file is available for download from the Microsoft Download Center:
DownloadDownload LetMeIn.exe now (http://download.microsoft.com/download/wince/sample/1.0/wce/en-us/letmein.exe)
Release Date: 06-June-2002

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:
119591 (http://support.microsoft.com/kb/119591/EN-US/) How to Obtain Microsoft Support Files from Online Services
Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file.

The LetMeIn.exe file contains 19 files of varying sizes.

File name Size in KB
EULA.txt 2
LetMeIn.def 1
LetMeIn.ico 1
LetMeIn.rc 3
LetMeIn.vcb 49
LetMeIn.vcl 3
LetMeIn.vco 49
LetMeIn.vcp 36
LetMeIn.vcw 1
LmiDialog.cpp 16
LmiDialog.h 1
LmiDoodler.cpp 11
LmiDoodler.h 1
LmiGlobals.cpp 1
LmiGlobals.h 1
LmiMain.cpp 3
LmiWindows.h 1
ReadMe.txt 7
Resource.h 1

APPLIES TO
• Microsoft Windows CE Platform Software Development Kit for Handheld PC 2000
• Microsoft Windows CE Platform Software Development Kit for Handheld PC 2000


Keywords:
kbinfo kbfile KB314989

http://support.microsoft.com/default.aspx?scid=kb;en-us;314989