Programming Microsoft Windows Ce Net 3Rd [Electronic resources] نسخه متنی

The CeUtil Functions

ActiveSync uses the PC registry to store voluminous amounts of information about the Windows CE devices that have partnered with the PC. ActiveSync also uses the registry to store extensive configuration information. While most of these registry keys are documented, if you access them by name you're assuming that those key names will always remain the same. This might not be the case, especially in international versions of Windows where registry keys are sometimes in a different language.

The CeUtil DLL exports functions that provide an abstraction layer over the registry keys used by ActiveSync. Using this DLL allows a PC application to query the devices that are currently registered and to add or delete registry values underneath the keys that hold data for specific devices. The CeUtil DLL doesn't communicate with a remote Windows CE device; it only looks in the PC registry for information that has already been put there by ActiveSync.

The keys in the registry related to ActiveSync are separated into either HKEY_LOCAL_MACHINE, for generic configurations such as the initial configuration for a newly registered device, or HKEY_CURRENT_USER, where the configuration information for the already registered devices is located. When a new device is registered, ActiveSync copies the template in HKEY_LOCAL_MACHINE to a new subkey under HKEY_CURRENT_USER that identifies the specific device.

In general, you register a new filter in the keys under HKEY_ LOCAL_MACHINE to ensure that all devices that are registered in the future also use your filter. You use the registry entries under HKEY_CURRENT_USER to register that filter for a specific device that was already registered before you installed that same filter.

Accessing ActiveSync Registry Entries

To open one of the many registry keys that hold connection information, you can use this function:

HRESULT CeSvcOpen (UINT uSvc, LPTSTR pszPath, BOOL fCreate,
PHCESVC phSvc);

The first parameter of this function is a flag that indicates which predefined key you want to open. Here are the available flags:

The following are keys under HKEY_LOCAL_MACHINE that apply to generic Windows CE Services configuration information.

CESVC_ROOT_MACHINEActiveSync root key under HKEY_LOCAL_MACHINE

CESVC_FILTERSRoot key for filter registration

CESVC_CUSTOM_MENUSRoot key for custom menu registration

CESVC_SERVICES_COMMONRoot key for services

CESVC_SYNC_COMMONRoot key for synchronization services registration

The following are keys under HKEY_CURRENT_USER that apply to specific Windows CE devices that are partnered with the PC.

CESVC_ROOT_USERActiveSync root key under HKEY_LOCAL_USER

CESVC_DEVICESRoot key for individual device registration

CESVC_DEVICEXRoot key for a specific device

CESVC_DEVICE_SELECTEDRoot key for the device currently selected in the ActiveSync window

CESVC_SERVICES_USERRoot services subkey for a specific device

CESVC_SYNCSynchronization subkey for a specific device

Of the many registry keys that can be returned by CeSvcOpen, the ones I'll be using throughout the chapter are CESVC_FILTERS, the key in which a filter is registered for all future devices; CESVC_DEVICES, the key in which information for all registered devices is located; and CESVC_DEVICEX, which is used to open keys for specific registered devices. The other flags are useful for registering synchronization objects as well as for registering general ActiveSync configuration information.

The second parameter to CeSvcOpen is pszPath. This parameter points either to the name of a subkey to open underneath the key specified by the uSvc flag or to a DWORD value that specifies the registered Windows CE device that you want to open if the uSvc flag requires that a device be specified. The fCreate parameter should be set to TRUE if you want to create the key being opened because it currently doesn't exist. If this parameter is set to FALSE, CeSvcOpen fails if the key doesn't already exist in the registry. Finally, the phSvc parameter points to a CESVC handle that receives the handle of the newly opened key. Although this isn't typed as a handle to a registry key (an HKEY), the key can be used in both the CeUtil registry functions and the standard registry functions.

CeSvcOpen returns a standard Win32 error code if the function fails. Otherwise, the key to the opened registry key is placed in the variable pointed to by phSvc.

You can open registry keys below those opened by CeSvcOpen by calling CeSvcOpenEx. This function is prototyped as

HRESULT CeSvcOpenEx (HCESVC hSvcRoot, LPTSTR pszPath, BOOL fCreate,
PHCESVC phSvc);

The parameters for this closely mirror those of RegOpenKey. The first parameter is a handle to a previously opened key. Typically, this key would have been opened by CeSvcOpen. The second parameter is the string that specifies the name of the subkey to be opened. Notice that since we're running on the PC, this string might not be a Unicode value. The fCreate parameter should be set to TRUE if you want the key to be created if it doesn't already exist. Finally, the phSvc parameter points to a CESVC handle that receives the handle to the opened key.

When you have finished with a key, you should close it with a call to this function:

HRESULT CeSvcClose (HCESVC hSvc);

The only parameter is the handle you want to close.

Enumerating Registered Devices

Of course, the requirement to specify the device ID value in CeSvcOpen begs the question of how you determine what devices have already been partnered with the PC. To determine this, you can use the function

HRESULT CeSvcEnumProfiles (PHCESVC phSvc, DWORD lProfileIndex,
PDWORD plProfile);

The first parameter to CeSvcEnumProfiles is a pointer to a CESVC handle. The handle this parameter points to is uninitiated the first time the function is called. The function returns a handle that must be passed in subsequent calls to CeSvcEnumProfiles. The second parameter is an index value. This value should be set to 0 the first time the function is called and incremented for each subsequent call. The final parameter is a pointer to a DWORD that receives the device ID for the registered device. You can use this value when you're calling CeSvcOpen to open a registry key for that device.

Each time the function is called, it returns NOERROR if a new device ID is returned. When all devices have been enumerated, CeSvcEnumProfiles returns ERROR_NO_MORE_ITEMS. You should be careful to continue calling CeSvcEnumProfiles until the function returns ERROR_NO_MORE_ITEMS so that the enumeration process will close the handle parameter pointed to by phSvc. If you want to stop enumerating after you've found a particular device ID, you'll need to call CeSvcClose to close the hSvc handle manually.

The following routine enumerates the Windows CE devices that have been registered on the PC. The program enumerates all the registered Windows CE devices and prints out the name and device type of each of the devices. The program uses the function CeSvcGetString, which I'll describe shortly.

int PrintCeDevices (void) {
HCESVC hSvc, hDevKey;
TCHAR szName[128], szType[64];
DWORD dwPro;
int i;
// Enumerate each registered device.
i = 0;
while (CeSvcEnumProfiles (&hSvc, i++, &dwPro) == 0) {
// Open the registry key for the device enumerated.
CeSvcOpen (CESVC_DEVICEX, (LPTSTR)dwPro, FALSE, &hDevKey);
// Get the name and device type strings.
CeSvcGetString (hDevKey, TEXT ("DisplayName"),
szName, dim(szName));
CeSvcGetString (hDevKey, TEXT ("DeviceType"),
szType, dim(szType));
// Print to the console.
printf (TEXT ("Name: %s\t\tType: %s"), szName, szType);
// Close the key opened by CeSvcOpen.
CeSvcClose (hDevKey);
}
return i-1;         // Return the number of devices found.
}

Reading and Writing Values

The remainder of the CeUtil library functions concern reading and writing values in the registry. In fact, you can skip these functions and use the registry functions directly, but the CeSvcxxx functions are a bit simpler to use. These functions allow you to read and write three of the data types used in the registry: DWORD, string, and binary data. These just happen to be the only data types used in the values under the ActiveSync keys. The functions are all listed here:

HRESULT CeSvcGetDword (HCESVC hSvc, LPCTSTR pszValName,
LPDWORD pdwVal);
HRESULT CeSvcSetDword (HCESVC hSvc, LPCTSTR pszValName,
DWORD dwVal);
HRESULT CeSvcGetString (HCESVC hSvc, LPCTSTR pszValName,
LPTSTR pszVal, DWORD cbVal);
HRESULT CeSvcSetString (HCESVC hSvc, LPCTSTR pszValName,
LPCTSTR pszVal);
HRESULT CeSvcGetBinary (HCESVC hSvc, LPCTSTR pszValName,
LPBYTE pszVal, LPDWORD pcbVal);
HRESULT CeSvcSetBinary (HCESVC hSvc, LPCTSTR pszValName,
LPBYTE pszVal, DWORD cbVal);

The parameters for these functions are fairly self-explanatory. The first parameter is the handle to an open key. The second parameter is the name of the value being read or written. The third parameter specifies the data or a pointer to where the data will be written. The fourth parameter on some of the functions specifies the size of the buffer for the data being read or, in the case of CeSvcSetBinary, the length of the data being written.

One final function in the CeUtil library is

HRESULT CeSvcDeleteVal (HCESVC hSvc, LPCTSTR pszValName);

This function, as you might expect, lets you delete a value from the registry. The parameters are the handle to an open key and the name of the value to be deleted.

The CeUtil library doesn't provide any function that you couldn't do yourself with a bit of work and the standard registry functions. However, using these functions frees you from having to depend on hard-coded registry key names that could change in the future. I strongly advise using these functions whenever possible when you're accessing registry entries that deal with ActiveSync.