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:

ABM_NEW

0x00

ABM_REMOVE

0x01

ABM_QUERYPOS

0x02

ABM_SETPOS

0x03

ABM_GETSTATE

0x04

ABM_GETTASKBARPOS

0x05

ABM_ACTIVATE

0x06

ABM_GETAUTOHIDEBAR

0x07

ABM_SETAUTOHIDEBAR

0x08

ABM_WINDOWPOSCHANGED

0x09

ABM_SETSTATE

0x0A

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.

This page was created on 8th April 2007 and was last modified
on 17th April 2007.