Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function registers a persistent request for change notifications. The specified application receives a notification when the specified value changes.

Syntax

HRESULT WINAPI RegistryNotifyApp( 
  HKEY 
hKey,
  LPCTSTR 
pszSubKey,
  LPCTSTR 
pszValueName,
  LPCTSTR 
pszName,
  LPCTSTR 
pszApp,
  LPCTSTR 
pszClass,
  LPCTSTR 
pszWindow,
  UINT 
msg,
  DWORD 
dwFlags,
  NOTIFICATIONCONDITION* 
pCondition
);

Parameters

hKey

[in] Handle to the open key or a predefined root value.

pszSubKey

[in] Key where the value is stored. If this value is NULL, then pszValueNameis assumed to be under hkey.

pszValueName

[in] Named value on which the notification is based. If the value is NULL, the change notification will be based on the default value.

pszName

[in] Unique user defined string that represents the notification request. You should pass this string to RegistryStopNotificationwhen you want the notification to stop. This name is unique for each notification request. To prevent collisions between applications, you can use the following format: ApplicationName.EventName.

pszApp

[in] Path to the executable to launch.

pszClass

[in] Class type of the window that will receive the notification.

If pszClassand pszWindoware set to NULL, then the function will only launch the executable.

pszWindow

[in] Name of the window that that will receive the notification.

If pszClassand pszWindoware NULL, then the function will only launch the executable.

msg

[in] Message passed to the window specified by pszClassand pszWindow.

dwFlags

[in] Notification flags.

This value must be 0 or RNAF_NONAMEONCMDLINE. If the value is 0,

/notify "pszName"

will be appended to the command line when the application is launched. Use RNAF_NONAMEONCMDLINE to suppress appending any parameters on the command line.

pCondition

[in] Condition that determines when to send the notification. When the comparison between pConditionand the new registry value is TRUE, then a notification is sent.

If pConditionis NULL, then any change in the specified registry value results in a notification.

Return Value

The following table shows the return values for this function.

Value Description

S_OK

Request for change notification is registered .

E_ALREADY_REGISTERED

A notification with the same name as passed in pszNamealready exists .

E_INVALIDARG

Invalid hKey, pszApp,or pszName.

Remarks

Success indicates that the caller will be notified every time the specified value changes and the specified condition are true. Failure does not cause any change.

To stop notifications, the caller must call RegistryStopNotification, otherwise the notification request is permanent. Even if the device is reset, the notification will remain active until RegistryStopNotificationis called.

On notification, RegistryNotifyAppdetermines if the executable that is specified in pszAppis already running by searching for the window that is specified in pszClassand pszWindow.If the executable is not running, the function launches the executable. The command passed to the executable must be specified in pszAppstring. If the path to the executable in pszAppcontains spaces, the pszAppstring should include quotes around the entire path.

Copy Code
TCHAR szApp[] = TEXT("\"\\Program Files\\myApp\\myApp.exe\"");

The message specified in msgis posted to the window by the Notifications Broker, which uses PostMessage. The following table shows the parameters passed to PostMessage.

Variable names Description

WPARAM

For data type REG_DWORD, the new value (or zero if the value was deleted), and zero (0 ) for all other data types.

LPARAM

Zero (0)

For each client to differentiate between multiple notifications, the msgparameter must be unique for each call to RegistryNotifyApp.

The client gets a notification when values are added or when values are changed. If one of the following conditions exists when the notification arrives, the notification will be removed:

  • The executable specified in pszAppcannot be launched.

  • The window specified in pszClassand pszWindowcannot be found after the executable specified in pszAppwas launched.

  • The PostMessagefunction fails.

This function can be used to monitor any registry key in the system. The header file snapi.h contains definitions for the registry keys, paths, values, and bitmasks for all the base notifications that are provided by the system.

If the key specified by hKeyand pszSubKeydoesn't exist, then hKeyis monitored until pszSubKeyis created, after which pszSubKeyis monitored and changes to the key will trigger notifications as requested. To minimize possible performance degradation stemming from a large nuimber of subkeys being monitored, it is a best practice to pass (as hKey) the handle to a key that's as close as possible to pszSubKeyrather than passing a root key. For example, if the client is a game and it is monitoring the key structure HKEY_CURRENT_USER\...\MyCoolGame\Player1 and the game could later create HKEY_CURRENT_USER\...\MyCoolGame\Player2, two possible ways to approach notification of changes to the Player2 key include:

Potential performance degradation Fewer potential problems

hKey= handle to HKEY_CURRENT_USER and pszSubKey=the full path to Player2

hKey= handle to HKEY_CURRENT_USER\...\MyCoolGame\ and pszSubKey=Player2

Code Example

The following code example demonstrates how to use RegistryNotifyApp.

Note:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
Copy Code
HRESULT RegistryNotifyAppExample()
{
	NOTIFICATIONCONDITION nc;
	HRESULT hr = S_OK;
	// The notification name must be unique across the device.
	// It is considered good practice to prefix this name with the
name of your application.
	TCHAR szNotificationName[] = TEXT("myAppCradled"); 
	TCHAR szAppName[]		= TEXT("myApp.exe param1 param2");
	// Receive notifications whenever the device is cradled.
	nc.ctComparisonType = REG_CT_EQUAL;
	nc.TargetValue.dw   = 1;
	// Since you are not masking, dwMask must be non-zero for
dwords.
	nc.dwMask = 0xFFFFFFFF;  
	// The application is launched from the command line with:
myApp.exe param1 param2 /notify "myAppCradled".
	hr = RegistryNotifyApp(SN_CRADLEPRESENT_ROOT, 
						 SN_CRADLEPRESENT_PATH, 
						 SN_CRADLEPRESENT_VALUE, 
						 szNotificationName, 
						 szAppName, 
						 NULL, 
						 NULL, 
						 0, 
						 0, 
						 &nc);
	// When you are done, call RegistryStopNotification to remove
the notification.
	// hr = RegistryStopNotification(szNotificationName);
	return hr;
}

Requirements

Header regext.h
Library aygshell.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also