WAP Wakeup

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

Wireless Application Protocol (WAP) Wakeup is a feature that provides the benefit of conserving application memory.

Usually, an application is able to receive WAP datagrams only while it is running and resident in memory. In terms of resources, this is impractical for asynchronous applications, which perform work only when processing incoming messages (which arrive at any time — sometimes infrequently). While waiting, this type of application does nothing. Except for the fact that the application still consumes resources (valuable application memory), it is as if it were hibernating. An example is a chess program that processes chess moves sent to it as Wireless Datagram Protocol (WDP) binary datagrams over the Short Message Service (SMS).

Using the WAP Wakeup feature, an asynchronous application can be available to process incoming messages, yet be neither running nor loaded in memory. When a WDP port receives a WDP Short Message Service (SMS) message, and the port has not been "opened" by an application (that is, registered with the WDP layer), the WDP provider searches the registry for the WAP Wakeup registered application associated with that port and automatically starts it. The application opens an Application Listener Window Class, which receives a message from the WDP provider (the DWORD value "WDP Port. Interpreting this message as a signal that a WDP message is waiting for it on the port, the application opens that port on the WDP layer. The application then receives and processes the WDP Short Message Service (SMS) message.

Remarks

WDP provides port-based addressing. The port number is used by the wakeup mechanism to route datagrams to the correct higher-layer entity (such as a protocol or application) above the WDP layer. The wakeup mechanism allows applications to register for messages on a particular port by including the port number in the event name. You must provide a unique key for each WDP port you want to register with your application. The wakeup mechanism is for WAP datagrams over Short Message Service (SMS) only. Only applications can be triggered by the Wakeup feature (for example, you cannot use the feature as a paging mechanism).

You cannot register your application for a WDP port range; you must register for each port individually. To avoid collisions, you must ensure that multiple applications do not register for the same port. When you register a port for you application, you must determine whether another application already "owns" the port. When choosing a WDP port number, be sure to keep the number of ports to a minimum, and follow the guidelines on WDP port usage. For more information, see "Wireless Datagram Protocol (WDP) Specification" at this OMA Web site.

To use WAP Wakeup with your application, you need to add a key like the following one to the system registry:

HKLM\Software\Microsoft\Shell\Event\Network\WDP\WDPportX\appName

The key must contain four values, which are detailed in the following table.

Key name Key value Value type Description

"Class"

class string

String

The destination window for the WDP/Short Message Service (SMS) message (Application Listener Window Class).

"Command"

WDP Client Application Path

String

The application's fully qualified path name.

"NotifyOnLaunch"

1

DWORD

A flag that indicates that messages associated with the WDP port are to be posted to the Application Listener Window Class.

> [!NOTE] > Without this key, the application is still started, but no messages are posted to the Application Listener Window Class.

WDP Port

Value of the message posted to the window

DWORD

A registry port/window message pair.

The name of the registry key represents the WDP port. The DWORD value represents the window message that will be posted to the Application Listener Window Class.

> [!NOTE] > You must ensure that messages are mapped to the WDP port.

For a complete example, see "Example: Registering a Chess Application" later in this topic.

Example: Registering a Chess Application

The following example demonstrates how to register a chess application for wakeup notification when chess moves (WDP messages) arrive on WDPport1 or WDPport2.

HKLM\Software\Microsoft\Shell\Event\Network\WDP\WDPport1\chess
    "Class" = REG_SZ: ListenerWnd
    "Command" = REG_SZ: chess.exe
    "NotifyOnLaunch" = REG_DWORD: 1
    WDPport1 = REG_DWORD: application message, such as the value of WM_APP+Num1.
HKLM\Software\Microsoft\Shell\Event\Network\WDP\WDPport2\chess
    "Class" = REG_SZ: ListenerWnd
    "Command" = REG_SZ: chess.exe
    "NotifyOnLaunch" = REG_DWORD: 1
    WDPport2 = REG_DWORD: application message, such as the value of WM_APP+Num2.

Requirements

Windows Embedded CE Windows CE .NET 4.2 and later
Windows Mobile Pocket PC for Windows Mobile 2003 and later, Smartphone for Windows Mobile 2003 and later

See Also

Concepts

Short Message Service (SMS) API
Wireless Application Protocol (WAP) API