WinRegisterUserDatatype: Difference between revisions

Latest revision as of 11:23, 18 April 2025

This function registers a data type and defines its structure.

Syntax

WinRegisterUserDatatype(hab, datatype, count, types)

Parameters

hab (HAB) - Input

Anchor-block handle.

datatype (LONG) - Input

Data type code to be defined.

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

count (LONG) - Input

Number of elements.

Must not be less than one.

types (PLONG) - Input

Data type codes of structure components.

Valid data types are the system-defined data types and their pointer equivalents, application-defined data types and their pointer equivalents, and control data types. Note that not all of the data types that occur in the CPI can be specified on this function.

A control data type is followed by one or more entries in the types array that are interpreted in a special way. Control data types allow arrays, offsets, and lengths to be defined.

Simple Data Types:

DTYP_ATOM - See ATOM.

DTYP_BIT16 - See USHORT.

DTYP_BIT32 - See ULONG.

DTYP_BIT8 - See UCHAR.

DTYP_BOOL - See BOOL.

DTYP_COUNT2 - See USHORT.

DTYP_COUNT2B - See USHORT.

DTYP_COUNT2CH - See USHORT.

DTYP_COUNT4B - See ULONG.

DTYP_CPID - See USHORT.

DTYP_ERRORID - See ERRORID.

DTYP_IDENTITY - See USHORT.

DTYP_IDENTITY4 - See ULONG.

DTYP_INDEX2 - See USHORT.

DTYP_IPT - See IPT.

DTYP_LENGTH2 - See USHORT.

DTYP_LENGTH4 - See ULONG.

DTYP_LONG - See LONG.

DTYP_OFFSET2B - See USHORT.

DTYP_PID - See PID.

DTYP_PIX - See PIX.

DTYP_PROGCATEGORY - See PROGCATEGORY.

DTYP_PROPERTY2 - See USHORT.

DTYP_PROPERTY4 - See LONG.

DTYP_RESID - See HMODULE.

DTYP_SEGOFF - See SEGOFF.

DTYP_SHORT - See SHORT.

DTYP_TID - See TID.

DTYP_TIME - See LONG.

DTYP_UCHAR - See UCHAR.

DTYP_ULONG - See ULONG.

DTYP_USHORT - See USHORT.

DTYP_WIDTH4 - See LONG.

DTYP_WNDPROC - See PFNWP.

Handle Data Types:

DTYP_HAB - See HAB.

DTYP_HACCEL - See HACCEL.

DTYP_HAPP - See HAPP.

DTYP_HATOMTBL - See HATOMTBL.

DTYP_HBITMAP - See HBITMAP.

DTYP_HDC - See HDC.

DTYP_HENUM - See HENUM.

DTYP_HINI - See HINI.

DTYP_HLIB - See HLIB.

DTYP_HMF - See HMF.

DTYP_HMQ - See HMQ.

DTYP_HPOINTER - See HPOINTER.

DTYP_HPROGRAM - See HPROGRAM.

DTYP_HPS - See HPS.

DTYP_HRGN - See HRGN.

DTYP_HSEM - See HSEM.

DTYP_HSPL - See HSPL.

DTYP_HSWITCH - See HSWITCH.

DTYP_HWND - See HWND.

Character/String/Buffer Data Types:

DTYP_BYTE - See BYTE.

DTYP_CHAR - See CHAR.

DTYP_STRL - See PSZ.

DTYP_STR16 - See STR16.

DTYP_STR32 - See STR32.

DTYP_STR64 - See STR64.

DTYP_STR8 - See STR8.

Structure Data Types:

DTYP_ACCEL - See ACCEL.

DTYP_ACCELTABLE - See ACCELTABLE.

DTYP_ARCPARAMS - See ARCPARAMS.

DTYP_AREABUNDLE - See AREABUNDLE.

DTYP_BITMAPINFO - See BITMAPINFO.

DTYP_BITMAPINFOHEADER - See BITMAPINFOHEADER.

DTYP_BTNCDATA - See BTNCDATA.

DTYP_CATCHBUF - See CATCHBUF.

DTYP_CHARBUNDLE - See CHARBUNDLE.

DTYP_CLASSINFO - See CLASSINFO.

DTYP_CREATESTRUCT - See CREATESTRUCT.

DTYP_CURSORINFO - See CURSORINFO.

DTYP_DEVOPENSTRUC - See DEVOPENSTRUC.

DTYP_DLGTEMPLATE - See DLGTEMPLATE.

DTYP_DLGTITEM - See DLGTITEM.

DTYP_ENTRYFDATA - See ENTRYFDATA.

DTYP_FATTRS - See FATTRS.

DTYP_FFDESCS - See FFDESCS.

DTYP_FIXED - See FIXED.

DTYP_FONTMETRICS - See FONTMETRICS.

DTYP_FRAMECDATA - See FRAMECDATA.

DTYP_GRADIENTL - See GRADIENTL.

DTYP_HCINFO - See HCINFO.

DTYP_IMAGEBUNDLE - See IMAGEBUNDLE.

DTYP_KERNINGPAIRS - See KERNINGPAIRS.

DTYP_LINEBUNDLE - See LINEBUNDLE.

DTYP_MARGSTRUCT - See MLEMARGSTRUCT.

DTYP_MARKERBUNDLE - See MARKERBUNDLE.

DTYP_MATRIXLF - See MATRIXLF.

DTYP_MLECTLDATA - See MLECTLDATA.

DTYP_OVERFLOW - See MLEOVERFLOW.

DTYP_OWNERITEM - See OWNERITEM.

DTYP_POINTERINFO - See POINTERINFO.

DTYP_POINTL - See POINTL.

DTYP_PROGRAMENTRY - See PROGRAMENTRY.

DTYP_PROGTYPE - See PROGTYPE.

DTYP_QMSG - See QMSG.

DTYP_RECTL - See RECTL.

DTYP_RGB - See RGB.

DTYP_RGNRECT - See RGNRECT.

DTYP_SBCDATA - See SBCDATA.

DTYP_SIZEF - See SIZEF.

DTYP_SIZEL - See SIZEL.

DTYP_SWBLOCK - See SWBLOCK.

DTYP_SWCNTRL - See SWCNTRL.

DTYP_SWENTRY - See SWENTRY.

DTYP_SWP - See SWP.

DTYP_TRACKINFO - See TRACKINFO.

DTYP_USERBUTTON - See USERBUTTON.

DTYP_WNDPARAMS - See WNDPARAMS.

DTYP_WPOINT - See WPOINT.

DTYP_WRECT - See WRECT.

DTYP_XYWINSIZE - See XYWINSIZE.

Pointer Data Type:

DTYP_P*: Pointer to an item of data type DTYP_*, where DTYP_* is one of the data types in the preceding lists. The value of a pointer data type is the value of the corresponding non-pointer data type prefixed with a minus to make it negative.

Minimum Application Data Type:

DTYP_USER: Minimum value for application-defined non-pointer data types.

Control Data Type:

DTYP_CTL_ARRAY

This starts a sequence of three array elements that define an array; the array resides in the structure being defined, and may have a fixed number of elements or a variable number of elements.

The following describes the possible elements:

n - DTYP_CTL_ARRAY

n+1 - data type of array data.

n+2 - minus the number of elements in the array (for an array of fixed size), or the index of the element in types corresponding to the structure component which contains the number of elements in the array being defined. This component must have a suitable numeric data type. The array-size element must recede element 'n' in types. The index is zero-based.

DTYP_CTL_LENGTH

This starts a sequence of four array elements that define a structure component containing the length of part or all of the structure. The length component resides at this point in the structure.

The following describes the possible elements:

n - DYP_CTL_LENGTH

n+1 - data type of structure component that contains the length (must be a suitable numeric data type).

n+2 - the index of the element in types corresponding to the first structure component that is included in the length; a value of -1 denotes the start of the structure. This index is zero-based. The element specified must not be one that is the second or subsequent element in a DTYP_CTL_* sequence of elements.

N+3 - the index of the element in types corresponding to the last structure component that is included in the length; it must not be less than the value contained in element n+2. A value of -1 denotes the end of the structure. The index is zero-based. The element specified must not be one that is the second or subsequent element in a DTYP_CTL_* sequence of elements. If the value is -1, the length includes all offset data residing at the end of the structure.

DTYP_CTL_OFFSET

This starts a sequence of four array elements that define data addressed by an offset. The offset resides at this point in the structure, and contains the offset in bytes of the data from the start of the outermost structure in which this component resides. The data addressed by the offset must occupy storage following the fixed part of the structure. The data may be scalar data or array data.

The following describes the possible elements:

n - DTYP_CTL_OFFSET

n+1 - data type of the structure component that contains the offset (must be a suitable unsigned numeric data type).

n+2 - data type of offset data.

n+3 - minus the number of elements in the array (for an array of fixed size), or the index of the element in types corresponding to the structure component that contains the number of elements in the array being defined; this component must have a suitable numeric data type; the array-size element may occur earlier or later in the structure. This index is zero-based. A value of -1 indicates that the data is not an array.

DTYP_CTL_PARRAY

This starts a sequence of three array elements that define a pointer to an array. The pointer resides at this point in the structure, and the array resides elsewhere. The array can have a fixed or variable number of elements.

The following describes the possible elements:

n - DTYP_CTL_PARRAY

n+1 - data type of array data.

n+2 - minus the number of elements in the array (for an array of fixed size) or the index of the element in types corresponding to the structure component that contains the number of elements in the array being defined. This component must have a suitable numeric data type. The array-size element may occur earlier or later in the structure. The index is zero-based.

Returns

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion.

FALSE - Error occurred.

Remarks

This function has no effect unless the RegisterUserHook hook has been set.

The value to be used should be obtained by calling WinAddAtom with the handle of the system atom manager, and subtracting DTYP_ATOM_OFFSET from the result.

WinAddAtom is guaranteed to return values in the range 0xC000 to 0xFFFF.

When a data type is defined using this function, a definition for the corresponding pointer data type is automatically established.

Errors

Possible returns from WinGetLastError:

PMERR_DATATYPE_TOO_SMALL (0x1048) - The datatype specified was too small.
PMERR_DATATYPE_NOT_UNIQUE (0x1046) - An attempt to register a datatype failed because it is not unique.
PMERR_ARRAY_TOO_SMALL (0x103E) - The array specified was too small.
PMERR_DATATYPE_ENTRY_NOT_NUM (0x1043) - The datatype entry specified was not numerical.
PMERR_DATATYPE_ENTRY_NOT_OFF (0x1044) - The datatype entry specified was not an offset.
PMERR_DATATYPE_ENTRY_BAD_INDEX (0x103F) - An invalid datatype entry index was specified.
PMERR_DATATYPE_ENTRY_CTL_MISS (0x1041) - The datatype entry control was missing.
PMERR_DATATYPE_ENTRY_CTL_BAD (0x1040) - An invalid datatype entry control was specified.

Example Code

This example calls WinRegisterUserDatatype to register a class or returns FALSE if an error occurs.

#define INCL_WINMESSAGEMGR
#define INCL_WINTYPES
#include <OS2.H>
#define DTYP_MINE DTYP_USER + 1

HAB hab;
LONG  asTypes[3] = {DTYP_CHAR,
                    DTYP_STRL,
                    DTYP_STR32};

WinRegisterUserDataType(hab,
                        DTYP_MINE,
                        3,
                        asTypes);

Related Functions