WinGetMsg

Retrieves messages from its message queue.

This function gets, waiting if necessary, a message from the thread's message queue and returns when a message conforming to the filtering criteria is available.

Syntax

WinGetMsg(hab, pqmsgmsg, hwndFilter, ulFirst, ulLast);

Parameters

hab (HAB) - input

Anchor-block handle.

pqmsgmsg (PQMSG) - output

Message structure.

hwndFilter (HWND) - input

Window filter.

ulFirst (ULONG) - input

First message identity.

ulLast (ULONG) - input

Last message identity.

Returns

rc (BOOL) - returns

Continue message indicator.

TRUE

Message returned is not a WM_QUIT message

FALSE

Message returned is a WM_QUIT message.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

Remarks

If system or queue hooks are installed, they are called before this function returns.

rc is generally used to determine when to terminate the application's main loop and exit the program.

hwndFilter constrains the returned message to be for a specific window or its children. When hwndFilter is null, the returned message can be for any window. The message identity is restricted to the range of message identities specified by ulFirst and ulLast inclusive. When ulFirst and ulLast are both zero, any message satisfies the range constraint. When ulFirst is greater than ulLast, messages except those whose identities lie between ulFirst and ulLast are eligible to be returned. Messages that do not conform to the filtering criteria remain in the queue.

When hwndFilter is null, and ulFirst and ulLast are both zero, all messages are returned in the order that they were posted to the queue.

By using filtering, messages can be processed in an order that is different from the one in the queue. Filtering is used in situations where applications receive messages of a particular type, rather than having to deal with other types of message at an inconvenient point in the logic of the application. For example, when a "mouse down" message is received, filtering can be used to wait for the "mouse up" message without having to be concerned with receiving other messages.

These constants can also be used when filtering messages:

WM_MOUSEFIRST Lowest value pointing device message 
WM_MOUSELAST Highest value pointing device message 
WM_BUTTONCLICKFIRST Lowest value pointing device button click message 
WM_BUTTONCLICKLAST Highest value pointing device button click message 
WM_DDE_FIRST Lowest value DDE message 
WM_DDE_LAST Highest value DDE message. 

Great care must be taken if filtering is used, to ensure that a message that satisfies the specification of the filtering parameters can occur, otherwise this function cannot complete. For example, calling this function with ulFirst and ulLast equal to WM_CHAR and with hwndFilter set to a window handle that does not have the input focus, prevents this function from returning.

Keystrokes are passed to the WinTranslateAccel call, which implies that accelerator keys are translated into WM_COMMAND or WM_SYSCOMMAND messages, and so are not seen as WM_CHAR messages by the application.

Note: An application must be prepared to receive messages other than those documented in this publication. All messages that an application does not want to handle should be dispatched to the appropriate window procedure using the WinDispatchMsg function.

Sample Code

#define INCL_WINMESSAGEMGR /* Or use INCL_WIN, INCL_PM, Also in COMMON section */
#include <os2.h>

HAB      hab;         /*  Anchor-block handle. */
PQMSG    pqmsgmsg;    /*  Message structure. */
HWND     hwndFilter;  /*  Window filter. */
ULONG    ulFirst;     /*  First message identity. */
ULONG    ulLast;      /*  Last message identity. */
BOOL     rc;          /*  Continue message indicator. */

rc = WinGetMsg(hab, pqmsgmsg, hwndFilter,
       ulFirst, ulLast);

This example uses WinGetMsg to continually loop and retrieve messages from the message queue until a WM_QUIT message occurs.

#define INCL_WINMESSAGEMGR      /* Window Message Functions     */
#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#include <os2.h>

HAB     hab;            /* anchor-block handle                  */
HMQ     hmq;            /* message queue handle                 */
PQMSG   pqmsgmsg;       /* message                              */

hab = WinInitialize(0);          /* initialize PM */

hmq = WinCreateMsgQueue(hab, 0); /* create default size queue */

/*
.
.  initialize windows
.
*/

/* get and dispatch messages from queue */
while (WinGetMsg(hab, &qmsgmsg, 0, 0, 0))
   WinDispatchMsg(hab, &qmsgmsg);

Related Functions

• WinBroadcastMsg
• WinCancelShutdown
• WinCreateMsgQueue
• WinDestroyMsgQueue
• WinDispatchMsg
• WinGetDlgMsg
• WinGetMsg
• WinInSendMsg
• WinPeekMsg
• WinPostMsg
• WinPostQueueMsg
• WinQueryMsgPos
• WinQueryMsgTime
• WinQueryQueueInfo
• WinQueryQueueStatus
• WinSendDlgItemMsg
• WinSendMsg
• WinSetClassMsgInterest
• WinSetMsgInterest
• WinSetMsgMode
• WinSetSynchroMode
• WinWaitMsg

Related Messages

• WM_CHAR
• WM_QUIT
• WM_SYSCOMMAND