Share via


Receiving and Dispatching Messages (Windows Embedded CE 6.0)

1/6/2010

To receive messages, call the GetMessage function. Typically, an application calls GetMessage inside the window message loop.

The following code example shows a message loop that calls GetMessage.

while (GetMessage(&msg, NULL, 0, 0)) 
{
    TranslateMessage(&msg);
    DispatchMessage(&msg);
}

When a thread calls GetMessage, Windows Embedded CE examines the thread message queue for incoming messages. Windows Embedded CE processes messages in the following order:

  1. Windows Embedded CE checks for messages placed on the queue by the SendMessage function. After the system removes the message from the queue, it dispatches the message to the appropriate window procedure from within the GetMessage function. This guarantees that the sending and receiving message queues remain synchronized. The receiver must call GetMessage for the sent messages to be processed.
  2. If no sent message is found, Windows Embedded CE checks for messages placed on the queue by a call to the PostMessage function.
  3. If no posted message is found, Windows Embedded CE checks the queue for messages posted by the user-input system.
    By processing user-input messages at a lower priority, the system guarantees that each input message and all posted messages that result from it are processed completely before moving on to the next input message.
  4. If no posted input messages are found, Windows Embedded CE checks the queue for WM_QUIT messages placed on the queue by a call to the PostQuitMessage function.
  5. If no posted quit messages are found, Windows Embedded CE checks the queue for WM_PAINT messages that were placed on the queue by the windowing system.
  6. If no paint messages are found, Windows Embedded CE checks the queue for WM_TIMER messages placed on the queue by the timer system.

When GetMessage receives any of the previous messages, it returns the message content. The thread must call the DispatchMessage function to dispatch the message to the correct window procedure. If the message is a WM_QUIT message, the return value of GetMessage is zero, which causes the thread to end its message loop.

The system dispatches messages in the GetMessage call of the message loop, and the application dispatches messages by calling the DispatchMessage function in the message loop.

You might need to process messages that you receive from GetMessage before you send them out by using DispatchMessage. The most common processing functions are the TranslateMessage, TranslateAccelerator, and IsDialogMessage functions. Some of these functions can dispatch messages internally, because the application no longer needs to call DispatchMessage in the main message loop.

You usually call TranslateMessage before DispatchMessage. TranslateMessage determines which characters go with keyboard messages. TranslateMessage also posts the characters to the message queue to be picked up on the next pass of the message loop.

To intercept keyboard messages and generate menu commands, call the TranslateAccelerator function. Call the IsDialogMessage function to ensure the proper operation of modeless dialog boxes.

The following code example shows a message loop that uses DispatchMessage, TranslateMessage, TranslateAccelerator, and IsDialogMessage in addition to GetMessage. The call to IsDialogMessage in the code example uses the HWND for the modeless dialog box that is currently active. The window handle of the modeless dialog box that is currently active should be tracked in a global variable by your application if you are using multiple modeless dialog boxes in your application.

while (GetMessage(&msg, NULL, 0, 0)) 
{
    if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg)) 
    {
        if (hwndDLGCurrent != NULL || !IsDialogMessage(hwndDLGCurrent, 
                                                       &msg)) 
        {
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
    }
}

You can remove a message from its queue by using the GetMessage function. Call the PeekMessage function to examine a message without removing it from its queue. This function fills an MSG structure with information about the message. Use PeekMessage carefully, because it does not block the waiting for a message event, which enables an application to continue running regardless of messages in the queue. In a Windows Embedded CE–based application, if an application does not block the waiting for a message or some other event, the kernel cannot shift the CPU into low-power mode, which can drain the device batteries quickly.

When processing messages, Windows Embedded CE supports both system-defined messages and application-defined messages. System-defined messages have message identifiers ranging from 0 through 0x3ff. Messages with message identifiers ranging from 0x400 through 0x7fff are available for application-defined messages. Windows Embedded CE defines the message number 0x400 as WM_USER. If you want to define a custom message for your application, define the message as an offset from WM_USER. The following code example shows how to define a custom message.

#define WM_MYNEWMESSAGE       (WM_USER + 999)

There are two types of system-defined messages: general window messages, which are used for all windows, and special-purpose messages, which apply to a particular class of windows. General window messages cover a wide range of information and requests, including messages for input device and keyboard input, as well as window creation and management.

The prefix of the symbolic constant for the message generally identifies the category to which the message belongs. For example, all general window messages start with WM, whereas messages that apply only to button controls start with BM.

The following table shows Windows Embedded CE message types.

Message type Description

BM

Button message

BN

Button notification

CB

Combo box message

CBN

Combo box notification

CDM

Common dialog box message

CDN

Common dialog box notification

CPL

Control panel message

DB

Object store message

DM

Dialog box default command button message

DTM

Date and time picker and Hypertext Markup Language (HTML) viewer messages

DTN

Date and time picker notification

EM

Edit control message

EN

Edit control notification

HDM

Header control message

HDN

Header control notification

IMN

Input context message

LB

List box control message

LBN

List box notification

LINE

Line device message

LVM

List view message

LVN

List view notification

MCM

Month calendar message

MCN

Month calendar notification

NM

Messages sent by a variety of controls

PBM

Progress bar message

PSM

Property sheet message

PSN

Property sheet notification

RB

Rebar message

RBN

Rebar notification

SB

Status bar window message

SBM

Scroll bar message

STM

Static bar message

STN

Static bar notification

TB

Toolbar message

TBM

Trackbar message

TBN

Trackbar notification

TCM

Tab control message

TCN

Tab control notification

TVM

Tree-view message

TVN

Tree-view notification

UDM

Up-down control message

UDN

Up-down control notification

WM

General window messages

You can define messages for use by the window of your application. If you create messages, be sure that the window procedure that receives them interprets and processes them correctly. The OS does not interpret application-defined messages.

Occasionally, you need to use messages to communicate with windows that are controlled by other processes. In such a situation, call the RegisterWindowMessage function to register a message identifier. The message number that is returned is guaranteed to be unique throughout the system. By using this function, you prevent the conflicts that can arise if different applications use the same message identifier for different purposes.

Windows Embedded CE does not support hooking messages, because the extra processing that is required by hooks can impair the performance of Windows Embedded CE–based devices.

When handling messages in your application, be aware of the WM_HIBERNATE message. Windows Embedded CE defines a WM_HIBERNATE message to notify an application when system resources run low. When an application receives this message, it should attempt to release as many resources as possible. The system checks memory status at five-second intervals. Every Windows Embedded CE–based application that uses even moderate amounts of system resources should implement a handler for the WM_HIBERNATE message. If an application window is not visible, the application cannot receive a WM_HIBERNATE message. The application cannot receive the WM_HIBERNATE message because the WM_HIBERNATE message is sent only to applications that have a button on the taskbar, which is the case for visible windows only. A hidden window will not get this message, even if it is a top-level, overlapped window.

See Also

Concepts

Working with Windows and Messages

Other Resources

GWES Application Development