SHAppBarMessage

Declaration

UINT_PTR
SHAppBarMessage (
    DWORD dwMessage,
    PAPPBARDATA pData);

Parameters

The dwMessage argument loosely describes the operation to perform with the information in the APPBARDATA structure addressed by the pData argument. The following are the values that EXPLORER.EXE recognises for dwMessage:

If dwMessage is any of ABM_QUERYPOS, ABM_SETPOS or ABM_GETTASKBARPOS, then the APPBARDATA structure is not only for input but may also be changed for output.

Return Value

The function itself returns NULL to indicate failure, but in general, the function returns whatever is returned from sending the input data to the taskbar window. Interpretation varies with dwMessage.

Behaviour (SHELL32)

Though SHELL32 implements the function, its role is just that of a switchboard, to direct the call to the taskbar. If there is no top-level window with the class name expected of the taskbar, namely “Shell_TrayWnd”, then the function has nowhere to send the request, and fails.

If the cbSize member of a supposed APPBARDATA structure at the address pData is too large (specifically, is more than 0x24), then the function rejects the input as implausible, and fails.

The taskbar may be, and typically is, implemented in another process. The input is sent to the taskbar window as a WM_COPYDATA message. Whatever is returned from sending this message is then returned by the function.

A variation applies when dwMessage is one of those that are expected to produce output. Since the WM_COPYDATA message provides only a one-way transfer, the function first copies the input to shared memory and includes with the message some extra parameters so that the taskbar window can access the shared memory and write into it. The function fails if it cannot set up this shared memory before sending the message or if it cannot retrieve the shared memory afterwards.

Behaviour (EXPLORER)

What the taskbar window does with the passed data is presently beyond the scope of these notes.

Availability

The SHAppBarMessage function is exported by name in all known SHELL32 versions. It has long been documented.

This is an ancient SHELL32 function. It is found in version 1.30 from Win32s and 3.51 from Windows NT 3.51, though admittedly with implementations that fail trivially (returning NULL having done nothing but set ERROR_CALL_NOT_IMPLEMENTED as the error code). The function has been “live” since version 4.00.