WinRegisterUserMsg

This function registers a user message and defines its parameters.

Syntax

WinRegisterUserMsg(hab, msgid, datatype1, dir1, datatype2, dir2, datatyper)

Parameters

hab (HAB) - Input

Anchor-block handle.

msgid (ULONG) - Input

Message identifier.

This must not be less than WM_USER, and must not have been defined previously.

datatype1 (LONG) - Input

Data type of message parameter 1.

Valid data types are listed below. For data types that are shorter than 4 bytes, the data must be placed in the least-significant bytes, with the most significant bytes nullified (unsigned data types) or signed-extended (signed data types).

DTYP_BIT16: See BIT16 data type.
DTYP_BIT32: See BIT32 data type.
DTYP_BIT8: See BIT8 data type.
DTYP_BOOL: See BOOL data type.
DTYP_LONG: See LONG data type.
DTYP_SHORT: See SHORT data type.
DTYP_UCHAR: See UCHAR data type.
DTYP_ULONG: See ULONG data type.
DTYP_USHORT: See USHORT data type.
DTYP_P*: A pointer to a system data type. Note that not all of the system data types that exist in the CPI are valid.
< -DTYP_USER: A pointer to a user data type. The user data type must have already been defined via WinRegisterUserDatatype.

dir1 (LONG) - Input

Direction of message parameter 1.

If the message parameter is a pointer, the direction values listed below apply to the contents of the storage location pointed at, as well as to the message parameter itself.

RUM_IN: Input parameter (inspected by the recipient of the message, but not altered).
RUM_OUT: Output parameter (altered by the recipient of the message, without inspecting its value first).
RUM_INOUT: Input/output parameter (inspected by the recipient of the message, and then altered).

datatype2 (LONG) - Input: Data type of message parameter 2.; See the description of datatype1.
dir2 (LONG) - Input: Direction of message parameter 2.; See the description of dir1.
datatyper (LONG) - Input: Data type of message reply.; See the description of datatype1. The message reply is always an output parameter.

Returns

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion.
FALSE: Error occurred.

Remarks

This function has no effect unless the RegisterUserHook hook, which is invoked by this function, has been set.

It is an error to attempt to register the same message identifier more than once within a single OS/2 process.

Errors

Possible returns from WinGetLastError:

PMERR_MSGID_TOO_SMALL (0x104F) - The message identifier specified is too small.
PMERR_DATATYPE_INVALID (0x1045) - An invalid datatype was specified.
PMERR_DATATYPE_TOO_LONG (0x1047) - The datatype specified was too long.

Example Code

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

HAB      hab;        /*  Anchor-block handle. */
ULONG    msgid;      /*  Message identifier. */
LONG     datatype1;  /*  Data type of message parameter 1. */
LONG     dir1;       /*  Direction of message parameter 1. */
LONG     datatype2;  /*  Data type of message parameter 2. */
LONG     dir2;       /*  Direction of message parameter 2. */
LONG     datatyper;  /*  Data type of message reply. */
BOOL     rc;         /*  Success indicator. */

rc = WinRegisterUserMsg(hab, msgid, datatype1,
       dir1, datatype2, dir2, datatyper);

This example uses the WinRegisterUserMsg call to register a user-defined message and define its parameters.

#define INCL_WINMESSAGEMGR
#define INCL_WINTYPES
#include <OS2.H>
#define WM_MY_MESSAGE WM_USER + 11

HAB hab;

WinRegisterUserMessage(hab,
                       WM_MY_MESSAGE,
                       DTYP_BIT16,  /* param1 is a USHORT */
                       RUM_INOUT,   /* param1 is input/output */
                       DTYP_BIT16,  /* param2 is a USHORT */
                       RUM_INOUT,   /* param2 is input/output */
                       DTYP_BIT16); /* reply is a USHORT */

Related Functions