WinPeekMsg: Difference between revisions

Latest revision as of 21:12, 8 April 2025

This function inspects the thread's message queue and returns to the application with or without a message.

Syntax

WinPeekMsg(hab, pqmsg, hwndFilter, ulFirst, ulLast, flOptions)

Parameters

hab (HAB) - Input

Anchor-block handle.

pqmsg (PQMSG) - Output

Message structure.

Note: If the function returns FALSE, the state of the QMSG structure is undefined. Applications should always check the return code before examining this structure.

hwndFilter (HWND) - Input

Window filter.

ulFirst (ULONG) - Input

First message identity.

ulLast (ULONG) - Input

Last message identity.

flOptions (ULONG) - Input

Options.

If neither of the following flags is specified, the message is not removed. If both of the following flags are specified, the message is removed

PM_REMOVE: Remove message from queue
PM_NOREMOVE: Do not remove message from queue.

Returns

rc (BOOL) - Returns

Message-available indicator.

TRUE: Message available
FALSE: No message available.

Remarks

This function is identical to the WinGetMsg function, except that it does not wait for the arrival of a message. The message can be left on the queue, by using flOptions.

For details of hwndFilter, ulFirst, and ulLast, see the WinGetMsg function.

The window handle within pqmsg is null if the message is posted to the queue with a hwnd that is null.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_HWND (0x1001) An invalid window handle was specified.
PMERR_INVALID_FLAG (0x1019) An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.

Example Code

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

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

rc = WinPeekMsg(hab, pqmsg, hwndFilter, ulFirst,
       ulLast, flOptions);

This example uses WinPeekMsg to count the total number of pending messages for the window corresponding to hwndFilter.

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

HAB     hab;            /* anchor-block handle                  */
QMSG    qmsg;           /* message                              */
HWND    hwndFilter;     /* message queue filter                 */
ULONG   flOptions;      /* peek options                         */
ULONG   ulMsgCount=0;   /* message count                        */

/* don't remove messages */
flOptions = PM_NOREMOVE;

/* count number of messages for filter window */
while (WinPeekMsg (hab, &qmsg, hwndFilter, 0, 0, flOptions))
   ulMsgCount++;

Related Functions

@@ Line 6: / Line 6: @@
 ==Parameters==
 ;hab ([[HAB]]) - Input: Anchor-block handle.
-;pqmsg ([[PQMSG]]) - Output: Message structure.
+;pqmsg (P[[QMSG]]) - Output: Message structure.
 :;'''Note:''' If the function returns FALSE, the state of the QMSG structure is undefined. Applications should always check the return code before examining this structure.
 ;hwndFilter ([[HWND]]) - Input: Window filter.