WAP Wakeup Using a Generic Application Wakeup API (Windows Embedded CE 6.0)

1/6/2010

This feature allows applications to shutdown and then resume or launch when a WAP packet (binary datagrams) arrive over Short Message Service (SMS). You implement this feature by using an generic application wakeup/notify model or by using the API.

API

The system registry exposes the interface. You need a unique key for the entries in the following table for each port that an application registers for a WAP wakeup. The port number in decimal form must be present in the registry key itself.

[HKLM\Software\Microsoft\Shell\Event\Network\WDP\<port 1>\<app key>]
...
[HKLM\Software\Microsoft\Shell\Event\Network\WDP\<port2>\<app key >]
...

The following table shows the registry entries.

Value : type	Description
Class : string	Application Listener Window Class, which is the destination window for the WDP/SMS message
Command : string	WDP client application path for launching the application when it is inactive.
NotifyOnLaunch : dword	Messages associated with the WDP port that will be posted to Listener Window Class when the WDP message arrives. If the application is not registered with the WDP Layer, then the message will be posted. If the application is not loaded, then the application will be launched. If key is not present in the registry and the application is not active, then the application will be launched, but no messages will be posted to the Listener Window Class.
<WDP Port > : dword	Represents the window message that will be posted to the window of the Listener Window class specified. This registry value is a port and window message pair. The <WDP Port > represents the WDP port, The application is responsible for mapping the message to the WDP port number.

Examples

Chess Application:

The following example shows how a sample application registers to be notified and launched a WDP message arrives on either <WDPport1> or <WDPport2>.

HKEY_LOCAL_MACHINE\Software\Microsoft\Shell\Event\Network\WDP\<WDPport1>\chess
   "Class"=string:ListenerWnd
   "Command"=string:chess.exe
   "NotifyOnLaunch"=dword:1
   "<WDPport1>"=dword:<app msg e.g. value of WM_APP+Num1>

HKEY_LOCAL_MACHINE\Software\Microsoft\Shell\Event\Network\WDP\<WDPport2>\chess
   "Class"=string:ListenerWnd
   "Command"=string:chess.exe
   "NotifyOnLaunch"=dword:1
    "<WDPport2>"=dword:<app msg e.g. value of WM_APP+Num2>

The following scenario outlines the sequence of events for a chess application.The application Chess.exe is closed but it must be able to receive WDP SMS messages on the WDPport1 and WDPport2.

1. Create the registry setting.
2. A WDP SMS messages arrives at the WDP layer on port WDPport1.
3. The WDP layer checks if the application is registered with the WDP layer on Port Number WDPport1. In this case, no application is registered.
4. The application checks the registry to determine if any application is registered for WDP messages on Port WDPport1., The application finds that Chess.exe application is registered.
5. If Chess.exe is loaded, the application launches Chess.exe.
6. The chess application opens "ListenerWnd" Listener Window Class.
7. "ListenerWnd" receives a message with DWORD value <WM_APP+Num1>
8. Chess.exe recognizes this message as an indication that a WDP message is awaiting on port WDPport1 and registers WDPport1 as it's own with the WDP layer.
9. Chess.exe receives and processes the awaiting WDP message.
10. Chess.exe closes.

Client Application Design FAQ

Q: How do you resolve collision if multiple applications register for the same port?

A: Applications must check the registry on their own to ensure that they 'own' the port.

Q: Can applications register for a port range?

A: No, applications must register each port individually.

Q: When a WDP/UDP datagram arrives, can it launch or notify an application?

A: No, an application can only be launched or notified when WDP datagrams arrive on the SMS bearer.

Q: Can I use any WDP port number?

A: The number of ports used should be kept at a minimum. The guidelines on WDP port usage set in the WDP specification should be followed. You can find the guideline on the WAP forum, currently www.wapforum.org.

Network

The following list shows the supported networks:

• Any network that supports WAP over SMS.
• Currently only GSM

See Also

Concepts

WAP Wakeup