Let Me In: Pocket PC User Interface Password Redirect Sample

Article translations Article translations
Article ID: 314989 - View products that this article applies to.
This article was previously published under Q314989
Expand all | Collapse all

On This Page

SUMMARY

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:
    1. The ActiveSync desktop component can request this password when the device tries to connect.
    2. 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) = "<description>"

    [HKCR\cplfile\DefaultIcon]
    (default) = "<module-name>,<icon-resource-id>"
  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:<minutes>
    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:<flag-byte>
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.

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:
Collapse this imageExpand this image

Download
Download LetMeIn.exe now
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 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.

Collapse this tableExpand this table
File nameSize in KB
EULA.txt2
LetMeIn.def1
LetMeIn.ico1
LetMeIn.rc3
LetMeIn.vcb49
LetMeIn.vcl3
LetMeIn.vco49
LetMeIn.vcp36
LetMeIn.vcw1
LmiDialog.cpp16
LmiDialog.h1
LmiDoodler.cpp11
LmiDoodler.h1
LmiGlobals.cpp1
LmiGlobals.h1
LmiMain.cpp3
LmiWindows.h1
ReadMe.txt7
Resource.h1

Properties

Article ID: 314989 - Last Review: August 9, 2004 - Revision: 4.2
APPLIES TO
  • Microsoft Windows CE Platform SDK for Pocket PC 2002
  • Microsoft Windows CE Platform SDK for Pocket PC
Keywords: 
kbfile kbinfo KB314989
Retired KB Content Disclaimer
This article was written about products for which Microsoft no longer offers support. Therefore, this article is offered "as is" and will no longer be updated.

Give Feedback

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com