AbortDoc to CreateWindowEx


AbortDoc

This function stops the current print job.

At a Glance

Header file | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int AbortDoc(HDC handle);

Parameters

hdc
[in] Handle to the device context (DC) for the print job.

Return Values

A value greater than zero indicates success. SP_ERROR indicates failure. To get extended error information, call GetLastError.

Remarks

Applications should call the AbortDoc function to stop a print job if an error occurs, or to stop a print job after the user cancels that job. To end a successful print job, an application should call the EndDoc function.

If Print Manager was used to start the print job, calling AbortDoc erases the entire spool job, so that the printer receives nothing. If Print Manager was not used to start the print job, the data may already have been sent to the printer. In this case, the printer driver resets the printer (when possible) and ends the print job.

See Also

EndDoc , SetAbortProc, StartDoc


AddFontResource

This function adds the font resource from the specified file to the Windows font table. The font can subsequently be used for text output by any Windows-based application.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int AddFontResource(LPCTSTR lpszFilename);

Parameters

lpszFilename
[in] Long pointer to a null-terminated string that contains a valid font file filename. The file name can specify a font resource file (.fon), a raw bitmap font file (.fnt), a raw TrueType file (.ttf), a TrueType resource file (.fot), or a TrueType collection file (.ttc).

Return Values

The number of fonts added indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Any application that adds or removes fonts from the system font table should notify other windows of the change by sending a WM_FONTCHANGE message to all top-level windows in the operating system. The application should send this message by calling the SendMessage function and setting the hwnd parameter to HWND_BROADCAST.

When an application no longer needs a font resource that it loaded by calling the AddFontResource function, it must remove the resource by calling the RemoveFontResource function.

Windows CE versions 2.0 and later support systems that use either TrueType or raster fonts but not both. The font type is chosen at system design time, and cannot be changed by an application.

Windows CE versions 1.0 and 1.01 support only raster fonts.

See Also

RemoveFontResource, SendMessage


AdjustWindowRectEx

This function calculates the required size of the rectangle of a window with extended style based on the desired client-rectangle size. The window rectangle can then be passed to the CreateWindowEx function to create a window whose client area is the desired size.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL AdjustWindowRectEx( LPRECT lpRect, DWORD dwStyle,
BOOL bMenu, DWORD dwExStyle );

Parameters

lpRect
Long pointer to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-right corners of the window to accommodate the desired client area.
dwStyle
Specifies the window styles of the window whose required size is to be calculated.
bMenu
Boolean that specifies whether the window has a menu.
dwExStyle
Specifies the extended style of the window whose required size is to be calculated.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The bMenu parameter must be FALSE; menu bars are not supported.

A client rectangle is the smallest rectangle that completely encloses a client area. A window rectangle is the smallest rectangle that completely encloses the window, which includes the client area and the nonclient area.

The AdjustWindowRectEx function does not add extra space when a menu bar wraps to two or more rows.

See Also

CreateWindowEx, RECT


AppendMenu

This function appends a new item to the end of the specified menu. You can use AppendMenu to specify the content, appearance, and behavior of the menu item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL AppendMenu(HMENU hMenu, UINT uFlags, UINT idNewItem,
LPCTSTR lpszNewItem);

Parameters

hMenu
[in] Handle to the menu bar, drop-down menu, submenu, or shortcut menu to be changed.
uFlags
[in] Specifies flags to control the appearance and behavior of the new menu item. This parameter can be a combination of the values listed in the following Remarks section.
uIDNewItem
[in] Specifies either the identifier of the new menu item or, if the uFlags parameter is set to MF_POPUP, the handle to the drop-down menu or submenu.
lpNewItem
[in] Long pointer to the content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter includes the MF_OWNERDRAW or MF_STRING flag, as follows:
Value
Description
MF_OWNERDRAW | Contains a 32-bit value supplied by the application that can be used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASURE or WM_DRAWITEM message sent when the menu is created or its appearance is updated.
MF_STRING | Contains a pointer to a null-terminated string.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

To get keyboard accelerators to work with bitmap or owner-drawn menu items, the owner of the menu must process the WM_MENUCHAR message.

The following flags can be set in the uFlags parameter:

MF_CHECKED
Places a check mark next to the menu item.
MF_ENABLED
Enables the menu item so it can be selected, and restores it from its grayed state.
MF_GRAYED
Disables the menu item and grays it so it cannot be selected.
MF_MENUBARBREAK
Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.

Windows CE versions 1.0 and 1.01 do not support this flag.

MF_MENUBREAK
Places the item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.

Windows CE versions 1.0 and 1.01 do not support this flag.

MF_OWNERDRAW
Specifies that the item is an owner-drawn item. Before the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message to retrieve the width and height of the menu item. The WM_DRAWITEM message is then sent to the window procedure of the owner window whenever the appearance of the menu item must be updated.
MF_POPUP
Specifies that the menu item opens a drop-down menu or submenu. The uIDNewItem parameter specifies the handle to the drop-down menu or submenu. This flag is used to add a menu name to a menu bar, or a menu item that opens a submenu to a drop-down menu, submenu, or shortcut menu.

Windows CE versions 1.0 and 1.01 do not support this flag.

MF_SEPARATOR
Draws a horizontal dividing line. This flag is used only in a drop-down menu, submenu, or shortcut menu. The line cannot be grayed, disabled, or highlighted. The lpNewItem and uIDNewItem parameters are ignored.
MF_STRING
Specifies that the menu item is a text string; the lpNewItem parameter points to the string.
MF_UNCHECKED
Does not place a check mark next to the item (default).

The following groups of flags cannot be used together:

  • MF_ENABLED and MF_GRAYED
  • MF_STRING and MF_OWNERDRAW
  • MF_MENUBARBREAK and MF_MENUBREAK
  • MF_CHECKED and MF_UNCHECKED

Windows CE version 1.0 does not support cascading menus. If you are using Windows CE version 1.0, you cannot insert an MF_POPUP menu into another pop-up menu. In Windows CE versions 2.0 and later, cascading menus are supported.

See Also

CreateMenu, DeleteMenu, DestroyMenu, InsertMenu, RemoveMenu


BeginDeferWindowPos

This function allocates memory for a multiple-window position structure and returns the handle to the structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

HDWP BeginDeferWindowPos( int nNumWindows);

Parameters

nNumWindows
Specifies the initial number of windows for which to store position information. The DeferWindowPos function increases the size of the structure, if necessary.

Return Values

If the function succeeds, the return value identifies the multiple-window—position structure. NULL indicates that insufficient system resources are available to allocate the structure. To get extended error information, call GetLastError.

Remarks

The multiple-window—position structure is an internal structure; an application cannot access it directly.

DeferWindowPos fills the multiple-window—position structure with information about the target position for one or more windows about to be moved. The EndDeferWindowPos function accepts the handle to this structure and repositions the windows by using the information stored in the structure.

If any of the windows in the multiple-window—position structure have the SWP_HIDEWINDOW or SWP_SHOWWINDOW flag set, none of the windows are repositioned.

If the system must increase the size of the multiple-window—position structure beyond the initial size specified by the nNumWindows parameter but cannot allocate enough memory to do so, the system fails the entire window positioning sequence (BeginDeferWindowPos, DeferWindowPos, and EndDeferWindowPos). By specifying the maximum size needed, an application can detect and process failure early in the process.

See Also

DeferWindowPos, EndDeferWindowPos


BeginPaint

This function prepares the specified window for painting and fills a PAINTSTRUCT structure with information about the painting.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HDC BeginPaint( HWND hwnd, LPPAINTSTRUCT lpPaint);

Parameters

hwnd
Handle to the window to be repainted.
lpPaint
Long pointer to the PAINTSTRUCT structure that will receive painting information.

Return Values

The handle to a display device context for the specified window indicates success. NULL indicates that no display device context is available.

Windows NT: To get extended error information, call GetLastError.

Remarks

The BeginPaint function automatically sets the clipping region of the device context to exclude any area outside the update region. The update region is set by the InvalidateRect function and by the system after sizing, moving, creating, scrolling, or any other operation that affects the client area. If the update region is marked for erasing, BeginPaint sends a WM_ERASEBKGND message to the window.

An application should not call BeginPaint except in response to a WM_PAINT message. Each call to BeginPaint must have a corresponding call to the EndPaint function.

If the caret is in the area to be painted, BeginPaint automatically hides the caret to prevent it from being erased.

If the window’s class has a background brush, BeginPaint uses that brush to erase the background of the update region before returning.

See Also

EndPaint, InvalidateRect, PAINTSTRUCT, ValidateRect


BitBlt

This function transfers pixels from a specified source rectangle to a specified destination rectangle, altering the pixels according to the selected raster operation (ROP) code.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL BitBlt(HDC hdcDest, int nXDest, int nYDest, int nWidth, int nHeight,
HDC hdcSrc, int nXSrc, int nYSrc, DWORD dwRop);

Parameters

hdcDest
[in] Handle to the destination device context.
nXDest
[in] Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.
nYDest
[in] Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.
nWidth
[in] Specifies the logical width of the source and destination rectangles.
nHeight
[in] Specifies the logical height of the source and the destination rectangles.
hdcSrc
[in] Handle to the source device context.
nXSrc
[in] Specifies the logical x-coordinate of the upper-left corner of the source rectangle.
nYSrc
[in] Specifies the logical y-coordinate of the upper-left corner of the source rectangle.
dwRop
[in] Specifies a raster-operation code. These codes define how the color data for the source rectangle is to be combined with the color data for the destination rectangle to achieve the final color.

The following list shows some common raster operation codes:
Value
Description
BLACKNESS | Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT | Inverts the destination rectangle.
MERGECOPY | Merges the colors of the source rectangle with the specified pattern by using the Boolean AND operator.
MERGEPAINT | Merges the colors of the inverted source rectangle with the colors of the destination rectangle by using the Boolean OR operator.
NOTSRCCOPY | Copies the inverted source rectangle to the destination.
NOTSRCERASE | Combines the colors of the source and destination rectangles by using the Boolean OR operator and then inverts the resultant color.
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.
PATPAINT | Combines the colors of the pattern with the colors of the inverted source rectangle by using the Boolean OR operator. The result of this operation is combined with the colors of the destination rectangle by using the Boolean OR operator.
SRCAND | Combines the colors of the source and destination rectangles by using the Boolean AND operator.
SRCCOPY | Copies the source rectangle directly to the destination rectangle.
SRCERASE | Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.
SRCINVERT | Combines the colors of the source and destination rectangles by using the Boolean XOR operator.
SRCPAINT | Combines the colors of the source and destination rectangles by using the Boolean OR operator.
WHITENESS | Fills the destination rectangle using the color associated with index 1 in the physical palette. This color is white for the default physical palette.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If a rotation or shear transformation is in effect in the source device context, BitBlt returns an error. If other transformations exist in the source device context (and a matching transformation is not in effect in the destination device context), the rectangle in the destination device context is stretched, compressed, or rotated as necessary.

If the color formats of the source and destination device contexts do not match, the BitBlt function converts the source color format to match the destination format.

When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context.

Not all devices support the BitBlt function. For more information, see the RC_BITBLT raster capability entry in the GetDeviceCaps function, as well as the MaskBlt and StretchBlt functions.

BitBlt returns an error if the source and destination device contexts represent different devices.

In Windows CE versions 1.0 and 1.01, the dwRop parameter can only be assigned the following values:

  • SRCAND
  • SRCCOPY
  • SRCINVERT
  • SRCPAINT

In Windows CE versions 2.0 and later, the dwRop parameter can be any ROP3.

See Also

GetDeviceCaps, MaskBlt, StretchBlt


BringWindowToTop

This function brings the specified window to the top of the z-order. If the window is a top-level window, it is activated. If the window is a child window, the top-level parent window associated with the child window is activated.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL BringWindowToTop( HWND hWnd );

Parameters

hWnd
Handle to the window to bring to the top of the z-order.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Use the BringWindowToTop function to uncover any window that is partially or completely obscured by other windows.

Calling this function is similar to calling the SetWindowPos function to change a window’s position in the z-order. BringWindowToTop does not make a window a top-level window.

If an application is not in the foreground and wants to be in the foreground, it should call the SetForegroundWindow function.

See Also

SetWindowPos, SetForegroundWindow


CallWindowProc

This function passes message information to the specified window procedure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LRESULT CallWindowProc( WNDPROC wndprcPrev, HWND hwnd,
UINT uMsg, WPARAM wParam, LPARAM lParam );

Parameters

lpPrevWndFunc
Long pointer to the previous window procedure.

If this value is obtained by calling the GetWindowLong function with the nIndex parameter set to GWL_WNDPROC or DWL_DLGPROC, it is actually either the address of a window or dialog box procedure, or a handle representing that address.

hWnd
Handle to the window procedure to receive the message.
Msg
Specifies the message.
wParam
Specifies additional message-specific information. The contents of this parameter depend on the value of the Msg parameter.
lParam
Specifies additional message-specific information. The contents of this parameter depend on the value of the Msg parameter.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

Use the CallWindowProc function for window subclassing. Usually, all windows with the same class share one window procedure. A subclass is a window or set of windows with the same class whose messages are intercepted and processed by another window procedure (or procedures) before being passed to the window procedure of the class.

The SetWindowLong function creates the subclass by changing the window procedure associated with a particular window, causing the system to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures.

If STRICT is defined, the lpPrevWndFunc parameter has the data type WNDPROC. The WNDPROC type is declared as follows:

LRESULT (CALLBACK* WNDPROC) (HWND, UINT, WPARAM, LPARAM);

If STRICT is not defined, the lpPrevWndFunc parameter has the data type FARPROC. The FARPROC type is declared as follows:

int (FAR WINAPI * FARPROC) ()

In C, the FARPROC declaration indicates a callback function that has an unspecified parameter list. In C++, however, the empty parameter list in the declaration indicates that a function has no parameters. This subtle distinction can break careless code. Following is one way to handle this situation:

#ifdef STRICT
  WNDPROC MyWindowProcedure
#else
  FARPROC MyWindowProcedure
#endif
...
    lResult = CallWindowProc(MyWindowProcedure, ...) ;

For further information about functions declared with empty argument lists, refer to The C++ Programming Language, Second Edition, by Bjarne Stroustrup.

Windows NT: The CallWindowProc function handles Unicode-to-ANSI conversion. You cannot take advantage of this conversion if you call the window procedure directly.

See Also

GetWindowLong, SetClassLong, SetWindowLong


CCHookProc

This function is an application-defined or library-defined callback function that is used with the Color common dialog box. CCHookProc receives messages or notifications intended for the default dialog box procedure.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and later

Syntax

UINT APIENTRY CCHookProc(HWND hdlg, UINT uiMsg,
WPARAM wParam, LPARAM lParam);

Parameters

hdlg
[in] Handle to the Color dialog box window for which the message is intended.
uiMsg
[in] Identifies the message being received.
wParam
[in] Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.
lParam
[in] Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a CHOOSECOLOR structure containing the values specified when the dialog was created.

Return Values

Zero indicates that the default dialog box procedure processes the message. Nonzero indicates that the default dialog box procedure ignores the message.

Remarks

When you use the ChooseColor function to create a Color dialog box, you can provide a CCHookProc hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the CHOOSECOLOR structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnHook member and specify the CC_ENABLEHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

See Also

ChooseColor, CHOOSECOLOR, EndDialog, PostMessage, WM_INITDIALOG, WM_CTLCOLORDLG


CheckMenuItem

This function sets the state of the specified menu item’s check mark attribute to either checked or unchecked.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DWORD CheckMenuItem(HMENU hmenu, UINT uIDCheckItem,
UINT uCheck);

Parameters

hmenu
[in] Handle to the menu of interest.
uIDCheckItem
[in] Specifies the menu item whose check-mark attribute is to be set, as determined by the uCheck parameter.
uCheck
[in] Specifies flags that control the interpretation of the uIDCheckItem parameter and the state of the menu item’s check-mark attribute. This parameter can be a combination of either MF_BYCOMMAND, or MF_BYPOSITION and MF_CHECKED or MF_UNCHECKED.
Value
Description
MF_BYCOMMAND | Indicates that the uIDCheckItem parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default, if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION | Indicates that the uIDCheckItem parameter gives the zero-based relative position of the menu item.
MF_CHECKED | Sets the check-mark attribute to the checked state.
MF_UNCHECKED | Sets the check-mark attribute to the unchecked state.

Return Values

The return value specifies the previous state of the menu item (either MF_CHECKED or MF_UNCHECKED). 0xFFFFFFFF indicates that the menu item does not exist.

Remarks

An item in a menu bar cannot have a check mark.

The uIDCheckItem parameter identifies a item that opens a submenu or a command item. For a item that opens a submenu, the uIDCheckItem parameter must specify the position of the item. For a command item, the uIDCheckItem parameter can specify either the item’s position or its identifier.

See Also

EnableMenuItem


CheckMenuRadioItem

This function checks a specified menu item and makes it a radio item. At the same time, the function unchecks all other menu items in the associated group and clears the radio-item type flag for those items.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL API CheckMenuRadioItem(HMENU hmenu, UINT idFirst,
UINT idLast, UINT idCheck, UINT uFlags);

Parameters

hmenu
[in] Handle to the menu that contains the group of menu items.
idFirst
[in] Identifier or position of the first menu item in the group.
idLast
[in] Identifier or position of the last menu item in the group.
idCheck
[in] Identifier or position of the menu item to check.
uFlags
[in] Value that specifies the meaning of idFirst, idLast, and idCheck. If this parameter is MF_BYCOMMAND, the other parameters specify menu item identifiers. If it is MF_BYPOSITION, the other parameters specify the menu item positions.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The CheckMenuRadioItem function sets the MFT_RADIOCHECK type flag and the MFS_CHECKED state for the item specified by idCheck and, at the same time, clears both flags for all other items in the group. The checked item is displayed using a bullet bitmap instead of a check-mark bitmap.

For more information about menu item type and state flags, see the MENUITEMINFO structure.


CheckRadioButton

This function adds a check mark to a specified radio button in a group and removes a check mark from all other radio buttons in the group.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CheckRadioButton( HWND hDlg, int nIDFirstButton,
int nIDLastButton, int nIDCheckButton );

Parameters

hDlg
[in] Handle to the dialog box that contains the radio button.
nIDFirstButton
[in] Specifies the identifier of the first radio button in the group.
nIDLastButton
[in] Specifies the identifier of the last radio button in the group.
nIDCheckButton
[in] Specifies the identifier of the radio button to select.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The CheckRadioButton function sends a BM_SETCHECK message to each of the radio buttons in the indicated group.


ChildWindowFromPoint

This function determines which, if any, of the child windows belonging to a parent window contains the specified point.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND ChildWindowFromPoint( HWND hWndParent, POINT Point );

Parameters

hWndParent
Handle to the parent window.
Point
Specifies a POINT structure that defines the client coordinates of the point to be checked.

Return Values

A handle to the child window that contains the point, even if the child window is hidden or disabled, indicates success. NULL indicates that the point lies outside the parent window. A handle to the parent window indicates that the point is within the parent window but not within any child window.

Remarks

The system maintains an internal list, containing the handles of the child windows associated with a parent window. The order of the handles in the list depends on the z-order of the child windows. If more than one child window contains the specified point, the system returns a handle to the first window in the list that contains the point.

See Also

POINT, WindowFromPoint


ChooseColor

This function creates a Color common dialog box that enables the user to select a color.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ChooseColor(LPCHOOSECOLOR lpcc);

Parameters

lpcc
Long pointer to a CHOOSECOLOR structure that contains information used to initialize the dialog box. When ChooseColor returns, this structure contains information about the user’s color selection.

Return Values

If the user clicks the OK button of the dialog box, the return value is nonzero. The rgbResult member of the CHOOSECOLOR structure contains the RGB color value of the color selected by the user.

If the user cancels or closes the Color dialog box or an error occurs, the return value is zero. To get extended error information, call the CommDlgExtendedError function, which can return one of the following values:

CDERR_FINDRESFAILURE | CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION | CDERR_NOHINSTANCE
CDERR_LOCKRESFAILURE | CDERR_NOHOOK
CDERR_LOADRESFAILURE | CDERR_NOTEMPLATE
CDERR_LOADSTRFAILURE | CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE |

Remarks

The Color common dialog does not support user-defined colors if the target device screen is less than 480 pixels in width. In this case, the CC_FULLOPEN and CC_PREVENTFULLOPEN flags are ignored.

The Color dialog box does not support palettes. The color choices offered by the dialog box are limited to the system colors and dithered versions of those colors.

You can provide a CCHookProc hook procedure for a Color dialog box. The hook procedure can process messages sent to the dialog box. To enable a hook procedure, set the CC_ENABLEHOOK flag in the Flags member of the CHOOSECOLOR structure and specify the address of the hook procedure in the lpfnHook member.

See Also

CCHookProc, CHOOSECOLOR, CommDlgExtendedError


ClientToScreen

This function converts the client coordinates of a specified point to screen coordinates.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ClientToScreen( HWND hWnd, LPPOINT lpPoint);

Parameters

hWnd
Handle to the window whose client area is used for the conversion.
lpPoint
Long pointer to a POINT structure that contains the client coordinates to be converted. The new screen coordinates are copied into this structure if the function succeeds.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

Remarks

The ClientToScreen function replaces the client coordinates in the POINT structure with the screen coordinates. The screen coordinates are relative to the upper-left corner of the screen.

See Also

MapWindowPoints, POINT, ScreenToClient


ClipCursor

This function confines the cursor to a rectangular area on the screen. If a subsequent cursor position (set by the SetCursorPos function or the mouse) lies outside the rectangle, Windows CE automatically adjusts the cursor position to keep it inside the rectangular area.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ClipCursor( CONST RECT *lpRect );

Parameters

lprc
[in] Long pointer to the RECT structure that contains the screen coordinates of the upper-left and lower-right corners of the confining rectangle. If this parameter is NULL, the cursor is free to move anywhere on the screen.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The cursor is a shared resource. If an application confines the cursor, it must release the cursor by using ClipCursor before relinquishing control to another application.

The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

See also

GetClipCursor, GetCursorPos, RECT, SetCursorPos


CloseClipboard

This function closes the clipboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CloseClipboard(void);

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

When the window has finished examining or changing the clipboard, close the clipboard by calling CloseClipboard. This enables other windows to access the clipboard.

Do not place an object on the clipboard after calling CloseClipboard.

See Also

GetOpenClipboardWindow, OpenClipboard


CombineRgn

This function combines two regions and stores the result in a third region. The two regions are combined according to the specified mode.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int CombineRgn(HRGN hrgnDest, HRGN hrgnSrc1, HRGN hrgnSrc2,
int fnCombineMode);

Parameters

hrgnDest
[in] Handle to a new region with dimensions defined by combining two other regions. (This region must exist before CombineRgn is called.)
hrgnSrc1
[in] Handle to the first of two regions to be combined.
hrgnSrc2
[in] Handle to the second of two regions to be combined.
fnCombineMode
[in] Specifies a mode indicating how the two regions will be combined. This parameter can be one of the following values:
Value
Description
RGN_AND | Creates the intersection of the two combined regions.
RGN_COPY | Creates a copy of the region identified by hrgnSrc1.
RGN_DIFF | Combines the parts of hrgnSrc1 that are not part of hrgnSrc2.
RGN_OR | Creates the union of two combined regions.
RGN_XOR | Creates the union of two combined regions except for any overlapping areas.

Return Values

The return value specifies the type of the resulting region. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than a single rectangle. ERROR indicates that no region is created.

Remarks

The three regions need not be distinct. For example, the hrgnSrc1 parameter can equal the hrgnDest parameter.

See Also

CreateRectRgnIndirect


CommandBands_AddAdornments

This function adds the Close button (X) to the upper right corner of the command bands control. You can also use it to add the Help button (?) and the OK button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CommandBands_AddAdornments (HWND hwndCmdBands, HINSTANCE hinst, DWORD dwFlags, LPREBARBANDINFO prbbi);

Parameters

hwndCmdBands
Handle to the he command bands control’s window. This handle is returned when the command bands control is created by the CommandBands_Create function.
hinst
Handle to the application instance.
dwFlags
Specifies the optional buttons to be added to the top band of the command bands control. This parameter can be a combination of the following values, or zero if neither of the optional buttons are needed.
Value
Description
Message
CMDBAR_HELP | Help button | WM_HELP
CMDBAR_OK | OK button | WM_COMMAND (with IDOK as the message identifier)

prbbi
Pointer to a REBARBANDINFO structure. Use this structure to customize the band that holds the adornments. This parameter can be NULL.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

By default the adornments band is created with an identifier of 0xFFFFFFFF. You can use the REBARBANDINFO structure you pass in the prbbi parameter to override this identifier.

See Also

CommandBands_Create, REBARBANDINFO


CommandBands_AddBands

This function adds one or more bands to the command bands control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CommandBands_AddBands (HWND hwndCmdBands,
HINSTANCE hinst, UINT cBands, LPREBARBANDINFO prbbi);

Parameters

hwndCmdBands
Handle to the command bands control’s window. This handle is returned when the command bands control is created by the CommandBands_Create function.
hinst
Handle to the application instance.
cBands
Number of bands to add.
prbbi
Pointer to an array of REBARBANDINFO structures that contain information about the bands to add. There must be the same number of elements in the array as specified in the cBands parameter.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

By default, each band is created with a command bar as its child window. The command bar can be retrieved by using the CommandBands_GetCommandBar function. To create a different kind of child control in a band, use the RBBIM_CHILD mask in the fMask field of the REBARBANDINFO structure, and specify the child control's window handle in the REBARBANDINFO structure’s hwndChild field.

See Also

CommandBands_Create, REBARBANDINFO


CommandBands_Create

This function instantiates a new command bands control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HWND CommandBands_Create (HINSTANCE hinst, HWND hwndParent,
UINT wID, DWORD dwStyles, HIMAGELIST himl);

Parameters

hinst
Handle to the application instance in which to create the command bands control.
hwndParent
Handle to the parent window for the command bands control.
wID
Identifier of the command bands control. This is used in any rebar notifications that are sent to the parent window.
dwStyles
Specifies the style of the command bands tool being created. This parameter can be any combination of the styles listed in Window and Message Box Styles and Control Styles.
himl
Handle to the image list that contains the images to draw in each band of the control. Set this parameter to NULL if no images are to be drawn.

Return Values

The window handle to the command bands control indicates success. NULL indicates failure.


CommandBands_GetCommandBar

This function retrieves the handle to a command bar child control in a band of the command bands control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HWND CommandBands_GetCommandBar (HWND hwndCmdBands,
UINT uBand);

Parameters

hwndCmdBands
Handle to the command bands control’s window. This handle is returned when the command bands control is created by the CommandBands_Create function.
uBand
Unsigned integer that contains the zero-based index of the band containing the command bar. If the user has had an opportunity to reposition the bands, use the RB_IDTOINDEX message to get the index of the band before passing the index to this function.

Return Values

The window handle to the command bar identified by the index in the wBandID parameter indicates success. NULL indicates failure.

Remarks

The index you pass in the wBandID parameter is the current position of the command bar band in the command bands control. This index may have a different value than the order in which you added the band to the control, because the user may have repositioned the band.

See Also

CommandBands_Create RB_IDTOINDEX


CommandBands_GetRestoreInformation

This function retrieves information necessary to restore a band’s current state, and places it in a COMMANDBANDSRESTOREINFO structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI CommandBands_GetRestoreInformation(
HWND hwndCmdBands, UINT uBand,
LPCOMMANDBANDSRESTOREINFO pcbr);

Parameters

hwndCmdBands
[in] Handle to the command bands control’s window. This handle is returned when the command bands control is created by the CommandBands_Create function.
uBand
[in] Unsigned integer that contains the zero-based index of the band containing the command bar. Use RB_IDTOINDEX to get the index of the band before passing the index to this function.
pcbri
[out] Pointer to an array of COMMANDBANDSRESTOREINFO structures that will receive information about the band’s current state.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Use CommandBands_GetRestoreInformation to save information about the bands in a command bands control before you close the application window. Save the information in the registry, so the bands can be restored to their current state the next time the application is opened. The next time the application is opened, use the values returned in the fStyle and cxRestored fields of the COMMANDBANDSRESTOREINFO structure for the fStyle and cx fields of the REBARBANDINFO structure you pass to the CommandBands_AddBands function. After you've added all the bands to the control, use the RB_MAXIMIZEBAND message to maximize any band whose fMaximized field in the COMMANDBANDSRESTOREINFO structure is set to TRUE.

See Also

CommandBands_AddBands, CommandBands_Create, COMMANDBANDSRESTOREINFO, RB_IDTOINDEX, REBARBANDINFO


CommandBands_Show

This function shows or hides the command bands control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI CommandBands_Show (HWND hwndCmdBands,
BOOL fShow);

Parameters

hwndCmdBands
Handle to command bands control’s window. This handle is returned when the command bands control is created by the CommandBands_Create function.
fShow
Boolean that specifies whether to show or hide the command bands control. Set this parameter to TRUE to show the command bar, or FALSE to hide it.

Return Values

The previous state of the command bands control indicates success.


CommandBar_AddAdornments

This function adds the Close button (X) to the command bar. You can also use it to add the Help button (?) and the OK button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_AddAdornments(HWND hwndCB, DWORD dwFlags,
DWORD dwReserved);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned when the command bar is created by the CommandBar_Create function.
dwFlags
Specifies the optional buttons to be added to the command bar. This parameter can be a combination of the following values, or zero if neither of the optional buttons are needed.
Value
Description
Message
CMDBAR_HELP | Help button | WM_HELP
CMDBAR_OK | OK button | WM_COMMAND (with IDOK as the message identifier)

dwReserved
Reserved; set to zero.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When a user selects the Close, OK, or Help button, the message associated with that button is placed in the application’s message queue.

Do not call the CommandBar_AddAdornments member function until after you have added all the other elements (menus, buttons, combo boxes) to the command bar.

See Also

CommandBar_AddButtons, CommandBar_InsertButton


CommandBar_AddBitmap

This function adds one or more images to the list of button images available for use in the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

int CommandBar_AddBitmap(HWND hwndCB, HINSTANCE hInst,
int idBitmap, int iNumImages, int iReserved, int iReserved);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
hInst
Handle to an instance of the executable module that contains the bitmap resource.
idBitmap
Identifier of the bitmap resource that contains the button images. If you specify HINST_COMMCTRL in the hInst parameter, you can use system-defined button bitmaps by specifying one of the following values.
Value
Description
IDB_STD_SMALL_COLOR | Adds small, color standard bitmaps.
IDB_VIEW_SMALL_COLOR | Adds small, color view bitmaps.

iNumImages
Integer that contains the number of button images in the bitmap. This can be zero if the bitmap being added is one of the system defined bitmaps—standard or view.

Return Values

The index of the first new image indicates success. A value of –1 indicates failure.

Remarks

Each button image should be 16x16 pixels in size.

The following values can be used as indexes to the standard and view bitmaps:

STD_COPY | STD_PROPERTIES
STD_CUT | STD_REDOW
STD_DELETE | STD_REPLACE
STD_FIND | STD_PASTE
STD_FILENEW | STD_PRINT
STD_FILEOPEN | STD_PRINTPRE
STD_FILESAVE | STD_UNDO
STD_HELP |
VIEW_DETAILS | VIEW_SORTDATE
VIEW_LARGEICONS | VIEW_SORTNAME
VIEW_LIST | VIEW_SORTSIZE
VIEW_SMALLICONS | VIEW_SORTTYPE

Windows CE version 1.0 only supports 2 bits per pixel (2bp) gray scale, so the bitmaps is not displayed in color.

See Also

CommandBar_Create


CommandBar_Create

This function instantiates a new command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HWND CommandBar_Create(HINSTANCE hInst, HWND hwndParent,
int idCmdBar);

Parameters

hInst
Handle to the application instance in which to create the command bar.
hwndParent
Handle to the parent window for the command bar.
idCmdBar
Identifier of the command bar.

Return Values

The window handle to the command bar indicates success. NULL indicates failure.

Remarks

The CommandBar_Create function creates an empty command bar.

See Also

CommandBar_Destroy


CommandBar_DrawMenuBar

This function repositions and redraws the command bar after a menu in the command bar has been modified.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CommandBar_DrawMenuBar(HWND hwndCB, int iButton);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
iButton
Zero-based index of the menu bar within the command bar.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

You must always call CommandBar_DrawMenuBar after you modify a menu in a command bar. Do not call DrawMenuBar.

An application should not use 0xFFFFFFFF as the command identifier of a button or separator in the command bar. This identifier is reserved for the command bar’s use.

See Also

CommandBar_Create, CommandBar_GetMenu


CommandBar_GetMenu

This function retrieves the handle to a menu on the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HMENU CommandBar_GetMenu(HWND hwndCB, int iButton);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
iButton
Zero-based index of the command bar separator button that holds the menu.

Return Values

The handle to the menu identified by the index in the iButton parameter indicates success. NULL indicates failure.

Remarks

If the separator button identified by the iButton parameter does not contain a menu bar, the CommandBar_GetMenu function will fail.

See Also

CommandBar_Create, CommandBar_InsertMenubar


CommandBar_Height

This function retrieves the height of the command bar in pixels.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

int CommandBar_Height(HWND hwndCB);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.

Return Values

The height, in pixels, of the of the command bar indicates success.

Remarks

Because the command bar occupies part of the client area of an application’s main window, you should call this function to determine the actual size of the client area.

See Also

CommandBar_Create


CommandBar_InsertComboBox

This function inserts a combo box into the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HWND CommandBar_InsertComboBox(HWND hwndCB,
HINSTANCE hInst, int iWidth, UINT dwStyle, WORD idComboBox,
WORD iButton);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
hInst
Handle to the application instance.
iWidth
Integer that contains the width, in pixels, of the combo box.
dwStyle
Specifies the window styles to apply to the combo box. The WS_VISIBLE and WS_CHILD styles are applied automatically. For descriptions of other styles you can apply, see Window and Message Box Styles.
idComboBox
Identifier of the combo box to insert.
iButton
Zero-based index of a button in the command bar. CommandBar_InsertComboBox inserts the combo box to the left of this button.

Return Values

The window handle to the combo box indicates success. NULL indicates failure.

See Also

CommandBar_Create, CommandBar_InsertButton, CommandBar_InsertMenubar


CommandBar_InsertMenubar

This function inserts a menu bar into the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_InsertMenubar(HWND hwndCB, HINSTANCE hInst,
WORD idMenu, WORD iButton);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
hInst
Handle to the application instance.
idMenu
Resource identifier of the menu bar to insert in the command bar.
iButton
Zero-based index of a button. CommandBar_InsertMenubar inserts the menu bar to the left of this button.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Use the same type of menu bar in the command bar of a Windows CE application that you use for the main menu in an application running on a Windows desktop platform.

See Also

CommandBar_Create, CommandBar_GetMenu , CommandBar_InsertButton, CommandBar_InsertComboBox, CommandBar_InsertMenuBarEx


CommandBar_InsertMenubarEx

This function inserts a menu into a command bar. The menu can be specified as a resource name, using MAKEINTRESORUCE, or as a menu handle.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_InsertMenubarEx(HWND hwndCB,
HINSTANCE hInst, LPTSTR pszMenu, WORD iButton);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
hInst
Handle to the application instance. This parameter must be NULL if pszMenu contains a menu handle. If pszMenu contains a resource name, hinst must contain the instance handle.
pszMenu
Pointer to the null-terminated string that contains the name of a menu resource or menu handle.
iButton
Zero-based index of a button. CommandBar_InsertMenubarEx inserts the menu bar to the left of this button.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Use the same type of menu bar in the command bar of a Windows CE application that you use for the main menu in an application running on a Windows desktop platform.

See Also

CommandBar_Create, CommandBar_GetMenu , CommandBar_InsertButton, CommandBar_InsertComboBox, CommandBar_InsertMenuBar


CommandBar_Show

This function shows or hides the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_Show(HWND hwndCB, BOOL fShow);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
fShow
Boolean that specifies whether to show or hide the command bar. Set this parameter to TRUE to show the command bar, or FALSE to hide it.

Return Values

The previous show state of the command bar. This function returns TRUE if command bar was displayed, FALSE if it was hidden.

Remarks

Command bars are created with the show state set to TRUE. To hide the command bar before the window is displayed call CommandBar_Show, with the fShow parameter set to false, before calling ShowWindow for the parent window.

See Also

CommandBar_Create, CommandBar_IsVisible, ShowWindow


CommDlgExtendedError

This function returns a common dialog box error value. This value indicates the most recent error to occur during the execution of one of the following common dialog box functions:

  • ChooseColor
  • GetOpenFileName
  • GetSaveFileName
  • PageSetupDlg
  • PrintDlg

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CommDlgExtendedError()

Return Values

If the most recent call to a common dialog box function succeeded, the return value is undefined.

If the common dialog box function returned FALSE because the user closed or canceled the dialog box, the return value is zero. Otherwise, the return value is a nonzero error code. For more information, see the following Remarks section.

Remarks

The CommDlgExtendedError function can return general error codes for any of the common dialog box functions. In addition, there are error codes that are returned only for a specific common dialog box. The error codes returned by CommDlgExtendedError are defined in the CDERR.H file.

The following general error codes can be returned for any of the common dialog box functions:

CDERR_DIALOGFAILURE
The dialog box could not be created. The common dialog box function’s call to the DialogBox function failed. For example, this error occurs if the common dialog box call specifies an invalid window handle.
CDERR_FINDRESFAILURE
The common dialog box function failed to find a specified resource.
CDERR_INITIALIZATION
The common dialog box function failed during initialization. This error often occurs when sufficient memory is not available.
CDERR_LOADRESFAILURE
The common dialog box function failed to load a specified resource.
CDERR_LOADSTRFAILURE
The common dialog box function failed to load a specified string.
CDERR_LOCKRESFAILURE
The common dialog box function failed to lock a specified resource.
CDERR_MEMALLOCFAILURE
The common dialog box function was unable to allocate memory for internal structures.
CDERR_NOHINSTANCE
The ENABLETEMPLATE flag was set in the Flags member of the initialization structure for the corresponding common dialog box, but you failed to provide a corresponding instance handle.
CDERR_NOHOOK
The ENABLEHOOK flag was set in the Flags member of the initialization structure for the corresponding common dialog box, but you failed to provide a pointer to a corresponding hook procedure.
CDERR_NOTEMPLATE
The ENABLETEMPLATE flag was set in the Flags member of the initialization structure for the corresponding common dialog box, but you failed to provide a corresponding template.
CDERR_REGISTRYFAILURE
The common dialog box function was unable to read from registry.
CDERR_STRUCTSIZE
The lStructSize member of the initialization structure for the corresponding common dialog box is invalid.

The following error codes can be returned for the PrintDlg function:

PDERR_CREATEDCFAILURE
The call to CreateDC failed.
PDERR_NOPORTS
No ports are registered.
PDERR_NOPRINTERS
No printers are registered.
PDERR_PARSEFAILURE
The PrintDlg function failed to parse the strings in the [devices] section of the WIN.INI file.
PDERR_PRINTERNOTFOUND
The [devices] section of the WIN.INI file did not contain an entry for the requested printer.
PDERR_RETDEFFAILURE
The PD_RETURNDEFAULT flag was specified in the Flags member of the PRINTDLG structure, but the hDevMode or hDevNames member was not NULL.
PDERR_SETUPFAILURE
The PrintDlg function failed to load the required resources.

The following error codes can be returned for the GetOpenFileName and GetSaveFileName functions:

FNERR_BUFFERTOOSMALL
The buffer pointed to by the lpstrFile member of the OPENFILENAME structure is too small for the filename specified by the user. The first two bytes of the lpstrFile buffer contain an integer value specifying the size, in bytes (ANSI version) or 16-bit characters (Unicode version), required to receive the full name.
FNERR_INVALIDFILENAME
A filename is invalid.
FNERR_SUBCLASSFAILURE
An attempt to subclass a list box failed because sufficient memory was not available.


CountClipboardFormats

This function retrieves the number of different data formats currently on the clipboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int CountClipboardFormats(void);

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

EnumClipboardFormats, RegisterClipboardFormat


CreateAcceleratorTable

This function creates an accelerator table.

At a Glance

Header file: | Winuser.h
Versions: | 1.0 and later

Syntax

HACCEL CreateAcceleratorTable(LPACCEL lpaccel, int cEntries);

Parameters

lpaccl
Long pointer to an array of ACCEL structures that describes the accelerator table.
cEntries
Specifies the number of ACCEL structures in the array.

Return Values

The handle to the created accelerator table indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

Before an application closes, it must use the DestroyAcceleratorTable function to destroy each accelerator table that it created by using the CreateAcceleratorTable function.

See Also

ACCEL, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


CreateBitmap

This function creates a bitmap with the specified width, height, and bit depth.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HBITMAP CreateBitmap(int nWidth, int nHeight, UINT cPlanes,
UINT cBitsPerPel, CONST VOID *lpvBits);

Parameters

nWidth
[in] Specifies the bitmap width, in pixels.
nHeight
[in] Specifies the bitmap height, in pixels.
cPlanes
[in] Specifies the number of color planes used by the device. The value of this parameter must be 1.
cBitsPerPel
[in] Specifies the number of bits required to identify the color of a single pixel.
lpvBits
[in] Long void pointer to an array of color data used to set the colors in a rectangle of pixels. Each scan line in the rectangle must be word aligned (scan lines that are not word aligned must be padded with zeros). If this parameter is NULL, the new bitmap is undefined.

Return Values

A handle to a bitmap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

While the CreateBitmap function can be used to create color bitmaps, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmap is selected into a device context, the system must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are faster than with a color bitmap returned from CreateBitmap.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

If an application sets the nWidth or nHeight parameters to zero, CreateBitmap returns the handle to a 1- by 1-pixel, monochrome bitmap.

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

CreateCompatibleBitmap, DeleteObject, SelectObject


CreateCaret

This function creates a new shape for the system caret and assigns ownership of the caret to the specified window. The caret shape can be a line or a block.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CreateCaret(HWND hWnd, HBITMAP hBitmap, int nWidth,
int nHeight);

Parameters

hWnd
[in] Handle to the window that owns the caret.
hBitmap
[in] Unsupported; set to NULL. The default caret is solid.
nWidth
[in] Integer that contains the width of the caret in logical units. If this parameter is zero, the width is set to the system-defined window border width.
nHeight
[in] Integer that contains the height, in logical units, of the caret. If this parameter is zero, the height is set to the system-defined window border height.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The nWidth and nHeight parameters specify the caret’s width and height, in logical units; the exact width and height, in pixels, depend on the window’s mapping mode.

CreateCaret automatically destroys the previous caret shape, if any, regardless of the window that owns the caret. The caret is hidden until the application calls the ShowCaret function to make the caret visible.

The system provides one caret per queue. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

You can retrieve the width or height of the system’s window border by using the GetSystemMetrics function, specifying the SM_CXBORDER and SM_CYBORDER values. Using the window border width or height guarantees that the caret will be visible on a high-resolution screen.

See Also

CreateBitmap, DestroyCaret, GetSystemMetrics, HideCaret, LoadBitmap, ShowCaret


CreateCompatibleBitmap

This function creates a bitmap compatible with the device associated with the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HBITMAP CreateCompatibleBitmap(HDC hdc, int nWidth, int nHeight);

Parameters

hdc
[in] Handle to a device context.
nWidth
[in] Specifies the bitmap width, in pixels.
nHeight
[in] Specifies the bitmap height, in pixels.

Return Values

A handle to the bitmap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The color format of the bitmap created by the CreateCompatibleBitmap function matches the color format of the device identified by the hdc parameter. This bitmap can be selected into any memory device context that is compatible with the original device.

Because memory device contexts allow both color and monochrome bitmaps, the format of the bitmap returned by the CreateCompatibleBitmap function differs when the specified device context is a memory device context. However, a compatible bitmap that was created for a nonmemory device context always possesses the same color format and uses the same color palette as the specified device context.

If an application sets the nWidth or nHeight parameters to zero, CreateCompatibleBitmap returns the handle to a 1- by 1-pixel, monochrome bitmap.

If a DIB section, which is a bitmap created by the CreateDIBSection function, is selected into the device context identified by the hdc parameter, CreateCompatibleBitmap creates a DIB section.

When you no longer need the bitmap, call the DeleteObject function to delete it.

See Also

CreateDIBSection, DeleteObject, SelectObject


CreateCompatibleDC

This function creates a memory device context (DC) compatible with the specified device.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HDC CreateCompatibleDC(HDC hdc);

Parameters

hdc
[in] Handle to an existing device context. If this handle is NULL, the function creates a memory device context compatible with the application's current screen.

Return Values

The handle to a memory device context indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

A memory device context is a device context that exists only in memory. When the memory device context is created, its display surface is exactly one monochrome pixel wide and one monochrome pixel high. Before an application can use a memory device context for drawing operations, it must select a bitmap of the correct width and height into the device context. This may be done by using CreateCompatibleBitmap specifying the height, width, and color organization required in the function call.

When a memory device context is created, all attributes are set to normal default values. The memory device context can be use as a normal device context. You can set the attributes to non-default values, obtain the current setting of its attributes, select pens, brushes and regions into it.

The CreateCompatibleDC function can only be used with devices that support raster operations. An application can determine whether a device supports these operations by calling the GetDeviceCaps function.

When you no longer need the memory device context, call the DeleteDC function to delete it.

See Also

CreateCompatibleBitmap, DeleteDC, GetDeviceCaps


CreateCursor

This function creates a cursor having the specified size, bit patterns, and hot spot.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HCURSOR CreateCursor( HINSTANCE hInst, int xHotSpot, int yHotSpot,
int nWidth, int nHeight, CONST VOID *pvANDPlane,
CONST VOID *pvXORPlane );

Parameters

hInst
[in] Handle to the current instance of the application creating the cursor.
xHotSpot
[in] Specifies the horizontal position of the cursor’s hot spot.
yHotSpot
[in] Specifies the vertical position of the cursor’s hot spot.
nWidth
[in] Specifies the width, in pixels, of the cursor.
nHeight
[in] Specifies the height, in pixels, of the cursor.
pvANDplane
[in] Void pointer to an array of bytes that contains the bit values for the AND bitmask of the cursor, as in a device-dependent monochrome bitmap.
pvXORplane
[in] Void pointer to an array of bytes that contains the bit values for the XOR bitmask of the cursor, as in a device-dependent monochrome bitmap.

Return Values

A handle to the cursor indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

Hotspots should be created with positive location values. If the xHotSpot or yHotSpot parameter has a negative value, the actual hotspot has an arbitrary position.

The nWidth and nHeight parameters must specify a width and height that are supported by the current display driver, because the system cannot create cursors of other sizes. To determine the width and height supported by the display driver, use the GetSystemMetrics function, specifying the SM_CXCURSOR or SM_CYCURSOR value.

Before closing, an application must call the DestroyCursor function to free any system resources associated with the cursor.

See Also

DestroyCursor, GetSystemMetrics, SetCursor


CreateDC

This function creates a device context (DC) for a device.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

HDC CreateDC( LPCTSTR lpszDriver, LPCTSTR lpszDevice,
LPCTSTR lpszOutput, CONST DEVMODE * lpInitData);

Parameters

lpszDriver
[in] Long pointer to a null-terminated string that specifies the file name of a driver. If this parameter is set to NULL, the system returns a screen DC.
lpszDevice
[in] Long pointer to a null-terminated string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, "Epson FX-80"). It is not the printer model name. The lpszDevice parameter must be used.

In Windows CE versions 2.0 and 2.01, this parameter is ignored.

lpszOutput
[in] Long pointer to an output destination. It can be one of the following values, and the colon is required when specifying a port.
Value
Description
COMx: Serial ports; x is a number from 1 to 9.
LPTx: Parallel ports; x is a number from 1 to 9.
IRDA: IRDA port. For Windows CE versions 2.0 and 2.01, use COM3: to specify the IRDA port.
\\servername\sharename Universal naming convention (UNC) that identifies a network printer server.

lpInitData
[in] Long pointer to a DEVMODE structure containing device-specific initialization data for the device driver. The lpInitData parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user.

Return Values

The handle to a device context for the specified device indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE passes the lpInitData and lpszOutput parameters to the driver without modification. The lpszOutput parameter must contain a colon after the port—that is, use “LPT1:” or “COM1:”—otherwise, the connection fails.

When you no longer need the device context, call the DeleteDC function to delete it.


CreateDialog

This function creates a modeless dialog box from a dialog box template resource.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateDialog( HINSTANCE hInstance, LPCTSTR lpTemplate, HWND hWndParent, DLGPROC lpDialogFunc );

Parameters

hInstance
[in] Handle to the module whose executable file contains the dialog box template.
lpTemplate
[in] Long pointer to the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

The handle to the dialog box indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateDialog function uses the CreateWindowEx function to create the dialog box. CreateDialog then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialog returns the window handle to the dialog box.

After CreateDialog returns, the application displays the dialog box (if it is not already displayed) by using the ShowWindow function. The application destroys the dialog box by using the DestroyWindow function.

Windows CE does not support all styles in the DLGTEMPLATE structure. This structure is in the template identified by the lpTemplate parameter.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogBox, DialogProc, DLGTEMPLATE, HIWORD, LOWORD, ShowWindow, WM_INITDIALOG


CreateDialogIndirect

This function creates a modeless dialog box from a dialog box template in memory.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateDialogIndirect( HINSTANCE hInstance, LPCDLGTEMPLATE lpTemplate, HWND hWndOwner,
DLGPROC lpDialogFunc );

Parameters

hInstance
[in] Handle to the module that creates the dialog box.
lpTemplate
[in] Long pointer to a global memory object containing a template that CreateDialogIndirect uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended dialog box template, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

After CreateDialogIndirect returns, you can free the template, which is only used to get the dialog box started.

hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

The window handle to the dialog box indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateDialogIndirect macro uses the CreateWindowEx function to create the dialog box. CreateDialogIndirect then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogIndirect returns the window handle to the dialog box.

After CreateDialogIndirect returns, you can use the ShowWindow function to display the dialog box (if it is not already visible). To destroy the dialog box, use the DestroyWindow function.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings.

Windows CE does not support all styles in the DLGTEMPLATE structure. This structure is in the template identified by the lpTemplate parameter.

See Also

CreateDialog, CreateDialogIndirectParam, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogProc, DLGITEMTEMPLATE, DLGTEMPLATE, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogIndirectParam

This function creates a modeless dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateDialogIndirectParam( HINSTANCE hInstance,
LPCDLGTEMPLATE lpTemplate, HWND hWndOwner,
DLGPROC lpDialogFunc, LPARAM lParamInit );

Parameters

hInstance
[in] Handle to the module that will create the dialog box.
lpTemplate
[in] Long pointer to a global memory object containing a template that CreateDialogIndirectParam uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended dialog box template, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

After CreateDialogIndirectParam returns, you can free the template, which is only used to get the dialog box started.

hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
lParamInit
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Values

The window handle to the dialog box indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateDialogIndirectParam function uses the CreateWindowEx function to create the dialog box. CreateDialogIndirectParam then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogIndirectParam returns the window handle to the dialog box.

After CreateDialogIndirectParam returns, you can use the ShowWindow function to display the dialog box (if it is not already visible). To destroy the dialog box, use the DestroyWindow function.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings.

Dialog boxes outside the visible area of the screen are not automatically repositioned.

If the user presses ALT+H while the dialog box has the input focus, the system posts a WM_HELP message to the dialog procedure. An application should respond to this message by displaying context-sensitive help for the dialog box.

The following styles are not supported for the style member of the DLGTEMPLATE structure:

DS_SETFONT
You cannot set the font inside dialog boxes.
DS_3DLOOK
Gives the dialog box a non-bold font and draws three-dimensional borders around control windows in the dialog box.

The DS_3DLOOK style is required only by Win32-based applications compiled for system versions earlier than Windows 95 or Windows NT 4.0. The system automatically applies the three-dimensional look to dialog boxes created by applications compiled for current versions of the system.

DS_RECURSE
Not required. Any child dialog box is automatically considered to be a recursive dialog box.
DS_CONTROL
Not required.

To get default positioning, use the DS_CENTER style.

If the WS_CHILD style is not specified, the WS_POPUP style is assumed.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogProc, DLGITEMTEMPLATE, DLGTEMPLATE, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogParam

This function creates a modeless dialog box from a dialog box template resource. Before displaying the dialog box, it passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateDialogParam( HINSTANCE hInstance,
LPCTSTR lpTemplateName, HWND hWndOwner, DLGPROC lpDialogFunc,
LPARAM dwInitParam );

Parameters

hInstance
[in] Handle to the module whose executable file contains the dialog box template.
lpTemplateName
[in] Long pointer to the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
dwInitParam
[in] Specifies the value to pass to the dialog box procedure in the lParam parameter in the WM_INITDIALOG message.

Return Values

The window handle to the dialog box indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateDialogParam function uses the CreateWindowEx function to create the dialog box. CreateDialogParam then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogParam returns the window handle of the dialog box.

After CreateDialogParam returns, the application displays the dialog box (if it is not already displayed) by using the ShowWindow function. The application destroys the dialog box by using the DestroyWindow function.

Windows CE does not support all styles in the DLGTEMPLATE structure. This structure is in the template identified by the lpTemplate parameter.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DestroyWindow, DialogProc, DLGTEMPLATE, HIWORD, LOWORD, MAKEINTRESOURCE, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDIBPatternBrushPt

This function creates a logical brush that has the pattern specified by the device-independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HBRUSH CreateDIBPatternBrushPt(const void * lpPackedDIB,
UINT iUsage);

Parameters

lpPackedDIB
[in] Long pointer to a packed DIB consisting of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.
iUsage
[in] Specifies whether the bmiColors member of the BITMAPINFO structure contains a valid color table and, if so, whether the entries in this color table contain explicit red, green, blue (RGB) values or palette indices. The iUsage parameter must be one of the following values:
Value
Description
DIB_PAL_COLORS | A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the brush is to be selected. Windows CE versions 1.0 and 1.01 do not support this value.
DIB_RGB_COLORS | A color table is provided and contains literal RGB values.

In Windows CE versions 2.0 and later, set the iUsage parameter to DIB_RGB_COLORS. When an 8 bpp bitmap is used, you can set iUsage to DIB_PAL_COLORS, however, in that case, Windows CE will ignore the values in the bmiColors array member of the BITMAPINFO structure.

Return Values

Handle to a logical brush indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

A brush is a bitmap that the system uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateDIBPatternBrushPt, it can select that brush into any device context by calling the SelectObject function.

When you no longer need the brush, call the DeleteObject function to delete it.

See Also

BITMAPINFO, CreateSolidBrush, DeleteObject, SelectObject, SetBrushOrgEx


CreateDIBSection

This function creates a device-independent bitmap (DIB) that applications can write to directly. The function returns a handle to the bitmap.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HBITMAP CreateDIBSection(HDC hdc, const BITMAPINFO *pbmi,
UINT iUsage, void *ppvBits, HANDLE hSection, DWORD dwOffset);

Parameters

hdc
[in] Handle to a device context. If the value of iUsage is DIB_PAL_COLORS, the function uses this device context's logical palette to initialize the device-independent bitmap’s colors.
pbmi
[in] Pointer to a BITMAPINFO structure that specifies various attributes of the device-independent bitmap, including the bitmap’s dimensions and colors.
iUsage
[in] Specifies the type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi (either logical palette indexes or literal RGB values). The following values are defined:
Value
Description
DIB_RGB_COLORS | The BITMAPINFO structure contains an array of literal RGB values. Specify this value except when an 8 bpp bitmap is used.
DIB_PAL_COLORS | Specify this value when an 8 bbp bitmap is used. When DIB_PAL_COLORS is used, the system ignores the bmiColors member of the BITMAPINFO structure and the dwOffset parameter. Set dwOffset to zero and the hSection parameter to NULL.

ppvBits
[in] Pointer to a variable that receives a pointer to the location of the device-independent bitmap’s bit values.
hSection
[in] Handle to a file mapping object that the function will use to create the device-independent bitmap. This parameter can be NULL.

If hSection is not NULL, it must be a handle to a file mapping object created by calling the CreateFileMapping function with the PAGE_READWRITE or PAGE_WRITECOPY flag. Read-only DIB sections are not supported. Handles created by other means will cause CreateDIBSection to fail.

If hSection is not NULL, the CreateDIBSection function locates the bitmap's bit values at offset dwOffset in the file mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection.

If hSection is NULL, the system allocates memory for the device-independent bitmap. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory. The dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL.

dwOffset
[in] Specifies the offset from the beginning of the file mapping object referenced by hSection where storage for the bitmap’s bit values is to begin. This value is ignored if hSection is NULL. The bitmap’s bit values are aligned on doubleword boundaries, so dwOffset must be a multiple of the size of a DWORD.

Return Values

A handle to the newly created device-independent bitmap indicates success, and *ppvBits points to the bitmap’s bit values.

NULL indicates failure, and *ppvBits is NULL.

To get extended error information, call GetLastError.

Remarks

As noted above, if hSection is NULL, the system allocates memory for the device-independent bitmap. The system closes the handle to that memory when you later delete the device-independent bitmap by calling the DeleteObject function. If hSection is not NULL, you must close the hSection memory handle yourself after calling DeleteObject to delete the bitmap.

In Windows CE versions 2.0 and later, the BITMAPINFO structure must include a color table if the images are palettized (usually 1,2,4, and 8 bpp formats). For 16 bpp or 32 bpp non-palettized images, the color table must be three entries long; the entries must specify the values of the red, green, and blue bitmasks. GDI ignores the color table for 24 bpp images; their pixels must be stored in Blue-Green-Red (BGR) format.

In Windows CE versions 1.0 and 1.01, the BITMAPINFO structure pointed to by the pbmi parameter must specify 1 or 2 bits per pixel.

See Also

BITMAPINFO, DeleteObject, GetObject, SelectObject


CreateFontIndirect

This function creates a logical font that has the characteristics specified in the specified structure. The font can subsequently be selected as the current font for any device context (DC).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HFONT CreateFontIndirect(const LOGFONT *lplf);

Parameters

lplf
[in] Long pointer to a LOGFONT structure that defines the characteristics of the logical font.

Return Values

A handle to a logical font indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateFontIndirect function creates a logical font with the characteristics specified in the LOGFONT structure. When this font is selected by using the SelectObject function, GDI’s font mapper attempts to match the logical font with an existing physical font. If it fails to find an exact match, it provides an alternative whose characteristics match as many of the requested characteristics as possible.

When you no longer need the font, call the DeleteObject function to delete it.

Windows CE versions 2.0 and later support systems that use either TrueType or raster fonts but not both. The font type (raster or TrueType) is chosen at system design time, and cannot be changed by an application.

Windows CE versions 1.0 and 1.01 support only raster fonts.

See Also

DeleteObject, LOGFONT, SelectObject


CreateIconIndirect

This function creates an icon or cursor from an ICONINFO structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HICON CreateIconIndirect(PICONINFO piconinfo);

Parameters

piconinfo
[in] Pointer to an ICONINFO structure the function uses to create the icon or cursor.

Return Values

A handle to the icon or cursor that is created indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The system copies the bitmaps in the ICONINFO structure before creating the icon. Because the system may temporarily select the bitmaps in a device context, the hbmMask and hbmColor members of the ICONINFO structure should not already be selected into a device context. The application must continue to manage the original bitmaps and delete them when they are no longer necessary.

When using Iconcurs.dll, call the CreateIconIndirect function to create either icons or monochrome cursors. Windows CE does not support color cursors.

Hotspots should be created with positive location values. If a hotspot is created with negative location values, there is no way to determine where it appears.

When you are finished using the icon, destroy it using the DestroyIcon function.

See Also

DestroyIcon, DrawIcon, ICONINFO, LoadIcon


CreateMenu

This function creates a menu. The menu is initially empty, but it can be filled with menu items by using the AppendMenu and InsertMenu functions.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HMENU CreateMenu(void);

Return Values

The handle to the newly created menu indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

Resources associated with a menu that is assigned to a window are freed automatically. If the menu is not assigned to a window, an application must free system resources associated with the menu before closing. An application frees menu resources by calling the DestroyMenu function.

See Also

AppendMenu, CreatePopupMenu, DestroyMenu, InsertMenu


CreatePalette

This function creates a logical color palette.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

HPALETTE CreatePalette( CONST LOGPALETTE * lplgpl);

Parameters

lplgpl
[in] Long pointer to a LOGPALETTE structure that contains information about the colors in the logical palette.

Return Values

A handle that identifies a logical palette indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

Once an application creates a logical palette, it can select that palette into a device context by calling the SelectPalette function. A palette selected into a device context can be realized by calling the RealizePalette function.

When you no longer need the palette, call the DeleteObject function to delete it.

Because Windows CE does not arbitrate between the palettes of the foreground and background applications, palettes are not automatically padded with Windows systems colors. Therefore, the number of color entries in the palette created by this function is always the same as the palNumEntries member of the LOGPALETTE structure.

See Also

GetDeviceCaps, RealizePalette, SelectPalette


CreatePatternBrush

This function creates a logical brush with the specified bitmap pattern.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

HBRUSH CreatePatternBrush( HBITMAP hbmp);

Parameters

hbmp
[in] Handle to the bitmap to be used to create the logical brush.

Return Values

A handle that identifies a logical brush indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

A pattern brush is a bitmap, which can be of an arbitrary size, that the system uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreatePatternBrush, it can select that brush into any device context by calling the SelectObject function.

You can delete a pattern brush without affecting the associated bitmap by using the DeleteObject function. Therefore, you can then use this bitmap to create any number of pattern brushes.

A brush created by using a monochrome (1 bit per pixel) bitmap has the text and background colors of the device context to which it is drawn. Pixels represented by a 0 bit are drawn with the current text color; pixels represented by a 1 bit are drawn with the current background color.

See Also

CreateDibSection


CreatePen

This function creates a logical pen that has the specified style, width, and color. The pen can subsequently be selected into a device context and used to draw lines and curves.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

HPEN CreatePen( int fnPenStyle, int nWidth, COLORREF crColor);

Parameters

fnPenStyle
[in] Specifies the pen style. It can be any one of the following values:
Value
Description
PS_SOLID | Pen is solid.
PS_DASH | Pen is dashed. This style is valid only when the pen width is one or less in device units.
PS_NULL | Pen is invisible.

nWidth
[in] Specifies the width of the pen, in logical units. If nWidth is zero, the pen is a single pixel wide, regardless of the current transformation.

CreatePen returns a pen with the specified width bit with the PS_SOLID style if you specify a width greater than one for the PS_DASH style.

crColor
[in] Specifies a color reference for the pen color.

Return Values

Handle to a logical pen indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

If the value specified by the nWidth parameter is zero, a line drawn with the created pen will always be a single pixel wide regardless of the current transformation.

If the value specified by nWidth is greater than 1, the fnPenStyle parameter must be PS_NULL or PS_SOLID.

User-specified endcap styles, such as PS_ENDCAP_ROUND, are not supported.

When you no longer need the pen, call the DeleteObject function to delete it.

See Also

CreatePenIndirect


CreatePenIndirect

This function creates a logical cosmetic pen that has the style, width, and color specified in the LOGPEN structure.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HPEN CreatePenIndirect(const LOGPEN * lplgpn);

Parameters

lplgpn
[in] Long pointer to the LOGPEN structure that specifies the pen's style, width, and color.

Return Values

A handle that identifies a logical cosmetic pen indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

When you no longer need the pen, call the DeleteObject function to delete it.

See Also

CreateDIBPatternBrushPt, DeleteObject, SelectObject


CreatePopupMenu

This function creates a pop-up menu. The menu is initially empty. You can fill it with menu items by using the InsertMenu and AppendMenu functions.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HMENU CreatePopupMenu(void);

Return Values

The handle to the newly created menu indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The application can add the new menu to an existing menu, or it can display a shortcut menu by calling the TrackPopupMenuEx or TrackPopupMenu functions.

Resources associated with a menu that is assigned to a window are freed automatically. If the menu is not assigned to a window, an application must free system resources associated with the menu before closing. An application frees menu resources by calling the DestroyMenu function.

See Also

AppendMenu, CreateMenu, DestroyMenu, InsertMenu, TrackPopupMenu


CreatePropertySheetPage

This function creates a new page for a property sheet.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

HPROPSHEETPAGE CreatePropertySheetPage(
LPCPROPSHEETPAGE lppsp);

Parameters

lppsp
[in] Long pointer to a PROPSHEETPAGE structure that defines a page to be included in a property sheet.

Return Values

The handle to the new property sheet indicates success. NULL indicates failure.

Remarks

An application uses the PropertySheet function to create a property sheet that includes the new page, or it uses the PSM_ADDPAGE message to add the new page to an existing property sheet.


CreateRectRgn

This function creates a rectangular region.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

HRGN CreateRectRgn( int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

nLeftRect
[in] Specifies the x-coordinate of the upper-left corner of the region.
nTopRect
[in] Specifies the y-coordinate of the upper-left corner of the region.
nRightRect
[in] Specifies the x-coordinate of the lower-right corner of the region.
nBottomRect
[in] Specifies the y-coordinate of the lower-right corner of the region.

Return Values

The handle to the region indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The region will be exclusive of the bottom and right edges.

Windows CE represents regions using 16-bit values.

See Also

CreateRectRgnIndirect


CreateRectRgnIndirect

This function creates a rectangular region.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HRGN CreateRectRgnIndirect(const RECT * lprc);

Parameters

lprc
[in] Long pointer to a RECT structure that contains the coordinates of the upper-left and lower-right corners of the rectangle that defines the region.

Return Values

The handle to the region indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The region will be exclusive of the bottom and right edges.

Windows CE represents regions using 16-bit values.

See Also

DeleteObject, RECT, SelectObject


CreateSolidBrush

This function creates a logical brush that has the specified solid color.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HBRUSH CreateSolidBrush( COLORREF crColor);

Parameters

crColor
[in] Specifies the color of the brush.

Return Values

A handle that identifies a logical brush indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

A solid brush is a bitmap that the system uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateSolidBrush, it can select that brush into any device context by calling the SelectObject function.

Windows CE does not support dithered brushes.


CreateStatusWindow

This function creates a status window, which is typically used to display the status of an application. The window generally appears at the bottom of the parent window, and it contains the specified text.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateStatusWindow(LONG style, LPSTR lpszText,
HWND hwndParent, WORD wID);

Parameters

style
Window styles for the status window. This parameter must include the WS_CHILD style and should also include the WS_VISIBLE style.
lpszText
Long pointer to a null-terminated string that contains the status text for the first part.
hwndParent
Handle to the parent window.
wID
Control identifier for the status window. The window procedure uses this value to identify messages it sends to the parent window.

Return Values

The handle for the status window indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateStatusWindow function calls the CreateWindow function to create the window. It passes the parameters to CreateWindow without modification and sets the position, width, and height parameters to default values.

See Also

CreateWindow


CreateToolbarEx

This function creates a toolbar window and adds the specified buttons to the toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HWND CreateToolbarEx(HWND hwnd, DWORD ws, UINT wID,
int nBitmaps, HINSTANCE hBMInst, UINT wBMID,
LPCTBBUTTON lpButtons, int iNumButtons, int dxButton, int dyButton,
int dxBitmap, int dyBitmap, UINT uStructSize);

Parameters

hwnd
Handle to the parent window for the toolbar.
ws
Specifies the window styles for the toolbar. This parameter must specify at least the WS_CHILD style.
wID
Control identifier for the toolbar.
nBitmaps
Number of button images contained in the bitmap specified by hBMInst and wBMID.
hBMInst
Handle to the module instance with the executable file that contains the bitmap resource.
wBMID
Resource identifier for the bitmap resource. If hBMInst is NULL, this parameter must be a valid bitmap handle.
lpButtons
Long pointer to an array of TBBUTTON structures that contain information about the buttons to add to the toolbar.
iNumButtons
Number of buttons to add to the toolbar.
dxButton
Specifies the width, in pixels, of the buttons to add to the toolbar.
dyButton
Specifies the height, in pixels, of the buttons to add to the toolbar.
dxBitmap
Specifies the width, in pixels, of the button images to add to the buttons in the toolbar.
dyBitmap
Specifies the height, in pixels, of the button images to add to the buttons in the toolbar.
uStructSize
Unsigned integer that contains the size of a TBBUTTON structure.

Return Values

The window handle to the toolbar indicates success. NULL indicates failure. To get extended error information, call GetLastError.

See Also

TBBUTTON


CreateUpDownControl

This function creates an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateUpDownControl(DWORD dwStyle, int x, int y, int cx, int cy,
HWND hwndParent, int nID, HINSTANCE hinst, HWND hwndBuddy,
int nUpper, int nLower, int nPos);

Parameters

dwStyle
Specifies the window styles for the control. This parameter should include the WS_CHILD, WS_BORDER, and WS_VISIBLE styles, and it may include any of the window styles specific to the up-down control.
x
Horizontal coordinate, in client coordinates, of the upper-left corner of the control.
y
Vertical coordinate, in client coordinates, of the upper-left corner of the control.
cx
Width, in pixels, of the up-down control.
cy
Height, in pixels, of the up-down control.
hParent
Handle to the parent window of the up-down control.
nID
Identifier for the up-down control.
hInst
Handle to the module instance of the application creating the up-down control.
hBuddy
Handle to the window associated with the edit up-down control. An edit control is the only up-down control that has a buddy window. If this parameter is NULL, the control has no buddy window.
nUpper
Upper limit (range) of the up-down control.
nLower
Lower limit (range) of the up-down control.
nPos
Position of the control.

Return Values

The window handle to the up-down control indicates success. NULL indicates failure.

Remarks

The only buddy window for up-down controls is an edit control.

See Also

SetDlgItemInt


CreateWindow

This function creates an overlapped, pop-up, or child window. It specifies the window class, window title, window style, and, optionally, the initial position and size of the window. This function also specifies the window's parent.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateWindow( LPCTSTR lpClassName, LPCTSTR lpWindowName, DWORD dwStyle, int x, int y, int nWidth, int nHeight, HWND hWndParent,
HMENU hMenu, HANDLE hInstance, PVOID lpParam);

Parameters

lpClassName
Long pointer to a null-terminated string or is an integer atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names. For a complete list, see the Remarks section.

lpWindowName
Long pointer to a null-terminated string that specifies the window name.

If the window style specifies a title bar, the window title pointed to by lpWindowName is displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static controls, use lpWindowName to specify the text of the control.

dwStyle
Specifies the style of the window being created. This parameter can be a combination of the following window styles, plus the control styles indicated in the Remarks section.
Value
Description
WS_BORDER | Creates a window that has a thin-line border.
WS_CAPTION | Creates a window that has a title bar (includes the WS_BORDER style).
WS_CHILD | Creates a child window. This style cannot be used with the WS_POPUP style.
WS_CHILDWINDOW | Same as the WS_CHILD style.
WS_CLIPCHILDREN | Excludes the area occupied by child windows when drawing occurs within the parent window. This style is used when creating the parent window.
WS_CLIPSIBLINGS | Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, the WS_CLIPSIBLINGS style clips all other overlapping child windows out of the region of the child window to be updated. If WS_CLIPSIBLINGS is not specified and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.
WS_DISABLED | Creates a window that is initially disabled. A disabled window cannot receive input from the user.
WS_DLGFRAME | Creates a window that has a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.
WS_GROUP | Specifies the first control of a group of controls. The group consists of this first control and all controls defined after it, up to the next control with the WS_GROUP style. The first control in each group usually has the WS_TABSTOP style so that the user can move from group to group. The user can subsequently change the keyboard focus from one control in the group to the next control in the group by using the direction keys.
WS_HSCROLL | Creates a window that has a horizontal scroll bar.
WS_ICONIC | Creates a window that is initially minimized. Same as the WS_MINIMIZE style.
WS_MAXIMIZE | Creates a window that is initially maximized.
WS_MAXIMIZEBOX | Creates a window that has a Maximize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_MINIMIZE | Creates a window that is initially minimized. Same as the WS_ICONIC style.
WS_MINIMIZEBOX | Creates a window that has a Minimize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_OVERLAPPED | Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_TILED style.
WS_OVERLAPPEDWINDOW | Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_TILEDWINDOW style.
WS_POPUP | Creates a pop-up window. This style cannot be used with the WS_CHILD style.
WS_POPUPWINDOW | Creates a pop-up window with WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW styles must be combined to make the window menu visible.
WS_SIZEBOX | Creates a window that has a sizing border. Same as the WS_THICKFRAME style.
WS_SYSMENU | Creates a window that has a window-menu on its title bar. The WS_CAPTION style must also be specified.
WS_TABSTOP | Specifies a control that can receive the keyboard focus when the user presses the TAB key. Pressing the TAB key changes the keyboard focus to the next control with the WS_TABSTOP style.
WS_THICKFRAME | Creates a window that has a sizing border. Same as the WS_SIZEBOX style.
WS_TILED | Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_OVERLAPPED style.
WS_TILEDWINDOW | Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_OVERLAPPEDWINDOW style.
WS_VISIBLE | Creates a window that is initially visible.
WS_VSCROLL | Creates a window that has a vertical scroll bar.

x
Specifies the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window’s client area.

If this parameter is set to CW_USEDEFAULT, the system selects the default position for the window’s upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.

y
Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window’s client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box’s client area relative to the upper-left corner of the parent window’s client area.

If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, the system ignores the y parameter.

nWidth
Specifies the width, in device units, of the window. For overlapped windows, nWidth is either the window’s width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, the system selects a default width and height for the window; the default width extends from the initial x-coordinate to the right edge of the screen, and the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, nWidth and nHeight are set to zero.
nHeight
Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window’s height, in screen coordinates. If nWidth is set to CW_USEDEFAULT, the system ignores nHeight.
hWndParent
Handle to the parent or owner window of the window being created. To create a child window or an owned window, supply a valid window handle. This parameter is optional for pop-up windows.

Windows NT 5.0 and later: To create a message-only window, supply HWND_MESSAGE or a handle to an existing message-only window.

hMenu
Handle to a menu, or specifies a child-window identifier depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.
hInstance
Handle to the instance of the module to be associated with the window.
lpParam
Long pointer to a value to be passed to the window through the CREATESTRUCT structure passed in the lParam parameter the WM_CREATE message.

Return Values

A handle to the new window indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateWindow function does not support the WM_NCDESTROY or the WM_PARENTNOTIFY message.

CreateWindow is implemented as a macro. It is defined as CreateWindowEx, but with the dwExStyle parameter set to 0L.

If lpClassName is an atom, it must be an atom returned from RegisterClass.

Menu bars are not supported. The hMenu parameter must be NULL, unless it is used as a child-window identifier.

The MDICLIENT window class is not supported.

The dwStyle parameter can be a combination of the window styles and control styles documented in Window and Message Box Styles and Control Styles.

The following dwStyle flags are not supported for windows:

WS_CHILDWINDOW | WS_ICONIC
WS_MAXIMIZE | WS_MAXIMIZEBOX
WS_MINIMIZE | WS_MINIMIZEBOX
WS_OVERLAPPEDWINDOW | WS_POPUPWINDOW
WS_SIZEBOX | WS_THICKFRAME
WS_TILED | WS_TILEDWINDOW

The following dwStyle flags are not supported for controls and dialog boxes:

Unsupported button styles | Unsupported static control styles
BS_LEFTTEXT | SS_BLACKFRAME
BS_MULTILINE | SS_GRAYFRAME
BS_TEXT | SS_METAPICT
BS_USERBUTTON | SS_SIMPLE
Unsupported combo box styles | SS_WHITERECT
CBS_OWNERDRAWFIXED | SS_BLACKRECT
CBS_OWNERDRAWVARIABLE | SS_GRAYRECT
CBS_SIMPLE | SS_RIGHTIMAGE
Unsupported list box control styles | SS_WHITEFRAME
LBS_NODATA | Unsupported dialog box styles
LBS_OWNERDRAWFIXED | DS_ABSALIGN
LBS_OWNERDRAWVARIABLE | DS_CENTERMOUSE
LBS_STANDARD | DS_CONTEXTHELP
Unsupported scroll bar styles | DS_FIXEDSYS
SBS_BOTTOMALIGN | DS_NOFAILCREATE
SBS_RIGHTALIGN | DS_NOIDLEMSG
SBS_SIZEBOXBOTTOMRIGHTALIGN | DS_SYSMODAL
SBS_SIZEGRIP |

You can use the BS_OWNERDRAW style as a substitute for the BS_USERBUTTON style.

You can use the SS_LEFT or SS_LEFTNOWORDWRAP style instead of the SS_SIMPLE style for static controls.

All windows implicitly have the WS_CLIPSIBLINGS and WS_CLIPCHILDREN styles.

Windows CE version 1.0 does not support owned windows, except for dialog boxes. If the hwndParent parameter is not NULL, the window is implicitly given the WS_CHILD style.

Windows CE version 1.0 does not support menu bars.

For Windows CE versions 2.10 and later, if nWidth and nHeight are set to CW_USEDEFAULT, the child window has dimensions of 0 x 0.

Before returning, CreateWindow sends a WM_CREATE message to the window procedure. For overlapped, pop-up, and child windows, CreateWindow sends WM_CREATE messages to the window. The lParam parameter of the WM_CREATE message contains a pointer to a CREATESTRUCT structure. If the WS_VISIBLE style is specified, CreateWindow sends the window all the messages required to activate and show the window.

The following predefined control classes can be specified in the lpClassName parameter. Note the corresponding control styles you can use in the dwStyle parameter.

BUTTON
Designates a small rectangular child window that represents a button the user can click to turn it on or off. Button controls can be used alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them. For more information about buttons and the styles you can specify in the dwStyle parameter, see Control Styles.
COMBOBOX
Designates a control consisting of a list box and a selection field similar to an edit control. When using this style, an application should either display the list box at all times or enable a drop-down list box. If the list box is visible, typing characters into the selection field highlights the first list box entry that matches the characters typed. Conversely, selecting an item in the list box displays the selected text in the selection field. For more information about combo boxes and the styles you can specify in the dwStyle parameter, see Control Styles.
EDIT
Designates a rectangular child window into which the user can type text from the keyboard. The user selects the control and gives it the keyboard focus by clicking it or moving to it by pressing the TAB key. The user can type text when the edit control displays a flashing caret; use the mouse to move the cursor, select characters to be replaced, or position the cursor for inserting characters; or use the BACKSPACE key to delete characters. For more information about edit controls and the styles you can specify in the dwStyle parameter, see Control Styles.
LISTBOX
Designates a list of character strings. Specify this control whenever an application must present a list of names, such as filenames, from which the user can choose. The user can select a string by clicking it. A selected string is highlighted, and a notification message is passed to the parent window. For more information about list boxes and the styles you can specify in the dwStyle parameter, see Control Styles.
MDICLIENT
Designates an MDI client window. This window receives messages that control the MDI application’s child windows. The recommended style bits are WS_CLIPCHILDREN and WS_CHILD. Specify the WS_HSCROLL and WS_VSCROLL styles to create an MDI client window that allows the user to scroll MDI child windows into view.
RichEdit
Designates a Rich Edit version 1.0 control. This window lets the user view and edit text with character and paragraph formatting, and can include embedded COM objects.
RICHEDIT_CLASS
Designates a Rich Edit version 2.0 control. This controls let the user view and edit text with character and paragraph formatting, and can include embedded COM objects.
SCROLLBAR
Designates a rectangle that contains a scroll box and has direction arrows at both ends. The scroll bar sends a notification message to its parent window whenever the user clicks the control. The parent window is responsible for updating the position of the scroll box, if necessary. For more information about scroll bars and the styles you can specify in the dwStyle parameter, see Control Styles.
STATIC
Designates a simple text field, box, or rectangle used to label, box, or separate other controls. Static controls take no input and provide no output. For more information about static controls and the styles you can specify in the dwStyle parameter, see Creating Controls.

Note If you specify Windows version 4.x when linking your application, its windows cannot have caption buttons unless they also have window menus. This is not a requirement if you specify Windows version 3.x when linking your application.

See Also

CreateDialog, CREATESTRUCT, CreateWindowEx, DialogBox, DLGTEMPLATE, DRAWITEMSTRUCT, LB_GETTEXT, LB_SETCOLUMNWIDTH, MessageBox, RegisterClass, SetForegroundWindow, WM_COMMAND, WM_CREATE, WM_DELETEITEM, WM_DRAWITEM, WM_MEASUREITEM, WM_PAINT, WM_SETFONT, WM_SETREDRAW, WM_VKEYTOITEM


CreateWindowEx

This function creates an overlapped, pop-up, or child window with an extended style; otherwise, this function is identical to the CreateWindow function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND CreateWindowEx(DWORD dwExStyle, LPCTSTR lpClassName, LPCTSTR lpWindowName, DWORD dwStyle, int x, int y, int nWidth,
int nHeight, HWND hWndParent, HMENU hMenu, HINSTANCE hInstance,
LPVOID lpParam);

Parameters

dwExStyle
Specifies the extended style of the window. This parameter can be one of the following values:
Value
Description
WS_EX_ACCEPTFILES | Specifies that a window created with this style accepts drag-drop files.
WS_EX_APPWINDOW | Forces a top-level window onto the taskbar when the window is visible.
WS_EX_CLIENTEDGE | Specifies that a window has a border with a sunken edge.
WS_EX_CONTEXTHELP | Includes a question mark in the title bar of the window. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a child window, the child receives a WM_HELP message. The Help application displays a pop-up window that typically contains help for the child window.
WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
WS_EX_DLGMODALFRAME | Creates a window that has a double border; the window can, optionally, be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter.
WS_EX_LEFT | Creates a window that has generic “left-aligned” properties. This is the default.
WS_EX_LEFTSCROLLBAR | If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the vertical scroll bar (if present) is to the left of the client area. For other languages, the style is ignored.
WS_EX_LTRREADING | The window text is displayed using left-to-right reading-order properties. This is the default.
WS_EX_MDICHILD | Creates an MDI child window.
WS_EX_NOACTIVATE | A top-level window created with this style cannot be activated. If a child window has this style, tapping it does not cause its top-level parent to be activated. A window that has this style receives stylus events, but neither it nor its child windows can get the focus. Supported in Windows CE versions 2.0 and later.
WS_EX_NOANIMATION | A window created with this style does not show animated exploding and imploding rectangles, and does not have a button on the taskbar. Supported in Windows CE versions 2.0 and later.
WS_EX_NOPARENTNOTIFY | Specifies that a child window created with this style does not send the WM_PARENTNOTIFY message to its parent window when it is created or destroyed.
WS_EX_OVERLAPPEDWINDOW | Combines the WS_EX_CLIENTEDGE and WS_EX_WINDOWEDGE styles.
WS_EX_PALETTEWINDOW | Combines the WS_EX_WINDOWEDGE, WS_EX_TOOLWINDOW, and WS_EX_TOPMOST styles.
WS_EX_RIGHT | The window has generic “right-aligned” properties. This depends on the window class. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading-order alignment; otherwise, the style is ignored.
WS_EX_RIGHTSCROLLBAR | Vertical scroll bar (if present) is to the right of the client area. This is the default.
WS_EX_RTLREADING | If the shell language is Hebrew, Arabic, or another language that supports reading-order alignment, the window text is displayed using right-to-left reading-order properties. For other languages, the style is ignored.
WS_EX_STATICEDGE | Creates a window with a three-dimensional border style intended to be used for items that do not accept user input.
WS_EX_TOOLWINDOW | Creates a tool window; that is, a window intended to be used as a floating toolbar. A tool window has a title bar that is shorter than a normal title bar, and the window title is drawn using a smaller font. A tool window does not appear in the taskbar or in the dialog that appears when the user presses ALT+TAB. If a tool window has a system menu, its icon is not displayed on the title bar. However, you can display the system menu by right-clicking or by typing ALT+SPACE.
WS_EX_TOPMOST | Specifies that a window created with this style should be placed above all non-topmost windows and should stay above them, even when the window is deactivated. To add or remove this style, use the SetWindowPos function.
WS_EX_TRANSPARENT | Specifies that a window created with this style should not be painted until siblings beneath the window (that were created by the same thread) have been painted. The window appears transparent because the bits of underlying sibling windows have already been painted.
To achieve transparency without these restrictions, use the SetWindowRgn function.
WS_EX_WINDOWEDGE | Specifies that a window has a border with a raised edge.

Using the WS_EX_RIGHT style for static or edit controls has the same effect as using the SS_RIGHT or ES_RIGHT style, respectively. Using this style with button controls has the same effect as using BS_RIGHT and BS_RIGHTBUTTON styles.

lpClassName
Long pointer to a null-terminated string or is an integer atom. If lpClassName is an atom, it must be a global atom created by a previous call to GlobalAddAtom. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names.

lpWindowName
Long pointer to a null-terminated string that specifies the window name.

If the window style specifies a title bar, the window title pointed to by lpWindowName is displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static controls, use lpWindowName to specify the text of the control.

dwStyle
Specifies the style of the window being created. This parameter can be a combination of the following window styles, plus the control styles indicated in the Remarks section.
Value
Description
WS_BORDER | Creates a window that has a thin-line border.
WS_CAPTION | Creates a window that has a title bar (includes the WS_BORDER style).
WS_CHILD | Creates a child window. This style cannot be used with the WS_POPUP style.
WS_CHILDWINDOW | Same as the WS_CHILD style.
WS_CLIPCHILDREN | Excludes the area occupied by child windows when drawing occurs within the parent window. This style is used when creating the parent window.
WS_CLIPSIBLINGS | Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, the WS_CLIPSIBLINGS style clips all other overlapping child windows out of the region of the child window to be updated. If WS_CLIPSIBLINGS is not specified and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.
WS_DISABLED | Creates a window that is initially disabled. A disabled window cannot receive input from the user.
WS_DLGFRAME | Creates a window that has a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.
WS_GROUP | Specifies the first control of a group of controls. The group consists of this first control and all controls defined after it, up to the next control with the WS_GROUP style. The first control in each group usually has the WS_TABSTOP style so that the user can move from group to group. The user can subsequently change the keyboard focus from one control in the group to the next control in the group by using the direction keys.
WS_HSCROLL | Creates a window that has a horizontal scroll bar.
WS_ICONIC | Creates a window that is initially minimized. Same as the WS_MINIMIZE style.
WS_MAXIMIZE | Creates a window that is initially maximized.
WS_MAXIMIZEBOX | Creates a window that has a Maximize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_MINIMIZE | Creates a window that is initially minimized. Same as the WS_ICONIC style.
WS_MINIMIZEBOX | Creates a window that has a Minimize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_OVERLAPPED | Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_TILED style.
WS_OVERLAPPEDWINDOW | Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_TILEDWINDOW style.
WS_POPUP | Creates a pop-up window. This style cannot be used with the WS_CHILD style.
WS_POPUPWINDOW | Creates a pop-up window with WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW styles must be combined to make the window menu visible.
WS_SIZEBOX | Creates a window that has a sizing border. Same as the WS_THICKFRAME style.
WS_SYSMENU | Creates a window that has a window menu on its title bar. The WS_CAPTION style must also be specified.
WS_TABSTOP | Specifies a control that can receive the keyboard focus when the user presses the TAB key. Pressing the TAB key changes the keyboard focus to the next control with the WS_TABSTOP style.
WS_THICKFRAME | Creates a window that has a sizing border. Same as the WS_SIZEBOX style.
WS_TILED | Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_OVERLAPPED style.
WS_TILEDWINDOW | Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_OVERLAPPEDWINDOW style.
WS_VISIBLE | Creates a window that is initially visible.
WS_VSCROLL | Creates a window that has a vertical scroll bar.

x
Specifies the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window’s client area.

If x is set to CW_USEDEFAULT, the system selects the default position for the window’s upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.

y
Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window’s upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window’s client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box’s client area relative to the upper-left corner of the parent window’s client area.

If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, the system ignores the y parameter.

nWidth
Specifies the width, in device units, of the window. For overlapped windows, nWidth is the window’s width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, the system selects a default width and height for the window; the default width extends from the initial x-coordinates to the right edge of the screen; the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, the nWidth and nHeight parameter are set to zero.
nHeight
Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window’s height, in screen coordinates. If the nWidth parameter is set to CW_USEDEFAULT, the system ignores nHeight.
hWndParent
Handle to the parent or owner window of the window being created. To create a child window or an owned window, supply a valid window handle. This parameter is optional for pop-up windows.
hMenu
Handle to a menu, or specifies a child-window identifier, depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.
hInstance
Handle to the instance of the module to be associated with the window.
lpParam
Long pointer to a value to be passed to the window through the CREATESTRUCT structure passed in the lParam parameter the WM_CREATE message.

Return Values

A handle to the new window indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE does not support stand-alone menu bars. The hMenu parameter must be NULL, unless it is used as a child-window identifier.

If lpClassName is an atom, it must be an atom returned from RegisterClass.

For more information about creating a window and for full descriptions of the other parameters of CreateWindowEx, see CreateWindow.

The following dwExStyle flags are not supported:

WS_EX_ACCEPTFILES | WS_EX_LEFTSCROLLBAR
WS_EX_LEFT | WS_EX_MDICHILD
WS_EX_LTRREADING | WS_EX_PALETTEWINDOW
WS_EX_NOPARENTNOTIFY | WS_EX_RIGHTSCROLLBAR
WS_EX_RIGHT | WS_EX_TRANSPARENT
WS_EX_RTLREADING | WS_EX_APPWINDOW

Windows CE version 1.0 does not support the WS_EX_TOPMOST style. Versions 2.0 and later do.

Windows CE versions 1.0 and 2.0 do not support the WS_EX_TOOLWINDOW style. Versions 2.10 and later do.

The following dwStyle flags are not supported:

WS_CHILDWINDOW | WS_ICONIC
WS_MAXIMIZE | WS_MAXIMIZEBOX
WS_MINIMIZE | WS_MINIMIZEBOX
WS_OVERLAPPEDWINDOW | WS_POPUPWINDOW
WS_SIZEBOX | WS_THICKFRAME
WS_TILED | WS_TILEDWINDOW

All windows implicitly have the WS_CLIPSIBLINGS and WS_CLIPCHILDREN styles.

Windows CE version 1.0 does not support owned windows, except for dialog boxes. If the hwndParent parameter is not NULL, the window is implicitly given the WS_CHILD style.

The CreateWindowEx function sends WM_NCCALCSIZE and WM_CREATE messages to the window being created.

The following predefined control classes can be specified in the lpClassName parameter. Note the corresponding control styles you can use in the dwStyle parameter.

BUTTON
Designates a small rectangular child window that represents a button the user can click to turn it on or off. Button controls can be used alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them. For more information about buttons and the styles you can specify in the dwStyle parameter, see Control Styles.
COMBOBOX
Designates a control consisting of a list box and a selection field similar to an edit control. When using this style, an application should either display the list box at all times or enable a drop-down list box. If the list box is visible, typing characters into the selection field highlights the first list box entry that matches the characters typed. Conversely, selecting an item in the list box displays the selected text in the selection field. For more information about combo boxes and the styles you can specify in the dwStyle parameter, see Control Styles.
EDIT
Designates a rectangular child window into which the user can type text from the keyboard. The user selects the control and gives it the keyboard focus by clicking it or moving to it by pressing the TAB key. The user can type text when the edit control displays a flashing caret; use the mouse to move the cursor, select characters to be replaced, or position the cursor for inserting characters; or use the BACKSPACE key to delete characters. For more information about edit controls and the styles you can specify in the dwStyle parameter, see Control Styles.
LISTBOX
Designates a list of character strings. Specify this control whenever an application must present a list of names, such as filenames, from which the user can choose. The user can select a string by clicking it. A selected string is highlighted, and a notification message is passed to the parent window. For more information about list boxes and the styles you can specify in the dwStyle parameter, see Control Styles.
MDICLIENT
Designates an MDI client window. This window receives messages that control the MDI application’s child windows. The recommended style bits are WS_CLIPCHILDREN and WS_CHILD. Specify the WS_HSCROLL and WS_VSCROLL styles to create an MDI client window that allows the user to scroll MDI child windows into view.
RichEdit
Designates a Rich Edit version 1.0 control. This window lets the user view and edit text with character and paragraph formatting, and can include embedded COM objects.
RICHEDIT_CLASS
Designates a Rich Edit version 2.0 control. This controls let the user view and edit text with character and paragraph formatting, and can include embedded COM objects.
SCROLLBAR
Designates a rectangle that contains a scroll box and has direction arrows at both ends. The scroll bar sends a notification message to its parent window whenever the user clicks the control. The parent window is responsible for updating the position of the scroll box, if necessary. For more information about scroll bars and the styles you can specify in the dwStyle parameter, see Control Styles.
STATIC
Designates a simple text field, box, or rectangle used to label, box, or separate other controls. Static controls take no input and provide no output. For more information about static controls and the styles you can specify in the dwStyle parameter, see Control Styles.

See Also

CREATESTRUCT, CreateWindow, RegisterClass, SetWindowPos, WM_CREATE, WM_PAINT


DefDlgProc to DrawText


DefDlgProc

This function carries out default message processing for a window procedure belonging to an application-defined dialog box class.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LRESULT DefDlgProc( HWND hDlg, UINT Msg, WPARAM wParam, LPARAM lParam );

Parameters

hDlg
[in] Handle to the dialog box.
Msg
[in] Specifies the message number.
wParam
[in] Specifies additional message-specific information.
lParam
[in] Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

The DefDlgProc function is the window procedure for the predefined class of dialog box. This procedure provides internal processing for the dialog box by forwarding messages to the dialog box procedure and carrying out default processing for any messages that the dialog box procedure returns as FALSE. Applications that create custom window procedures for their custom dialog boxes often use DefDlgProc instead of the DefWindowProc function to carry out default message processing.

Applications create custom dialog box classes by filling a WNDCLASS structure with appropriate information and registering the class with the RegisterClass function. Some applications fill the structure by using the GetClassInfo function, specifying the name of the predefined dialog box. In such cases, the applications modify at least the lpszClassName member before registering. In all cases, the cbWndExtra member of WNDCLASS for a custom dialog box class must be set to at least DLGWINDOWEXTRA.

The DefDlgProc function must not be called by a dialog box procedure; doing so results in recursive execution.

See Also

DefWindowProc, GetClassInfo, RegisterClass, WNDCLASS


DeferWindowPos

This function updates the specified multiple-window position structure for the specified window. The function then returns the handle to the updated structure. The EndDeferWindowPos function uses the information in this structure to change the position and size of a number of windows simultaneously. The BeginDeferWindowPos function creates the structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

HDWP DeferWindowPos( HDWP hWinPosInfo, HWND hWnd,
HWND hWndInsertAfter, int x, int y, int cx, int cy, UNIT uFlags );

Parameters

hWinPosInfo
Handle to a multiple-window—position structure that contains size and position information for one or more windows. This structure is returned by BeginDeferWindowPos or by the most recent call to DeferWindowPos.
hWnd
Handle to the window for which update information is stored in the structure.
hWndInsertAfter
Handle to the window that precedes the positioned window in the z-order. This parameter must be a window handle or one of the following values:
Value
Description
HWND_BOTTOM | Places the window at the bottom of the z-order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST | Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window.
HWND_TOP | Places the window at the top of the z-order.
HWND_TOPMOST | Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.

This parameter is ignored if the SWP_NOZORDER flag is set in the uFlags parameter.

x
Specifies the x-coordinate of the window’s upper-left corner.
y
Specifies the y-coordinate of the window’s upper-left corner.
cx
Specifies the window’s new width, in pixels.
cy
Specifies the window’s new height, in pixels.
uFlags
Specifies a combination of the following values that affect the size and position of the window:
Value
Description
SWP_DRAWFRAME | Draws a frame (defined in the window’s class description) around the window.
SWP_FRAMECHANGED | Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed.
SWP_HIDEWINDOW | Hides the window.
SWP_NOACTIVATE | Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS | Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE | Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER | Does not change the owner window’s position in the z-order.
SWP_NOREDRAW | Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION | Same as the SWP_NOOWNERZORDER flag.
SWP_NOSIZE | Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER | Retains the current z-order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW | Displays the window.

Return Values

The return value identifies the updated multiple-window – position structure. The handle returned by this function may differ from the handle passed to the function. The new handle that this function returns should be passed during the next call to the DeferWindowPos or EndDeferWindowPos function.

NULL indicates that insufficient system resources are available for the function to succeed. To get extended error information, call GetLastError.

Windows CE Remarks

The uFlags parameter does not support the SWP_DRAWFRAME, SWP_NOCOPYBITS, SWP_NOREDRAW, SWP_NOREPOSITION, SWP_NOOWNERZORDER, and SWP_NOSENDCHANGING flags.

Remarks

If a call to DeferWindowPos fails, the application should abandon the window-positioning operation and not call EndDeferWindowPos.

If SWP_NOZORDER is not specified, the system places the window identified by the hWnd parameter in the position following the window identified by the hWndInsertAfter parameter. If hWndInsertAfter is NULL or HWND_TOP, the system places the hWnd window at the top of the z-order. If hWndInsertAfter is set to HWND_BOTTOM, the system places the hWnd window at the bottom of the z-order.

All coordinates for child windows are relative to the upper-left corner of the parent window’s client area.

A window can be made a topmost window either by setting hWndInsertAfter to the HWND_TOPMOST flag and ensuring that the SWP_NOZORDER flag is not set, or by setting the window’s position in the z-order so that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned windows are also made topmost. Its owners, however, are not changed.

If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application requests that a window be simultaneously activated and its position in the z-order changed), the value specified in hWndInsertAfter is used only in the following circumstances:

  • Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.
  • The window identified by hWnd is not the active window.

An application cannot activate an inactive window without also bringing it to the top of the z-order. An application can change an activated window’s position in the z-order without restrictions, or it can activate a window and then move it to the top of the topmost or non-topmost windows.

A topmost window is no longer topmost if it is repositioned to the bottom (HWND_BOTTOM) of the z-order or after any non-topmost window. When a topmost window is made non-topmost, its owners and its owned windows are also made non-topmost windows.

A non-topmost window may own a topmost window, but not vice versa. Any window (for example, a dialog box) owned by a topmost window is itself made a topmost window to ensure that all owned windows stay above their owner.

See Also

BeginDeferWindowPos, EndDeferWindowPos


DefWindowProc

This function calls the default window procedure to provide default processing for any window messages that an application does not process. This function ensures that every message is processed. DefWindowProc is called with the same parameters received by the window procedure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LRESULT DefWindowProc( HWND hWnd, UINT Msg, WPARAM wParam,
LPARAM lParam );

Parameters

hWnd
[in] Handle to the window procedure that received the message.
Msg
[in] Specifies the message
wParam
[in] Specifies additional message information. The content of this parameter depends on the value of the Msg parameter.
lParam
[in] Specifies additional message information. The content of this parameter depends on the value of the Msg parameter.

Return Values

The return value is the result of the message processing and depends on the message. If Msg is WM_SETTEXT, zero is returned.

Remarks

DefWindowProc does not automatically call PostQuitMessage when it handles a WM_DESTROY message.

See Also

CallWindowProc, DefDlgProc, WindowProc


DeleteDC

This function deletes the specified device context (DC).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DeleteDC(HDC hdc);

Parameters

hdc
[in] Handle to the device context.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

An application must not delete a device context whose handle was obtained by calling the GetDC function. Instead, it must call the ReleaseDC function to free the device context.

See Also

GetDC, ReleaseDC


DeleteMenu

This function deletes an item from the specified menu. If the menu item invokes a pop-up menu, DeleteMenu destroys the handle to the pop-up menu and frees the memory used by the pop-up menu.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DeleteMenu(HMENU hMenu, UINT uPosition, UINT uFlags);

Parameters

hMenu
[in] Handle to the menu to be changed.
uPosition
[in] Specifies the menu item to be deleted, as determined by the uFlags parameter.
uFlags
[in] Specifies how the uPosition parameter is interpreted. This parameter must be one of the following values:
Value
Description
MF_BYCOMMAND | Indicates that uPosition gives the identifier of the menu item. The MF_BYCOMMAND flag is the default flag if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION | Indicates that uPosition gives the zero-based relative position of the menu item.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

See Also

RemoveMenu


DeleteObject

This function deletes a logical pen, brush, font, bitmap, region, or palette, freeing all system resources associated with the object. After the object is deleted, the specified handle is no longer valid.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DeleteObject(HGDIOBJ hObject);

Parameters

hObject
[in] Handle to a logical pen, brush, font, bitmap, region, or palette.

Return Values

Nonzero indicates success. Zero indicates that the specified handle is not valid or that the handle is currently selected into a device context. To get extended error information, call GetLastError.

Remarks

Do not delete a drawing object (pen or brush) while it is still selected into a device context.

When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The bitmap must be deleted independently.

See Also

SelectObject


DestroyAcceleratorTable

This function destroys an accelerator table. Before an application closes, it must use this function to destroy each accelerator table that it created by using the CreateAcceleratorTable function.

At a Glance

Header file: | Winuser.h
Versions: | 1.0 and later

Syntax

BOOL DestroyAcceleratorTable(HACCEL hAccel);

Parameters

hAccel
Handle to the accelerator table to destroy. This handle must have been created by a call to the CreateAcceleratorTable function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

CreateAcceleratorTable, LoadAccelerators, TranslateAccelerator


DestroyCaret

This function destroys the caret's current shape, frees the caret from the window, and removes the caret from the screen.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DestroyCaret(void);

Return Values

The return value of this function does not indicate whether the function was successful or not.

Remarks

DestroyCaret destroys the caret only if a window in the current task owns the caret. If a window that is not in the current task owns the caret, DestroyCaret does nothing and returns FALSE.

The system provides one caret per queue. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

See Also

CreateCaret, HideCaret, ShowCaret


DestroyCursor

This function destroys a cursor created by the CreateCursor function and frees any memory the cursor occupied. Do not use this function to destroy a cursor that was not created with the CreateCursor function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DestroyCursor( HCURSOR hCursor );

Parameters

hCursor
[in] Handle to the cursor to be destroyed. The cursor must not be in use.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DestroyCursor function destroys a non-shared cursor. Do not use this function to destroy a shared cursor. A shared cursor is valid as long as the module from which it was loaded remains in memory. The following functions obtain a shared cursor:

  • LoadCursor
  • LoadCursorFromFile
  • LoadImage (if you use the LR_SHARED flag)
  • CopyImage (if you use the LR_COPYRETURNORG flag and the hImage parameter is a shared cursor)

See Also

CreateCursor


DestroyIcon

This function destroys an icon and frees any memory the icon occupied.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DestroyIcon(HICON hIcon);

Parameters

hIcon
[in] Handle to the icon to be destroyed. The icon must not be in use.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DestroyIcon function may be called on the icon handle returned from CreateIconIndirect, ExtractIconEx, LoadImage or LoadIcon. The icon handle is invalid after calling DestroyIcon.

See Also

CreateIconIndirect


DestroyMenu

This function destroys the specified menu and frees any memory that the menu occupies.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DestroyMenu(HMENU hMenu);

Parameters

hMenu
[in] Handle to the menu to be destroyed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Before closing, an application must use the DestroyMenu function to destroy a menu not assigned to a window. A menu that is assigned to a window is automatically destroyed when the application closes.

See Also

CreateMenu, DeleteMenu, RemoveMenu


DestroyPropertySheetPage

This function destroys a property sheet page for the handle returned from the CreatePropertySheetPage function. An application must call this function for pages that have not been passed to the PropertySheet function.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DestroyPropertySheetPage(HPROPSHEETPAGE hPSPage);

Parameters

hPSPage
Handle to the property sheet page to delete.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

CreatePropertySheetPage


DestroyWindow

This function destroys the specified window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DestroyWindow( HWND hWnd );

Parameters

hWnd
Handle to the window to be destroyed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DestroyWindow function does not support the WM_NCDESTROY or the WM_PARENTNOTIFY message.

The DestroyWindow function destroys children of the specified window.

The DestroyWindow function does not flush the thread message queue.

A thread cannot use DestroyWindow to destroy a window created by a different thread.

If the window being destroyed is a child window that does not have the WS_EX_NOPARENTNOTIFY style, a WM_PARENTNOTIFY message is sent to the parent.

See Also

CreateDialog, CreateWindow, CreateWindowEx, WM_DESTROY


DialogBox

This function creates a modal dialog box from a dialog box template resource. DialogBox does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int DialogBox( HINSTANCE hInstance, LPCTSTR lpTemplate,
HWND hWndParent, DLGPROC lpDialogFunc );

Parameters

hInstance
[in] Handle to the module whose executable file contains the dialog box template.
lpTemplate
[in] Long pointer to the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

The value of the nResult parameter in the call to the EndDialog function indicates success. –1 indicates failure. To get extended error information, call GetLastError.

Remarks

The DialogBox macro uses the CreateWindowEx function to create the dialog box. DialogBox then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBox destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the value of the nResult parameter specified by the dialog box procedure when it called EndDialog.

Windows CE does not support all styles in the DLGTEMPLATE structure. This structure is in the template identified by the lpTemplate parameter.

See Also

CreateDialog, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, DialogProc, DLGTEMPLATE, EndDialog, HIWORD, LOWORD, MAKEINTRESOURCE, WM_INITDIALOG


DialogBoxIndirect

This function is defined as a macro and creates a modal dialog box from a dialog box template in memory. The DialogBoxIndirect macro does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int DialogBoxIndirect( HINSTANCE hInstance, LPDLGTEMPLATE lpTemplate, HWND hWndParent, DLGPROC lpDialogFunc );

Parameters

hInstance
[in] Handle to the module that creates the dialog box.
lpTemplate
[in] Long pointer to a global memory object containing a template that DialogBoxIndirect uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template for a dialog box, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended template for a dialog box, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Values

The value of the nResult parameter specified in the call to the EndDialog function indicates success. –1 indicates failure. To get extended error information, call GetLastError.

Remarks

The DialogBoxIndirect macro uses the CreateWindowEx function to create the dialog box. DialogBoxIndirect then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBoxIndirect destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the value of the nResult parameter specified by the dialog box procedure when it called EndDialog.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings.

Windows CE does not support all styles in the DLGTEMPLATE structure. This structure is in the template identified by the lpTemplate parameter.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirectParam, DialogBoxParam, DialogProc, DLGTEMPLATE, DLGITEMTEMPLATE, EndDialog, WM_INITDIALOG


DialogBoxIndirectParam

This function creates a modal dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int DialogBoxIndirectParam( HINSTANCE hInstance,
LPCDLGTEMPLATE hDialogTemplate, HWND hWndParent,
DLGPROC lpDialogFunc, LPARAM dwInitParam );

Parameters

hInstance
[in] Handle to the module that creates the dialog box.
hDialogTemplate
[in] Handle to a global memory object containing a template that DialogBoxIndirectParam uses to create the dialog box. A dialog box template consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format.

In a standard template for a dialog box, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays.

In an extended template for a dialog box, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.

hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Values

The value of the nResult parameter specified in the call to the EndDialog function indicates success. –1 indicates failure. To get extended error information, call GetLastError.

Remarks

The DialogBoxIndirectParam function uses the CreateWindowEx function to create the dialog box. DialogBoxIndirectParam then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBoxIndirectParam destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the value of the nResult parameter specified by the dialog box procedure when it called EndDialog.

In a standard dialog box template, the DLGTEMPLATE structure and each of the DLGITEMTEMPLATE structures must be aligned on DWORD boundaries. The creation data array that follows a DLGITEMTEMPLATE structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

In an extended dialog box template, the DLGTEMPLATEEX header and each of the DLGITEMTEMPLATEEX control definitions must be aligned on DWORD boundaries. The creation data array, if any, that follows a DLGITEMTEMPLATEEX structure must also be aligned on a DWORD boundary. All of the other variable-length arrays in the template must be aligned on WORD boundaries.

All character strings in the dialog box template, such as titles for the dialog box and buttons, must be Unicode strings.

If the user presses ALT+H while the dialog box has the input focus, the system posts a WM_HELP message to the dialog procedure. An application should respond to this message by displaying context-sensitive Help for the dialog box.

For other dialog restrictions, see CreateDialogIndirectParam.

See Also

CreateWindowEx, DialogProc, DialogBox, DialogBoxIndirect, DialogBoxParam, DLGITEMTEMPLATE, DLGTEMPLATE, EndDialog, WM_INITDIALOG


DialogBoxParam

This function creates a modal dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int DialogBoxParam( HINSTANCE hInstance, LPCTSTR lpTemplateName,
HWND hWndParent, DLGPROC lpDialogFunc, PARAM dwInitParam );

Parameters

hInstance
[in] Handle to the module whose executable file contains the dialog box template.
lpTemplateName
[in] Long pointer to the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent
[in] Handle to the window that owns the dialog box.
lpDialogFunc
[in] Long pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
dwInitParam
[in] Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Values

The value of the nResult parameter specified in the call to the EndDialog function indicates success. –1 indicates failure. To get extended error information, call GetLastError.

Remarks

The DialogBoxParam function uses the CreateWindowEx function to create the dialog box. DialogBoxParam then sends a WM_INITDIALOG message to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBoxParam destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the value of the nResult parameter specified by the dialog box procedure when it called EndDialog.

Windows CE does not support all styles in the DLGTEMPLATE structure. This structure is in the template identified by the lpTemplate parameter.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogProc, DLGTEMPLATE, EndDialog, HIWORD, LOWORD, MAKEINTRESOURCE, WM_INITDIALOG


DispatchMessage

This function dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the GetMessage function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LONG DispatchMessage(const MSG *lpmsg);

Parameters

lpmsg
[in] Long pointer to an MSG structure that contains the message.

Return Values

The return value specifies the value returned by the window procedure. Although its meaning depends on the message being dispatched, the return value generally is ignored.

Remarks

The MSG structure must contain valid message values. If the lpmsg parameter points to a WM_TIMER message and the lParam parameter of the WM_TIMER message is not NULL, lParam points to a function that is called instead of the window procedure.

See Also

GetMessage, MSG, PeekMessage, PostMessage, TranslateMessage


DrawEdge

This function draws one or more edges of a rectangle.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DrawEdge(HDC hdc, LPRECT qrc, UINT edge, UINT grfFlags);

Parameters

hdc
[in] Handle to the device context.
qrc
[in] Pointer to a RECT structure that contains the logical coordinates of the rectangle.
edge
[in] Specifies the type of inner and outer edge to draw. This parameter must be a combination of one inner-border flag and one outer-border flag. The inner-border flags are as follows.
Value
Description
BDR_RAISEDINNER | Raised inner edge.
BDR_SUNKENINNER | Sunken inner edge.

The outer-border flags are as follows.
Value
Description
BDR_RAISEDOUTER | Raised outer edge.
BDR_SUNKENOUTER | Sunken outer edge.

Alternatively, the edge parameter can specify one of the following flags.
Value
Description
EDGE_ETCHED | Combination of BDR_SUNKENOUTER and BDR_RAISEDINNER.
EDGE_RAISED | Combination of BDR_RAISEDOUTER and BDR_RAISEDINNER.
EDGE_SUNKEN | Combination of BDR_SUNKENOUTER and BDR_SUNKENINNER.

grfFlags
[in] Specifies the type of border. This parameter can be a combination of the following values.
Value
Description
BF_ADJUST | Rectangle to be adjusted to leave space for client area.
BF_BOTTOM | Bottom of border rectangle.
BF_BOTTOMRIGHT | Bottom and right side of border rectangle.
BF_DIAGONAL | Diagonal border.
BF_DIAGONAL_ENDBOTTOMLEFT | Diagonal border. The end point is the bottom-left corner of the rectangle; the origin is top-right corner.
BF_DIAGONAL_ENDBOTTOMRIGHT | Diagonal border. The end point is the bottom-right corner of the rectangle; the origin is top-left corner.
BF_DIAGONAL_ENDTOPLEFT | Diagonal border. The end point is the top-left corner of the rectangle; the origin is bottom-right corner.
BF_DIAGONAL_ENDTOPRIGHT | Diagonal border. The end point is the top-right corner of the rectangle; the origin is bottom-left corner.
BF_FLAT | Flat border.
BF_LEFT | Left side of border rectangle.
BF_MIDDLE | Interior of rectangle to be filled.
BF_MONO | One-dimensional border.
BF_RECT | Entire border rectangle.
BF_RIGHT | Right side of border rectangle.
BF_SOFT | Soft buttons instead of tiles.
BF_TOP | Top of border rectangle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

RECT


DrawFocusRect

This function draws a rectangle in the style used to indicate that the rectangle has the focus.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DrawFocusRect(HDC hDC, const RECT * lprc);

Parameters

hDC
[in] Handle to the device context.
lprc
[in] Long pointer to a RECT structure that specifies the logical coordinates of the rectangle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Because DrawFocusRect is an XOR function, calling it a second time with the same rectangle removes the rectangle from the screen.

This function draws a rectangle that cannot be scrolled. To scroll an area containing a rectangle drawn by this function, call DrawFocusRect to remove the rectangle from the screen, scroll the area, and then call DrawFocusRect again to draw the rectangle in the new position.

See Also

RECT


DrawFrameControl

This function draws a frame control of the specified type and style.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL DrawFrameControl( HDC hdc, LPRECT lprc, UINT uType,
UINT uState);

Parameters

hdc
Handle to the device context of the window in which to draw the control.
lprc
Long pointer to a RECT structure that contains the logical coordinates of the bounding rectangle for frame control.
uType
Specifies the type of frame control to draw. This parameter can be one of the following values.
Value
Description
DFC_BUTTON | Standard button
DFC_CAPTION | Title bar
DFC_SCROLL | Scroll bar

uState
Specifies the initial state of the frame control. If uType is DFC_BUTTON, uState can be one of the following values.
Value
Description
DFCS_BUTTON3STATE | Three-state button
DFCS_BUTTONCHECK | Check box
DFCS_BUTTONPUSH | Push button
DFCS_BUTTONRADIO | Radio button

If uType is DFC_CAPTION, uState can be one of the following values.
Value
Description
DFCS_CAPTIONCLOSE | Close button
DFCS_CAPTIONHELP | Help button
DFCS_CAPTIONOKBTN | OK button

If uType is DFC_MENU, uState can be one of the following values.
Value
Description
DFCS_MENUARROW | Submenu arrow
DFCS_MENUARROWRIGHT | Submenu arrow pointing left. This is used for the right-to-left cascading menus used with right-to-left languages such as Arabic or Hebrew.
DFCS_MENUBULLET | Bullet
DFCS_MENUCHECK | Check mark

If uType is DFC_SCROLL, uState can be one of the following values.
Value
Description
DFCS_SCROLLCOMBOBOX | Combo box scroll bar
DFCS_SCROLLDOWN | Down arrow of scroll bar
DFCS_SCROLLLEFT | Left arrow of scroll bar
DFCS_SCROLLRIGHT | Right arrow of scroll bar
DFCS_SCROLLUP | Up arrow of scroll bar

The following style can be used to adjust the bounding rectangle of the push button.
Value
Description
DFCS_ADJUSTRECT Bounding rectangle is adjusted to exclude the surrounding edge of the push button.

One or more of the following values can be used to set the state of the control to be drawn.
Value
Description
DFCS_CHECKED | Button is checked.
DFCS_INACTIVE | Button is inactive (grayed).
DFCS_PUSHED | Button is pushed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If uType is DFC_BUTTON and uState is not DFCS_BUTTONPUSH, the frame control is a black-on-white mask (that is, a black frame control on a white background). In such cases, the application must pass a handle to a bitmap memory device control. The application can then use the associated bitmap as the hbmMask parameter to the MaskBlt function, or it can use the device context as a parameter to the BitBlt function using ROPs such as SRCAND and SRCINVERT.

See Also

RECT


DrawIcon

This function draws an icon in the specified device context.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DrawIcon(HDC hDC, int X, int Y, HICON hIcon);

Parameters

hDC
[in] Handle to the device context for a window.
X
[in] Specifies the logical x-coordinate of the upper-left corner of the icon.
Y
[in] Specifies the logical y-coordinate of the upper-left corner of the icon.
hIcon
Handle to the icon to be drawn. The icon resource must have been previously loaded by using the LoadIcon or LoadImage functions.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DrawIcon function is implemented as a macro, defined as DrawIconEx(hdc, x, y, hicon, 0, 0, 0, NULL, DI_NORMAL).

DrawIcon places the icon’s upper-left corner at the location specified by the X and Y parameters. The location is subject to the current mapping mode of the device context.

See Also

DrawIconEx, LoadIcon


DrawIconEx

This function draws an icon in the specified device context, performing the raster operations as specified.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DrawIconEx(HDC hdc, int xLeft, int yTop, HICON hIcon, int cxWidth, int cyWidth, UINT istepIfAniCur, HBRUSH hbrFlickerFreeDraw, UINT diFlags);

Parameters

hdc
[in] Handle to the device context for a window.
xLeft
[in] Specifies the logical x-coordinate of the upper-left corner of the icon.
yTop
[in] Specifies the logical y-coordinate of the upper-left corner of the icon.
hIcon
[in] Handle to the icon to be drawn. The icon resource must have been previously loaded by using the LoadImage function.
cxWidth
[in] Specifies the logical width of the icon. This parameter must be zero or the native dimensions of the icon.
cyWidth
[in] Specifies the logical height of the icon. This parameter must be zero or the native dimensions of the icon.
istepIfAniCur
[in] Animated icons are not supported; set to zero.
hbrFlickerFreeDraw
[in] Specifies that the system draws the icon directly into the device context; set to NULL.
diFlags
[in] Specifies the following drawing flag:
Value
Description
DI_NORMAL Draws the icon using the image and the mask.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DrawIconEx function places the icon’s upper-left corner at the location specified by the xLeft and yTop parameters. The location is subject to the current mapping mode of the device context.

Windows CE does not support the following:

  • Stretching and compressing; that is, the icon resolution is fixed for a specified HICON, and no icon resizing is supported.
  • Mapping modes.
  • Using DrawIconEx to draw cursors.
  • Animated cursors.

See Also

LoadImage


DrawMenuBar

This function redraws the menu bar part of the command bar the specified window’s command bar. If the menu bar changes after Windows CE has created the window, this function must be called to draw the changed menu bar.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL DrawMenuBar( HWND hWnd);

Parameters

hWnd
[in] Handle to the window whose menu bar needs redrawing.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

CreateMenu, DeleteMenu, RemoveMenu, CommandBar_DrawMenuBar


DrawStatusText

This function draws the specified text in the style of a status window with borders.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

void DrawStatusText(HDC hdc, LPRECT lprc, LPCWSTR pszText, UINT uFlags);

Parameters

hdc
Handle to the display context for the window.
lprc
Long pointer to a RECT structure that contains the position, in client coordinates, of the rectangle in which the text is drawn. The function draws the borders just inside the edges of the specified rectangle.
pszText
Pointer to a null-terminated string that specifies the text to display. Tab characters in the string determine whether the string is left-aligned, right-aligned, or centered.
uFlags
Text drawing flags. This parameter can be a combination of these values:
Value
Description
SBT_NOBORDERS | Prevents borders from being drawn around the specified text.
SBT_POPOUT | Draws highlighted borders that make the text stand out.
SBT_RTLREADING | Displays text using right-to-left reading order on Hebrew or Arabic systems.

Return Values

None.

See Also

RECT


DrawText

This function draws formatted text in the specified rectangle. It formats the text according to the specified format method.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int DrawText(HDC hDC, LPCTSTR lpString, int nCount, LPRECT lpRect, UNIT uFormat);

Parameters

hDC
[in] Handle to the device context.
lpString
[in] Long pointer to the string to be drawn. If the nCount parameter is –1, the string must be null-terminated.

If uFormat includes DT_MODIFYSTRING, the function could add up to four additional characters to this string. The buffer containing the string should be large enough to accommodate these extra characters.

nCount
[in] Specifies the number of characters in the string. If nCount is –1, then the lpString parameter is assumed to be a pointer to a null-terminated string and DrawText computes the character count automatically.
lpRect
[in] Long pointer to a RECT structure that contains the rectangle (in logical coordinates) in which the text is to be formatted.
uFormat
[in] Specifies the method of formatting the text. It can be any combination of the following values:
Value
Description
DT_BOTTOM | Justifies the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE.
DT_CALCRECT | Determines the width and height of the rectangle. If there are multiple lines of text, DrawText uses the width of the rectangle pointed to by the lpRect parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text.
Before calling DrawText, an application must set the right and bottom members of the RECT structure pointed to by lpRect. These members are updated with the call to DrawText.
DT_CENTER | Centers text horizontally in the rectangle.
DT_EDITCONTROL | Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the function does not display a partially visible last line.
DT_END_ELLIPSIS or DT_PATH_ELLIPSIS | Replaces part of the given string with ellipses, if necessary, so that the result fits in the specified rectangle. The given string is not modified unless the DT_MODIFYSTRING flag is specified.
You can specify DT_END_ELLIPSIS to replace characters at the end of the string, or DT_PATH_ELLIPSIS to replace characters in the middle of the string. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash.
DT_EXPANDTABS | Expands tab characters. The default number of characters per tab is eight. The DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS, and DT_END_ELLIPSIS values cannot be used with the DT_EXPANDTABS value.
DT_INTERNAL | Uses the system font to calculate text metrics.
DT_LEFT | Aligns text to the left.
DT_MODIFYSTRING | Modifies the given string to match the displayed text. This flag has no effect unless the DT_END_ELLIPSIS or DT_PATH_ELLIPSIS flag is specified.
DT_NOCLIP | Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.
DT_NOPREFIX | Turns off processing of prefix characters. Normally, DrawText interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off.
DT_RIGHT | Aligns text to the right.
DT_RTLREADING | Layout in right to left reading order for bi-directional text when the font selected into the hdc is a Hebrew or Arabic font. The default reading order for all text is left to right.
DT_SINGLELINE | Displays text on a single line only. Carriage returns and linefeeds do not break the line.
DT_TABSTOP | Sets tab stops. Bits 15–8 (high-order byte of the low-order word) of the uFormat parameter specify the number of characters for each tab. The default number of characters per tab is eight. The DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be used with the DT_TABSTOP value.
DT_TOP | Top-justifies text (single line only).
DT_VCENTER | Centers text vertically (requires DT_SINGLELINE flag).
DT_WORDBREAK | Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-linefeed sequence also breaks the line.
DT_WORD_ELLIPSIS | Truncates text that does not fit in the rectangle and adds ellipses.

Return Values

The height of the text indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DrawText function uses the device context’s selected font, text color, and background color to draw the text. Unless the DT_NOCLIP format is used, DrawText clips the text so that it does not appear outside the specified rectangle. All formatting is assumed to have multiple lines unless the DT_SINGLELINE format is specified.

If the selected font is too large for the specified rectangle, the DrawText function does not attempt to substitute a smaller font.

For Windows CE versions 2.10 and later, line breaking is supported for the Chinese, Korean, and Japanese languages.

See Also

ExtTextOut, RECT


Ellipse to ExtTextOut


Ellipse

This function draws an ellipse. The center of the ellipse is the center of the specified bounding rectangle. The ellipse is outlined by the currently selected pen and filled by the currently selected brush.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL Ellipse(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

hdc
[in] Handle to the device context.
nLeftRect
[in] Specifies the x-coordinate of the upper-left corner of the bounding rectangle.
nTopRect
[in] Specifies the y-coordinate of the upper-left corner of the bounding rectangle.
nRightRect
[in] Specifies the x-coordinate of the lower-right corner of the bounding rectangle.
nBottomRect
[in] Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The current position is neither used nor updated by Ellipse.


EmptyClipboard

This function empties the clipboard and frees handles to data in the clipboard. The function then assigns ownership of the clipboard to the window that currently has the clipboard open.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EmptyClipboard(void);

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Before calling EmptyClipboard, an application must open the clipboard by using the OpenClipboard function. If the application specifies a NULL window handle when opening the clipboard, EmptyClipboard succeeds but sets the clipboard owner to NULL.

See Also

OpenClipboard, SetClipboardData, WM_DESTROYCLIPBOARD


EnableEUDC

This function enables or disables end-user-defined characters (EUDC).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.01 and later (Japanese version 1.0 and later)

Syntax

BOOL EnableEUDC(BOOL fEnableEUDC);

Parameters

fEnableEUDC
[in] Boolean that is set to TRUE to enable EUDC, and to FALSE to disable EUDC.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Enabling EUDC allows text output functions to retrieve information about end-user-defined characters from EUDC fonts. Disabling EUDC prevents output functions from accessing these fonts. By default, Windows CE enables EUDC fonts during GWES initialization.

For Windows CE versions 2.01 and later, this function is supported in TrueType font and no longer supported in raster font.


EnableHardwareKeyboard

This function enables or disables the keyboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL EnableHardwareKeyboard ( BOOL bEnable );

Parameters

bEnable
[in] Boolean value that specifies whether to enable or disable the keyboard. Set it to TRUE to enable the keyboard or FALSE to disable it.

Return Values

This function always returns TRUE.

Remarks

The EnableHardwareKeyboard function is useful for applications in which a user can write on the touch screen. When the keyboard is disabled, a user can rest a hand on it without causing spurious keyboard input. Use the disable mode carefully. If an application hangs while the keyboard is disabled, the keyboard is not available to other applications.

When EnableHardwareKeyboard changes the enabled state of the keyboard, it causes menus, tabs, buttons and static controls to repaint themselves, so they can change the way they display keyboard accelerators or other relevant information.

See Also

GetKeyboardStatus


EnableMenuItem

This function enables or disables (grays) the specified menu item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnableMenuItem(HMENU hMenu, UINT uIDEnableItem,
UINT uEnable);

Parameters

hMenu
[in] Handle to the menu.
uIDEnableItem
[in] Specifies the menu item to be enabled, disabled, or grayed, as determined by the uEnable parameter. This parameter specifies an item in a menu bar, menu, or submenu.
uEnable
[in] Specifies flags that control the interpretation of the uIDEnableItem parameter and indicate whether the menu item is enabled, disabled, or grayed. This parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_ENABLED, MF_DISABLED, or MF_GRAYED.
Value
Description
MF_BYCOMMAND | Indicates that uIDEnableItem gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION | Indicates that uIDEnableItem gives the zero-based relative position of the menu item.
MF_ENABLED | Indicates that the menu item is enabled and restored from a grayed state so that it can be selected.
MF_GRAYED | Indicates that the menu item is disabled and grayed so that it cannot be selected.

Return Values

The return value specifies the previous state of the menu item (it is either MF_ENABLED or MF_GRAYED). 0xFFFFFFFF indicates that the menu item does not exist.

Remarks

An application must use the MF_BYPOSITION flag to specify the correct menu handle. If the menu handle to the menu bar is specified, the top-level menu item (an item in the menu bar) is affected. To set the state of an item in a drop-down menu or submenu by position, an application must specify the handle to the drop-down menu or submenu.

When an application specifies the MF_BYCOMMAND flag, the system checks all items that open submenus in the menu identified by the specified menu handle. Therefore, unless duplicate menu items are present, specifying the menu handle to the menu bar is sufficient.

The InsertMenu, InsertMenuItem, LoadMenuIndirect, ModifyMenu, and SetMenuItemInfo functions can also set the state (enabled or grayed) of a menu item.

Menu items cannot be disabled without being grayed. To disable a menu item, use the MF_GRAYED flag.

See Also

CreateMenu, InsertMenu


EnableWindow

This function enables or disables mouse and keyboard input to the specified window or control. When input is disabled, the window does not receive input such as mouse clicks and key presses. When input is enabled, the window receives all input.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnableWindow( HWND hWnd, BOOL bEnable);

Parameters

hWnd
Handle to the window to be enabled or disabled.
bEnable
Boolean that specifies whether to enable or disable the window. If this parameter is TRUE, the window is enabled. If the parameter is FALSE, the window is disabled.

Return Values

Nonzero indicates that the window was previously disabled. Zero indicates that the window was not previously disabled. To get extended error information, call GetLastError.

Remarks

If the enabled state of a window is changing, a WM_ENABLE message is sent before the EnableWindow function returns. If a window is already disabled, all its child windows are implicitly disabled, although they are not sent a WM_ENABLE message.

A window must be enabled before it can be activated. For example, if an application is displaying a modeless dialog box and has disabled its main window, the application must enable the main window before destroying the dialog box. Otherwise, another window will receive the keyboard focus and be activated. If a child window is disabled, it is ignored when the system tries to determine which window should receive mouse messages.

By default, a window is enabled when it is created. To create a window that is initially disabled, an application can specify the WS_DISABLED style in the CreateWindow or CreateWindowEx function. After a window has been created, an application can use EnableWindow to enable or disable the window.

An application can use this function to enable or disable a control in a dialog box. A disabled control cannot receive the keyboard focus, nor can a user gain access to it.

See Also

CreateWindow, CreateWindowEx, IsWindowEnabled, WM_ENABLE


EndDeferWindowPos

This function simultaneously updates the position and size of one or more windows in a single screen-refreshing cycle.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

BOOL EndDeferWindowPos( HDWP hWinPosInfo);

Parameters

hWinPosInfo
Handle to a multiple-window – position structure that contains size and position information for one or more windows. This internal structure is returned by the BeginDeferWindowPos function or by the most recent call to the DeferWindowPos function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

This function does not cause a WM_WINDOWPOSCHANGING message to be sent.

Remarks

The EndDeferWindowPos function sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to each window identified in the internal structure.

See Also

DeferWindowPos, BeginDeferWindowPos


EndDialog

This function destroys a modal dialog box, causing the system to end any processing for the dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EndDialog( HWND hDlg, int nResult );

Parameters

hDlg
[in] Handle to the dialog box to be destroyed.
nResult
[in] Specifies the value to be returned to the application from the function that created the dialog box.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Dialog boxes created by the DialogBox, DialogBoxParam, DialogBoxIndirect, and DialogBoxIndirectParam functions must be destroyed using the EndDialog function. An application calls EndDialog from within the dialog box procedure; the function must not be used for any other purpose.

A dialog box procedure can call EndDialog at any time, even during the processing of the WM_INITDIALOG message. If your application calls the function while WM_INITDIALOG is being processed, the dialog box is destroyed before it is shown and before the input focus is set.

EndDialog does not destroy the dialog box immediately. Instead, it sets a flag and allows the dialog box procedure to return control to the system. The system checks the flag before attempting to retrieve the next message from the application queue. If the flag is set, the system ends the message loop, destroys the dialog box, and uses the value in nResult as the return value from the function that created the dialog box.

See Also

DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, WM_INITDIALOG


EndDoc

This function ends a print job.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int EndDoc( HDC hdc);

Parameters

hdc
[in] Handle to the device context (DC) for the print job.

Return Values

A value greater than zero indicates success. A value less than or equal to zero indicates failure. To get extended error information, call GetLastError.

Remarks

Applications should call EndDoc immediately after finishing a print job.

See Also

EndPage, StartDoc


EndPage

This function informs the device that the application has finished writing to a page. This function is typically used to direct the device driver to advance to a new page.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int EndPage( HDC hdc);

Parameters

hdc
[in] Handle to the device context (DC) for the print job.

Return Values

A value greater than zero indicates success. A value less than or equal to zero indicates failure. To get extended error information, call GetLastError.

Remarks

For Windows CE versions 1.0 through 2.01, the device context attributes are not retained between a call to EndPage and a call StartPage. You must reselect objects and set up the mapping mode again before printing the next page.

For Windows CE versions 2.10 and later, neither EndPage or StartPage resets the device context attributes. Device context attributes remain constant across subsequent pages. You do not need to reselect objects and set up the mapping mode again before printing the next page; however, doing so produces identical printer output and is compatible with earlier versions of Windows CE.

See Also

EndDoc, StartPage


EndPaint

This function marks the end of painting in the specified window. This function is required for each call to the BeginPaint function, but only after painting is complete.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EndPaint( HWND hWnd, CONST PAINTSTRUCT *lpPaint );

Parameters

hWnd
Handle to the window that has been repainted.
lpPaint
Long pointer to a PAINTSTRUCT structure that contains the painting information retrieved by BeginPaint.

Return Values

The return value is always nonzero.

Remarks

If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen.

See Also

BeginPaint, PAINTSTRUCT


EnumClipboardFormats

This function lets you enumerate the data formats that are currently available on the clipboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT EnumClipboardFormats(UINT format);

Parameters

format
[in] Unsigned integer that specifies a clipboard format that is known to be available.

To start an enumeration of clipboard formats, set format to zero. When format is zero, the function retrieves the first available clipboard format. For subsequent calls during an enumeration, set format to the result of the previous EnumClipboardFormat call.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. If the clipboard is not open, the function fails.

If there are no more clipboard formats to enumerate, the return value is zero. In this case, the GetLastError function returns the value NO_ERROR. This lets you distinguish between function failure and the end of enumeration.

Remarks

You must open the clipboard before enumerating its formats. Use the OpenClipboard function to open the clipboard. The EnumClipboardFormats function fails if the clipboard is not open.

The EnumClipboardFormats function enumerates formats in the order that they were placed on the clipboard. If you are copying information to the clipboard, add clipboard objects in order from the most descriptive clipboard format to the least descriptive clipboard format. If you are pasting information from the clipboard, retrieve the first clipboard format that you can handle. That will be the most descriptive clipboard format that you can handle.

The system provides automatic type conversions for certain clipboard formats. In the case of such a format, this function enumerates the specified format, then enumerates the formats to which it can be converted.

See Also

CountClipboardFormats, GetClipboardData, OpenClipboard, RegisterClipboardFormat, SetClipboardData


EnumFontFamilies

This function enumerates the fonts in a specified font family that are available on a specified device. This function supersedes the EnumFonts function.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 or later

Syntax

int EnumFontFamilies(HDC hdc, LPCTSTR lpszFamily,
FONTENUMPROC lpEnumFontFamProc, LPARAM lParam);

Parameters

hdc
[in] Handle to the device context (DC).
lpszFamily
[in] Long pointer to a null-terminated string that specifies the family name of the desired fonts. If lpszFamily is NULL, EnumFontFamilies randomly selects and enumerates one font of each available type family.
lpEnumFontFamProc
[in] Long pointer to the procedure-instance address of the application-defined callback function. For information about the callback function, see EnumFontFamProc.
lParam
[in] Pointer to application-supplied data. The data is passed to the callback function along with the font information.

Return Values

The return value is the last value returned by the callback function. Its meaning is defined by the application.

Remarks

For each font having the typeface name specified by the lpszFamily parameter, the EnumFontFamilies function retrieves information about that font and passes it to the function pointed to by the lpEnumFontFamProc parameter. The application-defined callback function can process the font information as desired. Enumeration continues until there are no more fonts or the callback function returns zero.

Windows CE versions 2.0 and later support systems that use either TrueType or raster fonts but not both. The font type (raster or TrueType) is chosen at system design time, and cannot be changed by an application.

Windows CE versions 1.0 and 1.01 support only raster fonts.

See Also

EnumFontFamProc, EnumFonts


EnumFonts

This function enumerates the fonts available on a specified device. This function is provided for compatibility with earlier versions of the Microsoft Platform SDK. Whenever possible, applications should use the EnumFontFamilies function.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 or later

Syntax

int EnumFonts(HDC hdc, LPCTSTR lpFaceName,
FONTENUMPROC lpFontFunc, LPARAM lParam);

Parameters

hdc
[in] Handle to the device context (DC).
lpFaceName
[in] Long pointer to a null-terminated string that specifies the typeface name of the desired fonts. If lpFaceName is NULL, EnumFonts randomly selects and enumerates one font of each available typeface.
lpFontFunc
[in] Long pointer to the application-defined callback function. For more information, see EnumFontsProc.
lParam
[in] Pointer to any application-defined data. The data is passed to the callback function along with the font information.

Return Values

The return value is the last value returned by the callback function. Its meaning is defined by the application.

Remarks

Use EnumFontFamiliesEx instead of EnumFonts. The EnumFontFamiliesEx function differs from the EnumFonts function in that it retrieves the style names associated with a TrueType font. With EnumFontFamiliesEx, you can retrieve information about font styles that cannot be enumerated using the EnumFonts function.

Windows CE versions 2.0 and later support systems that use either TrueType or raster fonts but not both. The font type (raster or TrueType) is chosen at system design time, and cannot be changed by an application.

Windows CE versions 1.0 and 1.01 support only raster fonts.

See Also

EnumFontFamilies, EnumFontsProc, GetDeviceCaps


EnumRegisterWordProc

This function is an application-defined callback function used with the ImmEnumRegisterWord function. It is used to process data of register strings. The REGISTERWORDENUMPROC type defines a pointer to this callback function. EnumRegisterWordProc is a placeholder for the application-defined function name.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

UINT CALLBACK EnumRegisterWordProc(LPCTSTR lpszReading,
DWORD dwStyle, LPCTSTR lpszString, LPVOID lpData );

Parameters

lpszReading
[in] Long pointer to a null-terminated string specifying the matched reading string.
dwStyle
[in] Specifies the style of register string.
lpszString
[in] Long pointer to a null-terminated string specifying the matched register string.
lpData
[in] Long pointer to application-supplied data.

Return Values

Nonzero continues enumeration. Zero stops enumeration.

Remarks

An application must register this function by passing its address to the ImmEnumRegisterWord function.


EnumWindows

This function enumerates all top-level windows on the screen by passing the handle to each window, in turn, to an application-defined callback function. EnumWindows continues until the last top-level window is enumerated or the callback function returns FALSE.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnumWindows( WNDENUMPROC lpEnumFunc, LPARAM lParam );

Parameters

lpEnumFunc
Long pointer to an application-defined callback function. For more information, see EnumWindowsProc.
lParam
Specifies an application-defined value to be passed to the callback function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The EnumWindows function does not enumerate child windows.

This function is more reliable than calling the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that has been destroyed.

See Also

EnumWindowsProc, GetWindow


EqualRgn

This function checks the two specified regions to determine whether they are identical. The function considers two regions identical if they are equal in size and shape.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EqualRgn(HRGN hSrcRgn1, HRGN hSrcRgn2);

Parameters

hSrcRgn1
[in] Handle to a region.
hSrcRgn2
[in] Handle to a region.

Return Values

Nonzero indicates that the two regions are equal. Zero indicates that the two regions are not equal. ERROR indicates that at least one of the region handles is invalid.

See Also

CreateRectRgnIndirect


ExcludeClipRect

This function creates a new clipping region that consists of the existing clipping region minus the specified rectangle.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int ExcludeClipRect(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

hdc
[in] Handle to the device context.
nLeftRect
[in] Specifies the logical x-coordinate of the upper-left corner of the rectangle.
nTopRect
[in] Specifies the logical y-coordinate of the upper-left corner of the rectangle.
nRightRect
[in] Specifies the logical x-coordinate of the lower-right corner of the rectangle.
nBottomRect
[in] Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Values

The return value specifies the new clipping region’s complexity. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than one rectangle. ERROR indicates that no region was created.

Remarks

The lower and right edges of the specified rectangle are not excluded from the clipping region.

See Also

IntersectClipRect


ExtEscape

This function allows applications to access capabilities of a particular device that are not available through the graphics display interface (GDI). The device capabilities that this function accesses must be implemented by an OEM.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.10 and later

Syntax

int ExtEscape( HDC hdc, int nEscape, int cbInput, LPCSTR lpszInData,
in cbOutput, LPSTR lpszOutData );

Parameters

hdc
[in] Handle to the device context.
nEscape
[in] Specifies the escape function to be performed.
cbInput
[in] Specifies the number of bytes of data pointed to by the lpszInData parameter.
lpszInData
[in] Long pointer to the input structure required for the specified escape.
cbOutput
[in] Specifies the number of bytes of data pointed to by the lpszOutData parameter.
lpszOutData
[out] Long pointer to the structure that receives output from this escape. This parameter must not be NULL if ExtEscape is called as a query function. If no data is to be returned in this structure, set cbOutput to 0.

Return Values

A value greater than zero indicates success. A value less than zero indicates an error. The QUERYESCSUPPORT printer escape, which checks for implementation only, returns zero when the escape is not implemented.

To get extended error information, call GetLastError.

Remarks

Use this function to pass a driver-defined escape value to a device.

The escape values passed in to this function are driver-defined. Windows CE does not support any system-defined escape values.

When using QUERYESCSUPPORT to find out whether a device supports an escape value, set the nEscape parameter to QUERYESCSUPPORT and point to the escape value in question with the lpszInData parameter.

See Also

GetDeviceCaps


ExtractIconEx

This function retrieves the handle from the specified executable file or dynamic-link library (DLL).

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

HICON ExtractIconEx(LPCTSTR lpszFile, int nIconIndex, HICON FAR *phiconLarge, HICON FAR *phiconSmall, UINT nIcons);

Parameters

lpszFile
[in] Long pointer to a null-terminated string that specifies the name of an executable file, DLL, or icon file from which icons will be extracted.
nIconIndex
[in] Specifies the zero-based index of the first icon to extract. For example, if this value is zero, the function extracts the first icon in the specified file.

For Windows CE versions 2.10 and later, the nIconIndex parameter must be zero or –N, where N is a specified resource identifier. The nIcons parameter must be 1.

For Windows CE versions 1.0 through 2.01, the function returns the total number of icons in the specified file if nIconIndex is –1 and phIconLarge and phiconSmall are both NULL. If the file is an executable file or DLL, the return value is the number of RT_GROUP_ICON resources. If the file is an .ICO file, the return value is 1.

phiconLarge
[out] Pointer to an array of icon handles which receives handles to the large icons extracted from the file. If this parameter is NULL, no large icons are extracted from the file.
phiconSmall
[out] Pointer to an array of icon handles which receives handles to the small icons extracted from the file. If this parameter is NULL, no small icons are extracted from the file.
nIcons
[in] Specifies the number of icons to extract from the file.

Return Values

For Windows CE versions 2.10 and later, this function returns the handle to an icon. If both phiconLarge and phiconSmall are not NULL, the return value defaults to the large icon.

For Windows CE versions 1.0 through 2.01, this function returns a UINT data type. If the nIconIndex parameter is –1, the phiconLarge parameter is NULL, and the phiconSmall parameter is NULL, then the return value is the number of icons contained in the specified file. Otherwise, the return value is the number of icons successfully extracted from the file.

Remarks

You must destroy all icons extracted by ExtractIconEx by calling the DestroyIcon function.

To retrieve the dimensions of the large and small icons, use the GetSystemMetrics function with the SM_CXICON, SM_CYICON, SM_CXSMICON, and SM_CYSMICON flags.


ExtTextOut

This function draws a character string by using the currently selected font. An optional rectangle may be provided, to be used for clipping, opaquing, or both.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ExtTextOut(HDC hdc, int X, int Y, UINT fuOptions, const RECT *lprc, LPCTSTR lpString, UINT cbCount, const int *lpDx);

Parameters

hdc
[in] Handle to the device context (DC).
X
[in] Specifies the logical x-coordinate of the reference point used to position the string.
Y
[in] Specifies the logical y-coordinate of the reference point used to position the string.
fuOptions
[in] Specifies how to use the application-defined rectangle. This parameter can be a combination of the following values:
Value
Description
ETO_CLIPPED | The text will be clipped to the rectangle.
ETO_OPAQUE | The current background color should be used to fill the rectangle.

lprc
[in] Long pointer to an optional RECT structure that specifies the dimensions of a rectangle that is used for clipping, opaquing, or both.
lpString
[in] Long pointer to the character string to be drawn. The string does not need to be zero-terminated, since cbCount specifies the length of the string.
cbCount
[in] Specifies the number of characters in the string.
lpDx
[in] Long pointer to an optional array of values that indicate the distance between origins of adjacent character cells. For example, lpDx[i] logical units separate the origins of character cell i and character cell i + 1.

Return Values

Nonzero indicates that the string is drawn. Zero indicates failureTo get extended error information, call GetLastError.

Remarks

The current text-alignment settings for the specified DC determine how the reference point is used to position the text.

If the lpDx parameter is NULL, the ExtTextOut function uses the default spacing between characters. The character-cell origins and the contents of the array pointed to by the lpDx parameter are given in logical units. A character-cell origin is defined as the upper-left corner of the character cell.

By default, the current position is not used or updated by this function. However, an application can call the SetTextAlign function with the fMode parameter set to TA_UPDATECP to permit the system to use and update the current position each time the application calls ExtTextOut for a specified DC. When this flag is set, the system ignores the X and Y parameters on subsequent ExtTextOut calls.

See Also

RECT


FillRect to GetWindowThreadProcessId


FillRect

This function fills a rectangle using the specified brush. This function fills the rectangle’s left and top borders, but excludes the right and bottom borders.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int FillRect(HDC hDC, CONST RECT *lprc, HBRUSH hbr);

Parameters

hDC
[in] Handle to the device context.
lprc
[in] Long pointer to a RECT structure that contains the logical coordinates of the rectangle to be filled.
hbr
[in] Handle to the brush used to fill the rectangle. In Windows CE versions 1.0 and 1.01, the hbr parameter cannot be a color brush.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The brush identified by the hbr parameter may be either a handle to a logical brush or a color value. If specifying a handle to a logical brush, call one of the following functions to obtain the handle: CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush. Additionally, you may retrieve a handle to one of the stock brushes by using the GetStockObject function. If specifying a color value for the hbr parameter, it must be one of the standard system colors (the value 1 must be added to the chosen color). For example:

FillRect(hdc, &rect, (HBRUSH) (COLOR_ENDCOLORS+1));

For a list of all the standard system colors, see GetSysColor.

When filling the specified rectangle, FillRect does not include the rectangle’s right and bottom sides. GDI fills a rectangle up to, but not including, the right column and bottom row, regardless of the current mapping mode.

See Also

CreateSolidBrush, GetStockObject, RECT


FillRgn

This function fills a region using the specified brush.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL FillRgn( HDC hdc, HRGN hrgn, HBRUSH hbr);

Parameters

hdc
[in] Handle to the device context.
hrgn
[in] Handle to the region to be filled. The region’s coordinates are presumed to be in logical units.
hbr
[in] Handle to the brush to be used to fill the region.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

CreateSolidBrush, GetStockObject,


FindWindow

The FindWindow function retrieves the handle to the top-level window whose class name and window name match the specified strings. This function does not search child windows.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND FindWindow( LPCTSTR lpClassName, LPCTSTR lpWindowName);

Parameters

lpClassName
Long pointer to a null-terminated string that specifies the class name or is an atom that identifies the class-name string. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpClassName; the high-order word must be zero.
lpWindowName
Long pointer to a null-terminated string that specifies the window name (the window’s title). If this parameter is NULL, all window names match.

Return Values

A handle to the window that has the specified class name and window name indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If lpClassName is an atom, it must be an atom returned from RegisterClass.

See Also

GetClassName, HIWORD, RegisterClass


GetActiveWindow

This function retrieves the window handle to the active window associated with the thread that calls the function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetActiveWindow(void);

Return Values

The handle to the active window associated with the calling thread's message queue indicates success. NULL indicates failure.


GetAsyncKeyState

This function determines whether a key is up or down at the time the function is called, and whether the key was pressed after a previous call to GetAsyncKeyState.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

SHORT GetAsyncKeyState( int vKey );

Parameters

vKey
[in] Specifies one of 256 possible virtual-key codes. For more information, see Virtual-Key Codes.

You can use left- and right-distinguishing constants to specify certain keys. For more information about constants, see Remarks.

Return Values

If the function succeeds, the return value specifies whether the key was pressed since the last call to GetAsyncKeyState, and whether the key is currently up or down. If the most significant bit is set, the key is down. The least significant bit is not valid in Windows CE, and should be ignored. GetAsyncKeyState returns the current key state even if a window in another thread or process currently has the keyboard focus.

Remarks

You can use the VK_LBUTTON virtual-key code constant to determine whether the stylus tip is touching the screen or not.

The GetAsyncKeyState function works with mouse buttons. However, it checks on the state of the physical mouse buttons, not on the logical mouse buttons that the physical buttons are mapped to. For example, the call GetAsyncKeyState(VK_LBUTTON) always returns the state of the left physical mouse button, regardless of whether it is mapped to the left or right logical mouse button. You can determine the system’s current mapping of physical mouse buttons to logical mouse buttons by calling

GetSystemMetrics(SM_SWAPBUTTON)

which returns TRUE if the mouse buttons have been swapped.

You can use the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the vKey parameter. This gives the state of the SHIFT, CTRL, or ALT keys without distinguishing between left and right.

You can use the following virtual-key code constants as values for vKey to distinguish between the left and right instances of those keys.

Code
Description
VK_LSHIFT | VK_RSHIFT
VK_LCONTROL | VK_RCONTROL
VK_LMENU | VK_RMENU

These left- and right-distinguishing constants are only available when you call the GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetKeyState, MapVirtualKey


GetBkColor

This function returns the current background color for the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF GetBkColor(HDC hdc);

Parameters

hdc
[in] Handle to the device context whose background color is to be returned.

Return Values

A COLORREF value for the current background color indicates success. CLR_INVALID indicates failure.

See Also

GetBkMode, SetBkColor


GetBkMode

This function returns the current background mix mode for a specified device context. The background mix mode of a device context affects text and dashed pens.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int GetBkMode(HDC hdc);

Parameters

hdc
[in] Handle to the device context whose background mode is to be returned.

Return Values

Either OPAQUE or TRANSPARENT, which specifies the current background mix mode, indicates success. Zero indicates failure.

Remarks

The background mix mode value is stored internally as a single byte.

See Also

GetBkColor, SetBkMode


GetCapture

This function retrieves the handle to the window (if any) that has captured the mouse or stylus input. Only one window at a time can capture the mouse or stylus input.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetCapture(void);

Return Values

The handle of the capture window associated with the current thread indicates success. NULL indicates that no window in the thread has captured the mouse.

Remarks

A NULL return value does not mean no other thread or process in the system has captured the mouse; it just means the current thread has not captured the mouse.

See Also

ReleaseCapture, SetCapture


GetCaretBlinkTime

This function returns the elapsed time, in milliseconds, required to invert the caret’s pixels.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT GetCaretBlinkTime(void);

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

SetCaretBlinkTime


GetCaretPos

This function copies the caret’s position, in client coordinates, to the specified POINT structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCaretPos(LPPOINT lpPoint);

Parameters

lpPoint
[out] Long pointer to the POINT structure that is to receive the client coordinates of the caret.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The caret position is always given in the client coordinates of the window that contains the caret.

See Also

SetCaretPos, POINT


GetClassInfo

This function retrieves information about a window class.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetClassInfo( HINSTANCE hInstance, LPCTSTR lpClassName, LPWNDCLASS lpWndClass );

Parameters

hInstance
Handle to the instance of the application that created the class. To retrieve information about classes defined by the system (such as buttons or list boxes), set this parameter to NULL.
lpClassName
Long pointer to a null-terminated string that contains the class name. The name must be that of a preregistered class or a class registered by a previous call to the RegisterClass function. Alternatively, this parameter can be an integer atom. If so, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.
lpWndClass
Long pointer to a WNDCLASS structure that receives the information about the class.

Return Values

Nonzero indicates that the function finds a matching class and successfully copies the data. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If lpClassName is an atom, it must be an atom returned from RegisterClass.

See Also

GetClassLong, GetClassName, RegisterClass, WNDCLASS


GetClassLong

This function retrieves the specified 32-bit (long) value from the WNDCLASS structure associated with the specified window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetClassLong( HWND hWnd, int nIndex);

Parameters

hWnd
Handle to the window and, indirectly, the class to which the window belongs.
nIndex
Specifies the 32-bit value to retrieve. To retrieve a 32-bit value from the extra class memory, specify the positive, zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would be an index to the third 32-bit integer. To retrieve any other value from the WNDCLASS structure, specify one of the following values:
Value
Description
GCW_ATOM | Retrieves an ATOM value that uniquely identifies the window class. This is the same atom that the RegisterClass function returns.
GCL_CBCLSEXTRA | Retrieves the size, in bytes, of the extra memory associated with the class.
GCL_CBWNDEXTRA | Retrieves the size, in bytes, of the extra window memory associated with each window in the class. For information on how to access this memory, see GetWindowLong.
GCL_HBRBACKGROUND | Retrieves a handle to the background brush associated with the class.
GCL_HCURSOR | Retrieves a handle to the cursor associated with the class.
GCL_HICON | Retrieves a handle to the icon associated with the class.
GCL_HICONSM | Retrieves a handle to the small icon associated with the class.
GCL_HMODULE | Retrieves a handle to the module that registered the class.
GCL_MENUNAME | Retrieves the address of the menu name string. The string identifies the menu resource associated with the class.
GCL_STYLE | Retrieves the window-class style bits.
GCL_WNDPROC | Retrieves the address of the window procedure associated with the class.

Return Values

The requested 32-bit value indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The nIndex parameter is a byte offset but must be a multiple of 4 bytes. Windows CE does not support unaligned access.

The only values supported for the nIndex parameter are GCL_HICON and GCL_STYLE.

If you are using the Windows CE Iconcurs component, which supports mouse cursors on appropriate target platforms, you can also use the GCL_HCURSOR value in the nIndex parameter.

Windows CE versions that support mouse cursors include the Iconcurs and Mcursor components rather than the Icon and Cursor components.

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

GetWindowLong, RegisterClass, SetClassLong, WNDCLASS


GetClassName

This function retrieves the name of the class to which the specified window belongs. The RAPI version is CeGetClassName for versions 2.0 and later.

At a Glance

Header file: | Winuser.h Rapi.h
Windows CE versions: | 1.0 and later

Syntax

int GetClassName( HWND hWnd, LPTSTR lpClassName, int nMaxCount);

Parameters

hWnd
Handle to the window and, indirectly, the class to which the window belongs.
lpClassName
Long pointer to the buffer that is to receive the class name string.
nMaxCount
Specifies the length, in characters, of the buffer pointed to by the lpClassName parameter. The class name string is truncated if it is longer than the buffer.

Return Values

The number of characters copied to the specified buffer indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetClassName function.

See Also

FindWindow, GetClassInfo, GetClassLong


GetClientRect

This function retrieves the coordinates of a window’s client area.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetClientRect( HWND hWnd, LPRECT lpRect);

Parameters

hWnd
Handle to the window whose client coordinates are to be retrieved.
lpRect
Long pointer to a RECT structure that receives the client coordinates. The left and top members are zero. The right and bottom members contain the width and height of the window.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Command bars are included in the client area.

See Also

GetWindowRect, RECT


GetClipboardData

This function retrieves data from the clipboard in a specified format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE GetClipboardData(UINT uFormat);

Parameters

uFormat
[in] Unsigned integer that specifies a clipboard format.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE does not support automatic data format conversions between clipboard formats.

An application can enumerate the available formats in advance by using the EnumClipboardFormats function.

The clipboard controls the handle that the GetClipboardData function returns, not the application. The application should copy the data immediately. The application cannot rely on being able to make long-term use of the handle. The application must not free the handle nor leave it locked.

The system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand.

See Also

EnumClipboardFormats, SetClipboardData, GetClipboardDataAlloc


GetClipboardDataAlloc

This function retrieves data from the clipboard in the specified format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE GetClipboardDataAlloc(UINT uFormat);

Parameters

uFormat
[in] Unsigned integer that specifies the clipboard format of the data being retreived.

Return Values

The handle to a clipboard object in the specified format indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The GetClipboardDataAlloc function can potentially save an extra memory allocation in cases where the clipboard data is being transferred across processes.

GetClipboardDataAlloc works like the GetClipboardData function except it returns a handle to the memory allocated for the clipboard data in the caller’s process. This memory is owned by the calling process and needs to be freed using LocalFree when no longer in use. GetClipboardDataAlloc should be used if the caller would usually call the GetClipboardData function and then the LocalAlloc function before copying the data.

See Also

GetClipboardData, LocalFree, LocalAlloc


GetClipboardFormatName

This function retrieves from the clipboard the name of the specified registered format. The function copies the name to the specified buffer.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int GetClipboardFormatName(UINT format, LPTSTR lpszFormatName,
int cchMaxCount);

Parameters

format
[in] Unsigned integer that specifies the type of format to be retrieved. This parameter must not specify any of the predefined clipboard formats.
lpszFormatName
[out] Long pointer to the buffer that is to receive the format name.
cchMaxCount
[in] Unsigned integer that specifies the maximum length, in characters, of the string to be copied to the buffer. If the name exceeds this limit, it is truncated.

Return Values

The length, in characters, of the string copied to the buffer indicates success. Zero indicates that the requested format does not exist or is predefined, and that the function failed. To get extended error information, call GetLastError.

Remarks

When an application registers a clipboard format name with a call to the RegisterClipboardFormat function, the system assigns an unsigned integer to the clipboard format.

To obtain the available clipboard formats for clipboard data, an application calls the EnumClipboardFormat function. This function enumerates the clipboard formats using their associated integers. An application calls GetClipboardFormatName to retrieve the name of a registered clipboard format and display it to a user.

See Also

EnumClipboardFormats, RegisterClipboardFormat


GetClipboardOwner

This function retrieves the window handle to the current owner of the clipboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetClipboardOwner(void);

Return Values

The handle of the window that owns the clipboard indicates success. NULL indicates that the clipboard is not owned. To get extended error information, call GetLastError.

Remarks

The clipboard can still contain data even if the clipboard is not currently owned.

In general, the clipboard owner is the window that last placed data in clipboard. The EmptyClipboard function assigns clipboard ownership.

See Also

EmptyClipboard


GetClipBox

This function retrieves the dimensions of the tightest bounding rectangle that can be drawn around the current visible area on the device. The visible area is defined by the current clipping region as well as any overlapping windows.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int GetClipBox(HDC hdc, LPRECT lprc);

Parameters

hdc
[in] Handle to the device context.
lprc
[out] Long pointer to a RECT structure that is to receive the rectangle dimensions.

Return Values

The return value specifies the clipping box’s complexity. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than one rectangle. ERROR indicates that an error occurred.

To get extended error information, call GetLastError.

Remarks

GetClipBox returns logical coordinates based on the specified device context.

See Also

RECT


GetClipCursor

This function retrieves the screen coordinates of the rectangular area to which the cursor is confined.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetClipCursor( LPRECT lpRect );

Parameters

lpRect
[out] Long pointer to a RECT structure that receives the screen coordinates of the confining rectangle. The structure receives the dimensions of the screen if the cursor is not confined to a rectangle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The cursor is a shared resource. If an application confines the cursor with the ClipCursor function, it must later release the cursor by using ClipCursor before relinquishing control to another application.

The calling process must have WINSTA_READATTRIBUTES access to the window station.

See also

ClipCursor, GetCursorPos, RECT


GetClipRgn

This function retrieves a handle identifying the current application-defined clipping region for the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int GetClipRgn(HDC hdc, HRGN hrgn);

Parameters

hdc
[in] Handle to the device context.
hrgn
[in/out] Handle to an existing region before the function is called. After the function returns, this parameter is a handle to a copy of the current clipping region.

Return Values

If there is no clipping region for the specified device context, zero indicates success. If there is a clipping region for the specified device context, 1 indicates success. –1 indicates that an error occurred.

To get extended error information, call GetLastError.

Remarks

An application-defined clipping region is a clipping region identified by the SelectClipRgn function. It is not a clipping region created when the application calls the BeginPaint function.

If the function succeeds, the hrgn parameter is a handle to a copy of the current clipping region. Subsequent changes to this copy will not affect the current clipping region.

See Also

BeginPaint, SelectClipRgn


GetCurrentObject

This function returns the currently selected object of the specified type.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HGDIOBJ GetCurrentObject(HDC hdc, UINT uObjectType);

Parameters

hdc
[in] Handle to the device context.
uObjectType
[in] Specifies the object type to be queried. It is one of the following values:
Value
Description
OBJ_PEN | Returns the current selected pen.
OBJ_BRUSH | Returns the current selected brush.
OBJ_PAL | Returns the current selected palette. Windows CE versions 1.0 and 1.01 do not support this value.
OBJ_FONT | Returns the current selected font.
OBJ_BITMAP | Returns the current selected bitmap.

Return Values

The handle of the specified object indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

An application can use the GetCurrentObject and GetObject functions to retrieve descriptions of the graphic objects currently selected into the given device context.

See Also

DeleteObject, GetObject, SelectObject


GetCursor

This function retrieves the handle to the current cursor.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HCURSOR GetCursor(VOID)

Return Values

The handle to the current cursor indicates success. NULL indicates that there is no cursor.

Remarks

If GetCursor is called after the CreateCursor function creates a cursor of zero dimensions, GetCursor retrieves that new cursor.

See also

SetCursor


GetCursorPos

This function retrieves the cursor’s position, in screen coordinates.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCursorPos( LPPOINT lpPoint );

Parameters

lpPoint
[out] Long pointer to a POINT structure that receives the screen coordinates of the cursor.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The cursor position is always given in screen coordinates and is not affected by the mapping mode of the window that contains the cursor.

The calling process must have WINSTA_READATTRIBUTES access to the window station.

See also

ClipCursor, POINT, SetCursor, SetCursorPos, ShowCursor


GetDC

This function retrieves a handle to a display device context (DC) for the client area of the specified window. The display device context can be used in subsequent graphics display interface (GDI) functions to draw in the client area of the window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HDC GetDC( HWND hWnd);

Parameters

hWnd
Handle to the window whose device context is to be retrieved. If this value is NULL, GetDC retrieves the device context for the entire screen.

Windows 98, Windows NT 5.0 and later: If this parameter is NULL, GetDC retrieves the device context for the primary display monitor.

Return Values

The handle the device context for the specified window's client area indicates success. NULL indicates failure.

Windows NT: To get extended error information, call GetLastError.

Remarks

The GetDC function retrieves a common, class, or private device context depending on the class style specified for the specified window. For common device contexts, GetDC assigns default attributes to the device context each time it is retrieved. For class and private device contexts, GetDC leaves the previously assigned attributes unchanged.

After painting with a common device context, the ReleaseDC function must be called to release the device context. Class and private device contexts do not have to be released. The number of device contexts is limited only by available memory.

See Also

GetWindowDC, ReleaseDC


GetDCEx

This function retrieves a handle to a display device context (DC) for the client area of a specified window or for the entire screen. You can use the returned handle in subsequent graphics display interface (GDI) functions to draw in the device context.

GetDCEx is an extension to the GetDC function, which gives an application more control over how and whether or not clipping occurs in the client area.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

HDC GetDCEx( HWND hWnd, HRGN hrgnClip, DWORD flags );

Parameters

hWnd
Handle to the window whose device context is to be retrieved. If this value is NULL, GetDCEx retrieves the device context for the entire screen.

Windows 98, Windows NT 5.0 and later: If this parameter is NULL, GetDCEx retrieves the device context for the primary display monitor. hrgnClip

Specifies a clipping region that may be combined with the visible region of the device context.

flags
Specifies how the device context is created. This parameter can be a combination of the following values.
Value
Description
DCX_WINDOW | Returns a device context corresponding to the window rectangle rather than the client rectangle.
DCX_CACHE | Returns a device context from the cache, rather than the OWNDC or CLASSDC window. Essentially overrides CS_OWNDC and CS_CLASSDC.
DCX_PARENTCLIP | Uses the visible region of the parent window. The parent's WS_CLIPCHILDREN and CS_PARENTDC style bits are ignored. The device context origin is set to the upper-left corner of the window identified by hWnd.
DCX_CLIPSIBLINGS | Excludes the visible regions of all sibling windows above the window identified by hWnd.
DCX_CLIPCHILDREN | Excludes the visible regions of all child windows below the window identified by hWnd.
DCX_NORESETATTRS | Does not reset the attributes of this device context to the default attributes when this device context is released.
DCX_LOCKWINDOWUPDATE | Allows drawing even if there is a LockWindowUpdate call in effect that would otherwise exclude this window. Used for drawing during tracking.
DCX_EXCLUDERGN | The clipping region identified by hrgnClip is excluded from the visible region of the returned device context.
DCX_INTERSECTRGN | The clipping region identified by hrgnClip is intersected with the visible region of the returned device context.
DCX_VALIDATE | When specified with DCX_INTERSECTUPDATE, causes the device context to be completely validated. Using this function with both DCX_INTERSECTUPDATE and DCX_VALIDATE is identical to using the BeginPaint function.

Return Values

The handle of the device context for the specified window indicates success. NULL indicates failure. An invalid value for the hWnd parameter causes the function to fail.

Windows NT: To get extended error information, call GetLastError.

Windows CE Remarks

The flags parameter supports the following values: DCX_WINDOW, DCX_CACHE, DCX_CLIPCHILDREN, DCX_CLIPSIBLINGS, DCX_EXCLUDERGN, DCX_INTERSECTRGN, DCX_EXCLUDEUPDATE, and DCX_INTERSECTUPDATE.

Unlike a DC returned by GetDC, a DC returned by this function is not kept in sync with its associated window. If the window moves or is resized, unexpected drawing results may occur. The chance of error is reduced if an application gets a DC, draws, and then releases that DC.

Remarks

Unless the display device context belongs to a window class, the ReleaseDC function must be called to release the device context after painting. Because only five common device contexts are available at any given time, failure to release a device context can prevent other applications from accessing a device context.

The function returns a device context belonging to the window's class if CS_CLASSDC, CS_OWNDC or CS_PARENTDC was specified as a style in the WNDCLASS structure when the class was registered.


GetDeviceCaps

This function retrieves information about the capabilities of a specified device.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int GetDeviceCaps(HDC hdc, int nIndex);

Parameters

hdc
[in] Handle to the device context.
nIndex
[in] Specifies the item to return. This parameter can be one of the following values.
Value
Description
DRIVERVERSION | The device driver version.
TECHNOLOGY | Device technology. It can be any one of the following values.
DT_PLOTTER | Vector plotter
DT_RASDISPLAY | Raster display
DT_RASPRINTER | Raster printer
DT_RASCAMERA | Raster camera
DT_CHARSTREAM | Character stream
DT_DISPFILE | Display file
HORZSIZE | Width, in millimeters, of the physical screen.
VERTSIZE | Height, in millimeters, of the physical screen.
HORZRES | Width, in pixels, of the screen.
VERTRES | Height, in raster lines, of the screen.
LOGPIXELSX | Number of pixels per logical inch along the screen width. In a system with multiple display monitors, this value is the same for all monitors.
LOGPIXELSY | Number of pixels per logical inch along the screen height. In a system with multiple display monitors, this value is the same for all monitors.
BITSPIXEL | Number of adjacent color bits for each pixel.
PLANES | Number of color planes.
NUMBRUSHES | Number of device-specific brushes.
NUMPENS | Number of device-specific pens.
NUMFONTS | Number of device-specific fonts.
NUMCOLORS | Number of entries in the device's color table, if the device has a color depth of no more than 8 bits per pixel. For devices with greater color depths, –1 is returned.
ASPECTX | Relative width of a device pixel used for line drawing.
ASPECTY | Relative height of a device pixel used for line drawing.
ASPECTXY | Diagonal width of the device pixel used for line drawing.
PDEVICESIZE | Reserved.
CLIPCAPS | Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is 0.
SIZEPALETTE | Number of entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with 16-bit Windows.
NUMRESERVED | Number of reserved entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with 16-bit Windows.
COLORRES | Actual color resolution of the device, in bits per pixel. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with 16-bit Windows.
PHYSICALWIDTH | For printing devices: the width of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical width value of 5100 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
Windows CE versions 1.0 and 1.01 do not support this value.
PHYSICALHEIGHT | For printing devices: the height of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical height value of 6600 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
Windows CE versions 1.0 and 1.01 do not support this value.
PHYSICALOFFSETX | For printing devices: the distance from the left edge of the physical page to the left edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the leftmost 0.25" of paper, has a horizontal physical offset of 150 device units.
Windows CE versions 1.0 and 1.01 do not support this value.
PHYSICALOFFSETY | For printing devices: the distance from the top edge of the physical page to the top edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the topmost 0.5" of paper, has a vertical physical offset of 300 device units.
Windows CE versions 1.0 and 1.01 do not support this value.
RASTERCAPS | Value that indicates the raster capabilities of the device, as shown in the following list:
RC_BANDING | Requires banding support.
RC_BITBLT | Capable of transferring bitmaps.
RC_BITMAP64 | Capable of supporting bitmaps larger than 64K.
RC_DI_BITMAP | Capable of supporting device independent bitmaps.
RC_DIBTODEV | Unsupported.
RC_GDI20_OUTPUT | Capable of supporting features of 16-bit Windows 2.0.
RC_PALETTE | Specifies a palette-based device.
RC_SCALING | Capable of scaling.
RC_STRETCHBLT | Unsupported.
RC_STRETCHDIB | Unsupported
CURVECAPS | Value that indicates the curve capabilities of the device, as shown in the following list:
CC_NONE | Device does not support curves.
CC_CHORD | Device can draw chord arcs.
CC_CIRCLES | Device can draw circles.
CC_ELLIPSES | Device can draw ellipses.
CC_INTERIORS | Device can draw interiors.
CC_PIE | Device can draw pie wedges.
CC_ROUNDRECT | Device can draw rounded rectangles.
CC_STYLED | Device can draw styled borders.
CC_WIDE | Device can draw wide borders.
CC_WIDESTYLED | Device can draw borders that are wide and styled.
LINECAPS | Value that indicates the line capabilities of the device, as shown in the following list:
LC_NONE | Device does not support lines.
LC_INTERIORS | Device can draw interiors.
LC_MARKER | Device can draw a marker.
LC_POLYLINE | Device can draw a polyline.
LC_POLYMARKER | Device can draw multiple markers.
LC_STYLED | Device can draw styled lines.
LC_WIDE | Device can draw wide lines.
LC_WIDESTYLED | Device can draw lines that are wide and styled.
POLYGONALCAPS | Value that indicates the polygon capabilities of the device, as shown in the following list:
PC_NONE | Device does not support polygons.
PC_INTERIORS | Device can draw interiors.
PC_POLYGON | Device can draw alternate-fill polygons.
PC_RECTANGLE | Device can draw rectangles.
PC_SCANLINE | Device can draw a single scanline.
PC_STYLED | Device can draw styled borders.
PC_WIDE | Device can draw wide borders.
PC_WIDESTYLED | Device can draw borders that are wide and styled.
PC_WINDPOLYGON | Device can draw winding-fill polygons.
TEXTCAPS | Value that indicates the text capabilities of the device, as shown in the following list:
TC_OP_CHARACTER | Device is capable of character output precision.
TC_OP_STROKE | Device is capable of stroke output precision.
TC_CP_STROKE | Device is capable of stroke clip precision.
TC_CR_90 | Device is capable of 90-degree character rotation.
TC_CR_ANY | Device is capable of any character rotation.
TC_SF_X_YINDEP | Device can scale independently in the x- and y-directions.
TC_SA_DOUBLE | Device is capable of doubled character for scaling.
TC_SA_INTEGER | Device uses integer multiples only for character scaling.
TC_SA_CONTIN | Device uses any multiples for exact character scaling.
TC_EA_DOUBLE | Device can draw double-weight characters.
TC_IA_ABLE | Device can italicize.
TC_UA_ABLE | Device can underline.
TC_SO_ABLE | Device can draw strikeouts.
TC_RA_ABLE | Device can draw raster fonts.
TC_VA_ABLE | Device can draw vector fonts.
TC_RESERVED | Reserved; must be zero.
TC_SCROLLBLT | Device cannot scroll using a bit-block transfer. Note that this meaning may be the opposite of what you expect.

Return Values

The return value specifies the value of the desired item.

Remarks

The following table shows the six indexes that GetDeviceCaps provides in place of printer escapes.

Index
Printer escape replaced
PHYSICALWIDTH | GETPHYSPAGESIZE
PHYSICALHEIGHT | GETPHYSPAGESIZE
PHYSICALOFFSETX | GETPRINTINGOFFSET
PHYSICALOFFSETY | GETPHYSICALOFFSET
SCALINGFACTORX | GETSCALINGFACTOR
SCALINGFACTORY | GETSCALINGFACTOR

Windows CE versions 1.0 and 1.01 do not support these indexes.

See Also

GetObjectType, StretchBlt


GetDialogBaseUnits

This function returns the dialog box base units used by Windows to create dialog boxes. Both Windows and applications use these units to convert the width and height of dialog boxes and controls from dialog units, as specified in dialog box templates, to pixels, and vice versa.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LONG GetDialogBaseUnits( void );

Return Values

A 32-bit value that contains the dialog base units indicates success. The low-order word of the return value contains the horizontal dialog box base unit, and the high-order word contains the vertical dialog box base unit.

Windows CE does not support any extended error values for this function.

Remarks

The horizontal base unit returned by GetDialogBaseUnits is equal to the average width, in pixels, of the characters in the system font; the vertical base unit is equal to the height, in pixels, of the font.

For a dialog box that does not use the system font, the base units are the average width and height, in pixels, of the characters in the dialog’s font. You can use the GetTextMetrics and GetTextExtentPoint32 functions to calculate these values for a selected font. However, by using the MapDialogRect function, you can avoid errors that might result if your calculations differ from those performed by the system.

Each horizontal base unit is equal to 4 horizontal dialog template units; each vertical base unit is equal to 8 vertical dialog template units. Therefore, to convert dialog template units to pixels, use the following formulas:

pixelX = (templateunitX * baseunitX) / 4
pixelY = (templateunitY * baseunitY) / 8

Similarly, to convert from pixels to dialog template units, use the following formulas:

templateunitX = (pixelX * 4) / baseunitX
templateunitY = (pixelY * 8) / baseunitY

The multiplication is performed before the division to avoid rounding problems if base units are not divisible by 4 or 8.

See Also

HIWORD, LOWORD, MapDialogRect


GetDlgCtrlID

This function returns the identifier of the specified control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int GetDlgCtrlID( HWND hwndCtl );

Parameters

hwndCtl
[in] Handle to the control.

Return Values

The identifier of the control indicates success. Zero indicates failure. An invalid value for the hwndCtl parameter, for example, will cause the function to fail. To get extended error information, call GetLastError.

Remarks

Identifiers are only valid for child windows. An application sets the identifier by passing it in as the hMenu parameter to the CreateWindowEx function. It can also be set and retrieved by calling the SetWindowLong and GetWindowLong functions with the nIndex parameter set to GWL_ID.

Although GetDlgCtrlID may return a value if hwndCtl identifies a top-level window, top-level windows cannot have identifiers and such a return value is never valid.

See Also

CreateWindow, CreateWindowEx, GetDlgItem


GetDlgItem

This function retrieves the handle to a control in the specified dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetDlgItem( HWND hDlg, int nIDDlgItem );

Parameters

hDlg
[in] Handle to the dialog box that contains the control.
nIDDlgItem
[in] Specifies the identifier of the control to be retrieved.

Return Values

The window handle of the specified control indicates success. NULL indicates failure due to an invalid dialog box handle or a nonexistent control. To get extended error information, call GetLastError.

Remarks

You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the hDlg parameter specifies a parent window and the child window has a unique identifier (as specified by the hMenu parameter in the CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window.

The GetDlgItem function works for immediate child controls of a dialog box—it does not search through nested dialog boxes.

See Also

CreateWindow, CreateWindowEx, GetDlgItemInt, GetDlgItemText


GetDlgItemInt

This function translates the text of a specified control in a dialog box into an integer value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT GetDlgItemInt( HWND hDlg, int nIDDlgItem, BOOL *lpTranslated,
BOOL bSigned);

Parameters

hDlg
[in] Handle to the dialog box that contains the control of interest.
nIDDlgItem
[in] Dialog item identifier that specifies the control whose text is to be translated.
lpTranslated
[out] Long pointer to a Boolean variable that receives a function success/failure value (TRUE indicates success, FALSE indicates failure).

This parameter is optional: it can be NULL. In that case, the function returns no information about success or failure.

bSigned
[in] Boolean that specifies whether the function should examine the text for a minus sign at the beginning and return a signed integer value if it finds one. TRUE specifies that this should be done, FALSE that it should not.

Return Values

If the function succeeds, the variable pointed to by lpTranslated is set to TRUE, and the return value is the translated value of the control text.

If the function fails, the variable pointed to by lpTranslated is set to FALSE, and the return value is zero. Note that, since zero is a possible translated value, a return value of zero does not by itself indicate failure.

If lpTranslated is NULL, the function returns no information about success or failure.

If the bSigned parameter is TRUE, specifying that the value to be retrieved is a signed integer value, cast the return value to an int type. To get extended error information, call GetLastError.

Remarks

The GetDlgItemInt function retrieves the text of the specified control by sending the control a WM_GETTEXT message. The function translates the retrieved text by stripping any extra spaces at the beginning of the text and then converting the decimal digits. The function stops translating when it reaches the end of the text or encounters a nonnumeric character.

If the bSigned parameter is TRUE, the GetDlgItemInt function checks for a minus sign (–) at the beginning of the text and translates the text into a signed integer value. Otherwise, the function creates an unsigned integer value.

The GetDlgItemInt function returns zero if the translated value is greater than INT_MAX (for signed numbers) or UINT_MAX (for unsigned numbers).

Text strings with more than 48 characters cannot be translated.

See Also

GetDlgCtrlID, GetDlgItem, GetDlgItemText, SetDlgItemInt


GetDlgItemText

This function retrieves the title or text associated with a control in a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT GetDlgItemText( HWND hDlg, int nIDDlgItem, LPTSTR lpString,
int nMaxCoun);

Parameters

hDlg
[in] Handle to the dialog box that contains the control.
nIDDlgItem
[in] Specifies the identifier of the control whose title or text is to be retrieved.
lpString
[out] Long pointer to the buffer to receive the title or text.
nMaxCount
[in] Specifies the maximum length, in characters, of the string to be copied to the buffer pointed to by lpString. If the length of the string exceeds the limit, the string is truncated.

Return Values

The number of characters copied to the buffer, not including the terminating null character, indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The GetDlgItemText function sends a WM_GETTEXT message to the control.

See Also

GetDlgItemInt, SetDlgItemInt, SetDlgItemText, WM_GETTEXT


GetDoubleClickTime

This function retrieves the current double-click time for the stylus.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT GetDoubleClickTime(void);

Return Values

The return value specifies the current double-click time, in milliseconds.


GetFocus

This function retrieves the handle to the keyboard focus window associated with the thread that called the function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetFocus(void);

Return Values

The handle to the window with the keyboard focus indicates success. NULL indicates that the calling thread’s message queue does not have an associated window with the keyboard focus.

Remarks

Even if GetFocus returns NULL, another thread’s queue may be associated with a window that has the keyboard focus.

Use the GetForegroundWindow function to retrieve the handle to the window with which the user is currently working. You can associate your thread’s message queue with the windows owned by another thread by using the AttachThreadInput function.

See Also

GetActiveWindow, GetCapture, SetFocus, WM_KILLFOCUS, WM_SETFOCUS


GetForegroundWindow

This function returns the handle to the foreground window—the window with which the user is currently working.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetForegroundWindow(void);

Return Values

The handle to the foreground window indicates success.

See Also

SetForegroundWindow


GetKeyboardLayout

This function retrieves the active keyboard layout for a specified thread.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

HKL GetKeyboardLayout( DWORD dwThreadId );

Parameters

dwThreadId
[in] Set to NULL to get the keyboard layout of the active thread. No other value is supported.

Return Values

The keyboard layout handle for the thread indicates success. The low-order word contains a language identifier for the input language and the high-order word contains a device handle for the physical layout of the keyboard. For more information about language identifiers, see Language Identifiers and Locales.

See Also

HIWORD, LOWORD,


GetKeyboardLayoutName

This function retrieves the name of the active keyboard layout.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

BOOL GetKeyboardLayoutName( LPTSTR pwszKLID );

Parameters

pwszKLID
[in] Pointer to the buffer of at least KL_NAMELENGTH characters that is to receive the name of the keyboard layout, including the Terminating null character.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The layout name is read from the registry and not from the loaded keyboard layout. Windows CE does not support the LoadKeyboardLayout function or any other keyboard layout function. Therefore, to change the keyboard layout name, use an application, such as a Control Panel applet, that changes the Active entry in the following registry subkey:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\KeyboardLayout.

The value of the Active entry identifies the system keyboard layout. Its type is REG_SZ.

To use a newly specified keyboard layout, the user must reset the device.

Remarks

Windows NT: GetKeyboardLayoutName receives the name of the active keyboard layout for the system.

Windows 95: GetKeyboardLayoutName receives the name of the active keyboard layout for the calling thread.›


GetKeyboardStatus

This function returns the status of the hardware keyboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | Japanese version 1.0 and later

Syntax

DWORD GetKeyboardStatus( VOID );

Return Values

KBDI_KEYBOARD_PRESENT indicates that hardware keyboard is present on the system. KBDI_KEYBOARD_ENABLED indicates that hardware keyboard is currently enabled. KBDI_KEYBOARD_ENTER_ESC indicates that the keyboard has an ENTER key and an ESCAPE key, or the equivalents. KBDI_KEYBOARD_ALPHA_NUM indicates that the keyboard has alphabetic and numeric keys.


GetKeyState

This function retrieves the status of the specified virtual key. The status specifies whether the key is up, down, or toggled on or off—alternating each time the key is pressed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

SHORT GetKeyState( int nVirtKey );

Parameters

nVirtKey
[in] Specifies a virtual key. If the desired virtual key is a letter or digit (A through Z, a through z, or 0 through 9), nVirtKey must be set to the ASCII value of that character. For other keys, it must be a virtual-key code.

If a non-English keyboard layout is used, virtual keys with values in the range ASCII A through Z and 0 through 9 are used to specify most of the character keys. For example, for the German keyboard layout, the virtual key of value ASCII O (0x4F) refers to the “o” key, whereas VK_OEM_1 refers to the “o with umlaut” key.

Return Values

The return value specifies the status of the specifed virtual key, as follows:

  • If the high-order bit is 1, the key is down; otherwise, it is up.
  • If the low-order bit is 1, the key is toggled. A key, such as the CAPS LOCK key, is toggled if it is turned on. The key is off and untoggled if the low-order bit is 0. A toggle key’s indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.

Remarks

The GetKeyState function can be used to check the down state of the following virtual keys:

VK_CONTROL | VK_RCONTROL
VK_LCONTROL | VK_RMENU
VK_LSHIFT | VK_RSHIFT
VK_LMENU | VK_SHIFT
VK_MENU |

For Windows CE versions 1.0 through 2.01, GetKeyState is used to check the toggled state of the VK_CAPITAL virtual key only. For Windows CE versions 2.10 and later, the toggle state of the VK_NUMLOCK virtual key can also be checked.

The key status returned from this function changes as a specifed thread reads key messages from its message queue. The status does not reflect the interrupt-level state associated with the hardware. Use the GetAsyncKeyState function to retrieve that information.

An application calls GetKeyState in response to a keyboard-input message. This function retrieves the state of the key when the input message was generated.

An application can use the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the nVirtKey parameter. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as values for nVirtKey to distinguish between the left and right instances of those keys.

VK_LSHIFT | VK_RSHIFT
VK_LCONTROL | VK_RCONTROL
VK_LMENU | VK_RMENU

These left- and right-distinguishing constants are available to an application only through the GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetAsyncKeyState, MapVirtualKey


GetMenuItemInfo

This function retrieves information about a menu item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetMenuItemInfo(HMENU hmenu, UINT uItem, BOOL fByPosition,
LPMENUITEMINFO pmii);

Parameters

hMenu
[in] Handle to the menu that contains the menu item.
uItem
[in] Specifies the identifier or position of the menu item to get information about. The meaning of this parameter depends on the value of fByPosition.
fByPosition
[in] Value that specifies the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.
lpmii
[in/out] Long pointer to a MENUITEMINFO structure that specifies the information to retrieve and receives information about the menu item.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The system provides the check mark bitmap; therefore, the MENUITEMINFO structure does not contain information about the check mark bitmaps.

See Also

SetMenuItemInfo, MENUITEMINFO


GetMessage

This function retrieves a message from the calling thread’s message queue and places it in the specified structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetMessage(LPMSG lpMsg, HWND hWnd, UINT wMsgFilterMin, UINT wMsgFilterMax);

Parameters

lpMsg
[out] Long pointer to an MSG structure that receives message information from the thread’s message queue.
hWnd
[in] Handle to the window whose messages are to be retrieved. One value has a special meaning:
Value
Description
NULL GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread by means of PostThreadMessage.

wMsgFilterMin
[in] Specifies the integer value of the lowest message value to be retrieved.
wMsgFilterMax
[in] Specifies the integer value of the highest message value to be retrieved.

Return Values

Nonzero indicates that the function retrieves a message other than WM_QUIT. Zero indicates that the function retrieves the WM_QUIT message. –1 indicates that an error occurred—for example, the function fails if hWnd is an invalid window handle or lpMsg is an invalid pointer. To get extended error information, call GetLastError.

Remarks

An application typically uses the return value to determine whether to end the main message loop and exit the program.

The GetMessage function only retrieves messages associated with the window identified by the hWnd parameter or any of its children, as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread by means of PostThreadMessage. GetMessage does not retrieve messages for windows that belong to other threads nor for threads other than the calling thread, even if hWnd is not NULL. Thread messages, posted by the PostThreadMessage function, have a message hWnd value of NULL. If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all messages related to keyboard input; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse messages. If the wMsgFilterMin and wMsgFilterMax parameters are both zero, the GetMessage function returns all available messages (that is, without performing any filtering).

GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until processed.

Note that the function return value can be nonzero, zero, or –1. Thus, you should avoid code like this:

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

The possibility of a –1 return value means that such code can lead to fatal application errors.

See Also

IsChild, MSG, PeekMessage, PostMessage, PostThreadMessage


GetMessagePos

This function returns a long value that gives the cursor position in screen coordinates.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetMessagePos(void);

Return Values

The return value specifies the x- and y-coordinates of the cursor position. The x-coordinate is the low order int and the y-coordinate is the high-order int.

Remarks

As noted above, the x-coordinate is in the low-order int of the return value; the y-coordinate is in the high-order int (both represent signed values because they can take negative values on systems with multiple monitors).

For platforms that use a stylus rather than a mouse, the cursor position is the position of the stylus on the touch screen when the last message retrieved by the GetMessage function occurred.

To determine the current position of the cursor instead of the position when the last message occurred, use the GetCursorPos function.

Do not use the LOWORD or HIWORD macros to extract the x- and y- coordinates of the cursor position because these macros return incorrect results on systems with multiple monitors. Systems with multiple monitor systems can have negative x- and y- coordinates, and LOWORD and HIWORD treat the coordinates as unsigned quantities.

See Also

GetMessage


GetMessageSource

This function determines the source of a keyboard message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

UINT GetMessageSource( );

Return Values

MSGSRC_SOFTWARE_POST indicates that the message source was software. MSGSRC_HARDWARE_KEYBOARD indicates that the message source was the keyboard. MSGSRC_UNKNOWN indicates that the message source is unknown.

Remarks

When targeting devices that support both a hardware keyboard and a “soft” keyboard, you can use the GetMessageSource function to determine the source of a keyboard input message. Keyboard events that originate from the keyboard driver or keybd_event are marked as hardware. Messages generated from PostMessage are marked as software.

Use this function to determine the source of the following messages:

  • WM_KEYDOWN
  • WM_KEYUP
  • WM_SYSKEYDOWN
  • WM_SYSKEYUP

See Also

keybd_event, PostMessage


GetMouseMovePoints

This function retrieves points—associated with WM_LBUTTONDOWN and WM_MOUSEMOVE messages—that would typically be discarded because an application cannot process these messages as fast as they are received.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI GetMouseMovePoints (PPOINT pptBuf, UINT nBufPoints, UINT *pnPointsRetrieved);

Parameters

pptBuf
Pointer to an array of points. On return, this buffer contains the points retrieved from the current mouse move.
nBufPoints
Specifies the size, in points, of the buffer passed in the pptBuf parameter.
pnPointsRetrieved
Pointer to an unsigned integer. On return, this parameter contains the number of points actually retrieved into the pptBuf buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The GetMouseMovePoints function allows an application to track stylus input at a somewhat higher resolution than the resolution of the display screen. This makes it possible to improve inking performance. GetMouseMovePoints does not draw the ink; it just makes it easier to collect the points so another function can draw them.

GetMouseMovePoints is not supported for emulation.

See Also

WM_LBUTTONDOWN, WM_MOUSEMOVE, POINT


GetNearestColor

This function returns the system palette color that will be displayed when the specified color value is used.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF GetNearestColor(HDC hdc, COLORREF crColor);

Parameters

hdc
[in] Handle to the device context (DC).
crColor
[in] Specifies a color value that identifies a requested color.

Return Values

If the function succeeds, the return value identifies a color from the system palette that corresponds to the specified color value.

If the function fails, the return value is CLR_INVALID.

To get extended error information, call GetLastError.

Remarks

The GetNearestColor function returns the color from the selected device context that most closely matches the specified color value.

See Also

COLORREF, GetDeviceCaps


GetNearestPaletteIndex

This function retrieves the index for the entry in the specified logical palette that most closely matches a specified color value.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

UINT GetNearestPaletteIndex( HPALETTE hpal, COLORREF crColor);

Parameters

hpal
[in] Handle to a logical color palette.
crColor
[in] Specifies a color to be matched.

Return Values

The index of an entry in a logical palette indicates success. CLR_INVALID indicates failure. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If the given logical palette contains entries with the PC_EXPLICIT flag set, the return value is undefined.

See Also

GetPaletteEntries, GetSystemPaletteEntries


GetNextDlgGroupItem

This function retrieves the handle to the first control in a group of controls that precedes or follows the specified control in a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetNextDlgGroupItem( HWND hDlg, HWND hCtl, BOOL bPrevious );

Parameters

hDlg
[in] Handle to the dialog box being searched.
hCtl
[in] Handle to the control to be used as the starting point for the search. If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search.
bPrevious
[in] Boolean that specifies how the function is to search the group of controls in the dialog box. If this parameter is TRUE, the function searches for the previous control in the group. If it is FALSE, the function searches for the next control in the group.

Return Values

The handle of the previous or next control in the group of controls indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The GetNextDlgGroupItem function searches controls in the order (or reverse order) they were created in the dialog box template. The first control in the group must have the WS_GROUP style; all other controls in the group must have been consecutively created and must not have the WS_GROUP style.

When searching for the previous control, the function returns the first control it locates that is visible and not disabled. If the control specified by hCtl has the WS_GROUP style, the function temporarily reverses the search to locate the first control having the WS_GROUP style, then resumes the search in the original direction, returning the first control it locates that is visible and not disabled, or returning hwndCtrl if no such control is found.

When searching for the next control, the function returns the first control it locates that is visible, not disabled, and does not have the WS_GROUP style. If it encounters a control having the WS_GROUP style, the function reverses the search, locates the first control having the WS_GROUP style, and returns this control if it is visible and not disabled. Otherwise, the function resumes the search in the original direction and returns the first control it locates that is visible and not disabled, or returns hCtl if no such control is found.

See Also

GetNextDlgTabItem


GetNextDlgTabItem

This function retrieves the handle to the first control with the WS_TABSTOP style that precedes or follows the specified control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetNextDlgTabItem( HWND hDlg, HWND hCtl, BOOL bPrevious );

Parameters

hDlg
[in] Handle to the dialog box to be searched.
hCtl
[in] Handle to the control to be used as the starting point for the search. If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search.
bPrevious
[in] Boolean that specifies how the function is to search the dialog box. If this parameter is TRUE, the function searches for the previous control in the dialog box. If this parameter is FALSE, the function searches for the next control in the dialog box.

Return Values

The window handle of the previous or next control that has the WS_TABSTOP style set indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The GetNextDlgTabItem function searches controls in the order (or reverse order) they were created in the dialog box template. The function returns the first control it locates that is visible, not disabled, and has the WS_TABSTOP style. If no such control exists, the function returns hCtl.

See Also

GetDlgItem, GetNextDlgGroupItem


GetObject

This function obtains information about a specified graphics object. Depending on the graphics object, the function places a filled-in BITMAP, DIBSECTON, LOGBRUSH, LOGFONT, or LOGPEN structure into a specified buffer.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int GetObject(HGDIOBJ hgdiobj, int cbBuffer, LPVOID lpvObject);

Parameters

hgdiobj
[in] Handle to the graphics object of interest. This can be a handle to one of the following: a logical bitmap, a brush, a font, a palette, a pen, or a device-independent bitmap created by calling the CreateDIBSection function.
cbBuffer
[in] Specifies the number of bytes of information to be written to the buffer.
lpvObject
[out] Long pointer to a buffer that is to receive the information about the specified graphics object.

The following table shows the type of information the buffer receives for each type of graphics object you can specify with hgdiobj:
Object type
Data written to *lpvObject
HBITMAP | BITMAP
HBITMAP returned from a call to CreateDIBSection | DIBSECTION, if cbBuffer is set to sizeof(DIBSECTION), or BITMAP, if cbBuffer is set to sizeof(BITMAP)
HPALETTE | A WORD count of the number of entries in the logical palette
HPEN | LOGPEN
HBRUSH | LOGBRUSH
HFONT | LOGFONT

If the lpvObject parameter is NULL, the function return value is the number of bytes required to store the information it writes to the buffer for the specified graphics object.

For Windows CE versions 1.0 and 1.01:

  • The HPALETTE object type is not supported.
  • GetObject always returns a BITMAP when it is used on a DIB section.

Return Values

If the function succeeds, and lpvObject is a valid pointer, the return value is the number of bytes stored into the buffer.

If the function succeeds, and lpvObject is NULL, the return value is the number of bytes required to hold the information the function would store into the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The buffer pointed to by the lpvObject parameter must be sufficiently large to receive the information about the graphics object.

If hgdiobj identifies a bitmap created by calling CreateDIBSection, and the specified buffer is large enough, the GetObject function returns a DIBSECTION structure. In addition, the bmBits member of the BITMAP structure contained within the DIBSECTION will contain a pointer to the bitmap's bit values.

If hgdiobj identifies a bitmap created by any other means, GetObject returns only the width, height, and color format information of the bitmap.

If hgdiobj identifies a logical palette, GetObject retrieves a 2-byte integer that specifies the number of entries in the palette. The function does not retrieve the LOGPALETTE structure defining the palette. To retrieve information about palette entries, an application can call the GetPaletteEntries function.

See Also

CreateDIBSection, GetRegionData, BITMAP, DIBSECTION, LOGBRUSH, LOGFONT, LOGPEN


GetObjectType

This function returns the type of the specified object.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetObjectType(HGDIOBJ h);

Parameters

h
[in] Handle to the graphics object.

Return Values

If the function succeeds, the return value identifies the object. This value can be one of the following:

Value
Description
OBJ_BITMAP | Bitmap
OBJ_BRUSH | Brush
OBJ_FONT | Font
OBJ_PAL | Palette
OBJ_PEN | Pen
OBJ_REGION | Region
OBJ_DC | Device context
OBJ_MEMDC | Memory device context

Windows CE versions 1.0 and 1.01 do not support the OBJ_PAL return value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

GetObject, SelectObject


GetOpenClipboardWindow

This function retrieves the handle to the window that currently has the clipboard open.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetOpenClipboardWindow(void);

Return Values

The handle of the window that has the clipboard open indicates success. NULL indicates that no window has the clipboard open. To get extended error information, call GetLastError.

Remarks

If an application or dynamic-link library (DLL) specifies a NULL window handle when calling the OpenClipboard function, the clipboard is opened but is not associated with a window. In such a case, GetOpenClipboardWindow returns NULL.

See Also

GetClipboardOwner, OpenClipboard


GetPaletteEntries

This function retrieves a specified range of palette entries from the specified logical palette.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

UINT GetPaletteEntries( HPALETTE hpal, UINT iStartIndex,
UINT nEntries, LPPALETTEENTRY lppe);

Parameters

hpal
[in] Handle to the logical color palette.
iStartIndex
[in] Index of the first entry in the logical palette to be retrieved. GetPaletteEntries fails if iStartIndex is greater than the number of palette entries.
nEntries
[in] Specifies the number of entries in the logical palette to be retrieved.
lppe
[out] Long pointer to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many structures as specified by the nEntries parameter.

Return Values

If the handle of the logical color palette is a valid pointer—not NULL—the number of entries retrieved from the logical palette indicates success. If the handle of the logical color palette is NULL, the number of entries in the specified palette indicates success. Zero indicates failure.

To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If the nEntries parameter specifies more entries than exist in the palette, the remaining members of the PALETTEENTRY structure are not altered.

See Also

GetNearestPaletteIndex, GetSystemPaletteEntries


GetParent

This function retrieves the handle to the specified child window's parent window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetParent( HWND hWnd);

Parameters

hWnd
Handle to the window whose parent window handle is to be retrieved.

Return Values

A handle to the parent window indicates success. NULL indicates that the window has no parent window. To get extended error information, call GetLastError.

Windows CE Remarks

Windows CE version 1.0 does not support owned windows, except for dialog boxes.

See Also

SetParent


GetPixel

This function retrieves the red, green, blue (RGB) color value of the pixel at the specified coordinates.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF GetPixel(HDC hdc, int nXPos, int nYPos);

Parameters

hdc
[in] Handle to the device context.
nXPos
[in] Specifies the logical x-coordinate of the pixel to be examined.
nYPos
[in] Specifies the logical y-coordinate of the pixel to be examined.

Return Values

The RGB value of the pixel indicates success. CLR_INVALID indicates that the pixel is outside of the current clipping region.

Remarks

The pixel must be within the boundaries of the current clipping region.

Not all devices support GetPixel. An application should call GetDeviceCaps to determine whether a specified device supports this function.

See Also

GetDeviceCaps, SetPixel


GetPriorityClipboardFormat

This function returns the first available clipboard format in the specified list.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int GetPriorityClipboardFormat(UINT *paFormatPriorityList, int cFormats);

Parameters

paFormatPriorityList
[in] Pointer to an array of unsigned integers identifying clipboard formats, in priority order. cFormats

[in] Integer that contains the number of entries in the paFormatPriorityList array. This value must not be greater than the number of entries in the list.

Return Values

The first clipboard format in the list for which data is available indicates success. NULL indicates that the clipboard is empty. –1 indicates that the clipboard contains data, but not in any of the specified formats. To get extended error information, call GetLastError.

Remarks

During a copy or cut operation, a window calls SetClipboardData to place data on the clipboard in as many clipboard formats as possible, ordered from the most descriptive clipboard format to the least descriptive. During a paste operation, an application can specify a different format priority order with GetPriorityClipboardFormat. This function returns the first format from the specified list that is found on the clipboard.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName, IsClipboardFormatAvailable, RegisterClipboardFormat, SetClipboardData


GetRegionData

This function fills the specified buffer with data describing a region. This data includes the dimensions of the rectangles that make up the region.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetRegionData(HRGN hRgn, DWORD dwCount,
LPRGNDATA lpRgnData);

Parameters

hRgn
[in] Handle to the region.
dwCount
[in] Specifies the size, in bytes, of the lpRgnData buffer.
lpRgnData
[out] Long pointer to a RGNDATA structure that receives the information. If this parameter is NULL, the return value contains the number of bytes needed for the region data.

Return Values

If dwCount specifies an adequate number of bytes, 1 indicates success. If dwCount is too small or lpRgnData is NULL, the required number of bytes indicates success. Zero indicates failure.

To get extended error information, call GetLastError.

Remarks

The GetRegionData function is used in conjunction with the ExtCreateRegion function.

Windows CE represents regions differently than other Windows-based desktop platforms. A Windows CE implementation of GetRegionData may return a greater number of rectangles for a specified region than Windows-based desktop platforms.

See Also

RGNDATA


GetRgnBox

This function retrieves the bounding rectangle of the specified region.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int GetRgnBox(HRGN hrgn, LPRECT lprc);

Parameters

hrgn
[in] Handle to the region.
lprc
[out] Long pointer to a RECT structure that receives the bounding rectangle.

Return Values

The return value specifies the region’s complexity. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than a single rectangle. Zero indicates that the hrgn parameter does not identify a valid region

See Also

RECT


GetScrollInfo

This function retrieves the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb).

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetScrollInfo( HWND hwnd, int fnBar, LPSCROLLINFO lpsi );

Parameters

hwnd
Handle to a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.
fnBar
Specifies the type of scroll bar for which to retrieve parameters. It is one of the following values:
Value
Description
SB_CTL | Retrieves the parameters for a scroll bar control. The hwnd parameter must be the handle to the scroll bar control.
SB_HORZ | Retrieves the parameters for the given window's standard horizontal scroll bar.
SB_VERT | Retrieves the parameters for the given window's standard vertical scroll bar.

lpsi
Long pointer to a SCROLLINFO structure. Before calling GetScrollInfo, set the cbSize member of the structure to sizeof(SCROLLINFO), and set the fMask member to specify the scroll bar parameters to retrieve. Before returning, the function copies the specified parameters to the appropriate members of the structure.

The fMask member can be a combination of the following values:
Value
Description
SIF_PAGE | Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS | Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE | Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
SIF_TRACKPOS | Copies the current scroll box tracking position to the nTrackPos member of the SCROLLINFO structure pointed to by lpsi.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The GetScrollInfo function enables applications to use 32-bit scroll positions. Although the messages that indicate scroll-bar position, WM_HSCROLL and WM_VSCROLL, provide only 16 bits of position data, the functions SetScrollInfo and GetScrollInfo provide 32 bits of scroll-bar position data. Thus, an application can call GetScrollInfo while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll-bar position data.

To get the 32-bit position of the scroll box (thumb) during a SB_THUMBTRACK notification in a WM_HSCROLL or WM_VSCROLL message, call GetScrollInfo with the SIF_TRACKPOS value in the fMask member of the SCROLLINFO structure. The function returns the tracking position of the scroll box in the nTrackPos member of the SCROLLINFO structure. This allows you to get the position of the scroll box as the user moves it. The following sample code illustrates the technique.

SCROLLINFO si;
case WM_HSCROLL:
 switch(LOWORD(wparam)) {
 case SB_THUMBTRACK:
 // Initialize SCROLLINFO structure

 ZeroMemory(&si, sizeof(SCROLLINFO));
 si.cbSize = sizeof(SCROLLINFO);
 si.fMask = SIF_TRACKPOS;

 // Call GetScrollInfo to get current tracking
 // position in si.nTrackPos

 if (!GetScrollInfo(hwnd, SB_HORZ, &si) )
 return 1; // GetScrollInfo failed
 break;
 .
 .
 .
 }

See Also

SCROLLINFO, SetScrollInfo, WM_HSCROLL, WM_VSCROLL


GetStockObject

This function retrieves a handle to one of the predefined stock pens, brushes or fonts.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HGDIOBJ GetStockObject(int fnObject);

Parameters

fnObject
[in] Specifies the type of stock object. It is one of the following values:
Value
Description
BLACK_BRUSH | Black brush.
DKGRAY_BRUSH | Dark gray brush.
GRAY_BRUSH | Gray brush.
HOLLOW_BRUSH | Hollow brush (equivalent to NULL_BRUSH).
LTGRAY_BRUSH | Light gray brush.
NULL_BRUSH | Null brush (equivalent to HOLLOW_BRUSH).
WHITE_BRUSH | White brush.
BLACK_PEN | Black pen.
WHITE_PEN | White pen.
SYSTEM_FONT | System font. By default, the system uses the system font to draw menus, dialog box controls, and text.
DEFAULT_PALETTE | Default palette. This palette consists of the static colors in the system palette. Windows CE versions 1.0 and 1.01 do not support this value.

Return Values

If the function succeeds, the return value identifies the logical object requested. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

Use the DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH stock objects only in windows with the CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush in any other style of window can lead to misalignment of brush patterns after a window is moved or sized. The origins of stock brushes cannot be adjusted.

The HOLLOW_BRUSH and NULL_BRUSH stock objects are equivalent.

It is not necessary (but it is not harmful) to delete stock objects by calling DeleteObject.

See Also

DeleteObject, SelectObject


GetSubMenu

This function retrieves the handle to the pop-up menu activated by the specified menu item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HMENU GetSubMenu(HMENU hMenu, int nPos);

Parameters

hMenu
[in] Handle to the menu.
nPos
[in] Specifies the zero-based relative position in the given menu of an item that activates a drop-down menu or submenu.

Return Values

The handle to the drop-down menu or submenu activated by the menu item indicates success. NULL indicates that the menu item does not activate a drop-down menu or submenu.

See Also

CreatePopupMenu


GetSysColor

This function retrieves the current color of the specified display element. Display elements are the parts of a window and the Windows display that appear on the system display screen.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetSysColor(int nIndex);

Parameters

nIndex
Specifies the display element whose color is to be retrieved. This parameter must be one of the following values:
Value
Description
COLOR_3DDKSHADOW | Dark shadow for three-dimensional display elements.
COLOR_3DFACE, COLOR_BTNFACE | Face color for three-dimensional display elements.
COLOR_3DHILIGHT, COLOR_3DHIGHLIGHT, COLOR_BTNHILIGHT, COLOR_BTNHIGHLIGHT | Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DLIGHT | Light color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DSHADOW, COLOR_BTNSHADOW | Shadow color for three-dimensional display elements (for edges facing away from the light source).
COLOR_ACTIVEBORDER | Active window border.
COLOR_ACTIVECAPTION | Active window title bar.
COLOR_APPWORKSPACE | Background color of multiple document interface (MDI) applications.
COLOR_BACKGROUND, COLOR_DESKTOP | Desktop.
COLOR_BTNTEXT | Text on push buttons.
COLOR_CAPTIONTEXT | Text in caption, size box, and scroll bar arrow box.
COLOR_GRAYTEXT | Grayed (disabled) text. This color is set to 0 if the current display driver does not support a solid gray color.
COLOR_HIGHLIGHT | Item(s) selected in a control.
COLOR_HIGHLIGHTTEXT | Text of item(s) selected in a control.
COLOR_INACTIVEBORDER | Inactive window border.
COLOR_INACTIVECAPTION | Inactive window caption.
COLOR_INACTIVECAPTIONTEXT | Color of text in an inactive caption.
COLOR_INFOBK | Background color for tooltip controls.
COLOR_INFOTEXT | Text color for tooltip controls.
COLOR_MENU | Menu background.
COLOR_MENUTEXT | Text in menus.
COLOR_SCROLLBAR | Scroll bar gray area.
COLOR_STATIC | Background color for static controls and dialogs. Supported in Windows CE versions 2.0 and later.
COLOR_STATICTEXT | Text color for static controls. Supported in Windows CE versions 2.0 and later.
COLOR_WINDOW | Window background.
COLOR_WINDOWFRAME | Window frame.
COLOR_WINDOWTEXT | Text in windows.

Return Values

The red, green, blue (RGB) color value that determines the color of the specified element indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE versions 1.0 and 1.01 only support a 2 bit gray scale palette, so GetSysColor returns a palette index rather than an RGB value. Windows CE graphic display interface (GDI) functions that accept a COLORREF structure can use either a palette index or an RGB value. However, if the application attempts to interpret the color value, be aware of this difference.

Windows CE version 2.0 supports 2 bits per pixel (2-bpp), 4 bits per pixel (4-bpp), and 8 bits per pixel (8-bpp) color devices, and can logically support 32 bits per pixel device independent bitmaps (DIBs). In Windows CE version 2.0, GetSysColor returns an RGB value.

System colors for monochrome displays are usually interpreted as shades of gray.


GetSysColorBrush

This function retrieves a handle identifying a logical brush that corresponds to the specified color index.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HBRUSH GetSysColorBrush(int nIndex);

Parameters

nIndex
[in] Specifies a color index. This value corresponds to the color used to paint one of the 21 window elements.

Return Values

Handle to a logical brush indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

A brush is a bitmap that the system uses to paint the interiors of filled shapes. An application can retrieve the current system colors by calling the GetSysColor function. An application can set the current system colors by calling the SetSysColors function.

An application must not register a window class for a window using a system brush.

The values assigned to the COLOR_* flags in Windows CE are different from the values assigned to these flags in Windows-based desktop platforms. Therefore, you should specify the COLOR_* flag value, rather than the corresponding integer value, for the nIndex parameter. For a list of all the standard system colors, see GetSysColor.

See Also

GetSysColor


GetSystemMenu

This function is implemented as a macro to maintain compatibility with existing code. Use the menu handle returned by this macro to disable the Close button. There is no other use for the return value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HMENU GetSystemMenu(HWND hWnd, BOOL bRevert);

Parameters

hWnd
[in] Handle to the window that will own a copy of the window menu.
bRevert
[in] Boolean that specifies the action to be taken. If this parameter is FALSE, GetSystemMenu returns the handle to the copy of the window menu currently in use. The copy is initially identical to the window menu, but it can be modified.

If this parameter is TRUE, GetSystemMenu resets the window menu back to the default state. The previous window menu, if any, is destroyed.

Return Values

The handle to a copy of the window menu indicates that the bRevert parameter is FALSE. NULL indicates that the bRevert parameter is TRUE.

Remarks

Use the following code to disable the Close button:

EnableMenuItem (GetSystemMenu(hwnd, FALSE), SC_CLOSE,MF_BYCOMMAND | MF_GRAYED);


GetSystemMetrics

This function retrieves the dimensions—widths and heights—of Windows display elements and system configuration settings. All dimensions retrieved by GetSystemMetrics are in pixels. The RAPI version is CeGetSystemMetrics for versions 2.0 and later.

At a Glance

Header file: | Winuser.h Rapi.h
Windows CE versions: | 1.0 and later

Syntax

int GetSystemMetrics(int nIndex);

Parameters

nIndex
Specifies the system metric or configuration setting to retrieve. All SM_CX* values are widths. All SM_CY* values are heights. The following values are defined.
Value
Description
SM_ARRANGE | Flags specifying how the system arranged minimized windows. For more information about minimized windows, see the following Remarks section.
SM_CLEANBOOT | Value that specifies how the system was started, as shown in the following table.
0 | Normal boot
1 | Fail-safe boot
2 | Fail-safe with network boot
Fail-safe boot (also called SafeBoot) bypasses the user’s startup files.
SM_CMONITORS | Windows NT 5.0 and later; Windows 98 and later: Number of display monitors on the desktop.
SM_CMOUSEBUTTONS | Number of buttons on mouse, or zero if no mouse is installed.
SM_CXBORDER, SM_CYBORDER | Width and height, in pixels, of a window border. This is equivalent to the SM_CXEDGE value for windows with the 3-D look.
SM_CXCURSOR, SM_CYCURSOR | Width and height, in pixels, of a cursor. The system cannot create cursors of other sizes.
SM_CXDLGFRAME, SM_CYDLGFRAME | Same as SM_CXFIXEDFRAME and SM_CYFIXEDFRAME.
SM_CXDOUBLECLK, SM_CYDOUBLECLK | Width and height, in pixels, of the rectangle around the location of a first click in a double-click sequence. The second click must occur within this rectangle for the system to consider the two clicks a double-click. (The two clicks must also occur within a specified time.)
SM_CXDRAG, SM_CYDRAG | Width and height, in pixels, of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins. This allows the user to click and release the mouse button easily without unintentionally starting a drag operation.
SM_CXEDGE, SM_CYEDGE | Dimensions, in pixels, of a 3-D border. These are the 3-D counterparts of SM_CXBORDER and SM_CYBORDER.
SM_CXFIXEDFRAME, SM_CYFIXEDFRAME | Thickness, in pixels, of the frame around the perimeter of a window that has a caption but is not sizable. SM_CXFIXEDFRAME is the width of the horizontal border and SM_CYFIXEDFRAME is the height of the vertical border.
Same as SM_CXDLGFRAME and SM_CYDLGFRAME.
SM_CXFRAME, SM_CYFRAME | Same as SM_CXSIZEFRAME and SM_CYSIZEFRAME.
SM_CXFULLSCREEN, SM_CYFULLSCREEN | Width and height of the client area for a full-screen window on the primary display monitor. To get the coordinates of the portion of the screen not obscured by the system taskbar or by application desktop toolbars, call the SystemParametersInfo function with the SPI_GETWORKAREA value.
SM_CXHSCROLL, SM_CYHSCROLL | Width, in pixels, of the arrow bitmap on a horizontal scroll bar; and height, in pixels, of a horizontal scroll bar.
SM_CXHTHUMB | Width, in pixels, of the thumb box in a horizontal scroll bar.
SM_CXICON, SM_CYICON | The default width and height, in pixels, of an icon. The LoadIcon function can load only icons of these dimensions.
SM_CXICONSPACING, SM_CYICONSPACING | Dimensions, in pixels, of a grid cell for items in large icon view. Each item fits into a rectangle of this size when arranged. These values are always greater than or equal to SM_CXICON and SM_CYICON.
SM_CXMAXIMIZED, SM_CYMAXIMIZED | Default dimensions, in pixels, of a maximized top-level window on the primary display monitor.
SM_CXMAXTRACK, SM_CYMAXTRACK | Default maximum dimensions, in pixels, of a window that has a caption and sizing borders. This metric refers to the entire desktop. The user cannot drag the window frame to a size larger than these dimensions.
SM_CXMENUCHECK, SM_CYMENUCHECK | Dimensions, in pixels, of the default menu check-mark bitmap.
SM_CXMENUSIZE, SM_CYMENUSIZE | Dimensions, in pixels, of menu bar buttons, such as the child window close button used in the multiple document interface.
SM_CXMIN, SM_CYMIN | Minimum width and height, in pixels, of a window.
SM_CXMINIMIZED, SM_CYMINIMIZED | Dimensions, in pixels, of a normal minimized window.
SM_CXMINSPACING, SM_CYMINSPACING | Dimensions, in pixels, of a grid cell for minimized windows. Each minimized window fits into a rectangle this size when arranged. These values are always greater than or equal to SM_CXMINIMIZED and SM_CYMINIMIZED.
SM_CXMINTRACK, SM_CYMINTRACK | Minimum tracking width and height, in pixels, of a window. The user cannot drag the window frame to a size smaller than these dimensions.
SM_CXSCREEN, SM_CYSCREEN | Width and height, in pixels, of the screen of the primary display monitor. These are the same values you obtain by calling GetDeviceCaps(hdcPrimaryMonitor, HORZRES/VERTRES).
SM_CXSIZE, SM_CYSIZE | Width and height, in pixels, of a button in a window's caption or title bar.
SM_CXSIZEFRAME, SM_CYSIZEFRAME | Thickness, in pixels, of the sizing border around the perimeter of a window that can be resized. SM_CXSIZEFRAME is the width of the horizontal border, and SM_CYSIZEFRAME is the height of the vertical border.
Same as SM_CXFRAME and SM_CYFRAME.
SM_CXSMICON, SM_CYSMICON | Recommended dimensions, in pixels, of a small icon. Small icons typically appear in window captions and in small icon view.
SM_CXSMSIZE, SM_CYSMSIZE | Dimensions, in pixels, of small caption buttons.
SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN | Windows NT 5.0 and later; Windows 98 and later: Width and height, in pixels, of the virtual screen. The virtual screen is the bounding rectangle of all display monitors. The SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN metrics are the coordinates of the top left corner of the virtual screen.
SM_CXVSCROLL, SM_CYVSCROLL | Width, in pixels, of a vertical scroll bar; and height, in pixels, of the arrow bitmap on a vertical scroll bar.
SM_CYCAPTION | Height, in pixels, of a normal caption area.
SM_CYKANJIWINDOW | For double-byte character set versions of the system, this is the height, in pixels, of the Kanji window at the bottom of the screen.
SM_CYMENU | Height, in pixels, of a single-line menu bar.
SM_CYSMCAPTION | Height, in pixels, of a small caption.
SM_CYVTHUMB | Height, in pixels, of the thumb box in a vertical scroll bar.
SM_DBCSENABLED | TRUE or nonzero if the double-byte character set (DBCS) version of USER.EXE is installed; FALSE or zero otherwise.
SM_DEBUG | TRUE or nonzero if the debugging version of USER.EXE is installed; FALSE or zero otherwise.
SM_MENUDROPALIGNMENT | TRUE or nonzero if drop-down menus are right-aligned with the corresponding menu-bar item; FALSE or zero if the menus are left-aligned.
SM_MIDEASTENABLED | TRUE if the system is enabled for Hebrew and Arabic languages.
SM_MOUSEPRESENT | TRUE or nonzero if a mouse is installed; FALSE or zero otherwise.
SM_MOUSEWHEELPRESENT | Windows NT 4.0 and later, Windows 98: TRUE or nonzero if a mouse with a wheel is installed; FALSE or zero otherwise.
SM_NETWORK | The least significant bit is set if a network is present; otherwise, it is cleared. The other bits are reserved for future use.
SM_PENWINDOWS | TRUE or nonzero if the Microsoft Windows for Pen computing extensions are installed; FALSE or zero otherwise.
SM_SECURE | TRUE if security is present; FALSE otherwise.
SM_SAMEDISPLAYFORMAT | Windows NT 5.0 and later; Windows 98 and later: TRUE if all the display monitors have the same color format, FALSE otherwise. Note that two displays can have the same bit depth, but different color formats. For example, the red, green, and blue pixels can be encoded with different numbers of bits, or those bits can be located in different places in a pixel’s color value.
SM_SHOWSOUNDS | TRUE or nonzero if the user requires an application to present information visually in situations where it would otherwise present the information only in audible form; FALSE, or zero, otherwise.
SM_SLOWMACHINE | TRUE if the computer has a low-end (slow) processor; FALSE otherwise.
SM_SWAPBUTTON | TRUE or nonzero if the meanings of the left and right mouse buttons are swapped; FALSE or zero otherwise.
SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN | Windows NT 5.0 and later; Windows 98 and later: Coordinates for the left side and the top of the virtual screen. The virtual screen is the bounding rectangle of all display monitors. The SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN metrics are the width and height of the virtual screen.

Return Values

The requested system metric or configuration setting indicates success. Zero indicates failure. The GetLastError function does not provide extended error information.

Windows CE Remarks

Windows CE does not support the following nIndex values:

SM_ARRANGE | SM_CXMINIMIZED
SM_CLEANBOOT | SM_CYMINIMIZED
SM_CMETRICS | SM_CXMINSPACING
SM_CMOUSEBUTTONS | SM_CYMINSPACING
SM_CXCURSOR | SM_CXMINTRACK
SM_CYCURSOR | SM_CYMINTRACK
SM_CXDRAG | SM_CXSIZE
SM_CYDRAG | SM_CYSIZE
SM_CXFRAME | SM_CXSIZEFRAME
SM_CYFRAME | SM_CYSIZEFRAME
SM_CXFULLSCREEN | SM_CXSMSIZE
SM_CYFULLSCREEN | SM_CYSMSIZE
SM_CXHTHUMB | SM_CYSMCAPTION
SM_CYKANJIWINDOW | SM_CYVTHUMB
SM_CXMAXIMIZED | SM_DBCSENABLED
SM_CYMAXIMIZED | SM_MENUDROPALIGNMENT
SM_CXMAXTRACK | SM_MIDEASTENABLED
SM_CYMAXTRACK | SM_NETWORK
SM_CXMENUCHECK | SM_PENWINDOWS
SM_CYMENUCHECK | SM_SECURE
SM_CXMENUSIZE | SM_SHOWSOUNDS
SM_CYMENUSIZE | SM_SLOWMACHINE
SM_CXMIN | SM_SWAPBUTTON
SM_CYMIN |

If the Windows CE–based device you are targeting supports a mouse cursor, you can use the SM_CXCURSOR or SM_CYCURSOR values in the nIndex parameter.

Windows CE versions that support mouse cursors include the Iconcurs and Mcursor components rather than the Icon and Cursor components.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetSystemMetrics function.

Remarks

System metrics may vary from display to display.

The SM_ARRANGE setting specifies how the system arranges minimized windows, and consists of a starting position and a direction. The starting position can be one of the following values.

Value
Description
ARW_BOTTOMLEFT | Start at the lower-left corner of the screen (default position).
ARW_BOTTOMRIGHT | Start at the lower-right corner of the screen. Equivalent to ARW_STARTRIGHT.
ARW_HIDE | Hide minimized windows by moving them off the visible area of the screen.
ARW_TOPLEFT | Start at the upper-left corner of the screen. Equivalent to ARV_STARTTOP.
ARW_TOPRIGHT | Start at the upper-right corner of the screen. Equivalent to ARW_STARTTOP | SRW_STARTRIGHT.

The direction in which to arrange can be one of the following values.

Value
Description
ARW_DOWN | Arrange vertically, top to bottom.
ARW_LEFT | Arrange horizontally, left to right.
ARW_RIGHT | Arrange horizontally, right to left.
ARW_UP | Arrange vertically, bottom to top.


GetSystemPaletteEntries

This function retrieves a range of palette entries from the system palette associated with the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

UINT GetSystemPaletteEntries( HDC hdc, UINT iStartIndex, UINT nEntries,
LPPALETTEENTRY lppe);

Parameters

hdc
[in] Handle to the device context (DC).
iStartIndex
[in] Index of the first entry to be retrieved from the system palette.
nEntries
[in] Specifies the number of entries to be retrieved from the system palette.
lppe
[out] Long pointer to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many structures as specified by the nEntries parameter. If this parameter is NULL, the function returns the total number of entries in the palette.

Return Values

The number of entries retrieved from the palette indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

GetSystemPaletteEntries fails if the device associated with hdc does not have a settable palette. Call the GetDeviceCaps function, specifying the RASTERCAPS constant, to determine if the device has a settable palette before calling GetSystemPaletteEntries.

See Also

GetDeviceCaps , GetNearestPaletteIndex


GetSystemPowerStatusEx

This function retrieves the power status of the system. The status indicates whether the system is running on AC or DC power, whether or not the batteries are currently charging, and the remaining life of main and backup batteries. The RAPI version is CeGetSystemPowerStatusEx for versions 2.0 and later.

At a Glance

Header file: | Winbase.h Rapi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetSystemPowerStatusEx(
PSYSTEM_POWER_STATUS_EX pstatus, BOOL fUpdate);

Parameters

pstatus
[out] Pointer to the SYSTEM_POWER_STATUS_EX structure receiving the power status information.
fUpdate
[in] If this Boolean is set to TRUE, GetSystemPowerStatusEx gets the latest information from the device driver, otherwise it retrieves cached information that may be out-of-date by several seconds.

Return Values

This function returns TRUE if successful; otherwise, it returns FALSE.

Remarks

The GetSystemPowerStatusEx function is not supported for emulation.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetSystemPowerStatusEx function.

See Also

SYSTEM_POWER_STATUS_EX


GetTextColor

This function retrieves the current text color for the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF GetTextColor(HDC hdc);

Parameters

hdc
[in] Handle to the device context.

Return Values

The current text color as a COLORREF value indicates success. CLR_INVALID indicates failure.

Remarks

The text color defines the foreground color of characters drawn by using the ExtTextOut function.

See Also

ExtTextOut, SetTextColor


GetTextExtentExPoint

This function retrieves the number of characters in a specified string that will fit within a specified space and fills an array with the text extent for each of those characters. A text extent is the distance between the beginning of the space and a character that will fit in the space.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetTextExtentExPoint(HDC hdc, LPCTSTR lpszStr, int cchString,
int nMaxExtent, LPINT lpnFit, LPINT alpDx, LPSIZE lpSize);

Parameters

hdc
[in] Handle to the device context (DC).
lpszStr
[in] Long pointer to the null-terminated string for which extents are to be retrieved.
cchString
[in] Specifies the number of characters in the string pointed to by the lpszStr parameter.
nMaxExtent
[in] Specifies the maximum allowable width, in logical units, of the formatted string.
lpnFit
[out] Long pointer to an integer to receive a count of the maximum number of characters that will fit in the space specified by the nMaxExtent parameter. When the lpnFit parameter is NULL, the nMaxExtent parameter is ignored.
alpDx
[out] Long pointer to an array of integers to receive partial string extents. Each element in the array gives the distance, in logical units, between the beginning of the string and one of the characters that fits in the space specified by the nMaxExtent parameter. Although this array should have at least as many elements as characters specified by the cchString parameter, the function fills the array with extents only for as many characters as are given by the lpnFit parameter. If alpDx is NULL, the function does not compute partial string widths.
lpSize
[in] Long pointer to a SIZE structure that contains the dimensions of the string, in logical units when the function returns. This value cannot be NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If both the lpnFit and alpDx parameters are NULL, calling the GetTextExtentExPoint function is equivalent to calling the GetTextExtentPoint function.

See Also

SIZE


GetTextExtentPoint

This function computes the width and height of the specified string of text.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL GetTextExtentPoint( HDC hdc, LPCTSTR lpString, int cbString,
LPSIZE lpSize);

Parameters

hdc
[in] Handle to the device context (DC).
lpString
[in] Long pointer to the string of text. The string does not need to be zero-terminated, since cbString specifies the length of the string.
cbString
[in] Specifies the number of characters in the string.
lpSize
[out] Long pointer to a SIZE structure in which the dimensions of the string are to be returned.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The GetTextExtentPoint function uses the currently selected font to compute the dimensions of the string. The width and height, in logical units, are computed without considering any clipping.

Because some devices kern characters, the sum of the extents of the characters in a string may not be equal to the extent of the string.

The calculated string width takes into account the intercharacter spacing set by the SetTextCharacterExtra function.

The GetTextExtentPoint function is identical to the GetTextExtentPoint32 function.

See Also

GetTextExtentPoint32


GetTextExtentPoint32

This function computes the width and height of the specified string of text.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL GetTextExtentPoint32( HDC hdc, LPCTSTR lpString, int cbString, LPSIZE lpSize);

Parameters

hdc
[in] Handle to the device context (DC).
lpString
[in] Long pointer to the string of text. The string does not need to be zero-terminated, since cbString specifies the length of the string.
cbString
[in] Specifies the number of characters in the string.
lpSize
[out] Long pointer to a SIZE structure in which the dimensions of the string are to be returned.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The GetTextExtentPoint32 function uses the currently selected font to compute the dimensions of the string. The width and height, in logical units, are computed without considering any clipping.

Because some devices kern characters, the sum of the extents of the characters in a string may not be equal to the extent of the string.

The calculated string width takes into account the intercharacter spacing set by the SetTextCharacterExtra function.

The GetTextExtentPoint32 function is identical to the GetTextExtentPoint function.

See Also

GetTextExtentPoint


GetTextFace

This function retrieves the typeface name of the font that is selected into the specified device context (DC).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 or later

Syntax

int GetTextFace(HDC hdc, int nCount, LPTSTR lpFaceName);

Parameters

hdc
[in] Handle to the device context (DC).
nCount
[in] Specifies the size, in characters, of the buffer.
lpFaceName
[out] Long pointer to the buffer that is to receive the typeface name. If this parameter is NULL, the function returns the number of characters in the name, including the terminating null character.

Return Values

The number of characters copied to the buffer indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The typeface name is copied as a null-terminated character string.

If the name is longer than the number of characters specified by the nCount parameter, the name is truncated.

See Also

GetTextColor, GetTextMetrics


GetTextMetrics

This function fills the specified buffer with the metrics for the currently selected font.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetTextMetrics(HDC hdc, LPTEXTMETRIC lptm);

Parameters

hdc
[in] Handle to the device context (DC).
lptm
[out] Long pointer to the TEXTMETRIC structure that is to receive the metrics.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

For any given font, the text metric values in Windows CE will not necessarily match the text metric values in Windows-based desktop platforms.

See Also

GetTextFace,TEXTMETRIC


GetUpdateRect

This function retrieves the coordinates of the smallest rectangle that completely encloses the update region of the specified window in client coordinates. If there is no update region, GetUpdateRect retrieves an empty rectangle; it sets all coordinates to zero.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetUpdateRect( HWND hWnd, LPRECT lpRect, BOOL bErase);

Parameters

hWnd
Handle to the window with an update region that is to be retrieved.
lpRect
Long pointer to the RECT structure that receives the coordinates of the enclosing rectangle.

An application can set this parameter to NULL to determine whether an update region exists for the window. If this parameter is NULL, GetUpdateRect returns nonzero if an update region exists, and zero if one does not. This provides a simple and efficient means of determining whether a WM_PAINT message resulted from an invalid area.

bErase
Boolean that specifies whether the background in the update region is to be erased. If this parameter is TRUE and the update region is not empty, GetUpdateRect sends a WM_ERASEBKGND message to the specified window to erase the background.

Return Values

Nonzero indicates that the update region is not empty. Zero indicates that there is no update region.

Windows NT: To get extended error information, call GetLastError.

Remarks

The update rectangle retrieved by the BeginPaint function is identical to that retrieved by GetUpdateRect.

BeginPaint automatically validates the update region, so any call to GetUpdateRect made immediately after the call to BeginPaint retrieves an empty update region.

See Also

BeginPaint, GetUpdateRgn, InvalidateRect, RECT, UpdateWindow, ValidateRect


GetUpdateRgn

This function retrieves the update region of a window by copying it into the specified region. The coordinates of the update region are relative to the upper-left corner of the window; that is, they are client coordinates.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int GetUpdateRgn( HWND hWnd, HRGN hRgn, BOOL bErase);

Parameters

hWnd
Handle to the window with an update region that is to be retrieved.
hRgn
Handle to the region to receive the update region.
bErase
Boolean that specifies whether the window background should be erased and whether nonclient areas of child windows should be drawn. If this parameter is FALSE, no drawing is done.

Return Values

The return value indicates the complexity of the resulting region. COMPLEXREGION indicates that the region consists of more than one rectangle. ERROR indicates that an error occurred. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle.

Windows CE Remarks

The bErase parameter is ignored, the window background is not erased and no drawing is done.

Remarks

The BeginPaint function automatically validates the update region, so any call to GetUpdateRgn made immediately after the call to BeginPaint retrieves an empty update region.

See Also

BeginPaint, GetUpdateRect, UpdateWindow


GetWindow

This function retrieves the handle to a window that has the specified relationship to the specified window. A remote application interface (RAPI) version of this function exists, named CeGetWindow.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND GetWindow( HWND hWnd, UINT uCmd);

Parameters

hWnd
Handle to a window. The window handle retrieved is relative to this window, based on the value of the uCmd parameter.
uCmd
Specifies the relationship between the specified window and the window whose handle is to be retrieved. This parameter can be one of the following values:
Value
Description
GW_CHILD | The retrieved handle identifies the child window at the top of the z-order, if the specified window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the specified window. It does not examine descendant windows.
GW_HWNDFIRST | The retrieved handle identifies the window of the same type that is highest in the z-order. If the specified window is a topmost window, the handle identifies the topmost window that is highest in the z-order. If the specified window is a child window, the handle identifies the sibling window that is highest in the z-order.
GW_HWNDLAST | The retrieved handle identifies the window of the same type that is lowest in the z-order. If the specified window is a topmost window, the handle identifies the topmost window that is lowest in the z-order. If the specified window is a child window, the handle identifies the sibling window that is lowest in the z-order.
GW_HWNDNEXT | The retrieved handle identifies the window below the specified window in the z-order. If the specified window is a topmost window, the handle identifies the topmost window below the specified window. If the specified window is a child window, the handle identifies the sibling window below the specified window.
GW_HWNDPREV | The retrieved handle identifies the window above the specified window in the z-order. If the specified window is a topmost window, the handle identifies the topmost window above the specified window. If the specified window is a child window, the handle identifies the sibling window above the specified window.
GW_OWNER | The retrieved handle identifies the specified window’s owner window, if any. This flag will not retrieve a parent window.

Return Values

A window handle indicates success. NULL indicates that no window exists with the specified relationship to the specified window. To get extended error information, call GetLastError.

Remarks

This function distinguishes between only top-level and child windows. Top-most windows are considered top-level windows.

In Windows CE version 1.0, the GW_OWNER flag value for the uCmd parameter is only supported for dialog boxes.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetWindow function.

See Also

GetActiveWindow


GetWindowDC

This function retrieves the device context (DC) for the entire window, including title bar, menus, and scroll bars.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HDC GetWindowDC( HWND hWnd );

Parameters

hWnd
Handle to the window with a device context that is to be retrieved. If this value is NULL, GetWindowDC retrieves the device context for the entire screen.

Windows 98, Windows NT 5.0 and later: If this parameter is NULL, GetWindowDC retrieves the device context for the primary display monitor.

Return Values

The handle of a device context for the specified window indicates success. NULL indicates an error or an invalid hWnd parameter.

Windows NT: To get extended error information, call GetLastError.

Remarks

GetWindowDC is intended for special painting effects within a window’s nonclient area. Painting in nonclient areas of any window is not recommended.

The GetSystemMetrics function can be used to retrieve the dimensions of various parts of the nonclient area, such as the title bar, menu, and scroll bars.

The GetDC function can be used to retrieve a device context for the entire screen.

After painting is complete, the ReleaseDC function must be called to release the device context. Not releasing the window device context has serious effects on painting requested by applications.

See Also

BeginPaint, GetDC, GetSystemMetrics, ReleaseDC


GetWindowLong

This function retrieves information about the specified window. GetWindowLong also retrieves the 32-bit (long) value at the specified offset into the extra window memory of a window. The RAPI version is CeGetWindowLong for versions 2.0 and later.

At a Glance

Header file: | Winuser.h Rapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG GetWindowLong( HWND hWnd, int nIndex );

Parameters

hWnd
Handle to the window and, indirectly, the class to which the window belongs.
nIndex
Specifies the zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus four; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer. To retrieve any other value, specify one of the following values:
Value
Description
GWL_EXSTYLE | Retrieves the extended window styles.
GWL_STYLE | Retrieves the window styles.
GWL_WNDPROC | Retrieves the address of the window procedure, or a handle representing the address of the window procedure. You must use the CallWindowProc function to call the window procedure.
GWL_HINSTANCE | Retrieves a handle to the application instance.
GWL_HWNDPARENT | Retrieves a handle to the parent window, if any.
GWL_ID | Retrieves the identifier of the window.
GWL_USERDATA | Retrieves the 32-bit value associated with the window. Each window has a corresponding 32-bit value intended for use by the application that created the window.

The following values are also available when the hWnd parameter identifies a dialog box:
Value
Description
DWL_DLGPROC | Retrieves the address of the dialog box procedure, or a handle representing the address of the dialog box procedure. You must use the CallWindowProc function to call the dialog box procedure.
DWL_MSGRESULT | Retrieves the return value of a message processed in the dialog box procedure.
DWL_USER | Retrieves extra information private to the application, such as handles or pointers.

Return Values

The requested 32-bit value indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The nIndex parameter must be a multiple of 4 bytes.

Unaligned access is not supported.

Windows CE does not support the GWL_HINSTANCE and GWL_HWNDPARENT values in the nIndex parameter.

Windows CE version 1.0 also does not support the DWL_DLGPROC and GWL_USERDATA value in the nIndex parameter.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetWindowLong function.

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASSEX structure used with the RegisterClassEx function.

See Also

CallWindowProc, RegisterClass, SetParent, SetWindowLong, WNDCLASS


GetWindowRect

This function retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetWindowRect( HWND hWnd, LPRECT lpRect );

Parameters

hWnd
Handle to the window.
lpRect
Long pointer to a RECT structure that receives the screen coordinates of the upper-left and lower-right corners of the window.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

GetClientRect, RECT


GetWindowText

This function copies the text of the specified window’s title bar—if it has one—into a buffer. If the specified window is a control, the text of the control is copied. The RAPI version is CeGetWindowText for versions 2.0 and later.

At a Glance

Header file: | Winuser.h Rapi.h
Windows CE versions: | 1.0 and later

Syntax

int GetWindowText( HWND hWnd, LPTSTR lpString, int nMaxCount);

Parameters

hWnd
Handle to the window or control containing the text.
lpString
Long pointer to the buffer that will receive the text.
nMaxCount
Specifies the maximum number of characters to copy to the buffer, including the NULL character. If the text exceeds this limit, it is truncated.

Return Values

The length, in characters, of the copied string, not including the terminating null character, indicates success. Zero indicates that the window has no title bar or text, if the title bar is empty, or if the window or control handle is invalid. To get extended error information, call GetLastError.

This function cannot retrieve the text of an edit control in another application.

Remarks

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetWindowText function.

If the target window is owned by the current process, GetWindowText causes a WM_GETTEXT message to be sent to the specified window or control. If the target window is owned by another process and has a caption, GetWindowText retrieves the window caption text. If the window does not have a caption, the return value is a null string.

See Also

GetWindowTextLength, SetWindowText, WM_GETTEXT


GetWindowTextLength

This function retrieves the length, in characters, of the specified window’s title bar text—if the window has a title bar. If the specified window is a control, the function retrieves the length of the text within the control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int GetWindowTextLength( HWND hWnd);

Parameters

hWnd
Handle to the window or control.

Return Values

The length, in characters, of the text indicates success. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section. Zero indicates that the window has no text. To get extended error information, call GetLastError.

Remarks

If the target window is owned by the current process, GetWindowTextLength causes a WM_GETTEXTLENGTH message to be sent to the specified window or control.

Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of DBCS characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. It can also occur when an application uses the ANSI version of GetWindowTextLength with a window whose window procedure is Unicode, or the Unicode version of GetWindowTextLength with a window whose window procedure is ANSI.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, SetWindowText, WM_GETTEXT, WM_GETTEXTLENGTH


GetWindowThreadProcessId

The GetWindowThreadProcessId function retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetWindowThreadProcessId(HWND hWnd,
LPDWORD lpdwProcessId);

Parameters

hWnd
Handle to the window.
lpdwProcessId
Pointer to a 32-bit value that receives the process identifier. If this parameter is not NULL, GetWindowThreadProcessId copies the identifier of the process to the 32-bit value; otherwise, it does not.

Return Values

The return value is the identifier of the thread that created the window.


HideCaret to HwxSetPartial


HideCaret

This function removes the caret from the screen. Hiding a caret does not destroy its current shape or invalidate the insertion point.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL HideCaret(HWND hWnd);

Parameters

hWnd
[in] Handle to the window that owns the caret. If this parameter is NULL, HideCaret searches the current task for the window that owns the caret.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

HideCaret hides the caret only if the specified window owns the caret. If the specified window does not own the caret, HideCaret does nothing and returns FALSE.

Hiding is cumulative. If your application calls HideCaret five times in a row, it must also call ShowCaret five times before the caret is displayed.

See Also

CreateCaret, DestroyCaret, GetCaretPos, SetCaretPos, ShowCaret


HwxALCPriority

This function is called by an application to specify which alphabet code (ALC) values the handwriting recognition engine returns first.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxALCPriority ( HRC hrc, ALC alc);

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.
alc
[in] Alphabet code (ALC) value that describes the character groupings used by the recognizer to prioritize the results of the recognition analysis. It can be one or more of the following values:
Value
Description
ALC_WHITE | Used for a blank or white space.
ALC_LCALPHA | Used for the lowercase alphabet, a through z.
ALC_UCALPHA | Used for the uppercase alphabet, A through Z.
ALC_NUMERIC | Used for the digits 0 through 9.
ALC_PUNC | Used for the set of standard punctuation. It is language-dependent.
ALC_NUMERIC_PUNC | Used for all non-digit characters in numbers, such as the period and the comma.
ALC_MATH | Used for a set of math symbols, such as %, ^, *, (), –, +, {}, <, and /.
ALC_MONETARY | Used for punctuation that appears in local monetary expressions.
ALC_COMMON_SYMBOLS | Signifies commonly used symbols from ALC_PUNC, ALC_NUMERIC_PUNC, ALC_MATH, and ALC_MONETARY.
ALC_OTHER | Signifies other punctuation that is not typically used.
ALC_ASCII | Used for the 7-bit ASCII characters—20 through 7F.
ALC_HIRAGANA | Used for Hiragana characters.
ALC_KATAKANA | Used for Katakana characters.
ALC_KANJI_COMMON | Used for the most commonly used Kanji characters.
ALC_KANJI_RARE | Used for the remaining Kanji characters.
ALC_HANGUL_COMMON | Signifies the commonly used Hangul characters used in Korea.
ALC_HANGUL_RARE | Signifies the remaining Hangul characters used in Korea.
ALC_OEM | Specific to recognizers created by OEMs.

ALC groupings created by combining two or more related ALC basic values are described in the following table.

ALC groupings
Basic ALC values
ALC_ALPHA | ALC_LCALPHA | ALC_UCALPHA
ALC_ALPHANUMERIC | ALC_ALPHA | ALC_NUMERIC
ALC_KANA | ALC_HIRAGANA | ALC_KATAKANA
ALC_KANJI_ALL | ALC_KANJI_COMMON | ALC_KANJI_RARE
ALC_HANGUL_ALL | ALC_HANGUL_COMMON | ALC_HANGUL_RARE
ALC_EXTENDED_SYM | ALC_MATH | ALC_MONETARY | ALC_OTHER
ALC_SYS_MINIMUM | ALC_ALPHANUMERIC | ALC_PUNC | ALC_WHITE
ALC_SYS_DEFAULT | ALC_SYS_MINIMUM | ALC_COMMON_SYMBOLS

These groupings can be combined with each other or with the basic values for various languages, as described in the following table.

Language ALC groupings
ALC groupings
ALC_USA_COMMON | ALC_SYS_DEFAULT
ALC_USA_EXTENDED | ALC_USA_COMMON | ALC_EXTENDED_SYM
ALC_JPN_COMMON | ALC_SYS_DEFAULT | ALC_KANA | ALC_KANJI_COMMON
ALC_JPN_EXTENDED | ALC_JPN_COMMON | ALC_EXTENDED_SYM | ALC_KANJI_RARE
ALC_CHS_COMMON | ALC_SYS_DEFAULT | ALC_KANJI_COMMON
ALC_CHS_EXTENDED | ALC_CHS_COMMON | ALC_EXTENDED_SYM | ALC_KANJI_RARE
ALC_CHT_COMMON | ALC_SYS_DEFAULT | ALC_KANJI_COMMON
ALC_CHT_EXTENDED | ALC_CHT_COMMON | ALC_EXTENDED_SYM | ALC_KANJI_RARE
ALC_KOR_COMMON | ALC_SYS_DEFAULT | ALC_HANGUL_COMMON | ALC_KANJI_COMMON
ALC_KOR_EXTENDED | ALC_KOR_COMMON | ALC_EXTENDED_SYM | ALC_HANGUL_RARE | ALC_KANJI_RARE

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The handwriting recognition engine matches user-drawn characters, or ink, to characters contained in ALCs. The engine then returns these possible matches in a list ordered from most likely match to least likely match. When the HwxALCValid function specifies multiple ALCs, an application can use HwxALCPriority to indicate which ALC has priority in the list of possible matches. For example, specifying ALC_SYS_MINIMUM with a call to HwxALCValid means that the handwriting recognition engine uses three ALCs: ALC_ALPHANUMERIC, ALC_PUNC, and ALC_WHITE. If a user draws a lowercase “j” and a call to HwxPriority gives ALC_ALPHANUMERIC priority, “j” is likely to returned as the best possible match. But, if ALC_PUNC—punctuation symbols—has priority, the semi-colon might be listed before “j” in the list of possible matches.

See Also

HwxALCValid


HwxALCValid

This function defines the set of characters that the character recognition engine can return when it converts ink, which is user-drawn input, to a text string.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxALCValid( HRC hrc, ALC alc);

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.
alc
[in] Alphabet code (ALC) value that describes the character groupings used by the recognizer to evaluate the input handwriting. It can be one or more of the following values:
Value
Description
ALC_WHITE | Used for a blank or white space.
ALC_LCALPHA | Used for the lowercase alphabet, a through z.
ALC_UCALPHA | Used for the uppercase alphabet, A through Z.
ALC_NUMERIC | Used for the digits 0 through 9.
ALC_PUNC | Used for the set of standard punctuation. It is language-dependent.
ALC_NUMERIC_PUNC | Used for all non-digit characters in numbers, such as the period and the comma.
ALC_MATH | Used for a set of math symbols, such as %, ^, *, (), _, +, {}, <, and /.
ALC_MONETARY | Used for punctuation that appears in local monetary expressions.
ALC_COMMON_SYMBOLS | Signifies commonly used symbols from ALC_WHITE, ALC_LCALPHA, ALC_UCALPHA, ALC_NUMERIC, ALC_PUNC, ALC_NUMERIC_PUNC, ALC_MATH, and ALC_MONETARY.
ALC_OTHER | Signifies other punctuation that is not typically used.
ALC_ASCII | Used for the 7-bit ASCII characters—20 through 7F.
ALC_HIRAGANA | Used for Hiragana characters.
ALC_KATAKANA | Used for Katakana characters.
ALC_KANJI_COMMON | Used for the most commonly used Kanji characters (JPN).
ALC_KANJI_RARE | Used for the remaining Kanji characters (JPN).
ALC_HANGUL_COMMON | Signifies the commonly used Hangul characters used in Korea.
ALC_HANGUL_RARE | Signifies the remaining Hangul characters used in Korea.
ALC_OEM | Specific to recognizers created by OEMs.

ALC groupings created by combining two or more related ALC basic values are described in the following table.

ALC groupings
Basic ALC values
ALC_ALPHA | ALC_LCALPHA | ALC_UCALPHA
ALC_ALPHANUMERIC | ALC_ALPHA | ALC_NUMERIC
ALC_KANA | ALC_HIRAGANA | ALC_KATAKANA
ALC_KANJI_ALL | ALC_KANJI_COMMON | ALC_KANJI_RARE
ALC_HANGUL_ALL | ALC_HANGUL_COMMON | ALC_HANGUL_RARE
ALC_EXTENDED_SYM | ALC_MATH | ALC_MONETARY | ALC_OTHER
ALC_SYS_MINIMUM | ALC_ALPHANUMERIC | ALC_PUNC | ALC_WHITE
ALC_SYS_DEFAULT | ALC_SYS_MINIMUM | ALC_COMMON_SYMBOLS

These groupings can be combined with each other or with the basic values for various languages, as described in the following table.

Language ALC groupings
ALC groupings
ALC_USA_COMMON | ALC_SYS_DEFAULT
ALC_USA_EXTENDED | ALC_USA_COMMON | ALC_EXTENDED_SYM
ALC_JPN_COMMON | ALC_SYS_DEFAULT | ALC_KANA | ALC_KANJI_COMMON
ALC_JPN_EXTENDED | ALC_JPN_COMMON | ALC_EXTENDED_SYM | ALC_KANJI_RARE
ALC_CHS_COMMON | ALC_SYS_DEFAULT | ALC_KANJI_COMMON
ALC_CHS_EXTENDED | ALC_CHS_COMMON | ALC_EXTENDED_SYM | ALC_KANJI_RARE
ALC_CHT_COMMON | ALC_SYS_DEFAULT | ALC_KANJI_COMMON
ALC_CHT_EXTENDED | ALC_CHT_COMMON | ALC_EXTENDED_SYM | ALC_KANJI_RARE
ALC_KOR_COMMON | ALC_SYS_DEFAULT | ALC_HANGUL_COMMON | ALC_KANJI_COMMON
ALC_KOR_EXTENDED | ALC_KOR_COMMON | ALC_EXTENDED_SYM | ALC_HANGUL_RARE | ALC_KANJI_RARE

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

This function lets an application restrict or expand the amount of characters that the recognition engine uses when it translates user-drawn characters. For example, if an application is expecting a telephone number as input from a user, the application can call HwxALCValid to specify the ALC_NUMERIC character range. Specifying a limited character range prevents the recognition engine from interpreting a user-drawn zero as an uppercase “O.”

When HwxALCValid specifies multiple ALCs, an application can use the HwxALCPriority function to indicate the first ALC to use during the handwriting recognition process.

HwxALCValid fails when a specified ALC is not loaded on the device.

See Also

HwxALCPriority


HwxConfig

This function initializes the handwriting recognition dynamic-link library (DLL).

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxConfig(void);

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

This function is called only once by an application to initialize the DLL. Call HwxConfig before calling other handwriting functions, all of which fail when the DLL is not initialized.


HwxCreate

This function creates an handwriting recognition context (HRC) object. This object is used by a handwriting recognition engine to obtain ink—information that describes what the user is drawing—and to store the results of recognition processing.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

HRC HwxCreate( HRC hrc );

Parameters

hrc
[in] Handle to an existing handwriting recognition context (HRC) object that provides settings for the recognition context being created. If it is NULL, then default settings are used.

Return Values

The handle to the newly created HRC object indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

To efficiently process handwriting, create a master HRC before collecting any ink. This master HRC is a template that contains all the information that the handwriting recognition engine needs to translate user input. First call HwxCreate, setting the hrc parameter to NULL. Call HwxSetGuide to specify a HWXGUIDE structure, and call HwxALCValid to specify an alphabet code (ALC) grouping. For each character or group of characters that an application collects from a user, copy the master HRC to another HRC for collecting and processing ink. After all of the ink in an HRC is processed, the HRC has served its purpose, so remove it with the HwxDestroy function. For the next collection of user input, copy the master HRC again, and so on.

The hrc parameter is used to copy settings from an old HRC into a new HRC object. These settings include alphabet code (ALC) groupings , the HWXGUIDE structure, the character previously processed, and ink that may be in the old context.

See Also

HwxALCValid, HwxDestroy, HWXGUIDE, HwxSetGuide


HwxDestroy

This function destroys a handwriting recognition context (HRC) object.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxDestroy( HRC hrc );

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The handwriting recognition engine uses an HRC to process each character that a user draws. Typically, before an application collects user input, it calls the HwxCreate function to create a master HRC. Whenever a new HRC is needed to interpret another character, an application copies the master HRC to an HRC used for processing. To conserve system resources, use HwxDestroy to remove each HRC after calling HwxGetResults.

After HwxDestroy returns TRUE, the handle hrc is no longer valid. An application should set hrc to NULL to ensure it is not inadvertently used again.

See Also

HwxCreate


HwxEndInput

This function notifies the handwriting recognition engine that no more ink should be added to the handwriting recognition context (HRC) object.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxEndInput ( HRC hrc );

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object that no longer receives ink.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

An application calls this function after using the HwxInput function to add the last ink to the HRC. The next call to HwxProcess completes recognition on all the input. Any calls to HwxInput on this HRC fail after HwxEndInput is called.

See Also

HwxInput, HwxProcess


HwxGetResults

This function retrieves the handwriting recognition engine results from the specified handwriting recognition context (HRC).

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

INT32 HwxGetResults ( HRC hrc, UINT cAlt, UINT iFirst, UINT cBoxRes,
HWXRESULTS * rgBoxResults );

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC).
cAlt
[in] Number of alternate results expected in the HWXRESULTS structure. If this parameter is 0, the function returns 0.
iFirst
[in] Index of the first character to return.
cBoxRes
[in] Number of characters to return.
rgBoxResults
[out] Array of ranked lists, one list per returned character, that specify results.

Return Values

The number of characters actually returned indicates success. HRCR_ERROR indicates failure.

Remarks

Before calling HwxGetResults, an application can call the HwxResultsAvailable function to find out how many characters are available from the handwriting recognition engine.

When the HWXGUIDE structure defines multiple input boxes, HwxGetResults provides character alternatives on a per-box basis in one call. The rgBoxResults buffer that was passed in contains the results for the returned characters. While the user is still entering characters in the current HRC, an application can use this function to display processed characters. An application can call this function repeatedly.

The following code example shows how to simultaneously retrieve results for 10 input boxes, with five alternatives per box.

HANDLE hMem = GlobalAlloc(GHND, 10 * (sizeof(HWXRESULTS) + (5-1) * sizeof(WCHAR)) );
HWXRESULTS * rgBoxR = (HWXRESULTS * ) GlobalLock( hMem);

do
{
    int iRes = HwxGetResults ( hrc, 5, indx, 10, rgBoxR);
    .
    .                // check for errors and use rgBoxR
    .
    indx += (UINT) iRes;
}
while (iRes == 10);

See Also

HWXRESULTS,HwxResultsAvailable


HwxInput

This function adds stroke information to the handwriting recognition context (HRC).

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxInput ( HRC hrc, POINT * lppnt, UINT upoints,
DWORD timestamp);

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.
lppnt
[in] Long pointer to an address of an array of POINT structures. The information in the POINT structures should be scaled to match the HWXGUIDE structure.
upoints
[in] Number of POINT structures.
timestamp
[in] Time stamp when a device, such as a stylus, started adding information to the input box. The time stamp should be taken directly from the MSG structure for the stylus down event.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

As a user draws a character, an application calls this function to add user input, or ink, to the HRC object one stroke at a time. A stroke consists of stylus down, stylus movement, and stylus lift. HwxInput takes the array of points, the count of the points, and the time stamp of the first stylus event in the stroke and adds it to the HRC object. When an application determines that there is no more ink to receive for an HRC, it calls the HwxEndInput function.

See Also

HwxEndInput, HWXGUIDE, MSG, POINT


HwxProcess

This function signals the recognizer to analyze the information in the specified handwriting recognition context (HRC) object.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxProcess ( HRC hrc );

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object to be analyzed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

This function processes the ink that has been received by the HRC object. Full recognition occurs only after HwxEndInput is called. The application must then call HwxGetResults to obtain recognition results.

There is no support for timeouts.See Also

HwxEndInput, HwxGetResults


HwxResultsAvailable

This function returns the number of characters that have been processed by the handwriting recognition engine and are available for HwxGetResults to retrieve.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

INT HwxResultsAvailable ( HRC hrc );

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.

Return Values

The number of characters in the HRC for HwxGetResults to retrieve indicates success. A value of –1 indicates an error.

If the function fails, use GetLastError for error information.

Remarks

With this function, an application can check the progress of the handwriting recognition engine and decide when to retrieve the results with HwxGetResults and display them to the user.

See Also

HwxGetResults


HwxSetAbort

This function sets an address that the handwriting recognition engine checks to determine if more user input, or ink, is available. If the address, which is the number of stokes collected for a character, indicates more ink is available, the handwriting recognition engine aborts. It can then be called again to include the new ink in its processing. If the stroke counter indicates that no new ink is available, the handwriting recognition engine continues processing.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxSetAbort( HRC hrc, UINT * pnumstrokes );

Parameters

hrc
[in] Handle of the handwriting recognition context (HRC) object.
pnumstrokes
[in] Pointer to the number of strokes currently in the handwriting recognition context (HRC). A stroke consists of stylus down, stylus movement, and stylus lift.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Use this function after a call to the HwxSetPartial function. Partial recognition processing works best in a multithreaded operating environment. This enables a single application process to have one thread collecting user input, or ink, and another thread processing ink, with both threads sharing the same memory address space. The thread that processes ink, or the recognition thread, uses the address pointed to by pnumstrokes as a signal to stop recognition processing when the collection thread has more ink for the recognition thread to work with. If the contents of that address do not match the number of strokes that the handwriting recognition engine—the recognition thread—is currently processing, then processing stops As long as pnumstrokes matches the number of strokes that the handwriting recognition engine is processing, processing continues.

To resume processing after an abort, the recognition thread calls the HwxProcess function.

Two stroke counters are maintained for the current character or glyph. One is in your application and the other is an internal stroke count. The application counter must be incremented when the stylus touches the input box, because it is starting a new stroke. When the stroke is done—that is, when the stylus is raised from the input box—HwxInput is called. HwxInput adds the stroke information to the character or glyph data and increments the internal stroke count for the character or glyph. While the user is putting the stroke information in the input box, the two counters are different..

Set pnumstrokes to point to the application stroke count. When HwxSetPartial has been called for this character or glyph and there is a new stroke in the input box, calling HwxSetAbort causes the partial recognition process to stop. The application then includes the new data in the information it is using for recognition.

See Also

HwxInput, HwxProcess, HwxSetPartial


HwxSetContext

This function specifies to the handwriting recognition context (HRC) which character the user previously entered. Using this character, the handwriting recognition engine can more accurately determine the character it is currently processing.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxSetContext ( HRC hrc, WCHAR wContext);

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.
wContext
[in] Unicode value of the character input by the user prior to the character that is processed in hrc. If this parameter is 0, the recognition engine does not use context information when identifying the character.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Call this function before calling the HwxProcess function. If HwxSetContext is not called, the handwriting recognition engine does not use context information to determine the character. Having context information greatly improves the performance of the handwriting recognition engine. Without context information, for example, it is difficult for the handwriting recognition engine to distinguish a lowercase “l” from the numeral one (“1”).

See Also

HwxProcess


HwxSetGuide

This function points to a structure that specifies the size and position on a screen of input boxes, which collect characters drawn by a user.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxSetGuide ( HRC hrc, HWXGUIDE * lpGuide );

Parameters

hrc
[in] Handle to the handwriting recognition context (HRC) object.
lpGuide
[in] Long pointer to a HWXGUIDE structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Call HwxSetGuide after the HwxCreate function and before accepting user input to the HRC with calls to the HwxInput function. The handwriting recognition engine requires that an application specify a HWXGUIDE structure for HRC objects.

The HWXGUIDE structure can define one input area, or box, or it can define many input areas. When the guide contains multiple input boxes, HwxGetResults returns results for multiple characters.

See Also

HwxCreate, HwxGetResults, HWXGUIDE,HwxInput


HwxSetPartial

This function enables partial recognition for the handwriting recognition engine.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

BOOL HwxSetPartial ( HRC hrc, UINT urecog);

Parameters

hrc
[in] Handle for the handwriting recognition context (HRC) object.
urecog
[in] Value for the partial recognition parameter. It is one of the following values:
Value
Description
HWX_PARTIAL_ALL | All strokes are input before recognition occurs, effectively turning off partial recognition.
HWX_PARTIAL_ORDER | Partial recognition processing is based on the assumption that first strokes entered by the user are the beginning of the character, and the remaining strokes are drawn in their correct order.
HWX_PARTIAL_FREE | Partial recognition processing is based on the assumption that the user may draw the character strokes in random order.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

When an application enables partial recognition, an application makes multiple calls to HwxProcess for a single character. When partial recognition is not enabled, an application calls HwxProcess once after an application collects all user input, or ink, for a character.

Use HwxSetPartial to enable partial recognition before calling HwxInput and HwxProcess to process ink.

Partial recognition enables the handwriting recognition engine to return choices even when the user incorrectly or partially writes a character or glyph. This benefits the user, who can enter complex characters without having to remember the exact order or number of necessary strokes. Partial recognition is available for processing complex characters, such as those used in the Japanese, Chinese, and Korean languages. For languages that consist of simple characters, such as European languages, partial recognition is not available.

A complex character is made up of many strokes. A stroke consists of three events: stylus down on the input panel, stylus movement, and stylus up. When a user starts drawing the first strokes of a complex character and partial recognition is enabled, an application calls HwxInput to supply ink to the HRC. A call to HwxProcess signals the handwriting recognition engine to start processing ink. An application can then call HwxResultsAvailable to see if the recognition engine has a possible match for the character. If results are available, an application calls HwxGetResults and displays the result to the user. The user can confirm the character and begin drawing the next character, or continue drawing the current character until it is correctly identified by the recognition engine.

Partial recognition works best in a multithreaded operating environment. This enables a single application process to have one thread collecting ink and another thread processing ink, with both threads sharing the same memory address space. When the collection thread has more ink for the handwriting recognition engine, it can use HwxSetAbort to signal the thread that is processing ink to stop recognition processing. After the additional information has been received and HwxPartial has been used to assess the character, the recognition thread calls HwxProcess to resume processing.

See Also

HwxGetResults, HwxInput, HwxProcess, HwxResultsAvailable, HwxSetAbort


ImageList_Add

This function adds an image or images to an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

int WINAPI ImageList_Add(HIMAGELIST himl, HBITMAP hbmImage, HBITMAP hbmMask);

Parameters

himl
[in] Handle to the image list.
hbmImage
[in] Handle to the bitmap that contains the image or images. The number of images is inferred from the width of the bitmap.
hbmMask
[in] Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Values

The index of the first new image indicates success. –1 indicates failure.

Remarks

The ImageList_Add function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

See Also

CreateBitmap, CreateDIBSection, ImageList_Create, ImageList_Remove


ImageList_AddMasked

This function adds an image or images to an image list, generating a mask from the specified bitmap.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

int WINAPI ImageList_AddMasked(HIMAGELIST himl,
HBITMAP hbmImage, COLORREF crMask);

Parameters

himl
[in] Handle to the image list.
hbmImage
[in] Handle to the bitmap that contains one or more images. The number of images is inferred from the width of the bitmap.
crMask
[in] Color used to generate the mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to 1.

Return Values

The index of the first new image indicates success. –1 indicates failure.

Remarks

The ImageList_AddMasked function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and crMask after the function returns.

See Also

COLORREF, CreateBitmap, ImageList_Create


ImageList_BeginDrag

This function begins dragging an image.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_BeginDrag(HIMAGELIST himlTrack, int iTrack, int dxHotspot, int dyHotspot);

Parameters

himlTrack
[in] Handle to the image list.
iTrack
[in] Index of the image to drag.
dxHotspot and dyHotspot
[in] Specifies the location of the drag position relative to the upper-left corner of the image.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

This function creates a temporary image list that is used for dragging. In response to subsequent WM_MOUSEMOVE messages, you can move the drag image by using the ImageList_DragMove function. To end the drag operation, you can use the ImageList_EndDrag function.

See Also

ImageList_GetDragImage


ImageList_Copy

This function copies images within a specified image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ImageList_Copy(HIMAGELIST himlDst, int iDst,
HIMAGELIST himlSrc, int iSrc, UINT uFlags);

Parameters

himlDst and himlSrc
[in] Handle to an image list that is the target of the copy operation. Both parameters must be identical.
iDst
[in] Zero-based index of the image to be used as the destination of the copy operation.
iSrc
[in] Zero-based index of the image to be used as the source of the copy operation.
uFlags
[in] Bit flag value that specifies the type of copy operation to be made. This parameter can be one of the following values:
Value
Description
ILCF_MOVE | The source image is copied to the destination image’s index. This operation results in multiple instances of a given image.
ILCF_SWAP | The source and destination images exchange positions within the image list.

Return Values

Nonzero indicates success. Zero indicates failure.


ImageList_Create

This function creates a new image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HIMAGELIST WINAPI ImageList_Create(int cx, int cy, UINT flags,
int cInitial, int cGrow);

Parameters

cx
[in] Width, in pixels, of each image.
cy
[in] Height, in pixels, of each image.
flags
[in] Set of bit flags that specify the type of image list to create. This parameter can be a combination of the following values, but it can include only one of the ILC_COLOR values.
Value
Description
ILC_COLOR | Use the default behavior if none of the other ILC_COLOR* flags is specified. Typically, the default is ILC_COLOR4, but for older display drivers, the default is ILC_COLORDDB.
ILC_COLORDDB | Use a device-dependent bitmap.
ILC_MASK | Use a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap.

cInitial
[in] Number of images that the image list initially contains.
cGrow
[in] Number of images by which the image list can grow when the system needs to make room for new images. This parameter represents the number of new images that the resized image list can contain.

Return Values

The handle to the image list indicates success. NULL indicates failure.


ImageList_Destroy

This function destroys an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_Destroy(HIMAGELIST himl);

Parameters

himl
[in] Handle to the image list to destroy.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_GetDragImage, ImageList_LoadBitmap, ImageList_LoadImage, ImageList_Merge


ImageList_DragEnter

This function locks updates to the specified window during a drag operation and displays the drag image at the specified position within the window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_DragEnter(HWND hwndLock, int x, int y);

Parameters

hwndLock
[in] Handle to the window that owns the drag image.
x
[in] Specifies the x-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.
y
[in] Specifies the y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_DragLeave


ImageList_DragLeave

This function unlocks the specified window and hides the drag image, allowing the window to be updated.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_DragLeave(HWND hwndLock);

Parameters

hwndLock
[in] Handle to the window that owns the drag image.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_DragEnter, ImageList_EndDrag


ImageList_DragMove

This function moves the image that is being dragged during a drag-and-drop operation. ImageList_DragMove is typically called in response to a WM_MOUSEMOVE message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_DragMove(int x, int y);

Parameters

x
[in] Specifies the x-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.
y
[in] Specifies the y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.


ImageList_DragShowNolock

This function shows or hides the image being dragged.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_DragShowNolock(BOOL fShow);

Parameters

fShow
[in] Boolean that specifies whether to show or hide the image being dragged. Specify TRUE to show the image or FALSE to hide the image.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_BeginDrag


ImageList_Draw

This function draws an image list item in the specified device context (DC).

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_Draw(HIMAGELIST himl, int i,
HDC hdcDst, int x, int y, UINT fStyle);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image to draw.
hdcDst
[in] Handle to the destination device context.
x
[in] Specifies the x-coordinate at which to draw within the specified device context.
y
[in] Specifies the y-coordinate at which to draw within the specified device context.
fStyle
[in] Specifies the drawing style and, optionally, the overlay image. For information about specifying an overlay image index, see the comments section at the end of this topic. This parameter can be a combination of an overlay image index and one or more of the following values:
Value
Description
ILD_BLEND25, ILD_FOCUS | Draws the image, blending 25 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_BLEND50, ILD_SELECTED, ILD_BLEND | Draws the image, blending 50 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_MASK | Draws the mask.
ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

An overlay image is drawn transparently over the primary image specified in the i parameter. To specify an overlay image in the fStyle parameter, use the INDEXTOOVERLAYMASK macro to shift the one-based index of the overlay image. Use the OR operator to logically combine the return value of the macro with the drawing style flags specified in the fStyle parameter. You must first specify this image as an overlay image by using the ImageList_SetOverlayImage function.

See Also

ImageList_DrawEx


ImageList_DrawEx

This function draws an image list item in the specified device context (DC). ImageList_DrawEx uses the specified drawing style and blends the image with the specified color.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_DrawEx(HIMAGELIST himl, int i,
HDC hdcDst, int x, int y, int dx, int dy, COLORREF rgbBk,
COLORREF rgbFg, UINT fStyle);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image to draw.
hdcDst
[in] Handle to the destination device context.
x
[in] Specifies the x-coordinate at which to draw within the specified device context.
y
[in] Specifies the y-coordinate at which to draw within the specified device context.
dx
[in] Specifies the width of the portion of the image to draw relative to the upper-left corner of the image. If dx and dy are zero, the function draws the entire image. The function does not ensure that the parameters are valid.
dy
[in] Specifies the height of the portion of the image to draw, relative to the upper-left corner of the image. If dx and dy are zero, the function draws the entire image. The function does not ensure that the parameters are valid.
rgbBk
[in] Background color of the image. This parameter can be an application-defined RGB value or one of the following values:
Value
Description
CLR_NONE | No background color. The image is drawn transparently.
CLR_DEFAULT | Default background color. The image is drawn using the background color of the image list.

This parameter is used only if the image list identified by himl was created with the ILC_MASK value.

rgbFg
[in] Foreground color of the image. This parameter can be an application-defined RGB value or one of the following values:
Value
Description
CLR_NONE | No blend color. The image is blended with the color of the destination device context.
CLR_DEFAULT | Default foreground color. The image is drawn using the system highlight color as the foreground color.

This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 value.

fStyle
[in] Specifies the drawing style and, optionally, the overlay image. For information about specifying an overlay image index, see the comments section at the end of this topic. This parameter can be a combination of an overlay image index and one or more of the following values:
Value
Description
ILD_BLEND25, ILD_FOCUS | Draws the image, blending 25 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_BLEND50, ILD_SELECTED, ILD_BLEND | Draws the image, blending 50 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_MASK | Draws the mask.
ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

An overlay image is drawn transparently over the primary image specified in the i parameter. To specify an overlay image in the fStyle parameter, use the INDEXTOOVERLAYMASK macro to shift the one-based index of the overlay image. Use the OR operator to logically combine the return value of the macro with the drawing style flags specified in the fStyle parameter. You must first specify this image as an overlay image by using the ImageList_SetOverlayImage function.

See Also

ImageList_Draw, COLORREF


ImageList_DrawIndirect

This function draws an image list image based on an IMAGELISTDRAWPARAMS structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ImageList_DrawIndirect(IMAGELISTDRAWPARAMS* pimldp);

Parameters

pimldp
[in] Pointer to an IMAGELISTDRAWPARAMS structure that contains information about the draw operation.

Return Values

Nonzero indicates success. Zero indicates failure.


ImageList_Duplicate

This function creates a duplicate of an existing image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HIMAGELIST ImageList_Duplicate(HIMAGELIST himl);

Parameters

himl
[in] Handle to the image list to be duplicated. All information contained in the original image list is copied to the new image list.

Return Values

The handle to the new duplicate image list indicates success. NULL indicates failure.

Remarks

The ImageList_Duplicate function is not supported for emulation.


ImageList_EndDrag

This function ends a drag operation.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_EndDrag(void);

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_BeginDrag


ImageList_GetBkColor

This function retrieves the current background color for an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF WINAPI ImageList_GetBkColor(HIMAGELIST himl);

Parameters

himl
[in] Handle to the image list.

Return Values

The background color indicates success. NULL indicates failure.

See Also

ImageList_SetBkColor


ImageList_GetDragImage

This function retrieves the temporary image list that is used for the drag image. ImageList_GetDragImage also retrieves the current drag position and the offset of the drag image relative to the drag position.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HIMAGELIST WINAPI ImageList_GetDragImage(POINT FAR* ppt, POINT FAR* pptHotspot);

Parameters

ppt
[out] Pointer to the pointer to a POINT structure that receives the current drag position. Can be NULL.
pptHotspot
[out] Pointer to the pointer to a POINT structure that receives the offset of the drag image relative to the drag position. Can be NULL.

Return Values

The handle to the image list indicates success. NULL indicates failure.

Remarks

The temporary image list is destroyed when the ImageList_EngDrag function is called. To begin a drag operation, use the ImageListBeginDrag function.


ImageList_GetIcon

This function creates an icon from an image and mask in an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HICON WINAPI ImageList_GetIcon(HIMAGELIST himl, int i,
UINT flags);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image.
flags
[in] Combination of flags that specify the drawing style. For a list of values, see the description of the ImageList_Draw function.

Return Values

The handle to the icon indicates success. NULL indicates failure.

Remarks

It is the responsibility of the calling application to destroy the icon returned from this function using the DestroyIcon function.

You can only use the ImageList_GetIcon function to create an icon, not a cursor.

See Also

ImageList_Draw, ImageList_ExtractIcon


ImageList_GetIconSize

This function retrieves the dimensions of images in an image list. All images in an image list have the same dimensions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_GetIconSize(HIMAGELIST himl, int FAR *cx, int FAR *cy);

Parameters

himl
[in] Handle to the image list.
cx
[in] Address of an integer variable that receives the width, in pixels, of each image.
cy
[in] Address of an integer variable that receives the height, in pixels, of each image.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_SetIconSize, ImageList_GetIcon


ImageList_GetImageCount

This function retrieves the number of images in an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

Int WINAPI ImageList_GetImageCount(HIMAGELIST himl);

Parameters

himl
[in] Handle to the image list.

Return Values

The number of images indicates success. NULL indicates failure.

See Also

ImageList_Create


ImageList_GetImageInfo

This function retrieves information about an image.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_GetImageInfo(HIMAGELIST himl, int i, IMAGEINFO FAR* pImageInfo);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image.
pImageInfo
[out] Pointer to an IMAGEINFO structure that receives information about the image. The information in this structure can be used to directly manipulate the bitmaps for the image.

Return Values

Nonzero indicates success. Zero indicates failure.


ImageList_LoadImage

This function creates an image list from the specified bitmap or icon resource.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HIMAGELIST WINAPI ImageList_LoadImage(HINSTANCE hi, LPCSTR lpbmp, int cx, int cGrow, COLORREF crMask, UINT uType,
UINT uFlags);

Parameters

hi
[in] Handle to the instance of an application or DLL that contains an image.
lpbmp
[in] Long pointer to the image to load.

If the uFlags parameter includes LR_LOADFROMFILE, lpbmp is the address of a null-terminated string that names the file containing the image to load.

If the hi parameter is non-NULL and LR_LOADFROMFILE is not specified, lpbmp is the address of a null-terminated string that contains the name of the image resource in the hi module.

If hi is NULL and LR_LOADFROMFILE is not specified, the low-order word of this parameter must be the identifier of an OEM image to load. To create this value, use the MAKEINTRESOURCE macro with one of the OEM image identifiers defined in Winuser.h. These identifiers have the following prefixes:

  • OBM_ for OEM bitmaps
  • OIC_ for OEM icons
cx
[in] Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified resource.
cGrow
[in] Number of images by which the image list can grow when the system needs to make room for new images. This parameter represents the number of new images that the resized image list can contain.
crMask
[in] Color used to generate a mask. Each pixel of this color in the specified bitmap or icon is changed to black, and the corresponding bit in the mask is set to 1. If this parameter is the CLR_NONE value, no mask is generated. If this parameter is the CLR_DEFAULT value, the color of the pixel at the upper-left corner of the image is treated as the mask color.
uType
[in] Flag that specifies the type of image to load. This parameter can be one of the following values:
Value
Description
IMAGE_BITMAP | Loads a bitmap.
IMAGE_ICON | Loads an icon.

uFlags
[in] Unsupported; set to 0.

Return Values

The handle to the image list indicates success. NULL indicates failure.

Remarks

You can only use this function with icons, not cursors.

See Also

ImageList_LoadBitmap


ImageList_Merge

This function creates a new image by combining two existing images. ImageList_Merge also creates a new image list to store the image.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HIMAGELIST WINAPI ImageList_Merge(HIMAGELIST himl1,
int i1, HIMAGELIST himl2, int i2, int dx, int dy);

Parameters

himl1
[in] Handle to the first image list.
i1
[in] Index of the first existing image.
himl2
[in] Handle to the second image list.
i2
[in] Index of the second existing image.
dx and dy
[in] Offset of the second image relative to the first image.

Return Values

The handle to the new image list indicates success. NULL indicates failure.

Remarks

The new image consists of the second existing image drawn transparently over the first. The mask for the new image is the result of performing a logical OR operation on the masks of the two existing images.

See Also

ImageList_Create


ImageList_Remove

This function removes an image from an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_Remove(HIMAGELIST himl, int i);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image to remove. If this parameter is –1, the function removes all images.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

When an image is removed, the indexes of the remaining images are adjusted so that the image indexes always range from zero to one less than the number of images in the image list. For example, if you remove the image at index 0, then image 1 becomes image 0, image 2 becomes image 1, and so on.

See Also

ImageList_RemoveAll


ImageList_Replace

This function replaces an image in an image list with a new image.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_Replace(HIMAGELIST himl, int i,
HBITMAP hbmImage, HBITMAP hbmMask);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image to replace.
hbmImage
[in] Handle to the bitmap that contains the image.
hbmMask
[in] Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

The ImageList_Replace function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.


ImageList_ReplaceIcon

This function replaces an image with an icon.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

int WINAPI ImageList_ReplaceIcon(HIMAGELIST himl, int i,
HICON hicon);

Parameters

himl
[in] Handle to the image list.
i
[in] Index of the image to replace. If i is –1, the function appends the image to the end of the list.
hicon
[in] Handle to the icon that contains the bitmap and mask for the new image.

Return Values

The index of the image indicates success. –1 indicates failure.

Remarks

Because the system does not save hicon, you can destroy it after the function returns if the icon was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

You can only use the ImageList_ReplaceIcon function with icons, not cursors.

See Also

ImageList_Replace


ImageList_SetBkColor

This function sets the background color for an image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF WINAPI ImageList_SetBkColor(HIMAGELIST himl,
COLORREF clrBk);

Parameters

himl
[in] Handle to the image list.
clrBk
[in] Background color to set. This parameter can be the CLR_NONE value; in that case, images are drawn transparently using the mask.

Return Values

The previous background color indicates success. CLR_NONE indicates failure.


ImageList_SetDragCursorImage

This function creates a new drag image by combining the specified image with the current drag image.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_SetDragCursorImage(HIMAGELIST himlDrag,
int iDrag, int dxHotspot, int dyHotspot);

Parameters

himlDrag
[in] Handle to the image list that contains the new image to combine with the drag image.
iDrag
[in] Index of the new image to combine with the drag image.
dxHotspot and dyHotspot
[in] Specifies the position of the hot spot within the new image.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_EndDrag, ImageList_BeginDrag


ImageList_SetIconSize

This function sets the dimensions of images in an image list and removes all images from the list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_SetIconSize(HIMAGELIST himl, int cx, int cy);

Parameters

himl
[in] Handle to the image list.
cx
[in] Width, in pixels, of the images in the image list. All images in an image list have the same dimensions.
cy
[in] Height, in pixels, of the images in the image list. All images in an image list have the same dimensions.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_GetIconSize


ImageList_SetImageCount

This function resizes an existing image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ImageList_SetImageCount(HIMAGELIST himl, UINT uNewCount);

Parameters

himl
[in] Handle to the image list that is resized.
uNewCount
[in] Value specifying the new size of the image list.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

If you expand an image list using the ImageList_SetImageCount function, you must add new images by using the ImageList_Replace function. If you do not add valid images at the new indexes, draw operations that use the new indexes will be unpredictable.

If you decrease the size of an image list by using this function, the truncated images are freed.


ImageList_SetOverlayImage

This function adds a specified image to the list of images to be used as overlay masks. An image list can have up to four overlay masks. The function assigns an overlay mask index to the specified image.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI ImageList_SetOverlayImage(HIMAGELIST himl,
int iImage, int iOverlay);

Parameters

himl
[in] Handle to the image list.
iImage
[in] Zero-based index of an image in the himl image list. This index identifies the image to use as an overlay mask.
iOverlay
[in] One-based index of the overlay mask.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

An overlay mask is an image drawn transparently over another image. To draw an overlay mask over an image, call the ImageList_Draw or ImageList_DrawEx function. The fStyle parameter of these functions can use the INDEXTOOVERLAYMASK macro to specify an overlay mask index.


ImmAssociateContext

This function associates the specified input context with the specified window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

HIMC ImmAssociateContext(HWND hWnd, HIMC hIMC);

Parameters

hWnd
[in] Handle to the window to be associated with the input context.
hIMC
[in] Handle to the input context.

Return Values

The handle to the input context previously associated with the window indicates success.

Remarks

If an application associates an input context with a window, the application must remove that association before destroying the input context. One way to do this is to save and reassociate the handle to the default input context with the window.

If the hIMC parameter is NULL, the ImmAssociateContext function removes any association the window may have with an input context. By default, the system associates the default input context with each window as it is created.

An application can specify only the default input context or NULL.


ImmAssociateContextEx

This function changes the association between the input method context and the specified window or its children.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmAssociateContextEx( HWND hWnd, HINC hIMC,
DWORD dwFlags );

Parameters

hWnd
[in] Handle to the window to be associated with the input context.
hIMC
[in] Handle to the input method context.
dwFlags
[in] Specifies the type of association between the window and the input method context. This parameter can be the following values:
Value
Description
IACE_CHILDREN | Associate the input method context to the child windows of hWnd only.
IACE_DEFAULT | Restore the window’s default input method context.
IACE_IGNORENOCONTEXT | Do not associate the input method context with windows that are not associated with any input method context.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the application calls this function with IACE_CHILDREN, the system associates the specified input method context with child windows of hWnd. It associates the input method context only with child windows of the thread that created hWnd. Any child window that is created after this function has been called will not be affected. Instead, the default input method context will be associated with it.

If the application calls this function with IACE_DEFAULT, the system restores the window’s default input method context. In this case, the hIMC parameter is ignored.


ImmConfigureIME

This function displays the configuration dialog box for the IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmConfigureIME( HKL hKL, HWND hWnd, DWORD dwMode,
LPVOID lpdata);

Parameters

hKL
[in] Handle to the keyboard layout.
hWnd
[in] Handle to the parent window for the dialog box.
dwMode
[in] Specifies the type of dialog box to display. This parameter can be one of the following values:
Value
Description
IME_CONFIG_GENERAL | Displays general purpose configuration dialog box.
IME_CONFIG_REGISTERWORD | Displays register word dialog box.
IME_CONFIG_SELECTDICTIONARY | Displays dictionary selection dialog box.

lpData
[in] Long pointer to supplemental data. If dwMode is IME_CONFIG_REGISTERWORD, this parameter must be the address of a REGISTERWORD structure.

If dwMode is not IME_CONFIG_REGISTERWORD, this parameter is ignored.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

The ImmConfigureIME function is called by the Control Panel.


ImmCreateContext

This function creates a new input context, allocating memory for the context and initializing it. An application calls this function to prepare its own input context.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

HIMC ImmCreateContext( void );

Return Values

The handle to the new input context indicates success. NULL indicates failure.


ImmCreateIMCC

This function enables an input method editor (IME) to create a new input method context (IMC) component that is a member of an IMC.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

HIMCC WINAPI ImmCreateIMCC( DWORD dwSize);

Parameters

dwSize
[in] Specifies the size of the new IMC component.

Return Values

The IMC component handle indicates success. 0 indicates failure.

Remarks

The IMC component created by this function is initialized with 0.

An IME is an OEM-developed application that monitors the user’s keystrokes, anticipates the characters the user may want, and presents a list of candidate characters from which to choose.

An IMC is a structure, maintained by the IME and used by IME windows, that contains information about the status of the IME. By default, the system creates and assigns an IMC to a thread if it calls a function that requires the use of an IMC. Within the thread, this default input context is a shared resource and is associated with each newly created window. An IMC requires considerable system resources, so use them judiciously.


ImmDestroyContext

This function releases the input context and frees any memory associated with it.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmDestroyContext( HIMC hIMC );

Parameters

hIMC
[in] Handle to the input context to free.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

Any application that creates an input context by using the ImmCreateContext function must call this function to free the context before it terminates.


ImmDestroyIMCC

This function enables an input method editor (IME) to destroy an input method context (IMC) component that is a member of an IMC.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

HIMCC WINAPI ImmDestroyIMCC( HIMCC hIMCC );

Parameters

hIMCC
[in] Handle to the IMC component.

Return Values

NULL indicates success. The IMC component handle indicates failure.


ImmDisableIME

This function disables the input method editor (IME) for a thread or all threads in a process.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmDisableIME( DWORD idThread );

Parameters

idThread
[in] Identifier of the thread for which the IME is disabled. If idThread is zero, the IME for the current thread is disabled. If idThread is –1, the IME is disabled for all threads in the current process. For Windows CE versions 2.10 and later, passing a –1 value for the idThread parameter is not supported.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The application must call this function before the first top-level window in the thread receives the WM_CREATE message. This means the application must call this function before calling CreateWindow to create the first top-level window.


ImmEnumRegisterWord

This function enumerates the register strings having the specified reading string, style, and register string.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

UINT ImmEnumRegisterWord( HKL hKL,
REGISTERWORDENUMPROC lpfnEnumProc, LPCTSTR lpszReading,
DWORD dwStyle, LPCTSTR lpszRegister, LPVOID lpData );

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
lpfnEnumProc
[in] Long pointer to the callback function. For more information, see EnumRegisterWordProc.
lpszReading
[in] Long pointer to the reading string to be enumerated. If NULL, this function enumerates all available reading strings that match with the specified dwStyle and lpszRegister.
dwStyle
[in] Specifies the style to be enumerate. If zero, this function enumerates all available styles that match with the specified lpszReading and lpszRegister.
lpszRegister
[in] Long pointer to the register string to enumerate. If NULL, this function enumerates all register strings that match with the specified lpszReading and dwStyle.
lpData
[in] Long pointer to application-supplied data. The function passes this parameter to the callback function.

Return Values

The last value returned by the callback function indicates success. Its meaning is defined by the application. Zero indicates that the function cannot enumerate the register strings.

Remarks

If dwStyle is zero and both lpszReading and lpszRegister are NULL, the ImmEnumRegisterWord function enumerates all register strings in the IME dictionary.


ImmEscape

This function carries out IME-specific subfunctions and is used mainly for country-specific functions.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

LRESULT ImmEscape( HKL hKL, HIMC hIMC, UINT uEscape,
LPVOID lpData );

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
hIMC
[in] Handle to the input context.
uEscape
[in] Index of the subfunction.
lpData
[in] Long pointer to subfunction-specific data.

Return Values

An escape-specific value indicates success. Zero indicates an error.


ImmGenerateMessage

This function enables an input method editor (IME) to generate messages that are sent to the window associated with the input method context (IMC). These messages are stored in hMsgBuf member of the INPUTCONTEXT structure identified by the hIMC parameter.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI ImmGenerateMessage( HIMC hIMC );

Parameters

hIMC
[in] Handle to the INPUTCONTEXT structure that contains IME messages in its hMsgBuf member.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

This is a general purpose function, but it is typically called by an IME when the input method manager (IMM) calls the ImmNotifyIME function to notify an IME of a context update.

An IME user interface (UI) should not call this function only to update UI appearance. Instead, the IME UI should be updated when the IME is informed about an updated IMC. It is recommended that this function be used by an IME only when the IME changes the IMC without any keystroke activity from the user and needs to inform an application of the change.


ImmGetCandidateList

This function retrieves a specified candidate list, copying the list to the specified buffer.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

DWORD ImmGetCandidateList(HIMC hIMC, DWORD deIndex, LPCANDIDATELIST lpCandList, DWORD dwBufLen);

Parameters

hIMC
[in] Handle to the input context.
deIndex
[in] Zero-based index of the candidate list.
lpCandList
[out] Long pointer to the CANDIDATELIST structure that receives the candidate list.
dwBufLen
[in] Specifies the size of the buffer, in bytes. If zero, the function returns the size in bytes required to receive the complete candidate list.

Return Values

The number of bytes copied to the specified buffer indicates success. Zero indicates failure.


ImmGetCandidateListCount

This function retrieves the size, in bytes, of the candidate lists.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

DWORD ImmGetCandidateListCount(HIMC hIMC, LPDWORD lpdwListCount);

Parameters

hIMC
[in] Handle to the input context.
lpdwListCount
[out] Long pointer to the 32-bit variable that receives the size of the candidate lists.

Return Values

The number of bytes required to receive all candidate lists indicates success.

Remarks

Applications typically call this function in response to a IMN_OPENCANDIDATE or IMN_CHANGECANDIDATE message.

See Also

IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE


ImmGetCandidateWindow

This function gets information about the candidate list window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmGetCandidateWindow(HIMC hIMC, DWORD dwIndex,
LPCANDIDATEFORM lpCandidate);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Specifies the index of the CANDIDATEFORM structure to retrieve. Windows CE supports four structures per context, ranging from 0 to 3.
lpCandidate
[out] Long pointer to the CANDIDATEFORM structure that receives information about the candidate window.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

In Windows CE Japanese version 1.0 and later, the following parameter is used instead of dwIndex:

dwBufLen
Size, in bytes, of the buffer that receives the information.

See Also

CANDIDATEFORM


ImmGetCompositionFont

This function retrieves information about the logical font currently used to display characters in the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmGetCompositionFont( HIMC hIMC, LPLOGFONT lplf );

Parameters

hIMC
[in] Handle to the input context.
lplf
[out] Long pointer to a LOGFONT structure that receives the font information.

Return Values

Nonzero indicates success. Zero indicates failure.


ImmGetCompositionString

This function retrieves information about the composition string.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

LONG ImmGetCompositionString(HIMC hIMC, DWORD dwIndex, LPVOID lpBuf, DWORD dwBufLen);

Parameters

hIMC
[in] Handle to the input context. In Windows CE versions 2.10 and later, if hIMC is NULL, then the length of the composition string, dwBufLen, is returned for the current active context.
dwIndex
[in] Specifies the index of the information to retrieve. For each value except GCS_CURSORPOS and GCS_DELTASTART, the function copies the requested information to the specified buffer. The function returns the cursor and delta position values in the low 16-bits of the return value.
lpBuf
[out] Long pointer to the buffer that receives the requested information.
dwBufLen
[in] Specifies the size of the buffer, in bytes. If zero, the ImmGetCompositionString function returns the buffer size needed for the complete information.

Return Values

The number of bytes copied to the destination buffer or, if dwBufLen is zero, the buffer size, in bytes, needed to receive all of the requested information indicates success. IMM_ERROR_NODATA indicates that the composition data is not ready in the input context. IMM_ERROR_GENERAL indicates that a general error was detected by IME.

Remarks

An application calls this function in response to the WM_IME_COMPOSITION or WM_IME_STARTCOMPOSITION message. The IMM removes the information when an application calls the ImmReleaseContext function.

See Also

ImmReleaseContext, WM_IME_COMPOSITION


ImmGetCompositionWindow

This function gets information about the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmGetCompositionWindow(HIMC hIMC,
LPCOMPOSITIONFORM lpCompForm);

Parameters

hIMC
[in] Handle to the input context.
lpCompForm
[out] Long pointer to the COMPOSITIONFORM structure that receives information about the composition window.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

COMPOSITIONFORM


ImmGetContext

This function retrieves the input context associated with the specified window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

HIMC ImmGetContext(HWND hWnd);

Parameters

hWnd
[in] Handle to the window to retrieve the input context for.

Return Values

The handle to the input context indicates success.

Remarks

An application should routinely use this function to retrieve the current input context before attempting to access information in the context.


ImmGetConversionList

This function retrieves the list of characters or words from one character or word.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

UINT ImmGetConversionList(HKL hKL, HIMC hIMC, LPCTSTR lpSrc,
LPCANDIDATELIST lpDst, DWORD dwBufLen, UINT uFlag);

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
hIMC
[in] Handle to the input context.
lpSrc
[in] Long pointer to a null-terminated character string.
lpDst
[out] Long pointer to the CANDIDATELIST structure that receives the conversion result.
dwBufLen
[in] Specifies the size of the destination buffer, in bytes. If zero, the function returns the buffer size needed for the complete conversion result.
uFlag
[in] Action flag. This parameter can be one of the following values:
Value
Description
GCL_CONVERSION | Source string is the reading string. The function copies the result string to the destination buffer.
GCL_REVERSECONVERSION | Source string is the result string. The function copies the reading string to the destination buffer.
GCL_REVERSE_LENGTH | Source string is the result string. The function returns the size in bytes of the reading string that would be created if GCL_REVERSECONVERSION were specified.

Return Values

The number of bytes copied to the specified buffer or, if dwBufLen is zero, the buffer size needed to receive the list indicate success.


ImmGetConversionStatus

This function gets the current conversion status.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmGetConversionStatus(HIMC hIMC, LPDWORD lpfdwConversion, LPDWORD lpfdwSentence);

Parameters

hIMC
[in] Handle to the input context for which to retrieve information. In Windows CE versions 2.10 and later, if hIMC is NULL, then the conversion status for the current active context is returned.
lpfdwConversion
[out] Long pointer to a 32-bit variable that receives a combination of conversion mode values.
lpfdwSentence
[out] Long pointer to a 32-bit variable that receives a sentence mode value.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

Conversion and sentence mode values are set only if the IME supports those modes.


ImmGetDefaultIMEWnd

This function gets the default window handle to the IME class.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

HWND ImmGetDefaultIMEWnd(HWND hWnd);

Parameters

hWnd
[in] Handle to the window for the application.

Return Values

The default window handle to the IME class indicates success. NULL indicates failure.

Remarks

For Windows CE versions 2.10 and later, this function enables multiple contexts per thread. For Japanese versions 1.0 through 2.0, the system creates only one default IME window.

See Also

WM_IME_STARTCOMPOSITION


ImmGetDescription

This function copies the description of the IME to the specified buffer.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

UINT ImmGetDescription( HKL hKL, LPTSTR lpszDescription,
UINT uBufLen );

Parameters

hKL
[in] Handle to the keyboard layout.
lpszDescription
[out] Long pointer to the buffer that receives the null-terminated string describing the IME.
uBufLen
[in] Specifies the size, in characters, of the buffer. If zero, the function returns the buffer size needed for the complete description, not including terminating null character.

The size of the buffer is in Unicode characters (each character is two bytes).

Return Values

The number of Unicode characters copied to the buffer or, if uBufLen is zero, the buffer size in characters needed to receive the description indicates success. Neither value includes the terminating null character.


ImmGetGuideLine

This function gets information about errors. Applications use the information to notify users.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

DWORD ImmGetGuideLine( HIMC hIMC, DWORD dwIndex,
LPTSTR lpBuf, DWORD dwBufLen );

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Specifies the type of guideline information to retrieve. This parameter can be one of the following values.
Value
Description
GGL_LEVEL | Returns the error level.
GGL_INDEX | Returns the error index.
GGL_STRING | Retrieves the error message string.
GGL_PRIVATE | Returns information about reverse conversion.

lpBuf
[out] Long pointer to the buffer that receives the error message string. This parameter can be NULL if dwIndex is not GGL_STRING or GGL_PRIVATE if dwBufLen is zero.
dwBufLen
[in] Specifies the size, in bytes, of the buffer pointed to by lpBuf. If zero, the function returns the buffer size needed to receive the error message string, not including the terminating null character.

Return Values

The return value is an error level, an error index, or the size of an error message string, depending on the value of the dwIndex parameter. If dwIndex is GGL_LEVEL, the return value is one of the following:

Value
Description
GL_LEVEL_ERROR | Error. The IME may not be able to continue.
GL_LEVEL_FATAL | Fatal error. The IME cannot continue, and data may be lost.
GL_LEVEL_INFORMATION | No error, but information is available for the user.
GL_LEVEL_NOGUIDELINE | No error. Remove previous error message if still visible.
GL_LEVEL_WARNING | Unexpected input or other result. The user should be warned, but the IME can continue.

If dwIndex is GGL_INDEX, the return value is one of the following:

Value
Description
GL_ID_CANNOTSAVE | The dictionary or the statistics data cannot be saved.
GL_ID_NOCONVERT | The IME cannot convert any more.
GL_ID_NODICTIONARY | The IME cannot find the dictionary, or the dictionary has an unexpected format.
GL_ID_NOMODULE | The IME can not find the module that IME needs.
GL_ID_READINGCONFLICT | For example, some vowels cannot put together.
GL_ID_TOOMANYSTROKE | There are too many strokes for one character or one clause.
GL_ID_TYPINGERROR | Typing error. The IME can not handle this typing.
GL_ID_UNKNOWN | Unknown error. The application should refer to the error message string.
GL_ID_INPUTREADING | IME accepts reading character input.
GL_ID_INPUTRADICAL | IME accepts radical character input.
GL_ID_INPUTCODE | IME accepts character code input.
GL_ID_CHOOSECANDIDATE | IME accepts candidate string selection.
GL_ID_REVERSECONVERSION | Information about reverse conversion is available.

If dwIndex is GGL_STRING, the return value is the number of bytes of the string copied to the buffer, or, if dwBufLen is zero, the return value is the buffer size needed to receive the string.

If dwIndex is GGL_PRIVATE, the return value is the number of bytes of information copied to the buffer. If dwIndex is GGL_PRIVATE and dwBufLen is zero, the return value is the buffer size needed to receive the information.

Remarks

Applications typically call this function after receiving an IMN_GUIDELINE message.


ImmGetHotKey

This function retrieves the value of the input method editor (IME) hot key.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI ImmGetHotKey( DWORD dwHotKeyID,
LPUINT lpuModifiers, LPUINT lpuVKey, LPHKL lphKL);

Parameters

dwHotKeyID
[in] Specifies the hot key identifier.
lpuModifiers
[out] Long pointer to the combination keys used with the hot key. Keys include MOD_ALT, MOD_CONTROL, MOD_SHIFT, MOD_LEFT, and MOD_RIGHT. The key up flag, MOD_ON_KEYUP, indicates the hot key is effective when the key is up. The modifier ignore flag, MOD_IGNORE_ALL_MODIFIER, indicates the combination of modifiers are ignored in hot key matching.
lpuVKey
[out] Long pointer to the virtual key code of the hot key.
lphKL
[out] Long pointer to the handle to the keyboard layout of the IME. If the return value of this parameter is NULL, the hot key can switch to the IME with this keyboard layout handle.

Windows CE does not support true keyboard layouts. In this instance, however, Windows CE returns the keyboard handle that is associated with the current IME and locale.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

This function is called by the IME control panel application.


ImmGetIMCCLockCount

This function enables an input method editor (IME) to get the lock count of the input method context (IMC) component.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

DWORD WINAPI ImmGetIMCCLockCount( HIMCC hIMCC );

Parameters

hIMCC
[in] Handle to the IMC component.

Return Values

Lock count of the IMC component indicates success.


ImmGetIMCCSize

This function enables an input method editor (IME) to get the size of the input method context (IMC) component.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

DWORD WINAPI ImmGetIMCCSize( HIMCC hIMCC );

Parameters

hIMCC
[in] Handle to the IMC component.

Return Values

The size of the IMC component indicates success.


ImmGetIMCLockCount

This function enables an input method editor (IME) to get the lock count of the input method context (IMC).

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

DWORD WINAPI ImmGetIMCLockCount( HIMC hIMC);

Parameters

hIMC
[in] Handle to the IMC.

Return Values

Lock count of the IMC indicates success. 0 indicates the IMC is invalid.


ImmGetIMEFileName

This function gets the file name of the IME associated with the specified keyboard layout.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmGetIMEFileName( HKL hKL, LPTSTR lpszFileName,
UINT uBufLen );

Parameters

hKL
[in] Handle to the keyboard layout. Windows CE does not support keyboard layouts; however, hKL is used in this instance to distinguish between locale-specific IMEs.
lpszFileName
[out] Long pointer to the buffer that receives the file name.
uBufLen
[in] Specifies the size, in bytes, of the buffer. If zero, the function returns the buffer size in bytes needed to receive the file name, not including the terminating null character.

Return Values

The number of bytes in the file name copied to the buffer, or, if uBufLen is zero, the buffer size needed for the file name indicates success. In either case, the terminating null character is not included.

Remarks

In the registry, the system stores the file name as the IME name value in HKEY_LOCAL_MACHINE root under the \System\CurrentControlSet\Control\Layout\hKL key.


ImmGetImeMenuItems

This function retrieves the menu items that are registered in the IME menu.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

DWORD WINAPI ImmGetImeMenuItems( HIMC hIMC, DWORD dwFlags,
DWORD dwType, LPIMEMENUITEMINFO lpImeParentMenu,
LPIMEMENUITEMINFO lpImeMenu, DWORD dwSize);

Parameters

hIMC
[in] Handle to the input context.
dwFlags
[in] Specifies a menu information flag. The following value is defined:
Value
Description
IGIMIF_RIGHTMENU If set, the function returns the menu items for the context menu (obtained by a right mouse click).

dwType
[in] Specifies the type of menu returned by this function. This parameter can be a combination of the following values.
Value
Description
IGIMII_CMODE | Returns the menu items that control the conversion mode.
IGIMII_SMODE | Returns the menu items that control sentence mode.
IGIMII_CONFIGURE | Returns the menu items that are related to configuration.
IGIMII_TOOLS | Returns the menu items that are related to tools.
IGIMII_HELP | Returns the menu items that control help.
IGIMII_OTHER | Returns the menu items that control other IME functions.
IGIMII_INPUTTOOLS | Returns the menu items that control input tools.

lpImeParentMenu
[in] Long pointer to the parent menu. It points to a IMEMENUITEMINFO structure with the fType member set to MFT_SUBMENU in order to return information about the submenu items of this parent menu. If this parameter is NULL, however, the function returns only top-level menu items.
lpImeMenu
[out] Long pointer to a buffer to receive the contents of the menu items. The buffer is an array of IMEMENUINFO structures. If this parameter is NULL, the function returns the number of registered menu items.
dwSize
[in] Specifies the size of the buffer to receive the IMEMENUITEMINFO structure.

Return Values

The number of menu items that were copied into lpImeMenu indicates success. If lpImeMenu is NULL, the function returns the number of registered menu items.


ImmGetOpenStatus

This function checks whether the IME is open or closed.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL WINAPI ImmGetOpenStatus(HIMC hIMC);

Parameters

hIMC
[in] Handle to the input context.

Return Values

Nonzero indicates that the IME is open. Zero indicates otherwise.

Remarks

In Windows CE versions 2.10 and later, if hIMC is NULL, then the status of the currently active context is returned.


ImmGetProperty

This function gets the property and capabilities of the IME associated with the specified keyboard layout.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmGetProperty(HKL hKL, DWORD fdwIndex);

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
fdwIndex
[in] Specifies the type of property information to retrieve. This parameter can be one of the following values:
Value
Description
IGP_PROPERTY | Property information.
IGP_CONVERSION | Conversion capabilities.
IGP_SENTENCE | Sentence mode capabilities.
IGP_UI | User interface capabilities.
IGP_SETCOMPSTR | Composition string capabilities.
IGP_SELECT | Selection inheritance capabilities.
IGP_GETIMEVERSION | Unsupported.

Return Values

Returns the property or capability value, depending on the value of the dwIndex parameter. If dwIndex is IGP_PROPERTY, returns a combination of the following values:

IME_PROP_AT_CARET
If set, conversion window is at the caret position. If clear, the window is near caret position.
IME_PROP_SPECIAL_UI
If set, IME has a nonstandard user interface. The application should not draw in the IME window.
IME_PROP_CANDLIST_START_FROM_1
If set, strings in the candidate list are numbered starting at 1. If clear, strings start at 0.
IME_PROP_UNICODE
If set, strings for the input context have Unicode characters. If clear, strings have single and double-byte characters.
IME_PROP_COMPLETE_ON_UNSELECT
If set, the IME will complete the composition string when the IME is deactivated. If clear, the IME will cancel the composition string when the IME is deactivated (such as from a keyboard layout change).

If dwIndex is IGP_UI, the return value is a combination of the following values:

Value
Description
UI_CAP_2700 | Supports text escapement values of 0 or 2700.
UI_CAP_ROT90 | Supports text escapement values of 0, 900, 1800, or 2700.
UI_CAP_ROTANY | Supports any text escapement value.

If dwIndex is IGP_SETCOMPSTR, the return value is a combination of the following values:

Value
Description
SCS_CAP_COMPSTR | Can create the composition string by using the SCS_SETSTR value of the ImmSetCompositionString function.
SCS_CAP_MAKEREAD | Can create the reading string from corresponding composition string when using the SCS_SETSTR value of the ImmSetCompositionString function.

If dwIndex is IGP_SELECT, the return value is a combination of the following values:

Value
Description
SELECT_CAP_CONVMODE | Inherits conversion mode when a new IME is selected.
SELECT_CAP_SENTENCE | Inherits sentence mode when a new IME is selected.

If dwIndex is IGP_GETIMEVERSION, the return value is one of the following values:

Value
Description
IMEVER_0310 | The IME was created for Windows 3.1
IMEVER_0400 | The IME was created for Windows 95.


ImmGetRegisterWordStyle

This function gets a list of the styles support by the IME associated with the specified keyboard layout.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

UINT ImmGetRegisterWordStyle( HKL hKL, UINT nItem,
LPSTYLEBUF lpStyleBuf );

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
nItem
[out] Maximum number of styles that the buffer can hold.
lpStyleBuf
[in] Long pointer to the STYLEBUF structure that receives the style information.

Return Values

The number of layout handles copied to the buffer, or, if nItems is zero, the buffer size in array elements needed to receive all available style information indicates success.


ImmGetStatusWindowPos

This function gets the position of the status window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmGetStatusWindowPos( HIMC hIMC, LPPOINT lpptPos );

Parameters

hIMC
[in] Handle to the input context.
lpptPos
[out] Long pointer to the POINT structure that receives the position coordinates. These are screen coordinates, relative to the upper-left corner of the screen.

Return Values

Nonzero indicates success. Zero indicates failure.


ImmGetVirtualKey

This function recovers the original virtual-key value associated with a key input message that has already been processed by the IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

UINT ImmGetVirtualKey( HWND hWnd );

Parameters

hWnd
[in] Handle to the window that receives the key message.

Return Values

The original virtual-key value indicates success.

Remarks

Although the IME sets the virtual-key value to VK_PROCESSKEY after processing a key input message, an application can recover the original virtual-key value with the ImmGetVirtualKey function. This function can be used only for key input messages containing the VK_PROCESSKEY value.


ImmIsIME

This function checks whether the specified handle identifies an IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmIsIME( HKL hKL );

Parameters

hKL
[in] Handle to the keyboard layout to check.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows CE Remarks

Windows CE validates the hKL parameter passed in.


ImmIsUIMessage

This function checks for messages intended for the IME window and sends those messages to the specified window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmIsUIMessage(HWND hWndIME, UINT msg, WPARAM wParam,
LPARAM lParam);

Parameters

hWndIME
[in] Handle to a window belonging to the IME window class.
msg
[in] Message to check.
wParam
[in] 32-bit message-specific parameter.
lParam
[in] 32-bit message-specific parameter.

Return Values

Nonzero indicates that the message is processed by the IME window.

Zero indicates that the message is not processed by the IME window.

Remarks

An application typically uses this function to display any composition string or candidate list specified by IME. If hWndIME is NULL, the function checks whether the message is a user interface message.


ImmLockIMC

This function enables an input method editor (IME) to access the INPUTCONTEXT structure for an input method context (IMC) by returning a pointer to the structure. ImmLockIMC increases the lock count for the IMC.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

LPINPUTCONTEXT WINAPI ImmLockIMC( HIMC hIMC);

Parameters

hIMC
[in] Handle to the IMC.

Return Values

Pointer to INPUTCONTEXT indicates success. NULL indicates failure.


ImmLockIMCC

This function enables an input method editor (IME) to get a pointer to an input method context (IMC) component that can be a member of the IMC. ImmLockIMC increases the lock count for the IMC.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

LPVOID WINAPI ImmLockIMCC( HIMCC hIMCC );

Parameters

hIMCC
[in] Handle to IMC component

Return Values

Pointer to the IMC component indicates success. NULL indicates failure.

Remarks

Windows CE does not use the lock count.


ImmNotifyIME

This function notifies the IME about changes to the status of the input context.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmNotifyIME(HIMC hIMC, DWORD dwAction, DWORD dwIndex,
DWORD dwValue);

Parameters

hIMC
[in] Handle to the input context.
dwAction
[in] Specifies the notification code. It is one of the following values:
Value
Description
NI_CHANGECANDIDATELIST | An application changed the current selected candidate; dwIndex is an index of a candidate list to be selected and dwValue is not used.
NI_CLOSECANDIDATE | An application directs the IME to close a candidate list; dwIndex is the index of the list to close; dwValue is not used. The IME sends a IMN_CLOSECANDIDATE message to the application if it closes the list.
NI_COMPOSITIONSTR | An application directs the IME to carry out an action on the composition string; dwValue is not used and dwIndex can be CPS_CANCEL, CPS_COMPLETE, CPS_CONVERT, or CPS_REVERT.
NI_IMEMENUSELECTED | An application directs the IME to allow the application to handle the specified menu; dwIndex is the ID of the menu and dwValue is an application-defined value for that menu item.
NI_OPENCANDIDATE | An application directs the IME to open a candidate list; dwIndex is the index of the list to open; dwValue is not used. The IME sends a IMN_OPENCANDIDATE message to the application if it opens the list.
NI_SELECTCANDIDATESTR | An application selected one of candidates; dwIndex is an index of a candidate list to be selected and dwValue is an index of a candidate string in the selected candidate list.
NI_SETCANDIDATE_PAGESIZE | The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 31.
NI_SETCANDIDATE_PAGESTART | The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 31.

dwIndex
[in] Specifies the index of a candidate list or, if dwAction is NI_COMPOSITIONSTR, one of the following values:
Value
Description
CPS_CANCEL | Clear the composition string and set the status to no composition string.
CPS_COMPLETE | Set the composition string as the result string.
CPS_CONVERT | Convert the composition string.
CPS_REVERT | Cancel the current composition string and revert to the unconverted string.

dwValue
[in] Specifies the index of a candidate string or not used, depending on the value of the dwAction parameter.

Return Values

Nonzero indicates success. Zero indicates failure.


ImmRegisterWord

This function registers a string into the dictionary of the IME associated with the specified keyboard layout.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmRegisterWord( HKL hKL, LPCTSR lpszReading,
DWORD dwStyle, LPCTSTR lpszRegister );

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
lpszReading
[in] Long pointer to a null-terminated string specifying the reading string associated with the string to register.
dwStyle
[in] Specifies the style of the register string. This parameter can be IME_REGWORD_STYLE_EUDC to indicate the string is in the EUDC range, or any value in the reserved range IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST to indicate a private style maintained by the specified IME.
lpszRegister
[in] Long pointer to a null-terminated string specifying the string to register.

Return Values

Nonzero indicates success. Zero indicates failure.


ImmReleaseContext

This function releases the input context and unlocks the memory associated in the context. An application must call ImmReleaseContext for each call to the ImmGetContext function.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmReleaseContext(HWND hWnd, HIMC hIMC);

Parameters

hWnd
[in] Handle to the window for which the input context was previously retrieved.
hIMC
[in] Handle to the input context.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImmGetContext


ImmReSizeIMCC

This function changes the size of an input method context (IMC) component.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

HIMCC WINAPI ImmReSizeIMCC( HIMCC hIMCC, DWORD dwSize );

Parameters

hIMCC
[in] Handle to the IMC component.
dwSize
[in] Specifies the new size of the IMC component.

Return Values

New handle of the IMC component indicates success. 0 indicates failure.


ImmSetCandidateWindow

This function sets information about the candidate list window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmSetCandidateWindow(HIMC hIMC, LPCANDIDATEFORM lpCandidate);

Parameters

hIMC
[in] Handle to the input context.
lpCandidate
[in] Long pointer to the CANDIDATEFORM structure that contains information about the candidate window.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

ImmSetCandidateWindow causes an IMN_SETCANDIDATEPOS message to be sent to the application.

In Japanese versions 1.0 and later, the ImmSetCandidateWindow function allows an index range of 0 to 4 for the dwIndex member of the CANDIDATEFORM structure. In Windows CE versions 2.10 and later, an index range of 0 to 3 is allowed.

See Also

CANDIDATEFORM


ImmSetCompositionFont

This function sets the logical font to be used to display characters in the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmSetCompositionFont( HIMC hIMC, LPLOGFONT lplf );

Parameters

hIMC
[in] Handle to the input context.
lplf
[in] Long pointer to the LOGFONT structure containing the font information to set.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

Even if an application never uses the composition window, it must set the appropriate font to ensure that characters are displayed properly. This is especially true for vertical writing.

This function causes a IMN_SETCOMPOSITIONFONT message to be sent to the application.


ImmSetCompositionString

This function sets the characters, attributes, and clauses of the composition and reading strings.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmSetCompositionString(HIMC hIMC, DWORD dwIndex,
LPCVOID lpComp, DWORD dwCompLen, LPCVOID lpRead,
DWORD dwReadLen);

Parameters

hIMC
[in] Handle to the input context.
dwIndex
[in] Specifies the type of information to set. This parameter can be one of one of the following values:
Value
Description
SCS_SETSTR | Sets the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid string. If either string is too long, the IME truncates it.
SCS_CHANGEATTR | Sets attributes for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid attribute array.
SCS_CHANGECLAUSE | Sets the clause information for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid clause information array.

lpComp
[in] Long pointer to the buffer containing the information to set for the composition string. The information is as specified by the dwIndex value.
dwCompLen
[in] Specifies the size, in bytes, of the information buffer for the composition string.
lpRead
[in] Long pointer to the buffer containing the information to set for the reading string. The information is as specified by the dwIndex value.
dwReadLen
[in] Specifies the size, in bytes, of the information buffer for the reading string.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

When changing attributes, all characters in a clause must have the same attribute. Converted characters must be either ATTR_CONVERTED or ATTR_TARGET_CONVERTED; unconverted characters either ATTR_INPUT or ATTR_TARGET_NOTCONVERTED.

When changing clause information, only the target clause can be changed and only one boundary of the clause can be changed at a time. The target clause has the ATTR_TARGET_CONVERTED or ATTR_TARGET_NOTCONVERTED attribute.

When the IME completes the changes, it sends a WM_IME_COMPOSITION message to the application notifying it of the changes.

See Also

WM_IME_COMPOSITION


ImmSetCompositionWindow

This function sets the position of the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmSetCompositionWindow(HIMC hIMC,
LPCOMPOSITIONFORM lpCompForm);

Parameters

hIMC
[in] Handle to the input context.
lpCompForm
[in] Long pointer to the COMPOSITIONFORM structure that contains the new position and other related information about the composition window.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

The ImmSetCompositionWindow function causes a IMN_SETSCOMPOSITIONWINDOW message to be sent to the application.

See Also

COMPOSITIONFORM


ImmSetConversionStatus

This function sets the current conversion status.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmSetConversionStatus(HIMC hIMC, DWORD fdwConversion, DWORD fdwSentence);

Parameters

hIMC
[in] Handle to the input context. If hIMC is NULL, then the conversion mode of the current active context is set.
fdwConvStatus
[in] Specifies conversion mode values.
fdwSentence
[in] Unsupported; should be set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

This function sends a IMN_SETCONVERSIONMODE message to the application when a mode change occurs and a IMN_SETSENTENCEMODE message when a sentence mode changes.


ImmSetHotKey

This function is called by the IME control panel application to set the value of the input method editor (IME) hot key.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI ImmSetHotKey( DWORD dwHotKeyID, UINT uModifiers, UINT uVKey, HKL hKL );

Parameters

dwHotKeyID
[in] Specifies the hot key identifier.
uModifiers
[in] Pointer to the combination keys used with the hot key. Keys include MOD_ALT, MOD_CONTROL, MOD_SHIFT, MOD_LEFT, and MOD_RIGHT. The key up flag, MOD_ON_KEYUP, indicates the hot key is effective when the key is up. The modifier ignore flag, MOD_IGNORE_ALL_MODIFIER, indicates the combination of modifiers are ignored in hot key matching.
uVKey
[in] Virtual key code of the hot key.
hKL
[in] Handle to the keyboard layout of the IME. If this parameter is specified, the hot key can switch to the IME with this keyboard layout handle.

Windows CE does not support true keyboard layouts. In this instance, however, Windows CE uses the keyboard handle to associate hot keys with a specific IME and locale.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

For a key that is not on each side of the keyboard, uModifiers should specify both sides, MOD_LEFT|MODE_RIGHT.

Windows CE supports the following hot key identifiers:

Hot Key Identifier
Description
IME_CHOTKEY_SHAPE_TOGGLE | For simplified Chinese, toggles the shape conversion mode of IME.
IME_CHOTKEY_SYMBOL_TOGGLE | For simplified Chinese, toggles the symbol conversion mode of IME. Symbol mode indicates that the user can input Chinese punctuation and symbols by mapping to the punctuation and symbols on the keyboard.
IME_JHOTKEY_CLOSE_OPEN | For Japanese, alternately opens and closes the IME.
IME_KHOTKEY_ENGLISH | Switches to from Korean to English.
IME_KHOTKEY_SHAPE_TOGGLE | For Korean, toggles the shape conversion mode of IME.
IME_KHOTKEY_HANJACONVERT | For Korean, switches to Hanja conversion.
IME_THOTKEY_SHAPE_TOGGLE | For traditional Chinese, toggles the shape conversion mode of IME.
IME_THOTKEY_SYMBOL_TOGGLE | For traditional Chinese, toggles the symbol conversion mode of IME.
IME_HOTKEY_DSWITCH_FIRST through IME_HOTKEY_DSWITCH_LAST | Enables a IME to be switched.


ImmSetOpenStatus

This function opens or closes the IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmSetOpenStatus(HIMC hIMC, BOOL fOpen);

Parameters

hIMC
[in] Handle to the input context. For Windows CE versions 2.10 and later, if hIMC is NULL, then the open status for the current active context is returned.
fOpen
[in] Open flag. If TRUE, the IME is opened; otherwise, it is closed.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

This function causes a IMN_SETOPENSTATUS message to be sent to the application.

See Also

IMN_SETOPENSTATUS


ImmSetStatusWindowPos

This function sets the position of the status window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmSetStatusWindowPos( HIMC hIMC, LPPOINT lpptPos );

Parameters

hIMC
[in] Handle to the input context.
lpptPos
[out] Long pointer to the POINT structure that receives the new position of the status window.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

The ImmSetStatusWindowPos function causes a IMN_SETSTATUSWINDOWPOS message to be sent to the application.


ImmSimulateHotKey

This function simulates the specified IME hot key, causing the same response as if the user had pressed the hot key in the specified window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

BOOL ImmSimulateHotKey(HWND hWnd, DWORD dwHotKeyID);

Parameters

hWnd
[in] Handle to the window.
dwHotKeyID
[in] Specifies the identifier of the IME hot key.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

For Japanese versions 1.0 and later, Windows CE supports the following value for the dwHotKeyID parameter:

IME_JHOTKEY_CLOSE_OPEN
(Japanese) Alternately opens and closes the IME.

This value is not supported for Windows CE versions 2.10 and later.


ImmSIPanelState

This function performs operations relating to the input panel, including getting or setting state information and communicating to the system the input attributes of the caller.

At a Glance

Header file: | imm.h
Versions: | Japanese version 2.0

Syntax

BOOL ImmSIPanelState(UINT dwCmd, LPVOID pValue);

Parameters

dwCmd
[in] Specifies the operation that is to be performed by ImmSiPanelState. The following operations are defined:
Value
Description
SIP_QUERY_LOCATION | Query the location of input panel. pValue is the pointer to RECT that stores the location of input panel in screen coordinates.
SIP_QUERY_STATE | Query the state of input panel. input panel can be in one of two states: hardware keyboard present and hardware keyboard not present. The pValue parameter is the pointer to DWORD, which can be either SIP_STATE_HDKB or SIP_STATE_NOHDKB.
SIP_SET_LOCATION | Set the location of the input panel. pValue is the pointer to POINT which is the new location of the input panel.
SIP_INPUT_ATTRIBUTES | Describe the caller’s input attributes for the input panel. The pValue parameter can contain one of the following values:
•SIP_INPUT_NUMERIC
•SIP_INPUT_ALPHANUMERIC
•SIP_INPUT_HIRAGANA
•SIP_INPUT_KATAKANA
•SIP_INPUT_EVERYTHING
•SIP_INPUT_HALFWIDTH
•SIP_INPUT_FULLWIDTH

pValue
[in] Pointer to parameters associated with the operation specified in the dwCmd parameter.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

This function is supported only for Windows CE Japanese version 2.0.


ImmUnlockIMC

This function reduces the lock count for the input method context (IMC).

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI ImmUnlockIMC( HIMC hIMC );

Parameters

hIMC
[in] Handle to the IMC.

Return Values

FALSE when the lock count of IMC is reduced to zero; otherwise, TRUE.


ImmUnlockIMCC

This function reduces the lock count for the input method context (IMC) component.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI ImmUnlockIMCC( HIMCC hIMCC );

Parameters

hIMCC
[in] Handle to the IMC component.

Return Values

FALSE indicates that the lock count of IMC component is reduced to zero; otherwise, TRUE.


ImmUnregisterWord

This function removes a register string from the dictionary of the IME associated with the specified keyboard layout.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

BOOL ImmUnregisterWord( HKL hKL, LPCTSTR lpszReading,
DWORD dwStyle, LPCTSTR lpszUnregister );

Parameters

hKL
[in] Ignored; set to NULL. Windows CE does not support true keyboard layouts.
lpszReading
[in] Long pointer to a null-terminated string specifying the reading string associated with the string to remove.
dwStyle
[in] Specifies the style of the register string. This parameter can be IME_REGWORD_STYLE_EUDC to indicate the string is in the EUDC range, or any value in the reserved range IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST to indicate a private style maintained by the specified IME.
lpszUnregister
[in] Long pointer to a null-terminated string specifying the register string to remove.

Return Values

Nonzero indicates success. Zero indicates failure.


InitCommonControls

This function registers and initializes the common control window classes. This function is obsolete. New applications should use the InitCommonControlsEx function.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

void InitCommonControls(void);

Return Values

None.


InitCommonControlsEx

This function registers specific common controls classes from the common control dynamic-link library (DLL).

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL InitCommonControlsEx(
LPINITCOMMONCONTROLSEX lpInitCtrls);

Parameters

lpInitCtrls
Long pointer to an INITCOMMONCONTROLSEX structure that contains information specifying which control classes are registered.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The effect of each call to InitCommonControlsEx is cumulative. For example, if InitCommonControlsEx is called with the ICC_UPDOWN_CLASS flag, then is later called with the ICC_HOTKEY_CLASS flag, the result is that both the up-down and hot key common control classes are registered and available to the application.


InsertMenu

This function inserts a new menu item into a menu, moving other items down the menu.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL InsertMenu(HMENU hMenu, UINT uPosition, UINT uFlags,
UINT uIDNewItem, LPCTSTR lpNewItem);

Parameters

hMenu
[in] Handle to the menu to be changed.
uPosition
[in] Specifies the menu item before which the new menu item is to be inserted, as determined by the uFlags parameter.
uFlags
[in] Specifies flags that control the interpretation of the uPosition parameter and the content, appearance, and behavior of the new menu item. This parameter must be a combination of one of the following required values and at least one of the values listed in the following Remarks section.
Value
Description
MF_BYCOMMAND | Indicates that the uPosition parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION | Indicates that the uPosition parameter gives the zero-based relative position of the new menu item. If uPosition is 0xFFFFFFFF, the new menu item is appended to the end of the menu.

uIDNewItem
[in] Specifies either the identifier of the new menu item or, if the uFlags parameter has the MF_POPUP flag set, the handle to the drop-down menu or submenu.
lpNewItem
[in] Long pointer to the content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter includes the MF_OWNERDRAW or MF_STRING flag, as follows:
Value
Description
MF_OWNERDRAW | Contains a 32-bit value supplied by the application that can be used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASUREITEM or WM_DRAWITEM message sent when the menu item is created or its appearance is updated.
MF_STRING | Contains a pointer to a null-terminated string (the default).

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

The following list describes the flags that can be set in the uFlags parameter:

MF_CHECKED
Places a check mark next to the menu item.
MF_ENABLED
Enables the menu item so that it can be selected and restores it from its grayed state.
MF_GRAYED
Disables the menu item and grays it so it cannot be selected.
MF_MENUBARBREAK
Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.

Windows CE versions 1.0 and 1.01 do not support this flag.

MF_MENUBREAK
Places the item on a new line (for menu bars) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.

Windows CE versions 1.0 and 1.01 do not support this flag.

MF_OWNERDRAW
Specifies that the item is an owner-drawn item. Before the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message to retrieve the width and height of the menu item. The WM_DRAWITEM message is then sent to the window procedure of the owner window whenever the appearance of the menu item must be updated.
MF_POPUP
Specifies that the menu item opens a drop-down menu or submenu. The uIDNewItem parameter specifies the handle to the drop-down menu or submenu. This flag is used to add a menu name to a menu bar or a menu item that opens a submenu to a drop-down menu, submenu, or shortcut menu.

Windows CE versions 1.0 and 1.01 do not support this flag.

MF_SEPARATOR
Draws a horizontal dividing line. This flag is used only in a drop-down menu, submenu, or shortcut menu. The line cannot be grayed, disabled, or highlighted. The lpNewItem and uIDNewItem parameters are ignored.
MF_STRING
Specifies that the menu item is a text string; the lpNewItem parameter points to the string.
MF_UNCHECKED
Does not place a check mark next to the menu item (default).

The following groups of flags cannot be used together:

  • MF_BYCOMMAND and MF_BYPOSITION
  • MF_ENABLED and MF_GRAYED
  • MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR
  • MF_MENUBARBREAK and MF_MENUBREAK
  • MF_CHECKED and MF_UNCHECKED

Menu items cannot be disabled without being grayed. To disable a menu item, use the MF_GRAYED flag.

Windows CE versions 1.0 and 1.01 do not support cascading menus. If you are using Windows CE version 1.0 or 1.01, you cannot insert an MF_POPUP menu into another pop-up menu. If using Windows CE versions 2.0 or later, you can.

See Also

AppendMenu, CreateMenu, DeleteMenu, RemoveMenu


IntersectClipRect

This function creates a new clipping region from the intersection of the current clipping region and the specified rectangle.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int IntersectClipRect(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

hdc
[in] Handle to the device context.
nLeftRect
[in] Specifies the logical x-coordinate of the upper-left corner of the rectangle.
nTopRect
[in] Specifies the logical y-coordinate of the upper-left corner of the rectangle.
nRightRect
[in] Specifies the logical x-coordinate of the lower-right corner of the rectangle.
nBottomRect
[in] Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Values

The return value specifies the new clipping region’s type. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than a single rectangle. ERROR indicates that an error occurred; the current clipping region is unaffected.

Remarks

The lower and rightmost edges of the specified rectangle are excluded from the clipping region.

See Also

ExcludeClipRect


InvalidateRect

This function adds a rectangle to the specified window’s update region. The update region represents the portion of the window’s client area that must be redrawn.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL InvalidateRect( HWND hWnd, const RECT *lpRect, BOOL bErase);

Parameters

hWnd
Handle to the window whose update region has changed. If this parameter is NULL, the system invalidates and redraws all windows, and sends the WM_ERASEBKGND message to the window procedure before the function returns.
lpRect
Long pointer to a RECT structure that contains the client coordinates of the rectangle to be added to the update region. If this parameter is NULL, the entire client area is added to the update region.
bErase
Boolean that specifies whether the background within the update region is to be erased when the update region is processed. If this parameter is TRUE, the background is erased when the BeginPaint function is called. If this parameter is FALSE, the background remains unchanged.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Windows NT: To get extended error information, call GetLastError.

Remarks

The hWnd parameter cannot be NULL.

The invalidated areas accumulate in the update region until the region is processed when the next WM_PAINT message occurs or until the region is validated by using the ValidateRect function.

The system sends a WM_PAINT message to a window whenever its update region is not empty and there are no other messages in the application queue for that window.

If the bErase parameter is TRUE for any part of the update region, the background is erased in the entire region, not just in the given part.

See Also

BeginPaint, RECT, ValidateRect, WM_ERASEBKGND, WM_PAINT


IsChild

This function tests whether a window is a child window or descendant window of a specified parent window. A child window is the direct descendant of a specified parent window if that parent window is in the chain of parent windows; the chain of parent windows leads from the original overlapped or pop-up window to the child window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsChild( HWND hWndParent, HWND hWnd);

Parameters

hWndParent
Handle to the parent window.
hWnd
Handle to the window to be tested.

Return Values

Nonzero indicates that the window is a child or descendant window of the specified parent window. Zero indicates that the window is not a child or descendant window of the specified parent window.

See Also

IsWindow, SetParent


IsClipboardFormatAvailable

This function determines whether the clipboard contains data in the specified format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsClipboardFormatAvailable(UINT format);

Parameters

format
[in] Unsigned integer that specifies a standard or registered clipboard format.

Return Values

Nonzero indicates that the clipboard format is available. Zero indicates that If the clipboard format is not available. To get extended error information, call GetLastError.

Remarks

Typically, an application that recognizes only one clipboard format would call this function when processing the WM_INITMENUPOPUP message. The application would then enable or disable the Paste menu item, depending on the return value. Applications that recognize more than one clipboard format should use the GetPriorityClipboardFormat function for this purpose.

See Also

CountClipboardFormats, EnumClipboardFormats, GetPriorityClipboardFormat, RegisterClipboardFormat, SetClipboardData, WM_INITMENUPOPUP


IsDialogMessage

This function determines whether a message is intended for the specified dialog box and, if it is, processes the message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsDialogMessage( HWND hDlg, LPMSG lpMsg );

Parameters

hDlg
[in] Handle to the dialog box.
lpMsg
[in] Long pointer to an MSG structure that contains the message to be checked.

Return Values

Nonzero indicates that the message has been processed. Zero indicates that the message has not been processed.

Remarks

Although the IsDialogMessage function is intended for modeless dialog boxes, you can use it with any window that contains controls, enabling the windows to provide the same keyboard selection as is used in a dialog box.

When IsDialogMessage processes a message, it checks for keyboard messages and converts them into selections for the corresponding dialog box. For example, the TAB key, when pressed, selects the next control or group of controls, and the DOWN ARROW key, when pressed, selects the next control in a group.

Because the IsDialogMessage function performs all necessary translating and dispatching of messages, a message processed by IsDialogMessage must not be passed to the TranslateMessage or DispatchMessage function.

IsDialogMessage sends WM_GETDLGCODE messages to the dialog box procedure to determine which keys should be processed.

IsDialogMessage can send DM_GETDEFID and DM_SETDEFID messages to the window. These messages are defined in the WINUSER.H header file as WM_USER and WM_USER +1, so conflicts are possible with application-defined messages having the same values.

See Also

DispatchMessage, DM_GETDEFID, DM_SETDEFID, MSG, TranslateMessage, WM_GETDLGCODE, WM_USER


IsWindow

This function determines whether the specified window handle identifies an existing window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsWindow(HWND hWnd);

Parameters

hWnd
Handle to the window to test.

Return Values

Nonzero indicates that the window handle identifies an existing window. Zero indicates that the window handle does not identify an existing window.

See Also

IsWindowEnabled, IsWindowVisible


IsWindowEnabled

This function determines whether the specified window is enabled for touch screen input and keyboard input.

At a Glance

Header file: | Winuser.h
Versions: | 1.0 and later

Syntax

BOOL IsWindowEnabled(HWND hWnd);

Parameters

hWnd
Handle to the window to test.

Return Values

Nonzero indicates that the window is enabled. Zero indicates that the window is not enabled.

Remarks

A child window receives input only if it is both enabled and visible.

See Also

EnableWindow, IsWindowVisible, IsWindow


IsWindowVisible

This function retrieves the visibility state of the specified window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsWindowVisible(HWND hWnd);

Parameters

hWnd
Handle to the window to test.

Return Values

Nonzero indicates that the specified window and its parent window have the WS_VISIBLE style. Zero indicates that the specified window and its parent window do not have the WS_VISIBLE style. Because the return value specifies whether the window has the WS_VISIBLE style, it may be nonzero even if the window is totally obscured by other windows.

Remarks

The visibility state of a window is indicated by the WS_VISIBLE style bit. When WS_VISIBLE is set, the window is displayed and subsequent drawing into it is displayed as long as the window has the WS_VISIBLE style.

Any drawing to a window with the WS_VISIBLE style will not be displayed if the window is obscured by other windows or is clipped by its parent window.

See Also

IsWindowEnabled, ShowWindow


keybd_event

This function synthesizes a keystroke. The system can use such a synthesized keystroke to generate a WM_KEYUP or WM_KEYDOWN message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

VOID keybd_event( BYTE bVk, BYTE bScan, DWORD dwFlags,
DWORD dwExtraInfo );

Parameters

bVk
[in] Specifies a virtual-key code. The code must be a value in the range 1 to 254.
bScan
[in] Specifies a hardware scan code for the key.
dwFlags
[in] Specifies various aspects of function operation. An application can use any combination of the following predefined constant values to set the flags.
Value
Description
KEYEVENTF_KEYUP | If specified, the key is being released. If not specified, the key is being depressed.
KEYEVENTF_SILENT | If specified, a keystroke is simulated, but no clicking sound is made.

dwExtraInfo
[in] Specifies an additional 32-bit value associated with the key stroke.

Return Values

None.

Remarks

When keyboard input is disabled with EnableHardwareKeyboard(FALSE), you can simulate keyboard input using keybd_event.

Although keybd_event passes an OEM-dependent hardware scan code to the system, applications should not use the scan code. The system converts scan codes to virtual-key codes internally and clears the up/down bit in the scan code before passing it to applications.

An application can simulate a press of the PRINTSCREEN key in order to obtain a screen snapshot and save it to the clipboard. To do this, call keybd_event with the bVk parameter set to VK_SNAPSHOT, and the bScan parameter set to 0 for a snapshot of the full screen or set bScan to 1 for a snapshot of the active window.

See Also

GetAsyncKeyState, GetKeyState, MapVirtualKey


KillTimer

This function destroys the specified timer. The system searches the message queue for any pending WM_TIMER messages associated with the timer and removes them.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL KillTimer(HWND hWnd, UINT uIDEvent);

Parameters

hWnd
Handle to the window associated with the specified timer. This value must be the same as the hWnd value passed to the SetTimer function that created the timer.
uIDEvent
Specifies the identifier of the timer to be destroyed. If the window handle passed to SetTimer is valid, this parameter must be the same as the uIDEvent value passed to SetTimer. If the application calls SetTimer with hWnd set to NULL, this parameter must be the timer identifier returned by SetTimer.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The KillTimer function does not remove WM_TIMER messages already posted to the message queue.

See Also

SetTimer, WM_TIMER


LoadAccelerators

This function loads the specified accelerator table.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

HACCEL LoadAccelerators(HINSTANCE hInstance, LPCTSTR lpTableName);

Parameters

hInstance
Handle to an instance of the module whose executable file contains the accelerator table to load.
lpTableName
Long pointer to a null-terminated string that names the accelerator table to load. Alternatively, this parameter can specify the resource identifier of an accelerator-table resource in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

The handle to the loaded accelerator table indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The resource is not copied into RAM, so it may not be modified.

If the accelerator table has not yet been loaded, the function loads it from the specified executable file.

Accelerator tables loaded from resources are freed automatically when the application terminates.

See Also

CreateAcceleratorTable, DestroyAcceleratorTable, MAKEINTRESOURCE


LoadBitmap

This function loads the specified bitmap resource from a module’s executable file.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HBITMAP LoadBitmap(HINSTANCE hInstance, LPCTSTR lpBitmapName);

Parameters

hInstance
[in] Handle to the instance of the module whose executable file contains the bitmap to be loaded.
lpBitmapName
[in] Long pointer to a null-terminated string that contains the name of the bitmap resource to be loaded. Alternatively, this parameter can consist of the resource identifier in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

The handle to the specified bitmap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If the bitmap pointed to by the lpBitmapName parameter does not exist or there is insufficient memory to load the bitmap, the function fails.

The application must call the DeleteObject function to delete each bitmap handle returned by the LoadBitmap function.

Windows CE version 1.0 supports only a 2 bit gray scale palette, so use only a bitmap that is 1 bit per pixel (monochrome .bmp) or 2 bits per pixel (.2bp).

See Also

CreateBitmap, DeleteObject, LoadIcon, MAKEINTRESOURCE


LoadCursor

This function loads a cursor resource.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HCURSOR LoadCursor ( HINSTANCE hInstance,
LPCTSTR lpCursorName);

Parameters

hInstance
[in] Handle to an instance of the module whose executable file contains the cursor to be loaded.
lpCursorName
[in] Long pointer to a null-terminated string that contains the name of the cursor resource to be loaded. Alternatively, this parameter can consist of the resource identifier in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can also be used to create this value.

To use one of the Win32 predefined cursors, the application must set the hInstance parameter to NULL and the lpCursorName parameter to one the values shown in the following table.
Value
Description
IDC_APPSTARTING | Standard arrow and small hourglass
IDC_ARROW | Standard arrow
IDC_CROSS | Crosshair
IDC_HAND | Hand
IDC_HELP | Arrow and question mark
IDC_ICON | Obsolete
IDC_NO | Slashed circle
IDC_SIZE | Obsolete; use IDC_SIZEALL
IDC_SIZEALL | Four-pointed arrow pointing north, south, east, and west
IDC_SIZENESW | Double-pointed arrow pointing northeast and southwest
IDC_SIZENS | Double-pointed arrow pointing north and south
IDC_SIZENWSE | Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE | Double-pointed arrow pointing west and east
IDC_UPARROW | Vertical arrow
IDC_WAIT | Hourglass

Return Values

The handle to the newly loaded cursor indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The LoadCursor function loads the cursor resource only if it has not been loaded; otherwise, it retrieves the handle to the existing resource. This function returns a valid cursor handle only if the lpCursorName parameter points to a cursor resource. If lpCursorName points to any type of resource other than a cursor (such as an icon), the return value is not NULL, even though it is not a valid cursor handle.

The LoadCursor function searches the cursor resource most appropriate for the cursor for the current display device. The cursor resource can be a color or monochrome bitmap.

Use the cursor component when targeting a platform that does not support mouse cursors. The only cursor this component supports is the wait cursor (IDC_WAIT). Use the LoadCursor function in conjunction with the SetCursor function to set the wait cursor.

SetCursor(LoadCursor(NULL, IDC_WAIT));

Use the mcursor component when targeting a platform that does support mouse cursors. This component supports the LoadCursor function the same way Windows desktop platforms do, except that it only supports monochrome cursors. Windows CE does not support color cursors. An attempt to load a color cursor will have unpredictable results.

See Also

SetCursor, SetCursorPos, ShowCursor


LoadIcon

This function loads the specified icon resource from the executable (.exe) file associated with an application instance.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HICON LoadIcon(HINSTANCE hInstance, LPCTSTR lpIconName);

Parameters

hInstance
[in] Handle to an instance of the module whose executable file contains the icon to be loaded. This parameter must be NULL when a standard icon is being loaded.
lpIconName
[in] Long pointer to a null-terminated string that contains the name of the icon resource to be loaded. Alternatively, this parameter can contain the resource identifier in the low-order word and zero in the high-order word. Use the MAKEINTRESOURCE macro to create this value.

Return Values

A handle to the newly loaded icon indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

LoadIcon loads the icon resource only if it has not been loaded; otherwise, it retrieves a handle to the existing resource. The function searches the icon resource for the icon most appropriate for the current display. The icon resource can be a color or monochrome bitmap.

LoadIcon can only load an icon whose size conforms to the SM_CXICON and SM_CYICON system metric values. Use the LoadImage function to load icons of other sizes.

In Windows CE version 1.0, the icon must be a two bit per pixel (.ic2) icon or a monochrome icon.

See Also

LoadImage, MAKEINTRESOURCE


LoadImage

This function loads an icon, cursor, or bitmap.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE LoadImage(HINSTANCE hinst,| LPCTSTR lpszName,
UINT uType, int cxDesired, int cyDesired, UINT fuLoad);

Parameters

hinst
[in] Handle to an instance of the module that contains the image to be loaded. To load an OEM image, set this parameter to zero.
lpszName
[in] Identifies the image to load. If the hinst parameter is non-NULL and the fuLoad parameter does not include LR_LOADFROMFILE, lpszName is a pointer to a null-terminated string that contains the name of the image resource in the hinst module.

If hinst is NULL and LR_LOADFROMFILE is not specified, the low-order word of this parameter must be the identifier of the OEM image to load. The OEM image identifiers are defined in Winuser.h and have the following prefixes:
Prefix
Description
OBM_ | OEM bitmaps
OIC_ | OEM icons
OCR_ | OEM cursors

If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName is the name of the file that contains the image.

uType
[in] Specifies the type of image to be loaded. This parameter can be one of the following values:
Value
Description
IMAGE_BITMAP | Loads a bitmap.
IMAGE_CURSOR | Loads a cursor.
IMAGE_ICON | Loads an icon.

cxDesired
[in] Specifies the width, in pixels, of the icon or cursor. If this parameter is zero, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If uType is IMAGE_BITMAP, this parameter must be zero.
cyDesired
[in] Specifies the height, in pixels, of the icon or cursor. If this parameter is zero, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height. If uType is IMAGE_BITMAP, this parameter must be zero.
fuLoad
[in] Set to zero.

Windows CE behaves as though the LR_DEFAULTCOLOR and LR_DEFAULTSIZE values are set. LR_DEFAULTCOLOR means “not monochrome..” LR_DEFAULTSIZE means that the system uses the width or height specified by the system metric values for cursors or icons if the cxDesired or cyDesired values are set to zero. If the resource contains multiple images, the function uses the size of the first image.

Return Values

The handle of the newly loaded image indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

When you are finished using a bitmap, cursor, or icon you loaded, you can release its associated memory by calling one of the functions in the following table.

Resource
Release function
Bitmap | DeleteObject
Cursor | DestroyCursor
Icon | DestroyIcon

The system automatically deletes these resources when the process that created them terminates, however, calling the appropriate function saves memory and decreases the size of the process's working set.

If you are targeting a platform that does not support mouse cursors, you cannot specify the SM_CXCURSOR and SM_CYCURSOR values in the cxDesired and cyDesired parameters, and you cannot specify IMAGE_CURSOR for the uType parameter.

See Also

GetSystemMetrics, LoadBitmap, LoadIcon


LoadMenu

This function loads the specified menu resource from the executable (.exe) file associated with an application instance.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HMENU LoadMenu(HINSTANCE hInstance, LPCTSTR lpMenuName);

Parameters

hInstance
[in] Handle to the instance of the module containing the menu resource to be loaded.
lpMenuName
[in] Long pointer to a null-terminated string that contains the name of the menu resource. Alternatively, this parameter can consist of the resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro.

Return Values

The handle to the menu resource indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The DestroyMenu function is used, before an application closes, to destroy the menu and free memory that the loaded menu occupied.

Windows CE versions 1.0 and 1.01 do not support cascading menus. Windows CE versions 2.0 and later support cascading menus.

See Also

MAKEINTRESOURCE


LoadString

This function loads a string resource from the executable file associated with a specified module, copies the string into a buffer, and appends a terminating null character.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int LoadString(HINSTANCE hInstance, UINT uID, LPTSTR lpBuffer,
int nBufferMax);

Parameters

hInstance
[in] Handle to an instance of the module whose executable file contains the string resource.
uID
[in] Specifies the integer identifier of the string to be loaded.
lpBuffer
[out] Long pointer to the buffer to receive the string.
nBufferMax
[in] Specifies the size of the buffer in bytes (ANSI version) or characters (Unicode version). The string is truncated and null terminated if it is longer than the number of characters specified.

Return Values

The number of characters copied into the buffer, not including the terminating null character, indicates success. Zero indicates that the string resource does not exist. To get extended error information, call GetLastError.

Remarks

If lpBuffer is set to NULL, the return value is a pointer to the requested string. The caller should cast the return value to an LPCTSTR. This pointer points directly to the resource, so the string is read-only. The length of the string, not including any Terminating null character, can be found in the word preceding the string.

To use the lpBuffer pointer, the –n flag must be set with the resource compiler, RC.

See Also

LoadAccelerators, LoadBitmap, LoadIcon, LoadMenu


MapDialogRect

This function converts, or maps, the specified dialog box units to screen units, or pixels. The function replaces the coordinates in the specified RECT structure with the converted coordinates, which allows the structure to be used to create a dialog box or position a control within a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MapDialogRect( HWND hDlg, LPRECT lpRect );

Parameters

hDlg
[in] Handle to a dialog box. This function accepts only handles returned by one of the dialog box creation functions; handles for other windows are not valid.
lpRect
[in] Long pointer to a RECT structure that contains the dialog box coordinates to be converted.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The MapDialogRect function assumes that the initial coordinates in the RECT structure represent dialog box units. To convert these coordinates from dialog box units to pixels, the function retrieves the current horizontal and vertical base units for the dialog box, then applies the following formulas:

left   = (left   * baseunitX) / 4
right  = (right  * baseunitX) / 4
top    = (top    * baseunitY) / 8
bottom = (bottom * baseunitY) / 8

The base units for the dialog box are the same as those retrieved by using the GetDialogBaseUnits function.

If one of the dimensions specified in the RECT structure is not a multiple of four, MapDialogRect always results in a rectangle that one pixel more for that dimension.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, GetDialogBaseUnits, RECT


MapVirtualKey

This function translates, or maps, a virtual-key code into a scan code or character value, or translates a scan code into a virtual-key code.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT MapVirtualKey( UINT uCode, UINT uMapType );

Parameters

uCode
[in] Specifies the virtual-key code or scan code for a key.
uMapType
[in] Specifies the translation to perform. It is the following value:
Value
Description
2 The uCode parameter is a virtual-key code and is translated into an unshifted character value in the low-order word of the return value. Dead keys (diacritics) are indicated by setting the top bit of the return value. If there is no translation, the function returns 0.

Return Values

A character value indicates success. Zero indicates that there is no translation.

See Also

GetAsyncKeyState, GetKeyState


MapWindowPoints

This function converts, or maps, a set of points from a coordinate space relative to one window to a coordinate space relative to another window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int MapWindowPoints( HWND hWndFrom, HWND hWndTo,
LPPOINT lpPoints, UINT cPoints);

Parameters

hWndFrom
Handle to the window from which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are presumed to be in screen coordinates.
hWndTo
Handle to the window to which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are converted to screen coordinates.
lpPoints
Long pointer to an array of POINT structures that contain the set of points to be converted. This parameter can also point to a RECT structure, in which case the cPoints parameter should be set to 2.
cPoints
Specifies the number of POINT structures in the array pointed to by the lpPoints parameter.

Return Values

If the function succeeds, the low-order word of the return value is the number of pixels added to the horizontal coordinate of each source point in order to compute the horizontal coordinate of each destination point; the high-order word is the number of pixels added to the vertical coordinate of each source point in order to compute the vertical coordinate of each destination point.

Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

See Also

ClientToScreen, POINT, RECT, ScreenToClient


MaskBlt

This function combines the color data for the source and destination bitmaps using the specified mask and raster operation.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MaskBlt(HDC hdcDest, int nXDest, int nYDest, int nWidth, int nHeight, HDC hdcSrc, int nXSrc, int nYSrc, HBITMAP hbmMask, int xMask, int yMask, DWORD dwRop);

Parameters

hdcDest
[in] Handle to the destination device context.
nXDest
[in] Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.
nYDest
[in] Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.
nWidth
[in] Specifies the width, in logical units, of the destination rectangle and source bitmap.
nHeight
[in] Specifies the height, in logical units, of the destination rectangle and source bitmap.
hdcSrc
[in] Handle to the device context from which the bitmap is to be copied. It must be zero if the dwRop parameter specifies a raster operation that does not include a source.
nXSrc
[in] Specifies the logical x-coordinate of the upper-left corner of the source bitmap.
nYSrc
[in] Specifies the logical y-coordinate of the upper-left corner of the source bitmap.
hbmMask
[in] Handle to the monochrome mask bitmap combined with the color bitmap in the source device context.
xMask
[in] Specifies the horizontal pixel offset for the mask bitmap specified by the hbmMask parameter.
yMask
[in] Specifies the vertical pixel offset for the mask bitmap specified by the hbmMask parameter.
dwRop
[in] Specifies both foreground and background ternary raster operation codes that the function uses to control the combination of source and destination data. The background raster operation code is stored in the high-order byte of the high-order word of this value; the foreground raster operation code is stored in the low-order byte of the high-order word of this value; the low-order word of this value is ignored, and should be zero. The macro MAKEROP4 creates such combinations of foreground and background raster operation codes.

For a discussion of foreground and background in the context of this function, see the following Remarks section.

For a list of common raster operation codes, see the BitBlt function.

Windows CE versions 1.0 and 1.01 support only the SRCCOPY and SRCINVERT raster operations.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

A value of 1 in the mask specified by hbmMask indicates that the foreground raster operation code specified by dwRop should be applied at that location. A value of 0 in the mask indicates that the background raster operation code specified by dwRop should be applied at that location.

If the raster operations require a source, the mask rectangle must cover the source rectangle. If it does not, the function will fail. If the raster operations do not require a source, the mask rectangle must cover the destination rectangle. If it does not, the function will fail.

If a rotation or shear transformation is in effect for the source device context when this function is called, an error occurs. However, other types of transformation are allowed.

If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format.

If the mask bitmap is not a monochrome bitmap, an error occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

Not all devices support the MaskBlt function. An application should call the GetDeviceCaps function to determine whether a device supports this function.

If no mask bitmap is supplied, this function behaves exactly like BitBlt, using the foreground raster operation code.

See Also

BitBlt, GetDeviceCaps, StretchBlt


MessageBeep

This function plays a waveform sound.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

BOOL MessageBeep(UINT uType);

Parameters

uType
[in] Specifies the sound type, as identified by an entry in the [sounds] section of the registry. It is one of the following values:
Value
Description
0xFFFFFFFF | SystemDefault
MB_ICONASTERISK | SystemAsterisk
MB_ICONEXCLAMATION | SystemExclamation
MB_ICONHAND | SystemHand
MB_ICONQUESTION | SystemQuestion
MB_OK | SystemDefault

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

After queuing the sound, the MessageBeep function returns control to the calling function and plays the sound asynchronously.

If it cannot play the specified alert sound, MessageBeep attempts to play the system default sound. If it cannot play the system default sound, the function produces a standard beep sound through the computer speaker.

The user can disable the warning beep by using the Sound Control Panel application.

See Also

MessageBox


MessageBox

This function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int MessageBox(HWND hWnd, LPCTSTR lpText, LPCTSTR lpCaption,
UINT uType);

Parameters

hWnd
[in] Handle to the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.
lpText
[in] Long pointer to a null-terminated string that contains the message to be displayed.
lpCaption
[in] Long pointer to a null-terminated string used for the dialog box title. If this parameter is NULL, the default title “Error” is used.
uType
[in] Specifies a set of bit flags that determine the contents and behavior of the dialog box. This parameter can be a combination of flags from the following groups of flags.

Specify one of the following flags to indicate the buttons contained in the message box:
Value
Description
MB_ABORTRETRYIGNORE | The message box contains three push buttons: Abort, Retry, and Ignore.
MB_OK | The message box contains one push button: OK. This is the default.
MB_OKCANCEL | The message box contains two push buttons: OK and Cancel.
MB_RETRYCANCEL | The message box contains two push buttons: Retry and Cancel.
MB_YESNO | The message box contains two push buttons: Yes and No.
MB_YESNOCANCEL | The message box contains three push buttons: Yes, No, and Cancel.

Specify one of the following flags to display an icon in the message box:
Value
Description
MB_ICONEXCLAMATION, MB_ICONWARNING | An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK | An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_ICONQUESTION | A question-mark icon appears in the message box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND | A stop-sign icon appears in the message box.

Specify one of the following flags to indicate the default button:
Value
Description
MB_DEFBUTTON1 | The first button is the default button.
MB_DEFBUTTON1 is the default unless MB_DEFBUTTON2, MB_DEFBUTTON3, or MB_DEFBUTTON4 is specified.
MB_DEFBUTTON2 | The second button is the default button.
MB_DEFBUTTON3 | The third button is the default button.
MB_DEFBUTTON4 | The fourth button is the default button.

The following flag is the default modality of the dialog box:
Value
Description
MB_APPLMODAL The user must respond to the message box before continuing work in the window identified by the hWnd parameter. However, the user can move to the windows of other threads and work in those windows.
Depending on the hierarchy of windows in the application, the user may be able to move to other windows within the thread. All child windows of the parent of the message box are automatically disabled, but popup windows are not.

In addition, you can specify the following flags:
Value
Description
MB_SETFOREGROUND | The message box becomes the foreground window. Internally, the system calls the SetForegroundWindow function for the message box.
MB_TOPMOST | The message box is created with the WS_EX_TOPMOST window style.

Return Values

Zero indicates that there is not enough memory to create the message box.

Upon success, one of the values described in the following table is returned.

Value
Description
IDABORT | Abort button was selected.
IDCANCEL | Cancel button was selected.
IDIGNORE | Ignore button was selected.
IDNO | No button was selected.
IDOK | OK button was selected.
IDRETRY | Retry button was selected.
IDYES | Yes button was selected.

If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect.

Remarks

If you create a message box while a dialog box is present, use the handle of the dialog box as the hWnd parameter. The hWnd parameter should not identify a child window, such as a control in a dialog box.

See Also

MessageBeep, SetForegroundWindow


mouse_event

This function synthesizes mouse motion and button clicks.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

VOID mouse_event(DWORD dwFlags, DWORD dx, DWORD dy,
DWORD dwData, DWORD dwExtraInfo );

Parameters

dwFlags
Specifies various aspects of mouse motion and button clicking. The bits in this parameter can be any reasonable combination of the following values:
Value
Description
MOUSEEVENTF_ABSOLUTE | Specifies that the dx and dy parameters contain normalized absolute coordinates. If not set, those parameters contain relative data: the change in position since the last reported position. This flag can be set, or not set, regardless of what kind of mouse or mouse-like device, if any, is connected to the system. For further information about relative mouse motion, see the following Remarks section.
MOUSEEVENTF_MOVE | Specifies that movement occurred.
MOUSEEVENTF_LEFTDOWN | Specifies that the left button is down.
MOUSEEVENTF_LEFTUP | Specifies that the left button is up.
MOUSEEVENTF_RIGHTDOWN | Specifies that the right button is down.
MOUSEEVENTF_RIGHTUP | Specifies that the right button is up.
MOUSEEVENTF_MIDDLEDOWN | Specifies that the middle button is down.
MOUSEEVENTF_MIDDLEUP | Specifies that the middle button is up.

dx
Specifies the mouse’s absolute position along the x-axis or its amount of motion since the last mouse event was generated, depending on the setting of MOUSEEVENTF_ABSOLUTE. Absolute data is given as the mouse’s actual x-coordinate; relative data is given as the number of mickeys moved. A mickey is the amount that a mouse has to move for it to report that it has moved.
dy
Specifies the mouse’s absolute position along the y-axis or its amount of motion since the last mouse event was generated, depending on the setting of MOUSEEVENTF_ABSOLUTE. Absolute data is given as the mouse’s actual y-coordinate; relative data is given as the number of mickeys moved.
dwData
If dwFlags is MOUSEEVENTF_WHEEL, then dwData specifies the amount of wheel movement. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user. One wheel click is defined as WHEEL_DELTA, which is 120.

If dwFlags is not MOUSEEVENTF_WHEEL, then dwData should be zero.

dwExtraInfo
Unsupported.

Return Values

None.

Remarks

If the mouse has moved, indicated by MOUSEEVENTF_MOVE being set, dx and dy hold information about that motion. The information is given as absolute or relative integer values.

If MOUSEEVENTF_ABSOLUTE value is specified, dx and dy contain normalized absolute coordinates between 0 and 65,535. The event procedure maps these coordinates onto the display surface. Coordinate (0,0) maps onto the upper-left corner of the display surface, (65535,65535) maps onto the lower-right corner.

If the MOUSEEVENTF_ABSOLUTE value is not specified, dx and dy specify relative motions from when the last mouse event was generated (the last reported position). Positive values mean the mouse moved right (or down); negative values mean the mouse moved left (or up).

Relative mouse motion is subject to the settings for mouse speed and acceleration level. An end user sets these values using the Mouse control panel application. An application obtains and sets these values with the SystemParametersInfo function.

The system applies two tests to the specified relative mouse motion when applying acceleration. If the specified distance along either the x or y axis is greater than the first mouse threshold value, and the mouse acceleration level is not zero, the operating system doubles the distance. If the specified distance along either the x or y axis is greater than the second mouse threshold value, and the mouse acceleration level is equal to two, the operating system doubles the distance that resulted from applying the first threshold test. It is thus possible for the operating system to multiply relatively-specified mouse motion along the x or y axis by up to four times.

Once acceleration has been applied, the system scales the resultant value by the desired mouse speed. Mouse speed can range from 1 (slowest) to 20 (fastest) and represents how much the pointer moves based on the distance the mouse moves. The default value is 10, which results in no additional modification to the mouse motion.

See Also

SystemParametersInfo


MoveWindow

This function changes the position and dimensions of the specified window. For a top-level window, the position and dimensions are relative to the upper-left corner of the screen. For a child window, they are relative to the upper-left corner of the parent window’s client area.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MoveWindow( HWND hWnd, int nX, int nY, int nWidth, int nHeight,
BOOL bRepaint);

Parameters

hWnd
Handle to the window.
X
Specifies the new position of the left side of the window.
Y
Specifies the new position of the top of the window.
nWidth
Specifies the new width of the window.
nHeight
Specifies the new height of the window.
bRepaint
Boolean that specifies whether the window is to be repainted. If this parameter is TRUE, the window receives a WM_PAINT message. If the parameter is FALSE, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of moving a child window. If this parameter is FALSE, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

The bRepaint parameter is ignored and is assumed to be FALSE.

Remarks

If the bRepaint parameter is TRUE, the system sends the WM_PAINT message to the window procedure immediately after moving the window (that is, the MoveWindow function calls the UpdateWindow function). If bRepaint is FALSE, the system places the WM_PAINT message in the message queue associated with the window. The message loop dispatches the WM_PAINT message only after dispatching all other messages in the queue.

MoveWindow sends WM_WINDOWPOSCHANGED, WM_MOVE, and WM_SIZE messages to the window.

See Also

SetWindowPos, UpdateWindow, WM_PAINT


MsgWaitForMultipleObjects

This function returns when one of the specified objects is in the signaled state, or when the time-out interval elapses. This function does not return if there is unread input of the specified type in the queue. It returns only when new input arrives.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

DWORD MsgWaitForMultipleObjectsEx(DWORD nCount,
LPHANDLE pHandles, BOOL fWaitAll, DWORD dwMilliseconds,
DWORD dwWakeMasks);

Parameters

nCount
[in] Specifies the number of object handles in the array pointed to by pHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS minus one.
pHandles
[in] Pointer to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.
fWaitAll
[in] Unsupported; set to FALSE.
dwMilliseconds
[in] Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the criteria specified by the dwWakeMask parameter have not been met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.
dwWakeMask
[in] Specifies input types for which an input event object handle will be added to the array of object handles. This parameter can be any combination of the following values:
Value
Description
QS_ALLEVENTS | An input, WM_TIMER, WM_PAINT, WM_HOTKEY, or posted message is in the queue.
QS_ALLINPUT | Any message is in the queue.
QS_ALLPOSTMESSAGE | A posted message (other than those listed here) is in the queue.
QS_HOTKEY | A WM_HOTKEY message is in the queue.
QS_INPUT | An input message is in the queue.
QS_KEY | A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE | A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEBUTTON | A mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEMOVE | A WM_MOUSEMOVE message is in the queue.
QS_PAINT | A WM_PAINT message is in the queue.
QS_POSTMESSAGE | A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE | A message sent by another thread or application is in the queue.
QS_TIMER | A WM_TIMER message is in the queue.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. The successful return value is one of the following:

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount –1)
The return value minus WAIT_OBJECT_0 indicates the pHandles array index of the object that satisfied the wait.
WAIT_OBJECT_0 + nCount
New input of the type specified in the dwWakeMask parameter is available in the thread’s input queue. Functions such as PeekMessage and GetMessage mark messages in the queue as old messages. Therefore, after you call one of these functions, a subsequent call to MsgWaitForMultipleObjects will not return until new input of the specified type arrives.

This value is also returned upon the occurrence of a system event that requires the thread’s action, such as foreground activation. Therefore, MsgWaitForMultipleObjects can return even though no appropriate input is available and even if dwWaitMask is set to 0. If this occurs, call PeekMessage or GetMessage to process the system event before trying the call to MsgWaitForMultipleObjects again.

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount –1)
The return value minus WAIT_ABANDONED_0 indicates the pHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_TIMEOUT
The time-out interval elapsed and the conditions specified by the dwWakeMask parameter were not satisfied.

0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

Remarks

The MsgWaitForMultipleObjects function is implemented as a macro that calls MsgWaitForMultipleObjectsEx, passing 0 in the dwFlags parameter.

The MsgWaitForMultipleObjects function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, using very little processor time while waiting for the conditions of the wait criteria to be met.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one. When fWaitAll is FALSE, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the objects not selected are unaffected.

The MsgWaitForMultipleObjects function can specify handles of the following object types in the pHandles array:

  • Event
  • Mutex
  • Critical section

The QS_ALLPOSTMESSAGE and QS_POSTMESSAGE flags differ in when they are cleared. QS_POSTMESSAGE is cleared when you call GetMessage or PeekMessage, whether or not you are filtering messages. QS_ALLPOSTMESSAGE is cleared when you call GetMessage or PeekMessage without filtering messages (wMsgFilterMin and wMsgFilterMax are 0). This can be useful when you call PeekMessage multiple times to get messages in different ranges.

See Also

MsgWaitForMultipleObjectsEx , WaitForMultipleObjects


MsgWaitForMultipleObjectsEx

This function returns when either one or all of the specified objects are in the signaled state, an I/O completion routine or asynchronous procedure call (APC) is queued to the thread, or the time-out interval elapses. This function does not return if there is unread input of the specified type in the queue. It returns only when new input arrives.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

DWORD MsgWaitForMultipleObjectsEx(DWORD nCount
LPHANDLE pHandles DWORD dwMilliseconds, DWORD dwWakeMask, DWORD dwFlags);

Parameters

nCount
[in] Specifies the number of object handles in the array pointed to by pHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS minus one.
pHandles
[in] Pointer to an array of object handles. For a list of the object types whose handles you can specify, see the Remarks section later in this topic. The array can contain handles to multiple types of objects.
dwMilliseconds
[in] Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the dwWakeMask and dwFlags parameters are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.
dwWakeMask
[in] Specifies input types for which an input event object handle will be added to the array of object handles. This parameter can be any combination of the following values:
Value
Description
QS_ALLEVENTS | An input, WM_TIMER, WM_PAINT, WM_HOTKEY, or posted message is in the queue.
QS_ALLINPUT | Any message is in the queue.
QS_ALLPOSTMESSAGE | A posted message (other than those listed here) is in the queue.
QS_INPUT | An input message is in the queue.
QS_KEY | A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE | A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_LBUTTONDOWN, and so on) is in the queue.
QS_MOUSEBUTTON | A mouse-button message (WM_LBUTTONUP, WM_LBUTTONDOWN, and so on) is in the queue.
QS_MOUSEMOVE | A WM_MOUSEMOVE message is in the queue.
QS_PAINT | A WM_PAINT message is in the queue.
QS_POSTMESSAGE | A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE | A message sent by another thread or application is in the queue.
QS_TIMER | A WM_TIMER message is in the queue.

dwFlags
[in] Specifies the wait type. It can be any combination of the following values:
Value
Description
0 | The function returns when any one of the objects is signaled. The return value indicates the object whose state caused the function to return.
MWMO_INPUTAVAILABLE | The function returns if input exists for the queue, even if the input has been seen (but not removed) using a call to another function, such as PeekMessage.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. The successful return value is one of the following:

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount –1)
If the MWMO_WAITALL flag is used, the return value indicates that the state of all specified objects is signaled. Otherwise, the return value minus WAIT_OBJECT_0 indicates the pHandles array index of the object that caused the function to return.
WAIT_OBJECT_0 + nCount
New input of the type specified in the dwWakeMask parameter is available in the thread’s input queue. Functions such as PeekMessage and GetMessage mark messages in the queue as old messages. Therefore, after you call one of these functions, a subsequent call to MsgWaitForMultipleObjectsEx will not return until new input of the specified type arrives.

This value is also returned upon the occurrence of a system event that requires the thread’s action, such as foreground activation. Therefore, MsgWaitForMultipleObjectsEx can return even though no appropriate input is available and even if dwWaitMask is set to 0. If this occurs, call PeekMessage or GetMessage to process the system event before trying the call to MsgWaitForMultipleObjectsEx again.

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount –1)
If the MWMO_WAITALL flag is used, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. Otherwise, the return value minus WAIT_ABANDONED_0 indicates the pHandles array index of an abandoned mutex object that caused the function to return.
WAIT_IO_COMPLETION
The wait was ended by a user-mode asynchronous procedure call (APC) queued to the thread.
WAIT_TIMEOUT
The time-out interval elapsed, but the conditions specified by the dwFlags and dwWakeMask parameters were not met.

0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

Remarks

The MsgWaitForMultipleObjectsEx function determines whether the conditions specified by dwWakeMask and dwFlags have been met. If the conditions have not been met, the calling thread enters an efficient wait state. The thread uses very little processor time while waiting for one of the conditions to be met or for the time-out interval to elapse.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the system decreases the count of a semaphore object by one. When dwFlags is zero, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the objects not selected are unaffected.

The MsgWaitForMultipleObjectsEx function copies the handle table, adds to it the message queue event, and calls WaitForMultipleObjects.

The MsgWaitForMultipleObjectsEx function can specify handles of any of the following object types in the pHandles array:

  • Event
  • Mutex
  • Critical section

The QS_ALLPOSTMESSAGE and QS_POSTMESSAGE flags differ in when they are cleared. QS_POSTMESSAGE is cleared when you call GetMessage or PeekMessage, whether or not you are filtering messages. QS_ALLPOSTMESSAGE is cleared when you call GetMessage or PeekMessage without filtering messages (wMsgFilterMin and wMsgFilterMax are 0). This can be useful when you call PeekMessage multiple times to get messages in different ranges.


OffsetRgn

This function moves a region by the specified offsets.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int OffsetRgn(HRGN hrgn, int nXOffset, int nYOffset);

Parameters

hrgn
[in] Handle to the region to be moved.
nXOffset
[in] Specifies the number of logical units to move left or right.
nYOffset
[in] Specifies the number of logical units to move up or down.

Return Values

The return value specifies the new region’s complexity. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than a single rectangle. ERROR indicates that an error occurred; the current clipping region is unaffected.


OpenClipboard

This function opens the clipboard for examination and prevents other applications from modifying the clipboard content.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL OpenClipboard(HWND hWndNewOwner);

Parameters

hWndNewOwner
[in] Handle to the window to be associated with the open clipboard. If this parameter is NULL, the open clipboard is associated with the current task.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

OpenClipboard fails if another window has the clipboard open.

An application should call the CloseClipboard function after every successful call to OpenClipboard.

The window identified by the hWndNewOwner parameter does not become the clipboard owner unless the EmptyClipboard function is called.

See Also

CloseClipboard, EmptyClipboard


PagePaintHook

This function is an application-defined or library-defined callback function used with the PageSetupDlg function. PagePaintHook receives messages that allow you to customize drawing of the sample page in the Page Setup dialog box.

The LPPAGEPAINTHOOK type defines a pointer to this callback function. PagePaintHook is a placeholder for the application-defined or library-defined function name.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.10 and later

Syntax

UINT CALLBACK PagePaintHook(HWND hdlg, UINT uiMsg,
WPARAM wParam, LPARAM lParam);

Parameters

hdlg
Handle to the Page Setup dialog box window.
uiMsg
Identifies the message being received.
wParam
Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.
lParam
Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

Return Values

If the hook procedure returns TRUE for any of the first three messages of a drawing sequence (WM_PSD_PAGESETUPDLG, WM_PSD_FULLPAGERECT, or WM_PSD_MINMARGINRECT), the dialog box sends no more messages and does not draw in the sample page until the next time the system needs to redraw the sample page. If the hook procedure returns FALSE for all three messages, the dialog box sends the remaining messages of the drawing sequence.

If the hook procedure returns TRUE for any of the remaining messages in a drawing sequence, the dialog box does not draw the corresponding portion of the sample page. If the hook procedure returns FALSE for any of these messages, the dialog box draws that portion of the sample page.

Remarks

The Page Setup dialog box includes an image of a sample page that shows how user selections affect the appearance of the printed output. The image consists of a rectangle that represents the selected paper or envelope type, with a dotted-line rectangle representing the current margins, and partial (Greek text) characters to show how text looks on the printed page. When you use the PageSetupDlg function to create a Page Setup dialog box, you can provide a PagePaintHook hook procedure to customize the appearance of the sample page.

To enable the hook procedure, use the PAGESETUPDLG structure that you passed to the dialog creation function. Specify the pointer to the hook procedure in the lpfnPagePaintHook member and specify the PSD_ENABLEPAGEPAINTHOOK flag in the Flags member.

When the dialog box is about to draw the contents of the sample page, the hook procedure receives messages in a specific order. The following table lists the messages in the order in which they are received.

Message
Description
WM_PSD_PAGESETUPDLG | The dialog box is about to draw the sample page. The hook procedure can use this message to prepare to draw the contents of the sample page.
WM_PSD_FULLPAGERECT | The dialog box is about to draw the sample page. This message specifies the bounding rectangle of the sample page.
WM_PSD_MINMARGINRECT | The dialog box is about to draw the sample page. This message specifies the margin rectangle.
WM_PSD_MARGINRECT | The dialog box is about to draw the margin rectangle.
WM_PSD_GREEKTEXTRECT | The dialog box is about to draw the Greek text inside the margin rectangle.
WM_PSD_ENVSTAMPRECT | The dialog box is about to draw in the envelope-stamp rectangle of an envelope sample page. This message is sent for envelopes only.
WM_PSD_YAFULLPAGERECT | The dialog box is about to draw the return address portion of an envelope sample page. This message is sent for envelopes and other paper sizes.


PageSetupDlg

This function creates a Page Setup dialog box that enables the user to specify the attributes of a printed page. These attributes include the paper size and source, the page orientation—portrait or landscape—and the width of the page margins.

For Windows CE versions 2.10 and later, this function replaces the PrintDlg function.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.10 and later

Syntax

BOOL PageSetupDlg( LPPAGESETUPDLG lppsd );

Parameters

lppsd
Long pointer to a PAGESETUPDLG structure that contains information used to initialize the dialog box. The structure receives information about the user’s selections when the function returns.

Return Values

If the user clicks the OK button, the return value is nonzero. The members of the PAGESETUPDLG structure pointed to by the lppsd parameter indicate the user’s selections.

If the user cancels or closes the Page Setup dialog box or an error occurs, the return value is zero. To get extended error information, use the CommDlgExtendedError function. One of the values shown in the following table is returned.

Value
Value
CDERR_DIALOGFAILURE | CDERR_NOTEMPLATE
CDERR_FINDRESFAILURE | CDERR_REGISTRYFAILURE
CDERR_INITIALIZATION | CDERR_STRUCTSIZE
CDERR_LOADRESFAILURE | PDERR_CREATEDCFAILURE
CDERR_LOADSTRFAILURE | PDERR_NOPORTS
CDERR_LOCKRESFAILURE | PDERR_NOPRINTERS
CDERR_MEMALLOCFAILURE | PDERR_PRINTERNOTFOUND
CDERR_NOHINSTANCE | PDERR_RETDEFFAILURE
CDERR_NOHOOK

For more information about these error values, see CommDlgExtendedError.

Remarks

To create your own print dialog, you must use the dialog template. Items on this template cannot be deleted however, items can be hidden, modified, and added.

The PageSetupDlg function fills the DEVNAMES structure with byte offsets rather than the expected character offsets.

See Also

CommDlgExtendedError, PAGESETUPDLG, DEVNAMES


PageSetupHook

This function is an application-defined or library-defined callback function used with the PageSetupDlg function. PageSetupHook receives messages or notifications intended for the default dialog box procedure of the Page Setup common dialog box.

The LPPAGESETUPHOOK type defines a pointer to this callback function. PageSetupHook is a placeholder for the application-defined or library-defined function name.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.10 and later

Syntax

UINT CALLBACK PageSetupHook(HWND hdlg, UINT uiMsg,
WPARAM wParam, LPARAM lParam);

Parameters

hdlg
Handle to the Page Setup dialog box window for which the message is intended.
uiMsg
Identifies the message being received.
wParam
Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.
lParam
Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a PAGESETUPDLG structure containing the values specified when the common dialog box was created.

Return Values

If the hook procedure returns zero, the default dialog box procedure processes the message.

If the hook procedure returns a nonzero value, the default dialog box procedure ignores the message.

Remarks

When you use the PageSetupDlg function to create a Page Setup common dialog box, you can provide a PageSetupHook hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the PAGESETUPDLG structure that you passed to the dialog creation function. Specify the pointer to the hook procedure in the lpfnPageSetupHook member and specify the PSD_ENABLEPAGESETUPHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.


PatBlt

This function paints the given rectangle using the brush that is currently selected into the specified device context. The brush pixels and the surface pixels are combined according to the specified raster operation.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL PatBlt(HDC hdc, int nXLeft, int nYLeft, int nWidth, int nHeight, DWORD dwRop);

Parameters

hdc
[in] Handle to the device context.
nXLeft
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the rectangle to be filled.
nYLeft
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the rectangle to be filled.
nWidth
[in] Specifies the width, in logical units, of the rectangle.
nHeight
Specifies the height, in logical units, of the rectangle.
dwRop
[in] Specifies the raster operation code. This code may be one of the following values:
Value
Description
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean OR operator.
DSTINVERT | Inverts the destination rectangle.
BLACKNESS | Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
WHITENESS | Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The values of the dwRop parameter for this function are a limited subset of the full 256 ternary raster-operation codes; in particular, an operation code that refers to a source rectangle cannot be used.

Not all devices support the PatBlt function. For more information, see the description of the RC_BITBLT capability in the GetDeviceCaps function.

See Also

BitBlt, GetDeviceCaps


PeekMessage

This function checks a thread message queue for a message and places the message (if any) in the specified structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL PeekMessage(LPMSG lpMsg, HWND hWnd, UINT wMsgFilterMin, UINT wMsgFilterMax, UINT wRemoveMsg);

Parameters

lpMsg
[in] Long pointer to an MSG structure that receives message information.
hWnd
[in] Handle to the window whose messages are to be examined.
wMsgFilterMin
[in] Specifies the value of the first message in the range of messages to be examined.
wMsgFilterMax
[in] Specifies the value of the last message in the range of messages to be examined.
wRemoveMsg
[in] Specifies how messages are handled. This parameter can be one of the following values:
Value
Description
PM_NOREMOVE
 Messages are not removed from the queue after processing by PeekMessage.
PM_REMOVE
 Messages are removed from the queue after processing by PeekMessage. An exception is WM_PAINT messages, which are not removed from the queue.

You can optionally combine the value PM_NOYIELD with either PM_NOREMOVE or PM_REMOVE. This flag prevents the system from releasing any thread that is waiting for the caller to go idle.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

Unlike the GetMessage function, the PeekMessage function does not wait for a message to be placed in the queue before returning.

PeekMessage retrieves only messages associated with the window identified by the hWnd parameter or any of its children as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, PeekMessage retrieves messages for any window that belongs to the current thread making the call. (PeekMessage does not retrieve messages for windows that belong to other threads.) If hWnd is –1, PeekMessage only returns messages with a hWnd value of NULL, as posted by the PostThreadMessage function. If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all keyboard messages; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse messages.

The PeekMessage function does not remove WM_PAINT messages from the queue. WM_PAINT messages remain in the queue until they are processed.

See Also

GetMessage, IsChild, MSG


PlaySound

The PlaySound function plays a sound specified by the specified file name, resource, or system event.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI PlaySound( LPCSTR pszSound, HMODULE hmod,
DWORD fdwSound);

Parameters

pszSound
Pointer to a null-terminated string that specifies the sound to play. If this parameter is NULL, any currently playing waveform sound is stopped. To stop a non-waveform sound, specify SND_PURGE in the fdwSound parameter.

Three flags in fdwSound (SND_ALIAS, SND_FILENAME, and SND_RESOURCE) determine whether the name is interpreted as an alias for a system event, a filename, or a resource identifier. If none of these flags are specified, PlaySound searches the registry or the WIN.INI file for an association with the specified sound name. If an association is found, the sound event is played. If no association is found in the registry, the name is interpreted as a filename.

hmod
Handle to the executable file that contains the resource to be loaded. This parameter must be NULL unless SND_RESOURCE is specified in fdwSound.
fdwSound
Flags for playing the sound. The following values are defined:
Value
Description
SND_APPLICATION | The sound is played using an application-specific association.
SND_ALIAS | The pszSound parameter is a system-event alias in the registry or the WIN.INI file. Do not use with either SND_FILENAME or SND_RESOURCE.
SND_ASYNC | The sound is played asynchronously and PlaySound returns immediately after beginning the sound. To terminate an asynchronously played waveform sound, call PlaySound with pszSound set to NULL.
SND_FILENAME | The pszSound parameter is a filename.
SND_LOOP | The sound plays repeatedly until PlaySound is called again with the pszSound parameter set to NULL. You must also specify the SND_ASYNC flag to indicate an asynchronous sound event.
SND_MEMORY | A sound event’s file is loaded in RAM. The parameter specified by pszSound must point to an image of a sound in memory.
SND_NODEFAULT | No default sound event is used. If the sound cannot be found, PlaySound returns silently without playing the default sound.
SND_NOSTOP | The specified sound event will yield to another sound event that is already playing. If a sound cannot be played because the resource needed to generate that sound is busy playing another sound, the function immediately returns FALSE without playing the requested sound.
If this flag is not specified, PlaySound attempts to stop the currently playing sound so that the device can be used to play the new sound.
SND_NOWAIT | If the driver is busy, return immediately without playing the sound.
SND_RESOURCE | The pszSound parameter is a resource identifier; hmod must identify the instance that contains the resource.
SND_SYNC | Synchronous playback of a sound event. PlaySound returns after the sound event completes.

Return Values

TRUE indicates success. FALSE indicates failure.

Windows CE Remarks

Windows CE does not support the SND_ALIAS_ID and SND_PURGE flags for the fdwSound parameter.

Remarks

The sound specified by pszSound must fit into available physical memory and be playable by an installed waveform-audio device driver. PlaySound searches the following directories for sound files: the current directory; the Windows CE directory; the Windows CE system directory; directories listed in the PATH environment variable; and the list of directories mapped in a network. For more information about the directory search order, see the documentation for the OpenFile function.

If it cannot find the specified sound, PlaySound uses the default system event sound entry instead. If the function can find neither the system default entry nor the default sound, it makes no sound and returns FALSE.

See Also

sndPlaySound


Polygon

This function draws a polygon consisting of two or more vertices connected by straight lines. The current pen outlines the polygon, and the current brush fills it using the specified polygon fill mode.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL Polygon(HDC hdc, const POINT *lpPoints, int nCount);

Parameters

hdc
[in] Handle to the device context.
lpPoints
[in] Long pointer to an array of POINT structures that specify the vertices of the polygon.
nCount
[in] Specifies the number of vertices in the array. This value must be greater than or equal to 2.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The polygon is closed automatically by drawing a line from the last vertex to the first.

The current position is neither used nor updated by the Polygon function.

Windows CE versions 1.0 and 1.01 support only convex polygons.

See Also

POINT, Polyline


Polyline

This function draws a series of line segments by connecting the points in the specified array.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL Polyline(HDC hdc, const POINT * lppt, int cPoints);

Parameters

hdc
[in] Handle to a device context.
lppt
[in] Long pointer to an array of POINT structures. Each structure in the array identifies a point in logical space.
cPoints
[in] Specifies the number of points in the array. This number must be greater than or equal to two.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The lines are drawn from the first point through subsequent points by using the current pen. Unlike the LineTo function, the Polyline function neither uses nor updates the current position.

See Also

POINT


PostKeybdMessage

This function posts a keyboard message to the specified window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL PostKeybdMessage( HWND hwnd, UINT VKey, KEY_STATE_FLAGS KeyStateFlags, UINT cCharacters,
UINT *pShiftStateBuffer, UINT*pCharacterBuffer );

Parameters

hwnd
[in] Handle to the window that receives the message. It must identify a window owned by the calling thread. If hwnd is NULL, then the keyboard message is sent to the active window or window with the focus of the calling thread. If hwnd is –1, then the keyboard message is sent to the active window or window with the focus of the system foreground thread.
VKey
[in] Virtual key code. This parameter can be set to 0.
KeyStateFlags
[in] State of the key. The key states are described in the following table.
Flag
Description
KeyStateToggledFlag | Key is toggled.
KeyStatePrevDownFlag | Key was previously down.
KeyStateDownFlag | Key is currently down.
KeyShiftAnyCtrlFlag | Left or right CTRL key is down.
KeyShiftAnyShiftFlag | Left or right SHIFT key is down.
KeyShiftAnyAltFlag | Left or right ALT key is down.
KeyShiftCapitalFlag | VK_CAPITAL is toggled.
KeyShiftLeftCtrlFlag | Left CTRL key is down.
KeyShiftLeftShiftFlag | Left SHIFT key is down.
KeyShiftLeftAltFlag | Left ALT key is down.
KeyShiftLeftWinFlag | Left Windows logo key is down.
KeyShiftRightCtrlFlag | Right CTRL key is down.
KeyShiftRightShiftFlag | Right SHIFT key is down.
KeyShiftRightAltFlag | Right ALT key is down.
KeyShiftRightWinFlag | Right Windows logo key is down.
KeyShiftDeadFlag | Corresponding character is dead character.
KeyShiftNoCharacterFlag | No characters in pCharacterBuffer to translate.

cCharacters
[in] Number of characters in the pCharacterBuffer array.
pCharacterBuffer
[in] Pointer to a buffer that contains the characters to send. This parameter cannot be NULL.
pShiftStatBuffer
[in] Pointer to a buffer that contains a corresponding shift state entry for each character in the pCharacterBuffer array. The shift state for each character must be the same as the KeyStateFlags parameter. This parameter cannot be NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The characters in pCharacterBuffer are the characters posted to the receiver’s queue when TranslateMessage is called for the VK key event. Unlike the keybd_event function, PostKeybdMessage does not affect the global key state.

PostKeybdMessage does not support a different state for each translated character. If a different state is required for each character, then individual calls to PostKeybdMessage must be made.

If VKey is set to 0 when TranslateMessage is called, then the virtual key translation is also set to 0. Because 0 is not valid for virtual key, an application should ignore it.


PostMessage

This function places a message in the message queue associated with the thread that created the specified window and then returns without waiting for the thread to process the message. Messages in a message queue are retrieved by calls to the GetMessage or PeekMessage function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL PostMessage(HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam);

Parameters

hWnd
[in] Handle to the window whose window procedure is to receive the message. Two values have special meanings:
Value
Description
HWND_BROADCAST | The message is posted to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows. The message is not posted to child windows.
NULL | The function behaves like a call to PostThreadMessage with the dwThreadId parameter set to the identifier of the current thread.

Msg
[in] Specifies the message to be posted.
wParam
[in] Specifies additional message-specific information.
lParam
[in] Specifies additional message-specific information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage, SendNotifyMessage, and SendMessageCallback), its message parameters can not include pointers. Otherwise, the operation will fail. The functions will return before the receiving thread has had a chance to process the message and the sender will free the memory before it is used.

See Also

GetMessage, PeekMessage, PostThreadMessage, SendDlgItemMessage, SendMessage


PostQuitMessage

This function indicates to Windows that a thread has made a request to terminate (quit). It is typically used in response to a WM_DESTROY message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

void PostQuitMessage(int nExitCode);

Parameters

nExitCode
[in] Specifies an application exit code. This value is used as the wParam parameter of the WM_QUIT message.

Return Values

None.

Remarks

The PostQuitMessage function posts a WM_QUIT message to the thread’s message queue and returns immediately; the function simply indicates to the system that the thread is requesting to quit at some time in the future.

When the thread retrieves the WM_QUIT message from its message queue, it should exit its message loop and return control to the system. The exit value returned to the system must be the wParam parameter of the WM_QUIT message.

See Also

GetMessage, PeekMessage, PostMessage, WM_DESTROY, WM_QUIT


PostThreadMessage

This function places a message in the message queue of the specified thread and then returns without waiting for the thread to process the message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL PostThreadMessage(DWORD idThread, UINT Msg,
WPARAM wParam, LPARAM lParam);

Parameters

idThread
[in] Identifier of the thread to which the message will be posted.

The function fails if the specified thread does not have a message queue. The system creates a thread's message queue when the thread makes its first call to one of the Win32 USER or GDI functions. For more information, see the Remarks section.

Msg
[in] Specifies the type of message to be posted.
wParam
[in] Specifies additional message-specific information.
lParam
[in] Specifies additional message-specific information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. GetLastError returns ERROR_INVALID_THREAD_ID if idThread is not a valid thread identifier, or if the thread specified by idThread does not have a message queue.

Remarks

The thread to which the message is posted must have created a message queue, or else the call to PostThreadMessage fails. Use one of the following methods to handle this situation:

  • Call PostThreadMessage. If it fails, call the Sleep function and call PostThreadMessage again. Repeat until PostThreadMessage succeeds.
  • Create an event object, then create the thread. Use the WaitForSingleObject function to wait for the event to be set to the signaled state before calling PostThreadMessage. In the thread to which the message will be posted, call PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE) to force the system to create the message queue. Set the event, to indicate that the thread is ready to receive posted messages.

The thread to which the message is posted retrieves the message by calling the GetMessage or PeekMessage function. The hwnd member of the returned MSG structure is NULL.

See Also

GetCurrentThreadId, GetMessage, MSG, PeekMessage, PostMessage


PrintDlg

This function displays a Print or Print Setup dialog box. The Print dialog box enables the user to specify the properties of a particular print job.

For Windows CE versions 2.10 and later, this function has been replaced by the PageSetupDlg function.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and 2.01

Syntax

BOOL PrintDlg(LPPRINTDLG lppd);

Parameters

lppd
Long pointer to a PRINTDLG structure that contains information used to initialize the dialog box. When PrintDlg returns, this structure contains information about the user’s selections.

Return Values

If the user clicks the OK button, the return value is nonzero. The members of the PRINTDLG structure pointed to by the lppd parameter indicate the user’s selections.

If the user canceled or closed the Print or Printer Setup dialog box or an error occurred, the return value is zero. To get extended error information, use the CommDlgExtendedError function. If the user canceled or closed the dialog box, CommDlgExtendedError returns zero; otherwise, it returns one of the following values:

CDERR_FINDRESFAILURE | PDERR_CREATEICFAILURE
CDERR_INITIALIZATION | PDERR_DEFAULTDIFFERENT
CDERR_LOADRESFAILURE | PDERR_DNDMMISMATCH
CDERR_LOADSTRFAILURE | PDERR_GETDEVMODEFAIL
CDERR_LOCKRESFAILURE | PDERR_INITFAILURE
CDERR_MEMALLOCFAILURE | PDERR_LOADDRVFAILURE
CDERR_MEMLOCKFAILURE | PDERR_NODEFAULTPRN
CDERR_NOHINSTANCE | PDERR_NODEVICES
CDERR_NOHOOK | PDERR_PARSEFAILURE
CDERR_NOTEMPLATE | PDERR_PRINTERNOTFOUND
CDERR_STRUCTSIZE | PDERR_RETDEFFAILURE

Remarks

The PRINTDLG structure contains different members in Windows CE than it does in Windows-based desktop platforms.

If the hook procedure (pointed to by the lpfnPrintHook member of the PRINTDLG structure) processes the WM_CTLCOLORDLG message, the hook procedure must return a handle for the brush that should be used to paint the control background.

Calling PrintDlg with dwFlags equal to PD_RETURNDEFAULTDC causes the function to use the last-saved settings or the default settings. This can cause PrintDlg to fail if the settings are not valid. You should use the manual PrintDlg—that is, without the PD_RETURNDEFAULTDC—to choose a valid printer, port, or other destination to ensure that you can print to it.

When you are done with the device context (DC) returned by PrintDlg, call the DeleteDC function to delete it.

See Also

CommDlgExtendedError, CreateDC, PRINTDLG, PrintHookProc, StartDoc, DeleteDC, WM_CTLCOLORDLG, PageSetupDlg, PAGESETUPDLG


PrintHookProc

This function is an application-defined or library-defined callback function that is used with the Print common dialog box. PrintHookProc receives messages or notifications intended for the default dialog box procedure.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and later

Syntax

UINT APIENTRY PrintHookProc(HWND hdlg, UINT uiMsg,
WPARAM wParam, LPARAM lParam);

Parameters

hdlg
[in] Handle to the Print common dialog box window for which the message is intended.
uiMsg
[in] Identifies the message being received.
wParam
[in] Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.
lParam
[in] Specifies additional information about the message. The exact meaning depends on the value of the uiMsg parameter.

If the uiMsg parameter indicates the WM_INITDIALOG message, lParam is a pointer to a PRINTDLG structure containing the values specified when the common dialog box was created.

Return Values

Zero indicates that the default dialog box procedure processes the message. Nonzero indicates that the default dialog box procedure ignores the message.

Remarks

When you use the PrintDlg function to create a Print common dialog box, you can provide a PrintHookProc hook procedure to process messages or notifications intended for the dialog box procedure. To enable the hook procedure, use the PRINTDLG structure that you passed to the dialog creation function. Specify the address of the hook procedure in the lpfnPrintHook member and specify the PD_ENABLEPRINTHOOK flag in the Flags member.

The default dialog box procedure processes the WM_INITDIALOG message before passing it to the hook procedure. For all other messages, the hook procedure receives the message first. Then, the return value of the hook procedure determines whether the default dialog procedure processes the message or ignores it.

If the hook procedure processes the WM_CTLCOLORDLG message, it must return a valid brush handle for painting the background of the dialog box. In general, if the hook procedure processes any WM_CTLCOLOR* message, it must return a valid brush handle for painting the background of the specified control.

Do not call the EndDialog function from the hook procedure. Instead, the hook procedure can call the PostMessage function to post a WM_COMMAND message with the IDABORT value to the dialog box procedure. Posting IDABORT closes the dialog box and causes the dialog box function to return FALSE. If you need to know why the hook procedure closed the dialog box, you must provide your own communication mechanism between the hook procedure and your application.

You can subclass the standard controls of the common dialog box. However, the common dialog box procedure may also subclass the controls. Because of this, you should subclass controls when your hook procedure processes the WM_INITDIALOG message. This ensures that your subclass procedure receives the control-specific messages before the subclass procedure set by the dialog box procedure.

See Also

EndDialog, PostMessage, PrintDlg, PRINTDLG, WM_INITDIALOG, WM_CTLCOLORDLG


PropertySheet

This function creates a property sheet and adds the pages defined in the specified property sheet header structure.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

int PropertySheet(LPCPROPSHEETHEADER lppsph);

Parameters

lppsph
[in] Long pointer to a PROPSHEETHEADER structure that defines the frame and pages of a property sheet.

Return Values

A positive value indicates success. –1 indicates failure.

If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, the successful return value is the window handle to the property sheet dialog.

The return values described in the following table have a special meaning.

Value
Description
ID_PSREBOOTSYSTEM | A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect.
ID_PSRESTARTWINDOWS | A page sent the PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect.

To get extended error information, call GetLastError.

Remarks

By default, PropertySheet creates a modal dialog. If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, PropertySheet creates a modeless dialog and returns immediately after the dialog is created. In this case, the PropertySheet return value is the window handle to the modeless dialog.

For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog. Your message loop should use PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog. When the user chooses the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

PROPSHEETHEADER, PSM_REBOOTSYSTEM, PSM_RESTARTWINDOWS


PropSheetPageProc

This function is an application-defined callback function that a property sheet calls when a page is created and when it is about to be destroyed. An application can use PropSheetPageProc to perform initialization and cleanup operations for the page.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

UINT CALLBACK PropSheetPageProc(HWND hwnd, UINT uMsg, LPPROPSHEETPAGE ppsp);

Parameters

hwnd
[in] Reserved; set to NULL.
uMsg
[in] Action flag. It is one of the following values:
Value
Description
PSPCB_CREATE | A page is being created. Return nonzero to allow the page to be created, or zero to prevent it.
PSPCB_RELEASE | A page is being destroyed. The return value is ignored.

ppsp
[in] Pointer to a PROPSHEETPAGE structure that defines the page being created or destroyed.

Return Values

The return value depends on the value of uMsg.

Remarks

An application must specify the address of this callback function in the pfnCallback member of a PROPSHEETPAGE structure before specifying the address of the structure in a call to the CreatePropertySheetPage function.

See Also

CreatePropertySheetPage, PROPSHEETPAGE


PropSheetProc

This function is an application-defined callback function that the system calls when the property sheet is being created and initialized.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

void CALLBACK PropSheetProc(HWND hwndDlg, UINT uMsg,
LPARAM lParam);

Parameters

hwndDlg
[in] Handle to the property sheet dialog box.
uMsg
[in] Specifies the message being received. It is one of the following values:
Value
Description
PSCB_INITIALIZED | Indicates that the property sheet is being initialized. The lParam value is zero for this message.
PSCB_PRECREATE | Indicates that the property sheet is about to be created. The hwndDlg parameter is NULL, and the lParam parameter is the address of a dialog template in memory. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.

lParam
[in] Additional information about the message. The meaning of this value depends on the uMsg parameter.

Return Values

None.

Remarks

To enable a PropSheetProc callback function, use the PROPSHEETHEADER structure when you call the PropertySheet function to create the property sheet. Use the pfnCallback member to specify an address of the callback function, and set the PSP_USECALLBACK flag in the dwFlags member.

PropSheetProc is a placeholder for the application-defined function name. The PFNPROPSHEETCALLBACK type is the address of a PropSheetProc callback function.

See Also

PropertySheet, PROPSHEETHEADER


PtInRegion

This function determines whether the specified point is inside the specified region.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL PtInRegion(HRGN hrgn, int X, int Y);

Parameters

hrgn
[in] Handle to the region to be examined.
X
[in] Specifies the x-coordinate of the point.
Y
[in] Specifies the y-coordinate of the point.

Return Values

Nonzero indicates that the specified point is in the region. Zero indicates that the specified point is not in the region.

See Also

RectInRegion


RealizePalette

This function maps palette entries from the current logical palette to the system palette.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

UNIT RealizePalette(HDC hdc);

Parameters

hdc
[in] Handle to the device context (DC) into which a logical palette has been selected.

Return Values

The number of entries in the logical palette mapped to the system palette indicates success. GDI_ERROR indicates failure. To get extended error information, call GetLastError.

Remarks

RealizePalette fails if the device associated with hdc does not have a settable palette. Call the GetDeviceCaps function, specifying the RASTERCAPS constant, to determine if the device has a settable palette before calling RealizePalette.

RealizePalette modifies the palette for the device associated with the specified device context. If the device context is a memory DC, the color table for the bitmap selected into the DC is modified. If the device context is a display DC, the physical palette for that device is modified.

A logical color palette is a buffer between color-intensive applications and the system, allowing these applications to use as many colors as needed without interfering with colors displayed by other windows.

When an application's window has the focus and it calls RealizePalette, the system attempts to realize as many of the requested colors as possible. The same is also true for applications with inactive windows.

Windows CE does not arbitrate between the palettes of the background and foreground applications. The foreground application has complete control of the system palette. Therefore, Windows CE does not perform any color matching operations for foreground applications; it simply overwrites the system palette entries with the hdc parameter’s palette entries.

Windows CE does not support RealizePalette for background applications.

See Also

GetDeviceCaps, SelectPalette


Rectangle

This function draws a rectangle. The current brush outlines the rectangle and the current brush fills it.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL Rectangle(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

hdc
[in] Handle to the device context.
nLeftRect
[in] Specifies the logical x-coordinate of the upper-left corner of the rectangle.
nTopRect
[in] Specifies the logical y-coordinate of the upper-left corner of the rectangle.
nRightRect
[in] Specifies width of the rectangle.
nBottomRect
[in] Specifies height of the rectangle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The current position is neither used nor updated by Rectangle. The extreme bottom and right edges of rectangle are not drawn because the bottom and right coordinates are treated as the width and height respectively of the rectangle instead of its edges.

See Also

RoundRect


RectInRegion

This function determines whether any part of the specified rectangle is within the boundaries of a region.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL RectInRegion(HRGN hrgn, const RECT * lprc);

Parameters

hrgn
[in] Handle to the region.
lprc
[in] Long pointer to a RECT structure that contains the coordinates of the rectangle. The lower and right edges of the rectangle are not included.

Return Values

Nonzero indicates that any part of the specified rectangle lies within the boundaries of the region. Zero indicates that no part of the specified rectangle lies within the boundaries of the region.

See Also

PtInRegion, RECT


RectVisible

This function determines whether any part of the specified rectangle lies within the clipping region of the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL RectVisible( HDC hdc, CONST RECT * lprc);

Parameters

hdc
[in] Handle to the device context.
lprc
[in] Long pointer to a RECT structure that contains the logical coordinates of the specified rectangle.

Return Values

Nonzero indicates that some portion of the specified rectangle lies within the clipping region. Zero indicates that no portion of the specified rectangle lies within the clipping region.

See Also

RectInRegion


RegisterClass

This function registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

ATOM RegisterClass(const WNDCLASS *lpWndClass);

Parameters

lpWndClass
Long pointer to a WNDCLASS structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Return Values

An atom that uniquely identifies the class being registered indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

The WNDCLASS structure pointed to by the lpWndClass parameter does not support the lpszMenuName field because Windows CE does not support default menus.

Unless you are using the Windows CE Iconcurs component, which provides mouse cursor support on appropriate target platforms, you cannot use the hCursor field in the WNDCLASS structure pointed to by lpWndClass.

Remarks

If you register the window class by using RegisterClassA, the application tells the system that the windows of the created class expect messages with text or character parameters to use the ANSI character set; if you register it by using RegisterClassW, the application requests that the system pass text parameters of messages as Unicode.

All window classes that an application registers are unregistered when it terminates.

Windows 95: All window classes registered by a DLL are unregistered when the DLL is unloaded.

Windows NT: No window classes registered by a DLL are unregistered when the DLL is unloaded.

Windows 95: RegisterClass fails if the cbWndExtra or cbClsExtra member of the WNDCLASS structure contains more than 40 bytes.

See Also

CreateWindow, CreateWindowEx, GetClassInfo, GetClassName, UnregisterClass, WindowProc, WNDCLASS


RegisterClipboardFormat

This function registers a new clipboard format. This format can then be used as a valid clipboard format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT RegisterClipboardFormat(LPCWSTR lpszFormat);

Parameters

lpszFormat
[in] Long pointer to a null-terminated string that names the new format.

Return Values

The registered clipboard format indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of RegisterClipboardFormat.

If a registered format with the specified name already exists, a new format is not registered and the return value identifies the existing format. This enables more than one application to copy and paste data using the same registered clipboard format. Note that the format name comparison is case-insensitive.

Registered clipboard formats are identified by values in the range 0xC000 through 0xFFFF.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName


RegisterHotKey

This function defines a system-wide hot key.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL RegisterHotKey( HWND hWnd, int id, UINT fsModifiers, UINT vk );

Parameters

hWnd
[in] Handle to the window that will receive WM_HOTKEY messages generated by the hot key. If this parameter is NULL, WM_HOTKEY messages are posted to the message queue of the calling thread and must be processed in the message loop.
id
[in] Identifier of the hot key. No other hot key in the calling thread should have the same identifier. An application must specify a value in the range 0x0000 through 0xBFFF. A shared dynamic-link library (DLL) must specify a value in the range 0xC000 through 0xFFFF fsModifiers

[in] Specifies keys that must be pressed in combination with the key specified by the nVirtKey parameter in order to generate a WM_HOTKEY message. The fsModifiers parameter can be a combination of the following values:
Value
Description
MOD_ALT | Either ALT key must be held down.
MOD_CONTROL | Either CTRL key must be held down.
MOD_KEYUP | Both key up events and key down events generate a WM_HOTKEY message.
MOD_SHIFT | Either SHIFT key must be held down.
MOD_WIN | Either WINDOWS key was held down. These keys are labeled with the Microsoft Windows logo.

vk
[in] Specifies the virtual-key code of the hot key.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

When a key is pressed, the system looks for a match against all hot keys. Upon finding a match, the system posts the WM_HOTKEY message to the message queue of the thread that registered the hot key. This message is posted to the beginning of the queue so it is removed by the next iteration of the message loop.

RegisterHotKey can be used to register hot keys across threads.

RegisterHotKey fails if the keystrokes specified for the hot key have already been registered by another hot key.

If the window identified by the hWnd parameter already registered a hot key with the same identifier as that specified by the id parameter, the new values for the fsModifiers and vk parameters replace the previously specified values for these parameters.

See Also

UnregisterHotKey, WM_HOTKEY


RegisterWindowMessage

This function defines a new window message that is guaranteed to be unique throughout the system. The returned message value can be used when calling the SendMessage or PostMessage function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

UINT RegisterWindowMessage( LPCTSTR lpString);

Parameters

lpString
Long pointer to a null-terminated string that specifies the message to be registered.

Return Values

A message identifier in the range 0xC000 through 0xFFFF indicates that the message is successfully registered. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The RegisterWindowMessage function is typically used to register messages for communicating between two cooperating applications.

If two different applications register the same message string, the applications return the same message value. The message remains registered until the session ends.

Only use RegisterWindowMessage when more than one application must process the same message. For sending private messages within a window class, an application can use any integer in the range WM_USER through 0x7FFF. (Messages in this range are private to a window class, not to an application. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use values in this range.)

See Also

PostMessage, SendMessage


ReleaseCapture

This function releases the stylus capture from a window in the current thread and restores normal stylus input processing. A window that has captured the stylus receives all stylus input, regardless of the position of the stylus.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ReleaseCapture(void);

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

An application calls this function after calling the SetCapture function.

See Also

GetCapture, SetCapture, WM_CAPTURECHANGED


ReleaseDC

This function releases a device context (DC), freeing it for use by other applications. The effect of ReleaseDC depends on the type of device context.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int ReleaseDC( HWND hWnd, HDC hDC);

Parameters

hWnd
Handle to the window whose device context is to be released.
hDC
Handle to the device context to be released.

Return Values

The return value specifies whether the device context is released. 1 indicates that the device context is released. Zero indicates that the device context is not released.

Remarks

The application must call the ReleaseDC function for each call to the GetWindowDC function and for each call to the GetDC function that retrieves a common device context.

An application cannot use the ReleaseDC function to release a device context that was created by calling the CreateDC function; instead, it must use the DeleteDC function.

See Also

DeleteDC, GetDC, GetWindowDC


RemoveFontResource

This function removes the fonts in the specified file from the Windows CE font table.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL RemoveFontResource(LPCTSTR lpFileName);

Parameters

lpFileName
[in] Long pointer to a null-terminated string that names a font resource file.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

An application that adds or removes fonts from the system font table should notify other windows of the change by sending a WM_FONTCHANGE message to all top-level windows in the system. The application sends this message by calling the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

If there are outstanding references to a font, the associated resource remains loaded until no device context (DC) is using it.

See Also

AddFontResource, SendMessage


RemoveMenu

This function deletes a menu item from the specified menu. If the menu item activates a pop-up menu, RemoveMenu does not destroy the pop-up menu or its handle, allowing the menu to be reused. Before RemoveMenu is called, the GetSubMenu function should retrieve the handle to the pop-up menu.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL RemoveMenu(HMENU hMenu, UINT uPosition, UINT uFlags);

Parameters

hMenu
[in] Handle to the menu to be changed.
uPosition
[in] Specifies the menu item to be deleted, as determined by the uFlags parameter.
uFlags
[in] Specifies how the uPosition parameter is interpreted. This parameter must be one of the following values:
Value
Description
MF_BYCOMMAND | Indicates that uPosition gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION | Indicates that uPosition gives the zero-based relative position of the menu item.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

See Also

CreatePopupMenu, DeleteMenu, GetSubMenu


RestoreDC

This function restores a device context (DC) to the specified state. The device context is restored by popping state information off a stack created by earlier calls to the SaveDC function.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL RestoreDC(HDC hdc, int nSavedDC);

Parameters

hdc
[in] Handle to the device context.
nSavedDC
[in] Specifies the instance of the device context to be restored. If this parameter is positive, nSavedDC represents a specific instance of the device context to be restored. If this parameter is negative, nSavedDC represents an instance relative to the current device context. For example, –1 restores the most recently saved state.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The stack can contain the state information for several instances of the device context. If the state specified by the given parameter is not at the top of the stack, RestoreDC deletes all state information between the top of the stack and the specified instance.

See Also

CreateDC


RoundRect

This function draws a rectangle with rounded corners. The current brush outlines the rectangle and the current brush fills it.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL RoundRect(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect, int nWidth, int nHeight);

Parameters

hdc
[in] Handle to the device context.
nLeftRect
[in] Specifies the x-coordinate of the upper-left corner of the rectangle.
nTopRect
[in] Specifies the y-coordinate of the upper-left corner of the rectangle.
nRightRect
[in] Specifies the x-coordinate of the lower-right corner of the rectangle.
nBottomRect
[in] Specifies the y-coordinate of the lower-right corner of the rectangle.
nWidth
[in] Specifies the width of the ellipse used to draw the rounded corners.
nHeight
[in] Specifies the height of the ellipse used to draw the rounded corners.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The current position is neither used nor updated by this function.

See Also

Rectangle


SaveDC

This function saves the current state of the specified device context by copying data describing selected objects and graphic modes (such as the bitmap, brush, palette, font, pen, region, and drawing mode) to a context stack.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int SaveDC( HDC hdc);

Parameters

hdc
[in] Handle to the device context to be saved.

Return Values

If the function succeeds, the return value identifies the saved device context.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The SaveDC function can be used any number of times to save any number of instances of the device context's state.

A saved state can later be restored by using the RestoreDC function.

See Also

RestoreDC


ScreenToClient

This function converts the screen coordinates of a specified point on the screen to client coordinates.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ScreenToClient( HWND hWnd, LPPOINT lpPoint);

Parameters

hWnd
Handle to the window whose client area will be used for the conversion.
lpPoint
Long pointer to a POINT structure that contains the screen coordinates to be converted.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

Remarks

The function uses the window identified by the hWnd parameter and the screen coordinates given in the POINT structure to compute client coordinates. It then replaces the screen coordinates with the client coordinates. The new coordinates are relative to the upper-left corner of the specified window’s client area.

The ScreenToClient function assumes the specified point is in screen coordinates.

See Also

ClientToScreen, MapWindowPoints, POINT


ScrollDC

This function scrolls a rectangle of bits horizontally and vertically.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ScrollDC(HDC hDC, int dx, int dy, const RECT *lprcScroll,
const RECT *lprcClip, HRGN hrgnUpdate, LPRECT lprcUpdate);

Parameters

hDC
[in] Handle to the device context that contains the bits to be scrolled.
dx
[in] Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left. Only one of the dx and dy parameters can be nonzero.
dy
[in] Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll up. Only one of the dx and dy parameters can be nonzero.
lprcScroll
[in] Long pointer to the RECT structure containing the coordinates of the scrolling rectangle.
lprcClip
[in] Long pointer to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.
hrgnUpdate
[in] Handle to the region uncovered by the scrolling process. ScrollDC defines this region; it is not necessarily a rectangle.
lprcUpdate
[out] Long pointer to the RECT structure that receives the coordinates of the rectangle bounding the scrolling update region. This is the largest rectangular area that requires repainting. When the function returns, the values in the structure are in client coordinates, regardless of the mapping mode for the specified device context.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the lprcUpdate parameter is NULL, the system does not compute the update rectangle. If both the hrgnUpdate and lprcUpdate parameters are NULL, the system does not compute the update region. If hrgnUpdate is not NULL, the system proceeds as though it contains a valid handle to the region uncovered by the scrolling process (defined by ScrollDC).

When you must scroll the entire client area of a window, use the ScrollWindowEx function.

See Also

RECT


ScrollWindowEx

This function scrolls the content of the specified window’s client area.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int ScrollWindowEx( HWND hWnd, int dx, int dy, const RECT *prcScroll,
const RECT *prcClip, HRGN hrgnUpdate, LPRECT prcUpdate, UINT flags);

Parameters

hWnd
Handle to the window where the client area is to be scrolled.
dx
Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left.
dy
Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll up.
prcScroll
Pointer to the RECT structure specifying the portion of the client area to be scrolled. If this parameter is NULL, the entire client area is scrolled.
prcClip
Pointer to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.
hrgnUpdate
Handle to the region that is modified to hold the region invalidated by scrolling. This parameter may be NULL.
prcUpdate
Pointer to the RECT structure receiving the boundaries of the rectangle invalidated by scrolling. This parameter may be NULL.
flags
Specifies flags that control scrolling. This parameter can be one of the following values:
Value
Description
SW_ERASE | Erases the newly invalidated region by sending a WM_ERASEBKGND message to the window when specified with the SW_INVALIDATE flag.
SW_INVALIDATE | Invalidates the region identified by the hrgnUpdate parameter after scrolling.
SW_SCROLLCHILDREN | Scrolls all child windows that intersect the rectangle pointed to by the prcScroll parameter. The child windows are scrolled by the number of pixels specified by the dx and dy parameters. The system sends a WM_MOVE message to all child windows that intersect the prcScroll rectangle, even if they do not move.
SW_SMOOTHSCROLL | Windows NT 5.0 and later: Scrolls using smooth scrolling. Use the high-order word of the flags parameter to indicate how much time the smooth-scrolling operation should take.

Return Values

COMPLEXREGION indicates that the region consists of more than one rectangle. ERROR indicates that an error occurred. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. To get extended error information, call GetLastError.

Windows CE Remarks

The flags parameter does not support SW_SCROLLCHILDREN.

Only one of the dx and dy parameters can be nonzero.

For Windows CE versions 2.10 and later, support has been added for SW_SCROLLWINDOW in the flags parameter.

The RedrawWindow, DPtoLP, and LPtoDP functions are not supported.

Remarks

If the SW_INVALIDATE and SW_ERASE flags are not specified, ScrollWindowEx does not invalidate the area that is scrolled from. If either of these flags is set, ScrollWindowEx invalidates this area. The area is not updated until the application calls the UpdateWindow function or retrieves the WM_PAINT message from the application queue.

If the window has the WS_CLIPCHILDREN style, the returned areas specified by hrgnUpdate and prcUpdate represent the total area of the scrolled window that must be updated, including any areas in child windows that need updating.

If the SW_SCROLLCHILDREN flag is specified, the system does not properly update the screen if part of a child window is scrolled. The part of the scrolled child window that lies outside the source rectangle is not erased and is not properly redrawn in its new destination. To move child windows that do not lie completely within the rectangle specified by prcScroll, use the DeferWindowPos function. The cursor is repositioned if the SW_SCROLLCHILDREN flag is set and the caret rectangle intersects the scroll rectangle.

All input and output coordinates (for prcScroll, prcClip, prcUpdate, and hrgnUpdate) are determined as client coordinates, regardless of whether the window has the CS_OWNDC or CS_CLASSDC class style. Use the LPtoDP and DPtoLP functions to convert to and from logical coordinates, if necessary.

See Also

RECT, ScrollDC, UpdateWindow, DeferWindowPos


SelectClipRgn

This function selects a region as the current clipping region for the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int SelectClipRgn(HDC hdc, HRGN hrgn);

Parameters

hdc
[in] Handle to the device context.
hrgn
[in] Handle to the region to be selected.

Return Values

The return value specifies the region’s complexity. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than a single rectangle. ERROR indicates that an error occurred; the current clipping region is unaffected.

To get extended error Information, call GetLastError.

Remarks

Only a copy of the selected region is used. The region itself can be selected for any number of other device contexts or it can be deleted.

The SelectClipRgn function assumes that the coordinates for a region are specified in device units.

To remove a device-context’s clipping region, specify a NULL region handle.

See Also

SetRectRgn


SelectObject

This function selects an object into a specified device context. The new object replaces the previous object of the same type.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

HGDIOBJ SelectObject(HDC hdc, HGDIOBJ hgdiobj);

Parameters

hdc
[in] Handle to the device context.
hgdiobj
[in] Handle to the object to be selected. The specified object must have been created by using one of the following functions:
Object
Functions
Bitmap
 CreateBitmap, CreateCompatibleBitmap, CreateDIBSection
(Bitmaps can be selected for memory device contexts only, and for only one device context at a time.)
Brush
 CreateDIBPatternBrushPt, CreatePatternBrush, CreateSolidBrush
Font
 CreateFontIndirect
Pen
 CreatePen, CreatePenIndirect
Region
 CombineRgn, CreateRectRgn, CreateRectRgnIndirect

Return Values

If the selected object is not a region, the handle of the object being replaced indicates success. If the selected object is a region, one of the following values indicates success:

Value
Description
SIMPLEREGION | Region consists of a single rectangle.
COMPLEXREGION | Region consists of more than one rectangle.
NULLREGION | Region is empty.

NULL indicates that an error occurred and the selected object is not a region. Otherwise, a GDI_ERROR value is returned.

Remarks

This function returns the previously selected object of the specified type. An application should always replace a new object with the original, default object after it has finished drawing with the new object.

An application cannot select a bitmap into more than one device context at a time.

See Also

CombineRgn, CreateBitmap, CreateCompatibleBitmap, CreateFontIndirect, CreatePenIndirect, CreateRectRgnIndirect, CreateSolidBrush, SelectClipRgn


SelectPalette

This function selects the specified logical palette into a device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

HPALETTE SelectPalette( HDC hdc, HPALETTE hpal,
BOOL bForceBackground);

Parameters

hdc
[in] Handle to the device context (DC).
hpal
[in] Handle to the logical palette to be selected.
bForceBackground
[in] Ignored. Because Windows CE does not arbitrate between the palettes of the foreground and background applications, Windows CE ignores this parameter and always treats it as FALSE. This causes the logical palette to be copied into the device palette when the application is in the foreground.

Return Values

A handle that identifies the device context's previous logical palette indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

An application can select a logical palette into more than one device context. However, changes to a logical palette will affect all device contexts for which it is selected.

See Also

CreatePalette, GetDeviceCaps, RealizePalette


SendDlgItemMessage

This function sends a message to the specified control in a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LONG SendDlgItemMessage( HWND hDlg, int nIDDlgItem, UINT Msg,
WPARAM wParam, LPARAM lParam );

Parameters

hDlg
[in] Handle to the dialog box that contains the control.
nIDDlgItem
[in] Specifies the identifier of the control that receives the message.
Msg
[in] Specifies the message to be sent.
wParam
[in] Specifies additional message-specific information.
lParam
[in] Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

The SendDlgItemMessage function does not return until the message has been processed.

Using SendDlgItemMessage is identical to retrieving a handle of the specified control and calling the SendMessage function.

See Also

SendMessage


SendInput

This function synthesizes keystrokes, stylus and mouse motions, and button clicks.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

UINT SendInput(UINT nInputs, LPINPUT pInputs, int cbSize);

Parameters

nInputs
Specifies how many structures pInputs points to.
pInputs
Pointer to an array of INPUT structures. Each structure represents an event to be inserted into the keyboard or mouse input stream.
cbSize
Specifies the size of an INPUT structure. If cbSize is not the size of an INPUT structure, the function will fail.

Return Values

The number of events that the function inserted into the keyboard or mouse input stream indicates success. To get extended error information, call GetLastError.

Windows CE Remarks

Windows CE does not support the INPUT_HARDWARE value in the type field of the INPUT structure referred to by the pInputs parameter.

Remarks

The SendInput function inserts the events in the INPUT structures serially into the keyboard or mouse input stream. These events aren’t interspersed with other keyboard or mouse input events inserted either by the user (with the keyboard or mouse) or by calls to keybd_event, mouse_event, or other calls to SendInput.

See Also

INPUT, keybd_event


SendMessage

This function sends the specified message to a window or windows. SendMessage calls the window procedure for the specified window and does not return until the window procedure has processed the message. The PostMessage function, in contrast, posts a message to a thread's message queue and returns immediately.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LRESULT SendMessage(HWND hWnd, UINT Msg, WPARAM wParam,
LPARAM lParam);

Parameters

hWnd
[in] Handle to the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.
Msg
[in] Specifies the message to be sent.
wParam
[in] Specifies additional message-specific information.
lParam
[in] Specifies additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

If the specified window was created by the calling thread, the window procedure is called immediately as a subroutine. If the specified window was created by a different thread, the system switches to that thread and calls the appropriate window procedure. Messages sent between threads are processed only when the receiving thread executes message retrieval code. The sending thread is blocked until the receiving thread processes the message.

Windows CE does not support all the messages the Windows-based desktop platforms support.

See Also

PostMessage, SendDlgItemMessage


SendNotifyMessage

This function sends the specified message to the given window. If the window was created by the calling thread, SendNotifyMessage calls the window procedure for the window and does not return until the window procedure has processed the message. If the window was created by a different thread, SendNotifyMessage passes the message to the window procedure and returns immediately; it does not wait for the window procedure to finish processing the message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SendNotifyMessage(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam);

Parameters

hWnd
[in] Handle to the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.
Msg
[in] Specifies the message to be sent.
wParam
[in] Specifies additional message-specific information.
lParam
[in] Specifies additional message-specific information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage, SendNotifyMessage, and SendMessageCallback), its message parameters can not include pointers. Otherwise, the operation will fail. The functions will return before the receiving thread has had a chance to process the message and the sender will free the memory before it is used.

Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication.

See Also

PostMessage, PostThreadMessage, SendMessage


SetAbortProc

This function sets the application-defined function that allows a print job to be canceled during printing.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int SetAbortProc( HDC hdc, ABORTPROC lpAbortProc);

Parameters

hdc
[in] Handle to the device context (DC) for the print job.
lpAbortProc
[in] Long pointer to the application-defined abort function.

Return Values

A value greater than zero indicates success. SP_ERROR indicates failure. To get extended error information, call GetLastError.

See Also

EndDoc, StartDoc, StartPage


SetActiveWindow

This function makes the specified top-level window associated with the thread calling this function the active window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND SetActiveWindow(HWND hWnd);

Parameters

hWnd
[in] Handle to the top-level window to be activated.

Return Values

The handle to the window that was previously active indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The SetActiveWindow function activates a window, but not if the application is in the background. The window will be brought into the foreground—the top of z-order—if the application is in the foreground when it sets the activation.

If the window identified by the hWnd parameter was created by the calling thread, the active window status of the calling thread is set to hWnd. Otherwise, the active window status of the calling thread is set to NULL.

For Windows CE versions 2.10 and later, if you call this function with hWnd set to the handle of the child window, SetActiveWindow returns NULL and sets the extended error value to zero.

The SetForegroundWindow window function, on the other hand, activates a window and forces it into the foreground. An application should only call SetForegroundWindow if it needs to display critical errors or information that needs the user’s immediate attention.

See Also

GetActiveWindow, SetForegroundWindow, WM_ACTIVATE


SetBkColor

This function sets the current background color to the specified color. If the device cannot represent the specified color, it sets the background color to the nearest physical color.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF SetBkColor(HDC hdc, COLORREF crColor);

Parameters

hdc
[in] Handle to the device context.
crColor
[in] Specifies the new background color.

Return Values

If the function succeeds, the return value specifies the previous background color as a COLORREF value.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

Remarks

This function fills the gaps between styled lines drawn using a pen created by the CreatePen function. The SetBKColor function also sets the background colors for the ExtTextOut function.

If the background mode is OPAQUE, the background color is used to fill gaps between styled lines, gaps between hatched lines in brushes, and character cells. The background color is also used when converting bitmaps from color to monochrome and vice versa.

See Also

GetBkMode, SetBkMode, COLORREF


SetBkMode

This function sets the background mix mode of the specified device context. The background mix mode is used with text, hatched brushes, and with non-solid pen styles.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int SetBkMode(HDC hdc, int iBkMode);

Parameters

hdc
[in] Handle to the device context.
iBkMode
[in] Specifies the background mode. It is either of the following values:
Value
Description
OPAQUE | Background is filled with the current background color before the text, hatched brush, or pen is drawn.
TRANSPARENT | Background remains untouched.

Return Values

If the function succeeds, the return value specifies the previous background mode.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The SetBkMode function affects the line styles for lines drawn using a pen created by the CreatePen function. SetBkMode does not affect lines drawn using a pen created by the ExtCreatePen function.

The iBkMode parameter can also be set to driver-specific values. GDI passes such values to the device driver and otherwise ignores them.

The iBKMode parameter is stored internally as a single byte.

See Also

GetBkMode


SetBrushOrgEx

This function is called by an application to set the brush origin of the next brush selected into the specified device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetBrushOrgEx(HDC hdc, int nXOrg, int nYOrg, LPPOINT lppt);

Parameters

hdc
[in] Handle to the device context.
nXOrg
[in] Specifies the x-coordinate, in device units, of the new brush origin. If this value is greater than the brush width, its value is reduced using the modulus operator (nXOrg mod brush width).
nYOrg
[in] Specifies the y-coordinate, in device units, of the new brush origin. If this value is greater than the brush height, its value is reduced using the modulus operator (nYOrg mod brush height).
lppt
[out] Long pointer to a POINT structure that receives the previous brush origin.

This parameter can be NULL if the previous brush origin is not required.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

A brush is a bitmap that the system uses to paint the interiors of filled shapes.

The brush origin is a pair of coordinates specifying the location of one pixel in the bitmap. The default brush origin coordinates are (0,0). For horizontal coordinates, the value 0 corresponds to the leftmost column of pixels; the width corresponds to the rightmost column. For vertical coordinates, the value 0 corresponds to the uppermost row of pixels; the height corresponds to the lowermost row.

The system automatically tracks the origin of all window-managed device contexts and adjusts their brushes as necessary to maintain an alignment of patterns on the surface. The brush origin that is set with this call is relative to the upper-left corner of the client area.

An application should call SetBrushOrgEx after using SetStretchBltMode to set the bitmap stretching mode to HALFTONE. This must be done to avoid brush misalignment.

Automatic tracking of the brush origin is not supported. Applications must call SetBrushOrgEx to align the brush before using it and call the SelectObject function to select the modified brush..

See Also

POINT, SelectObject


SetCapture

This function sets the pen capture to the specified window belonging to the current thread. After a window has captured the pen, all pen input is directed to that window. Only one window at a time can capture the pen.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND SetCapture(HWND hWnd);

Parameters

hWnd
[in] Handle to the window in the current thread that is to capture the mouse.

Return Values

The handle of the window that had previously captured the mouse indicates success. NULL indicates that there is no such window.

Remarks

Only the foreground window can capture the mouse. When a background window attempts to do so, the window receives messages only for mouse events that occur when the cursor hot spot is within the visible portion of the window. Also, even if the foreground window has captured the mouse, the user can still click another window, bringing it to the foreground.

When the window no longer requires all mouse input, the thread that created the window should call the ReleaseCapture function to release the mouse.

This function cannot be used to capture mouse input meant for another process.

See Also

GetCapture, ReleaseCapture, WM_CAPTURECHANGED


SetCaretBlinkTime

This function sets the caret blink time to the specified number of milliseconds. The blink time is the elapsed time, in milliseconds, required to invert the caret's pixels.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCaretBlinkTime(UINT wMSeconds);

Parameters

uMSeconds
[in] Unsigned integer that contains the new blink time, in milliseconds.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The user can set the blink time using the Control Panel. Applications should respect the setting that the user has chosen. The SetCaretBlinkTime function should only be used by applications that allow the user to set the blink time, such as a Control Panel applet.

Changing the caret blink time in one application does not affect the blink time in subsequently loaded applications.

See Also

GetCaretBlinkTime


SetCaretPos

This function moves the caret to the specified coordinates.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCaretPos(int X, int Y);

Parameters

X
[in] Integer that contains the new x-coordinate of the caret.
Y
[in] Integer that contains the new y-coordinate of the caret.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

SetCaretPos moves the caret whether or not the caret is hidden.

The system provides one caret per queue. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive. A window can set the caret position only if it owns the caret.

See Also

GetCaretPos, HideCaret, ShowCaret


SetClassLong

This function replaces the specified 32-bit (LONG) value at the specified offset into the extra class memory of the WNDCLASS structure for the class to which the specified window belongs.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DWORD SetClassLong( HWND hWnd, int nIndex, LONG dwNewLong );

Parameters

hWnd
Handle to the window and, indirectly, the class to which the window belongs.
nIndex
Specifies the 32-bit value to replace. To set a 32-bit value in the extra class memory, specify the positive, zero-based byte offset of the value to be set. Valid values are in the range zero through the number of bytes of extra class memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would be an index to the third 32-bit integer. In Windows CE, the byte offset but must be a multiple of 4 bytes.

If a mouse cursor is supported, this parameter can be set to the following value:
Value
Description
GCL_HCURSOR Replaces a handle to the cursor associated with the class.
Windows CE versions that support mouse cursors include the Iconcurs and Mcursor components rather than the Icon and Cursor components.

dwNewLong
Specifies the replacement value.

Return Values

The previous value of the specified 32-bit integer indicates success. Zero indicates that the value was not previously set or that the function failed. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

Unaligned access is not supported.

Use the SetClassLong function with care. For example, it is possible to change the background color for a class by using SetClassLong, but this change does not immediately repaint all windows belonging to the class.

See Also

GetClassLong, RegisterClass, SetWindowLong, WindowProc, WNDCLASS


SetClipboardData

This function places data on the clipboard in a specified clipboard format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE SetClipboardData(UINT uFormat, HANDLE hMem);

Parameters

uFormat
[in] Unsigned integer that specifies a clipboard format. This parameter can be a registered format or any of the standard clipboard formats. Windows CE supports the following standard clipboard:
Value
Description
CF_BITMAP | A handle to a bitmap (HBITMAP).
CF_DIB | A memory object containing a BITMAPINFO structure followed by the bitmap bits.
CF_DIF | Software Arts' Data Interchange Format.
CF_PALETTE | Handle of a color palette. Whenever an application places data in the clipboard that depends on or assumes a color palette, it should place the palette on the clipboard as well.
If the clipboard contains data in the CF_PALETTE (logical color palette) format, the application should use the SelectPalette and RealizePalette functions to realize (compare) any other data in the clipboard against that logical palette.
When displaying clipboard data, the clipboard always uses as its current palette any object on the clipboard that is in the CF_PALETTE format.
CF_PENDATA | Data for the pen extensions to the Microsoft® Windows® for Pen Computing.
CF_RIFF | Represents audio data more complex than can be represented in a CF_WAVE standard wave format.
CF_SYLK | Microsoft Symbolic Link (SYLK) format.
CF_TEXT | Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. Use this format for ANSI text.
CF_WAVE | Represents audio data in one of the standard wave formats, such as 11 kHz or 22 kHz pulse code modulation (PCM).
CF_TIFF | Tagged-image file format.
CF_UNICODETEXT | Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.

hMem
[in] Handle to the data in the specified format. This parameter can be NULL, indicating that the window provides data in the specified clipboard format (renders the format) upon request. If a window delays rendering, it must process the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages.

After SetClipboardData is called, the system owns the object identified by the hMem parameter. The application can read the data, but must not free the handle or leave it locked. If the hMem parameter identifies a memory object, the object must have been allocated using the LocalAlloc function.

Return Values

The handle of the data indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The data to be set into the clipboard should be allocated using the LocalAlloc function.

Windows CE does not perform any implicit conversions between formats.

The window must be the current clipboard owner, and the application must have called the OpenClipboard function.

The uFormat parameter can identify a registered clipboard format, or it can be one of the standard clipboard formats. The system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand.

See Also

BITMAPINFO, GetClipboardData, OpenClipboard, RegisterClipboardFormat, WM_DESTROYCLIPBOARD, WM_RENDERFORMAT, WM_RENDERALLFORMATS


SetCursor

This function establishes the cursor shape.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HCURSOR SetCursor(HCURSOR hcur);

Parameters

hCursor
[in] Handle to the cursor. The cursor must have been created by the CreateCursor or loaded by the LoadCursor or LoadImage function. If this parameter is NULL, the cursor is removed from the screen.

The width and height of the cursor must be the values returned by the GetSystemMetrics function for SM_CXCURSOR and SM_CYCURSOR.

Return Values

The handle to the previous cursor, if there was one, indicates success. NULL indicates that there was no previous cursor.

Remarks

Use Cursor.lib when targeting a platform that does not support mouse cursors. The only cursor this component supports is the wait cursor. Use the following code to set the wait cursor:

SetCursor(LoadCursor(NULL, IDC_WAIT));

Use Mcursor.lib when targeting a platform that does support mouse cursors. This component does not support color cursors.

If SetCursor is called after CreateCursor creates a zero dimension cursor, it still shows the old cursor, not the new cursor.

The cursor is set only if the new cursor is different from the previous cursor; otherwise, the function returns immediately.

The cursor is a shared resource. A window should set the cursor shape only when the cursor is in its client area or when the window is capturing mouse input. In systems without a mouse, the window should restore the previous cursor before the cursor leaves the client area or before it relinquishes control to another window.

If your application must set the cursor while it is in a window, make sure the class cursor for the specified window’s class is set to NULL. If the class cursor is not NULL, the system restores the class cursor each time the mouse is moved.

The cursor is not shown on the screen if the internal cursor display count is less than zero. This occurs if the application uses the ShowCursor function to hide the cursor more times than to show the cursor.

See also

CreateCursor, GetCursor, GetSystemMetrics, LoadCursor, LoadImage, SetCursorPos, ShowCursor


SetCursorPos

This function moves the cursor to the specified screen coordinates. If the new coordinates are not within the screen rectangle set by the most recent ClipCursor function, Windows CE automatically adjusts the coordinates so the cursor stays within the rectangle.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCursorPos( int x, int y);

Parameters

x
[in] Specifies the new x-coordinate, in screen coordinates, of the cursor.
y
[in] Specifies the new y-coordinate, in screen coordinates, of the cursor.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The cursor is a shared resource. A window should move the cursor only when the cursor is in its client area.

The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

See also

ClipCursor, GetCursorPos, SetCursor, ShowCursor


SetDlgItemInt

This function sets the text of a control in a dialog box to the string representation of a specified integer value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetDlgItemInt( HWND hDlg, int nIDDlgItem, UINT uValue,
BOOL bSigned );

Parameters

hDlg
[in] Handle to the dialog box that contains the control.
nIDDlgItem
[in] Specifies the control to be changed.
uValue
[in] Specifies the integer value, assumed to be signed, that is used to generate the item text.
bSigned
[in] Ignored; set to zero

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

To set the new text, this function sends a WM_SETTEXT message to the specified control.

See Also

GetDlgItemInt, SetDlgItemText, WM_SETTEXT


SetDlgItemText

This function sets the title or text of a control in a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetDlgItemText( HWND hDlg, int nIDDlgItem, LPCTSTR lpString );

Parameters

hDlg
[in] Handle to the dialog box that contains the control.
nIDDlgItem
[in] Identifies the control with a title or text that is to be set.
lpString
[in] Long pointer to the null-terminated string that contains the text to be copied to the control.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The SetDlgItemText function sends a WM_SETTEXT message to the specified control.

See Also

GetDlgItemInt, GetDlgItemText, SetDlgItemInt, WM_SETTEXT


SetFocus

This function sets the keyboard focus to the specified window. All subsequent keyboard input is directed to this window. The window, if any, that previously had the keyboard focus loses it.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND SetFocus(HWND hWnd);

Parameters

hWnd
[in] Handle to the window that will receive the keyboard input. If this parameter is NULL, keystrokes are ignored.

Return Values

The handle to the window that previously had the keyboard focus indicates success. NULL indicates that the hWnd parameter is invalid or the window is not associated with the calling thread’s message queue. To get extended error information, call GetLastError.

Remarks

The SetFocus function sends a WM_KILLFOCUS message to the window that loses the keyboard focus and a WM_SETFOCUS message to the window that receives the keyboard focus. It also activates either the window that receives the focus or the parent of the window that receives the focus.

If a window is active but does not have the focus, any key pressed will produce the WM_SYSCHAR, WM_SYSKEYDOWN, or WM_SYSKEYUP message. If the VK_MENU key is also pressed, the lParam parameter of the message will have bit 30 set. Otherwise, the messages produced do not have this bit set.

Do not use the SetFocus function to set the keyboard focus to a window associated with another thread’s message queue. There is one exception. If a window on one thread is the child of the window on the other thread, or if the windows are siblings of the same parent, the thread associated with one window can set the focus to the other window even though it belongs to a different thread. In this case, there is no need to call AttachThreadInput first.

See Also

GetActiveWindow, GetFocus, SetActiveWindow, SetCapture, SetForegroundWindow, WM_KILLFOCUS, WM_SETFOCUS, WM_SYSCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


SetForegroundWindow

This function puts the thread that created the specified window into the foreground and activates the window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetForegroundWindow(HWND hWnd);

Parameters

hWnd
[in] Handle to the window that should be activated and brought to the foreground.

Return Values

Nonzero indicates that the window was brought to the foreground. Zero indicates that the window was not brought to the foreground.

Remarks

The foreground window is the window at the top of the z-order. It is the window that the user is working with. In a preemptive multitasking environment, you should generally let the user control which window is the foreground window.

The thread that owns the window is not given a priority boost.

See Also

GetForegroundWindow, SetActiveWindow


SetMenuItemInfo

This function changes information about a menu item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetMenuItemInfo(HMENU hmenu, UINT uItem, BOOL fByPosition,
LPCMENUITEMINFO pmii);

Parameters

hMenu
[in] Handle to the menu that contains the menu item.
uItem
[in] Specifies the identifier or position of the menu item to change. The meaning of this parameter depends on the value of fByPosition.
fByPosition
[in] Value that specifies the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.
lpmii
[in] Long pointer to a MENUITEMINFO structure that contains information about the menu item and specifies which menu item attributes to change.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Use SetMenuItemInfo to set the menu item content, an application-defined identifier, and application-defined data. SetMenuItemInfo can also set the menu item type, but it cannot change the type.

SetMenuItemInfo cannot set the menu item state, submenu, and check mark bitmaps.

In order for keyboard accelerators to work with bitmap or owner-drawn menu items, the owner of the menu must process the WM_MENUCHAR message.


SetPaletteEntries

This function sets RGB (red, green and blue) color values and flags in a range of entries in a logical palette.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

UINT SetPaletteEntries( HPALETTE hpal, UINT iStart, UINT cEntries, CONST PALETTEENTRY * lppe);

Parameters

hpal
[in] Handle to the logical palette.
iStart
[in] Specifies the first logical-palette entry to be set. This function fails if iStart is greater than the number of palette entries.
cEntries
[in] Specifies the number of logical-palette entries to be set.
lppe
[in] Long pointer to the first member of an array of PALETTEENTRY structures containing the RGB values and flags.

Return Values

The number of entries that were set in the logical palette indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

An application can determine whether or not a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

Even if a logical palette has been selected and realized, changes to the palette do not affect the physical palette in the surface. RealizePalette must be called again to set the new logical palette into the surface.

See Also

GetDeviceCaps, GetPaletteEntries, RealizePalette


SetParent

This function changes the parent window of the specified child window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND SetParent( HWND hWndChild, HWND hWndNewParent );

Parameters

hWndChild
Handle to the child window.
hWndNewParent
Handle to the new parent window. If this parameter is NULL, the desktop window becomes the new parent window.

Windows NT 5.0 and later: If this parameter is HWND_MESSAGE, the child window becomes a message-only window.

Return Values

A handle to the previous parent window indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

An application can use the SetParent function to set the parent window of a pop-up, overlapped, or child window. The new parent window and the child window must belong to the same application.

If the window identified by the hWndChild parameter is visible, the system performs the appropriate redrawing and repainting.

For compatibility reasons, SetParent does not modify the WS_CHILD or WS_POPUP window styles of the window whose parent is being changed. Therefore, if hWndNewParent is NULL, you should also clear the WS_CHILD bit and set the WS_POPUP style after calling SetParent. Conversely, if hWndNewParent is not NULL and the window was previously a child of the desktop, you should clear the WS_POPUP style and set the WS_CHILD style before calling SetParent.

See Also

GetParent


SetPixel

This function sets the pixel at the specified coordinates to the specified color.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF SetPixel(HDC hdc, int X, int Y, COLORREF crColor);

Parameters

hdc
[in] Handle to the device context.
X
[in] Specifies the x-coordinate, in logical units, of the point to be set.
Y
[in] Specifies the y-coordinate, in logical units, of the point to be set.
crColor
[in] Specifies the color to be used to paint the point.

Return Values

The RGB value that the function sets the pixel to indicates success. This value may differ from the color specified by crColor; that happens when an exact match for the specified color cannot be found. –1 indicates failure. To get extended error information, call GetLastError.

Remarks

The function fails if the pixel coordinates lie outside of the current clipping region.

Not all devices support the SetPixel function. For more information, see GetDeviceCaps.

See Also

GetDeviceCaps


SetRectRgn

This function changes a region into a rectangular region with the specified coordinates.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL SetRectRgn( HRGN hrgn, int nLeftRect, int nTopRect, int nRightRect, int nBottomRect);

Parameters

hrgn
[in] Handle to the region.
nLeftRect
[in] Specifies the x-coordinate of the upper-left corner of the rectangular region.
nTopRect
[in] Specifies the y-coordinate of the upper-left corner of the rectangular region.
nRightRect
[in] Specifies the x-coordinate of the lower-right corner of the rectangular region.
nBottomRect
[in] Specifies the y-coordinate of the lower-right corner of the rectangular region.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The region does not include the lower and right boundaries of the rectangle.

See Also

RectVisible


SetROP2

This function sets the current foreground mix mode. GDI uses the foreground mix mode to combine pens and interiors of filled objects with the colors already on the screen. The foreground mix mode defines how colors from the brush or pen are combined with the colors in the existing image.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int SetROP2( HDC hdc, int fnDrawMode);

Parameters

hdc
[in] Handle to the device context.
fnDrawMode
[in] Specifies the new mix mode. It is one of the following values:
Value
Description
R2_BLACK | Pixel is always 0.
R2_COPYPEN | Pixel is the pen color.
R2_MASKNOTPEN | Pixel is a combination of the colors common to both the screen and the inverse of the pen.
R2_MASKPEN | Pixel is a combination of the colors common to both the pen and the screen.
R2_MASKPENNOT | Pixel is a combination of the colors common to both the pen and the inverse of the screen.
R2_MERGENOTPEN | Pixel is a combination of the screen color and the inverse of the pen color.
R2_MERGEPEN | Pixel is a combination of the pen color and the screen color.
R2_MERGEPENNOT | Pixel is a combination of the pen color and the inverse of the screen color.
R2_NOP | Pixel remains unchanged.
R2_NOT | Pixel is the inverse of the screen color.
R2_NOTCOPYPEN | Pixel is the inverse of the pen color.
R2_NOTMASKPEN | Pixel is the inverse of the R2_MASKPEN color.
R2_NOTMERGEPEN | Pixel is the inverse of the R2_MERGEPEN color.
R2_NOTXORPEN | Pixel is the inverse of the R2_XORPEN color.
R2_WHITE | Pixel is always 1.
R2_XORPEN | Pixel is a combination of the colors in the pen and in the screen, but not in both.

Return Values

If the function succeeds, the return value is the previous mix mode. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Mix modes define how GDI combines source and destination colors when drawing with the current pen. The mix modes are binary raster operation codes, representing all possible Boolean functions of two variables, using the binary operations AND, OR, and XOR (exclusive OR), and the unary operation NOT. The mix mode is for raster devices only; it is not available for vector devices.

See Also

CreatePatternBrush


SetScrollInfo

This function sets the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb). SetScrollInfo also redraws the scroll bar, if requested.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int SetScrollInfo( HWND hwnd, int fnBar, LPSCROLLINFO lpsi,
BOOL fRedraw );

Parameters

hwnd
Handle to a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.
fnBar
Specifies the type of scroll bar for which to set parameters. It is one of the following values:
Value
Description
SB_CTL | Sets the parameters of a scroll bar control. The hwnd parameter must be the handle to the scroll bar control.
SB_HORZ | Sets the parameters of the given window's standard horizontal scroll bar.
SB_VERT | Sets the parameters of the given window's standard vertical scroll bar.

lpsi
Long pointer to a SCROLLINFO structure. Before calling SetScrollInfo, set the cbSize member of the structure to sizeof(SCROLLINFO), set the fMask member to indicate the parameters to set, and specify the new parameter values in the appropriate members.

The fMask member can be a combination of the following values:
Value
Description
SIF_DISABLENOSCROLL | Disables the scroll bar instead of removing it, if the scroll bar’s new parameters make the scroll bar unnecessary.
SIF_PAGE | Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS | Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE | Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.

fRedraw
Boolean that specifies whether the scroll bar is redrawn to reflect the changes to the scroll bar. If this parameter is TRUE, the scroll bar is redrawn, otherwise, it is not redrawn.

Return Values

The current position of the scroll box indicates success.

Remarks

The SetScrollInfo function performs range checking on the values specified by the nPage and nPos members of the SCROLLINFO structure. The nPage member must specify a value from 0 to nMax - nMin +1. The nPos member must specify a value between nMin and nMax - max(nPage –1, 0). If either value is beyond its range, the function sets it to a value that is just within the range.

In Windows CE versions 2.0 and 2.01, if you pass a null pointer in the lpsi parameter, SetScrollInfo returns zero, rather than the current position of the scroll box. For Windows CE versions 2.10 and later, if you pass a null pointer in the lpsi parameter, SetScrollInfo returns the current scroll bar position and sets the ERROR_INVALID_PARAMETER error code through a call to SetLastError.

See Also

GetScrollInfo, SCROLLINFO, SetLastError


SetScrollPos

This function sets the position of the scroll box (thumb) in the specified scroll bar and, if requested, redraws the scroll bar to reflect the new position of the scroll box. SetScrollPos is provided for compatibility with Windows 3.x. Win32-based applications should use the SetScrollInfo function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

int SetScrollPos( HWND hWnd, int nBar, int nPos, BOOL bRedraw);

Parameters

hWnd
Handle to a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.
nBar
Specifies the scroll bar to be set. This parameter can be one of the following values:
Value
Description
SB_CTL | Sets the position of the scroll box in a scroll bar control. The hWnd parameter must be the handle to the scroll bar control.
SB_HORZ | Sets the position of the scroll box in a window’s standard horizontal scroll bar.
SB_VERT | Sets the position of the scroll box in a window’s standard vertical scroll bar.

nPos
Specifies the new position of the scroll box. The position must be within the scrolling range. For more information about the scrolling range, see the SetScrollRange function.
bRedraw
Boolean that specifies whether the scroll bar is redrawn to reflect the new scroll box position. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

Return Values

The previous position of the scroll box indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the scroll bar is redrawn by a subsequent call to another function, setting the bRedraw parameter to FALSE is useful.

Because the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, applications that rely solely on those messages for position data have a practical maximum value of 65,535 for the SetScrollPos function’s nPos parameter.

However, because the SetScrollInfo, SetScrollPos, SetScrollRange, GetScrollInfo, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollInfo for a description of the technique.

See Also

GetScrollInfo, ScrollDC, ScrollWindowEx, SetScrollRange


SetScrollRange

This function sets the minimum and maximum position values for the specified scroll bar. It can also be used to hide or show a standard scroll bar. SetScrollRange is provided for compatibility with Windows 3.x. Win32-based applications should use the SetScrollInfo function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL SetScrollRange( HWND hWnd, int nBar, int nMinPos, int nMaxPos, BOOL bRedraw );

Parameters

hWnd
Handle to a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.
nBar
Specifies the scroll bar to be set. This parameter can be one of the following values:
Value
Description
SB_CTL | Sets the range of a scroll bar control. The hWnd parameter must be the handle to the scroll bar control.
SB_HORZ | Sets the range of a window’s standard horizontal scroll bar.
SB_VERT | Sets the range of a window’s standard vertical scroll bar.

nMinPos
Specifies the minimum scrolling position.
nMaxPos
Specifies the maximum scrolling position.
bRedraw
Boolean that specifies whether the scroll bar should be redrawn to reflect the change. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

You can use SetScrollRange to hide the scroll bar by setting nMinPos and nMaxPos to the same value. An application should not call the SetScrollRange function to hide a scroll bar while processing a scroll bar message.

If the call to SetScrollRange immediately follows a call to the SetScrollPos function, the bRedraw parameter in SetScrollPos must be zero to prevent the scroll bar from being drawn twice.

The default range for a standard scroll bar is 0 through 100. The default range for a scroll bar control is empty (both the nMinPos and nMaxPos parameter values are zero). The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

Because the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, applications that rely solely on those messages for position data have a practical maximum value of 65,535 for the SetScrollRange function’s nMaxPos parameter.

However, because the SetScrollInfo, SetScrollPos, SetScrollRange, GetScrollInfo, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollInfo for a description of the technique.

See Also

GetScrollInfo, SetScrollPos


SetSysColors

This function sets the colors for one or more display elements.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI SetSysColors( int cElements, CONST INT *lpaElements,
CONST COLORREF *lpaRgbValues );

Parameters

cElements
Specifies the number of display elements in the array pointed to by the lpaElements parameter.
lpaElements
Long pointer to an array of integers that specify the display elements to be changed. For a list of display elements, see GetSysColor.
lpaRgbValues
Long pointer to an array of unsigned long integers that contains the new red, green, blue (RGB) color value for each display element in the array pointed to by the lpaElements parameter.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The SetSysColors function sends a WM_SYSCOLORCHANGE message to all windows to inform them of the change in color. It also directs the system to repaint the affected portions of all currently visible windows.

The SetSysColors function changes the current session only. The new colors are not saved when the system terminates.

See Also

GetSysColor


SetTextColor

This function sets the text color of the specified device context to the specified color.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF SetTextColor(HDC hdc, COLORREF crColor);

Parameters

hdc
[in] Handle to the device context.
crColor
[in] Specifies the color of the text.

Return Values

A color reference for the previous text color indicates success. CLR_INVALID indicates failure. To get extended error information, call GetLastError.

Remarks

The text color is used to draw the face of each character written by the ExtTextOut function. The text color is also used in converting bitmaps from color to monochrome and vice versa.

See Also

BitBlt, ExtTextOut, RGB, SetBkColor, StretchBlt


SetTimer

This function creates a timer with the specified time-out value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

UINT SetTimer(HWND hWnd, UINT nIDEvent, UINT uElapse, TIMERPROC lpTimerFunc);

Parameters

hWnd
Handle to the window to be associated with the timer. This window must be owned by the calling thread. If this parameter is NULL, no window is associated with the timer and the nIDEvent parameter is ignored.
nIDEvent
Specifies a nonzero timer identifier. If the hWnd parameter is NULL, this parameter is ignored.
uElapse
Specifies the time-out value, in milliseconds.
lpTimerFunc
Long pointer to the function to be notified when the time-out value elapses. For more information about the function, see TimerProc.

If lpTimerFunc is NULL, the system posts a WM_TIMER message to the application queue. The hwnd member of the message’s MSG structure contains the value of the hWnd parameter.

Return Values

An integer identifying the new timer indicates success. An application can pass this value, or the string identifier, if it exists, to the KillTimer function to destroy the timer. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

An application can process WM_TIMER messages by including a WM_TIMER case statement in the window procedure or by specifying a TimerProc callback function when creating the timer. When you specify a TimerProc callback function, the default window procedure calls the callback function when it processes WM_TIMER. Therefore, you need to dispatch messages in the calling thread, even when you use TimerProc instead of processing WM_TIMER.

The wParam parameter of the WM_TIMER message contains the value of the nIDEvent parameter.

See Also

KillTimer, MSG, TimerProc, WM_TIMER


SetViewportOrgEx

This function sets the viewpoint origin of a device context to the specified coordinates.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

SetViewportOrgEx(HDC hdc, int X, int Y, LPPOINT lpPoint);

Parameters

hdc
[in] Handle to the device context.
X
[in] Specifies the x-coordinate, in device units, of the new viewport origin.
Y
[in] Specifies the y-coordinate, in device units, of the new viewport origin.
lpPoint
[in] Long pointer to a POINT structure. The previous viewport origin (in device coordinates) is placed in this structure. If lpPoint is NULL, nothing is returned.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.


SetWindowLong

This function changes an attribute of the specified window. SetWindowLong also sets a 32-bit (LONG) value at the specified offset into the extra window memory of a window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LONG SetWindowLong( HWND hWnd, int nIndex, LONG dwNewLong );

Parameters

hWnd
Handle to the window and, indirectly, the class to which the window belongs.
nIndex
Specifies the zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of extra window memory, minus 4; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer. Windows CE, the byte offset but must be a multiple of 4 bytes.

To set any other value, specify one of the following values:
Value
Description
GWL_EXSTYLE | Sets a new extended window style.
GWL_STYLE | Sets a new window style.
GWL_ID | Sets a new identifier of the window.
GWL_USERDATA | Sets the 32-bit value associated with the window. Each window has a corresponding 32-bit value intended for use by the application that created the window. Windows CE versions 2.0 and later support the this value, but Windows CE versions 1.0 and 1.01 do not.

The following values are also available when the hWnd parameter identifies a dialog box:
Value
Description
DWL_DLGPROC | Sets the new address of the dialog box procedure. Windows CE versions 2.0 and later support the this value, but Windows CE versions 1.0 and 1.01 do not.
DWL_MSGRESULT | Sets the return value of a message processed in the dialog box procedure.
DWL_USER | Sets new extra information that is private to the application, such as handles or pointers.

dwNewLong
Specifies the replacement value.

Return Values

The previous value of the specified 32-bit integer indicates success. Zero indicates failure. To get extended error information, call GetLastError.

If the previous value of the specified 32-bit integer is zero, and the function succeeds, the return value is zero, but the function does not clear the last error information. This makes it difficult to determine success or failure. To deal with this, you should clear the last error information by calling SetLastError(0) before calling SetWindowLong. Then, function failure is indicated by a return value of zero and a GetLastError result that is nonzero.

Remarks

The SetWindowLong function fails if the window specified by the hWnd parameter does not belong to the same process as the calling thread.

Unaligned access is not supported.

Certain window data is cached, so changes you make using SetWindowLong will not take effect until you call the SetWindowPos function.

If you use SetWindowLong with the GWL_WNDPROC index to replace the window procedure, the window procedure must conform to the guidelines specified in the description of the WindowProc callback function.

If you use SetWindowLong with the DWL_MSGRESULT index to set the return value for a message processed by a dialog procedure, you should return TRUE directly afterwards. Otherwise, if you call any function that results in your dialog procedure receiving a window message, the nested window message could overwrite the return value you set using DWL_MSGRESULT.

Calling SetWindowLong with the GWL_WNDPROC index creates a subclass of the window class used to create the window. An application can subclass a system class, but should not subclass a window class created by another process. The SetWindowLong function creates the window subclass by changing the window procedure associated with a particular window class, causing the system to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures.

You must not call SetWindowLong with the GWL_HWNDPARENT index to change the parent of a child window. Instead, use the SetParent function.

See Also

CallWindowProc, GetWindowLong, RegisterClass, SetParent, WindowProc, WNDCLASS


SetWindowPos

This function changes the size, position, and z-order of a child, pop-up, or top-level window. Child, pop-up, and top-level windows are ordered according to their appearance on the screen. The topmost window receives the highest rank and is the first window in the z-order.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetWindowPos( HWND hWnd, HWND hWndInsertAfter, int X, int Y,
int cx, int cy, UINT uFlags);

Parameters

hWnd
Handle to the window.
hWndInsertAfter
Handle to the window to precede the positioned window in the z-order. This parameter must be a window handle or one of the following values:
Value
Description
HWND_BOTTOM | Places the window at the bottom of the z-order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST | Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window. This value is not supported in Windows CE versions 1.0 and 1.01.
HWND_TOP | Places the window at the top of the z-order.
HWND_TOPMOST | Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated. This value is not supported in Windows CE versions 1.0 and 1.01.

For more information about how this parameter is used, see the following Remarks section.

X
Specifies the new position of the left side of the window, in client coordinates.
Y
Specifies the new position of the top of the window, in client coordinates.
cx
Specifies the new width of the window, in pixels.
cy
Specifies the new height of the window, in pixels.
uFlags
Specifies the window sizing and positioning flags. This parameter can be a combination of the following values:
Value
Description
SWP_ASYNCWINDOWPOS | If the calling thread and the thread that owns the window are attached to different input queues, the system posts the request to the thread that owns the window. This prevents the calling thread from blocking its execution while other threads process the request.
SWP_DEFERERASE | Prevents generation of the WM_SYNCPAINT message.
SWP_DRAWFRAME | Draws a frame (defined in the window’s class description) around the window. This value is not supported in Windows CE versions 1.0 and 1.01.
SWP_FRAMECHANGED | Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed.
SWP_HIDEWINDOW | Hides the window.
SWP_NOACTIVATE | Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS | Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned. This value is not supported in Windows CE versions 1.0 and 1.01.
SWP_NOMOVE | Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER | Does not change the owner window’s position in the z-order.
SWP_NOREDRAW | Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION | Same as the SWP_NOOWNERZORDER flag.
SWP_NOSIZE | Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER | Retains the current z-order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW | Displays the window.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the specified window is a visible top-level window and the SWP_NOACTIVATE flag is not specified, this function activates the window. If the window is the currently active and either the SWP_NOACTIVATE flag or the SWP_HIDEWINDOW flag is specified, the activation is passed on to another visible top-level window.

A window can be made a topmost window either by setting the hWndInsertAfter parameter to HWND_TOPMOST and ensuring that the SWP_NOZORDER flag is not set, or by setting a window’s position in the z-order so that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned windows are also made topmost. Its owners, however, are not changed.

If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application requests that a window be simultaneously activated and its position in the z-order changed), the value specified in hWndInsertAfter is used only in the following circumstances:

  • Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.
  • The window identified by hWnd is not the active window.

When you set the SWP_FRAMECHANGED flag in the nFlags parameter to this function, Windows CE redraws the entire non-client area of the window, which may change the size of the client area. This is the only way to get the non-client area to be recalculated and is typically used after a you've changed the window style by calling SetWindowLong.

If the SWP_SHOWWINDOW or SWP_HIDEWINDOW flag is set, the window cannot be moved or sized.

If you have changed certain window data using SetWindowLong, you must call SetWindowPos to have the changes take effect. Use the following combination for uFlags: SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED.

SetWindowPos always causes a WM_WINDOWPOSCHANGED message to be sent to the window. The flags passed in this message are exactly the same as those passed into the function. No other messages are sent by this function.

If an owned window was created with the WS_OVERLAPPED style, SetWindowPos uses the parent window coordinates to reposition it. If the owned window was created using the WS_POPUP style, it is repositioned using screen coordinates.

An application cannot activate an inactive window without also bringing it to the top of the z-order. Applications can change an activated window’s position in the z-order without restrictions, or it can activate a window and then move it to the top of the topmost or non-topmost windows.

If a topmost window is repositioned to the bottom (HWND_BOTTOM) of the z-order or after any non-topmost window, it is no longer topmost. When a topmost window is made non-topmost, its owners and its owned windows are also made non-topmost windows.

A non-topmost window can own a topmost window, but the reverse cannot occur. Any window (for example, a dialog box) owned by a topmost window is itself made a topmost window, to ensure that all owned windows stay above their owner.

If an application is not in the foreground, and should be in the foreground, it must call the SetForegroundWindow function.

See Also

MoveWindow, SetForegroundWindow, SetWindowLong, WM_WINDOWPOSCHANGED


SetWindowText

This function changes the text of the specified window’s title bar, if it has one. If the specified window is a control, the text of the control is changed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetWindowText( HWND hWnd, LPCTSTR lpString );

Parameters

hWnd
Handle to the window or control whose text is to be changed.
lpString
Long pointer to a null-terminated string to be used as the new title or control text.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the target window is owned by the current process, SetWindowText causes a WM_SETTEXT message to be sent to the specified window or control. If the control is a list box control created with the WS_CAPTION style, however, SetWindowText sets the text for the control, not for the list box entries.

The SetWindowText function does not expand tab characters (ASCII code 0x09). Tab characters are displayed as vertical bar (|) characters.

See Also

GetWindowText, WM_SETTEXT


ShowCaret

This function makes the caret visible on the screen at the caret’s current position. When the caret becomes visible, it begins flashing automatically.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ShowCaret(HWND hWnd);

Parameters

hWnd
[in] Handle to the window that owns the caret. If this parameter is NULL, ShowCaret searches the current task for the window that owns the caret.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

ShowCaret shows the caret if the specified window owns the caret and the caret has a shape. If either of these conditions is not met, ShowCaret displays nothing and returns zero. If the caret has been hidden two or more times in a row, ShowCaret displays nothing, but returns a nonzero value.

Hiding is cumulative. If your application calls HideCaret five times in a row, it must also call ShowCaret five times before the caret reappears.

The system provides one caret per queue. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

See Also

CreateCaret, DestroyCaret, GetCaretPos, HideCaret, SetCaretPos


ShowCursor

This function displays or hides the cursor.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int ShowCursor( BOOL bShow );

Parameters

bShow
[in] Boolean that specifies whether the internal display counter is to be incremented or decremented. If bShow is TRUE, the display count is incremented by one. If bShow is FALSE, the display count is decremented by one.

Return Values

The return value specifies the new display counter.

Remarks

This function sets an internal display counter that determines whether the cursor should be displayed. The cursor is displayed only if the display count is greater than or equal to 0. If a mouse is installed, the initial display count is 0. If no mouse is installed, the display count is –1.

See also

ClipCursor, GetCursorPos, SetCursor, SetCursorPos


ShowWindow

This function sets the specified window’s show state.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ShowWindow( HWND hWnd, int nCmdShow);

Parameters

hWnd
Handle to the window.
nCmdShow
Specifies how the window is to be shown. The first time ShowWindow is called, the value should be the value obtained by the WinMain function in its nCmdShow parameter. In subsequent calls, this parameter can be one of the following values:
Value
Description
SW_FORCEMINIMIZE | Windows NT 5.0 and later: Minimizes a window, even if the thread that owns the window is hung. This flag should only be used when minimizing windows from a different thread.
SW_HIDE | Hides the window and activates another window.
SW_MAXIMIZE | Maximizes the specified window.
SW_MINIMIZE | Minimizes the specified window and activates the next top-level window in the z-order.
SW_RESTORE | Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW | Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT | Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application.
SW_SHOWMAXIMIZED | Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED | Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE | Displays the window as a minimized window. The active window remains active.
SW_SHOWNA | Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

Return Values

Nonzero indicates that the window was previously visible. Zero indicates that the window was previously hidden.

Windows CE Remarks

The nCmdShow parameter does not support the following values:

  • SW_MAXIMIZE
  • SW_MINIMIZE
  • SW_RESTORE
  • SW_SHOWDEFAULT
  • SW_SHOWMAXIMIZED
  • SW_SHOWMINIMIZED
  • SW_SHOWMINNOACTIVE

Remarks

The first time an application calls ShowWindow, it should use the WinMain function’s nCmdShow parameter as its nCmdShow parameter. Subsequent calls to ShowWindow must use one of the values in the given list, instead of the one specified by the WinMain function’s nCmdShow parameter.

See Also

CreateProcess, CreateWindow, WinMain


SipEnumIM

This function enumerates the currently available input methods (IMs).

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

int SipEnumIM( IMENUMPROC pEnumIMProc);

Parameters

pEnumIMProc
[in] Pointer to the SipEnumIMProc callback function that receives information about the available IMs.

Return Values

The number of IMs. Zero indicates there are no IMs to enumerate.

Remarks

For each IM, the SipEnumIM function retrieves information about that IM and passes it to the function pointed to by the pEnumIMProc parameter. The application-defined callback function can process the IM information as desired. Enumeration continues until there are no more IMs or the callback function returns zero.

SipEnumIM does not require that the input panel environment be loaded in order to successfully enumerate the IMs. Therefore, a call to SipEnumIM does not initialize the input panel environment. The input panel environment is initialized by the first function called that needs a loaded input environment. All input panel functions initialize the input panel environment except SipEnumIM, SipStatus, SipSetDefaultRect, and SipRegisterNotification.

See Also

SipEnumIMProc


SipEnumIMProc

This application-defined callback function is used with the SipEnumIM function to enumerate the currently available input methods.

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

int SipEnumIMProc( IMENUMINFO *pIMInfo );

Parameters

pIMInfo
[in] Pointer to an IMENUMINFO structure , which contains information on an installed input method (IM).

Return Values

Nonzero continues enumeration. Zero stops enumeration.

Remarks

The pEnumIMProc parameter of the SipEnumIM function defines a pointer to SipEnumIMProc, which is a placeholder for the application-defined function name. An application must register this callback function by passing its address to the SipEnumIM function.

See Also

IMENUMINFO, SipEnumIM


SipGetCurrentIM

This function returns the class identifier (CLSID) of the current input method (IM).

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipGetCurrentIM( CLSID *pClsid );

Parameters

pClsid
[out] Pointer to a buffer that contains the CLSID of the new IM.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Use the SipSetCurrentIM function to set the CLSID of the current IM.

See Also

SipSetCurrentIM


SipGetInfo

This function receives information including the state of the input panel, the area of the desktop that is not obscured by the input panel, the screen coordinates of the input panel, and information about the input method (IM) that the input panel is currently using.

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipGetInfo( SIPINFO *pSipInfo);

Parameters

pSipInfo
[out] Pointer to the SIPINFO structure that contains information about the current input panel.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The IM data that is part of the SIPINFO structure is defined by an IM, not by the Corsip component. Request this information only if you know specifically that the IM has data and only if you know how to use such data. If no IM data is available, a request to retrieve IM data causes SipGetInfo to fail. To prevent a request to retrieve IM data and avoid an unnecessary failure, set the dwImDataSize member of SIPINFO to 0 before calling SipGetInfo.

See Also

SipSetInfo, SIPINFO


SipRegisterNotification

This function registers a window, which then receives input panel notifications related to the current input method (IM).

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipRegisterNotification( HWND hWnd );

Parameters

hWnd
[in] Handle of the window to receive input panel notifications.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Only one application can register a window to receive input panel notifications. This registration remains in effect until the device is either cold or warm booted. The IM sends information, such as user input, to the input panel, and the input panel forwards that information to the window that hWnd identifies.

SipRegisterNotification does not require that the input panel environment be loaded in order to complete successfully. Therefore, a call to SipRegisterNotification does not initialize the input panel environment. The input panel environment is initialized by the first function called that needs a loaded input environment. All input panel functions initialize the input panel environment except SipEnumIM, SipStatus, SipSetDefaultRect, and SipRegisterNotification.


SipSetCurrentIM

This function sets the class identifier (CLSID) for the current input method (IM).

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipSetCurrentIM( CLSID *pClsid );

Parameters

pClsid
[in] Pointer to the buffer that contains that contains the CLSID of the new IM.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

An IM is a common control; therefore, it is a window class defined by the application developer.

SipGetCurrentIM returns the CLSID of the active IM.

See Also

SipGetCurrentIM


SipSetDefaultRect

This function sets the default size and position of the input panel window.

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipSetDefautRect( RECT * pRect );

Parameter

pRect
[in] Pointer to a RECT structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The default size and position do not take effect until the application loads a new IM.

SipSetDefaultRect does not require that the input panel environment be loaded in order to complete successfully. Therefore, a call to SipSetDefaultRect does not initialize the input panel environment. The input panel environment is initialized by the first function called that needs a loaded input environment. All input panel functions initialize the input panel environment except SipEnumIM, SipStatus, SipSetDefaultRect, and SipRegisterNotification.

See Also

RECT


SipSetInfo

This function sets information including the state of the input panel, the area of the desktop that is not obscured by the input panel, the screen coordinates of the input panel, and application-defined information about the input method (IM) that the input panel is currently using.

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipSetInfo( SIPINFO *pSipInfo );

Parameters

pSipInfo
[in] Pointer to the SIPINFO structure that contains information about the current input panel.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Use SipGetInfo to set the input panel information to accommodate the current IM by setting information in the SIPINFO structure such as the input panel window position, size, and state.

To prevent undesirable information from being passed to SipSetInfo, clear the SIPINFO structure beforehand. The following code example shows how to clear the structure.

memset(pSipInfo, 0, sizeof(SIPINFO))

Use the SipGetInfo function to retrieve information the input panel.

See Also

SipGetInfo, SIPINFO


SipShowIM

This function shows or hides the currently active input panel window. An application must call this function to display the input panel and its current input method.

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL SipShowIM( DWORD dwFlags );

Parameters

dwShow
[in] Specifies whether to show or hide the current input panel window. It is one of the following flags:
Value
Description
SIPF_ON | Shows the input panel window.
SIPF_OFF | Hides the input panel window.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

When this function is called, the input panel notifies the input method (IM) of the appropriate action to take, which is whether to adopt a hidden or visible state.

On devices that have a limited display area, an application can call SipShowIM to hide the input panel and increase the display area for output.


SipStatus

This function is called by an application to determine if the input panel environment is loaded. With this information, an application can decide whether to continue interacting with the input panel environment.

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

DWORD SipStatus(void);

Return Values

SIP_STATUS_AVAILABLE indicates that the input panel environment is installed. SIP_STATUS_UNAVAILABLE indicates that the input panel environment is not installed.

Remarks

A call to SipStatus does not initialize the input panel environment. The input panel environment is initialized by the first function called that needs a loaded input environment. All input panel functions initialize the input panel environment except SipEnumIM, SipStatus, SipSetDefaultRect, and SipRegisterNotification.


sndPlaySound

This function plays a waveform sound.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

BOOL sndPlaySound(LPCTSTR lpszSoundName, UINT fuOptions);

Parameters

lpszSound
Long pointer to a null-terminated string that specifies the sound to play. This parameter can be either an entry in the registry or in WIN.INI that identifies a system sound, or it can be the name of a waveform-audio file. (If the function does not find the entry, the parameter is treated as a filename.) If this parameter is NULL, any currently playing sound is stopped.
fuSound
Flags for playing the sound. The following values are defined:
Value
Description
SND_ASYNC | The sound is played asynchronously and the function returns immediately after beginning the sound. To terminate an asynchronously played sound, call sndPlaySound with lpszSoundName set to NULL.
SND_LOOP | The sound plays repeatedly until sndPlaySound is called again with the lpszSoundName parameter set to NULL. You must also specify the SND_ASYNC flag to loop sounds.
SND_MEMORY | The parameter specified by lpszSoundName points to an image of a waveform sound in memory.
SND_NODEFAULT | If the sound cannot be found, the function returns silently without playing the default sound.
SND_NOSTOP | If a sound is currently playing, the function immediately returns FALSE, without playing the requested sound.
SND_SYNC | The sound is played synchronously and the function does not return until the sound ends.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the specified sound cannot be found, sndPlaySound plays the system default sound. If there is no system default entry in the registry or WIN.INI file, or if the default sound cannot be found, the function makes no sound and returns FALSE.

The specified sound must fit in available physical memory and be playable by an installed waveform-audio device driver. If sndPlaySound does not find the sound in the current directory, the function searches for it using the standard directory-search order.


StartDoc

This function starts a print job.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int StartDoc( HDC hdc, CONST DOCINFO * lpdi);

Parameters

hdc
[in] Handle to the device context (DC) for the print job.
lpdi
[in] Long pointer to a DOCINFO structure that contains the name of the document file and the name of the output file.

Return Values

A value greater than zero indicates success. This value is the print job identifier for the document. A value less than or equal to zero indicates failure. To get extended error information, call GetLastError.

Remarks

Applications should call the StartDoc function immediately before beginning a print job. Using this function ensures that multipage documents are not interspersed with other print jobs.

Windows CE does not support printing to files. It ignores the lpszOutput member of the DOCINFO structure.

See Also

EndDoc, StartPage


StartPage

This function prepares the printer driver to accept data.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

int StartPage( HDC hDC);

Parameters

hDC
[in] Handle to the device context (DC) for the print job.

Return Values

A value greater than zero indicates success. A value less than or equal to zero indicates failure. To get extended error information, call GetLastError.

Remarks

The system disables the ResetDC function between calls to the StartPage and EndPage functions. This means that you cannot change the device mode except at page boundaries. After calling EndPage, you can call ResetDC to change the device mode, if necessary. A call to ResetDC resets all device context attributes back to default values.

For Windows CE versions 1.0 through 2.01, the device context attributes are not retained between a call to EndPage and a call. You must reselect objects and set up the mapping mode again before printing the next page.

For Windows CE versions 2.10 and later, neither EndPage or StartPage resets the device context attributes. Device context attributes remain constant across subsequent pages. You do not need to re-select objects and set up the mapping mode again before printing the next page; however, doing so produces identical printer output and is compatible with earlier versions of Windows CE.

See Also

EndPage, StartDoc


StretchBlt

This function copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary. Windows stretches or compresses the bitmap according to the stretching mode set in the destination device context.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL StretchBlt(HDC hdcDest, int nXOriginDest, int nYOriginDest,
int nWidthDest, int nHeightDest, HDC hdcSrc, int nXOriginSrc,
int nYOriginSrc, int nWidthSrc, int nHeightSrc, DWORD dwRop);

Parameters

hdcDest
[in] Handle to the destination device context.
nXOriginDest
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.
nYOriginDest
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.
nWidthDest
[in] Specifies the width, in logical units, of the destination rectangle.
nHeightDest
[in] Specifies the height, in logical units, of the destination rectangle.
hdcSrc
[in] Handle to the source device context.
nXOriginSrc
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.
nYOriginSrc
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.
nWidthSrc
[in] Specifies the width, in logical units, of the source rectangle.
nHeightSrc
[in] Specifies the height, in logical units, of the source rectangle.
dwRop
[in] Specifies the raster operation to be performed. Raster operation codes define how the system combines colors in output operations that involve a brush, a source bitmap, and a destination bitmap.

See BitBlt for a list of common raster operation codes.

Windows CE versions 1.0 and 1.01 support only the SRCCOPY and SRCINVERT raster operations.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

StretchBlt stretches or compresses the source bitmap in memory and then copies the result to the destination rectangle. The color data for pattern or destination pixels is merged after the stretching or compression occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

If the specified raster operation requires a brush, the system uses the brush currently selected into the destination device context.

The destination coordinates are transformed by using the transformation currently specified for the destination device context; the source coordinates are transformed by using the transformation currently specified for the source device context.

If the source transformation has a rotation or shear, an error occurs.

If destination, source, and pattern bitmaps do not have the same color format, StretchBlt converts the source and pattern bitmaps to match the destination bitmap.

If StretchBlt must convert a monochrome bitmap to a color bitmap, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert a color bitmap to a monochrome bitmap, it sets pixels that match the background color to white (1) and sets all other pixels to black (0). The foreground and background colors of the device context with color are used.

StretchBlt creates a mirror image of a bitmap if the signs of the nWidthSrc and nWidthDest parameters or of the nHeightSrc and nHeightDest parameters differ. If nWidthSrc and nWidthDest have different signs, the function creates a mirror image of the bitmap along the x-axis. If nHeightSrc and nHeightDest have different signs, the function creates a mirror image of the bitmap along the y-axis. Windows CE versions 1.0 and 1.01 do not support mirroring.

Not all devices support the StretchBlt function. For more information, see the GetDeviceCaps.

See Also

BitBlt, GetDeviceCaps, MaskBlt


SystemIdleTimerReset

This function resets the system idle timer.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

void SystemIdleTimerReset( )

Return Value

None.

Remarks

When there are no more threads to run, a Windows CE-based device enters the idle state to conserve power. The transition from the on state to the idle state takes approximately 10 microseconds.


TrackPopupMenu

This function displays a floating pop-up menu at the specified location and tracks the selection of items on the pop-up menu. The floating pop-up menu can appear anywhere on the screen.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TrackPopupMenu(HMENU hMenu, UINT uFlags, int x, int y,
int nReserved, HWND hWnd, const RECT *prcRect);

Parameters

hMenu
[in] Handle to the shortcut menu to be displayed. The handle can be obtained by calling CreatePopupMenu to create a new shortcut menu, or by calling GetSubMenu to retrieve the handle to a submenu associated with an existing menu item.
uFlags
[in] A set of bit flags that specify function options.

Use one of the following bit flag constants to specify how the function positions the shortcut menu horizontally.
Value
Description
TPM_CENTERALIGN | If this flag is set, the function centers the shortcut menu horizontally relative to the coordinate specified by the x parameter.
TPM_LEFTALIGN | If this flag is set, the function positions the shortcut menu so that its left side is aligned with the coordinate specified by the x parameter.
TPM_RIGHTALIGN | Positions the shortcut menu so that its right side is aligned with the coordinate specified by the x parameter.
Use one of the following bit flag constants to specify how the function positions the shortcut menu vertically.
TPM_BOTTOMALIGN | If this flag is set, the function positions the shortcut menu so that its bottom side is aligned with the coordinate specified by the y parameter.
TPM_TOPALIGN | If this flag is set, the function positions the shortcut menu so that its top side is aligned with the coordinate specified by the y parameter.
TPM_VCENTERALIGN | If this flag is set, the function centers the shortcut menu vertically relative to the coordinate specified by the y parameter.

Use the following bit flag constants to determine the user selection without having to set up a parent window for the menu.
Value
Description
TPM_NONOTIFY | Unsupported.
TPM_RETURNCMD | If this flag is set, the function returns the menu item identifier of the user's selection in the return value.

x
[in] Specifies the horizontal location of the shortcut menu, in screen coordinates.
y
[in] Specifies the vertical location of the shortcut menu, in screen coordinates.
nReserved
[in] Reserved; set to zero.
hWnd
[in] Handle to the window that owns the shortcut menu. This window receives all messages from the menu. The window does not receive a WM_COMMAND message from the menu until the function returns.

If you specify TPM_NONOTIFY in the uFlags parameter, the function does not send messages to the window identified by hWnd. However, you must still pass a window handle in hWnd. It can be any window handle from your application.

prcRect
[in] Ignored.

Return Values

If you specify TPM_RETURNCMD in the uFlags parameter, the return value is the menu-item identifier of the item that the user selected. If the user cancels the menu without making a selection, or if an error occurs, then the return value is zero.

If you do not specify TPM_RETURNCMD in the uFlags parameter, the return value is nonzero if the function succeeds and zero if it fails. To get extended error information, call GetLastError.

See Also

CreatePopupMenu, GetSubMenu, RECT, WM_COMMAND


TrackPopupMenuEx

This function displays a floating pop-up menu at the specified location and tracks the selection of items on the pop-up menu. The floating pop-up menu can appear anywhere on the screen.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TrackPopupMenuEx(HMENU hmenu, UINT uFlags, int x, int y,
HWND hwnd, LPTPMPARAMS lptpm);

Parameters

hmenu
[in] Handle to the shortcut menu to be displayed. This handle can be obtained by calling the CreatePopupMenu function to create a new shortcut menu or by calling the GetSubMenu function to retrieve the handle to a submenu associated with an existing menu item.
uFlags
[in] Specifies positioning and other options. This parameter can be zero or more of the values listed with the TrackPopupMenu function.
x
[in] Horizontal location of the shortcut menu, in screen coordinates.
y
[in] Vertical location of the shortcut menu, in screen coordinates.
hwnd
[in] Handle to the window that owns the shortcut menu. This window receives all messages from the menu. The window does not receive a WM_COMMAND message from the menu until the function returns.
lptpm
[in] Long pointer to a TPMPARAMS structure that specifies an area of the screen the menu should not overlap. This parameter can be NULL.

Return Values

If you specify TPM_RETURNCMD in the uFlags parameter, the return value is the menu-item identifier of the item that the user selected. If the user cancels the menu without making a selection, or if an error occurs, then the return value is zero.

If you do not specify TPM_RETURNCMD in the uFlags parameter, the return value is nonzero if the function succeeds and zero if it fails. To get extended error information, call GetLastError.

Remarks

For Windows CE versions 1.0 and 1.01, the lptpm parameter is not supported and must be set to NULL. This parameter is supported in versions 2.0 and later.

See Also

CreatePopupMenu, GetSubMenu, TPMPARAMS, TrackPopupMenu, WM_COMMAND


TranslateAccelerator

This function processes accelerator keys for menu commands. TranslateAccelerator translates a WM_KEYDOWN or WM_SYSKEYDOWN message to a WM_COMMAND message and then sends the WM_COMMAND message directly to the appropriate window procedure. TranslateAccelerator does not return until the window procedure has processed the message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

int TranslateAccelerator(HWND hWnd, HACCEL hAccTable, LPMSG lpMsg);

Parameters

hWnd
Handle to the window whose messages are to be translated.
hAccTable
Handle to an accelerator table. The accelerator table must have been loaded by a call to the LoadAccelerators function or created by a call to the CreateAcceleratorTable function.
lpMsg
Long pointer to an MSG structure that contains message information retrieved from the calling thread’s message queue by using the GetMessage or PeekMessage function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

All accelerator key messages are translated into WM_COMMAND messages; Windows CE does not support the WM_SYSCOMMAND message.

Remarks

To differentiate the message that this function sends from messages sent by menus or controls, the high-order word of the wParam parameter of the WM_COMMAND or WM_SYSCOMMAND message contains the value 1.

Accelerator key combinations used to select items from the window menu are translated into WM_SYSCOMMAND messages; all other accelerator key combinations are translated into WM_COMMAND messages.

When TranslateAccelerator returns a nonzero value and the message is translated, the application should not use the TranslateMessage function to process the message again.

An accelerator need not correspond to a menu command.

If the accelerator command corresponds to a menu item, the application is sent a WM_INITMENUPOPUP message, as if the user were trying to display the menu. However, these messages are not sent if any of the following conditions exist:

  • The window is disabled.
  • The menu item is disabled.
  • The accelerator key combination does not correspond to an item on the window menu and the window is minimized.
  • A mouse capture is in effect. For information about mouse capture, see the SetCapture function.

If the specified window is the active window and no window has the keyboard focus (which is generally the case if the window is minimized), TranslateAccelerator translates WM_SYSKEYUP and WM_SYSKEYDOWN messages instead of WM_KEYUP and WM_KEYDOWN messages.

If an accelerator keystroke occurs that corresponds to a menu item when the window that owns the menu is minimized, TranslateAccelerator does not send a WM_COMMAND message. However, if an accelerator keystroke occurs that does not match any of the items in the window’s menu or in the window menu, the function sends a WM_COMMAND message, even if the window is minimized.

See Also

CreateAcceleratorTable, GetMessage, LoadAccelerators, MSG, PeekMessage, SetCapture, TranslateMessage, WM_COMMAND, WM_INITMENUPOPUP, WM_KEYDOWN, WM_SYSKEYDOWN


TranslateCharsetInfo

This function translates based on the specified character set, code page, or font signature value, setting all members of the destination structure to appropriate values.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.10 and later

Syntax

UINT TranslateCharsetInfo( DWORD FAR *lpSrc,
LPCHARSETINFO lpCs, DWORD dwFlags );

Parameters

lpSrc
[in] Either a long pointer to a code page bitfield or a value as defined by the dwFlags parameter. If dwFlags is TCI_SRCFONTSIG, this parameter is the address of the fsCsb member of a FONTSIGNATURE structure. Otherwise, this parameter is a 32-bit value.
lpCs
[out] Long pointer to a CHARSETINFO structure that receives the translated character set information.
dwFlags
[in] Specifies a bitmask of translation flags. It is one of the following values:
Value
Description
TCI_SRCCHARSET | Source contains the character set value in the low word, and zero in the high word.
TCI_SRCCODEPAGE | Source is a code-page identifier in the low word and zero in the high word.
TCI_SRCFONTSIG | Source is the code-page bitfield portion of a FONTSIGNATURE structure. On input, you set one bit. Choose from the ANSI range (bits 0-15), the combined ANSI and OEM range (bits 16-31), or the OEM range (bits 32-63). On output, the structure has only one bit set.
If the TCI_SRCFONTSIG value is given, the lpSrc parameter must be the address of the code-page bit field. If any other TCI_* value is given, the lpSrc parameter must be a value not an address.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

OEM code pages are not supported.

Character sets, code pages, and font signature bitmaps supported by Windows CE are listed in the following table.

Character Sets
Code Pages
Font Signature Bitmaps
ANSI_CHARSET | 1252 | FS_LATIN1
SHIFTJIS_CHARSET | 932 | FS_JISJAPAN
HANGEUL_CHARSET | 949 | FS_WANSUNG
JOHAB_CHARSET | 1361 | FS_JOHAB
GB2312_CHARSET | 936 | FS_CHINESESIMP
CHINESEBIG5_CHARSET | 950 | FS_CHINESETRAD
HEBREW_CHARSET | 1255 | FS_HEBREW
ARABIC_CHARSET | 1256 | FS_ARABIC
GREEK_CHARSET | 1253 | FS_GREEK
TURKISH_CHARSET | 1254 | FS_TURKISH
BALTIC_CHARSET | 1257 | FS_BALTIC
EASTEUROPE_CHARSET | 1250 | FS_LATIN2
RUSSIAN_CHARSET | 1251 | FS_CYRILLIC
THAI_CHARSET | 874 | FS_THAI

The table entries are ordered exactly as they are translated. For example, specifying lpSrc as HANGEUL_CHARSET and dwFlags as TCI_SRCCHARSET fills CHARSETINFO with HANGEUL_CHARSET, code page 949, and FS_WANSUNG. Specifying lpSrc as code page 936 and dwFlags as TCI_SRCCODEPAGE fills CHARSETINFO with GB2312_CHARSET, code page 936, and FS_CHINESESIMP.

On output, the fsUSB and fsCsb members of the FONTSIGNATURE structure—specified by the fs member of the CHARSETINFO structure—are zero-filled before setting the returned code-page bitfield value.

See Also

CHARSETINFO


TranslateMessage

This function translates virtual-key messages into character messages. The character messages are posted to the calling thread’s message queue, to be read the next time the thread calls the GetMessage or PeekMessage function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TranslateMessage(const MSG *lpMsg);

Parameters

lpMsg
[in] Long pointer to an MSG structure that contains message information retrieved from the calling thread’s message queue by using the GetMessage or PeekMessage function.

Return Values

Nonzero indicates that the message is translated, that is, a character message is posted to the thread’s message queue. If the message is WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, the return value is nonzero, regardless of the translation. Zero indicates that the message is not translated, that is, a character message is not posted to the thread’s message queue.

Remarks

The TranslateMessage function does not modify the message pointed to by the lpMsg parameter.

WM_KEYDOWN and WM_KEYUP combinations produce a WM_CHAR or WM_DEADCHAR message. WM_SYSKEYDOWN and WM_SYSKEYUP combinations produce a WM_SYSCHAR or WM_SYSDEADCHAR message.

TranslateMessage produces WM_CHAR messages only for keys that are mapped to ASCII characters by the keyboard driver. Windows CE does not support scan codes or extended key flags, so it does not support the values 16 through 24 in the lKeyData parameter (lParam) of the WM_CHAR message generated by the TranslateMessage function.

TranslateMessage can only be used to translate messages received from calls to GetMessage or PeekMessage.

If applications process virtual-key messages for some other purpose, they should not call TranslateMessage. For instance, an application should not call TranslateMessage if the TranslateAccelerator function returns a nonzero value.

See Also

GetMessage, PeekMessage, TranslateAccelerator, WM_CHAR, WM_DEADCHAR, WM_KEYDOWN, WM_KEYUP, WM_SYSCHAR, WM_SYSDEADCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


TransparentImage

This function transfers a bitmap, omitting the portions drawn in a specified color.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL TransparentImage(HDC hdcDest, LONG DstX, LONG DstY,
LONG DstCx, LONG DstCy, HANDLE hSrc, LONG SrcX, LONG SrcY,
LONG SrcCx, LONG SrcCy, COLORREF TransparentColor );

Parameters

hdcDest
[in] Handle to a device context.
DstX
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.
DstY
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.
DstCx
[in] Specifies the width, in logical units, of the destination rectangle.
DistCy
[in] Specifies the height, in logical units, of the destination rectangle.
hSrc
[in] Specifies a source device context or a source bitmap.
SrcX
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.
SrcY
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.
SrcCx
[in] Specifies the width, in logical units, of the source rectangle.
SrcCy
[in] Specifies the height, in logical units, of the source rectangle.
TransparentColor
[in] Indicates the color in the bitmap that will be rendered transparent.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the hSrc parameter is a HBITMAP, then that bitmap must not be selected into a device context at the time TransparentImage is called.

See Also

StretchBlt, MaskBlt


UnregisterClass

This function removes a window class, freeing the memory required for the class.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL UnregisterClass( LPCTSTR lpClassName, HINSTANCE hInstance );

Parameters

lpClassName
Long pointer to a null-terminated string or is an integer atom. If lpClassName is a string, it specifies the window class name. This class name must have been registered by a previous call to the RegisterClass function. System classes, such as dialog box controls, cannot be unregistered.

If this parameter is an integer atom, it must be a global atom created by a previous call to the RegisterClass function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

hInstance
Handle to the instance of the module that created the class.

Return Values

Nonzero indicates success. Zero indicates that the class could not be found or if a window still exists that was created with the class. To get extended error information, call GetLastError.

Remarks

Before calling this function, an application must destroy all windows created with the specified class.

All window classes that an application registers are unregistered when it terminates.

Windows 95: All window classes registered by a DLL are unregistered when the DLL is unloaded.

Windows NT: No window classes registered by a DLL registers are unregistered when the DLL is unloaded.

See Also

RegisterClass


UnregisterHotKey

This function frees a hot key previously registered by the calling thread.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL UnregisterHotKey( HWND hWnd, int id );

Parameters

hWnd
[in] Handle to the window associated with the hot key to be freed. This parameter should be NULL if the hot key is not associated with a window.
id
[in] Identifier of the hot key to be freed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

RegisterHotKey, WM_HOTKEY


UpdateWindow

This function updates the client area of the specified window by sending a WM_PAINT message to the window if the window’s update region is not empty. UpdateWindow sends a WM_PAINT message directly to the window procedure of the specified window, bypassing the application queue. If the update region is empty, no message is sent.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL UpdateWindow( HWND hWnd);

Parameters

hWnd
Handle to the window to be updated.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

See Also

GetUpdateRect, GetUpdateRgn, InvalidateRect, WM_PAINT


ValidateRect

This function validates the client area within a rectangle by removing the rectangle from the update region of the specified window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ValidateRect( HWND hWnd, const RECT *lpRect );

Parameters

hWnd
Handle to the window whose update region is to be modified. If this parameter is NULL, the system invalidates and redraws all windows and sends the WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before the function returns.
lpRect
Long pointer to a RECT structure that contains the client coordinates of the rectangle to be removed from the update region. If this parameter is NULL, the entire client area is removed.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

Windows CE Remarks

Passing in a NULL value for the hWnd parameter is not supported.

Remarks

The BeginPaint function automatically validates the entire client area. Neither the ValidateRect nor ValidateRgn function should be called if a portion of the update region must be validated before the next WM_PAINT message is generated.

The system continues to generate WM_PAINT messages until the current update region is validated.

See Also

BeginPaint, InvalidateRect, RECT, WM_PAINT


waveInAddBuffer

This function sends an input buffer to the specified waveform-audio input device. When the buffer is filled, the application is notified.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInAddBuffer(HWAVEIN hWaveIn,
LPWAVEHDR lpWaveInHdr, UINT wSize);

Parameters

hwi
Handle to the waveform-audio input device.
pwh
Pointer to a WAVEHDR structure that identifies the buffer.
cbwh
Size, in bytes, of the WAVEHDR structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVE | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_UNPREPARED | Buffer pointed to by the pwh parameter has not been prepared.

Remarks

When the buffer is filled, the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure.

The buffer must be prepared with the waveInPrepareHeader function before it is passed to this function.


waveInClose

This function closes the specified waveform-audio input device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInClose(HWAVEIN hWaveIn);

Parameters

hwi
Handle to the waveform-audio input device. If the function succeeds, the handle is no longer valid after this call.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_STILLPLAYING | There are still buffers in the queue.

Remarks

If there are input buffers that have been sent with the waveInAddBuffer function and that haven’t been returned to the application, the close operation will fail. Call the waveInReset function to mark all pending buffers as done.


waveInGetDevCaps

This function retrieves the capabilities of a specified waveform-audio input device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInGetDevCaps(UINT uDeviceID,
LPWAVEINCAPS lpCaps, UINT wSize);

Parameters

uDeviceID
Identifier of the waveform-audio output device. It can be either a device identifier or a Handle to an open waveform-audio input device.
pwic
Pointer to a WAVEINCAPS structure to be filled with information about the capabilities of the device.
cbwic
Size, in bytes, of the WAVEINCAPS structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_BADDEVICEID | Specified device identifier is out of range.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

Use this function to determine the number of waveform-audio input devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier. Only cbwic bytes (or less) of information is copied to the location pointed to by pwic. If cbwic is zero, nothing is copied and the function returns zero.


waveInGetErrorText

This function retrieves a textual description of the error identified by the specified error number.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInGetErrorText(UINT wError, LPTSTR lpText,
UINT wSize);

Parameters

mmrError
Error number.
pszText
Address of the buffer to be filled with the textual error description.
cchText
Size, in characters, of the buffer pointed to by pszText.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_BADERRNUM | Specified error number is out of range.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


waveInGetID

This function gets the device identifier for the specified waveform-audio input device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInGetID(HWAVEIN hWaveIn, PUINT lpuDeviceID);

Parameters

hwi
Handle to the waveform-audio input device.
puDeviceID
Pointer to a variable to be filled with the device identifier.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | The hwi parameter specifies an invalid handle.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.


waveInGetNumDevs

This retrieves the number of waveform input devices present in the system.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

UINT waveInGetNumDevs(void);

Return Values

The number of devices indicates success. Zero indicates that no devices are present or that an error occurred.


waveInGetPosition

This function retrieves the current input position of the specified waveform input device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInGetPosition(HWAVEIN hWaveIn, LPMMTIME lpInfo,
UINT wSize);

Parameters

hwi
Handle to the waveform-audio input device.
pmmt
Pointer to an MMTIME structure.
cbmmt
Size, in bytes, of the MMTIME structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

Before calling this function, set the wType member of the MMTIME structure to indicate the time format you want. After calling this function, check wType to determine whether the desired time format is supported. If the format is not supported, the member will specify an alternative format.

The position is set to zero when the device is opened or reset.


waveInMessage

This function sends messages to the waveform output device drivers.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInMessage(HWAVEIN hWave, UINT wMsg,
DWORD dw1, DWORD dw2);

Parameters

hwi
Handle to the waveform-audio input device.
uMsg
Message to send.
dwParam1 and dwParam2
Specifies message parameters.

Return Values

The value returned from the driver indicates success.


waveInOpen

This function opens a specified waveform input device for recording.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInOpen(LPHWAVEIN lphWaveIn, UINT uDeviceID, LPWAVEFORMATEX lpFormat, DWORD dwCallback,
DWORD dwCallbackInstance, DWORD dwFlags);

Parameters

phwi
Address filled with a handle identifying the open waveform-audio input device. Use this handle to identify the device when calling other waveform-audio input functions. This parameter can be NULL if WAVE_FORMAT_QUERY is specified for fdwOpen.
uDeviceID
Identifier of the waveform-audio input device to open. It can be either a device identifier or a Handle to an open waveform-audio input device. You can use the following flag instead of a device identifier:
Value
Description
WAVE_MAPPER The function selects a waveform-audio input device capable of recording in the specified format.

pwfx
Pointer to a WAVEFORMATEX structure that identifies the desired format for recording waveform-audio data. You can free this structure immediately after waveInOpen returns.
dwCallback
Specifies the address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio recording to process messages related to the progress of recording. If no callback function is required, this value can be zero.
dwCallbackInstance
Specifies user-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism.
fdwOpen
Flags for opening the device. The following values are defined:
Value
Description
CALLBACK_EVENT | The dwCallback parameter is an event handle.
CALLBACK_FUNCTION | The dwCallback parameter is a callback procedure address.
CALLBACK_NULL | No callback mechanism. This is the default setting.
CALLBACK_THREAD | The dwCallback parameter is a thread identifier.
CALLBACK_WINDOW | The dwCallback parameter is a window handle.
WAVE_FORMAT_DIRECT | If this flag is specified, the ACM driver does not perform conversions on the audio data.
WAVE_FORMAT_QUERY | The function queries the device to determine whether it supports the specified format, but it does not open the device.
WAVE_MAPPED | The uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_ALLOCATED | Specified resource is already allocated.
MMSYSERR_BADDEVICEID | Specified device identifier is out of range.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_BADFORMAT | Attempted to open with an unsupported waveform-audio format.

Remarks

Use the waveInGetNumDevs function to determine the number of waveform-audio input devices present on the system. The device identifier specified by uDeviceID varies from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier.

If you choose to have a window or thread receive callback information, the following messages are sent to the window procedure or thread to indicate the progress of waveform-audio input: MM_WIM_OPEN, MM_WIM_CLOSE, and MM_WIM_DATA.

If you choose to have a function receive callback information, the following messages are sent to the function to indicate the progress of waveform-audio input: WIM_OPEN, WIM_CLOSE, and WIM_DATA.


waveInPrepareHeader

This function prepares a buffer for waveform input.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInPrepareHeader(HWAVEIN hWaveIn,
LPWAVEHDR lpWaveInHdr, UINT wSize);

Parameters

hwi
Handle to the waveform-audio input device.
pwh
Pointer to a WAVEHDR structure that identifies the buffer to be prepared.
cbwh
Size, in bytes, of the WAVEHDR structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

The lpData, dwBufferLength, and dwFlags members of the WAVEHDR structure must be set before calling this function (dwFlags must be zero).


waveInReset

This function stops input on a specified waveform input device and resets the current position to 0. All pending buffers are marked as done and returned to the application.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Synax

MMRESULT waveInReset(HWAVEIN hWaveIn);

Parameters

hwi
Handle to the waveform-audio input device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.


waveInStart

This function starts input on the specified waveform input device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInStart(HWAVEIN hWaveIn);

Parameters

hwi
Handle to the waveform-audio input device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

Buffers are returned to the application when full or when the waveInReset function is called (the dwBytesRecorded member in the header will contain the length of data). If there are no buffers in the queue, the data is thrown away without notifying the application, and input continues.

Calling this function when input is already started has no effect, and the function returns zero.


waveInStop

This function stops waveform input.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInStop(HWAVEIN hWaveIn);

Parameters

hwi
Handle to the waveform-audio input device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

If there are any buffers in the queue, the current buffer will be marked as done (the dwBytesRecorded member in the header will contain the length of data), but any empty buffers in the queue will remain there.

Calling this function when input is not started has no effect, and the function returns zero.


waveInUnprepareHeader

This function cleans up the preparation performed by waveInPrepareHeader. The function must be called after the device driver fills a data buffer and returns it to the application. You must call this function before freeing the data buffer.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveInUnprepareHeader(HWAVEIN hWaveIn, LPWAVEHDR lpWaveInHdr, UINT wSize);

Parameters

hwi
Handle to the waveform-audio input device.
pwh
Pointer to a WAVEHDR structure identifying the buffer to be cleaned up.
cbwh
Size, in bytes, of the WAVEHDR structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_STILLPLAYING | Buffer pointed to by the pwh parameter is still in the queue.

Remarks

This function complements the waveInPrepareHeader function.

You must call this function before freeing the buffer. After passing a buffer to the device driver with the waveInAddBuffer function, you must wait until the driver is finished with the buffer before calling waveInUnprepareHeader. Unpreparing a buffer that has not been prepared has no effect, and the function returns zero.


waveOutBreakLoop

This function breaks a loop on a specified waveform output device and allows playback to continue with the next block in the driver list.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutBreakLoop(HWAVEOUT hWaveOut);

Parameters

hwo
Handle to the waveform-audio output device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

The blocks making up the loop are played to the end before the loop is terminated.

Calling this function when nothing is playing or looping has no effect, and the function returns zero.


waveOutClose

This function closes the specified waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutClose(HWAVEOUT hWaveOut);

Parameters

hwo
Handle to the waveform-audio output device. If the function succeeds, the handle is no longer valid after this call.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_STILLPLAYING | There are still buffers in the queue.

Remarks

If the device is still playing a waveform-audio file, the close operation fails. Use the waveOutReset function to terminate playback before calling waveOutClose.


waveOutGetDevCaps

This function queries a specified waveform device to determine its capabilities.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutGetDevCaps(UINT uDeviceID,
LPWAVEOUTCAPS lpCaps, UINT wSize);

Parameters

uDeviceID
Identifier of the waveform-audio output device. It can be either a device identifier or a Handle to an open waveform-audio output device.
pwoc
Pointer to a WAVEOUTCAPS structure to be filled with information about the capabilities of the device.
cbwoc
Size, in bytes, of the WAVEOUTCAPS structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

Use the waveOutGetNumDevs function to determine the number of waveform-audio output devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier. Only cbwoc bytes (or less) of information is copied to the location pointed to by pwoc. If cbwoc is zero, nothing is copied and the function returns zero.


waveOutGetErrorText

This function retrieves a textual description of the error identified by the specified error number.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutGetErrorText(UINT wError, LPTSTR lpText,
UINT wSize);

Parameters

mmrError
Error number.
pszText
Address of a buffer to be filled with the textual error description.
cchText
Size, in characters, of the buffer pointed to by pszText.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


waveOutGetID

This function gets the device identifier for a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Synax

MMRESULT waveOutGetID(HWAVEOUT hWaveOut,
PUINT lpuDeviceID);

Parameters

hwo
Handle to the waveform-audio output device.
puDeviceID
Pointer to a variable to be filled with the device identifier.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | The hwo parameter specifies an invalid handle.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.


waveOutGetNumDevs

This function retrieves the number of waveform output devices present in the system.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

UINT waveOutGetNumDevs(void);

Return Values

The number of devices indicates success. Zero indicates that no devices are present or that an error occurred.


waveOutGetPitch

This function queries the current pitch setting of a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutGetPitch(HWAVEOUT hWaveOut,
LPDWORD lpdwPitch);

Parameters

hwo
Handle to the waveform-audio output device.
pdwPitch
Pointer to a variable to be filled with the current pitch multiplier setting. The pitch multiplier indicates the current change in pitch from the original authored setting. The pitch multiplier must be a positive value.

The pitch multiplier is specified as a fixed-point value. The high-order word of the variable contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no pitch change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

Changing the pitch does not change the playback rate, sample rate, or playback time. Not all devices support pitch changes. To determine whether the device supports pitch control, use the WAVECAPS_PITCH flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).


waveOutGetPlaybackRate

This function queries the current playback rate setting of a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutGetPlaybackRate(HWAVEOUT hWaveOut,
LPDWORD lpdwRate);

Parameters

hwo
Handle to the waveform-audio output device.
pdwRate
Pointer to a variable to be filled with the current playback rate. The playback rate setting is a multiplier indicating the current change in playback rate from the original authored setting. The playback rate multiplier must be a positive value.

The rate is specified as a fixed-point value. The high-order word of the variable contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no playback rate change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

Changing the playback rate does not change the sample rate but does change the playback time. Not all devices support playback rate changes. To determine whether a device supports playback rate changes, use the WAVECAPS_PLAYBACKRATE flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).


waveOutGetPosition

This function retrieves the current playback position of the specified waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutGetPosition(HWAVEOUT hWaveOut,
LPMMTIME lpInfo, UINT wSize);

Parameters

hwo
Handle to the waveform-audio output device.
pmmt
Pointer to an MMTIME structure.
cbmmt
Size, in bytes, of the MMTIME structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

Before calling this function, set the wType member of the MMTIME structure to indicate the time format you want. After calling this function, check wType to determine whether the time format is supported. If the format is not supported, wType will specify an alternative format.

The position is set to zero when the device is opened or reset.


waveOutGetVolume

This function queries the current volume setting of a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutGetVolume(HWAVEOUT hwo,
LPDWORD lpdwVolume);

Parameters

hwo
Handle to an open waveform-audio output device. This parameter can also be a device identifier.
pdwVolume
Pointer to a variable to be filled with the current volume setting. The low-order word of this location contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of the specified location contains the mono volume level.

The full 16-bit setting(s) set with the waveOutSetVolume function is returned, regardless of whether the device supports the full 16 bits of volume-level control.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

If a device identifier is used, then the result of the waveOutGetVolume call and the information returned in pdwVolume applies to all instances of the device. If a device handle is used, then the result and information returned applies only to the instance of the device referenced by the device handle.

Not all devices support volume changes. To determine whether the device supports volume control, use the WAVECAPS_VOLUME flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

To determine whether the device supports left- and right-channel volume control, use the WAVECAPS_LRVOLUME flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by waveOutGetDevCaps).

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.


waveOutMessage

This function sends messages to the waveform output device drivers.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutMessage(HWAVEOUT hWaveOut, UINT msg, DWORD dw1, DWORD dw2);

Parameters

hwo
Handle to the waveform-audio output device.
uMsg
Message to send.
dwParam1 and dwParam2
Specifies message parameters.

Return Values

The value returned from the driver indicates success.


waveOutOpen

This function opens a specified waveform output device for playback.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutOpen(LPHWAVEOUT phwo, UINT uDeviceID, LPWAVEFORMATEX pwfx, DWORD dwCallback, DWORD dwCallbackInstance, DWORD fdwOpen);

Parameters

phwo
Address filled with a handle identifying the open waveform-audio output device. Use the handle to identify the device when calling other waveform-audio output functions. This parameter might be NULL if the WAVE_FORMAT_QUERY flag is specified for fdwOpen.
uDeviceID
Identifier of the waveform-audio output device to open. It can be either a device identifier or a Handle to an open waveform-audio input device. You can use the following flag instead of a device identifier:
Value
Description
WAVE_MAPPER The function selects a waveform-audio output device capable of playing the specified format.

pwfx
Pointer to a WAVEFORMATEX structure that identifies the format of the waveform-audio data to be sent to the device. You can free this structure immediately after passing it to waveOutOpen.
dwCallback
Specifies the address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio playback to process messages related to the progress of the playback. If no callback function is required, this value can be zero.
dwCallbackInstance
Specifies user-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism.
fdwOpen
Flags for opening the device. The following values are defined:
Value
Description
CALLBACK_EVENT | The dwCallback parameter is an event handle.
CALLBACK_FUNCTION | The dwCallback parameter is a callback procedure address.
CALLBACK_NULL | No callback mechanism. This is the default setting.
CALLBACK_THREAD | The dwCallback parameter is a thread identifier.
CALLBACK_WINDOW | The dwCallback parameter is a window handle.
WAVE_ALLOWSYNC | If this flag is specified, a synchronous waveform-audio device can be opened. If this flag is not specified while opening a synchronous driver, the device will fail to open.
WAVE_FORMAT_DIRECT | If this flag is specified, the ACM driver does not perform conversions on the audio data.
WAVE_FORMAT_QUERY | If this flag is specified, waveOutOpen queries the device to determine if it supports the specified format, but the device is not actually opened.
WAVE_MAPPED | If this flag is specified, the uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_BADDEVICEID | Specified device identifier is out of range.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_BADFORMAT | Attempted to open with an unsupported waveform-audio format.
WAVERR_SYNC | Device is synchronous but waveOutOpen was called without using the WAVE_ALLOWSYNC flag.

Remarks

Use the waveOutGetNumDevs function to determine the number of waveform-audio output devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier.

The structure pointed to by pwfx can be extended to include type-specific information for certain data formats by using the WAVEFORMATEX structure to specify the length of the additional data.

If you choose to have a window or thread receive callback information, the following messages are sent to the window procedure function to indicate the progress of waveform-audio output: MM_WOM_OPEN, MM_WOM_CLOSE, and MM_WOM_DONE.

If you choose to have a function receive callback information, the following messages are sent to the function to indicate the progress of waveform-audio output: WOM_OPEN, WOM_CLOSE, and WOM_DONE.


waveOutPause

This function pauses playback on a specified waveform output device. The current playback position is saved. Use waveOutRestart to resume playback from the current playback position.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutPause(HWAVEOUT hWaveOut);

Parameters

hwo
Handle to the waveform-audio output device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

Calling this function when the output is already paused has no effect, and the function returns zero.


waveOutPrepareHeader

This function prepares a waveform data block for playback.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutPrepareHeader(HWAVEOUT hwo,
LPWAVEHDR pwh, UINT cbwh);

Parameters

hwo
Handle to the waveform-audio output device.
pwh
Pointer to a WAVEHDR structure that identifies the data block to be prepared.
cbwh
Size, in bytes, of the WAVEHDR structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.

Remarks

The lpData, dwBufferLength, and dwFlags members of the WAVEHDR structure must be set before calling this function (dwFlags must be zero).

The dwFlags, dwBufferLength, and dwLoops members of the WAVEHDR structure can change between calls to this function and the waveOutWrite function. (The only flags that can change in this interval for the dwFlags member are WHDR_BEGINLOOP and WHDR_ENDLOOP.) If you change the size specified by dwBufferLength before the call to waveOutWrite, the new value must be less than the prepared value.

Preparing a header that has already been prepared has no effect, and the function returns zero.


waveOutReset

This function stops playback on a specified waveform output device and resets the current position to 0. All pending playback buffers are marked as done and returned to the application.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutReset(HWAVEOUT hWaveOut);

Parameters

hwo
Handle to the waveform-audio output device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.


waveOutRestart

This function restarts a paused waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutRestart(HWAVEOUT hWaveOut);

Parameters

hwo
Handle to the waveform-audio output device.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

Calling this function when the output is not paused has no effect, and the function returns zero.


waveOutSetPitch

This function sets the pitch of a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutSetPitch(HWAVEOUT hWaveOut, DWORD dwPitch);

Parameters

hwo
Handle to the waveform-audio output device.
dwPitch
Specifies a new pitch multiplier setting. This setting indicates the current change in pitch from the original authored setting. The pitch multiplier must be a positive value.

The pitch multiplier is specified as a fixed-point value. The high-order word contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no pitch change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

Changing the pitch does not change the playback rate or the sample rate, nor does it change the playback time. Not all devices support pitch changes. To determine whether the device supports pitch control, use the WAVECAPS_PITCH flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).


waveOutSetPlaybackRate

This function sets the playback rate of a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutSetPlaybackRate(HWAVEOUT hWaveOut,
DWORD dwRate);

Parameters

hwo
Handle to the waveform-audio output device.
dwRate
Specifies a new playback rate setting. This setting is a multiplier indicating the current change in playback rate from the original authored setting. The playback rate multiplier must be a positive value.

The rate is specified as a fixed-point value. The high-order word contains the signed integer part of the number, and the low-order word contains the fractional part. A value of 0x8000 in the low-order word represents one-half, and 0x4000 represents one-quarter. For example, the value 0x00010000 specifies a multiplier of 1.0 (no playback rate change), and a value of 0x000F8000 specifies a multiplier of 15.5.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

Changing the playback rate does not change the sample rate but does change the playback time. Not all devices support playback rate changes. To determine whether a device supports playback rate changes, use the WAVECAPS_PLAYBACKRATE flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).


waveOutSetVolume

This function sets the volume of a waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutSetVolume(HWAVEOUT hwo, DWORD dwVolume);

Parameters

hwo
Handle to an open waveform-audio output device. This parameter can also be a device identifier.
dwVolume
Specifies a new volume setting. The low-order word contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume, and a value of 0x0000 is silence.

If a device does not support both left and right volume control, the low-order word of dwVolume specifies the volume level, and the high-order word is ignored.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
MMSYSERR_NOTSUPPORTED | Function is not supported.

Remarks

If a device identifier is used, then the result of the waveOutSetVolume call applies to all instances of the device. If a device handle is used, then the result applies only to the instance of the device referenced by the device handle.

Not all devices support volume changes. To determine whether the device supports volume control, use the WAVECAPS_VOLUME flag to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function). To determine whether the device supports volume control on both the left and right channels, use the WAVECAPS_LRVOLUME flag.

Most devices do not support the full 16 bits of volume-level control and will not use the high-order bits of the requested volume setting. For example, for a device that supports 4 bits of volume control, requested volume level values of 0x4000, 0x4FFF, and 0x43BE all produce the same physical volume setting: 0x4000. The waveOutGetVolume function returns the full 16-bit setting set with waveOutSetVolume.

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.


waveOutUnprepareHeader

This function cleans up the preparation performed by waveOutPrepareHeader. The function must be called after the device driver is finished with a data block. You must call this function before freeing the data buffer.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutUnprepareHeader(HWAVEOUT hwo, LPWAVEHDR pwh, UINT cbwh);

Parameters

hwo
Handle to the waveform-audio output device.
pwh
Pointer to a WAVEHDR structure identifying the data block to be cleaned up.
cbwh
Size, in bytes, of the WAVEHDR structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_STILLPLAYING | Data block pointed to by the pwh parameter is still in the queue.

Remarks

This function complements waveOutPrepareHeader. You must call this function before freeing the buffer. After passing a buffer to the device driver with the waveOutWrite function, you must wait until the driver is finished with the buffer before calling waveOutUnprepareHeader.

Unpreparing a buffer that has not been prepared has no effect, and the function returns zero.


waveOutWrite

This function sends a data block to the specified waveform output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

MMRESULT waveOutWrite(HWAVEOUT hwo, LPWAVEHDR pwh,
UINT cbwh);

Parameters

hwo
Handle to the waveform-audio output device.
pwh
Pointer to a WAVEHDR structure containing information about the data block.
cbwh
Size, in bytes, of the WAVEHDR structure.

Return Values

One of the values described in the following table is returned.

Value
Description
MMSYSERR_NOERROR | Success.
MMSYSERR_INVALHANDLE | Specified device handle is invalid.
MMSYSERR_NODRIVER | No device driver is present.
MMSYSERR_NOMEM | Unable to allocate or lock memory.
WAVERR_UNPREPARED | Data block pointed to by the pwh parameter has not been prepared.

Remarks

When the buffer is finished, the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure.

The buffer must be prepared with the waveOutPrepareHeader function before it is passed to waveOutWrite. Unless the device is paused by calling the waveOutPause function, playback begins when the first data block is sent to the device.


WindowFromPoint

This function retrieves the handle to the window that contains the specified point.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

HWND WindowFromPoint( POINT Point );

Parameters

Point
Specifies a POINT structure that defines the point to be checked.

Return Values

A handle to the window that contains the point indicates success. NULL indicates that no window exists at the specified point. A handle to the window under the static text control indicates that the point is over a static text control.

Remarks

The WindowFromPoint function does not retrieve a handle to a hidden or disabled window, even if the point is within the window. An application should use the ChildWindowFromPoint function for a nonrestrictive search.

See Also

ChildWindowFromPoint, POINT


ACCEL

This structure defines an accelerator key used in an accelerator table.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagACCEL {
 BYTE fVirt;
 WORD key;
 WORD cmd;
 WORD pad;
} ACCEL;

Members

fVirt
Specifies the accelerator flags. It can be a combination of the following values:
Value
Description
FALT | The ALT key must be held down when the accelerator key is pressed.
FCONTROL | The CTRL key must be held down when the accelerator key is pressed.
FNOINVERT | Specifies that no top-level menu item is highlighted when the accelerator is used. If this flag is not specified, a top-level menu item will be highlighted, if possible, when the accelerator is used.
FSHIFT | The SHIFT key must be held down when the accelerator key is pressed.
FVIRTKEY | The key member specifies a virtual-key code. If this flag is not specified, key is assumed to specify an ASCII character code.

key
Specifies the accelerator key. This member can be either a virtual-key code or an ASCII character code.
cmd
Specifies the accelerator identifier. This value is placed in the low-order word of the wParam parameter of the WM_COMMAND or WM_SYSCOMMAND message when the accelerator is pressed.
pad
Reserved member that creates a WORD of padding between accelerator table entries.

See Also

WM_COMMAND, WM_SYSCOMMAND, CreateAcceleratorTable


BITMAP

This structure defines the type, width, height, color format, and bit values of a bitmap.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagBITMAP {
 LONG bmType;
LONG bmWidth;
LONG bmHeight;
LONG bmWidthBytes;
WORD bmPlanes;
WORD bmBitsPixel;
LPVOID bmBits;
} BITMAP;

Members

bmType
Specifies the bitmap type; set to zero
bmWidth
Specifies the width, in pixels, of the bitmap. The width must be greater than zero.
bmHeight
Specifies the height, in pixels, of the bitmap. The height must be greater than zero.
bmWidthBytes
Specifies the number of bytes in each scan line. This value must be divisible by 2, because the system assumes that the bit values of a bitmap form an array that is word aligned.
bmPlanes
Specifies the count of color planes.
bmBitsPixel
Specifies the number of bits required to indicate the color of a pixel.
bmBits
Pointer to the location of the bit values for the bitmap. The bmBits member must be a long pointer to an array of character (1-byte) values.

Remarks

The bitmap formats currently used are monochrome and color. The monochrome bitmap uses a one-bit, one-plane format. Each scan is a multiple of 32 bits.

Scans are organized as follows for a monochrome bitmap of height n:

Scan 0
Scan 1
.
.
.
Scan n-2
Scan n-1

The pixels on a monochrome device are either black or white. If the corresponding bit in the bitmap is 1, the pixel is set to the foreground color; if the corresponding bit in the bitmap is zero, the pixel is set to the background color.

All devices that have the RC_BITBLT device capability support bitmaps. For more information, see GetDeviceCaps.

Each device has a unique color format.

See Also

GetDeviceCaps, GetObject


BITMAPCOREHEADER

This structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagBITMAPCOREHEADER {
DWORD bcSize;
WORD bcWidth;
WORD bcHeight;
WORD bcPlanes;
WORD bcBitCount;
} BITMAPCOREHEADER;

Members

bcSize
Specifies the number of bytes required by the structure
bcWidth
Specifies the width of the bitmap, in pixels
bcHeight
Specifies the height of the bitmap, in pixels
bcPlanes
Specifies the number of planes for the target device. This value must be 1.
bcBitCount
Specifies the number of bits per pixel. This value must be 1, 2, 4, 8, or 24.

Remarks

The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and a color table to provide a complete definition of DIB dimensions and colors. For more information about specifying a DIB, see BITMAPCOREINFO.

An application should use the information stored in the bcSize member to locate the color table in a BITMAPCOREINFO structure. The following code sample shows how to locate the color table.

pColor = ((LPBYTE) pBitmapCoreInfo +
        (WORD) (pBitmapCoreInfo -> bcSize))

See Also

BITMAPCOREINFO, RGBTRIPLE


BITMAPCOREINFO

This structure defines the dimensions and color information for a device independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _BITMAPCOREINFO {
BITMAPCOREHEADER bmciHeader;
RGBTRIPLE bmciColors[1];
} BITMAPCOREINFO;

Members

bmciHeader
Specifies a BITMAPCOREHEADER structure that contains information about the dimensions and color format of a DIB.
bmciColors
Specifies an array of RGBTRIPLE structures that define the colors in the bitmap.

Remarks

A DIB consists of two parts: a BITMAPCOREINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG boundary. The origin of the bitmap is the lower left corner.

The bcBitCount member of the BITMAPCOREHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member can be one of the following values:

Value
Description
1 | The bitmap is monochrome, and the bmciColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmciColors table; if the bit is set, the pixel has the color of the second entry in the table.
2 | The bitmap has a maximum of 4 colors, and the bmciColors member contains up to 4 entries.
4 | The bitmap has a maximum of 16 colors, and the bmciColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8 | The bitmap has a maximum of 256 colors, and the bmciColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
24 | The bitmap has a maximum of 2^24 colors, and the bmciColors member is NULL. Each three-byte triplet in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel.

The colors in the bmciColors table should appear in order of importance.

Alternatively, for functions that use DIBs, the bmciColors member can be an array of 16-bit unsigned integers that specify indexes into the currently realized logical palette, instead of explicit RGB values. In this case, an application using the bitmap must call the DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with the iUsage parameter set to DIB_PAL_COLORS.

Note The bmciColors member should not contain palette indexes if the bitmap is to be stored in a file or transferred to another application. Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.

See Also

BITMAPCOREHEADER, RGBTRIPLE


BITMAPFILEHEADER

This structure contains information about the type, size, and layout of a file that containing a device-independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagBITMAPFILEHEADER {
 WORD bfType;
DWORD bfSize;
WORD bfReserved1;
WORD bfReserved2;
DWORD bfOffBits;
} BITMAPFILEHEADER;

Members

bfType
Specifies the file type. It must be BM.
bfSize
Specifies the size, in bytes, of the bitmap file
bfReserved1
Reserved; set to zero
bfReserved2
Reserved; set to zero
bfOffBits
Specifies the offset, in bytes, from the BITMAPFILEHEADER structure to the bitmap bits

Remarks

A BITMAPINFO or BITMAPCOREINFO structure immediately follows the BITMAPFILEHEADER structure in the DIB file.

See Also

BITMAPINFO


BITMAPINFO

This structure defines the dimensions and color information of a Windows-based device-independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagBITMAPINFO {
BITMAPINFOHEADER bmiHeader;
RGBQUAD bmiColors[1];
} BITMAPINFO;

Members

bmiHeader
Specifies a bitmap information header structure that contains information about the dimensions of color format. Use the BITMAPINFOHEADER structure.
bmiColors
Contains one of the following:
  • An array of RGBQUAD. The elements of the array make up the color table.
  • An array of 16-bit unsigned integers that specifies indexes into the currently realized logical palette. This use of bmiColors is allowed for functions that use DIBs. When bmiColors elements contain indexes to a realized logical palette, they must also call the following bitmap functions: CreateDIBPatternBrushPt and CreateDIBSection. The iUsage parameter of CreateDIBSection must be set to DIB_PAL_COLORS.

    The number of entries in the array depends on the values of the biBitCount and biClrUsed members of the BITMAPINFOHEADER structure.

    The colors in the bmiColors table appear in order of importance. For more information, see the “Remarks” section.

Remarks

A device-independent bitmap consists of two distinct parts: a BITMAPINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG data-type boundary. If the height of the bitmap is positive, the bitmap is a bottom-up DIB and its origin is the lower-left corner. If the height is negative, the bitmap is a top-down DIB and its origin is the upper left corner.

A bitmap is packed when the bitmap array immediately follows the BITMAPINFO header. Packed bitmaps are referenced by a single pointer. For packed bitmaps, the ClrUsed member of the BITMAPINFOHEADER structure must be set to an even number when using the DIB_PAL_COLORS mode so the DIB bitmap array starts on a DWORD boundary.

Note The bmiColors member should not contain palette indexes if the bitmap is stored in a file or transferred to another application.

Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.

See Also

BITMAPINFOHEADER, CreateDIBSection, RGBQUAD, CreateDIBPatternBrushPt, SetClipboardData, LOGBRUSH


BITMAPINFOHEADER

This structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagBITMAPINFOHEADER{
DWORD biSize;
LONG biWidth;
LONG biHeight;
WORD biPlanes;
WORD biBitCount
DWORD biCompression;
DWORD biSizeImage;
LONG biXPelsPerMeter;
LONG biYPelsPerMeter;
DWORD biClrUsed;
DWORD biClrImportant;
} BITMAPINFOHEADER;

Members

biSize
Specifies the number of bytes required by the structure.
biWidth
Specifies the width of the bitmap, in pixels.
biHeight
Specifies the height of the bitmap, in pixels. If biHeight is positive, the bitmap is a bottom-up DIB and its origin is the lower-left corner. If biHeight is negative, the bitmap is a top-down DIB and its origin is the upper-left corner.

If biHeight is negative, indicating a top-down DIB, biCompression must be either BI_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed.

biPlanes
Specifies the number of planes for the target device. This value must be set to 1.
biBitCount
Specifies the number of bits per pixel. The biBitCount member of the BITMAPINFOHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member must be one of the following values.
Value
Description
1 | The bitmap is monochrome, and the bmiColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmiColors table; if the bit is set, the pixel has the color of the second entry in the table.
2 | The bitmap has four possible color values.
4 | The bitmap has a maximum of 16 colors, and the bmiColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8 | The bitmap has a maximum of 256 colors, and the bmiColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
16 | The bitmap has a maximum of 2^16 colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each WORD in the bitmap array represents a single pixel. The relative intensities of red, green, and blue are represented with 5 bits for each color component. The value for blue is in the least significant 5 bits, followed by 5 bits each for green and red. The most significant bit is not used. The bmiColors color table is used for optimizing colors used on palette-based devices, and must contain the number of entries specified by the biClrUsed member of the BITMAPINFOHEADER.
24 | The bitmap has a maximum of 2^24 colors, and the bmiColors member is NULL. Each 3-byte triplet in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel. The bmiColors color table is used for optimizing colors used on palette-based devices, and must contain the number of entries specified by the biClrUsed member of the BITMAPINFOHEADER.
32 | The bitmap has a maximum of 2^32 colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each DWORD in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel. The high byte in each DWORD is not used. The bmiColors color table is used for optimizing colors used on palette-based devices, and must contain the number of entries specified by the biClrUsed member of the BITMAPINFOHEADER.
If the biCompression member of the BITMAPINFOHEADER is BI_BITFIELDS, the bmiColors member contains three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. Each DWORD in the bitmap array represents a single pixel.

biCompression
Specifies the type of compression for a compressed bottom-up bitmap (top-down DIBs cannot be compressed). This member must be the following value:
Value
Description
BI_RGB An uncompressed format

biSizeImage
Specifies the size, in bytes, of the image. This may be set to zero for BI_RGB bitmaps.
biXPelsPerMeter
Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. An application can use this value to select a bitmap from a resource group that best matches the characteristics of the current device.
biYPelsPerMeter
Specifies the vertical resolution, in pixels per meter, of the target device for the bitmap
biClrUsed
Specifies the number of color indexes in the color table that are actually used by the bitmap. If this value is zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member for the compression mode specified by biCompression.

If biClrUsed is nonzero and the biBitCount member is less than 16, the biClrUsed member specifies the actual number of colors the graphics engine or device driver accesses. If biBitCount is 16 or greater, the biClrUsed member specifies the size of the color table used to optimize performance of the system color palettes. If biBitCount equals 16 or 32, the optimal color palette starts immediately following the three DWORD masks.

If the bitmap is a packed bitmap (a bitmap in which the bitmap array immediately follows the BITMAPINFO header and is referenced by a single pointer), the biClrUsed member must be either zero or the actual size of the color table.

biClrImportant
Specifies the number of color indexes required for displaying the bitmap. If this value is zero, all colors are required.

Remarks

The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color table to provide a complete definition of the dimensions and colors of a DIB.

An application should use the information stored in the biSize member to locate the color table in a BITMAPINFO structure, as follows:

pColor = ((LPSTR)pBitmapInfo +
    (WORD)(pBitmapInfo->bmiHeader.biSize));

For Windows CE versions 1.0 and 1.01, the biBitCount member must be either one or two.

See Also

BITMAPINFO, DIBSECTION


CANDIDATEFORM

This structure contains position information for the candidate window.

At a Glance

Header file: | Wceemul.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

typedef _tagCANDIDATEFORM {
 DWORD dwIndex;
 DWORD dwStyle;
 POINT ptCurrentPos;
 RECT rcArea;
} CANDIDATEFORM;

Members

dwIndex
Specifies the candidate list identifier. Can be 0 for the first list, 1 for the second, and so on. The maximum index is 31.
dwStyle
Specifies the position style. It is one of the following values:
Value
Description
CFS_CANDIDATEPOS | Displays the upper-left corner of the candidate list window at the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window that contains the list window, and are subject to adjustment by the system.
CFS_EXCLUDE | Excludes the candidate window from the area specified by rcArea. The ptCurrentPos member specifies the coordinates of the current point of interest, typically the caret position.

ptCurrentPos
Coordinates of the upper-left corner of the candidate window or the caret position, depending on the value of dwStyle.
rcArea
Coordinates of the upper-left and lower-right corners of the exclusion area.

Remarks

In Japanese versions 1.0 and later, the ImmSetCandidateWindow function allows an index range from 0 through 4 for the dwIndex member of the CANDIDATEFORM structure. In Windows CE versions 2.10 and later, an index range from 0 through 3 is allowed.

See Also

POINT, RECT


CANDIDATELIST

This structure contains information about a candidate list.

At a Glance

Header file: | Wceemul.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

typedef struct _tagCANDIDATELIST {
 DWORD dwSize;
 DWORD dwStyle;
 DWORD dwCount;
 DWORD dwSelection;
 DWORD dwPageStart;
 DWORD dwPageSize;
 DWORD dwOffset[];
} CANDIDATELIST;

Members

dwSize
Specifies the size, in bytes, of the structure, the offset array, and all candidate strings
dwStyle
Specifies candidate style values. It can be one or more of the following values:
Value
Description
IME_CAND_UNKNOWN | Candidates are in a style other than listed here.
IME_CAND_READ | Candidates are in same reading.
IME_CAND_CODE | Candidates are in a code range.
IME_CAND_MEANING | Candidates are in same meaning.
IME_CAND_RADICAL | Candidates use the same radical character.
IME_CAND_STROKES | Candidates are in same number of strokes.

For the IME_CAND_CODE style, the candidate list has a special structure depending on the value of the dwCount member. If dwCount is 1, the dwOffset member contains a single DBCS character rather than an offset, and no candidate string is provided. If the dwCount member is greater than 1, the dwOffset member contains valid offsets, and the candidate strings are text representations of individual DBCS character values in hexadecimal notation.

dwCount
Specifies the number of candidate strings.
dwSelection
Specifies the index of the selected candidate string.
dwPageStart
Specifies the index of the first candidate string in the candidate window. This varies as the user presses the PAGE UP and PAGE DOWN keys.
dwPageSize
Specifies the number of candidate strings to be shown in one page in the candidate window. The user can move to the next page by pressing IME-defined keys, such as the PAGE UP or PAGE DOWN key. If this number is zero, an application can define a proper value by itself.
dwOffset
Specifies the offset to the start of the first candidate string, relative to the start of this structure. The offsets for subsequent strings immediately follow this member, forming an array of 32-bit offsets.

Remarks

The candidate strings immediately follow the last offset in the dwOffset array.


COLORREF

This value is a 32-bit value used to specify an RGB color.

The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is 0xFF.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Remarks

When specifying an explicit RGB color, the COLORREF value have the following hexadecimal form:

0x00bbggrr

The low-order byte contains a value for the relative intensity of red, the second byte contains a value for green, and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is 0xFF.

See Also

GetBValue, GetGValue, GetRValue, RGB, SetBkColor


COMMANDBANDSRESTOREINFO

This structure contains information necessary to restore a band to its current state.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCOMMANDBANDSRESTOREINFO {
 UINT cbSize;
 UINT wID;
 UINT fStyle;
 UINT cxRestored;
 BOOL fMaximized;
} COMMANDBANDSRESTOREINFO, *LPCOMMANDBANDSRESTOREINFO;

Members

dwSize
Size of the structure, in bytes. You must supply the value for this member.
wID
Identifier of the band. This member corresponds to the wID member of the REBARBANDINFO structure, and is filled in by the CommandBands_GetRestoreInformation function.
fStyle
Flags that specify the band style. This member corresponds to the fStyle member of the REBARBANDINFO structure, and is filled in by the CommandBands_GetRestoreInformation function. It can be a combination of the following values:
Value
Description
RBBS_BREAK | The band is on a new line.
RBBS_CHILDEDGE | The band has an edge at the top and bottom of the child window.
RBBS_FIXEDBMP | The background bitmap does not move when the band is resized.
RBBS_FIXEDSIZE | The band cannot be sized. With this style, the sizing grip is not displayed on the band.
RBBS_GRIPPERALWAYS | The band will always have sizing grip, even if it is the only band in the rebar.
RBBS_HIDDEN | The band will not be visible.
RBBS_NOVERT | The band is not displayed when the rebar control uses the CCS_VERT style.
RBBS_VARIABLEHEIGHT | The band can be resized by the rebar control. The cyIntegral and cyMaxChild members affect how the rebar will resize the band.

cxRestored
Restored width of the band, in pixels. The restored width is the width of the band after the user has dragged it. If the user has never dragged it, it is the initial size of the band. This member corresponds to the cx member of the REBARBANDINFO structure, and is filled in by the CommandBands_GetRestoreInformation function.
fMaximized
Indicates whether the band is maximized. Only one band in a row can be maximized at a time. This member corresponds to the fStyle member of the REBARBANDINFO structure, and is filled in by the CommandBands_GetRestoreInformation function.

See Also

CommandBands_GetRestoreInformation, REBARBANDINFO


COMPOSITIONFORM

This structure contains position information for a composition window.

At a Glance

Header file: | Wceemul.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

typedef _tagCOMPOSITIONFORM {
 DWORD dwStyle;
 POINT ptCurrentPos;
 RECT rcArea;
} COMPOSITIONFORM;

Members

dwStyle
Specifies the position style. It must be the following values:
Value
Description
CFS_DEFAULT Moves the composition window to the default position. The input method editor (IME) window can display the composition window outside the client area, such as in a floating window.

ptCurrentPos
Coordinates of the upper-left corner of the composition window.
rcArea
Coordinates of the upper-left and lower-right corners of the composition window.


DEVMODE

This structure contains information about a printer environment and device initialization.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct_devicemode {
BCHAR dmDeviceName[CCHDEVICENAME];
WORD dmSpecVersion;
WORD dmDriverVersion;
WORD dmSize;
WORD dmDriverExtra;
DWORD dmFields;
short dmOrientation;
short dmPaperSize;
short dmPaperLength;
short dmPaperWidth;
short dmScale;
short dmCopies;
short dmDefaultSource;
short dmPrintQuality;
short dmColor;
short dmDuplex;
short dmYResolution;
short dmTTOption;
short dmCollate;
BCHAR dmFormName[CCHFORMNAME];
WORD dmLogPixels;
DWORD dmBitsPerPel;
DWORD dmPelsWidth;
DWORD dmPelsHeight;
DWORD dmDisplayFlags;
DWORD dmDisplayFrequency;
DWORD dmICMMethod;
DWORD dmICMIntent;
DWORD dmMediaType;
 DWORD dmDitherType;
 DWORD dmICCManufacturer;
 DWORD dmICCModel;
 DWORD dmPanningWidth;
 DWORD dmPanningHeight;
} DEVMODE;

Members

dmDeviceName
Unsupported; set to zero.
dmSpecVersion
Specifies the version number of the initialization data specification on which the structure is based. Must be initialized to SPEC_VERSION.
dmDriverVersion
Unsupported; set to zero.
dmSize
Specifies the size, in bytes, of the DEVMODE structure, not including any private driver-specific data that might follow the structure’s public members. Set this member to sizeof(DEVMODE) to indicate the version of the DEVMODE structure being used.
dmDriverExtra
Unsupported; set to zero.
dmFields
Unsupported; set to zero.
dmOrientation
For printer devices only, specifies the orientation of the paper. It is either DMORIENT_PORTRAIT (1) or DMORIENT_LANDSCAPE (2).
dmPaperSize
For printer devices only, specifies the size of the paper to print on. This member is one of the following predefined values:
Value
Description
DMPAPER_LETTER | Letter, 8 1/2- by 11-inches
DMPAPER_A4 | A4 Sheet, 210- by 297-millimeters

dmPaperLength
dmPaperWidth
Unsupported; set to zero.
dmScale
Unsupported; set to zero.
dmCopies
Unsupported; set to zero.
dmDefaultSource
Unsupported; set to zero.
dmPrintQuality
Specifies the printer resolution. The following are predefined device-independent values:
  • DMRES_DRAFT
  • DMRES_HIGH
dmColor
Switches between color and monochrome on color printers. The following are possible values:
  • DMCOLOR_COLOR
  • DMCOLOR_MONOCHROME
dmDuplex
Unsupported; set to zero.
dmYResolution
Unsupported; set to zero.
dmTTOption
Unsupported; set to zero.
dmCollate
Unsupported; set to zero.
dmFormName
Unsupported; set to zero.
dmLogPixels
Unsupported; set to zero.
DmBitsPerPel
dmPelsWidth
dmPelsHeight
Unsupported; set to zero.
DmDisplayFlags
dmDisplayFrequency
Unsupported; set to zero.
DmICMMethod
dmICMIntent
Unsupported; set to zero.
DmMediaType
dmDitherType
Unsupported; set to zero.
DmPanningWidth
dmPanningHeight
Unsupported; set to zero.

Remarks

A device driver’s private data follows the public portion of the DEVMODE structure. The size of the public data can vary for different versions of the structure. The dmSize member specifies the number of bytes of public data, and the dmDriverExtra member specifies the number of bytes of private data.

All unsupported members should be initialized to zero.

See Also

CreateDC


DIBSECTION

This structure contains information about a device-independent bitmap (DIB).

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagDIBSECTION {
BITMAP dsBm;
BITMAPINFOHEADER dsBmih;
DWORD dsBitfields[3];
HANDLE dshSection;
DWORD dsOffset;
} DIBSECTION;

Members

dsBm
Specifies a BITMAP data structure that contains information about the device-independent bitmap: its type, dimensions, color capacities, and a pointer to its bit values.
dsBmih
Specifies a bitmap information header structure that contains information about the color format of the DIB. Use the BITMAPINFOHEADER structure.
dsBitfields
Specifies three DWORD color masks for the device-independent bitmap. This member is only valid when the BitCount member of the BITMAP INFORMATION HEADER structure has a value greater than 8. Each color mask indicates the bits within a DWORD used to encode one of the three color channels (red, green, and blue).
dshSection
Contains a handle to the file mapping object that the CreateDIBSection function used to create the device-independent bitmap. If CreateDIBSection was called with a NULL value for its hSection parameter, causing the system to allocate memory for the bitmap, the dshSection member will be NULL.
dsOffset
Specifies the offset to the bitmap’s bit values within the file mapping object referenced by dshSection. If dshSection is NULL, the dsOffset value has no meaning.

See Also

CreateDIBSection , GetObject


DLGITEMTEMPLATEEX

This structure is not defined in any standard header file. The structure definition is provided here to explain the format of an extended template for a dialog box.

For each control in a dialog box, an extended dialog box template has a block of data that uses the DLGITEMTEMPLATEEX format to describe the control. For a description of the format of an extended dialog box template, see DLGTEMPLATEEX.

Syntax

typedef struct {
DWORD helpID;
DWORD exStyle;
DWORD style;
short x;
short y;
short cx;
short cy;
WORD id;
sz_Or_Ord windowClass;
sz_Or_Ord title;
WORD extraCount;
} DLGITEMTEMPLATEEX;

Members

helpID
Specifies the help context identifier for the control.
dwExtendedStyle
Specifies extended styles for a window. This member is not used to create controls in dialog boxes, but applications that use dialog box templates can use it to create other types of windows.
style
Specifies the style of the control. This member can be a combination of window style values (such as WS_BORDER) and one or more of the control style values (such as BS_PUSHBUTTON and ES_LEFT).
x
Specifies the x-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box's client area.
y
Specifies the y-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is relative to the upper-left corner of the dialog box client area.
cx
Specifies the control width, in dialog box units
cy
Specifies the control height, in dialog box units
id
Specifies the control identifier
windowClass
Specifies a variable-length array of 16-bit elements that identifies the window class of the control. If the first element of this array is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.

If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system class. The ordinal can be one of the atom values shown in the following table.
Value
Description
0x0080 | Button
0x0081 | Edit
0x0082 | Static
0x0083 | List box
0x0084 | Scroll bar
0x0085 | Combo box

title
Specifies a variable-length array of 16-bit elements that contains the initial text or resource identifier of the control. If the first element of this array is 0xFFFF, the array has one additional element that specifies an ordinal value that identifies a resource, such as an icon, in an executable file. You can use a resource identifier for controls, such as static icon controls, that load and display an icon or other resource rather than text.

If the first element is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the initial text.

extraCount
Specifies the number of bytes of creation data that follow this member. If this value is greater than zero, the creation data begins at the next WORD boundary. This creation data can be of any size and format. The control's window procedure must be able to interpret the data. When the system creates the control, it passes a pointer to this data in the lParam parameter of the WM_CREATE message that it sends to the control.

Remarks

An extended template for a dialog box consists of a DLGTEMPLATEEX header followed by a DLGITEMTEMPLATEEX structure for each control in the dialog box.

Each DLGITEMTEMPLATEEX structure must be aligned on a DWORD boundary. The variable-length windowClass and title arrays must be aligned on WORD boundaries. The creation data array, if any, must be aligned on a WORD boundary.

If you specify character strings in the windowClass and title arrays, you must use Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DialogBoxIndirectParam, DLGITEMTEMPLATE, DLGTEMPLATE, DLGTEMPLATEEX, MapDialogRect, MultiByteToWideChar


DLGTEMPLATE

This structure defines the dimensions and style of a dialog box. This structure, always the first in a dialog box template, also specifies the number of controls in the dialog box and therefore specifies the number of subsequent DLGITEMTEMPLATE structures in the template.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct { // dltt
DWORD style;
DWORD dwExtendedStyle;
WORD cdit;
short x;
short y;
short cx;
short cy;
} DLGTEMPLATE;

Members

style
Specifies the style of the dialog box. It can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and one or more of the following dialog box style values:
Value
Description
DS_ABSALIGN | Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, the system assumes they are client coordinates.
DS_CENTER | Centers the dialog box in the working area; that is, the area not obscured by the tray
DS_CENTERMOUSE | Centers the mouse cursor in the dialog box
DS_CONTEXTHELP | Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog box procedure. The help application displays a pop-up window that typically contains help for the control.
Note that DS_CONTEXTHELP is only a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
DS_LOCALEDIT | Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application data segment. Otherwise, edit controls allocate storage from a global memory object.
DS_MODALFRAME | Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and window menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOFAILCREATE | Creates the dialog box even if errors occur—for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG | Suppresses WM_ENTERIDLE messages that the system would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_SETFONT | Indicates that the header of the dialog box template contains additional data specifying the font to use for text in the client area and controls of the dialog box. The font data begins on the WORD boundary that follows the title array. It specifies a 16-bit point size value and a Unicode font name string. If possible, the system creates a font according to the specified values. Then the system passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message.
If this style is not specified, the dialog box template does not include the font data.
You cannot set the font inside dialog boxes in Windows CE versions 1.0 and 1.01, but you can in Windows CE versions 2.0 and later.
DS_SETFOREGROUND | Causes the system to use the SetForegroundWindow function to bring the dialog box to the foreground.

dwExtendedStyle
Specifies extended styles for a window. This member is not used to create dialog boxes, but applications that use dialog box templates can use it to create other types of windows.
cdit
Specifies the number of items in the dialog box
x
Specifies the x-coordinate, in dialog box units, of the upper-left corner of the dialog box
y
Specifies the y-coordinate, in dialog box units, of the upper-left corner of the dialog box
cx
Specifies the width, in dialog box units, of the dialog box
cy
Specifies the height, in dialog box units, of the dialog box

Remarks

To get default positioning, use the DS_CENTER style.

In a standard template for a dialog box, the DLGTEMPLATE structure is always immediately followed by three variable-length arrays that specify the menu, class, and title for the dialog box. When the DS_SETFONT style is given, these arrays are also followed by a 16-bit value specifying point size and another variable-length array specifying a typeface name. Each array consists of one or more 16-bit elements. The menu, class, title, and font arrays must be aligned on WORD boundaries.

Immediately following the DLGTEMPLATE structure is a menu array that identifies a menu resource for the dialog box. If the first element of this array is 0x0000, the dialog box has no menu and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a menu resource in an executable file. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a menu resource in an executable file.

Following the menu array is a class array that identifies the window class of the control. If the first element of the array is 0x0000, the system uses the predefined dialog box class for the dialog box and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system window class. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.

Following the class array is a title array that specifies a null-terminated Unicode string that contains the title of the dialog box. If the first element of this array is 0x0000, the dialog box has no title and the array has no other elements.

The 16-bit point size value and the typeface array follow the title array, but only if the style member specifies the DS_SETFONT style. The point size value specifies the point size of the font to use for the text in the dialog box and its controls. The typeface array is a null-terminated Unicode string specifying the name of the typeface for the font. When these values are given, the system creates a font having the given size and typeface (if possible) and sends a WM_SETFONT message to the dialog box procedure and the control window procedures as it creates the dialog box and controls.

Following the DLGTEMPLATE header in a standard dialog box template are one or more DLGITEMTEMPLATE structures that define the dimensions and style of the controls in the dialog box. The cdit member specifies the number of DLGITEMTEMPLATE structures in the template. These DLGITEMTEMPLATE structures must be aligned on DWORD boundaries.

If you specify character strings in the menu, class, title, or typeface arrays, you must use Unicode strings. To create code that works on both Windows 95/98 and Windows NT, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam


DLGTEMPLATEEX

This structure is not defined in any standard header file. The structure definition is provided here to explain the format of an extended template for a dialog box.

An extended dialog box template begins with a DLGTEMPLATEEX header that describes the dialog box and specifies the number of controls in the dialog box. For each control in a dialog box, an extended dialog box template has a block of data that uses the DLGITEMTEMPLATEEX format to describe the control.

Syntax

typedef struct {
WORD dlgVer;
WORD signature;
DWORD helpID;
DWORD exStyle;
DWORD style;
WORD cDlgItems;
short x;
short y;
short cx;
short cy;
sz_Or_Ord menu;
sz_Or_Ord windowClass;
WCHAR title[titleLen];
short pointsize;
short weight;
short bItalic;
WCHAR font[fontLen];
} DLGTEMPLATEEX;

Members

dlgVer
Specifies the version number of the extended dialog box template. This member must specify 1.
signature
Indicates whether a template is an extended dialog box template. A value of 0xFFFF indicates an extended dialog box template. In this case, the dlgVer member specifies the template version number. If signature is any value other than 0xFFFF, this is a standard template that uses the DLGTEMPLATE and DLGITEMTEMPLATE structures.
helpID
Specifies the help context identifier for the dialog box window. When the system sends a WM_HELP message, it passes this value in the dwContextId member of the HELPINFO structure.
exStyle
Specifies extended styles for a window. This member is not used to create dialog boxes, but applications that use dialog box templates can use it to create other types of windows.
style
Specifies the style of the dialog box. This member can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and one or more of the dialog box style values shown in the following table.
Value
Description
DS_3DLOOK | Gives the dialog box a nonbold font and draws three-dimensional borders around control windows in the dialog box.
DS_ABSALIGN | Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, the system recognizes them as client coordinates.
DS_CENTER | Centers the dialog box in the working area; that is, the area not obscured by the tray
DS_CENTERMOUSE | Centers the mouse cursor in the dialog box
DS_CONTEXTHELP | Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog procedure, which should call the WinHelp function using the HELP_WM_HELP command. The help application displays a pop-up window that typically contains help for the control.
Note that DS_CONTEXTHELP is only a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. You cannot use the WS_EX_CONTEXTHELP style with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
DS_CONTROL | Creates a dialog box that works well as a child window of another dialog box, much like a page in a property sheet. This style allows the user to tab among the control windows of a child dialog box, use its accelerator keys, and so on.
DS_MODALFRAME | Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and window menu by specifying the WS_CAPTION and WS_SYSMENU styles
DS_NOFAILCREATE | Creates the dialog box even if errors occur—for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG | Suppresses WM_ENTERIDLE messages that the system would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_SETFONT | Indicates that the DLGTEMPLATEEX header of the extended dialog box template contains four additional members (pointsize, weight, bItalic, and font) that describe the font to use for the text in the client area and controls of the dialog box. If possible, the system creates a font according to the values specified in these members. Then the system passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message.
If this style is not specified, the extended dialog box template does not include the pointsize, weight, bItalic, and font members.
DS_SETFOREGROUND | Causes the system to use the SetForegroundWindow function to bring the dialog box to the foreground

cDlgItems
Specifies the number of controls in the dialog box
x
Specifies the x-coordinate, in dialog box units, of the upper-left corner of the dialog box
y
Specifies the y-coordinate, in dialog box units, of the upper-left corner of the dialog box
cx
Specifies the width, in dialog box units, of the dialog box
cy
Specifies the height, in dialog box units, of the dialog box
menu
Specifies a variable-length array of 16-bit elements that identifies a menu resource for the dialog box. If the first element of this array is 0x0000, the dialog box has no menu and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a menu resource in an executable file. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a menu resource in an executable file.
windowClass
Specifies a variable-length array of 16-bit elements that identifies the window class of the dialog box. If the first element of the array is 0x0000, the system uses the predefined dialog box class for the dialog box and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system window class. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.
title
Specifies a null-terminated Unicode string that contains the title of the dialog box. If the first element of this array is 0x0000, the dialog box has no title and the array has no other elements.
pointsize
Specifies the point size of the font to use for the text in the dialog box and its controls. The pointsize, weight, bItalic, and font members are present in an extended dialog box template only if the style member specifies the DS_SETFONT style.
weight
Specifies the weight of the font in the range 0 through 1000. This can be any of the values listed for the lfWeight member of the LOGFONT structure. This member is present only if the style member specifies DS_SETFONT.
bItalic
Indicates whether the font is italic. If this value is TRUE, the font is italic. This member is present only if the style member specifies DS_SETFONT.
font
Specifies a null-terminated Unicode string that contains the name of the typeface for the font. This member is present only if the style member specifies DS_SETFONT.

Remarks

You can use an extended dialog box template instead of a standard dialog box template in the CreateDialogIndirectParam and DialogBoxIndirectParam functions and the CreateDialogIndirect and DialogBoxIndirect macros. A standard dialog box template uses the DLGTEMPLATE and DLGITEMTEMPLATE structures.

Following the DLGTEMPLATEEX header in an extended dialog box template is one or more DLGITEMTEMPLATEEX structures that describe the controls of the dialog box. The cDlgItems member specifies the number of DLGITEMTEMPLATEEX structures in the template.

Each DLGITEMTEMPLATEEX structure in the template must be aligned on a DWORD boundary. If the style member specifies the DS_SETFONT style, the first DLGITEMTEMPLATEEX structure begins on the first DWORD boundary after the font string. If DS_SETFONT is not specified, the first structure begins on the first DWORD boundary after the title string.

The menu, windowClass, title, and font arrays must be aligned on WORD boundaries.

If you specify character strings in the menu, windowClass, title, and font arrays, you must use Unicode strings. To create code that works on both Windows 95/98 and Windows NT, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, DialogBoxIndirectParam, DLGITEMTEMPLATE, DLGITEMTEMPLATEEX, DLGTEMPLATE, MapDialogRect, MultiByteToWideChar, WM_SETFONT


DOCINFO

This structure contains the information necessary for printing documents.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
int cbSize;
LPCTSTR lpszDocName;
LPCTSTR lpszOutput;
LPCTSTR lpszDatatype;
DWORD fwType;
} DOCINFO; .

Members

cbSize
Specifies the structure size, in bytes.
lpszDocName
Long pointer to a null-terminated string that specifies the name of the document.
lpszOutput
Long pointer to a null-terminated string that specifies the name of an output file. If this pointer is NULL, the output will be sent to the device identified by the device context handle that was passed to the StartDoc function.
lpszDatatype
Unsupported; set to zero.
fwType
Unsupported; set to zero.

See Also

StartDoc


ENUMLOGFONT

This structure defines a font’s attributes, full name, and style.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagENUMLOGFONT {
 LOGFONT elfLogFont;
TCHAR elfFullName[LF_FULLFACESIZE];
TCHAR elfStyle[LF_FACESIZE];
} ENUMLOGFONT;

Members

elfLogFont
Specifies a LOGFONT structure that defines the attributes of a font.
elfFullName
Specifies a unique name for the font. For example, “ABCD Font Company TrueType Bold Italic Sans Serif”.
elfStyle
Specifies the style of the font, for example, “Bold Italic”.

See Also

EnumFontFamProc, LOGFONT


HD_HITTESTINFO

This structure contains information about a hit test, and is superseded by the HD_HITTESTINFO structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _HD_HITTESTINFO {
POINT pt;
UINT flags;
int iItem;
} HD_HITTESTINFO;

Members

pt
POINT structure that contains the point to be hit test, in client coordinates.
flags
Receives information about the results of a hit test. It can be one or more of the following values:
Value
Description
HHT_NOWHERE | The point is inside the header control’s bounding rectangle but is not over a header item.
HHT_ONDIVIDER | The point is on the divider between two header items.
HHT_ONDIVOPEN | The point is on the divider of an item that has a width of zero. Dragging the divider reveals the item instead of resizing the item to the left of the divider.
HHT_ONHEADER | The point is inside the header control’s bounding rectangle.
HHT_TOLEFT | The point is to the left of the header control’s bounding rectangle.
HHT_TORIGHT | The point is to the right of the header control’s bounding rectangle.

Two of these values can be combined, such as when the position is above and to the left of the client area.

iItem
If the hit test is successful, this member contains the index of the item at the hit test point.

See Also

HDM_HITTEST


HD_ITEM

This structure contains information about an item in a header control. This structure is superseded by the HDITEM structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _HD_ITEM { hdi
UINT mask;
int cxy;
LPSTR pszText;
HBITMAP hbm;
int cchTextMax;
int fmt;
LPARAM lParam;
} HD_ITEM;

Members

mask
Indicates which other structure members contain valid data or must be filled in. It can be a combination of the following values:
Value
Description
HDI_BITMAP | The hbm member is valid.
HDI_FORMAT | The fmt member is valid.
HDI_HEIGHT | The cxy member is valid and specifies the item’s height.
HDI_IMAGE | Version 4.70. The iImage member is valid and specifies the image to be displayed with the item.
HDI_LPARAM | The lParam member is valid.
HDI_ORDER | Version 4.70. The iOrder member is valid and specifies the item’s order value.
HDI_TEXT | The pszText and cchTextMax members are valid.
HDI_WIDTH | The cxy member is valid and specifies the item’s width.

cxy
Width or height of the item.
pszText
Pointer to a null-terminated item string. If this member is set to LPSTR_TEXTCALLBACK, the control requests text information for this item by sending an HDN_GETDISPINFO notification message.
hbm
Handle to the item bitmap.
cchTextMax
Length of the item string, in characters.
fmt
Set of bit flags that specify the item’s format.

This member can include one of the following text justification or right-to-left reading order bit flags:
Value
Description
HDF_CENTER | The item’s contents are centered.
HDF_LEFT | The item’s contents are left-aligned.
HDF_RIGHT | The item’s contents are right-aligned.
HDF_RTLREADING | Text is displayed using right-to-left reading order for Hebrew or Arabic systems.

The flag from the preceding list is combined with one of the following values:
Value
Description
HDF_BITMAP | The item displays a bitmap.
HDF_BITMAP_ON_RIGHT | Version 4.70. The bitmap appears to the right of text. This does not affect an image from an image list assigned to the header item.
HDF_IMAGE | Version 4.70. The item displays an image from the image list.
HDF_OWNERDRAW | The header control’s owner draws the item.
HDF_STRING | The item displays a string.

Additionally, the following flag can be combined with any of the preceding flags:
Value
Description
HDF_IMAGE The item displays an image from an image list.

You can use the HDF_JUSTIFYMASK mask to isolate the text justification portion of the fmt member.

lParam
Application-defined item data.
iImage
Version 4.70. Zero-based index of an image within the image list. The specified image will be displayed in the header item in addition to any image specified in the hbm member. If iImage is set to I_IMAGECALLBACK, the control requests text information for this item by using an HDN_GETDISPINFO notification message.
iOrder
Version 4.70. Order in which the item appears within the header control, from left to right. That is, the value for the far left item is 0. The value for the next item to the right is 1, and so on.

Remarks

The header control can display text, an image, and a bitmap for an item all at the same time. The alignment flags determine the order in which they appear. With HDF_LEFT or HDF_CENTER, the order is image, text, and then bitmap. With HDF_RIGHT the order is bitmap, image, and then text.

See Also

HDM_GETITEM, HDM_INSERTITEM


HD_LAYOUT

This structure contains information used to set the size and position of a header control, and is superseded by the HDLAYOUT structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _HD_LAYOUT {
RECT FAR *prc;
WINDOWPOS FAR *pwpos;
} HD_LAYOUT;

Members

prc
Pointer to a RECT structure that contains the coordinates of a rectangle that the header control will occupy.
pwpos
Pointer to a WINDOWPOS structure that receives information about the appropriate size and position of the header control.

See Also

HDM_LAYOUT, RECT, WINDOWPOS


HD_NOTIFY

This structure contains information used to process notification messages from a header control. This structure is superseded by the NMHEADER structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _HD_NOTIFY {
NMHDR hdr;
int iItem;
int iButton;
HD_ITEM FAR *pitem;
} HD_NOTIFY;

Members

hdr
NMHDR structure that contains information about the notification message.
iItem
Zero-based index of the header item that is the focus of the notification message.
iButton
Index of the mouse button used to generate the notification message. It is one of the following values:
Value
Description
0 | Left button
1 | Right button
2 | Middle button

pitem
Pointer to an HD_ITEM structure that contains information specific to the item indicated by iItem.

See Also

HD_ITEM, NMHDR, WM_NOTIFY


HDHITTESTINFO

This structure contains information about a hit test. This structure is used with the HDM_HITTEST message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _HD_HITTESTINFO {
POINT pt;
UINT flags;
int iItem;
} HD_HITTESTINFO;

Members

pt
Points to test, in client coordinates.
flags
Receives information about the results of a hit test. It can be one or more of the following values.
Value
Description
HHT_NOWHERE | The point is inside the header control’s bounding rectangle but is not over a header item.
HHT_ONDIVIDER | The point is on the divider between two header items.
HHT_ONDIVOPEN | The point is on the divider of an item that has a width of zero. Dragging the divider reveals the item instead of resizing the item to the left of the divider.
HHT_ONHEADER | The point is inside the header control’s bounding rectangle.
HHT_TOLEFT | The point is to the left of the header control’s bounding rectangle.
HHT_TORIGHT | The point is to the right of the header control’s bounding rectangle.

Two of these values can be combined, such as when the position is above and to the left of the client area.

iItem
Receives the index of item at point, if any.


HDITEM

This structure contains information about an item in a header control. This structure has been updated to support header item images and order values.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _HDITEM {
 UINT mask;
int cxy;
LPTSTR pszText;
HBITMAP hbm;
int cchTextMax;
int fmt;
LPARAM lParam;
int iImage;
 int iOrder;
} HDITEM;

Members

mask
Specifies which other structure members contain valid data or must be filled in. It can be a combination of the following values:
Value
Description
HDI_BITMAP | The hbm member is valid.
HDI_FORMAT | The fmt member is valid.
HDI_HEIGHT | The cxy member is valid and specifies the item’s height.
HDI_IMAGE | The iImage member is valid and specifies the image to be displayed with the item.
HDI_LPARAM | The lParam member is valid.
HDI_ORDER | The iOrder member is valid and specifies the item’s order value.
HDI_TEXT | The pszText and cchTextMax members are valid.
HDI_WIDTH | The cxy member is valid and specifies the item’s width.

cxy
Width or height of the item.
pszText
Pointer to a null-terminated item string. If this member is set to LPSTR_TEXTCALLBACK, the control will request text information for this item by using HDN_GETDISPINFO notification messages.
hbm
Handle to the item bitmap.
cchTextMax
Length of the item string, in characters.
fmt
Set of bit flags that specify the item’s format.

This member can include one of the following text justification or right-to-left reading order bit flags.
Value
Description
HDF_CENTER | The item’s contents are centered.
HDF_LEFT | The item’s contents are left-aligned.
HDF_RIGHT | The item’s contents are right-aligned.
HDF_RTLREADING | Windows 95 only: Text is displayed using right-to-left reading order for Hebrew or Arabic systems.

The preceding flag is combined with one of the following flags.
Value
Description
HDF_BITMAP | The item displays a bitmap.
HDF_BITMAP_ON_RIGHT | The bitmap appears to the right of text. This does not affect an image from an image list assigned to the header item.
HDF_OWNERDRAW | The header control’s owner draws the item.
HDF_STRING | The item displays a string.

Additionally, the following flag can be combined with any of the preceding flags.
Value
Description
HDF_IMAGE The item displays an image from an image list.
You can use the HDF_JUSTIFYMASK mask to isolate the text justification portion of the fmt member.

lParam
Application-defined item data.
iImage
Zero-based index of an image within the image list. The specified image will be displayed in the header item, in addition to any image specified in the hbm member. If iImage is set to I_IMAGECALLBACK, the control requests text information for this item by using HDN_GETDISPINFO notification messages.
iOrder
Order in which the item appears within the header control, from left to right. That is, the value for the far left item is 0. The value for the next item to the right is 1, and so on.

Remarks

The header control can display text, an image and a bitmap for an item all at the same time. The alignment flags determine the order in which they appear. With HDF_LEFT or HDF_CENTER, the order is image, text, and then bitmap. With HDF_RIGHT the order is bitmap, image and then text.


HDLAYOUT

This structure contains information used to set the size and position of a header control. This structure is used with the HDM_LAYOUT message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _HD_LAYOUT { // hdl
RECT FAR* prc;
WINDOWPOS FAR* pwpos;
} HD_LAYOUT;

Members

prc
Pointer to a RECT structure that contains the coordinates of a rectangle that the header control will occupy.
pwpos
Pointer to a WINDOWPOS structure that receives information about the appropriate size and position of the header control.


ICONINFO

This structure contains information about an icon.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _ICONINFO {
BOOL fIcon;
DWORD xHotspot;
DWORD yHotspot;
HBITMAP hbmMask;
HBITMAP hbmColor;
} ICONINFO;

Members

fIcon
Boolean that specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; a value of FALSE specifies a cursor.
xHotspot
Specifies the x-coordinate of a cursor’s hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored.
yHotspot
Specifies the y-coordinate of the cursor’s hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored.
hbmMask
Specifies the icon bitmask bitmap. If this structure defines a black and white icon, this bitmask is formatted so that the upper half is the icon AND bitmask and the lower half is the icon XOR bitmask. Under this condition, the height should be an even multiple of two. If this structure defines a color icon, this mask only defines the AND bitmask of the icon.
hbmColor
Handle to the icon color bitmap. This member can be optional if this structure defines a black and white icon. The AND bitmask of hbmMask is applied with the SRCAND flag to the destination; subsequently, the color bitmap is applied (using XOR) to the destination by using the SRCINVERT flag.

Remarks

If you are not using the Iconcurs component, the fIcon member must be set to TRUE. The Windows CE Icon component does not support cursors. If you need mouse cursor support in your application, use the Windows CE Iconcurs component rather than the Windows CE Icon component.

See Also

CreateIconIndirect


IMAGEINFO

This structure contains information about an image in an image list. This structure is used with the ImageList_GetImageInfo function.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _IMAGEINFO {
 HBITMAP hbmImage;
 HBITMAP hbmMask;
 int Unused1;
 int Unused2;
 RECT rcImage;
} IMAGEINFO;

Members

hbmImage
Handle to the bitmap that contains the images.
hbmMask
Handle to a monochrome bitmap that contains the masks for the images. If the image list does not contain a mask, this member is NULL.
Unused1
Not used; set to zero.
Unused2
Not used; set to zero.
rcImage
Bounding rectangle of the specified image within the bitmap specified by hbmImage.

See Also

ImageList_GetImageInfo


IMAGELISTDRAWPARAMS

This structure contains information about an image list draw operation and is used with the ImageList_DrawIndirect function.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _IMAGELISTDRAWPARAMS {
 DWORD cbSize;
 HIMAGELIST himl;
 int i;
 HDC hdcDst;
 int x;
 int y;
 int cx;
 int cy;
 int xBitmap;
 int yBitmap;
 COLORREF rgbBk;
 COLORREF rgbFg;
 UINT fStyle;
 DWORD dwRop;
} IMAGELISTDRAWPARAMS, FAR * LPIMAGELISTDRAWPARAMS;

Members

cbSize
Size of this structure, in bytes.
himl
Handle to the image list that contains the image to be drawn.
i
Zero-based index of the image to be drawn.
hdcDst
Handle to the destination device context.
x and y
Specify the coordinates that the image will be drawn at.
cx and cy
Specify the number of pixels to be drawn, relative to the upper-left corner of the drawing operation as specified by xBitmap and yBitmap. If cx and cy are zero, ImageList_DrawIndirect draws the entire valid section. The function does not ensure that the parameters are valid.
xBitmap and yBitmap
Specify the coordinates that specify the upper-left corner of the drawing operation with respect to the image itself. Pixels of the image that are to the left of xBitmap and above yBitmap are not drawn.
rgbBk
Image background color. It can be an application-defined RGB value or one of the following values:
Value
Description
CLR_DEFAULT | Default background color. The image is drawn using the image list background color.
CLR_NONE | No background color. The image is drawn transparently.

This parameter is used only if the image list identified by himl was created with the ILC_MASK value.

rgbFg
Image foreground color. It is an application-defined RGB value or one of the following values:
Value
Description
CLR_DEFAULT | Default foreground color. The image is drawn using the system highlight color as the foreground color.
CLR_NONE | No blend color. The image is blended with the color of the destination device context.

This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 flag.

fStyle
Flag that specifies the drawing style and, optionally, the overlay image. It can be a combination of one or more of the following values:
Value
Description
ILD_BLEND25 | Draws the image, blending 25 percent with the blend color specified by rgbFg. This value has no effect if the image list does not contain a mask.
ILD_FOCUS | Same as ILD_BLEND25.
ILD_BLEND50 | Draws the image, blending 50 percent with the blend color specified by rgbFg. This value has no effect if the image list does not contain a mask.
ILD_SELECTED | Same as ILD_BLEND50.
ILD_BLEND | Same as ILD_BLEND50.
ILD_MASK | Draws the mask.
ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_ROP | Draws the image using the raster-operation code specified by the dwRop member.
ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.

dwRop
Specifies a raster-operation code. These codes define how the color data for the source rectangle will be combined with the color data for the destination rectangle to achieve the final color. This member is ignored if the fStyle member does not include the ILD_ROP flag.

Some common raster operation codes are listed below:
Value
Description
BLACKNESS | Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT | Inverts the destination rectangle.
MERGECOPY | Merges the source rectangle colors with the specified pattern by using the Boolean AND operator.
MERGEPAINT | Merges the inverted source rectangle colors with the destination rectangle colors by using the Boolean OR operator.
NOTSRCCOPY | Copies the inverted source rectangle to the destination.
NOTSRCERASE | Combines the source and destination rectangle colors by using the Boolean OR operator. Inverts the resultant color.
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the specified pattern colors with the destination rectangle colors by using the Boolean XOR operator.
PATPAINT | Combines the pattern colors with the inverted source rectangle colors by using the Boolean OR operator. Combines the result with the destination rectangle colors by using the Boolean OR operator.
SRCAND | Combines the source and destination rectangle colors by using the Boolean AND operator.
SRCCOPY | Copies the source rectangle directly to the destination rectangle.
SRCERASE | Combines the destination rectangle’s inverted colors with the source rectangle colors by using the Boolean AND operator.
SRCINVERT | Combines the source and destination rectangle colors by using the Boolean XOR operator.
SRCPAINT | Combines the source and destination rectangle colors by using the Boolean OR operator.
WHITENESS | Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)

Remarks

An overlay image is an image that is drawn on top of the primary image specified in the i member of this structure. To specify an overlay image, logically OR the fStyle member with the INDEXTOOVERLAYMASK macro, passing the one-based index of the overlay image in the macro. This image must have been previously specified as an overlay image using the ImageList_SetOverlayImage API.

To extract the overlay image from the fStyle member, use the logical AND to combine fStyle with the ILD_OVERLAYMASK value.


IMEMENUITEMINFO

This structure contains information about IME menu items.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagIMEMENUITEMINFO {
UINT cbSize;
UINT fType;
UINT fState;
UINT wID;
HBITMAP hbmpChecked;
HBITMAP hbmpUnchecked;
DWORD dwItemData;
WCHAR szString[IMEMENUITEM_STRING_SIZE];
HBITMAP hbmpItem;
} IMEMENUITEMINFO, *PIMEMENUITEMINFO, NEAR *NPIMEMENUITEMINFO, FAR *LPIMEMENUITEMINFO

Members

cbSize
Size of the structure in bytes.
fType
Menu item type. It is one of the following values:
Value
Description
IMFT_RADIOCCHECK | Displays checked menu items using a radio-button mark instead of a check mark if the hbmpChecked member is NULL.
IMFT_SEPARATOR | Specifies that the menu item is a separator. A menu item separator appears as a horizontal dividing line. The hbmpItem and szString members are ignored in this case.
IMFT_SUBMENU | Specifies that the menu item is a submenu.

fState
Menu item state. It can be one or more of the following values.
Value
Description
IMFS_CHECKED | The menu item is checked. For more information, see the description of the hbmpChecked member.
IMFS_DEFAULT | The menu item is the default. A menu can contain only one default menu item, which is displayed in bold.
IMFS_DISABLED | The menu item is disabled but not shaded. It can still be selected.
IMFS_ENABLED | The menu item is enabled. This is the default state.
IMFS_GRAYED | The menu item is disabled and shaded so it cannot be selected.
IMFS_HILITE | The menu item is highlighted.
IMFS_UNCHECKED | The menu item is unchecked. For more information about unchecked menu items, see the description of the hbmpUnchecked member.
IMFS_UNHILITE | The menu item is not highlighted. This is the default state.

wID
Application-defined 16-bit value that identifies the menu item.
hbmpChecked
Handle to the bitmap to display next to the item if it is checked. If this member is NULL, a default bitmap is used. If the IMFT_RADIOCHECK type value is specified, the default bitmap is a bullet. Otherwise, it is a check mark.
hbmpUnchecked
Handle to the bitmap to display next to the item if it is not checked. If this member is NULL, no bitmap is used.
dwItemData
Specifies an application-defined value associated with the menu item.
szString
Null-terminated string that contains the content of the menu item.
hbmpItem
Handle to a bitmap to display.


INITCOMMONCONTROLSEX

This structure carries information used to load common control classes from the dynamic-link library (DLL). This structure is used with the InitCommonControlsEx function.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagINITCOMMONCONTROLSEX {
 DWORD dwSize;
 DWORD dwICC;
} INITCOMMONCONTROLSEX, *LPINITCOMMONCONTROLSEX;

Members

dwSize
Specifies the size of the structure, in bytes.
dwICC
Indicates which common control classes will be loaded from the DLL. It can be a combination of the following values:
Value
Description
ICC_BAR_CLASSES | Loads toolbar, status bar, trackbar and command bar classes.
ICC_COOL_CLASSES | Loads rebar control class.
ICC_DATE_CLASSES | Loads date and time-picker control class.
ICC_LISTVIEW_CLASSES | Loads list view and header control classes.
ICC_PROGRESS_CLASS | Loads progress bar control class.
ICC_TAB_CLASSES | Loads tab control classes.
ICC_TREEVIEW_CLASSES | Loads tree view control classes.
ICC_UPDOWN_CLASS | Loads Up-Down control class.

Remarks

Windows CE does not support the ICC_ANIMATE_CLASS, ICC_HOTKEY_CLASS, ICC_INTERNET_CLASSES, or ICC_USEREX_CLASSES flags in the dwICC member.


INPUTCONTEXT

Syntax

typedef struct tagINPUTCONTEXT{
HWND hWnd;
 BOOL fOpen;
 DWORD fdwClient;
HWND hwndImeInUse;
POINT ptStatusWndPos;
 POINT ptSoftKbdPos;
 DWORD fdwConversion;
 DWORD fdwSentence;
 union{
 LOGFONTA A;
 LOGFONTW W;
 } lfFont;
 COMPOSITIONFORM cfCompForm;
 CANDIDATEFORM cfCandForm[4];
 HIMCC hCompStr;
 HIMCC hCandInfo;
 HIMCC hGuideLine;
 HIMCC hPrivate;
 DWORD dwNumMsgBuf;
 HIMCC hMsgBuf;
 DWORD fdwInit;
 DWORD dwReserve[3]
} INPUTCONTEXT, *PINPUTCONTEXT, NEAR *NPINPUTCONTEXT, FAR *LPINPUTCONTEXT;

Members

hWnd
Handle to the window that uses the input context.
fOpen
Boolean that indicates the present status of the opened or closed IME.
fdwClient
hwndImeInUse
Handle to the input method editor (IME) control window.
ptStatusWndPos
Position of the status window.
ptSoftKbdPos
Position of the soft keyboard.
fdwConversion
Conversion mode used by the IME composition engine.
fdwSentence
Sentence mode used by the IME composition engine.
lfFont
LOGFONT structure used by the IME user interface to draw the composition string.
cfCompForm
COMPOSITIONFORM structure used by the IME user interface to create the composition window.
cfCandForm[4]
CANDIDATEFORM structures used by the IME user interface to create the candidate windows. This IMC supports 4 candidate forms.
hCompStr
Handle to the COMPOSITIONSTR structure. This handle is available when there is the composition string.
hCandInfo
Handle to a memory block that contains the CANDIDATEINFO structure and CANDIDATELIST structures. This handle is available when there are the candidate strings.
hGuideLine
Handle to a memory block that contains the GUIDELINE structure. This handle is available when there is the guideline information.
hPrivate
Handle to a memory block used by IME for its private date area.
dwNumMsgBuf
Specifies the umber of messages stored in hMsgBuf.
hMsgBuf
Handle to the memory block that stores the messages. The format of this memory block is:
[Message1] [wParam1] [lParam1] {[Message2] [wParam2] [lParam2]{...{...{...}}}}

All values are double words.

fdwInit
Initialize flag. When IME initializes the members of the INPUTCONTEXT structure, IME must set the bits of the member indicated by this flag. It is a combination of the following values:
Value
Description
INIT_STATUSWNDPOS | Initializes ptStatusWndPos.
INIT_CONVERSION | Initializes fdwConversion.
INIT_SENTENCE | Initializes fdwSentence.
INIT_LOGFONT | Initializes lfFont.
INIT_COMPFORM | Initializes cfCompForm.
INIT_SOFTKBDPOS | Initializes ptSoftKbdPos.

dwReserve[3]
Reserved; set to zero.


LOGBRUSH

This structure defines the style, color, and pattern of a logical brush.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagLOGBRUSH {
UINT lbStyle;
COLORREF lbColor;
LONG lbHatch;
} LOGBRUSH;

Members

lbStyle
Specifies the brush style. It is one of the following styles:
Value
Description
BS_DIBPATTERN | A pattern brush defined by a device-independent bitmap (DIB) specification. If lbStyle is BS_DIBPATTERN, the lbHatch member contains a handle to a packed DIB.
Windows 95 and Windows 98: Creating brushes from bitmaps or DIBs larger than 8x8 pixels is not supported. If a larger bitmap is given, only a portion of the bitmap is used.
BS_DIBPATTERN8X8 | Same as BS_DIBPATTERN.
BS_DIBPATTERNPT | A pattern brush defined by a device-independent bitmap (DIB) specification. If lbStyle is BS_DIBPATTERNPT, the lbHatch member contains a pointer to a packed DIB.
BS_HATCHED | Hatched brush.
BS_HOLLOW | Hollow brush.
BS_NULL | Same as BS_HOLLOW.
BS_PATTERN | Pattern brush defined by a memory bitmap.
BS_PATTERN8X8 | Same as BS_PATTERN.
BS_SOLID | Solid brush.

lbColor
Specifies the color in which the brush is to be drawn. If lbStyle is the BS_HOLLOW or BS_PATTERN style, lbColor is ignored.

If lbStyle is BS_DIBPATTERN or BS_DIBPATTERNBT, the low-order word of lbColor specifies whether the bmiColors members of the BITMAPINFO structure contain explicit red, green, blue (RGB) values or indices into the currently realized logical palette. The lbColor member must be one of the following values:
Value
Description
DIB_PAL_COLORS | The color table consists of an array of 16-bit indices into the currently realized logical palette.
DIB_RGB_COLORS | The color table contains literal RGB values.

lbHatch
Specifies a hatch style. The meaning depends on the brush style defined by lbStyle.

If lbStyle is BS_DIBPATTERN, the lbHatch member contains a handle to a packed DIB. If lbStyle is BS_DIBPATTERNPT, the lbHatch member contains a pointer to a packed DIB.

If lbStyle is BS_HATCHED, the lbHatch member specifies the orientation of the lines used to create the hatch. It can be one of the following values:
Value
Description
HS_BDIAGONAL | A 45-degree upward, left-to-right hatch
HS_CROSS | Horizontal and vertical cross-hatch
HS_DIAGCROSS | 45-degree crosshatch
HS_FDIAGONAL | A 45-degree downward, left-to-right hatch
HS_HORIZONTAL | Horizontal hatch
HS_VERTICAL | Vertical hatch

If lbStyle is BS_PATTERN, lbHatch is a handle to the bitmap that defines the pattern. The bitmap cannot be a DIB section bitmap, which is created by the CreateDIBSection function.

If lbStyle is BS_SOLID or BS_HOLLOW, lbHatch is ignored.

Remarks

Windows CE version 1.0 supports only the following lbStyle values:

  • BS_NULL
  • BS_SOLID

Windows CE version 2.0 supports the following additional lbStyle values:

  • BS_DIBPATTERNPT
  • BS_PATTERN

Although lbColor controls the foreground color of a hatch brush, the SetBkMode and SetBkColor functions control the background color.

See Also

BITMAPINFO, CreateDIBSection, SetBkColor, SetBkMode


LOGFONT

This structure defines the attributes of a font.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagLOGFONT {
LONG lfHeight;
LONG lfWidth;
LONG lfEscapement;
LONG lfOrientation;
LONG lfWeight;
BYTE lfItalic;
BYTE lfUnderline;
BYTE lfStrikeOut;
BYTE lfCharSet;
BYTE lfOutPrecision;
BYTE lfClipPrecision;
BYTE lfQuality;
BYTE lfPitchAndFamily;
TCHAR lfFaceName[LF_FACESIZE];
} LOGFONT;

Members

lfHeight
Specifies the height, in logical units, of the font’s character cell or character. The character height value (also known as the em height) is the character cell height value minus the internal-leading value. The font mapper interprets the value specified in lfHeight in the following manner:
Value
Description
> 0 | The font mapper transforms this value into device units and matches it against the cell height of the available fonts.
0 | The font mapper uses a default height value when it searches for a match.
< 0 | The font mapper transforms this value into device units and matches its absolute value against the character height of the available fonts.

For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size.

This mapping occurs when the font is used for the first time.

For the MM_TEXT mapping mode, you can use the following formula to specify a height for a font with a given point size:

lfHeight = -MulDiv(PointSize, GetDeviceCaps(hDC, LOGPIXELSY), 72);
lfWidth
Specifies the average width, in logical units, of characters in the font. If lfWidth is zero, the aspect ratio of the device is matched against the digitization aspect ratio of the available fonts to find the closest match, determined by the absolute value of the difference.
lfEscapement
Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the device. The escapement vector is parallel to the base line of a row of text.

Windows NT: When the graphics mode is set to GM_ADVANCED, you can specify the escapement angle of the string independently of the orientation angle of the string’s characters.

When the graphics mode is set to GM_COMPATIBLE, lfEscapement specifies both the escapement and orientation. You should set lfEscapement and lfOrientation to the same value.

Windows 95: The lfEscapement member specifies both the escapement and orientation. You should set lfEscapement and lfOrientation to the same value.

lfOrientation
Specifies the angle, in tenths of degrees, between each character’s base line and the x-axis of the device.
lfWeight
Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used.

The following values are defined:
Value
Weight
FW_DONTCARE | 0
FW_THIN | 100
FW_EXTRALIGHT | 200
FW_ULTRALIGHT | 200
FW_LIGHT | 300
FW_NORMAL | 400
FW_REGULAR | 400
FW_MEDIUM | 500
FW_SEMIBOLD | 600
FW_DEMIBOLD | 600
FW_BOLD | 700
FW_EXTRABOLD | 800
FW_ULTRABOLD | 800
FW_HEAVY | 900
FW_BLACK | 900

lfItalic
Specifies an italic font if set to TRUE.
lfUnderline
Specifies an underlined font if set to TRUE.
lfStrikeOut
Specifies a strikeout font if set to TRUE.
lfCharSet
Specifies the character set. The following values are predefined:
ANSI_CHARSET | BALTIC_CHARSET
CHINESEBIG5_CHARSET | DEFAULT_CHARSET
EASTEUROPE_CHARSET | GB2312_CHARSET
GREEK_CHARSET | HANGUL_CHARSET
MAC_CHARSET | OEM_CHARSET
RUSSIAN_CHARSET | SHIFTJIS_CHARSET
SYMBOL_CHARSET | TURKISH_CHARSET

Korean Windows:
JOHAB_CHARSET

Middle-Eastern Windows:
HEBREW_CHARSET
ARABIC_CHARSET

Thai Windows:
THAI_CHARSET

The OEM_CHARSET value specifies a character set that is operating-system dependent.

You can use the DEFAULT_CHARSET value to allow the name and size of a font to fully describe the logical font. If the specified font name does not exist, a font from any character set can be substituted for the specified font, so you should use DEFAULT_CHARSET sparingly to avoid unexpected results.

Fonts with other character sets may exist in the operating system. If an application uses a font with an unknown character set, it should not attempt to translate or interpret strings that are rendered with that font.

This member is important in the font mapping process. To ensure consistent results, specify a specific character set. If you specify a typeface name in the lfFaceName member, make sure that the lfCharSet value matches the character set of the typeface specified in lfFaceName.

lfOutPrecision
Specifies the output precision. The output precision defines how closely the output must match the requested font’s height, width, character orientation, escapement, pitch, and font type. It can be one of the following values:
Value
Description
OUT_CHARACTER_PRECIS | Not used.
OUT_DEFAULT_PRECIS | Specifies the default font mapper behavior.
OUT_DEVICE_PRECIS | Instructs the font mapper to choose a Device font when the system contains multiple fonts with the same name.
OUT_OUTLINE_PRECIS | Windows NT: This value instructs the font mapper to choose from TrueType and other outline-based fonts.
OUT_RASTER_PRECIS | Instructs the font mapper to choose a raster font when the system contains multiple fonts with the same name.
OUT_STRING_PRECIS | This value is not used by the font mapper, but it is returned when raster fonts are enumerated.
OUT_STROKE_PRECIS | Windows NT: This value is not used by the font mapper, but it is returned when TrueType, other outline-based fonts, and vector fonts are enumerated.
Windows 95: This value is used to map vector fonts, and is returned when TrueType or vector fonts are enumerated.
OUT_TT_ONLY_PRECIS | Instructs the font mapper to choose from only TrueType fonts. If there are no TrueType fonts installed in the system, the font mapper returns to default behavior.
OUT_TT_PRECIS | Instructs the font mapper to choose a TrueType font when the system contains multiple fonts with the same name.

Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, and OUT_TT_PRECIS values to control how the font mapper chooses a font when the operating system contains more than one font with a given name. For example, if an operating system contains a font named Symbol in raster and TrueType form, specifying OUT_TT_PRECIS forces the font mapper to choose the TrueType version. Specifying OUT_TT_ONLY_PRECIS forces the font mapper to choose a TrueType font, even if it must substitute a TrueType font of another name.

lfClipPrecision
Specifies the clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. It can be one or more of the following values:
Value
Description
CLIP_DEFAULT_PRECIS | Specifies default clipping behavior.
CLIP_CHARACTER_PRECIS | Not used.
CLIP_STROKE_PRECIS | Not used by the font mapper, but is returned when raster, vector, or TrueType fonts are enumerated.
Windows NT: For compatibility, this value is always returned when enumerating fonts.
CLIP_MASK | Not used.
CLIP_EMBEDDED | You must specify this flag to use an embedded read-only font.
CLIP_LH_ANGLES | When this value is used, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed.
If not used, device fonts always rotate counterclockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system.
For more information about the orientation of coordinate systems, see the description of the nOrientation parameter
CLIP_TT_ALWAYS | Not used.

lfQuality
Specifies the output quality. The output quality defines how carefully the graphics device interface (GDI) must attempt to match the logical-font attributes to those of an actual physical font. It can be one of the following values:
Value
Description
DEFAULT_QUALITY | Appearance of the font does not matter.
DRAFT_QUALITY | Appearance of the font is less important than when PROOF_QUALITY is used. For GDI raster fonts, scaling is enabled, which means that more font sizes are available, but the quality may be lower. Bold, italic, underline, and strikeout fonts are synthesized if necessary.
PROOF_QUALITY | Character quality of the font is more important than exact matching of the logical-font attributes. For GDI raster fonts, scaling is disabled and the font closest in size is chosen. Although the chosen font size may not be mapped exactly when PROOF_QUALITY is used, the quality of the font is high and there is no distortion of appearance. Bold, italic, underline, and strikeout fonts are synthesized if necessary.

lfPitchAndFamily
Specifies the pitch and family of the font. The two low-order bits specify the pitch of the font and can be one of the following values:
  • DEFAULT_PITCH
  • FIXED_PITCH
  • VARIABLE_PITCH

Bits 4 through 7 of the member specify the font family and can be one of the following values:

  • FF_DECORATIVE
  • FF_DONTCARE
  • FF_MODERN
  • FF_ROMAN
  • FF_SCRIPT
  • FF_SWISS

The proper value can be obtained by using the Boolean OR operator to join one pitch constant with one family constant.

Font families describe the look of a font in a general way. They are intended for specifying fonts when the exact typeface desired is not available. The values for font families are as follows:
Value
Description
FF_DECORATIVE | Novelty fonts, for example, Old English.
FF_DONTCARE | Don’t care or don’t know.
FF_MODERN | Fonts with constant stroke width (monospace), with or without serifs. Monospace fonts are usually modern, for example, Pica, Elite, and CourierNew®.
FF_ROMAN | Fonts with variable stroke width (proportional) and with serifs, for example, MS® Serif.
FF_SCRIPT | Fonts designed to look like handwriting, for example, Script and Cursive.
FF_SWISS | Fonts with variable stroke width (proportional) and without serifs, for example, MS® Sans Serif.

lfFaceName
Specifies a null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 32 characters, including the terminating null character. The EnumFontFamilies function can be used to enumerate the typeface names of all currently available fonts. If lfFaceName is an empty string, GDI uses the first font that matches the other specified attributes.

Remarks

Windows CE version 1.0 does not support the following values for lfClipPrecision:

  • CLIP_MASK
  • CLIP_EMBEDDED
  • CLIP_LH_ANGLES
  • CLIP_TT_ALWAYS

Windows CE version 1.0 does not support the PROOF_QUALITY value for the lfQuality member.

Windows CE version 2.0 ignores the lfClipPrecision and lfQuality members with one important exception. If the raster font engine is installed, a IfClipPrecision value of CLIP_CHARACTER_PRECIS will cause functions that create and select fonts to fail.

See Also

CreateFontIndirect, EnumFontFamilies


LOGPALETTE

This structure defines a logical color palette.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagLOGPALETTE {
WORD palVersion;
WORD palNumEntries;
PALETTEENTRY palPalEntry[1];
} LOGPALETTE;

Members

palVersion
Specifies the version number of the system.
palNumEntries
Specifies the number of entries in the logical color palette.
palPalEntry
Specifies an array of PALETTEENTRY structures that define the color and usage of each entry in the logical palette.

Remarks

The colors in the palette-entry table should appear in order of importance because entries earlier in the logical palette are most likely to be placed in the system palette.

See Also

PALETTEENTRY, CreatePalette


LOGPEN

This structure defines the style, width, and color of a pen. The CreatePenIndirect function uses the LOGPEN structure.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagLOGPEN {
UINT lopnStyle;
POINT lopnWidth;
COLORREF lopnColor;
} LOGPEN;

Members

lopnStyle
Specifies the pen style, which is one of the following values:
Value
Description
PS_SOLID | Pen is solid.
PS_DASH | Pen is dashed.
PS_DOT | Pen is dotted.
PS_DASHDOT | Pen has alternating dashes and dots.
PS_DASHDOTDOT | Pen has dashes and double dots.
PS_NULL | Pen is invisible.
PS_INSIDEFRAME | Pen is solid. When this pen is used in any graphics device interface (GDI) drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.

lopnWidth
Specifies the POINT structure that contains the pen width, in logical units. If the pointer member is NULL, the pen is one pixel wide on raster devices. The y member in the POINT structure for lopnWidth is not used.
lopnColor
Specifies the pen color.

Remarks

Windows CE does not support the following values for the lopnStyle member:

  • PS_DOT
  • PS_DASHDOT
  • PS_DASHDOTDOT
  • PS_INSIDEFRAME

If the width of the pen is greater than 1 and the pen style is PS_INSIDEFRAME, the line is drawn inside the frame of all GDI objects except polygons and polylines. If the pen color does not match an available red, green, blue (RGB) value, the pen is drawn with a logical (dithered) color. If the pen width is less than or equal to 1, the PS_INSIDEFRAME style is identical to the PS_SOLID style.

See Also

CreatePenIndirect, POINT, RGB


LV_COLUMN

This structure contains information about a column in report view. This structure is also used to receive information about a column, and is superseded by the LVCOLUMN structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _LV_COLUMN {
UINT mask;
int fmt;
int cx;
LPSTR pszText;
int cchTextMax;
int iSubItem;
} LV_COLUMN;

Members

mask
Specifies which members contain valid information. It can be zero, or one or more of the following values:
Value
Description
LVCF_FMT | The fmt member is valid.
LVCF_IMAGE | Version 4.70. The iImage member is valid.
LVCF_ORDER | Version 4.70. The iOrder member is valid.
LVCF_SUBITEM | The iSubItem member is valid.
LVCF_TEXT | The pszText member is valid.
LVCF_WIDTH | The cx member is valid.

fmt
Alignment of the column heading and the subitem text in the column. It is one of the following values:
Value
Description
LVCFMT_BITMAP_ON_RIGHT | Version 4.70. The bitmap appears to the right of text. This does not affect an image from an image list assigned to the header item.
LVCFMT_CENTER | Text is centered.
LVCFMT_COL_HAS_IMAGES | Version 4.70. The header item contains an image in the image list.
LVCFMT_IMAGE | Version 4.70. The item displays an image from an image list.
LVCFMT_LEFT | Text is left-aligned.
LVCFMT_RIGHT | Text is right-aligned.

The leftmost column in a list view control must be left-aligned.

cx
Width of the column, in pixels.
pszText
If column information is being set, this member is the pointer to a null-terminated string that contains the column heading text. If the structure is receiving information about a column, this member specifies the address of the buffer that receives the column heading text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information about a column, this member is ignored.
iSubItem
Index of subitem associated with the column.
iImage
Version 4.70. Zero-based index of an image within the image list. The specified image will appear within the column.
iOrder
Version 4.70. Zero-based column offset. Column offset is in left-to-right order. For example, zero indicates the leftmost column.

Remarks

This structure is used with the LVM_GETCOLUMN, LVM_SETCOLUMN, LVM_INSERTCOLUMN, and LVM_DELETECOLUMN messages.


LV_DISPINFO

This structure contains information needed to display an owner-drawn item in a list view control. This structure is identical to the NMLVDISPINFO structure, but was renamed to fit standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tag LV_DISPINFO {
NMHDR hdr;
LV_ITEM item;
} LV_DISPINFO;

Members

hdr
NMHDR structure that contains information about this notification message.
item
LV_ITEM structure that identifies the item or subitem. The structure either contains or receives information about the item. The mask member contains a set of bit flags that specify which item attributes are relevant. It can be one or more of the following bit flags:
Value
Description
LVIF_IMAGE | The iImage member specifies, or is to receive, the index of the item’s icon in the image list.
LVIF_STATE | The state member specifies, or is to receive, the state of the item.
LVIF_TEXT | The pszText member specifies the new item text or the address of a buffer that is to receive the item text.

If the structure is receiving item text, the pszText and cchTextMax members specify the address and size of a buffer. You can either copy text to the buffer or assign the address of a string to the pszText member. In the latter case, you must not change or delete the string until the corresponding item text is deleted or two additional LVN_GETDISPINFO messages have been sent.

If you are handling the LVN_GETDISPINFO message, you can set the LVIF_DI_SETITEM flag in the mask member. This tells the operating system to store the requested list item information and not ask for it again. For list view controls with the LVS_REPORT style, this flag only applies to the first (subitem 0) column’s information. The control will not store information for subitems.


LV_FINDINFO

This structure contains information used to search for a list view item. This structure is identical to the LVFINDINFO structure, but was renamed to fit standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _LV_FINDINFO {
UINT flags;
LPCSTR psz;
LPARAM lParam;
POINT pt;
UINT vkDirection;
} LV_FINDINFO;

Members

flags
Type of search to perform. It can be one or more of the following values:
Value
Description
LVFI_PARAM | Searches based on the lParam member. The lParam member of the matching item’s LV_ITEM structure must match the lParam member of this structure. If this value is specified, all other values are ignored.
LVFI_PARTIAL | Checks to see if the item text begins with the string pointed to by the psz member. This value implies use of LVFI_STRING.
LVFI_STRING | Searches based on the item text. Unless additional values are specified, the item text of the matching item must exactly match the string pointed to by the psz member.
LVFI_WRAP | Continues the search at the beginning if no match is found.
LVFI_NEARESTXY | Finds the item nearest to the position specified in the pt member, in the direction specified by the vkDirection member.

psz
Pointer to a null-terminated string to compare with the item text if flags specifies LVFI_STRING or LVFI_PARTIAL.
lParam
Value to compare with the lParam member of a list view item’s LV_ITEM structure if the flags member specifies LVFI_PARAM.
pt
POINT structure that specifies the starting position to search from. This member is used only if LVFI_NEARESTXY is specified in the flags member.
vkDirection
Direction to search. This member contains the virtual key code of an arrow key that corresponds to the direction to search. This member is used only if LVFI_NEARESTXY is specified in the flags member.

See Also

LVM_FINDITEM, LV_ITEM


LV_HITTESTINFO

This structure contains information about a hit test, and is superseded by the LVHITTESTINFO structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _LV_HITTESTINFO {
POINT pt;
UINT flags;
int iItem;
} LV_HITTESTINFO;

Members

pt
Position to hit test, in client coordinates.
flags
Receives information about the results of a hit test. It can be one or more of the following values:
Value
Description
LVHT_ABOVE | The position is above the control’s client area.
LVHT_BELOW | The position is below the control’s client area.
LVHT_NOWHERE | The position is inside the list view control’s client window, but it is not over a list item.
LVHT_ONITEMICON | The position is over a list view item’s icon.
LVHT_ONITEMLABEL | The position is over a list view item’s text.
LVHT_ONITEMSTATEICON | The position is over the state image of a list view item.
LVHT_TOLEFT | The position is to the left of the list view control’s client area.
LVHT_TORIGHT | The position is to the right of the list view control’s client area.

You can use LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT to determine whether to scroll the contents of a list view control. Two of these values may be combined. For example, if the position is above and to the left of the client area, you could use both LVHT_ABOVE and LVHT_TOLEFT.

You can test for LVHT_ONITEM to determine whether a specified position is over a list view item. This value is a bitwise-OR operation on LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON.

iItem
Receives the index of the matching item. If hit-testing a subitem, this value represents the subitem’s parent item.

See Also

LVM_HITTEST


LV_ITEM

This structure specifies or receives the attributes of a list view item, and is superceded by the LVITEM structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _LV_ITEM {
UINT mask;
int iItem;
int iSubItem;
UINT state;
UINT stateMask;
LPSTR pszText;
int cchTextMax;
int iImage;
LPARAM lParam;
} LV_ITEM;

Members

mask
Specifies which members of this structure contain data to be set or which members are being requested. It can be one or more of the following flags:
Value
Description
LVIF_TEXT | The pszText member is valid or must be filled in.
LVIF_IMAGE | The iImage member is valid or must be filled in.
LVIF_INDENT | The iIndent member is valid or must be filled in.
LVIF_NORECOMPUTE | The control will not generate LVN_GETDISPINFO to retrieve text information if it receives a LVM_GETITEM message. Instead, the pszText member will contain LPSTR_TEXTCALLBACK.
LVIF_PARAM | The lParam member is valid or must be filled in.
LVIF_STATE | The state member is valid or must be filled in.
LVIF_DI_SETITEM | The operating system should store the requested list item information and not ask for it again. This flag is used only with the LVN_GETDISPINFO notification message.

iItem
Zero-based index of the item to which this structure refers.
iSubItem
One-based index of the subitem to which this structure refers, or zero if this structure refers to an item rather than a subitem.
state
Indicates the item’s state, state image, and overlay image. The stateMask member indicates the valid bits of this member.

Bits 0 through 7 of this member contain the item state flags. This can be one or more of the item state values.

Bits 8 through 11 of this member specify the one-based overlay image index. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed over the item’s icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To set the overlay image index in this member, you should use the INDEXTOOVERLAYMASK macro. The image list’s overlay images are set with the ImageList_SetOverlayImage function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item’s icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To set the state image index, you should use the INDEXTOSTATEIMAGEMASK macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the LVM_SETIMAGELIST message.

stateMask
Specifies which bits of the state member will be retrieved or modified. For example, setting this member to LVIS_SELECTED will cause only the item’s selection state to be retrieved.

This member allows you to modify one or more item states without having to retrieve all of the item states first. For example, setting this member to LVIS_SELECTED and state to zero will cause the item’s selection state to be cleared, but none of the other states will be affected.

To retrieve or modify all of the states, set this member to (UINT) –1.

You can use the macro ListView_SetItemState both to set and to clear bits.

pszText
Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the item is a callback item. Do not set the pszText member to LPSTR_TEXTCALLBACK if the list view control has LVS_SORTASCENDING or LVS_SORTDESCENDING style.

If the structure is receiving item attributes, this member is the address of the buffer that receives the item text.

cchTextMax
Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. This member is ignored if the structure specifies item attributes.
iImage
Index of the item’s icon in the control’s image list. This applies to both the large and small image list.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the list view control sends the parent an LVN_GETDISPINFO notification message to get the index when it needs to display the image.

lParam
32-bit value specific to the item. If you use the LVM_SORTITEMS message, the list view control passes this value to the application-defined comparison function. You can also use the LVM_FINDITEM message to search a list view control for an item with a specified lParam value.

Remarks

The LV_ITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM, and LVM_DELETEITEM.

See Also

LVN_SETDISPINFO


LV_KEYDOWN

This structure contains information about a keyboard event in a list view control. This structure is identical to the NMLVKEYDOWN structure, but was renamed to fit standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagLV_KEYDOWN {
NMHDR hdr;
WORD wVKey;
UINT flags;
} LV_KEYDOWN;

Members

hdr
NMHDR structure that contains additional information about the notification message.
wVKey
Virtual key code.
flags
Set to zero.

See Also

LVN_KEYDOWN, NMHDR


LVCOLUMN

This structure contains information about a column in report view. This structure is used both for creating columns and manipulating them using messages. The structure was extended to support new mask values. Two new members, iOrder and iImage, were added to support the new mask values.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _LVCOLUMN {
UINT mask;
int fmt;
int cx;
LPTSTR pszText;
int cchTextMax;
int iSubItem;
int iOrder;
 int iImage;
} LVCOLUMN;

Members

mask
Specifies which members contain valid information. It can be zero, or one or more of the following values.
Value
Description
LVCF_FMT | The fmt member is valid.
LVCF_IMAGE | The iImage member is valid.
LVCF_ORDER | The iOrder member is valid.
LVCF_SUBITEM | The iSubItem member is valid.
LVCF_TEXT | The pszText member is valid.
LVCF_WIDTH | The cx member is valid.

fmt
Alignment of the column heading and the subitem text in the column. It is one of the following values:
Value
Description
LVCFMT_BITMAP_ON_RIGHT | The bitmap appears to the right of text. This does not affect an image from an image list assigned to the header item.
LVCFMT_CENTER | Text is centered.
LVCFMT_IMAGE | The item displays an image from an image list.
LVCFMT_LEFT | Text is left-aligned.
LVCFMT_RIGHT | Text is right-aligned.

The leftmost column in a list view control must be left aligned.

cx
Width of the column, in pixels.
pszText
If column information is being set, this member is the pointer to a null-terminated string that contains the column heading text. If the structure is receiving information about a column, this member specifies the address of the buffer that receives the column heading text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information about a column, this member is ignored.
iSubItem
Index of subitem associated with the column.
iOrder
Zero-based column offset. Column offset is with left-to-right order. For example, zero indicates the leftmost column.
iImage
Zero-based index of an image within the image list. The specified image will appear within the column.

Remarks

This structure supersedes the LV_COLUMN structure.

This structure is used with the LVM_GETCOLUMN, LVM_SETCOLUMN, LVM_INSERTCOLUMN, and LVM_DELETECOLUMN messages.


LVFINDINFO

This structure that contains information used to search for a list view item.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagLVFINDINFO
{
 UINT flags;
 LPCTSTR psz;
 LPARAM lParam;
 POINT pt;
 UINT vkDirection;
} LVFINDINFO, FAR* LPFINDINFO;

Members

flags
Specifies the type of search to perform. It can be one or more of the following values:
Value
Description
LVFI_PARAM | Searches based on the lParam member. The lParam member of the matching item’s LVITEM structure must match the lParam member of this structure. If this value is specified, all other values are ignored.
LVFI_PARTIAL | Matches if the item text begins with the string pointed to by the psz member. This value implies use of LVFI_STRING.
LVFI_STRING | Searches based on the item text. Unless additional values are specified, the item text of the matching item must exactly match the string pointed to by the psz member.
LVFI_WRAP | Continues the search at the beginning if no match is found.
LVFI_NEARESTXY | Finds the item nearest to the position specified in the pt member, in the direction specified by the vkDirection member.

psz
Pointer to a null-terminated string to compare with the item text if flags specifies LVFI_STRING or LVFI_PARTIAL.
lParam
Value to compare with the lParam member of a list view item’s LVITEM structure if the flags member specifies LVFI_PARAM.
pt
POINT structure that specifies the starting position to search from. This member is used only if LVFI_NEARESTXY is specified in the flags member.
vkDirection
Specifies the direction to search in by containing the virtual-key code of an arrow key that specified the direction to search in. This member is used only if LVFI_NEARESTXY is specified in the flags member.

Remarks

This structure supersedes the LV_FINDINFO structure.


LVHITTESTINFO

This structure has been extended to accommodate subitem hit-testing. The LVHITTESTINFO structure contains information about a hit test. It is used in association with the LVM_HITTEST and LVM_SUBITEMHITTEST messages and their related macros.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _LVHITTESTINFO {
POINT pt;
UINT flags;
int iItem;
int iSubItem;
 } LVHITTESTINFO;

Members

pt
Position to hit test, in client coordinates.
flags
Receives information about the results of a hit test. It can be one or more of the following values.
Value
Description
LVHT_ABOVE | The position is above the control’s client area.
LVHT_BELOW | The position is below the control’s client area.
LVHT_NOWHERE | The position is inside the list view control’s client window, but it is not over a list item.
LVHT_ONITEMICON | The position is over a list view item’s icon.
LVHT_ONITEMLABEL | The position is over a list view item’s text.
LVHT_ONITEMSTATEICON | The position is over the state image of a list view item.
LVHT_TOLEFT | The position is to the left of the list view control’s client area.
LVHT_TORIGHT | The position is to the right of the list view control’s client area.

You can use LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT to determine whether to scroll the contents of a list view control. Two of these values may be combined. For example, if the position is above and to the left of the client area, you could use both LVHT_ABOVE and LVHT_TO LEFT.

You can test for LVHT_ONITEM to determine whether a specified position is over a list view item. This value is a bitwise-OR operation on LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON.

iItem
Receives the index of the matching item. Or if hit-testing a subitem, this value represents the subitem’s parent item.
iSubItem
Receives the index of the matching subitem. When hit-testing an item, this member will be zero.

Remarks

This structure supersedes the LV_HITTESTINFO structure.


LVITEM

This structure that specifies or receives the attributes of a list view item. It has been updated to support a new mask value (LVIF_INDENT) that enables item indenting.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _LVITEM {
UINT mask;
int iItem;
int iSubItem;
UINT state;
UINT stateMask;
LPTSTR pszText;
int cchTextMax;
int iImage;
LPARAM lParam;
 int iIndent;
} LVITEM;

Members

mask
Specifies which members of this structure contain data to be set or are being requested. It can be a combination of one or more of the following flags:
Value
Description
LVIF_TEXT | The pszText member is valid or must be filled in.
LVIF_IMAGE | The iImage member is valid or must be filled in.
LVIF_INDENT | The iIndent member is valid or must be filled in.
LVIF_NORECOMPUTE | The control will not generate a LVN_GETDISPINFO message to retrieve text information if it receives a LVM_GETITEM message. Instead, the pszText member will contain LPSTR_TEXTCALLBACK.
LVIF_PARAM | The lParam member is valid or must be filled in.
LVIF_STATE | The state member is valid or must be filled in.
LVIF_DI_SETITEM | The operating system should store the requested list item information, and not ask for it again. This flag is used only with the LVN_GETDISPINFO notification message.

iItem
Zero-based index of the item to which this structure refers.
iSubItem
One-based index of the subitem to which this structure refers, or zero if this structure refers to an item rather than a subitem.
state
Current state of the item if the item’s state is being retrieved, or the new state if the item’s state is being set. The stateMask member specifies which bits of this member should be retrieved or modified. Any bits in this member that are not set in stateMask will be ignored. This member can be any valid combination of list view state values.
stateMask
Specifies which bits of the state member will be retrieved or modified.

If the item’s state is being retrieved, this member enables you to specify which states will be retrieved. For example, setting this member to LVIS_SELECTED will cause only the item’s selection state to be retrieved.

If item’s state is being modified, this member allows you to modify one or more states without having to retrieve all of the states first. For example, setting this member to LVIS_SELECTED and state to zero will cause the item’s selection state to be cleared, but none of the other states will be affected.

To retrieve or modify all of the states, set this member to (UINT) –1.

pszText
Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the item is a callback item. Do not set the pszText member to LPSTR_TEXTCALLBACK if the list view control has LVS_SORTASCENDING or LVS_SORTDESCENDING style.

If the structure is receiving item attributes, this member is the Pointer to the buffer that receives the item text.

cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index of the list view item’s icon in the icon list and the small icon image list.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the list view control sends the parent an LVN_GETDISPINFO notification message to get the index when it needs to display the image.

lParam
Specifies the 32-bit value of the item. If you use the LVM_SORTITEMS message, the list view control passes this value to the application-defined comparison function. You can also use the LVM_FINDITEM message to search a list view control for an item with a specified lParam value.
iIndent
Number of image widths to indent the item. A single indentation equals the width of an item image. Therefore, the value 1 indents the item by the width of one image, the value 2 indents by two images, and so on. Note that this member is supported only for items. Attempting to set subitem indentation will cause the calling function to fail.

Remarks

The LVITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM, and LVM_DELETEITEM.

This structure supersedes the LV_ITEM structure.

Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. This member is ignored if the structure specifies item attributes.


MCHITTESTINFO

This structure carries information specific to hit-testing points for a month calendar control. This structure is used with the MCM_HITTEST message and the corresponding MonthCal_HitTest macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
 UINT cbSize;
 POINT pt;
 UINT uHit;
SYSTEMTIME st;
} MCHITTESTINFO, *PMCHITTESTINFO;

Members

cbSize
Size of this structure, in bytes.
pt
POINT structure that contains information about the point to be hit-tested.
uHit
Output member that receives a bit flag representing the result of the hit-test operation. It is one of the following values:
Value
Description
MCHT_CALENDARBK | The specified point was in the calendar’s background.
MCHT_CALENDARDATE | The specified point was on a particular date within the calendar. The SYSTEMTIME structure at lpMCHitTest->st is set to the date at the given point.
MCHT_CALENDARDATENEXT | The specified point was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_CALENDARDATEPREV | The specified point was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_CALENDARDAY | The specified point was over a day abbreviation (“Fri”). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the top row.
MCHT_CALENDARWEEKNUM | The specified point was over a week number (MCS_WEEKNUMBERS only). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the leftmost column.
MCHT_NOWHERE | The specified point was either not on the month calendar control, or in an inactive portion of the control.
MCHT_TITLEBK | The specified point was over the background of a month’s title.
MCHT_TITLEBTNNEXT | The specified point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_TITLEBTNPREV | The specified point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLEMONTH | The specified point was in a month’s title bar, over a month name.
MCHT_TITLEYEAR | The specified point was in a month’s title bar, over the year value.

st
SYSTEMTIME structure that receives date and time information specific to the location that was hit-tested.


MSG

This structure contains message information from a thread’s message queue.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagMSG {
HWND hwnd;
UINT message;
WPARAM wParam;
LPARAM lParam;
DWORD time;
POINT pt;
} MSG;

Members

hwnd
Handle to the window whose window procedure receives the message.
message
Specifies the message identifier.
wParam
Specifies additional information about the message. The exact meaning depends on the value of the message member.
lParam
Specifies additional information about the message. The exact meaning depends on the value of the message member.
time
Specifies the time at which the message was posted.
pt
Specifies the cursor position, in screen coordinates, when the message was posted.

Remarks

On Windows CE–based devices that use a stylus and touch screen instead of a mouse, the pt member contains the coordinates of the last position touched on the screen, rather than the coordinates of the current cursor position.

If you need mouse cursor support in your application, use the Windows CE Iconcurs component rather than the Windows CE Icon component and the Windows CE Mcursor component rather than the Windows CE Cursor component.

See Also

GetMessage, PeekMessage


NEWTEXTMETRIC

This structure contains data that describes a physical font.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagNEWTEXTMETRIC {
LONG tmHeight;
LONG tmAscent;
LONG tmDescent;
LONG tmInternalLeading;
LONG tmExternalLeading;
LONG tmAveCharWidth;
LONG tmMaxCharWidth;
LONG tmWeight;
LONG tmOverhang;
LONG tmDigitizedAspectX;
LONG tmDigitizedAspectY;
BCHAR tmFirstChar;
BCHAR tmLastChar;
BCHAR tmDefaultChar;
BCHAR tmBreakChar;
BYTE tmItalic;
BYTE tmUnderlined;
BYTE tmStruckOut;
BYTE tmPitchAndFamily;
BYTE tmCharSet;
 DWORD ntmFlags;
UINT ntmSizeEM;
UINT ntmCellHeight;
UINT ntmAvgWidth;
} NEWTEXTMETRIC;

Members

tmHeight
Specifies the height (ascent + descent) of characters.
tmAscent
Specifies the ascent (units above the base line) of characters.
tmDescent
Specifies the descent (units below the base line) of characters.
tmInternalLeading
Specifies the amount of leading (space) inside the bounds set by the tmHeight member. Accent marks and other diacritical characters may occur in this area. The designer may set this member to zero.
tmExternalLeading
Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls in either OPAQUE or TRANSPARENT mode. The designer may set this member to zero.
tmAveCharWidth
Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include overhang required for bold or italic characters.
tmMaxCharWidth
Specifies the width of the widest character in the font.
tmWeight
Specifies the weight of the font.
tmOverhang
Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

tmDigitizedAspectX
Specifies the horizontal aspect of the device for which the font was designed.
tmDigitizedAspectY
Specifies the vertical aspect of the device for which the font was designed. The ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the aspect ratio of the device for which the font was designed.
tmFirstChar
Specifies the value of the first character defined in the font.
tmLastChar
Specifies the value of the last character defined in the font.
tmDefaultChar
Specifies the value of the character to be substituted for characters that are not in the font.
tmBreakChar
Specifies the value of the character to be used to define word breaks for text justification.
tmItalic
Specifies an italic font if it is nonzero.
tmUnderlined
Specifies an underlined font if it is nonzero.
tmStruckOut
Specifies a strikeout font if it is nonzero.
tmPitchAndFamily
Specifies the pitch and family of the selected font. The low-order bit (bit 0) specifies the pitch of the font. If it is 1, the font is variable pitch (or proportional). If it is 0, the font is fixed pitch (or monospace). Bits 1 and 2 specify the font type. If both bits are 0, the font is a raster font; if bit 1 is 1 and bit 2 is 0, the font is a vector font; if bit 1 is 0 and bit 2 is set, or if both bits are 1, the font is some other type. Bit 3 is 1 if the font is a device font; otherwise, it is 0.

The four high-order bits designate the font family. The tmPitchAndFamily member can be combined with the hexadecimal value 0xF0 by using the bitwise AND operator and can then be compared with the font family names for an identical match. For more information about the font families, see LOGFONT.

tmCharSet
Specifies the character set of the font.
ntmFlags
Specifies whether the font is italic, underscored, outlined, bold, and so forth. The following list shows the bits corresponding to each font type:
Bit
Font
0 | Italic
1 | Underscore
2 | Negative
3 | Outline
4 | Strikeout
5 | Bold

ntmSizeEM
Specifies the size of the em square for the font. This value is in “notional units” (that is, the units for which the font was designed).
ntmCellHeight
Specifies the height, in notional units, of the font. This value should be compared with the value of the ntmSizeEM member.
ntmAvgWidth
Specifies the average width of characters in the font, in notional units. This value should be compared with the value of the ntmSizeEM member.

Remarks

The last four members of the NEWTEXTMETRIC structure are not included in the TEXTMETRIC structure; in all other respects, the structures are identical.

The sizes in the NEWTEXTMETRIC structure are typically given in logical units; that is, they depend on the current mapping mode of the display context.

See Also

EnumFontFamilies, GetTextMetrics, LOGFONT


NM_LISTVIEW

This structure contains information about a list view notification message. This structure is identical to the NMLISTVIEW structure, but was renamed to fit standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagNM_LISTVIEW {
NMHDR hdr;
int iItem;
int iSubItem;
UINT uNewState;
UINT uOldState;
UINT uChanged;
POINT ptAction;
} NM_LISTVIEW;

Members

hdr
NMHDR structure that contains information about this notification message.
iItem
Identifier of the list view item, or -1 if not used.
iSubItem
Identifier of the subitem, or zero if none.
uNewState
New item state. This member is zero for notification messages that do not use it.
uOldState
Old item state. This member is zero for notification messages that do not use it.
uChanged
Set of flags that indicate the item attributes that have changed. This member is zero for notifications that do not use it. Otherwise, it can have the same values as the mask member of the LV_ITEM structure.
ptAction
POINT structure that indicates the location at which the event occurred. This member is undefined for notification messages that do not use it.

See Also

LV_ITEM, NMHDR, WM_NOTIFY, LVN_BEGINDRAG,


NM_TREEVIEW

This structure contains information about a tree view notification message. This structure is identical to the NMTREEVIEW structure, but was renamed to follow current naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _NM_TREEVIEW {
NMHDR hdr;
UINT action;
TV_ITEM itemOld;
TV_ITEM itemNew;
POINT ptDrag;
} NM_TREEVIEW;
typedef NM_TREEVIEW FAR *LPNM_TREEVIEW;

Members

hdr
NMHDR structure that contains information about this notification message.
action
Notification-specific action flag.
itemOld
TV_ITEM structure that contains information about the old item state. This member is zero for notification messages that do not use it.
itemNew
TV_ITEM structure that contains information about the new item state. This member is zero for notification messages that do not use it.
ptDrag
POINT structure that contains the client coordinates of the mouse at the time the event occurred that caused the notification message to be sent.

See Also

WM_NOTIFY


NM_UPDOWN

This structure contains information about an up-down control notification message. This structure is identical to the NMUPDOWN structure, but was renamed to follow current naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _NM_UPDOWN {
NMHDR hdr;
int iPos;
int iDelta;
} NM_UPDOWNW;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iPos
Signed integer value that represents the up-down control’s current position.
iDelta
Signed integer value that represents the proposed change in the up-down control’s position.

Remarks

In Windows CE version 2.0, this structure has been renamed NMUPDOWN.

See Also

NMHDR, UDN_DELTAPOS, WM_NOTIFY


NMCUSTOMDRAW

This structure contains information specific to an NM_CUSTOMDRAW notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMCUSTOMDRAWINFO {
 NMHDR hdr;
 DWORD dwDrawStage;
 HDC hdc;
 RECT rc;
 DWORD dwItemSpec;
 UINT uItemState;
 LPARAM lItemlParam;
} NMCUSTOMDRAW, FAR * LPNMCUSTOMDRAW;

Members

hdr
Handle to a NMHDR structure that contains information about this notification message.
dwDrawStage
Specifies the current drawing stage. It is one of the following values.

Global Drawstage values:
Value
Description
CDDS_POSTERASE | After the erasing cycle is complete.
CDDS_POSTPAINT | After the painting cycle is complete.
CDDS_PREERASE | Before the erasing cycle begins.
CDDS_PREPAINT | Before the painting cycle begins.

Item-Specific Drawstage values:
Value
Description
CDDS_ITEM | Indicates that the dwItemSpec, uItemState, and lItemParam members are valid.
CDDS_ITEMPOSTERASE | After an item has been erased
CDDS_ITEMPOSTPAINT | After an item has been drawn
CDDS_ITEMPREERASE | Before an item is erased
CDDS_ITEMPREPAINT | Before an item is drawn

hdc
Handle to the control’s device context. Use this HDC to perform any GDI functions.
rc
RECT structure that describes the bounding rectangle of the area being drawn.
dwItemSpec
Specifies the item number. This value is control specific, using the item-referencing convention for that control. Additionally, trackbar controls use the following values to identify portions of control:
Value
Description
TBCD_CHANNEL | Identifies the channel that the trackbar control’s thumb marker slides along.
TBCD_THUMB | Identifies the trackbar control’s thumb marker. This is the portion of the control that the user moves.
TBCD_TICS | Identifies the increment tic marks that appear along the edge of the trackbar control.

uItemState
Specifies the current item state. It can be a combination of the following values:
Value
Description
CDIS_CHECKED | The item is checked.
CDIS_DEFAULT | The item is in its default state.
CDIS_DISABLED | The item is disabled.
CDIS_FOCUS | The item is in focus.
CDIS_GRAYED | The item is grayed.
CDIS_HOT | The item is currently under the pointer (“hot”).
CDIS_SELECTED | The item is selected.

lItemlParam
Application-defined item data.


NMDATETIMECHANGE

This structure contains information about a change that has taken place in a date and time picker (DTP) control. This structure is used with the DTN_DATETIMECHANGE notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMDATETIMECHANGE {
 NMHDR nmhdr;
 DWORD dwFlags;
 SYSTEMTIME st;
} NMDATETIMECHANGE, FAR * LPNMDATETIMECHANGE;

Members

nmhdr
NMHDR structure that contains information about the notification message.
dwFlags
Specifies if the control was set to “no date” status (for DTS_SHOWNONE only). Also specifies whether the contents of the st member are valid and contain current time information. It is one of the following values:
Value
Description
GDT_NONE | The control is set to “no date” status. The “no date” status applies only to controls that are set to the DTS_SHOWNONE style.
GDT_VALID | The control is not set to the “no date” status. The st member contains the current date and time.

st
SYSTEMTIME structure that contains information about the current system date and time.


NMDATETIMEFORMAT

This structure is used with the DTN_FORMAT notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMDATETIMEFORMAT{
 NMHDR nmhdr;
 LPCTSTR pszFormat;
 SYSTEMTIME st;
 LPCTSTR pszDisplay;
 TCHAR szDisplay[64];
} NMDATETIMEFORMAT, FAR * LPNMDATETIMEFORMAT;

Members

nmhdr
NMHDR structure that contains information about the notification message.
pszFormat
Pointer to the null-terminated substring that defines a DTP control callback field The substring comprises one or more “X” characters, followed by a NULL character. For additional information about callback fields, see Callback Fields.
st
SYSTEMTIME structure that contains information about the current system date and time.
pszDisplay
Pointer to a null-terminated string. By default, this pointer is set to point at szDisplay by the DTP control.

It is legal to set this member to point at an existing string. If so, the application is not required to place a string into the szDisplay member.

szDisplay
Specifies the 64-character buffer that is to receive the null-terminated string that the DTP control will display. It is not necessary that the application fill the entire buffer.

Remarks

The NMDATETIMEFORMAT structure contains information about a portion of the format string that defines a callback field within a date and time picker (DTP) control. It carries the substring that defines the callback field and contains a buffer to receive the string that will be displayed in the callback field.


NMDATETIMEFORMATQUERY

This structure is used with the DTN_FORMATQUERY notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMDATETIMEFORMATQUERY{
 NMHDR nmhdr;
 LPCTSTR pszFormat;
 SIZE szMax;
} NMDATETIMEFORMATQUERY, FAR * LPNMDATETIMEFORMATQUERY;

Members

nmhdr
NMHDR structure that contains information about this notification message.
pszFormat
Pointer to a null-terminated substring that defines a DTP control callback field. The substring is one or more “X” characters followed by a NULL. For additional information about callback fields, see Callback Fields.
szMax
SIZE structure that must be filled with the maximum size of the text to be displayed in the callback field.

Remarks

The NMDATETIMEFORMATQUERY structure contains information about a date and time picker (DTP) control callback field. It contains a substring (taken from the control’s format string) that defines a callback field. The structure receives the maximum allowable size of the text that will be displayed in the callback field.


NMDATETIMESTRING

This structure contains information specific to an edit operation that has taken place in a date and time picker (DTP) control. This message is used with the DTN_USERSTRING notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMDATETIMESTRING{
 NMHDR nmhdr;
 LPCTSTR pszUserString;
 SYSTEMTIME st;
 DWORD dwFlags;
} NMDATETIMESTRING, FAR * LPNMDATETIMESTRING;

Members

nmhdr
NMHDR structure that contains information about this notification message.
pszUserString
Pointer to the null-terminated string that the user entered.
st
SYSTEMTIME structure that must be filled in by the owner when handling the DTN_USERSTRING notification message.
dwFlags
Return member. Set this member to GDT_VALID to indicate that the st member is valid, or to GDT_NONE to set the control to “no date” status (DTS_SHOWNONE style only).


NMDATETIMEWMKEYDOWN

This structure carries information used to describe and handle a DTN_WMKEYDOWN notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMDATETIMEWMKEYDOWN{
 NMHDR nmhdr;
 int nVirtKey;
 LPCTSTR pszFormat;
 SYSTEMTIME st;
} NMDATETIMEWMKEYDOWN, FAR * LPNMDATETIMEWMKEYDOWN;

Members

nmhdr
NMHDR structure that contains information about the notification message.
nVirtKey
Virtual key code that represents the key that the user pressed.
pszFormat
Pointer to a null-terminated substring, taken from the format string, that defines the callback field.
st
SYSTEMTIME structure containing the current date and time from the DTP control. The owner of the control must modify the time information based on the user’s keystroke.


NMDAYSTATE

This structure carries information required to process the MCN_GETDAYSTATE notification message. All members of this structure are for input, except prgDayState, which the user must set when processing MCN_GETDAYSTATE.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMDAYSTATE {
 NMHDR nmhdr;
 SYSTEMTIME stStart;
 int cDayState;
 LPMONTHDAYSTATE prgDayState;
} NMDAYSTATE, FAR * LPNMDAYSTATE;

Members

nmhdr
NMHDR structure that contains information about this notification message.
stStart
SYSTEMTIME structure that contains the starting date.
cDayState
Value that specifies the total number of elements that must be in the array at prgDayState.
prgDayState
Pointer to an array of MONTHDAYSTATE values. This must be set to point to an array that contains as many elements as specified in cDayState. The first element in the array corresponds to the date in stStart.


NMHDDISPINFO

This structure contains information used in handling HDN_GETDISPINFO notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMHDDISPINFO {
 NMHDR hdr;
 int iItem;
 UINT mask;
 LPTSTR pszText;
 int cchTextMax;
 int iImage;
 LPARAM lParam;
} NMHDDISPINFO, FAR* LPNMHDDISPINFO;

Members

hdr
NMHDR structure containing information about this notification message.
iItem
Zero-based index of the item in the header control.
mask
Specifies which members of the structure must be filled in by the owner of the header control. It can be a combination of the following values:
Value
Description
HDI_TEXT | The pszText member must be filled in.
HDI_IMAGE | The iImage member must be filled in.
HDI_LPARAM | The lParam member must be filled in.
HDI_DI_SETITEM | A return value. Specifies that the header control should store the item information and not ask for it again.

pszText
Pointer to a null-terminated string that contains the text to be displayed for the header item.
cchTextMax
Size of the buffer that pszText points to.
iImage
Zero-based index of an image within the image list. The specified image will be displayed with the header item, but does not take the place of the image specified in the hbm member. If iImage is set to I_IMAGECALLBACK, the control requests image information for this item by using HDN_GETDISPINFO notification messages.
lParam


NMHDR

This structure contains information about a notification message. The pointer to this structure is specified as the lParam member of the WM_NOTIFY message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagNMHDR {
HWND hwndFrom;
UINT idFrom;
UINT code;
} NMHDR;

Members

hwndFrom
Window handle to the control sending a message.
idFrom
Identifier of the control sending a message.
code
Notification code. This member can be a control-specific notification code or it can be one of the common notification codes. The following values are not supported:
  • NM_RCLICK
  • NM_RDBCLICK


NMHEADER

This structure contains information about header control notification messages. This structure supersedes the HD_NOTIFY structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMHEADER{
 NMHDR hdr;
 int iItem;
 int iButton;
 HDITEM FAR* pItem;
} NMHEADER, FAR* LPNMHEADER;

Members

hdr
NMHDR structure that contains information about the notification message.
iItem
Zero-based index of the header item that is the focus of the notification message.
iButton
Index of the mouse button used to generate the notification message. It is one of the following values:
Value
Description
0 | Left button
1 | Right button
2 | Middle button

pItem
Pointer to an HDITEM structure that contains information specific to the item indicated by iItem.


NMKEY

This structure contains information used with key notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMKEY {
 NMHDR hdr;
 WORD wVKey;
 UINT flags;
} NMKEY, FAR * LPNMKEY;

Members

hdr
Handle to a NMHDR structure that contains additional information about this notification.
wVKey
Virtual key code of the key that caused the event.
flags
Flags associated with the key. These are the same flags that are passed in the high-order word of the lParam in the WM_KEYDOWN message.


NMLISTVIEW

This structure contains information about a list view notification message. This structure is the same as the NM_LISTVIEW structure, but has been renamed to fit standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMLISTVIEW{
 NMHDR hdr;
 int iItem;
 int iSubItem;
 UINT uNewState;
 UINT uOldState;
 UINT uChanged;
 POINT ptAction;
 LPARAM lParam;
} NMLISTVIEW, FAR *LPNMLISTVIEW;

Members

hdr
NMHDR structure that contains information about this notification message.
iItem
Identifier of the list view item, or ?1 if not used.
iSubItem
Identifier of the subitem, or zero if none.
uNewState
Specifies the new item state. This member is zero for notification messages that do not use it.
uOldState
Specifies the old item state. This member is zero for notification messages that do not use it.
uChanged
Set of flags that indicate the item attributes that have changed. This member is zero for notification messages that do not use it. Otherwise, it can have the same values as the mask member of the LVITEM structure.
ptAction
Specifies a POINT structure that indicates the location at which the event occurred. This member is undefined for notification messages that do not use it.
lParam
Specifies the item’s application-defined 32-bit value. This member is undefined for notification messages that do not use it.


NMLVCACHEHINT

This structure contains information used to update the cached item information for use with a virtual list view.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMLVCACHEHINT {
 NMHDR hdr;
 int iFrom;
 int iTo;
} NMLVCACHEHINT, *PNMLVCACHEHINT;

Members

hdr
NMHDR structure that contains information about this notification message.
iFrom
Starting index of the requested range of items. This value is inclusive.
iTo
Ending index of the requested range of items. This value is inclusive.


NMLVCUSTOMDRAW

This structure contains information specific to an NM_CUSTOMDRAW notification message sent by a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMLVCUSTOMDRAW {
 NMCUSTOMDRAW nmcd;
 COLORREF clrText;
 COLORREF clrTextBk;
} NMLVCUSTOMDRAW, *LPNMLVCUSTOMDRAW;

Members

nmcd
NMCUSTOMDRAW structure that contains general Custom Draw information.
clrText
COLORREF value that represents the color that is used to display text foreground in the list view control.
clrTextBk
COLORREF value that represents the color that is used to display text background in the list view control.


NMLVFINDITEM

This structure that contains information the owner needs to find items requested by a virtual list view control. This structure is sent to the owner during notification using the LVN_ODFINDITEM message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _NMLVFINDITEM {
 NMHDR hdr;
 int iStart;
 LVFINDINFO lvfi;
} NMLVFINDITEM, *PNMLVFINDITEM;

Members

hdr
NMHDR structure that contains information on this notification message.
iStart
Item index to act as the start of the search.
lvfi
LVFINDINFO structure that contains information necessary to perform a search.


NMLVKEYDOWN

This structure that contains information used in processing the LVN_KEYDOWN notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagLVKEYDOWN {
 NMHDR hdr;
 WORD wVKey;
 UINT flags;
} NMLVKEYDOWN, FAR *LPNMLVKEYDOWN;

Members

hdr
NMHDR structure that contains additional information about the notification message.
wVKey
Virtual-key code.
flags
Set to zero.


NMLVODSTATECHANGE

This structure that contains information for use in processing the LVN_ODSTATECHANGED notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMLVODSTATECHANGE {
 NMHDR hdr;
 int iFrom;
 int iTo;
 UINT uNewState;
 UINT uOldState;
} NMLVODSTATECHANGE, FAR *LPNMLVODSTATECHANGE;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iFrom
Zero-based index of the first item in the range of items.
iTo
Zero-based index of the last item in the range of items.
uNewState and uOldState
Indicate the new and old states for the item or items. These members can be any valid combination of the following state flags:
Value
Description
LVIS_CUT | The item is marked for a cut and paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag and drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and on the system colors used for selection.


NMMOUSE

This structure contains information used with mouse notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMMOUSE {
 NMHDR hdr;
 DWORD dwItemSpec;
 DWORD dwItemData;
 POINT pt;
} NMMOUSE, FAR * LPNMMOUSE;

Members

hdr
Handle to a NMHDR structure that contains additional information about this notification.
dwItemSpec
Specifies the control-specific item identifier.
dwItemData
Specifies control-specific item data.
pt
POINT structure that contains the screen coordinates of the mouse when the click occurred.


NMRBAUTOSIZE

This structure contains information used in handling the RBN_AUTOSIZE notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMRBAUTOSIZE {
 NMHDR hdr;
 BOOL fChanged;
 RECT rcTarget;
 RECT rcActual;
} NMRBAUTOSIZE, *LPNMRBAUTOSIZE;

hdr
NMHDR structure that contains additional information about the notification message.
fChanged
Boolean that indicates if the size or layout of the rebar control has changed. A nonzero value indicates that a change occurred; zero indicates otherwise.
rcTarget
RECT structure that contains the rectangle that the rebar control tried to size itself to.
rcActual
RECT structure that contains the rectangle that the rebar control actually sized itself to.


NMREBAR

This structure contains information used in handling the RBN_BEGINDRAG and RBN_ENDDRAG notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMREBAR {
 NMHDR hdr;
 UINT uBand;
 UINT wID;
 UINT cyChild;
 UINT cyBand;
} NMREBAR, *LPNMREBAR;

hdr
NMHDR structure that contains additional information about the notification message.
uBand
Zero-based index of the band affected by the notification. This will be -1 if no band is affected.
wID
Application-defined identifier of the band. If uBand is -1, this member is undefined.
cyChild
Vertical size, in pixels, of the band’s child window. This member is not currently used.
cyBand
Vertical size, in pixels, of the band. This member is not currently used.


NMSELCHANGE

This structure carries information required to process the MCN_SELCHANGE notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMSELCHANGE{
 NMHDR nmhdr;
 SYSTEMTIME stSelStart;
 SYSTEMTIME stSelEnd;
} NMSELCHANGE, FAR * LPNMSELCHANGE;

Members

nmhdr
NMHDR structure that contains information about this notification message.
stSelStart
SYSTEMTIME structure that contains the date for the first day in the user’s selection range.
stSelEnd
SYSTEMTIME structure that contains the date for the last day in the user’s selection range.


NMTCKEYDOWN

This structure contains information about a key press in a tab control. It is used with the TCN_KEYDOWN notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMTCKEYDOWN {
 NMHDR hdr;
 WORD wVKey;
 UINT flags;
} NMTCKEYDOWN;

Members

hdr
NMHDR structure that contains information about the notification message.
wVKey
Virtual key code.
flags
Value that is identical to the lParam parameter of the WM_KEYDOWN message.


NMTOOLBAR

This structure contains information used to process toolbar notification messages. It is identical to the TBNOTIFY structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMTOOLBAR {
 NMHDR hdr;
 int iItem;
 TBBUTTON tbButton;
 int cchText;
 LPTSTR pszText;
} NMTOOLBAR, FAR* LPNMTOOLBAR;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iItem
Command identifier of the button associated with the notification.
tbButton
TBBUTTON structure that contains information about the toolbar button associated with the notification. This member only contains valid information with the TBN_QUERYINSERT and TBN_QUERYDELETE notifications.
cchText
Count of characters in the button text.
pszText
Pointer to a character buffer that contains the button text.


NMTVCUSTOMDRAW

This structure contains information specific to an NM_CUSTOMDRAW notification message sent by a tree view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagNMTVCUSTOMDRAW {
 NMCUSTOMDRAW nmcd;
 COLORREF clrText;
 COLORREF clrTextBk;
} NMTVCUSTOMDRAW, *LPNMTVCUSTOMDRAW;

Members

nmcd
NMCUSTOMDRAW structure that contains general Custom Draw information.
clrText
COLORREF value that represents the color that is used to display text foreground in the list view control.
clrTextBk
COLORREF value that represents the color that is used to display text background in the list view control.


NMTVKEYDOWN

This structure contains information about a keyboard event in a tree-view control. This structure is used with the TVN_KEYDOWN notification message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagTVKEYDOWN {
 NMHDR hdr;
 WORD wVKey;
 UINT flags;
} NMTVKEYDOWN, FAR *LPNMTVKEYDOWN;

Members

hdr
NMHDR structure that contains information about this notification message.
sVKey
Virtual key code.
flags
Set to zero.


PAINTSTRUCT

This structure contains information that an application uses to paint the client area of a window owned by that application.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPAINTSTRUCT {
HDC hdc;
BOOL fErase;
RECT rcPaint;
BOOL fRestore;
BOOL fIncUpdate;
BYTE rgbReserved[32];
} PAINTSTRUCT;

Members

hdc
Handle to the display DC to be used for painting.
fErase
Boolean that specifies whether the background must be erased. This value is nonzero if the application should erase the background. The application is responsible for erasing the background if a window class is created without a background brush. For more information, see the description of the hbrBackground member of the WNDCLASS structure.
rcPaint
Specifies a RECT structure that specifies the upper left and lower right corners of the rectangle in which the painting is requested.
fRestore
Reserved; used internally by the system.
fIncUpdate
Reserved; used internally by the system.
rgbReserved
Reserved; used internally by the system.

See Also

BeginPaint, RECT, WNDCLASS


PALETTEENTRY

This structure specifies the color and usage of a logical palette entry. A logical palette is defined by a LOGPALETTE structure.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagPALETTEENTRY {
 BYTE peRed;
 BYTE peGreen;
 BYTE peBlue;
 BYTE peFlags;
} PALETTEENTRY;

Members

peRed
Specifies a red intensity value for the palette entry.
peGreen
Specifies a green intensity value for the palette entry.
peBlue
Specifies a blue intensity value for the palette entry.
peFlags
Specifies how the palette entry is to be used. The peFlags member may be set to NULL or one of the following values:
Value
Description
PC_EXPLICIT | Specifies that the low-order word of the logical palette entry designates a hardware palette index. This flag allows the application to show the contents of the display device palette.
PC_NOCOLLAPSE | Specifies that the color be placed in an unused entry in the system palette instead of being matched to an existing color in the system palette. If there are no unused entries in the system palette, the color is matched normally. Once this color is in the system palette, colors in other logical palettes can be matched to this color.
PC_RESERVED | Specifies that the logical palette entry be used for palette animation. This flag prevents other windows from matching colors to the palette entry since the color frequently changes. If an unused system-palette entry is available, the color is placed in that entry. Otherwise, the color is not available for animation.

Remarks

Window CE ignores the peFlags member. It should be initialized to 0.

See Also

CreatePalette, LOGPALETTE


PBRANGE

This structure contains information about the high and low limits of a progress bar control. This structure is used with the PBM_GETRANGE message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
 int iLow;
 int iHigh;
} PBRANGE, *PPBRANGE;

Members

iLow
Specifies the current low limit for the progress bar control.
iHigh
Specifies the current high limit for the progress bar control.


POINT

This structure defines the x- and y-coordinates of a point.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPOINT { // pt
LONG x;
LONG y;
} POINT;

Members

x
Specifies the x-coordinate of the point.
y
Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, PtInRect, SetBrushOrgEx, WindowFromPoint


PROPSHEETHEADER

This structure defines the frame and pages of a property sheet.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _PROPSHEETHEADER {
DWORD dwSize;
DWORD dwFlags;
HWND hwndParent;
HINSTANCE hInstance;
union {
HICON hIcon;
LPCWSTR pszIcon;
};
LPCWSTR pszCaption;
UINT nPages;
union {
UINT nStartPage;
LPCWSTR pStartPage;
};
union {
LPCPROPSHEETPAGE ppsp;
HPROPSHEETPAGE FAR *phpage;
};
PFNPROPSHEETCALLBACK pfnCallback;
} PROPSHEETHEADER, FAR *LPPROPSHEETHEADER;

typedef const PROPSHEETHEADER FAR *LPCPROPSHEETHEADER;

Members

dwSize
Specifies the size, in bytes, of this structure.
dwFlags
Specifies a bitmask of flags that indicate which options to use when creating the property sheet page. It can be a combination of the following values:
Value
Description
PSH_DEFAULT | Uses the default meaning for all structure members.
PSH_HASHELP | Displays the property sheet Help button. The Help button is enabled only when the PSP_HASHELP flag is set in the PROPSHEETAPGE structure for the active page. If any of the initial property sheet pages set the PSP_HASHELP flag, the Help button is automatically displayed regardless of the PSH_HASHELP flag. However, PSH_HASHELP is useful when none of the initial pages set PSP_HASHELP, but pages added later might.
PSH_HEADER | Version 4.71. Indicates that a header bitmap will be used. If this value does not include PSH_USEHBMHEADER, the header bitmap is obtained from pszbmHeader. If this value includes PSH_USEHBMHEADER, the header bitmap is obtained from hbmHeader. This flag is ignored if PSH_WIZARD97 is not included.
PSH_MODELESS | Causes the PropertySheet function to create the property sheet as a modeless dialog instead of as a modal dialog. When this flag is set, PropertySheet returns immediately after the dialog is created, and the return value from PropertySheet is the window handle to the property sheet dialog.
PSH_NOAPPLYNOW | Removes the Apply Now button.
PSH_PROPSHEETPAGE | Uses ppsp and ignores phpage when creating the pages for the property sheet.
PSH_PROPTITLE | Displays the string “Properties for”, followed by the string specified by pszCaption, in the title bar of the property sheet.
PSH_RTLREADING | Displays the title of the property sheet dialog using right-to-left reading order on Hebrew or Arabic systems.
PSH_STRETCHWATERMARK | Version 4.71. Stretches the bitmap to fit the background of the property sheet instead of tiling the watermark and/or header bitmap. This flag is ignored if PSH_WIZARD97 and PSH_WATERMARK or PSH_HEADER are not included.
PSH_USECALLBACK | Calls the function specified by pfnCallback when initializing the property sheet defined by this structure.
PSH_USEHBMHEADER | Version 4.71. Obtains the header bitmap from hbmHeader instead of pszbmHeader. This flag is ignored if PSH_WIZARD97 and PSH_HEADER are not included.
PSH_USEHBMWATERMARK | Version 4.71. Obtains the watermark bitmap from hbmWatermark instead of pszbmWatermark. This flag is ignored if PSH_WIZARD97 and PSH_WATERMARK are not included.
PSH_USEHICON | Not supported.
PSH_USEHPLWATERMARK | Version 4.71. Obtains the HPALETTE for drawing the watermark bitmap and/or header bitmap from hplWatermark instead of using the default palette. This flag is ignored if PSH_WIZARD97 and PSH_WATERMARK or PSH_HEADER are not included.
PSH_USEICONID | Not supported.
PSH_USEPAGELANG | Version 4.71. The language for the property sheet will be taken from the first page’s resource.
PSH_USEPSTARTPAGE | Uses pStartPage and ignores nStartPage when displaying the initial page of the property sheet.
PSH_WATERMARK | Version 4.71. Specifies that a watermark bitmap will be used. If this value does not include PSH_USEHBMWATERMARK, the watermark bitmap is obtained from pszbmWatermark. If this value includes PSH_USEHBMWATERMARK, the header bitmap is obtained from hbmWatermark. This flag is ignored if PSH_WIZARD97 is not included.
PSH_WIZARD | Creates a wizard property sheet.
PSH_WIZARD97 | Creates a wizard property sheet that allows a header and/or watermark bitmap to be displayed in the background. This and all Wizard 97-associated flags are not currently implemented.
PSH_WIZARDCONTEXTHELP | Adds a system menu to the wizard property sheet. This flag is ignored if PSH_WIZARD or PSH_WIZARD97 is not included.
PSH_WIZARDHASFINISH | Always displays the Finish button on the wizard. This flag is ignored if PSH_WIZARD or PSH_WIZARD97 is not included.

hwndParent
Handle to the property sheet’s owner window.
hInstance
Handle to the instance from which to load the icon or title string resource. If pszIcon or pszCaption identifies a resource to load, this member must be specified.
hIcon
Handle to the icon to use as the small icon in the title bar of the property sheet dialog box. If dwFlags does not include PSH_USEHICON, this member is ignored.
pszIcon
Pointer to an icon resource to use as the small icon in the title bar of the property sheet dialog box. This member can specify either the identifier of the icon resource or the address of the string that specifies the name of the icon resource. If dwFlags does not include PSH_USEICONID, this member is ignored.
pszCaption
Pointer to the null-terminated string that contains the title of the property sheet dialog box. This member can specify either the identifier of a string resource or the address of a string that specifies the title. If dwFlags includes PSH_PROPTITLE, the string “Properties for” is inserted at the beginning of the title.
nPages
Number of elements in the phpage array.
nStartPage
Zero-based index of the initial page that appears when the property sheet dialog box is created.
pStartPage
Pointer to the name of the initial page that appears when the property sheet dialog box is created. This member can specify either the identifier of a string resource or the address of a string that specifies the name.
ppsp
Pointer to an array of PROPSHEETPAGE structures that define the pages in the property sheet. If dwFlags does not include PSH_PROPSHEETPAGE, this member is ignored.
phpage
Pointer to an array of handles to the property sheet pages. Each handle must have been created by a previous call to the CreatePropertySheetPage function. If dwFlags includes PSH_PROPSHEETPAGE, this member is ignored.
pfnCallback
Pointer to an application-defined callback function that is called when the property sheet is initialized. For more information about the callback function, see the description of the PropSheetProc function. If dwFlags does not include PSH_USECALLBACK, this member is ignored.
hbmWatermark
Version 4.71. Handle to the watermark bitmap. If dwFlags does not include PSH_USEHBMWATERMARK, this member is ignored.
pszbmWatermark
Version 4.71. Pointer to a bitmap resource to use as the watermark. This member can specify either the identifier of the bitmap resource or the address of the string that specifies the name of the bitmap resource. If dwFlags includes PSH_USEHBMWATERMARK, this member is ignored.
hplWatermark
Version 4.71. HPALETTE used for drawing the watermark bitmap and/or header bitmap. If dwFlags does not include PSH_USEHPLWATERMARK, this member is ignored.
hbmHeader
Version 4.71. Handle to the header bitmap. If dwFlags does not include PSH_USEHBMHEADER, this member is ignored.
pszbmHeader
Version 4.71. Pointer to a bitmap resource to use as the header. This member can specify either the identifier of the bitmap resource or the address of the string that specifies the name of the bitmap resource. If dwFlags includes PSH_USEHBMHEADER, this member is ignored.

See Also

CreatePropertySheetPage, PropertySheet, PROPSHEETPAGE


PROPSHEETPAGE

This structure defines a page in a property sheet.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _PROPSHEETPAGE {
DWORD dwSize;
DWORD dwFlags;
HINSTANCE hInstance;
union {
LPCSTR pszTemplate;
LPCDLGTEMPLATE pResource;
};
union {
HICON hIcon;
LPCSTR pszIcon;
};
LPCSTR pszTitle;
DLGPROC pfnDlgProc;
LPARAM lParam;
LPFNPSPCALLBACK pfnCallback;
UINT FAR * pcRefParent;
} PROPSHEETPAGE, FAR *LPPROPSHEETPAGE;

typedef const PROPSHEETPAGE FAR *LPCPROPSHEETPAGE;

Members

dwSize
Specifies the size, in bytes, of the structure. The size includes any extra application-defined data at the end of the structure.
dwFlags
Specifies a bitmask of flags that enable optional attributes of the property sheet page, and indicate the valid members of the PROPSHEETPAGE structure. This member can be any combination of the following values:
Value
Description
PSP_DEFAULT | Uses the default meaning for all structure members.
PSP_DLGINDIRECT | Creates the page from the dialog box template in memory pointed to by the pResource member. The Win32 PropertySheet function assumes that the template is in writeable memory; a read-only template will cause an exception on some versions of Windows. If this flag is not set, the page loads the dialog box template from the resource identified by the pszTemplate member.
PSP_HASHELP | Enables the property sheet Help button when this page is active.
PSP_USECALLBACK | Calls the function specified by pfnCallback when creating or destroying the property sheet page defined by this structure.
PSP_HICON | Not supported.
PSP_PREMATURE | The page is created when the property sheet is created. Usually, the page is not created until the first time it is selected.
PSP_USEICONID | Not supported.
PSP__USEREFPARENT | Maintains the reference count specified by pcRefParent for the lifetime of the property sheet page created from this structure.
PSP_USETITLE | Uses pszTitle as the title of the property sheet dialog box instead of the title stored in the dialog box template.
PSP_RTLREADING | When this page is active, displays the text of pszTitle using right-to-left reading order on Hebrew or Arabic systems.

hInstance
Handle to the instance from which to load the dialog box template, icon, or title string resource.
pszTemplate
Pointer to a dialog box template to use to create the page. This member can specify either the resource identifier of the template or the address of a string that specifies the name of the template. If dwFlags includes the PSP_DLGINDIRECT value, this member is ignored.
pResource
Pointer to a dialog box template in memory. The Win32 PropertySheet function assumes that the template is in writeable memory; a read-only template will cause an exception on some versions of Windows. If dwFlags does not include the PSP_DLGINDIRECT value, this member is ignored.
hIcon
Ignored. Must be NULL.
pszIcon
Ignored. Must be NULL.
pszTitle
Pointer to the null-terminated string that contains the title of the property sheet dialog box. This title overrides the title specified in the dialog box template. This member can specify either the identifier of a string resource or the pointer to a string that specifies the title. If dwFlags does not include the PSP_USETITLE value, this member is ignored.
pfnDlgProc
Pointer to the dialog box procedure for the page. The dialog box procedure must not call the Win32 EndDialog function.
lParam
Application-defined data.
pfnCallback
Pointer to an application-defined callback function that is called when the page is created and when it is about to be destroyed. For more information about the Win32 callback function, see PropSheetPageProc. If dwFlags does not include the PSP_USECALLBACK value, this member is ignored.
pcRefParent
Pointer to the reference count value. If dwFlags does not include the PSP_USERREFPARENT value, this member is ignored.

Remarks

When the PropertySheet function creates the page, the dialog box procedure for the page receives a WM_INITDIALOG message. The lParam parameter of this message points to the PROPSHEETPAGE structure used to create the page.

See Also

CreatePropertySheetPage, PropSheetPageProc


PSHNOTIFY

This structure contains information for the PSN_APPLY and PSN_RESET notification messages.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _PSHNOTIFY {
NMHDR hdr;
LPARAM lParam;
} PSHNOTIFY, FAR *LPPSHNOTIFY;

Members

hdr
NMHDR structure that contains additional information about the notification.
lParam
Additional information about this notification. See the description of the particular notification message to determine what, if any, information is contained in this member.

See Also

PSN_APPLY, PSN_RESET


RBHITTESTINFO

This structure contains information specific to a hit test operation. This structure is used with the RB_HITTEST message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _RB_HITTESTINFO {
 POINT pt;
 UINT flags;
 int iBand;
} RBHITTESTINFO, FAR *LPRBHITTESTINFO;

Members

pt
POINT structure that describes the point to be hit tested, in client coordinates.
flags
Receives a flag value indicating the rebar band’s component located at the point described by pt. It is one of the following values:
Value
Description
RBHT_CAPTION | The point was in the rebar band’s caption.
RBHT_CLIENT | The point was in the rebar band’s client area.
RBHT_GRABBER | The point was in the rebar band’s grabber.
RBHT_NOWHERE | The point was not in a rebar band.

iBand
Receives the rebar band’s index at the point described by pt. This value is the zero-based index of the band or -1 if no band was at the hit-tested point.


REBARBANDINFO

This structure contains information that defines a band in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagREBARBANDINFO{
 UINT cbSize;
 UINT fMask;
 UINT fStyle;
 COLORREF clrFore;
 COLORREF clrBack;
 LPTSTR lpText;
 UINT cch;
 int iImage;
 HWND hwndChild;
 UINT cxMinChild;
 UINT cyMinChild;
 UINT cx;
 HBITMAP hbmBack;
 UINT wID;
 UINT cyChild;
UINT cyMaxChild;
 UINT cyIntegral;
 UINT cxIdeal;
 LPARAM lParam;
 } REBARBANDINFO, FAR *LPREBARBANDINFO;

Members

cbSize
Size of this structure, in bytes. The application must fill this member before sending any messages that use the address of this structure as a parameter.
fMask
Flags that indicate which members of this structure are valid or must be filled. It can be a combination of the following values:
Value
Description
RBBIM_BACKGROUND | The hbmBack member is valid or must be filled.
RBBIM_CHILD | The hwndChild member is valid or must be filled.
RBBIM_CHILDSIZE | The cxMinChild and cyMinChild members are valid or must be filled.
RBBIM_COLORS | The clrFore and clrBack members are valid or must be filled.
RBBIM_IDEALSIZE | The cxIdeal member is valid or must be filled.
RBBIM_ID | The wID member is valid or must be filled.
RBBIM_IMAGE | The iImage member is valid or must be filled.
RBBIM_LPARAM | The lParam member is valid or must be filled.
RBBIM_SIZE | The cx member is valid or must be filled.
RBBIM_STYLE | The fStyle member is valid or must be filled.
RBBIM_TEXT | The lpText member is valid or must be filled.

fStyle
Flags that specify the band style. It can be a combination of the following values:
Value
Description
RBBS_BREAK | The band is on a new line.
RBBS_CHILDEDGE | The band has an edge at the top and bottom of the child window.
RBBS_FIXEDBMP | The background bitmap does not move when the band is resized.
RBBS_FIXEDSIZE | The band cannot be sized. With this style, the sizing grip is not displayed on the band.
RBBS_GRIPPERALWAYS | The band will always have sizing grip, even if it is the only band in the rebar.
RBBS_HIDDEN | The band will not be visible.
RBBS_NOVERT | The band is not displayed when the rebar control uses the CCS_VERT style.
RBBS_VARIABLEHEIGHT | The band can be resized by the rebar control. cyIntegral and cyMaxChild affect how the rebar will resize the band.

clrFore and clrBack
Band foreground and background colors. If hbmBack specifies a background bitmap, these members are ignored.
lpText
Long pointer to a buffer that contains the display text for the band. If band information is being requested from the control and RBBIM_TEXT is specified in fMask, this member must be initialized to the address of the buffer that will receive the text.
cch
Size of the buffer at lpText, in bytes. If information is not being requested from the control, this member is ignored.
iImage
Zero-based index of any image that should be displayed in the band, if any. The image list is set using the RB_SETBARINFO message.
hwndChild
Handle to the child window contained in the band, if any.
cxMinChild
Minimum length of the child window, in pixels. The band cannot be sized smaller than this value.
cyMinChild
Minimum thickness of the child window, in pixels. The band cannot be sized smaller than this value.
cx
Length of the band, in pixels.
hbmBack
Handle to a bitmap that is used as the background for this band.
wID
Unsigned integer that the control uses to identify this band for Custom Draw notification messages. This value may be used for additional purposes in the future.
cyChild
Initial height of the band, in pixels. This member is ignored unless the RBBS_VARIABLEHEIGHT style is specified.
cyMaxChild
Maximum height of the band, in pixels. This member is ignored unless the RBBS_VARIABLEHEIGHT style is specified.
cyIntegral
Specifies the step value by which the band can grow or shrink, in pixels. If the band is resized, it will be resized in steps specified by this value. This member is ignored unless the RBBS_VARIABLEHEIGHT style is specified.
cxIdeal
Specifies the ideal width of the band, in pixels. If the band is maximized to the ideal width (see RB_MAXIMIZEBAND), the rebar control will attempt to make the band this width.
lParam
Specifies a 32-bit application-defined value.

Remarks

The cxMinChild, cyMinChild, and cx members provide information on dimensions relative to the orientation of the control. That is, for a horizontal rebar control, cxMinChild and cx are horizontal measurements and cyMinChild is a vertical measurement. However, if the control uses the CCS_VERT style, cxMinChild and cx are vertical measurements and cyMinChild is a horizontal measurement.


REBARINFO

This structure contains information that describes rebar control characteristics.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagREBARINFO{
 UINT cbSize;
 UINT fMask;
 HIMAGELIST himl;
} REBARINFO, FAR *LPREBARINFO;

Members

cbSize
Size of this structure, in bytes. Your application must fill this member before sending any messages that use the address of this structure as a parameter.
fMask
Flag values that describe characteristics of the rebar control. Currently, rebar controls support only one value.
Value
Description
RBIM_IMAGELIST The himl member is valid or must be filled.

himl
Handle to an image list. The rebar control will use the specified image list to obtain images.


RECONVERTSTRING

This structure defines the strings for IME reconversion. It is the first item in a memory block that contains the strings for reconversion.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagRECONVERTSTRING {
 DWORD dwSize;
DWORD dwVersion;
DWORD dwStrLen;
DWORD dwStrOffset;
DWORD dwCompStrLen;
DWORD dwCompStrOffset;
DWORD dwTargetStrLen;
DWORD dwTargetStrOffset;
} RECONVERTSTRING, *PRECONVERTSTRING, NEAR *NPRECONVERTSTRING, FAR *LPRECONVERTSTRING;

Members

dwSize
Specifies the size of this structure and the memory block it heads.
dwVersion
Specifies the version number. Must be zero.
dwStrLen
Specifies the length of the string that contains the composition string.
dwStrOffset
Specifies the offset from the start position of this structure.
dwCompStrLen
Specifies the length of the string that will be the composition string.
dwCompStrOffset
Specifies the offset of the string that will be the composition string.
dwTargetStrLen
Specifies the length of the string that is related to the target clause in the composition string.
dwTargetStrOffset
Specifies the offset of the target string.


REGISTERWORD

This structure contains reading information or a word to register. You can pass this structure to the ImmConfigureIME function to have the information or word appear as an initial value in the configuration dialog box of the input method editor.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagREGISTERWORD {
 LPTSTR lpReading;
LPTSTR lpWord;
} REGISTERWORD;

Members

lpReading
Long pointer to the reading information for the word to register. If the reading information is not needed, it can be NULL.
lpWord
Long pointer to the word to register. If a word is not needed, it can be NULL.


RGBQUAD

This structure describes a color consisting of relative intensities of red, green, and blue.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagRGBQUAD {
BYTE rgbBlue;
 BYTE rgbGreen;
 BYTE rgbRed;
 BYTE rgbReserved;
} RGBQUAD;

Members

rgbBlue
Specifies the intensity of blue in the color.
rgbGreen
Specifies the intensity of green in the color.
rgbRed
Specifies the intensity of red in the color.
rgbReserved
Reserved; set to zero.

Remarks

Windows CE does not support the rgbReserved member. It should be initialized to zero.

The bmiColors member of the BITMAPINFO structure consists of an array of RGBQUAD structures.

See Also

CreateDIBSection


RGBTRIPLE

This structure describes a color consisting of relative intensities of red, green, and blue. The bmciColors member of the BITMAPCOREINFO structure consists of an array of RGBTRIPLE structures.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagRGBTRIPLE {
BYTE rgbtBlue;
BYTE rgbtGreen;
BYTE rgbtRed;
} RGBTRIPLE;

Members

rgbtBlue
Specifies the intensity of blue in the color.
rgbtGreen
Specifies the intensity of green in the color.
rgbtRed
Specifies the intensity of red in the color.

See Also

BITMAPCOREHEADER, BITMAPCOREINFO


RGNDATA

This structure contains a header and an array of rectangles that comprise a region. The rectangles are sorted top to bottom, left to right. They do not overlap.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RGNDATA {
RGNDATAHEADER rdh;
char Buffer[1];
} RGNDATA;

Members

rdh
Specifies a RGNDATAHEADER structure. The members of this structure specify the type of region (whether it is rectangular or trapezoidal), the number of rectangles that make up the region, the size of the buffer that contains the rectangle structures, and so on.
Buffer
Specifies an arbitrary-size buffer that contains the RECT structures that make up the region.

See Also

RECT, RGNDATAHEADER


RGNDATAHEADER

This structure describes the data returned by the GetRegionData function.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RGNDATAHEADER {
DWORD dwSize;
DWORD iType;
DWORD nCount;
DWORD nRgnSize;
RECT rcBound;
} RGNDATAHEADER;

Members

dwSize
Specifies the size, in bytes, of the header.
iType
Specifies the type of region. This value must be RDH_RECTANGLES.
nCount
Specifies the number of rectangles that make up the region.
nRgnSize
Specifies the size of the buffer required to receive the RECT structure that specifies the coordinates of the rectangles that make up the region. If the size is not known, this member can be zero.
rcBound
Specifies a bounding rectangle for the region.

See Also

GetRegionData, RECT, RGNDATA


SPLBUFFER

This structure contains information about a spelling session. An application uses this structure to specify the text for the spelling checker to process, and the spelling checker uses this structure to return misspelled words and suggested corrections.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagSPLBUFFER{
const WCHAR * pwszIn;
 WCHAR * pwszOut;
 SPLSUGGEST aspl[8];
 DWORD iwcIn;
 DWORD cwcIn;
 DWORD dwMode;
 DWORD cwcOut;
 DWORD cwcUsed;
 DWORD dwErr;
 DWORD iwcErr;
 DWORD cwcErr;
 DWORD cspl;
} SPLBUFFER, *PSPLBUFFER;

Members

pwszIn
Pointer to the beginning of the input buffer, which contains the text to be processed.
pwszOut
Pointer to the output buffer, which the spelling checker fills with suggestions. Each suggested word is a null-terminated string. A second NULL character indicates the end of the suggestion list. When the application calls the SplEnumUserDict function, the output buffer contains up to eight words from the specified user dictionary.
aspl
Array of eight SPLSUGGEST structures that specify pointers to spelling checker suggestions and the score for each suggestion. The pwsz member of SPLSUGGEST points to a single suggestion, which is a null-terminated string in pwszOut. The nScore member of SPLSUGGEST specifies the suggestion’s score. The spelling checker can provide up to eight suggestions and scores for each misspelled word.
iwcIn
Index that specifies a number of characters offset from pwzIn. Use iwcIn for context checking. The iwcIn member specifies to the spelling checker a number of characters preceding the first word to be checked. For example, the correctness of the first word to be processed can depend on the word that precedes it
cwcIn
Size, in characters, of the input buffer relative to pwszIn.
dwMode
Specifies the processing mode. It is one of the following flags:
Value
Description
SPL_NO_STATE_INFO | The input buffer has an arbitrary starting point. This mode occurs when the user selects a portion of a document to check instead of an entire document.
SPL_IS_CONTINUED | After the user requests that the spelling checker ignore an error, the spelling checker continues to process the text in the input buffer.
SPL_IS_EDITED_CHANGE | The input buffer has changed because a mistake was corrected. The result is a signal to an application to carefully resume processing because of the potential of entering a loop where the spelling checker becomes stuck on a word that it determines to be incorrect.
SPL_STARTS_SENTENCE | The input buffer starts at the beginning of a sentence. This mode typically occurs when processing starts at the beginning of the input buffer.

cwcOut
Size, in characters, of the output buffer.
cwcUsed
Portion of the output buffer, in characters, that the suggestions utilize. This value includes the NULL character that terminates each suggestion.
dwErr
Specifies the error or result of the spell checking. It is one of the following flags:
Value
Description
SPL_OK | The spelling checker reached the end of the input buffer and found no more errors.
SPL_ERROR_CAPITALIZATION | The word should be capitalized.
SPL_INITIAL_NUMERAL | The word begins with a numeral.
SPL_MORE_INFO_THAN_BUFFER_CAN_HOLD | The output buffer is not large enough to hold all the suggestions.
SPL_NO_MORE_SUGGESTIONS | There are no more suggestions for the misspelled word.
SPL_REPEAT_WORD | The word occurs consecutively in the buffer.
SPL_RETURNING_AUTO_REPLACE | The spelling checker returned a word that automatically replaces the misspelled word.
SPL_RETURNING_CHANGE_ALWAYS | The spelling checker returned a word that is in the change always internal user dictionary.
SPL_RETURNING_CHANGE_ONCE | The spelling checker returned a word that is in the change once internal user dictionary.
SPL_UNKNOWN_INPUT_WORD | The word is not in any of the dictionaries.
SPL_WORD_CONSIDERED_ABBREVIATION | The word is probably an abbreviation, but the spelling checker indicates the word is an error nevertheless.
SPL_UNKNOWN_ERROR | The error is not known.

iwcErr
Index of the location of the error relative to the beginning of the input buffer, which pwszIn points to. The iwcErr member specifies the number of characters in the input buffer that precede the error.
cwcErr
Length of the word containing the error. A possible use of this value is to specify a single word to check with an inline spelling checker with an automatic replacement feature.
cspl
Number of suggestions that the spelling checker provides in the output buffer.

Remarks

The SplCheck, SplSuggest, and SplReplace functions use this structure to track a spelling session. A spelling session is created by the SplInit function and ended by the SplQuit function. SplCheck causes the spelling checker to process the input buffer. SplSuggest causes the spelling checker to provide suggestions in the output buffer. SplReplace offers a suggestion that an application can use to automatically replace a misspelled word. An application can use this function to implement an inline spelling checker with an automatic replacement feature.

The SplEnumUserDict function uses the output buffer to enumerate user dictionaries so that an application can display dictionary contents to a user.

See Also

SplCheck, SplEnumUserDict, SplInit, SplQuit, SplReplace, SplSuggest, SPLSUGGEST


SPLSUGGEST

This structure contains a pointer to a word that the spelling checker suggests as a correction for a misspelled word. This structure optionally provides a score for the suggested word to indicate the probability that the suggestion is correct.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagSPLSUGGEST{
WCHAR * pwsz;
 DWORD nScore;
} SPLSUGGEST, *PSPLSUGGEST;

Members

pwsz
Pointer to a single suggested word in the output buffer for the spelling checker. The pwszOut member of the SPLBUFFER structure points to the beginning of this output buffer.
nScore
Score of the word that pwsz points to. The spelling checker can provide this score, which indicates the likelihood of the word being correct.

Remarks

An application calls the SplSuggest function to receive up to eight suggested words from the spelling checker, which then puts these words in the output buffer pointed to by the pwszOut member of the SPLBUFFER structure. The pwsz member of SPLSUGGEST points to a single word in the output buffer.

SPLSUGGEST is the data type for the aspl member of the SPLBUFFER structure.

To get a score for each suggested word, set the SPL_SCORE_SUGGESTIONS flag using the SplOptionSet function. When this flag is not set, nScore is not valid.

See Also

SPLBUFFER, SplLimitSet, SplOptionSet, SplSuggest


STYLEBUF

This structure contains the identifier and name of a style.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _tagSTYLEBUF {
 DWORD dwStyle;
 CHAR szDescription[32];
} STYLEBUF;

Members

dwStyle
Specifies the style of the register string. Can be IME_REGWORD_STYLE_EUDC to indicate a string in the EUDC range.
szDescription

Null-terminated string that contains the description of the style.


TBADDBITMAP

This structure adds a bitmap that contains button images to a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct {
HINSTANCE hInst;
UINT nID;
} TBADDBITMAP, *LPTBADDBITMAP;

Members

hInst
Handle to the module instance with the executable file that contains a bitmap resource. You can add the system-defined button bitmaps to the list by specifying HINST_COMMCTRL as the hInst member and one of the following values as the nID member:
Value
Description
IDB_STD_LARGE_COLOR | Adds large, color standard bitmaps.
IDB_STD_SMALL_COLOR | Adds small, color standard bitmaps.
IDB_VIEW_LARGE_COLOR | Adds large, color view bitmaps.
IDB_VIEW_SMALL_COLOR | Adds small, color view bitmaps.

nID
Resource identifier of the bitmap resource that contains the button images. If hInst is NULL, this parameter must be the handle to a bitmap that contains the button images.

The Windows header files provide the following values to be used as indexes to the standard and view bitmaps:
Value
Description
STD_COPY | Specifies the copy image.
STD_CUT | Specifies the cut image.
STD_DELETE | Specifies the delete image.
STD_FILENEW | Specifies the new file image.
STD_FILEOPEN | Specifies the open file image.
STD_FILESAVE | Specifies the save file image.
STD_FIND | Specifies the find image.
STD_HELP | Specifies the help image.
STD_PASTE | Specifies the paste image.
STD_PRINT | Specifies the print image.
STD_PRINTPRE | Specifies the print preview image.
STD_PROPERTIES | Specifies the properties image.
STD_REDOW | Specifies the redo image.
STD_REPLACE | Specifies the replace image.
STD_UNDO | Specifies the undo image.
VIEW_DETAILS | Specifies the view details image.
VIEW_LARGEICONS | Specifies the view large icons image.
VIEW_LIST | Specifies the view list image.
VIEW_SMALLICONS | Specifies the view small icons image.
VIEW_SORTDATE | Specifies the sort by date image.
VIEW_SORTNAME | Specifies the sort by name image.
VIEW_SORTSIZE | Specifies the sort by size image.
VIEW_SORTTYPE | Specifies the sort by type image.

Remarks

The TBADDBITMAP structure is used with the TB_ADDBITMAP message.


TBBUTTON

This structure contains information about a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TBBUTTON {
int iBitmap;
int idCommand;
BYTE fsState;
BYTE fsStyle;
DWORD dwData;
int iString;
} TBBUTTON, NEAR* PTBBUTTON, FAR* LPTBBUTTON;
typedef const TBBUTTON FAR* LPCTBBUTTON;

Members

iBitmap
Zero-based index of the button image.
idCommand
Command identifier associated with the button. This identifier is used in a WM_COMMAND message when the button is chosen.
fsState
Button state flags. It can be a combination of the values listed in Toolbar Button States.
fsStyle
Button style. It can be a combination of the button style values listed in Toolbar Control Button Styles.
dwData
Specifies an application-defined value.
iString
Zero-based index of the button string.

See Also

WM_COMMAND


TBBUTTONINFO

This structure contains or receives information for a specific button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
 UINT cbSize;
 DWORD dwMask;
 int idCommand;
 int iImage;
 BYTE fsState;
 BYTE fsStyle;
 WORD cx;
 DWORD lParam;
 LPTSTR pszText;
 int cchText;
} TBBUTTONINFOA, *LPTBBUTTONINFOA;

Members

cbSize
Size of the structure, in bytes. This member must be filled in prior to sending the associated message.
dwMask
Indicates which members contain valid information. This member must be filled in prior to sending the associated message. This can be a combination of one or more of the following values:
Value
Description
TBIF_COMMAND | The idCommand member contains valid information or is being requested.
TBIF_IMAGE | The iImage member contains valid information or is being requested.
TBIF_LPARAM | The lParam member contains valid information or is being requested.
TBIF_SIZE | The cx member contains valid information or is being requested.
TBIF_STATE | The fsState member contains valid information or is being requested.
TBIF_STYLE | The fsStyle member contains valid information or is being requested.
TBIF_TEXT | The pszText member contains valid information or is being requested.

idCommand
Command identifier of the button.
iImage
Image index of the button.
fsState
State flags of the button. This is a combination of one or more of the toolbar button states.
fsStyle
Style flags of the button. This is a combination of one or more of the toolbar button styles.
cx
Specifies the width of the button, in pixels.
lParam
Specifies the application defined 32-bit value associated with the button.
pszText
Pointer to a character buffer that contains or receives the button text.
cchText
Size of the buffer at pszText. If the button information is being set, this member is ignored.


TBNOTIFY

This structure contains information used to process notification messages from a toolbar, and is superseded by the NMTOOLBAR structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct_TBNOTIFY {
NMHDR hdr;
INT iItem;
TBBUTTON tbButton;
INT cchText;
LPTSTR pszText;
} TBNOTIFY, FAR* LPTBNOTIFY;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iItem
Command identifier of the button associated with the notification.
tbButton
TBBUTTON structure that contains information about the toolbar button associated with the notification.
cchText
Count of characters in the button text.
pszText
Pointer to a character buffer that contains the button text.

See Also

WM_NOTIFY


TBREPLACEBITMAP

This structure is used with the TB_REPLACEBITMAP message to replace one toolbar bitmap with another.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
 HINSTANCE hInstOld;
 UINT nIDOld;
 HINSTANCE hInstNew;
 UINT nIDNew;
 int nButtons;
} TBREPLACEBITMAP, *LPTBREPLACEBITMAP;

Members

hInstOld
Module instance handle of the bitmap resource being replaced.
nIDOld
Resource identifier of the bitmap being replaced.
hInstNew
Module instance handle that contains the new bitmap resource.
nIDNew
Resource identifier of the new bitmap.
nButtons
Number of button images contained in the new bitmap.


TC_HITTESTINFO

This structure contains information about a hit test, and is superseded by the TCHITTESTINFO structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TC_HITTESTINFO {
POINT pt;
UINT flags;
} TC_HITTESTINFO;

Members

pt
Position to hit test, in client coordinates.
flags
Receives the results of a hit test. The tab control sets this member to one of the following values:
Value
Description
TCHT_NOWHERE | The position is not over a tab.
TCHT_ONITEM | The position is over a tab but not over its icon or its text. For owner-drawn tab controls, this value is specified if the position is anywhere over a tab.
TCHT_ONITEMICON | The position is over a tab’s icon.
TCHT_ONITEMLABEL | The position is over a tab’s text.

TCHT_ONITEM is a bitwise-OR operation on TCHT_ONITEMICON and TCHT_ONITEMLABEL.

See Also

TCM_HITTEST


TC_ITEM

This structure specifies or receives the attributes of a tab, and is superseded by the TCITEM structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TC_ITEM {
UINT mask;
UINT lpReserved1;
UINT lpReserved2;
LPSTR pszText;
int cchTextMax;
int iImage;
LPARAM lParam;
} TC_ITEM;

Members

mask
Specifies which members to retrieve or set. It can be a combination of the following values:
Value
Description
TCIF_IMAGE | The iImage member is valid.
TCIF_PARAM | The lParam member is valid.
TCIF_RTLREADING | The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.
TCIF_STATE | Version 4.70. The dwState member is valid.
TCIF_TEXT | The pszText member is valid.

dwState
Version 4.70. Specifies the item’s current state if information is being retrieved. If item information is being set, this member contains the state value to be set for the item. For a list of valid tab control item states, see Tab Control Item States. This member is ignored in the TCM_INSERTITEM message.
dwStateMask
Version 4.70. Specifies which bits of the dwState member contain valid information. This member is ignored in the TCM_INSERTITEM message.
lpReserved1
Version 4.00. Not used.
lpReserved2
Version 4.00. Not used.
pszText
Pointer to a null-terminated string that contains the tab text when item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index in the tab control’s image list, or –1 if there is no image for the tab.
lParam
Application-defined data associated with the tab control item. If more or less than 4 bytes of application-defined data exist per tab, an application must define a structure and use it instead of the TC_ITEM structure. The first member of the application-defined structure must be a TCITEMHEADER structure.

See Also

TCM_GETITEM,TCM_INSERTITEM, TCM_SETITEM


TC_ITEMHEADER

This structure specifies or receives the attributes of a tab, and is superseded by the TCITEMHEADER structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TC_ITEMHEADER {
UINT mask;
UINT lpReserved1;
UINT lpReserved2;
LPSTR pszText;
int cchTextMax;
int iImage;
} TC_ITEMHEADER;

Members

mask
Specifies which members to retrieve or set. It can be a combination of the following values:
Value
Description
TCIF_IMAGE | The iImage member is valid.
TCIF_RTLREADING | The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.
TCIF_TEXT | The pszText member is valid.

lpReserved1
Reserved; do not use.
lpReserved2
Reserved; do not use.
pszText
Pointer to a null-terminated string that contains the tab text if item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index into the tab control’s image list, or –1 if there is no image for the tab.

Remarks

This structure is the same as the TC_ITEM structure, except that it does not include an lParam member for application-defined data.

See Also

TC_ITEM, TCM_SETITEMEXTRA


TC_KEYDOWN

This structure contains information about a key press in a tab control, and is superseded by the NMTCKEYDOWN structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TC_KEYDOWN {
NMHDR hdr;
WORD wVKey;
UINT flags;
} TC_KEYDOWN;

Members

hdr
NMHDR structure that contains information about the notification message.
wVKey
Virtual key code.
flags
Value that is identical to the lParam parameter of the WM_KEYDOWN message.

See Also

TCN_KEYDOWN


TCITEM

This structure specifies or receives the attributes of a tab item. It is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagTCITEM {
UINT mask;
 DWORD dwState;
 DWORD dwStateMask;
 LPTSTR pszText;
 int cchTextMax;
 int iImage;
 LPARAM lParam;
} TCITEM;

Members

mask
Specifies which members to retrieve or set. It can be a combination of the following values:
Value
Description
TCIF_IMAGE | The iImage member is valid.
TCIF_PARAM | The lParam member is valid.
TCIF_RTLREADING | The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.
TCIF_STATE | The dwState member is valid.
TCIF_TEXT | The pszText member is valid.

dwState
Specifies the item’s current state if information is being retrieved. If item information is being set, this member contains the state value to be set for the item. For a list of valid tab control item states, see Tab Control Item States.
dwStateMask
Specifies which bits of the dwState member are valid.
pszText
Pointer to a null-terminated string that contains the tab text when item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
CchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index into the tab control’s image list, or -1 if there is no image for the tab.
lParam
Application-defined data associated with the tab control item. If more or less than 4 bytes of application-defined data exist per tab, an application must define a structure and use it instead of the TCITEM structure. The first member of the application-defined structure must be a TCITEMHEADER structure.

Remarks

This structure supersedes the TC_ITEM structure.


TCITEMHEADER

This structure specifies or receives the attributes of a tab. It is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagTCITEMHEADER{
 UINT mask;
 UINT lpReserved1;
 UINT lpReserved2;
 LPTSTR pszText;
 int cchTextMax;
 int iImage;
} TCITEMHEADER, FAR *LPTCITEMHEADER;

Members

mask
Specifies which members to retrieve or set. It can be a combination of the following values:
Value
Description
TCIF_IMAGE | The iImage member is valid.
TCIF_RTLREADING | The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.
TCIF_TEXT | The pszText member is valid.

lpReserved1
Reserved; do not use.
lpReserved2
Reserved; do not use.
pszText
Pointer to a null-terminated string that contains the tab text if item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index into the tab control’s image list, or –1 if there is no image for the tab.

Remarks

This structure supersedes the TC_ITEMHEADER structure.


TEXTMETRIC

This structure contains basic information about a physical font.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagTEXTMETRIC {
 LONG tmHeight;
LONG tmAscent;
LONG tmDescent;
LONG tmInternalLeading;
LONG tmExternalLeading;
LONG tmAveCharWidth;
LONG tmMaxCharWidth;
LONG tmWeight;
LONG tmOverhang;
LONG tmDigitizedAspectX;
LONG tmDigitizedAspectY;
char tmFirstChar;
char tmLastChar;
char tmDefaultChar;
char tmBreakChar;
BYTE tmItalic;
BYTE tmUnderlined;
BYTE tmStruckOut;
BYTE tmPitchAndFamily;
BYTE tmCharSet;
} TEXTMETRIC;

Members

tmHeight
Specifies the height (ascent + descent) of characters.
tmAscent
Specifies the ascent (units above the base line) of characters.
tmDescent
Specifies the descent (units below the base line) of characters.
tmInternalLeading
Specifies the amount of leading (space) inside the bounds set by the tmHeight member. Accent marks and other diacritical characters may occur in this area. The designer may set this member to zero.
tmExternalLeading
Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls in either OPAQUE or TRANSPARENT mode. The designer may set this member to zero.
tmAveCharWidth
Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include the overhang required for bold or italic characters.
tmMaxCharWidth
Specifies the width of the widest character in the font.
tmWeight
Specifies the weight of the font.
tmOverhang
Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

tmDigitizedAspectX
Specifies the horizontal aspect of the device for which the font was designed.
tmDigitizedAspectY
Specifies the vertical aspect of the device for which the font was designed. The ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the aspect ratio of the device for which the font was designed.
tmFirstChar
Specifies the value of the first character defined in the font.
tmLastChar
Specifies the value of the last character defined in the font.
tmDefaultChar
Specifies the value of the character to be substituted for characters not in the font.
tmBreakChar
Specifies the value of the character that will be used to define word breaks for text justification.
tmItalic
Specifies an italic font if it is nonzero.
tmUnderlined
Specifies an underlined font if it is nonzero.
tmStruckOut
Specifies a strikeout font if it is nonzero.
tmPitchAndFamily
Specifies information about the pitch, the technology, and the family of a physical font.

The four low-order bits of this member specify information about the pitch and the technology of the font. A constant is defined for each of the four bits:
Value
Description
TMPF_FIXED_PITCH | If this bit is set the font is a variable pitch font. If this bit is clear the font is a fixed pitch font. Note that those meanings are the opposite of what the constant name implies.
TMPF_VECTOR | If this bit is set, the font is a vector font.
TMPF_TRUETYPE | If this bit is set, the font is a TrueType font.
TMPF_DEVICE | If this bit is set, the font is a device font.

An application should carefully test for qualities encoded in these low-order bits, making no arbitrary assumptions. For example, besides having their own bits set, TrueType and PostScript fonts set the TMPF_VECTOR bit. A monospace bitmap font has all of these low-order bits clear; a proportional bitmap font sets the TMPF_FIXED_PITCH bit. A Postscript printer device font sets the TMPF_DEVICE, TMPF_VECTOR, and TMPF_FIXED_PITCH bits.

The four high-order bits of tmPitchAndFamily designate the font’s font family. An application can use the value 0xF0 and the bitwise AND operator to mask out the four low-order bits of tmPitchAndFamily, thus obtaining a value that can be directly compared with font family names to find an identical match. For information about font families, see the description of the LOGFONT structure.

tmCharSet
Specifies the character set of the font. The character set is one of the following values:
ANSI_CHARSET | DEFAULT_CHARSET
SYMBOL_CHARSET | SHIFTJIS_CHARSET
HANGUL_CHARSET | GB2312_CHARSET
CHINESEBIG5_CHARSET | OEM_CHARSET
JOHAB_CHARSET | HEBREW_CHARSET
ARABIC_CHARSET | GREEK_CHARSET
TURKISH_CHARSET | VIETNAMESE_CHARSET
THAI_CHARSET | EASTEUROPE_CHARSET
RUSSIAN_CHARSET | MAC_CHARSET
BALTIC_CHARSET

See Also

GetTextMetrics, LOGFONT


TV_DISPINFO

This structure contains and retrieves ‹6/30, a-laurha: “retrieves and sets” is the CE purpose statement; “contains and retrieves” was the Win32 purpose statement; which is correct?and sets ›information about a tree view item. This structure is identical to the NMTVDISPINFO structure, but was renamed to follow standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TV_DISPINFO {
NMHDR hdr;
TV_ITEM item;
} TV_DISPINFO;

Members

hdr
NMHDR structure that contains information about this notification message.
item
TV_ITEM structure that identifies and contains information about the tree view item. The mask member of the TV_ITEM structure specifies which information is being set or retrieved. It can be one or more of the following values:
Value
Description
TVIF_CHILDREN | The cChildren member specifies, or is to receive, a value that indicates whether the item has child items.
TVIF_IMAGE | The iImage member specifies, or is to receive, the index of the item’s nonselected icon in the image list.
TVIF_SELECTEDIMAGE | The iSelectedImage member specifies, or is to receive, the index of the item’s selected icon in the image list.
TVIF_TEXT | The pszText member specifies the new item text or the address of a buffer that is to receive the item text.
If the structure is receiving item text, you typically copy the text to the buffer pointed to by the pszText member of the TV_ITEM structure. However, you can return a string in the pszText member instead. If you do so, you cannot change or delete the string until the corresponding item text is deleted or until two additional TVN_GETDISPINFO notification messages have been sent.

See Also

TVN_SETDISPINFO, WM_NOTIFY


TV_HITTESTINFO

This structure contains information used to determine the location of a point relative to a tree view control. This structure is identical to the TVHITTESTINFO structure, but was renamed to follow standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TVHITTESTINFO {
POINT pt;
UINT flags;
HTREEITEM hItem;
} TV_HITTESTINFO, FAR *LPTV_HITTESTINFO;

Members

pt
Client coordinates of the point to test.
flags
Receives information about the results of a hit test. It can be one or more of the following values:
Value
Description
TVHT_ABOVE | Above the client area.
TVHT_BELOW | Below the client area.
TVHT_NOWHERE | In the client area, but below the last item.
TVHT_ONITEM | On the bitmap or label associated with an item.
TVHT_ONITEMBUTTON | On the button associated with an item.
TVHT_ONITEMICON | On the bitmap associated with an item.
TVHT_ONITEMINDENT | In the indentation associated with an item.
TVHT_ONITEMLABEL | On the label (string) associated with an item.
TVHT_ONITEMRIGHT | In the area to the right of an item.
TVHT_ONITEMSTATEICON | On the state icon for a tree view item that is in a user-defined state.
TVHT_TOLEFT | To the left of the client area.
TVHT_TORIGHT | To the right of the client area.

hItem
Handle to the item that occupies the point.

See Also

TVM_HITTEST


TV_INSERTSTRUCT

This structure contains information used to add a new item to a tree view control. This structure is identical to the TVINSERTSTRUCT structure, but was renamed to follow standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TV_INSERTSTRUCT {
HTREEITEM hParent;
HTREEITEM hInsertAfter;
TV_ITEM item;
} TV_INSERTSTRUCT, FAR *LPTV_INSERTSTRUCT;

Members

hParent
Handle to the parent item. If this member is the TVI_ROOT value or NULL, the item is inserted at the root of the tree view control.
hInsertAfter
Handle to the item after which the new item is to be inserted, or one of the following values:
Value
Description
TVI_FIRST | Inserts the item at the beginning of the list.
TVI_LAST | Inserts the item at the end of the list.
TVI_SORT | Inserts the item into the list in alphabetical order.

item
TV_ITEM structure that contains information about the item to add.

See Also

TVM_INSERTITEM


TV_ITEM

This structure specifies or receives attributes of a tree view item. This structure is identical to the TVITEM structure, but was renamed to follow standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TV_ITEM { tvi
UINT mask;
HTREEITEM hItem;
UINT st ate;
UINT stateMask;
LPSTR pszText;
int cchTextMax;
int iImage;
int iSelectedImage;
int cChildren;
LPARAM lParam;
} TV_ITEM, FAR *LPTV_ITEM;

Members

mask
Indicates which of the other structure members contain valid data. When this structure is used with the TVM_GETITEM message, the mask member indicates the item attributes to retrieve. This member can be one or more of the following values:
Value
Description
TVIF_CHILDREN | The cChildren member is valid.
TVIF_HANDLE | The hItem member is valid.
TVIF_IMAGE | The iImage member is valid.
TVIF_PARAM | The lParam member is valid.
TVIF_SELECTEDIMAGE | The iSelectedImage member is valid.
TVIF_STATE | The state and stateMask members are valid.
TVIF_TEXT | The pszText and cchTextMax members are valid.

hItem
Handle to the item to which this structure refers.
state
Set of bit flags and image list indexes that indicate the item’s state. When setting the state of an item, the stateMask member indicates the bits of this member that are valid. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member.

Bits 0 through 7 of this member contain the item state flags. For a list of possible item state flags, see Tree View Control Item States.

Bits 8 through 11 of this member specify the one-based overlay image index. The overlay image is superimposed over the item’s icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK mask. To set the overlay image index in this member, you should use the INDEXTOOVERLAYMASK macro. The image list’s overlay images are set with the ImageList_SetOverlayImage function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item’s icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the TVIS_STATEIMAGEMASK mask. To set the state image index, you should use the INDEXTOSTATEIMAGEMASK macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the TVM_SETIMAGELIST message.

stateMask
Bits of the state member that are valid. If you are retrieving an item’s state, set the bits of the stateMask member to indicate the bits to be returned in the state member. If you are setting an item’s state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item’s overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item’s state image index, set the TVIS_STATEIMAGEMASK bits.
pszText
Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree view control sends the parent window a TVN_GETDISPINFO notification message when it needs the item text for displaying, sorting, or editing and a TVN_SETDISPINFO notification message when the item text changes.

If the structure is receiving item attributes, this member is the address of the buffer that receives the item text.

cchTextMax
Size of the buffer pointed to by the pszText member, in characters. If this structure is being used to set item attributes, this member is ignored.
iImage
Index in the tree view control’s image list of the icon image to use when the item is in the nonselected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree view control sends the parent a TVN_GETDISPINFO notification message to get the index when it needs to display the image.

iSelectedImage
Index in the tree view control’s image list of the icon image to use when the item is in the selected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree view control sends the parent a TVN_GETDISPINFO notification message to get the index when it needs to display the image.

cChildren
Indicates whether the item has associated child items. It is one of the following values:
Value
Description
0 | The item has no child items.
1 | The item has one or more child items.
I_CHILDRENCALLBACK | The parent window keeps track of whether the item has child items. In this case, when the tree view control needs to display the item, the control sends the parent a TVN_GETDISPINFO notification message to determine whether the item has child items.
If the tree view control has the TVS_HASBUTTONS style, it uses this member to determine whether to display the button indicating the presence of child items. You can use this member to force the control to display the button even though the item does not have any child items inserted. This allows you to display the button while minimizing the control’s memory usage by inserting child items only when the item is visible or expanded.

lParam
Specifies a 32-bit value to associate with the item.

See Also

TVM_INSERTITEM, TVM_SETITEM


TV_KEYDOWN

This structure contains information about a keyboard event in a tree view control. This structure is identical to the NMTVKEYDOWN structure, but was renamed to follow standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TV_KEYDOWN {
NMHDR hdr;
WORD wVKey;
UINT flags;
} TV_KEYDOWN;

Members

hdr
NMHDR structure that contains information about this notification message.
wVKey
Virtual key code.
flags
Set to zero.

See Also

TVN_KEYDOWN, WM_NOTIFY


TV_SORTCB

This structure contains information used to sort child items in a tree view control. This structure is identical to the TVSORTCB structure, but was renamed to follow standard naming conventions.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TV_SORTCB { tvscb
HTREEITEM hParent;
PFNTVCOMPARE lpfnCompare;
LPARAM lParam;
} TV_SORTCB, FAR *LPTV_SORTCB;

Members

hParent
Handle to the parent item.
lpfnCompare
Long pointer to an application-defined callback function, which is called during a sort operation each time the relative order of two list items needs to be compared. The callback function has the following form:
int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
 LPARAM lParamSort);

The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters of the callback function correspond to the lParam member of the TV_ITEM structure for the two items being compared. The lParamSort member corresponds to the lParam member of TV_SORTCB.

lParam
Application-defined 32-bit value that gets passed as the lParamSort parameter in the callback function specified in lpfnCompare.

See Also

TVM_SORTCHILDRENCB


WAVEFORMATEX

This structure defines the format of waveform-audio data. Only format information common to all waveform-audio data formats is included in this structure. For formats that require additional information, this structure is included as the first member in another structure, along with the additional information.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
WORD wFormatTag;
WORD nChannels;
DWORD nSamplesPerSec;
DWORD nAvgBytesPerSec;
WORD nBlockAlign;
WORD wBitsPerSample;
WORD cbSize;
} WAVEFORMATEX;

Members

wFormatTag
Waveform-audio format type. Format tags are registered with Microsoft Corporation for many compression algorithms. A complete list of format tags can be found in the Mmsystem.h header file.
nChannels
Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels.
nSamplesPerSec
Sample rate, in samples per second (hertz), that each channel should be played or recorded. If wFormatTag is WAVE_FORMAT_PCM, then common values for nSamplesPerSec are 8.0 kHz, 11.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, this member must be computed according to the manufacturer’s specification of the format tag.
nAvgBytesPerSec
Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is WAVE_FORMAT_PCM, nAvgBytesPerSec should be equal to the product of nSamplesPerSec and nBlockAlign. For non-PCM formats, this member must be computed according to the manufacturer’s specification of the format tag.

Playback and record software can estimate buffer sizes by using the nAvgBytesPerSec member.

nBlockAlign
Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, nBlockAlign should be equal to the product of nChannels and wBitsPerSample divided by 8 (bits per byte). For non-PCM formats, this member must be computed according to the manufacturer’s specification of the format tag.

Playback and record software must process a multiple of nBlockAlign bytes of data at a time. Data written and read from a device must always start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).

wBitsPerSample
Bits per sample for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, then wBitsPerSample should be equal to 8 or 16. For non-PCM formats, this member must be set according to the manufacturer’s specification of the format tag. Note that some compression schemes cannot define a value for wBitsPerSample, so this member can be zero.
cbSize
Size, in bytes, of extra format information appended to the end of the WAVEFORMATEX structure. This information can be used by non-PCM formats to store extra attributes for the wFormatTag. If no extra information is required by the wFormatTag, this member must be set to zero. For WAVE_FORMAT_PCM formats only, this member is ignored.

Remarks

An example of a format that uses extra information is the Microsoft Adaptive Delta Pulse Code Modulation (MS-ADPCM) format. The wFormatTag for MS-ADPCM is WAVE_FORMAT_ADPCM. The cbSize member is typically set to 32. The extra information stored for WAVE_FORMAT_ADPCM is coefficient pairs required for encoding and decoding the waveform-audio data.


WAVEHDR

This structure defines the header used to identify a waveform-audio buffer.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
LPSTR lpData;
DWORD dwBufferLength;
DWORD dwBytesRecorded;
DWORD dwUser;
DWORD dwFlags;
DWORD dwLoops;
struct wavehdr_tag *lpNext;
DWORD reserved;
} WAVEHDR;

Members

lpData
Long pointer to the address of the waveform buffer.
dwBufferLength
Specifies the length, in bytes, of the buffer.
dwBytesRecorded
When the header is used in input, this member specifies how much data is in the buffer.
dwUser
Specifies user data.
dwFlags
Specifies information about the buffer. It is one of the following flags:
Value
Description
WHDR_BEGINLOOP | This buffer is the first buffer in a loop. This flag is used only with output buffers.
WHDR_DONE | Set by the device driver to indicate that it is finished with the buffer and is returning it to the application.
WHDR_ENDLOOP | This buffer is the last buffer in a loop. This flag is used only with output buffers.
WHDR_INQUEUE | Set by Windows to indicate that the buffer is queued for playback.
WHDR_PREPARED | Set by Windows to indicate that the buffer has been prepared with the waveInPrepareHeader or waveOutPrepareHeader function.

dwLoops
Specifies the number of times to play the loop. This member is used only with output buffers.
wavehdr_tag
Reserved.
reserved
Reserved.

Remarks

Use the WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the dwFlags member to specify the beginning and ending data blocks for looping. To loop on a single block, specify both flags for the same block. Use the dwLoops member in the WAVEHDR structure for the first block in the loop to specify the number of times to play the loop.

The lpData, dwBufferLength, and dwFlags members must be set before calling the waveInPrepareHeader or waveOutPrepareHeader function. For either function, the dwFlags member must be set to zero.


WAVEINCAPS

This structure describes the capabilities of a waveform-audio input device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
WORD wMid;
WORD wPid;
MMVERSION vDriverVersion;
CHAR szPname[MAXPNAMELEN];
DWORD dwFormats;
WORD wChannels;
WORD wReserved1;
} WAVEINCAPS;

Members

wMid
Manufacturer identifier for the device driver for the waveform-audio input device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.
wPid
Product identifier for the waveform-audio input device. Product identifiers are defined in Manufacturer and Product Identifiers.
vDriverVersion
Version number of the device driver for the waveform-audio input device. The high-order byte is the major version number, and the low-order byte is the minor version number.
szPname
Null-terminated string that contains the product name.
dwFormats
Specifies the standard formats that are supported. It is one or a combination of the following flags:
Flag
Description
WAVE_FORMAT_1M08 | 11.025 kHz, mono, 8-bit
WAVE_FORMAT_1M16 | 11.025 kHz, mono, 16-bit
WAVE_FORMAT_1S08 | 11.025 kHz, stereo, 8-bit
WAVE_FORMAT_1S16 | 11.025 kHz, stereo, 16-bit
WAVE_FORMAT_2M08 | 22.05 kHz, mono, 8-bit
WAVE_FORMAT_2M16 | 22.05 kHz, mono, 16-bit
WAVE_FORMAT_2S08 | 22.05 kHz, stereo, 8-bit
WAVE_FORMAT_2S16 | 22.05 kHz, stereo, 16-bit
WAVE_FORMAT_4M08 | 44.1 kHz, mono, 8-bit
WAVE_FORMAT_4M16 | 44.1 kHz, mono, 16-bit
WAVE_FORMAT_4S08 | 44.1 kHz, stereo, 8-bit
WAVE_FORMAT_4S16 | 44.1 kHz, stereo, 16-bit

wChannels
Number that specifies whether the device supports mono (1) or stereo (2) input.
wReserved1
Padding.


WAVEOUTCAPS

This structure describes the capabilities of a waveform-audio output device.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
WORD wMid;
WORD wPid;
MMVERSION vDr iverVersion;
CHAR szPname[MAXPNAMELEN];
DWORD dwFormats;
WORD wChannels;
WORD wReserved1;
DWORD dwSupport;
} WAVEOUTCAPS;

Members

wMid
Manufacturer identifier for the device driver for the device. Manufacturer identifiers are defined in Manufacturer and Product Identifiers.
wPid
Product identifier for the device. Product identifiers are defined in Manufacturer and Product Identifiers.
vDriverVersion
Version number of the device driver for the device. The high-order byte is the major version number, and the low-order byte is the minor version number.
szPname
Null-terminated string that contains the product name.
dwFormats
Specifies the standard formats that are supported. It is one or a combination of the following flags:
Flag
Description
WAVE_FORMAT_1M08 | 11.025 kHz, mono, 8-bit
WAVE_FORMAT_1M16 | 11.025 kHz, mono, 16-bit
WAVE_FORMAT_1S08 | 11.025 kHz, stereo, 8-bit
WAVE_FORMAT_1S16 | 11.025 kHz, stereo, 16-bit
WAVE_FORMAT_2M08 | 22.05 kHz, mono, 8-bit
WAVE_FORMAT_2M16 | 22.05 kHz, mono, 16-bit
WAVE_FORMAT_2S08 | 22.05 kHz, stereo, 8-bit
WAVE_FORMAT_2S16 | 22.05 kHz, stereo, 16-bit
WAVE_FORMAT_4M08 | 44.1 kHz, mono, 8-bit
WAVE_FORMAT_4M16 | 44.1 kHz, mono, 16-bit
WAVE_FORMAT_4S08 | 44.1 kHz, stereo, 8-bit
WAVE_FORMAT_4S16 | 44.1 kHz, stereo, 16-bit

wChannels
Number specifying whether the device supports mono (1) or stereo (2) output.
wReserved1
Packing.
dwSupport
Specifies the optional functionality supported by the device. It is one of the following flags:
Value
Description
WAVECAPS_LRVOLUME | Supports separate left and right volume control.
WAVECAPS_PITCH | Supports pitch control.
WAVECAPS_PLAYBACKRATE | Supports playback rate control.
WAVECAPS_SYNC | The driver is synchronous and blocks while playing a buffer.
WAVECAPS_VOLUME | Supports volume control.
WAVECAPS_SAMPLEACCURATE | Returns sample-accurate position information.

Remarks

If a device supports volume changes, the WAVECAPS_VOLUME flag is set for the dwSupport member. If a device supports separate volume changes on the left and right channels, both the WAVECAPS_VOLUME and the WAVECAPS_LRVOLUME flags are set for this member.


WNDCLASS

This structure contains the window class attributes that are registered by the RegisterClass function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _WNDCLASS {
 UINT style;
WNDPROC lpfnWndProc;
int cbClsExtra;
int cbWndExtra;
HANDLE hInstance;
HICON hIcon;
HCURSOR hCursor;
HBRUSH hbrBackground;
LPCTSTR lpszMenuName;
LPCTSTR lpszClassName;
} WNDCLASS;

Members

style
Specifies the class style(s). Styles can be combined by using the bitwise OR (|) operator. This member can be any combination of the following values:
Value
Description
CS_BYTEALIGNCLIENT | Aligns the window’s client area on the byte boundary (in the x direction). This style affects the width of the window and its horizontal position on the display.
CS_BYTEALIGNWINDOW | Aligns a window on a byte boundary (in the x direction). This style affects the width of the window and its horizontal position on the display.
CS_CLASSDC | Allocates one device context to be shared by all windows in the class. Because window classes are process specific, it is possible for multiple threads of an application to create a window of the same class. It is also possible for the threads to attempt to use the device context simultaneously. When this happens, the system allows only one thread to successfully finish its drawing operation.
CS_DBLCLKS | Sends double-click messages to the window procedure when the user double-clicks the mouse while the cursor is within a window belonging to the class.
CS_GLOBALCLASS | Allows an application to create a window of the class regardless of the value of the hInstance parameter passed to the CreateWindow or CreateWindowEx function. If you do not specify this style, the hInstance member passed to the CreateWindow (or CreateWindowEx) function must be the same as the hInstance member passed to the RegisterClass function.
You can create a global class by creating the window class in a dynamic-link library (DLL) and listing the name of the DLL in the registry under the following keys:
HKEY_LOCAL_MACHINE\Software
\Microsoft\Windows NT\
CurrentVersion\Windows\AppInit_DLLs
Whenever a process starts, the system loads the specified DLLs in the context of the newly started process before calling the entry-point function in that process. The DLL must register the class during its initialization procedure and must specify the CS_GLOBALCLASS style.
CS_HREDRAW | Redraws the entire window if a movement or size adjustment changes the width of the client area.
CS_NOCLOSE | Disables Close on the window menu.
CS_OWNDC | Allocates a unique device context for each window in the class.
CS_PARENTDC | Sets the clipping region of the child window to that of the parent window so that the child can draw on the parent. A window with the CS_PARENTDC style bit receives a regular device context from the system’s cache of device contexts. It does not give the child the parent’s device context or device context settings. Specifying CS_PARENTDC enhances an application’s performance.
CS_SAVEBITS | Saves, as a bitmap, the portion of the screen image obscured by a window. The system uses the saved bitmap to re-create the screen image when the window is removed. The system displays the bitmap at its original location and does not send WM_PAINT messages to windows obscured by the window if the memory used by the bitmap has not been discarded and if other screen actions have not invalidated the stored image. This style is useful for small windows (for example, menus or dialog boxes) that are displayed briefly and then removed before other screen activity takes place. This style increases the time required to display the window, because the system must first allocate memory to store the bitmap.
CS_VREDRAW | Redraws the entire window if a movement or size adjustment changes the height of the client area.

lpfnWndProc
Long pointer to the window procedure. You must use the CallWindowProc function to call the window procedure. For more information, see WindowProc.
cbClsExtra
Specifies the number of extra bytes to allocate following the window-class structure. The system initializes the bytes to zero.
cbWndExtra
Specifies the number of extra bytes to allocate following the window instance. The system initializes the bytes to zero. If an application uses WNDCLASS to register a dialog box created by using the CLASS directive in the resource file, it must set this member to DLGWINDOWEXTRA.
hInstance
Handle to the instance that the window procedure of this class is within.
hIcon
Handle to the class icon. This member must be a handle to an icon resource. If this member is NULL, an application must draw an icon whenever the user minimizes the application’s window.
hCursor
Handle to the class cursor. This member must be a handle to a cursor resource. If this member is NULL, an application must explicitly set the cursor shape whenever the mouse moves into the application’s window.
hbrBackground
Handle to the class background brush. This member can be a handle to the physical brush to be used for painting the background, or it can be a color value. A color value must be one of the following standard system colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following HBRUSH types:
COLOR_ACTIVEBORDER | COLOR_HIGHLIGHTTEXT
COLOR_ACTIVECAPTION | COLOR_INACTIVEBORDER
COLOR_APPWORKSPACE | COLOR_INACTIVECAPTION
COLOR_BACKGROUND | COLOR_MENU
COLOR_BTNFACE | COLOR_MENUTEXT
COLOR_BTNSHADOW | COLOR_SCROLLBAR
COLOR_BTNTEXT | COLOR_WINDOW
COLOR_CAPTIONTEXT | COLOR_WINDOWFRAME
COLOR_GRAYTEXT | COLOR_WINDOWTEXT
COLOR_HIGHLIGHT

The system automatically deletes class background brushes when the class is freed. An application should not delete these brushes, because a class may be used by multiple instances of an application.

When this member is NULL, an application must paint its own background whenever it is requested to paint in its client area. To determine whether the background must be painted, an application can either process the WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint function.

lpszMenuName
Long pointer to a null-terminated character string that specifies the resource name of the class menu, as the name appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If this member is NULL, windows belonging to this class have no default menu.
lpszClassName
Either a long pointer to a null-terminated string or an atom. If this member is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be in the low-order word of lpszClassName; the high-order word must be zero.

If lpszClassName is a string, it specifies the window class name.

Remarks

The following members are restricted.

  • cbClsExtra must be a multiple of four.
  • cbWndExtra must be a multiple of four.
  • Unless you’re using the Windows CE Iconcurs component, which supports mouse cursors on appropriate target platforms, the hCursor member must be set to NULL.
  • lpszMenuName is not supported and must be NULL.
  • lpszClassName must be a string. Atoms are not supported.
  • In Windows CE 1.0, the style member must either contain the CS_DBLCLKS value or NULL.
  • In Windows CE versions 2.0 and later, the style member can accept the following values as well.
    • CS_GLOBALCLASS
    • CS_HREDRAW
    • CS_NOCLOSE
    • CS_PARENTDC
    • CS_VREDRAW

In Windows CE, all window classes are process global. The CS_GLOBALCLASS value is included to provide source level compatibility with applications that are also compiled under other versions of Windows.

Note The technique of putting a class name and DLL in the registry and having a DLL automatically loaded is not supported.

See Also

BeginPaint, CreateWindow, CreateWindowEx, GetDC, MAKEINTRESOURCE, PAINTSTRUCT, RegisterClass, WindowProc, WM_PAINT


BM_CLICK

This message is sent by an application to simulate the user clicking a button. This message causes the button to receive a WM_LBUTTONDOWN and a WM_LBUTTONUP message, and the button's parent window to receive a BN_CLICKED notification message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BM_CLICK wParam = 0; lParam = 0;

Return Values

None.

Remarks

If the button is in a dialog box and the dialog box is not active, the BM_CLICK message might fail. To ensure success in this situation, call the SetActiveWindow function to activate the dialog box before sending the BM_CLICK message to the button.

See Also

BN_CLICKED, WM_LBUTTONDOWN, WM_LBUTTONUP


BM_GETCHECK

This message is sent by an application to retrieve the check state of a radio button or check box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BM_GETCHECK wParam = 0; lParam = 0;

Return Values

A button created with the BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE returns one of the values described in the following table.

Value
Description
BST_CHECKED | Button is checked.
BST_INDETERMINATE | Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).
BST_UNCHECKED | Button is unchecked

If the button has any other style, the return value is zero.

See Also

BM_GETSTATE, BM_SETCHECK


BM_GETSTATE

This message is sent by an application to determine the state of a button or check box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BM_GETSTATE wParam = 0; lParam = 0;

Return Values

The return value specifies the current state of the button. Use the following bitmasks to extract information about the state:

Value
Description
0x0003 | Specifies the check state (radio buttons and check boxes only). A value of BST_UNCHECKED indicates the button is unchecked; a value of BST_CHECKED indicates the button is checked. A radio button is checked when it contains a dot; a check box is checked when it contains an X. A value of BST_INDETERMINATE indicates the check state is indeterminate (applies only if the button has the BS_3STATE or BS_AUTO3STATE style). A three-state check box is grayed when its state is indeterminate.
BST_CHECKED | Indicates the button is checked.
BST_FOCUS | Specifies the focus state. A nonzero value indicates that the button has the keyboard focus.
BST_INDETERMINATE | Indicates the button is grayed because the state of the button is indeterminate. This value applies only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_PUSHED | Specifies the highlight state. A nonzero value indicates that the button is highlighted. A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.
BST_UNCHECKED | Indicates the button is unchecked. Same as a return value of zero.

See Also

BM_GETCHECK, BM_SETSTATE


BM_SETCHECK

This message is sent by an application to set the check state of a radio button or check box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BM_SETCHECK wParam = (WPARAM) fCheck, lParam = 0;

Parameters

fCheck
Specifies the check state. It is one of the following values:
Value
Description
BST_CHECKED | Sets the button state to checked.
BST_INDETERMINATE | Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_UNCHECKED | Sets the button state to unchecked.

Return Values

This message always returns zero.

Remarks

The BM_SETCHECK message has no effect on push buttons.

See Also

BM_GETCHECK, BM_GETSTATE, BM_SETSTATE


BM_SETSTATE

This message is sent by an application to change the highlight state of a button.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BM_SETSTATE wParam = (WPARAM) fState; lParam = 0;

Parameters

fState
Boolean that specifies whether the button is to be highlighted. A value of TRUE highlights the button. A value of FALSE removes any highlighting.

Return Values

This message always returns zero.

Remarks

Highlighting only affects the appearance of a button. It has no effect on the check state of a radio button or check box.

A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

See Also

BM_GETSTATE, BM_SETCHECK


BM_SETSTYLE

This message is sent by an application to change the style of a button.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BM_SETSTYLE wParam = (WPARAM) LOWORD (dwStyle),
lParam = MAKELPARAM (fRedraw, 0)

Parameters

dwStyle
Value of wParam. Specifies the new button style. This parameter can be a combination of button styles. For information about button styles, see the Windows CE User Interface Services Guide.
fRedraw
Value of the low-order word of lParam. Boolean that specifies whether the button is to be redrawn. A value of TRUE redraws the button; a value of FALSE does not redraw the button.

Return Values

This message always returns zero.

Remarks

The following button styles are not supported:

  • BS_PUSHBOX
  • BS_USERBUTTON


BN_CLICKED

This message is sent when the user taps the pen on the touch screen. The parent window of the button receives this notification message through the WM_COMMAND message. Unlike the other button notification messages, this message is intended for applications written for any version of Windows.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BN_CLICKED idButton = (int)LOWORD(wParam);
hwndButton = (HWND) lParam;

Parameters

idButton
Identifier of the button.
hwndButton
Handle to the button.

Remarks

A disabled button does not send a BN_CLICKED notification message to its parent window.

See Also

WM_COMMAND


BN_KILLFOCUS

This notification message is sent when a button loses the keyboard focus. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BN_KILLFOCUS

See Also

BN_SETFOCUS, WM_COMMAND


BN_PAINT

This notification message is sent when a button should be painted. The parent window of the button receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BN_PAINT

Remarks

This notification message is provided for compatibility with applications written for 16-bit versions of Windows earlier than version 3.0. Win32-based applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_SETFOCUS

This notification message is sent when a button receives the keyboard focus. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BN_SETFOCUS

See Also

BN_KILLFOCUS, WM_COMMAND


CB_ADDSTRING

This message is sent by an application to add a string to the list box of a combo box. If the combo box does not have the CBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list, and the list is sorted.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_ADDSTRING wParam = 0, lParam = (LPARAM)(LPCSTR) lpsz

Parameters

lpsz
Long pointer to the null-terminated string to be added. If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data rather than the string it would otherwise point to. The item data can be retrieved or modified by sending the CB_GETITEMDATA or CB_SETITEMDATA message.

Return Values

The zero-based index to the string in the list box of the combo box indicates success. CB_ERR indicates that an error has occurred. CB_ERRSPACE indicates that insufficient space is available to store the new string.

Remarks

If you create an owner-drawn combo box with the CBS_SORT style but without the CBS_HASSTRINGS style, the WM_COMPAREITEM message is sent one or more times to the owner of the combo box so the new item can be properly placed in the list.

To insert a string at a specific location within the list, use the CB_INSERTSTRING message.

See Also

CB_INSERTSTRING, WM_COMPAREITEM


CB_DELETESTRING

This message is sent by an application to delete a string in the list box of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_DELETESTRING wParam = (WPARAM) index, lParam = 0

Parameters

index
Specifies the zero-based index of the string to delete.

Return Values

A count of the strings remaining in the list indicates success. CB_ERR indicates that the index parameter specifies an index greater than the number of items in the list.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the system sends a WM_DELETEITEM message to the owner of the combo box so the application can free any additional data associated with the item.

See Also

CB_RESETCONTENT, WM_DELETEITEM


CB_FINDSTRING

This message is sent by an application to search the list box of a combo box for an item beginning with the characters in a specified string.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_FINDSTRING wParam = (WPARAM) indexStart,
lParam = (LPARAM)(LPCSTR) lpszFind

Parameters

indexStart
Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is –1, the entire list box is searched from the beginning.
lpszFind
Long pointer to the null-terminated string that contains the prefix to search for. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The zero-based index of the matching item indicates success. CB_ERR indicates an unsuccessful search.

Remarks

This message does not work across processes. You can not make the call SendMessage(CB_FINDSTRING) to another process.

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRING message does depends on whether your application uses the CBS_SORT style. If you use the CBS_SORT style, WM_COMPAREITEM messages are sent to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, the CB_FINDSTRING message searches for a list item that matches the value of the lpszFind parameter.

See Also

CB_FINDSTRINGEXACT, CB_SELECTSTRING, CB_SETCURSEL, WM_COMPAREITEM


CB_FINDSTRINGEXACT

This message is sent by an application to find the first list box string in a combo box that matches the string specified in the lpszFind parameter.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_FINDSTRINGEXACT wParam = (WPARAM) indexStart,
lParam = (LPARAM)(LPCSTR) lpszFind

Parameters

indexStart
Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is –1, the entire list box is searched from the beginning.
lpszFind
Long pointer to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The zero-based index of the matching item indicates success. CB_ERR indicates an unsuccessful search.

Remarks

This message does not work across processes. You can not make the call SendMessage(CB_FINDSTRINGEXACT) to another process.

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRINGEXACT message does depends on whether your application uses the CBS_SORT style. If you use the CBS_SORT style, WM_COMPAREITEM messages are sent to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, the CB_FINDSTRINGEXACT message searches for a list item that matches the value of the lpszFind parameter.

See Also

CB_FINDSTRING, CB_SELECTSTRING, WM_COMPAREITEM


CB_GETCOUNT

This message is sent by an application to retrieve the number of items in the list box of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETCOUNT wParam = 0; lParam = 0;

Return Values

The number of items in the list box indicates success. CB_ERR indicates that an has occurred.

Remarks

The index is zero-based, so the returned count is one greater than the index value of the last item.


CB_GETCURSEL

This message is sent by an application to retrieve the index of the currently selected item, if any, in the list box of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETCURSEL wParam = 0; lParam = 0;

Return Values

The zero-based index of the currently selected item indicates success. CB_ERR indicates that no item is selected.

See Also

CB_SELECTSTRING, CB_SETCURSEL


CB_GETDROPPEDCONTROLRECT

This message is sent by an application to retrieve the screen coordinates of the drop-down list box of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETDROPPEDCONTROLRECT wParam = 0,
lParam = (LPARAM)(RECT FAR*) lprc

Parameters

lprc
Long pointer to the RECT structure that is to receive the coordinates.

Return Values

1 indicates success. CB_OKAY (0) indicates failure.


CB_GETDROPPEDSTATE

This message is sent by an application to determine whether the list box of a combo box is dropped down.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETDROPPEDSTATE wParam = 0; lParam = 0;

Return Values

TRUE indicates that the list box is visible. FALSE indicates otherwise.

See Also

CB_SHOWDROPDOWN


CB_GETDROPPEDWIDTH

This message is sent by an application to retrieve the minimum allowable width, in pixels, of the list box of a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETDROPPEDWIDTH wParam = 0; lParam = 0;

Return Values

The width, in pixels, indicates success. CB_ERR indicates failure.

Remarks

By default, the minimum allowable width of the drop-down list box is 0. The width of the list box is either the minimum allowable width or the combo box width, whichever is larger.

See Also

CB_SETDROPPEDWIDTH


CB_GETEDITSEL

This message is sent by an application to get the starting and ending character positions of the current selection in the edit control of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETEDITSEL wParam = (WPARAM)(LPDWORD) lpdwStart,
lParam = (LPARAM)(LPDWORD) lpdwEnd

Parameters

lpdwStart
Long pointer to a 32-bit value that receives the starting position of the selection. This parameter can be set to NULL.
lpdwEnd
Long pointer to a 32-bit value that receives the ending position of the selection. This parameter can be set to NULL.

Return Values

The return value is a zero-based 32-bit value with the starting position of the selection in the low-order word and with the ending position of the first character after the last selected character in the high-order word.

See Also

CB_SETEDITSEL


CB_GETEXTENDEDUI

This message is sent by an application to determine whether a combo box has the default user interface or the extended user interface.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETEXTENDEDUI wParam = 0; lParam = 0;

Return Values

TRUE indicates that the combo box has the extended user interface, the return value is TRUE. FALSE indicates otherwise.

Remarks

By default, the F4 key opens or closes the list and the DOWN ARROW key changes the current selection. In a combo box with the extended user interface, the F4 key is disabled and pressing the DOWN ARROW key opens the drop-down list.

See Also

CB_SETEXTENDEDUI


CB_GETHORIZONTALEXTENT

This message is sent by an application to retrieve from a combo box the width, in pixels, by which the list box can be scrolled horizontally (the scrollable width). This is applicable only if the list box has a horizontal scroll bar.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETHORIZONTALEXTENT wParam = 0; lParam = 0;

Return Values

The scrollable width, in pixels, indicates success.

See Also

CB_SETHORIZONTALEXTENT


CB_GETITEMDATA

This message is sent by an application to a combo box to retrieve the application-supplied 32-bit value associated with the specified item in the combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETITEMDATA wParam = (WPARAM) index, lParam = 0

Parameters

index
Specifies the zero-based index of the item.

Return Values

The 32-bit value associated with the item indicates success. CB_ERR indicates that an error has occurred.

If the item is in an owner-drawn combo box created without the CBS_HASSTRINGS style, the return value is the 32-bit value contained in the lParam parameter of the CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo box. If the CBS_HASSTRINGS style was not used, the return value is the lParam parameter contained in a CB_SETITEMDATA message.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA


CB_GETITEMHEIGHT

This message is sent by an application to determine the height of list items or the selection field in a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETITEMHEIGHT wParam = (WPARAM) index, lParam = 0

Parameters

index
Specifies the combo box component whose height is to be retrieved.

This parameter must be –1 to retrieve the height of the selection field. It must be zero to retrieve the height of list items, unless the combo box has the CBS_OWNERDRAWVARIABLE style. In that case, the index parameter is the zero-based index of a specific list item.

Return Values

The height, in pixels, of the list items in a combo box indicates success. If the combo box has the CBS_OWNERDRAWVARIABLE style, it is the height of the item specified by the index parameter. If index is –1, the return value is the height of the edit control (or static-text) portion of the combo box. If an error occurs, the return value is CB_ERR.

See Also

CB_SETITEMHEIGHT, WM_MEASUREITEM


CB_GETLBTEXT

This message is sent by an application to retrieve a string from the list of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETLBTEXT wParam = (WPARAM) index;
lParam = (LPARAM)(LPCSTR) lpszBuffer;

Parameters

index
Specifies the zero-based index of the string to retrieve.
lpszBuffer
Long pointer to the buffer that receives the string. The buffer must have sufficient space for the string and a terminating null character. You can send a CB_GETLBTEXTLEN message prior to the CB_GETLBTEXT message to retrieve the length, in bytes, of the string.

Return Values

The length of the string, in bytes and excluding the terminating null character, indicates success. CB_ERR indicates that the index parameter does not specify a valid index.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter of the message receives the 32-bit value associated with the item (the item data).

See Also

CB_GETLBTEXTLEN


CB_GETLBTEXTLEN

This message is sent by an application to retrieve the length, in characters, of a string in the list of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETLBTEXTLEN wParam = (WPARAM) index; lParam = 0;

Parameters

index
Specifies the zero-based index of the string.

Return Values

The length of the string, in characters and excluding the terminating null character, indicates success. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

CB_ERR indicates that the index parameter does not specify a valid index.

Remarks

Under certain conditions, the return value is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; so you can always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT


CB_GETLOCALE

This message is sent by an application to retrieve the current locale of the combo box. The locale is used to determine the correct sorting order of displayed text for combo boxes with the CBS_SORT style and text added by using the CB_ADDSTRING message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

CB_GETLOCALE wParam = 0; lParam = 0;

Return Values

The return value is a 32-bit value that specifies the current locale of the combo box. The high word contains the country code and the low-order word contains the language identifier.

Remarks

The language identifier is made up of a sublanguage identifier and a primary language identifier. The PRIMARYLANGID macro obtains the primary language identifier and the SUBLANGID macro obtains the sublanguage identifier.

See Also

CB_ADDSTRING, CB_SETLOCALE, PRIMARYLANGID, SUBLANGID


CB_GETTOPINDEX

This message is sent by an application to retrieve the zero-based index of the first visible item in the list box portion of a combo box. Initially the item with index zero is at the top of the list box, but if the list box contents have been scrolled, another item may be at the top.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_GETTOPINDEX wParam = 0; lParam = 0;

Return Values

The index of the first visible item in the list box of the combo box indicates success. CB_ERR indicates failure.

See Also

CB_SETTOPINDEX


CB_INITSTORAGE

This message is sent by an application before adding a large number of items to the list box portion of a combo box. This message allocates memory for storing list box items.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_INITSTORAGE wParam = (WPARAM)(int) cItems;
lParam = (LPARAM)(DWORD) cb;

Parameters

cItems
Specifies the number of items to add.
cb
Specifies the amount of memory to allocate for item strings, in bytes.

Return Values

The total number of items for which memory has been pre-allocated—that is, the total number of items added by all successful CB_INITSTORAGE messages—indicates success. CB_ERRSPACE indicates failure.

Windows NT: For Windows NT version 4.0, this message does not allocate the specified amount of memory; however, it always returns the value specified in the cItems parameter. For Windows NT version 5.0, the message allocates memory and returns the success and error values described above.

Remarks

The lParam parameter is unused in Windows CE.

The CB_INITSTORAGE message helps speed up the initialization of combo boxes that have a large number of items (over 100). It reserves the specified amount of memory so that subsequent CB_ADDSTRING, CB_INSERTSTRING, and CB_DIR messages take the shortest possible time. You can use estimates for the cItems and cb parameters. If you overestimate, the extra memory is allocated, if you underestimate, the normal allocation is used for items that exceed the requested amount.

See Also

CB_ADDSTRING , CB_INSERTSTRING


CB_INSERTSTRING

This message is sent by an application to insert a string into the list box of a combo box. Unlike the CB_ADDSTRING message, the CB_INSERTSTRING message does not cause a list with the CBS_SORT style to be sorted.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_INSERTSTRING wParam = (WPARAM) index;
lParam = (LPARAM)(LPCSTR) lpsz;

Parameters

index
Specifies the zero-based index of the position at which to insert the string. If this parameter is –1, the string is added to the end of the list.
lpsz
Long pointer to the null-terminated string to be inserted. If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the value of the lpsz parameter is stored rather than the string it would otherwise point to.

Return Values

The index of the position at which the string was inserted indicates success. CB_ERR indicates that an error has occurred. CB_ERRSPACE indicates that there is insufficient space available to store the new string.

See Also

CB_ADDSTRING


CB_LIMITTEXT

This message is sent by an application to limit the length of the text the user may type into the edit control of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_LIMITTEXT wParam = (WPARAM) cchLimit; lParam = 0;

Parameters

cchLimit
Specifies the maximum number of characters the user can enter. If this parameter is zero, the text length is set to 0x7FFFFFFE characters.

Return Values

The return value is always TRUE.

Remarks

If the combo box does not have the CBS_AUTOHSCROLL style, setting the text limit to be larger than the size of the edit control has no effect.

The CB_LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control when a string in the list box is selected.

The default limit to the text a user can enter in the edit control is 30,000 characters.


CB_RESETCONTENT

This message is sent by an application to remove all items from the list box and edit control of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_RESETCONTENT wParam = 0; lParam = 0;

Return Values

This message always returns CB_OKAY.

Remarks

The Microsoft Platform SDK documentation says this message always returns CB_OKAY (0). This is inaccurate. This message always returns TRUE.

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the owner of the combo box receives a WM_DELETEITEM message for each item in the combo box.

See Also

CB_DELETESTRING, WM_DELETEITEM


CB_SELECTSTRING

This message is sent by an application to search the list of a combo box for an item that begins with the characters in a specified string. If a matching item is found, it is selected and copied to the edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SELECTSTRING wParam = (WPARAM) indexStart;
lParam = (LPARAM)(LPCSTR) lpszSelect;

Parameters

indexStart
Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list, it continues from the top of the list back to the item specified by the indexStart parameter. If indexStart is –1, the entire list is searched from the beginning.
lpszSelect
Long pointer to the null-terminated string that contains the prefix to search for. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The index of the selected item indicates that the string has been found. CB_ERR indicates an unsuccessful search; the current selection is not changed.

Remarks

Windows CE does not support owner draw.

A string is selected only if the characters from the starting point match the characters in the prefix string.

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_SELECTSTRING message does depends on whether you use the CBS_SORT style. If the CBS_SORT style is used, the system sends WM_COMPAREITEM messages to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, CB_SELECTSTRING attempts to match the DWORD value against the value of the lpszSelect parameter.

See Also

CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_SETCURSEL, WM_COMPAREITEM


CB_SETCURSEL

This message is sent by an application to select a string in the list of a combo box. If necessary, the list scrolls the string into view. The text in the edit control of the combo box changes to reflect the new selection and any previous selection in the list is removed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETCURSEL wParam = (WPARAM) index; lParam = 0;

Parameters

index
Specifies the zero-based index of the string to select. If the index parameter is –1, any current selection in the list is removed and the edit control is cleared.

Return Values

The index of the item selected indicates success. CB_ERR indicates that index is greater than the number of items in the list or if index is set to –1; the selection is cleared.

See Also

CB_FINDSTRING, CB_GETCURSEL, CB_SELECTSTRING


CB_SETDROPPEDWIDTH

This message is sent by an application to set the maximum allowable width, in pixels, of the list box of a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETDROPPEDWIDTH wParam = (WPARAM) wWidth, lParam = 0,

Parameters

wWidth
Specifies the width of the list box, in pixels.

Return Values

The new width of the list box indicates success. CB_ERR indicates failure.

Remarks

By default, the minimum allowable width of the drop-down list box is 0. The width of the list box is either the minimum allowable width or the combo box width, whichever is larger.

See Also

CB_GETDROPPEDWIDTH


CB_SETEDITSEL

This message is sent by an application to select characters in the edit control of a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETEDITSEL wParam = 0; lParam = MAKELPARAM(ichStart, ichEnd);

Parameters

ichStart
Value of the low-order word of lParam. Specifies the starting position. If this parameter is set to –1, the selection, if any, is removed.
ichEnd
Value of the high-order word of lParam. Specifies the ending position. If this parameter is set to –1, all text from the starting position to the last character in the edit control is selected.

Return Values

TRUE indicates success. CB_ERR indicates that the message is sent to a combo box with the CBS_DROPDOWNLIST style.

Remarks

The positions are zero-based. The first character of the edit control is in the zero position. The first character after the last selected character is in the ending position. For example, to select the first four characters of the edit control, use a starting position of 0 and an ending position of 4.

See Also

CB_GETEDITSEL


CB_SETEXTENDEDUI

This message is sent by an application to select either the default user interface or the extended user interface for a combo box that has the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETEXTENDEDUI wParam = (WPARAM)(BOOL) fExtended;
lParam = 0;

Parameters

fExtended
Boolean that specifies whether the combo box uses the extended user interface or the default user interface. A value of TRUE selects the extended user interface; a value of FALSE selects the standard user interface.

Return Values

CB_OKAY indicates success. CB_ERR indicates that an error has occurred.

Remarks

By default, the F4 key opens or closes the list and the DOWN ARROW changes the current selection. In the extended user interface, the F4 key is disabled and the DOWN ARROW key opens the drop-down list.

See Also

CB_GETEXTENDEDUI


CB_SETHORIZONTALEXTENT

This message is sent by an application to set the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden or, if the combo box has the CBS_DISABLENOSCROLL style, disabled.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETHORIZONTALEXTENT wParam = (WPARAM) cxExtent;
lParam = 0;

Parameters

cxExtent
Specifies the scrollable width of the list box, in pixels.

Return Values

None.

See Also

CB_GETHORIZONTALEXTENT


CB_SETITEMDATA

This message is sent by an application to set the 32-bit value associated with the specified item in a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETITEMDATA wParam = (WPARAM) index;
lParam = (LPARAM)(DWORD) dwData;

Parameters

index
Specifies the item’s zero-based index.
dwData
Specifies the new value to be associated with the item.

Return Values

CB_ERR indicates that an error has occurred.

Remarks

Windows CE does not support owner draw combo boxes.

If the specified item is in an owner-drawn combo box created without the CBS_HASSTRINGS style, this message replaces the 32-bit value in the lParam parameter of the CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo box.

See Also

CB_ADDSTRING, CB_GETITEMDATA, CB_INSERTSTRING


CB_SETITEMHEIGHT

This message is sent by an application to set the height of list items or the selection field in a combo box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETITEMHEIGHT wParam = (WPARAM) index;
lParam = (LPARAM)(int) height;

Parameters

index
Specifies the component of the combo box for which to set the height.

This parameter must be –1 to set the height of the selection field. It must be zero to set the height of list items, unless the combo box has the CBS_OWNERDRAWVARIABLE style. In that case, the index parameter is the zero-based index of a specific list item.

height
Specifies the height, in pixels, of the combo box component identified by index.

Return Values

CB_ERR indicates that the index or height is invalid.

Remarks

Windows CE does not support owner drawn combo boxes.

The selection field height in a combo box is set independently of the height of the list items. An application must ensure that the height of the selection field is not smaller than the height of a particular list item.

See Also

CB_GETITEMHEIGHT, WM_MEASUREITEM


CB_SETLOCALE

This message is sent by an application to set the current locale of the combo box. If the combo box has the CBS_SORT style and strings are added using CB_ADDSTRING, the locale of a combo box affects how list items are sorted.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

CB_SETLOCALE
wParam = (WPARAM) (WORD) wLocaleID;
lParam = 0;

Parameters

wLocaleID
Specifies the locale identifier for the combo box to use for sorting when adding text.

Return Values

The return value is the previous locale identifier. If wParam specifies a locale not installed on the system, the return value is CB_ERR and the current combo box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier and the MAKELANGID macro to construct a language identifier. The language identifier is made up of a primary language identifier and a sublanguage identifier.

See Also

CB_ADDSTRING, CB_GETLOCALE, MAKELANGID, MAKELCID


CB_SETTOPINDEX

This message is sent by an application to ensure that a particular item is visible in the list box of a combo box. The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SETTOPINDEX wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the list item.

Return Values

Zero indicates success. CB_ERR indicates failure.

See Also

CB_GETTOPINDEX


CB_SHOWDROPDOWN

This message is sent by an application to show or hide the list box of a combo box that has the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CB_SHOWDROPDOWN wParam = (WPARAM)(BOOL) fShow;
lParam = 0;

Parameters

fShow
Boolean that specifies whether the drop-down list box is to be shown or hidden. A value of TRUE shows the list box; a value of FALSE hides it.

Return Values

The return value is always TRUE.

Remarks

This message has no effect on a combo box created with the CBS_SIMPLE style.

See Also

CB_GETDROPPEDSTATE


CBN_CLOSEUP

This notification message is sent when the list box of a combo box has been closed. The parent window of the combo box receives this notification message through the WM_COMMAND message.

In general, you cannot predict the order in which notifications will be sent. In particular, a CBN_SELCHANGE notification may occur either before or after a CBN_CLOSEUP notification.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_CLOSEUP idComboBox = (int)LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

If the user changed the current selection, the combo box also sends the CBN_SELCHANGE notification when the drop-down list closes. In general, you cannot predict the order in which notifications will be sent. In particular, a CBN_SELCHANGE notification message may occur either before or after a CBN_CLOSEUP notification message.

To execute a specific process each time the user selects a list item, you can handle either the CBN_SELCHANGE or CBN_CLOSEUP notification message. Typically, you would wait for the CBN_CLOSEUP notification before processing a change in the current selection. This can be particularly important if a significant amount of processing is required.

This notification message is not sent to a combo box that has the CBS_SIMPLE style.

See Also

CBN_DROPDOWN, CBN_SELCHANGE, WM_COMMAND


CBN_DBLCLK

This notification message is sent when the user double-clicks a string in the list box of a combo box. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

CBN_DBLCLK idComboBox = (int) LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

This notification message occurs only for a combo box with the CBS_SIMPLE style. In a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style, a double-click cannot occur because a single click closes the list box.

See Also

CBN_SELCHANGE, WM_COMMAND


CBN_DROPDOWN

This notification message is sent when the list box of a combo box is about to be made visible. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_DROPDOWN idComboBox = (int)LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

This notification message can occur only for a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

See Also

CBN_CLOSEUP, WM_COMMAND


CBN_EDITCHANGE

This notification message is sent after the user has taken an action that may have altered the text in the edit control portion of a combo box. Unlike the CBN_EDITUPDATE notification message, this notification message is sent after Windows updates the screen. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_EDITCHANGE idComboBox = (int)LOWORD(wParam); hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITUPDATE, WM_COMMAND


CBN_EDITUPDATE

This notification message is sent when the edit control portion of a combo box is about to display altered text. This notification is sent after the control has formatted the text, but before it displays the text. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_EDITUPDATE idComboBox = (int)LOWORD(wParam); hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITCHANGE, WM_COMMAND


CBN_ERRSPACE

This notification message is sent when a combo box cannot allocate enough memory to meet a specific request. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_ERRSPACE idComboBox = (int)LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

See Also

WM_COMMAND


CBN_KILLFOCUS

This notification message is sent when a combo box loses the keyboard focus. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_KILLFOCUS idComboBox = (int)LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

See Also

CBN_SETFOCUS, WM_COMMAND


CBN_SELCHANGE

This notification message is sent when the selection in the list box of a combo box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys. The parent window of the combo box receives this message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_SELCHANGE idComboBox = (int)LOWORD(wParam); hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

To get the index of the current selection, send the CB_GETCURSEL message to the control.

The CBN_SELCHANGE notification message is not sent when the current selection is set using the CB_SETCURSEL message.

See Also

CBN_DBLCLK, CB_SETCURSEL, WM_COMMAND


CBN_SELENDCANCEL

This notification message is sent when the user selects an item, but then selects another control or closes the dialog box. It indicates the user’s initial selection is to be ignored. The parent window of the combo box receives this notification message through the WM_COMMAND message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDCANCEL notification message is not sent.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_SELENDCANCEL idComboBox = (int)LOWORD(wParam); hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

In a combo box with the CBS_SIMPLE style, the CBN_SELENDCANCEL notification message is not sent. The CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE notification message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDCANCEL notification message is not sent.

See Also

CBN_SELENDOK, WM_COMMAND


CBN_SELENDOK

This notification message is sent when the user clicks a list item, or selects an item and then closes the list. It indicates the user's selection is to be processed. The parent window of the combo box receives this notification message through the WM_COMMAND message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDOK notification message is not sent.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_SELENDOK idComboBox = (int)LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

Remarks

In a combo box with the CBS_SIMPLE style, the CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE notification message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDOK notification message is not sent.

See Also

CBN_SELENDCANCEL, WM_COMMAND


CBN_SETFOCUS

This notification message is sent when a combo box receives the keyboard focus. The parent window of the combo box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

CBN_SETFOCUS idComboBox = (int)LOWORD(wParam);
hwndComboBox = (HWND) lParam;

Parameters

idComboBox
Identifier of the combo box.
hwndComboBox
Handle to the combo box.

See Also

CBN_KILLFOCUS, WM_COMMAND


CDM_SETDEFEXT

This message sets the default filename extension for an Explorer-style Open or Save As common dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 1.0 and later

Syntax

CDM_SETDEFEXT wParam = 0; lParam = (LPARAM) (LPSTR) pszext;

Parameters

hdlg
Handle to the common dialog box window to receive the message.
pszext
Pointer to the null-terminated string that contains the new file name extension. Must not include a period (.).

Return Values

None.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


CDN_TYPECHANGE

This notification message is sent by an Explorer-style Open or Save As common dialog box when the user selects a new file type from the file types combo box. Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 1.0 and later

Syntax

CDN_TYPECHANGE lpon = (LPOFNOTIFY) lParam;

Parameters

lpon
Long pointer to an OFNOTIFY structure.

The OFNOTIFY structure contains an NMHDR structure whose code member indicates the CDN_TYPECHANGE notification code.

The OFNOTIFY structure also contains a pointer to an OPENFILENAME structure whose nFilterIndex member indicates the one-based index of the newly selected file type filter.

Return Values

The return value is ignored.

Remarks

The system sends this notification only if the dialog box was created using the OFN_EXPLORER value.

See Also

GetOpenFileName, GetSaveFileName, NMHDR, OFNOTIFY, OPENFILENAME, WM_NOTIFY


CPL_DBLCLK

This message is sent to a Control Panel application when the user double-clicks the icon in the control panel explorer.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Syntax

CPL_DBLCLK uAppNum = (UINT) lParam1; lData = (LONG) lParam2;

Parameters

uAppNum
Dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT –1).
lData
Value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads the lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Values

Zero indicates that the CPlApplet function processes this message successfully. Nonzero indicates otherwise.

Remarks

In response to this message, a Control Panel application must display the corresponding dialog box.

See Also

CPL_GETCOUNT, CPL_NEWINQUIRE, CPLINFO, NEWCPLINFO


CPL_EXIT

This message is sent once to a Control Panel application before the controlling application releases the DLL that contains the application.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Return Values

Zero indicates that the CPlApplet function processes this message successfully.

Remarks

This message is sent after the last CPL_STOP message is sent.

In response to this message, a Control Panel application must free any memory that it has allocated and perform global-level cleanup.

See Also

CPL_STOP


CPL_GETCOUNT

This message is sent to a Control Panel application to retrieve the number of dialog boxes supported by the application.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Return Values

The CPlApplet function returns the number of dialog boxes that the Control Panel application supports.

Remarks

This message is sent immediately after the CPL_INIT message.

See Also

CPL_INIT


CPL_INIT

This message is sent to a Control Panel application to prompt it to perform global initialization, especially memory allocation.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Return Values

If initialization succeeds, the CPlApplet function should return nonzero. Otherwise, it should return zero.

If CPlApplet returns zero, the controlling application ends communication and releases the DLL that contains the Control Panel application.

Remarks

The return value is not checked by the control panel explorer.

In Windows CE version 1.0, an error is recognized when the applet does not fill the NEWCPLINFO structure properly in response to the CPL_NEWINQUIRE message.

Because this is the only way a Control Panel application can signal an error condition, the application should allocate memory in response to this message.

This message is sent immediately after the DLL that contains the application is loaded.

See Also

FreeLibrary


CPL_NEWINQUIRE

This message is sent to a Control Panel application to request information about a dialog box that the application supports.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Syntax

CPL_NEWINQUIRE uAppNum = (UINT) lParam1;
lpncpli = (LPNEWCPLINFO) lParam2;

Parameters

uAppNum
Dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT –1).
lpncpli
Long pointer to a NEWCPLINFO structure. The Control Panel application should fill this structure with information about the dialog box.

Return Values

Zero indicates that the CPlApplet function processes this message successfully.

Remarks

The Control Panel sends the CPL_NEWINQUIRE message once for each dialog box supported by your application. The Control Panel also sends a CPL_INQUIRE message for each dialog box. These messages are sent immediately after the CPL_GETCOUNT message. However, the system does not guarantee the order in which the CPL_INQUIRE and CPL_NEWINQUIRE messages are sent.

You can perform initialization for the dialog box when you receive CPL_INQUIRE. If you must allocate memory, do so in response to the CPL_INIT message.

The CPL_NEWINQUIRE message was introduced in Windows version 3.1 as a replacement for CPL_INQUIRE. However, CPL_INQUIRE is the preferred message for Windows 95 and Windows NT version 4.0. This is because CPL_NEWINQUIRE returns information in a form that the system cannot cache. Consequently, applications that process CPL_NEWINQUIRE must be loaded each time the Control Panel needs the information, resulting in a significant reduction in performance.

The only applications that should use CPL_NEWINQUIRE are those that need to change their icon or display strings based on the state of the computer. In this case, your CPL_INQUIRE handler should specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members of the CPLINFO structure, rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings, allowing you to specify information based on the current state of the computer. Of course, this is significantly slower than using cached information.

See Also

CPL_GETCOUNT, CPL_INIT, NEWCPLINFO


CPL_STOP

This message is sent once for each dialog box when the application controlling the Control Panel application closes.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Syntax

CPL_STOP uAppNum = (UINT) lParam1; lData = (LONG) lParam2;

Parameters

uAppNum
Dialog box number.
lData
Value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads the lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Values

Zero indicates that the CPlApplet function processes this message successfully.

Remarks

In response to this message, a Control Panel application must perform cleanup for the given dialog box.

See Also

CPL_EXIT, CPL_GETCOUNT, CPL_NEWINQUIRE, NEWCPLINFO


DM_GETDEFID

This message is sent by an application to retrieve the identifier of the default push button control for a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DM_GETDEFID

Return Values

If a default push button exists, the high-order word of the return value contains the value DC_HASDEFID and the low-order word contains the control identifier. Otherwise, the return value is zero.

Remarks

The DefDlgProc function processes this message.

See Also

DefDlgProc, DM_SETDEFID


DM_SETDEFID

This message is sent by an application to change the identifier of the default push button for a dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

DM_SETDEFID wParam = idControl;

Parameters

idControl
Specifies the identifier of a push button control that becomes the default.

Return Values

The return value is always TRUE.

Remarks

This message should not be used to change the default style when doing a SetFocus to a dialog control. Use the WM_NEXTDLGCTL message instead.

This message is processed by the DefDlgProc function. To set the default push button, the function can send WM_GETDLGCODE and BM_SETSTYLE messages to the given control and the current default push button.

Using the DM_SETDEFID message can result in more than one button appearing to have the default push button state. When the system brings up a dialog, it draws the first push button in the dialog template with the default state border. Sending a DM_SETDEFID message to change the default button will not always remove the default state border from the first push button. In these cases, the application should send a BM_SETSTYLE message to change the first push button border style.

See Also

DefDlgProc, BM_SETSTYLE, DM_GETDEFID, WM_GETDLGCODE, WM_NEXTDLGCTL


DTM_ADDTEXT

This message is sent by an application to add text to the HTML control.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_ADDTEXT wParam = (WPARAM)(BOOL) bPlainText;
lParam = (LPARAM)(LPSTR) szText;

Parameters

bPlainText
Boolean that indicates the format of the text to be added. If set to TRUE, the text is treated as plain text. If set to FALSE, the text is treated as HTML formatted text.
szText
Null-terminated text string to be added to the HTML control.

Return Values

None.

See Also

DTM_ADDTEXTW


DTM_ADDTEXTW

This message is sent by an application to add Unicode text to the HTML control.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_ADDTEXT wParam = (WPARAM)(BOOL) bPlainText;
lParam = (LPARAM)(LPWSTR) szwText;

Parameters

bPlainText
Boolean that indicates the format of the text to be added. If set to TRUE, the text is treated as plain text. If set to FALSE, the text is treated as HTML formatted text.
szwText
Null-terminated wide character text string to be added to the HTML control.

Return Values

None.

Remarks

This is the Unicode version of DTM_ADDTEXT. After the Unicode text has been added to the HTML control, the text parameters in the notification messages will be Unicode.

See Also

DTM_ADDTEXT


DTM_ANCHOR

This message is sent by an application to tell the HTML control to jump to the indicated anchor.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_ANCHOR wParam = 0, lParam = (LPARAM)(LPSTR) szAnchor;

Parameters

szAnchor
Null-terminated text string that contains the name of the anchor to which the HTML control is to jump.

Return Values

None.

Remarks

If the anchor is already in the document, the jump occurs immediately. If the specified anchor is not in the document, the request will be remembered such that, if the anchor is added, the jump will occur as soon as the anchor is available. While there is a pending anchor, any navigation commands from the user, such as keyboard scrolling or using the scroll bar, aborts the pending anchor jump.

See Also

DTM_ANCHORW


DTM_ANCHORW

This message is sent by an application to tell the HTML control to jump to the indicated anchor.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_ANCHORW wParam = 0,lParam = (LPARAM)(LPWSTR) szwAnchor;

Parameters

szwAnchor
Null-terminated wide character text string that contains the name of the anchor to which the HTML control is to jump.

Return Values

None.

Remarks

If the anchor is already in the document, the jump occurs immediately. If the specified anchor is not in the document, the request will be remembered so that, if the anchor is added, the jump will occur as soon as the anchor is available. While there is a pending anchor, any navigation commands from the user, such as keyboard scrolling or using the scroll bar, aborts the pending anchor jump.

This is the Unicode version of DTM_ANCHOR.

See Also

DTM_ANCHOR


DTM_ENABLESHRINK

This message is sent by an application to command the HTML control to toggle the image shrink enable mode, or shrink mode. If shrink mode is enabled, the HTML control will shrink images as required to make the page fit the window.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_ENABLESHRINK wParam = 0,
lParam = (LPARAM)(BOOL) bEnableShrink;

Parameters

bEnableShrink
Boolean that indicates whether to enable shrink mode. If set to TRUE, shrink mode is enabled. If set to FALSE, shrink mode is not enabled.

Return Values

None.

Remarks

This message only affects graphic files that are too large to fit in the window. Usually, in this situation, part of the graphic extends beyond the right edge of the window and the horizontal scroll bar is displayed. Sending DTM_ENABLESHRINK with the lParam set to TRUE removes the horizontal scroll bar and redraws the page so it fits inside the window.


DTM_ENDOFSOURCE

This message is sent by an application to inform the HTML control that the document is complete.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_ENDOFSOURCE wParam = 0, lParam = 0,

Return Values

None.

Remarks

This message implies that no more text will be added until the document is cleared. This allows the HTML control to clean up error conditions resulting from incomplete data or corrupt or invalid HTML text.

See Also

DTM_ADDTEXT


DTM_GETMCCOLOR

This message retrieves the color for a specified portion of the month calendar within a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_GetMonthCalColor

Syntax

DTM_GETMCCOLOR wParam = (WPARAM)(INT)iColor; lParam = 0;

Parameters

iColor
Specifies which month calendar color to retrieve. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Retrieves the background color displayed between months.
MCSC_MONTHBK | Retrieves the background color displayed within the month.
MCSC_TEXT | Retrieves the color used to display text within a month.
MCSC_TITLEBK | Retrieves the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Retrieves the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Retrieves the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. The message returns –1 if unsuccessful.


DTM_GETMCFONT

This message retrieves the font that the date and time picker (DTP) control’s child month calendar control is currently using.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_GetMonthCalFont

Syntax

DTM_GETMCFONT wParam = 0; lParam = 0;

Return Values

Returns an HFONT value that is the handle to the current font.


DTM_GETMONTHCAL

This message retrieves the handle to a date and time picker’s (DTP) child month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_GetMonthCal

Syntax

DTM_GETMONTHCAL wParam = 0; lParam = 0;

Return Values

Returns the handle to a DTP control’s child month calendar control upon success. The message returns NULL upon failure.

Remarks

DTP controls create a child month calendar control when the user clicks the drop-down arrow. When the month calendar is no longer needed, it is destroyed. Therefore, your application must not rely on a static handle to the DTP control’s child month calendar.


DTM_GETRANGE

This message retrieves the current minimum and maximum allowable system times for a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_GetRange

Syntax

DTM_GETRANGE wParam = 0; lParam = (LPARAM) lpSysTimeArray;

Parameters

lpSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures.

Return Values

Returns a DWORD value that is a combination of GDTR_MIN or GDTR_MAX.

Remarks

The first element of the SYSTEMTIME array contains the minimum allowable time if GDTR_MIN is set. The second element of the SYSTEMTIME array contains the maximum allowable time if GDTR_MAX is set.


DTM_GETSYSTEMTIME

This message retrieves the currently selected time from a date and time picker (DTP) control and places it in a specified SYSTEMTIME structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_GetSystemtime

Syntax

DTM_GETSYSTEMTIME wParam = 0; lParam = (LPARAM) lpSysTime;

Parameters

lpSysTime
Long pointer to the SYSTEMTIME structure that receives the system time information. This parameter must be a valid address and cannot be NULL.

Return Values

Returns GDT_VALID if the time information was placed successfully in the specified structure; or the message can return GDT_NONE if the control was set to the DTS_SHOWNONE style and the control check box was not selected.


DTM_IMAGEFAIL

This message is sent by an application to inform the HTML control that the image indicated by the cookie could not be loaded. The cookie value is the value referenced by the dwCookie member of the INLINEIMAGEINFO structure that was sent with the DTM_SETIMAGE message.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_IMAGEFAIL wParam = 0, lParam = (LPARAM)(DWORD) dwCookie;

Parameters

dwCookie
Indicates that the load image that could not be loaded. This value is passed in the dwCookie member of the NM_HTMLVIEW structure when an NM_INLINE_IMAGE notification message is received. This is the same value that was passed in the dwCookie member of the INLINEIMAGEINFO structure when the DTM_SETIMAGE message was sent to the HTML control.

Return Values

None.

Remarks

The Image loading icon will be replaced with the broken image icon, and the ALT text will be displayed.

See Also

DTM_SETIMAGE, NM_INLINE_IMAGE


DTM_SELECTALL

This message is sent by an application to tell an HTML viewer control to select all the text in the current HTML page.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_SELECTALL wParam = 0; lParam = 0;

Return Values

None.


DTM_SETFORMAT

This message sets the display of a date and time picker (DTP) control based on a specified format string.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_SetFormat

Syntax

DTM_SETFORMAT wParam = 0; lParam = (LPARAM) lpszFormat;

Parameters

lpszFormat
Long pointer to a null-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style. The format string is a combination of string fragments. It is interpreted literally, with the exception of the following string fragments:
Value
Description
“d” | The one- or two-digit day.
“dd” | The two-digit day. Single-digit day values are preceded by a zero.
“ddd” | The three-character weekday abbreviation.
“dddd” | The full weekday name.
“h” | The one- or two-digit hour in 12-hour format.
“hh” | The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
“H” | The one- or two-digit hour in 24-hour format.
“HH” | The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
“m” | The one- or two-digit minute.
“mm” | The two-digit minute. Single-digit values are preceded by a zero.
“M” | The one- or two-digit month number.
“MM” | The two-digit month number. Single-digit values are preceded by a zero.
“MMM” | The three-character month abbreviation.
“MMMM” | The full month name.
“t” | The one-letter AM/PM abbreviation; that is, “AM” is displayed as “A.”
“tt” | The two-letter AM/PM abbreviation; that is, “AM” is displayed as “AM.”
“X” | A callback field. The control still uses the other valid format characters, and queries the owner to fill in the “X” portion. Therefore, the owner must be prepared to handle the DTN_WMKEYDOWN, DTN_FORMAT, and DTN_FORMATQUERY notification messages. Multiple “X” characters can be used in series to signify unique callback fields.
“y” | The year is displayed as the last two digits, but with no leading zero for years less than 10.
“yy” | The last two digits of the year; that is, 1996 would be displayed as “96.”
"yyyy" | The full year; that is, 1996 would be displayed as “1996.”

Return Values

Nonzero indicates success. Zero indicates otherwise.

Remarks

It is acceptable to include extra characters within the format string to produce a richer display. However, any nonformat characters must be enclosed within single quotes. For example, the format string “‘Today is: ‘hh’:’m’:’s ddddMMMdd’, ‘yyy” would produce output like “Today is: 04:22:31 Tuesday Mar 23, 1996”.

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L”yyyy” and L”yy” (the ‘L’ indicates a Unicode (16-bit characters) string). If L”y” is passed in, the function assumes L”yy”. If L”yyy” is passed in, the function assumes L”yyyy”. If more than 4 date (L”dddd”) or 4 month (L”MMMM”) pictures are passed in, then the function defaults to L”dddd” or L”MMMM”.

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as “May ‘93”, the format string would be: L”MMMM ‘‘‘‘yy” The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

Note A DTP control tracks locale changes when it is using the default format string. If you set a custom format string, it will not be updated in response to locale changes.


DTM_SETIMAGE

This message is sent by an application to associate a bitmap with an image.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

DTM_SETIMAGE wParam = 0,
lParam = (LPARAM)(LPINLINEIMAGEINFO) lpInlineImageInfo;

Parameters

lpInlineImageInfo
Long pointer to an INLINEIMAGEINFO structure that contains information about the bitmap image.

Return Values

None.

See Also

DTM_IMAGEFAIL, INLINEIMAGEINFO, NM_INLINE_IMAGE


DTM_SETMCCOLOR

This message sets the color for a specified portion of the month calendar within a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_SetMonthCalColor

Syntax

DTM_SETMCCOLOR wParam = (WPARAM)(INT) iColor;
lParam = (LPARAM)(COLORREF) clr;

Parameters

iColor
Specifies which month calendar color to set. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Sets the background color displayed between months.
MCSC_MONTHBK | Sets the background color displayed within the month.
MCSC_TEXT | Sets the color used to display text within a month.
MCSC_TITLEBK | Sets the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Sets the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Sets the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

clr
COLORREF value that represents the color that is set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, the message returns –1.


DTM_SETMCFONT

This message sets the font to be used by the date and time picker (DTP) control’s child month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_SetMonthCalFont

Syntax

DTM_SETMCFONT wParam = (WPARAM)(HFONT) hFont;
lParam = (LPARAM) MAKELONG(fRedraw, 0);

Parameters

hFont
Handle to the font to be set.
fRedraw
Boolean that specifies whether the control should be redrawn immediately upon setting the font. Setting this parameter to TRUE causes the control to redraw itself.

Return Values

The return value for this message is not used.


DTM_SETRANGE

This message sets the minimum and maximum allowable system times for a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_SetRange

Syntax

DTM_SETRANGE wParam = (WPARAM) flags;
lParam = (LPARAM) lpSysTimeArray;

Parameters

flags
Specifies which range values are valid. It can be a combination of the following values:
Value
Description
GDTR_MIN | The first element in the SYSTEMTIME structure array is valid and will be used to set the minimum allowable system time.
GDTR_MAX | The second element in the SYSTEMTIME structure array is valid and will be used to set the maximum allowable system time.

lpSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures. The first element of the SYSTEMTIME array contains the minimum allowable time. The second element of the SYSTEMTIME array contains the maximum allowable time. It is not necessary to fill an array element that is not specified in the flags parameter.

Return Values

Nonzero indicates success. Zero indicates otherwise.


DTM_SETSYSTEMTIME

This message sets the time in a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | DateTime_SetSystemtime

Syntax

DTM_SETSYSTEMTIME wParam = (WPARAM) flag;
lParam = (LPARAM) lpSysTime;

Parameters

flag
Specifies the action that should be performed. It is one of the following values:
Value
Description
GDT_VALID | Sets the DTP control according to the data within the structure that lpSysTime points to.
GDT_NONE | Sets the DTP control to “no date” and clear its check box. lpSysTime is ignored when this flag is specified. This flag applies only to DTP controls that are set to the DTS_SHOWNONE style.

lpSysTime
Long pointer to a SYSTEMTIME structure that contains the system time used to set the DTP control.

Return Values

Nonzero indicates success. Zero indicates otherwise.


DTN_CLOSEUP

This notification message is sent by a date and time picker (DTP) control when the user closes the drop-down month calendar. The month calendar is closed when the user chooses a date from the month calendar or clicks the drop-down arrow while the calendar is open.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_CLOSEUP lpNmhdr = (LPMNHDR) lParam;

Parameters

lpNmhdr
Long pointer to an NMHDR structure that contains information about the notification message.

Remarks

DTP controls do not maintain a static child month calendar control. The DTP control destroys the child month calendar control prior to sending this notification. Therefore, your application must not rely on a static window handle for the control’s child month calendar.

Return Values

The return value for this notification is not used.


DTN_DATETIMECHANGE

This notification message is sent by a date and time picker (DTP) control whenever a change occurs. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_DATETIMECHANGE
lpChange = (LPNMDATETIMECHANGE) lParam;

Parameters

lpChange
Long pointer to an NMDATETIMECHANGE structure that contains information about the change that took place in the control.

Return Values

The owner of the control must return zero.


DTN_DROPDOWN

This notification message is sent by a date and time picker (DTP) control when the user activates the drop-down month calendar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_DROPDOWN lpNmhdr = (LPNMHDR)lParam;

Parameters

lpNmhdr
Long pointer to an NMHDR structure that contains information about the notification message.

Remarks

DTP controls do not maintain a static child month calendar control. The DTP control creates a new month calendar control before sending this notification message. Additionally, the DTP control destroys the child control when it is not active (visible). Therefore, your application must not rely on a static window handle for the control’s child month calendar.

Return Values

The return value for this notification is not used.


DTN_FORMAT

This notification message is sent by a date and time picker (DTP) control to request text to be displayed in a callback field. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_FORMAT lpNMFormat = (LPNMDATETIMEFORMAT) lParam;

Parameters

lpNMFormat
Long pointer to an NMDATETIMEFORMAT structure that contains information regarding this instance of the notification message. The structure contains the substring that defines the callback field and receives the formatted string that the control will display.

Remarks

Handling this message allows the owner of the control to provide a custom string that the control will display. For additional information about callback fields, see Callback Fields.

Return Values

The owner of the control must return zero.


DTN_FORMATQUERY

This notification message is sent by a date and time picker (DTP) control to retrieve the maximum allowable size of the string that will be displayed in callback field. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_FORMATQUERY
lpDTFormatQuery = (LPNMDATETIMEFORMATQUERY) lParam;

Parameters

lpDTFormatQuery
Long pointer to an NMDATETIMEFORMATQUERY structure that contains information about the callback field. The structure contains a substring that defines a callback field and receives the maximum allowable size of the of string that will be displayed in the callback field.

Remarks

The owner of the control must calculate the maximum possible width of the text that will be displayed in the callback field, set the szMax member of the NMDATETIMEFORMATQUERY structure, and return zero.

Handling this message prepares the control to adjust for the maximum size of the string that will be displayed in a particular callback field. This enables the control to properly display output at all times, reducing flicker within the control’s display. For additional information about callback fields, see Callback Fields.


DTN_USERSTRING

This notification message is sent by a date and time picker (DTP) control when a user completes editing a string in the control. It is only sent by DTP controls that are set to the DTS_APPCANPARSE style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_USERSTRING lpDTstring = (LPNMDATETIMESTRING) lParam;

Parameters

lpDTstring
Long pointer to an NMDATETIMESTRING structure that contains information about the instance of the notification message.

Remarks

This message is sent in the form of a WM_NOTIFY message.

The owner of the control must return zero.

Handling this message allows the owner to provide custom responses to strings entered into the control by the user. The owner must be prepared to parse the input string and take action if necessary.


DTN_WMKEYDOWN

This message is sent by a date and time picker (DTP) control when the user types in a callback field. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

DTN_WMKEYDOWN
lpDTKeystroke = (LPNMDATETIMEWMKEYDOWN) lParam;

Parameters

lpDTKeystroke
Long pointer to an NMDATETIMEWMKEYDOWN structure that contains information about this instance of the notification. The structure includes information about the key that the user typed, the substring that defines the callback field, and the current system date and time.

Return Values

The owner of the control must return zero.

Remarks

Handling this message allows the owner of the control to provide specific responses to keystrokes within the callback fields of the control.


EM_CANUNDO

This message is sent by an application to determine whether an edit-control operation can be undone; that is, whether the control can respond to the EM_UNDO message. This message has no parameters.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_CANUNDO wParam = 0; lParam = 0;

Return Values

TRUE indicates that the edit control can correctly process the EM_UNDO message. FALSE indicates otherwise.

See Also

EM_UNDO


EM_CHARFROMPOS

This message is sent by an application to retrieve the zero-based character index and zero-based line index of the character nearest the specified point in an edit control.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

EM_CHARFROMPOS wParam = 0; lParam = MAKELPARAM(x, y);

Parameters

lParam
Specifies the coordinates of a point in the control’s client area. The coordinates are in screen units and are relative to the upper-left corner of the control’s client area.
Control
Description
Rich edit controls | lParam is a pointer to a POINTL structure that contains the horizontal and vertical coordinates.
Edit controls | The low-order word of lParam contains the horizontal coordinate. The high-order word contains the vertical coordinate.

Return Values

The low-order word of the return value specifies the zero-based index of the character nearest the specified point. This index is relative to the beginning of the control, not the beginning of the line. If the specified point is beyond the last character in the edit control, the return value indicates the last character in the control.

The high-order word of the return value specifies the zero-based index of the line that contains the character. For single-line edit controls, this value is zero. The index indicates the line delimiter if the specified point is beyond the last visible character in a line.

See Also

EM_POSFROMCHAR


EM_EMPTYUNDOBUFFER

This message is sent by an application to reset the undo flag of an edit control. The undo flag is set whenever an operation within the edit control can be undone.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_EMPTYUNDOBUFFER wParam = 0; lParam = 0;

Return Values

None.

Remarks

The undo flag is automatically reset whenever the edit control receives a WM_SETTEXT or EM_SETHANDLE message.

See Also

EM_CANUNDO, EM_UNDO, WM_SETTEXT


EM_FMTLINES

This message is sent by an application to set the inclusion flag of soft line-break characters on or off within a multiline edit control. A soft line break consists of two carriage returns and a linefeed and is inserted at the end of a line that is broken because of word wrapping.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_FMTLINES wParam = (WPARAM)(BOOL) fAddEOL; lParam = 0;

Parameters

fAddEOL
Boolean value that specifies whether soft-line break characters are to be inserted. A value of TRUE inserts the characters; a value of FALSE removes them.

Return Values

The return value is identical to the fAddEOL parameter.

Remarks

This message affects only the buffer returned by the EM_GETHANDLE message and the text returned by the WM_GETTEXT message. It has no effect on the display of the text within the edit control.

The EM_FMTLINES message does not affect a line that ends with a hard line break. A hard line break consists of one carriage return and a linefeed.

Note that the size of the text changes when this message is processed.

See Also

WM_GETTEXT


EM_GETFIRSTVISIBLELINE

This message is sent by an application to determine the uppermost visible line in an edit control. This message has no parameters.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETFIRSTVISIBLELINE wParam = 0; lParam = 0;

Return Values

The return value is the zero-based index of the uppermost visible line in a multiline edit control. For single-line edit controls, the return value is the zero-based index of the first visible character.


EM_GETLIMITTEXT

This message is sent by an application to retrieve the current text limit, in characters, for an edit control.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

EM_GETLIMITTEXT wParam = 0; lParam = 0;

Return Values

The text limit indicates success.

See Also

EM_SETLIMITTEXT


EM_GETLINE

This message is sent by an application to copy a line of text from an edit control and place it in a specified buffer.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETLINE wParam = (WPARAM) line;
lParam = (LPARAM)(LPCSTR) lpch;

Parameters

line
Specifies the zero-based index of the line to retrieve from a multiline edit control. A value of zero specifies the topmost line. This parameter is ignored by a single-line edit control.
lpch
Long pointer to the buffer that receives a copy of the line. The first word of the buffer specifies the maximum number of characters that can be copied to the buffer.

Return Values

The number of characters copied indicates success. Zero indicates that the line number specified by the line parameter is greater than the number of lines in the edit control.

Remarks

The copied line does not contain a terminating null character.

See Also

EM_LINELENGTH, WM_GETTEXT


EM_GETLINECOUNT

This message is sent by an application to retrieve the number of lines in a multiline edit control. This message has no parameters.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETLINECOUNT wParam = 0; lParam = 0;

Return Values

An integer specifying the number of lines in the multiline edit control indicates success. 1 indicates that no text is in the edit control.

See Also

EM_GETLINE


EM_GETMARGINS

This message is sent by an application to retrieve the widths of the left and right margins for an edit control.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

EM_GETMARGINS wParam = 0; lParam = 0;

Return Values

The width of the left margin in the low-order word and the width of the right margin in the high-order word indicate success.

See Also

EM_SETMARGINS


EM_GETMODIFY

This message is sent by an application to determine whether the contents of an edit control have been modified. This message has no parameters.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETMODIFY wParam = 0; lParam = 0;

Return Values

TRUE indicates that the content of edit control has been modified. FALSE indicates otherwise.

Remarks

The system maintains an internal flag indicating whether the content of the edit control has been changed. This flag is cleared when the edit control is first created; alternatively, an application can send an EM_SETMODIFY message to the edit control to clear the flag.

See Also

EM_SETMODIFY


EM_GETPASSWORDCHAR

This message is sent by an application to retrieve the password character displayed in an edit control when the user enters text. This message has no parameters.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETPASSWORDCHAR; wParam = 0; lParam = 0;

Return Values

The return value specifies the character to be displayed in place of the character typed by the user. NULL indicates that no password character exists.

Remarks

If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk (*).


EM_GETRECT

This message is sent by an application to retrieve the formatting rectangle of an edit control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit-control window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETRECT wParam = 0; lParam (LPARAM)(LPRECT) lprc;

Parameters

lprc
Long pointer to the RECT structure that receives the formatting rectangle.

Return Values

The return value is not a meaningful value.

Remarks

You can modify the formatting rectangle of a multiline edit control by using the EM_SETRECT and EM_SETRECTNP messages.

See Also

EM_SETRECT, EM_SETRECTNP


EM_GETSEL

This message is sent by an application to get the starting and ending character positions of the current selection in an edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_GETSEL wParam = (WPARAM)(LPDWORD) lpdwStart;
lParam = (WPARAM)(LPDWORD) lpdwEnd;

Parameters

lpdwStart
Long pointer to a 32-bit value that receives the starting position of the selection. This parameter can be NULL.
lpdwEnd
Long pointer to a 32-bit value that receives the position of the first nonselected character after the end of the selection. This parameter can be NULL.

Return Values

The return value is a zero-based 32-bit value with the starting position of the selection in the low-order word and the position of the first character after the last selected character in the high-order word. If either of these values exceeds 65,535, the return value is –1.

Remarks

In a rich edit control, if the selection is not entirely contained in the first 64 KB, use the message EM_EXGETSEL.

See Also

EM_SETSEL


EM_LIMITTEXT

This message is sent by an application to limit the amount of text the user may enter into an edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_LIMITTEXT wParam = (WPARAM) cchMax; lParam = 0;

Parameters

cchMax
Specifies the maximum number of characters the user can enter. If this parameter is zero, the text length is set to 0x7FFFFFFE characters for single-line edit controls or 0xFFFFFFFF for multiline edit controls.

Return Values

None.

Remarks

The maximum number of characters the user can enters different in Windows CE than it is on desktop Windows platforms. In Windows CE, if the cchMax parameter is zero, the text length is set to 0x7FFE (32,766) characters for single-line edit controls or 0xFFFF (65,535) for multiline edit controls. However, the default limit for a multiline edit control is 0xFFFFFFFF. Also, if cchMax is set to -1, the multiline edit control limit is 0xFFFFFFFF.

The EM_LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control by the WM_SETTEXT message. If an application uses the WM_SETTEXT message to place more text into an edit control than is specified in the EM_LIMITTEXT message, the user can edit the entire contents of the edit control.

The default limit to the amount of text a user can enter in an edit control is 30,000 characters.

In a rich edit control, use the message EM_EXLIMITTEXT for text length values greater than 64 KB.

See Also

WM_SETTEXT


EM_LINEFROMCHAR

This message is sent by an application to retrieve the index of the line that contains the specified character index in a multiline edit control. A character index is the number of characters from the beginning of the edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_LINEFROMCHAR wParam = (WPARAM) ich; lParam = 0

Parameters

ich
Specifies the character index of the character contained in the line whose number is to be retrieved. If the ich parameter is –1, either the line number of the current line (the line containing the caret) is retrieved or, if there is a selection, the line number of the line containing the beginning of the selection is retrieved.

Return Values

The zero-based line number of the line containing the character index specified by ich indicates success.

Remarks

In a rich edit control, if the character index is greater than 64 KB, use the message EM_EXLINEFROMCHAR.

See Also

EM_LINEINDEX


EM_LINEINDEX

This message is sent by an application to retrieve the character index of a line in a multiline edit control. The character index is the number of characters from the beginning of the edit control to the specified line.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_LINEINDEX wParam = (WPARAM) line; lParam = 0;

Parameters

line
Specifies the zero-based line number. A value of –1 specifies the current line number (the line that contains the caret).

Return Values

The return value is the character index of the line specified in the line parameter, or it is –1 if the specified line number is greater than the number of lines in the edit control.

See Also

EM_LINEFROMCHAR


EM_LINELENGTH

This message is sent by an application to retrieve the length of a line, in characters, in an edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_LINELENGTH wParam = (WPARAM) ich; lParam = 0;

Parameters

ich
Specifies the character index of a character in the line whose length is to be retrieved when EM_LINELENGTH is sent to a multiline edit control. If this parameter is –1, the message returns the number of unselected characters on lines containing selected characters. For example, if the selection extended from the fourth character of one line through the eighth character from the end of the next line, the return value would be 10 (three characters on the first line and seven on the next).

Return Values

The return value is the length, in characters, of the line specified by the ich parameter when an EM_LINELENGTH message is sent to a multiline edit control. The return value is the length, in characters, of the text in the edit control when an EM_LINELENGTH message is sent to a single-line edit control.

Remarks

Use the EM_LINEINDEX message to retrieve a character index for a specified line number within a multiline edit control.

See Also

EM_LINEINDEX


EM_LINESCROLL

This message is sent by an application to scroll the text vertically or horizontally in a multiline edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_LINESCROLL wParam = (WPARAM) cxScroll;
lParam = (LPARAM) cyScroll;

Parameters

cxScroll
Specifies the number of characters to scroll horizontally.
cyScroll
Specifies the number of lines to scroll vertically.

Return Values

TRUE indicates that the message is sent to a multiline edit control. FALSE indicates that the message is sent to a single-line edit control.

Remarks

The edit control does not scroll vertically past the last line of text in the edit control. If the current line plus the number of lines specified by the cyScroll parameter exceeds the total number of lines in the edit control, the value is adjusted so that the last line of the edit control is scrolled to the top of the edit-control window.

The EM_LINESCROLL message can be used to scroll horizontally past the last character of any line.


EM_POSFROMCHAR

This message is sent by an application to retrieve the coordinates of the specified character in an edit control.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

EM_POSFROMCHAR wCharIndex = (WPARAM) wParam;

Parameters

wCharIndex
Specifies the zero-based index of the character.

Return Values

The return value is the position of the character, (x, y). For a single-line edit control, the y-coordinate is always zero.

Remarks

On return, the x-coordinate of the character is contained in the LOWORD of the LRESULT and the y-coordinate is contained in the HIWORD of the LRESULT.

Any index beyond the last character returns –1.

A returned coordinate can be negative if the character has been scrolled outside the edit control’s client area. The coordinates are truncated to integer values.

If wCharIndex is the index of a line delimiter, the returned coordinates are of the position just past the last visible character in the line.

If wCharIndex is greater than the index of the last character in the control, the returned coordinates are of the position just past the last character of the control.

See Also

EM_CHARFROMPOS


EM_REPLACESEL

This message is sent by an application to replace the current selection in an edit control with the specified text.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_REPLACESEL wParam = 0;
lParam = (LPARAM)(LPCTSTR) lpszReplace;

Parameters

fCanUndo
Boolean value that specifies whether the replacement operation can be undone. If set to TRUE, the operation can be undone. If set to FALSE , the operation cannot be undone.
lpszReplace
Long pointer to a null-terminated string that contains the replacement text.

Return Values

None.

Remarks

Use the EM_REPLACESEL message to replace only a portion of the text in an edit control. To replace all of the text, use the WM_SETTEXT message.

If there is no current selection, the replacement text is inserted at the current location of the caret.

See Also

WM_SETTEXT


EM_SCROLL

This message is sent by an application to scroll the text vertically in a multiline edit control. This message is equivalent to sending a WM_VSCROLL message to the edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SCROLL wParam = (WPARAM)(INT) nScroll; lParam = 0;

Parameters

nScroll
Specifies the action the scroll bar is to take. It is one of the following values:
Value
Description
SB_LINEDOWN | Scrolls down one line.
SB_LINEUP | Scrolls up one line.
SB_PAGEDOWN | Scrolls down one page.
SB_PAGEUP | Scrolls up one page.

Return Values

If the message is successful, the high-order word of the return value is TRUE, and the low-order word is the number of lines that the command scrolls. The number returned may not be the same as the actual number of lines scrolled if the scrolling moves to the beginning or the end of the text. If the nScroll parameter specifies an invalid value, the return value is FALSE.

Remarks

An application should use the EM_LINESCROLL message to scroll to a specific line or character position.

An application should use the EM_SCROLLCARET message to scroll the caret into view.

See Also

EM_LINESCROLL, EM_SCROLLCARET, WM_VSCROLL


EM_SCROLLCARET

This message is sent by an application to scroll the caret into view in an edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SCROLLCARET wParam = 0; lParam = 0;

Parameters

wParam
Reserved; set to zero.
lParam
Reserved; set to zero.

Return Values

Nonzero indicates that the message is sent to an edit control.

See Also

EM_SETSEL


EM_SETLIMITTEXT

This message is sent by an application to set the text limit for an edit control. The text limit is the maximum amount of text, in bytes, that the edit control can contain.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

EM_SETLIMITTEXT wParam = (WPARAM) cbMax; lParam = 0;

Parameters

cchMax
Specifies the new text limit, in characters. If this parameter is 0, the system sets the maximum text limit. For more information, see Remarks.

Return Values

None.

Remarks

The Win32 Platform SDK erroneously states that EM_SETLIMITTEXT sets the limit to the number of bytes specified by cbMax. Both Windows NT and Windows CE set the limit to the number of chars specified by the cbMax.

Windows NT
For single-line edit controls, the text limit is either 0x7FFFFFFE bytes or the value of the wParam parameter, whichever is smaller. For multiline edit controls, this value is either 0xFFFFFFFF bytes or the value of the wParam parameter, whichever is smaller.
Windows 95 and Windows 98
For single-line edit controls, the text limit is either 0x7FFE bytes or the value of the wParam parameter, whichever is smaller. For multiline edit controls, this value is either 0xFFFF bytes or the value of the wParam parameter, whichever is smaller.

See Also

EM_GETLIMITTEXT


EM_SETMARGINS

This message is sent by an application to set the widths of the left and right margins for an edit control. The message redraws the control to reflect the new margins.

At a Glance

Header file: | Winuser.h
Windows CE Versions: | 1.0 and later

Syntax

EM_SETMARGINS wParam = (WPARAM) fwMargin;
lParam = (LPARAM)MAKELONG(wLeft, wRight);

Parameters

fwMargin
Specifies the margins to set. It is one or a combination of the following values:
Value
Description
EC_LEFTMARGIN | Sets the left margin.
EC_RIGHTMARGIN | Sets the right margin.
EC_USEFONTINFO | Uses information about the current font of the edit control to set the margins. For a single-line edit control, margins are set to the average width of characters in the font. For a multiline edit control, the right margin is set to the “A” width of the font (the distance added to the current position before drawing a character), and the left margin is set to the “C” width (the distance added to the current position to provide white space to the right of a character).
If EC_USEFONTINFO is specified, the lParam parameter is ignored.

wLeft
Value of the low-order word of lParam. Specifies the width of the left margin, in pixels. This value is ignored if fwMargin does not include EC_LEFTMARGIN or if EC_USEFONTINFO is specified.
wRight
Value of the high-order word of lParam. Specifies the width of the right margin, in pixels. This value is ignored if fwMargin does not include EC_RIGHTMARGIN or if EC_USEFONTINFO is specified.

Return Values

None.

Remarks

The EC_USEFONTINFO flag for fwMargin is not supported.

See Also

EM_GETMARGINS


EM_SETMODIFY

This message is sent by an application to set or clear the modification flag for an edit control. The modification flag indicates whether the text within the edit control has been modified. It is automatically set whenever the user changes the text. An EM_GETMODIFY message can be sent to retrieve the value of the modification flag.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETMODIFY wParam = (WPARAM)(UINT) fModified; lParam = 0;

Parameters

fModified
Boolean value that specifies the new value for the modification flag. A value of TRUE indicates the text has been modified, and a value of FALSE indicates it has not been modified.

Return Values

None.

Remarks

In a rich edit control, objects created without the REO_DYNAMICSIZE flag will lock in their extents when the modify flag is set to FALSE.

See Also

EM_GETMODIFY


EM_SETPASSWORDCHAR

This message is sent by an application to set or remove a password character displayed in a single-line edit control when the user types text. When a password character is set, that character is displayed in place of each character the user types.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETPASSWORDCHAR wParam = (WPARAM)(UINT) ch; lParam = 0;

Parameters

ch
Specifies the character to be displayed in place of the character typed by the user. If this parameter is zero, the characters typed by the user are displayed.

Return Values

None.

Remarks

When the EM_SETPASSWORDCHAR message is received by an edit control, the edit control redraws all visible characters by using the character specified by the ch parameter.

If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk (*). This style is removed if an EM_SETPASSWORDCHAR message is sent with the ch parameter set to zero.

See Also

EM_GETPASSWORDCHAR


EM_SETREADONLY

This message is sent by an application to set or remove the read-only style (ES_READONLY) of an edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETREADONLY wParam = (WPARAM)(BOOL) fReadOnly;
lParam = 0L;

Parameters

fReadOnly
Boolean value that specifies whether to set or remove the ES_READONLY style. A value of TRUE sets the ES_READONLY style; a value of FALSE removes the ES_READONLY style.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

When an edit control has the ES_READONLY style, the user cannot change the text within the edit control.

To determine whether an edit control has the ES_READONLY style, use the GetWindowLong function with the GWL_STYLE flag.

See Also

GetWindowLong


EM_SETRECT

This message is sent by an application to set the formatting rectangle of a multiline edit control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit control window. When the edit control is first created, the formatting rectangle is the same as the client area of the edit control window. By using the EM_SETRECT message, an application can make the formatting rectangle larger or smaller than the edit control window.

This message is processed only by multiline edit controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETRECT wParam = 0; lParam = (LPARAM)(LPRECT) lprc;

Parameters

lprc
Long pointer to a RECT structure that specifies the new dimensions of the rectangle.

Return Values

None.

Remarks

The EM_SETRECT message causes the text of the edit control to be redrawn. To change the size of the formatting rectangle without redrawing the text, use the EM_SETRECTNP message.

If the edit control does not have a horizontal scroll bar, and the formatting rectangle is set to be larger than the edit control window, lines of text exceeding the width of the edit control window (but smaller than the width of the formatting rectangle) are clipped instead of wrapped.

If the edit control contains a border, the formatting rectangle is reduced by the size of the border. If you are adjusting the rectangle returned by an EM_GETRECT message, you must remove the size of the border before using the rectangle with the EM_SETRECT message.

See Also

EM_GETRECT, EM_SETRECTNP


EM_SETRECTNP

This message is sent by an application to set the formatting rectangle of a multiline edit control. The formatting rectangle is the limiting rectangle of the text. The limiting rectangle is independent of the size of the edit control window. When the edit control is first created, the formatting rectangle is the same as the client area of the edit control window. By using the EM_SETRECTNP message, an application can make the formatting rectangle larger or smaller than the edit control window.

The EM_SETRECTNP message is identical to the EM_SETRECT message, except that the edit control window is not redrawn.

This message is processed only by multiline edit controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETRECTNP wParam = 0; lParam = (LPARAM)(LPRECT) lprc;

Parameters

lprc
Long pointer to a RECT structure that specifies the new dimensions of the rectangle.

Return Values

None.

See Also

EM_SETRECT


EM_SETSEL

This message is sent by an application to select a range of characters in an edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETSEL wParam = (WPARAM)(INT) nStart;
lParam = (LPARAM)(INT) nEnd;

Parameters

nStart
Specifies the starting character position of the selection.
nEnd
Specifies the ending character position of the selection.

Return Values

None.

Remarks

In a rich edit control, if the selection is not entirely contained in the first 64 KB, use the message EM_EXSETSEL.

If the nStart parameter is 0 and the nEnd parameter is –1, all the text in the edit control is selected. If nStart is –1, any current selection is removed. The caret is placed at the end of the selection indicated by the greater of the two values nEnd and nStart.

See Also

EM_GETSEL, EM_REPLACESEL, EM_SCROLLCARET


EM_SETTABSTOPS

This message is sent by an application to set the tab stops in a multiline edit control. When text is copied to the control, any tab character in the text causes space to be generated up to the next tab stop.

This message is processed only by multiline edit controls.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_SETTABSTOPS wParam = (WPARAM) cTabs;
lParam = (LPARAM)(LPWORD) lpwTabs;

Parameters

cTabs
Specifies the number of tab stops contained in the lpdwTabs parameter. If this parameter is zero, the lpdwTabs parameter is ignored and default tab stops are set at every 32 dialog template units. If this parameter is 1, tab stops are set at every n dialog template units, where n is the distance pointed to by the ldpwTabs parameter. If the cTabs parameter is greater than 1, lpdwTabs points to an array of tab stops.
lpdwTabs
Long pointer to an array of unsigned integers specifying the tab stops, in dialog template units. If the cTabs parameter is 1, lpdwTabs points to an unsigned integer containing the distance between all tab stops, in dialog template units.

Return Values

TRUE indicates that all the tabs are set. FALSE indicates otherwise.

Remarks

The EM_SETTABSTOPS message does not automatically redraw the edit control window. If the application is changing the tab stops for text already in the edit control, it should call the InvalidateRect function to redraw the edit control window.

The values specified by the lpdwTabs parameter are in dialog template units, which are the device-independent units used in dialog box templates. To convert measurements from dialog template units to screen units (pixels), use the MapDialogRect function.

See Also

GetDialogBaseUnits, InvalidateRect


EM_UNDO

This message is sent by an application to undo the last edit control operation. This message has no parameters.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EM_UNDO wParam = 0; lParam = 0;

Return Values

For a single-line edit control, the return value is always TRUE. For a multiline edit control, the return value is TRUE if the undo operation is successful, or FALSE if the undo operation fails.

Remarks

An undo operation can also be undone. For example, you can restore deleted text with the first EM_CANUNDO message, and remove the text again with a second EM_CANUNDO message as long as there is no intervening edit operation.

See Also

EM_CANUNDO


EN_CHANGE

This notification message is sent when the user has taken an action that may have altered text in an edit control. Unlike the EN_UPDATE notification message, this notification message is sent after Windows updates the screen. The parent window of the edit control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_CHANGE idEditCtrl = (int) LOWORD (wParam);
hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Identifier of the edit control.
hwndEditCtrl
Handle to the edit control.

See Also

EN_UPDATE, WM_COMMAND


EN_ERRSPACE

This notification message is sent when an edit control cannot allocate enough memory to meet a specific request. The parent window of the edit control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_ERRSPACE idEditCtrl = (int) LOWORD (wParam);
hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Identifier of the edit control.
hwndEditCtrl
Handle to the edit control.

See Also

WM_COMMAND


EN_HSCROLL

This notification message is sent when the user clicks an edit control’s horizontal scroll bar. The parent window of the edit control receives this notification message through the WM_COMMAND message. The parent window is notified before the screen is updated.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_HSCROLL idEditCtrl = (int) LOWORD (wParam);
hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Identifier of the edit control.
hwndEditCtrl
Handle to the edit control.

See Also

EN_VSCROLL, WM_COMMAND


EN_KILLFOCUS

This notification message is sent when an edit control loses the keyboard focus. The parent window of the edit control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_KILLFOCUS idEditCtrl = (int) LOWORD (wParam);
wNotifyCode = HIWORD (wParam); hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Value of the low-order word of wParam. Identifier of the edit control.
wNotifyCode
Value of the high-order word of wParam. Notification code.
hwndEditCtrl
Handle to the edit control.

See Also

EN_SETFOCUS, WM_COMMAND


EN_MAXTEXT

This notification message is sent when the current text insertion has exceeded the specified number of characters for the edit control. The text insertion has been truncated.

This message is also sent when an edit control does not have the ES_AUTOHSCROLL style and the number of characters to be inserted would exceed the width of the edit control.

This message is also sent when an edit control does not have the ES_AUTOVSCROLL style and the total number of lines resulting from a text insertion would exceed the height of the edit control.

The parent window of the edit control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_MAXTEXT idEditCtrl = (int) LOWORD (wParam);
hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Identifier of the edit control.
hwndEditCtrl
Handle to the edit control.

See Also

EM_LIMITTEXT, WM_COMMAND


EN_SETFOCUS

This notification message is sent when an edit control receives the keyboard focus. The parent window of the edit control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_SETFOCUS idEditCtrl = (int) LOWORD (wParam);
wNotifyCode = HIWORD (wParam); hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Value of the low-order word of wParam. Identifier of the edit control.
wNotifyCode
Value of the high-order word of wParam. Notification code.
hwndEditCtrl
Handle to the edit control.

See Also

EN_KILLFOCUS, WM_COMMAND


EN_UPDATE

This notification message is sent when an edit control is about to display altered text. This notification is sent after the control has formatted the text but before it displays the text. This makes it possible to resize the edit control window, if necessary. The parent window of the edit control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_UPDATE idEditCtrl = (int) LOWORD (wParam);
hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Identifier of the edit control.
hwndEditCtrl
Handle to the edit control.

See Also

EN_CHANGE, WM_COMMAND


EN_VSCROLL

This notification message is sent when the user clicks an edit control’s vertical scroll bar. The parent window of the edit control receives this notification message through the WM_COMMAND message. The parent window is notified before the screen is updated.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

EN_VSCROLL idEditCtrl = (int) LOWORD (wParam);
hwndEditCtrl = (HWND) lParam;

Parameters

idEditCtrl
Identifier of the edit control.
hwndEditCtrl
Handle to the edit control.

See Also

EN_HSCROLL, WM_COMMAND


HDM_CREATEDRAGIMAGE

This message creates a transparent version of an item’s image within an existing header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_CreateDragImage

Syntax

HDM_CREATEDRAGIMAGE wParam = (WPARAM) (int) iIndex;
lParam = 0;

Parameters

iIndex
Zero-based index of the item within the header control. The image assigned to this item is the basis for the transparent image.

Return Values

Returns a handle to an image list that contains the new image as its only element


HDM_DELETEITEM

This message deletes an item from a header control. You can send this message explicitly or use the Header_DeleteItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | Header_DeleteItem

Syntax

HDM_DELETEITEM wParam = (WPARAM)(int) index; lParam = 0;

Parameters

index
Index of the item to delete

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

HDM_INSERTITEM


HDM_GETIMAGELIST

This message retrieves the handle to the image list that has been set for an existing header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_GetImageList

Syntax

HDM_GETIMAGELIST wParam = 0; lParam = 0;

Return Values

Returns a handle to the image list set for the header control


HDM_GETITEM

This message retrieves data about an item in a header control. You can send this message explicitly or use the Header_GetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | Header_GetItem

Syntax

HDM_GETITEM wParam = (WPARAM)(int) index;
lParam = (LPARAM)(HD_ITEM FAR*) phdi;

Parameters

index
Index of the item for which data is retrieved
phdi
Pointer to an HDITEM structure. When the message is sent, the mask member indicates the type of data requested. When the message returns, the other members receive the requested data. If the mask member specifies zero, the message returns TRUE, but copies no data to the structure.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

HD_ITEM, HDM_GETITEMCOUNT, HDM_SETITEM


HDM_GETITEMCOUNT

This message retrieves a count of the items in a header control. You can send this message explicitly or use the Header_GetItemCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | Header_GetItemCount

Syntax

HDM_GETITEMCOUNT wParam = 0; lParam = 0;

Return Values

The number of items indicates success. -1 indicates failure.

See Also

HD_ITEM, HDM_GETITEM


HDM_GETITEMRECT

This message retrieves the bounding rectangle for a specified item in a header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_GetItemRect

Syntax

HDM_GETITEMRECT wParam = (WPARAM) (int) iIndex;
lParam = (LPARAM) lpItemRect;

Parameters

iIndex
Zero-based index of the header control item for which to retrieve the bounding rectangle
lpItemRect
Long pointer to a RECT structure that receives the bounding rectangle data

Return Values

Nonzero indicates success. Zero indicates failure


HDM_GETORDERARRAY

This message retrieves the current left-to-right order of items in a header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_GetOrderArray

Syntax

HDM_GETORDERARRAY wParam = (WPARAM) (int) iSize;
lParam = (LPARAM) lpiArray;

Parameters

iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Long pointer to the buffer that receives the index values for items in the header. The buffer must be large enough to hold the total number of header items * sizeof(int). The following code example shows how to reserve enough memory to hold the index values.
INT iItems,
    *lpiArray ;

// Get memory for buffer
(iItems = SendMessage(hwndHD, HDM_GETITEMCOUNT, 0,0))!=-1)
    if(!(lpiArray = calloc(iItems,sizeof(INT))))
MessageBox(hwnd, "Out of memory.","Error", MB_OK);

Return Values

Returns nonzero if successful, and the buffer at lpiArray receives the item number for each item in the header control, in the order in which they appear from left to right. Otherwise, the message returns zero.


HDM_HITTEST

This message tests a point to determine which header item, if any, is at the specified point.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDM_HITTEST wParam = 0;
lParam = (LPARAM)(HD_HITTESTINFO FAR *) phdhti;

Parameters

phdhti
Pointer to an HDHITTESTINFO structure that contains the position to test and receive test result data.

Return Values

The index of the item at the specified position, if any, indicates success. –1 indicates failure.

See Also

HD_HITTESTINFO


HDM_INSERTITEM

This message inserts a new item into a header control. You can send this message explicitly or use the Header_InsertItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | Header_InsertItem

Syntax

HDM_INSERTITEM wParam = (WPARAM)(int) index;
lParam = (LPARAM)(const HD_ITEM FAR*) phdi;

Parameters

index
Index of the item after which the new item is inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.
phdi
Pointer to an HDITEM structure that contains data about the new item

Return Values

The index of the new item indicates success. –1 indicates failure.

See Also

HD_ITEM


HDM_LAYOUT

Retrieves the correct header control size and position within the parent window. This message retrieves the header control size and position within a specified rectangle. This message is used to determine the appropriate dimensions for a new header control to occupy the specified rectangle. You can send this message explicitly or use the Header_Layout macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | Header_Layout

Syntax

HDM_LAYOUT wParam = 0;
lParam = (LPARAM)(HD_LAYOUT FAR*) playout;

Parameters

playout
Pointer to an HDLAYOUT structure. The prc member specifies the rectangle coordinates, and the pwpos member receives the size and position for the header control within the rectangle.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

HD_LAYOUT


HDM_ORDERTOINDEX

This message retrieves an index value for an item based on its order in the header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_OrderToIndex

Syntax

HDM_ORDERTOINDEX wParam = (WPARAM) iOrder; lParam = 0;

Parameters

iOrder
Order in which the item appears within the header control, from left to right. For example, the index value of the item in the far left column would be 0. The value for the next item to the right would be 1, and so on.

Return Values

Returns INT that indicates the item index. If iOrder is invalid (negative or too large), the return value equals iOrder.


HDM_SETHOTDIVIDER

This message changes the divider color between header items to indicate the destination of an external drag-and-drop operation.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_SetHotDivider

Syntax

HDM_SETHOTDIVIDER wParam = (WPARAM) flag;
lParam = (LPARAM) dwInputValue;

Parameters

flag
Specifies the type of value represented by dwInputValue. It is one of the following values:
Value
Description
TRUE | Indicates that dwInputValue holds the client coordinates of the pointer
FALSE | Indicates that dwInputValue holds a divider index value

dwInputValue
Value held in dwInputValue is interpreted based upon the value of flag.

If flag is TRUE, dwInputValue represents the x- and y-coordinates of the pointer. The x-coordinate is in the low-order word, and the y-coordinate is in the high-order word. When the header control receives the message, it highlights the appropriate divider based on the dwInputValue coordinates.

If flag is FALSE, dwInputValue represents the integer index of the divider highlighted.

Return Values

Returns a value equal to the index of the divider that the control highlighted

Remarks

This message creates an effect that a header control automatically produces when it has the HDS_DRAGDROP style. The HDM_SETHOTDIVIDER message is intended for use when the owner of the control manually handles drag-and-drop operations.


HDM_SETIMAGELIST

This message assigns an image list to an existing header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_SetImageList

Syntax

HDM_SETIMAGELIST wParam = 0; lParam = (LPARAM) himl;

Parameters

himl
Handle to an image list

Return Values

Returns the handle to the image list previously associated with the control. The message returns NULL upon failure, or if no image list was set previously.


HDM_SETITEM

This message sets the specified item attributes in a header control. You can send this message explicitly or use the Header_SetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | Header_SetItem

Syntax

HDM_SETITEM wParam = (WPARAM)(int) index;
lParam = (LPARAM)(const HD_ITEM FAR*) phdi;

Parameters

iIndex
Current index of the item whose attributes are changed
phdItem
Pointer to an HDITEM structure that contains item data. When this message is sent, the mask member of the structure must be set to indicate which attributes are set.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

HD_ITEM, HDN_ITEMCHANGED, HDN_ITEMCHANGING


HDM_SETORDERARRAY

This message sets the left-to-right order of header items.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | Header_SetOrderArray

Syntax

HDM_SETORDERARRAY wParam = (WPARAM) (int) iSize;
lParam = (LPARAM) lpiArray;

Parameters

iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Long pointer to an array that specifies the order in which items should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays item 2, item 0, and item 1 in that order, from left to right.

Return Values

Nonzero indicates success. Zero indicates otherwise.


HDN_BEGINDRAG

This notification message is sent by a header control when a drag operation has begun on one of its items. It is sent only by header controls set to the HDS_DRAGDROP style, and is sent as a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HDN_BEGINDRAG pNMHeader = (LPNMHEADER) lParam;

Parameters

pNMHeader
Pointer to an NMHEADER structure that contains data about the header item dragged

Return Values

To enable the header control to automatically manage drag-and-drop operations, return FALSE. If the owner of the control is manually performing drag-and-drop reordering, return TRUE.

Remarks

A header control defaults to automatically managing drag-and-drop reordering. Returning TRUE to indicate external (manual) drag-and-drop management enables the owner of the control to provide custom services as part of the drag-and-drop process.


HDN_BEGINTRACK

This notification message notifies a header control parent window the user has begun dragging a divider in the control; that is, the user has pressed the stylus to the touch screen over a divider in the header control. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_BEGINTRACK phdn = (HD_NOTIFY FAR *) lParam;

Parameters

phdn
Pointer to an NMHEADER structure that contains data about the header control and the item whose divider is dragged.

Return Values

TRUE prevents tracking. FALSE enables tracking of the divider.

See Also

HD_NOTIFY, HDN_ENDTRACK, HDN_TRACK, WM_NOTIFY


HDN_DIVIDERDBLCLICK

This notification message notifies a header control’s parent window that the user double-tapped the divider area of the control. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_DIVIDERDBLCLICK phdn = (HD_NOTIFY FAR *) lParam;

Parameters

phdn
Pointer to an NMHEADER structure that contains data about the header control and the item whose divider was double-clicked

Return Values

None

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ENDDRAG

This notification message is sent by a header control when a drag operation has ended on one of its items. It is sent only by header controls set to the HDS_DRAGDROP style, and is sent as a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HDN_ENDDRAG pNMHeader = (LPNMHEADER) lParam;

Parameters

pNMHeader
Pointer to an NMHEADER structure that contains data about the header item dragged

Return Values

To enable the control to automatically place and reorder the item, return FALSE. Return TRUE to prevent the item from being placed.

Remarks

If the owner is performing external (manual) drag-and-drop management, it must return FALSE. The owner then must reorder header items manually by sending HDM_SETITEM or HDM_SETORDERARRAY.


HDN_ENDTRACK

This notification message notifies a header control parent window that the user has finished dragging a divider. It sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_ENDTRACK phdn = (HD_NOTIFY FAR * ) lParam;

Parameters

phdn
Pointer to an NMHEADER structure that contains data about the header control and the item whose divider was dragged

Return Values

None

See Also

HD_NOTIFY, HDN_BEGINTRACK, HDN_TRACK, WM_NOTIFY


HDN_GETDISPINFO

This notification message is sent to the owner of a header control when the control needs data about a callback header item. It is sent as a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

HDN_GETDISPINFO pDispInfo = (LPNMHDDISPINFO) lParam;

Parameters

pDispInfo
Pointer to an NMHDDISPINFO structure. On input, the members of the structure specify what data is required and the item of interest.

Remarks

Fill the appropriate members of the structure to return the requested data to the header control. If your message handler sets the mask member of the NMHDDISPINFO structure to HDI_DI_SETITEM, the header control stores the data and will not request it again.


HDN_ITEMCHANGED

This notification message notifies a header control parent window the header item attributes have changed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_ITEMCHANGED phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr
Pointer to an NMHEADER structure that contains data about the header control, including attributes that have changed.

Return Values

None

See Also

HD_NOTIFY, HDM_SETITEM, WM_NOTIFY


HDN_ITEMCHANGING

This notification message notifies a header control parent window the header item attributes are about to change. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_ITEMCHANGING phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr
Pointer to an NMHEADER structure that contains data about the header control and the header item, including the attributes about to change.

Return Values

TRUE prevents the changes. FALSE accepts the changes.

See Also

HD_NOTIFY, HDM_SETITEM, WM_NOTIFY


HDN_ITEMCLICK

This notification message notifies a header control parent window that the user tapped the control. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_ITEMCLICK phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr
Pointer to an NMHEADER structure that identifies the header control and specifies the index of the header item clicked and the mouse button used to click the item. The pItem member is set to NULL.

Return Values

None

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMDBLCLICK

This notification message notifies a header control parent window that the user double-tapped the control. It is sent in the form of a WM_NOTIFY message. Only header controls with the HDS_BUTTONS style send this notification.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_ITEMDBLCLICK pnmhdr = (NMHDR FAR *) lParam;

Parameters

pnmhdr
Pointer to an NMHEADER structure that contains data about this notification.

Return Values

None

See Also

NMHDR, WM_NOTIFY


HDN_TRACK

This notification message notifies a header control parent window the user is dragging a divider in the header control. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HDN_TRACK phdr = (HD_NOTIFY FAR *) lParam;

Parameters

phdr
Pointer to an NMHEADER structure that contains data about the header control and the item whose divider is dragged

Return Values

TRUE ends tracking. FALSE continues tracking.

See Also

HD_NOTIFY, HDN_BEGINTRACK, HDN_ENDTRACK, WM_NOTIFY


IMC_CLOSESTATUSWINDOW

This message is sent by an application to the input method editor (IME) window to hide the status window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_CLOSESTATUSWINDOW;
lParam = (LPARAM) 0;

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

When the status window of IME is hidden, this message does nothing. Although an application may send this message to the IME window, the application does not receive the corresponding IMN_CLOSESTATUSWINDOW message.


IMC_GETCANDIDATEPOS

This message is sent by an application to an IME window to get the position of the candidate window. Because the IME may adjust the candidate window position, an application uses this message to get the actual position to decide whether to reposition the window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCANDIDATEPOS;
lParam = (LPARAM) &CandForm;

Parameters

&CandForm
Pointer to the CANDIDATEFORM structure that receives the position of the candidate window

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.


IMC_GETCOMPOSITIONFONT

An application sends the IMC_GETCOMPOSITIONFONT message to an IME window to retrieve the logical font used for displaying intermediate characters in the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCOMPOSITIONFONT;
lParam = (LPARAM) &LogFont;

Parameters

&LogFont
Pointer to the LOGFONT structure that receives data about the logical font

Return Values

Zero indicates success. Nonzero indicates failure.


IMC_GETCOMPOSITIONWINDOW

This message is sent by an application to an input method editor (IME) window to get the position of the composition window. Because the IME may adjust the composition window position, an application uses this message to get the actual position to decide whether to reposition the window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCOMPOSITIONWINDOW;
lParam = (LPARAM) &CompForm;

Parameters

&CompForm
Pointer to the COMPOSITIONFORM structure that receives the position of the composition window

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.


IMC_GETCONVERSIONMODE

This message is sent by an application to an IME window to obtain the current conversion mode. The window retrieves the current conversion mode from the current input context.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCONVERSIONMODE;
lParam = 0;

Return Values

Returns a combination of IME conversion mode values.


IMC_GETOPENSTATUS

This message is sent by an application to an IME window to determine whether the IME is open.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETOPENSTATUS;
lParam = 0;

Return Values

Nonzero indicates that the current IME is open. Zero indicates the current IME is closed.


IMC_GETSENTENCEMODE

This message is sent by an application to an input method editor (IME) window to obtain current sentence mode.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETSENTENCEMODE;
lParam = 0;

Return Values

Returns a combination of IME sentence mode values.


IMC_GETSTATUSWINDOWPOS

This message is sent by an application to an IME window to get the position of the status window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETSTATUSWINDOWPOS;
lParam = 0;

Return Values

A POINTS structure that contains the x- and y-coordinates of the status window position indicates success.


IMC_OPENSTATUSWINDOW

This message is sent by an application to the IME window to show the status window. This message is ignored if the system is not in the show IME status mode. The user can set or clear the show IME status mode from the taskbar.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_OPENSTATUSWINDOW;
lParam = (LPARAM) 0;

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

If the status window is already shown, this message does nothing. Although the application may send this message to the IME window, the application does not receive the corresponding IMN_OPENSTATUSWINDOW message.


IMC_SETCANDIDATEPOS

This message is sent by an application to an IME window to set the position of the candidate window. This message is intended for applications that display composition characters on their own but use the IME window to display candidates.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCANDIDATEPOS;
lParam = (LPARAM) &CandForm;

Parameters

&CandForm
Pointer to the CANDIDATEFORM structure that contains the x- and y-coordinates for the candidate window. The application should set the dwIndex member in the structure.

Return Values

Zero indicates success. Nonzero indicates failure.


IMC_SETCOMPOSITIONFONT

This message is sent by an application to an IME window to specify the logical font to use for displaying intermediate characters in the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCOMPOSITIONFONT;
lParam = (LPARAM) &LogFont;

Parameters

&LogFont
Pointer to the LOGFONT structure that contains data about the logical font

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

When processing this message, the IME window changes the current selected font in the input context.


IMC_SETCOMPOSITIONWINDOW

This message is sent by an application to an input method editor (IME) window to set the style of the composition window. The message set this style in the current input context and the style is subsequently applied to each IME window that receives that input context.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCOMPOSITIONWINDOW;
lParam = (LPARAM) &CompForm;

Parameters

&CompForm
Pointer to the COMPOSITIONFORM structure that contains the style data

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

By default, the IME window has the CFS_POINT style. This means the IME window uses the current caret position and window client area when it opens a composition window.


IMC_SETCONVERSIONMODE

This message is sent by an application to an IME window to set current conversion mode.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCONVERSIONMODE;
lParam = (LPARAM) cMode;

Parameters

cMode
IME conversion mode value.

Return Values

Zero indicates success. Nonzero indicates failure.


IMC_SETOPENSTATUS

This message is sent by an application to an input method editor (IME) window to open or close the current IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETOPENSTATUS;
lParam = (LPARAM) bOpen;

Parameters

bOpen
Boolean that is set to TRUE if the IME is opened, or to FALSE if the IME is closed

Return Values

Zero indicates success. Nonzero indicates failure.

Remarks

When processing this message, the IME window changes the current input context.


IMC_SETSENTENCEMODE

This message is sent by an application to an IME window to set the current sentence mode.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETSENTENCEMODE;
lParam = 0;

Parameters

lParam
IME sentence mode value.

Return Values

Zero indicates success. Nonzero indicates failure.


IMC_SETSTATUSWINDOWPOS

This message is sent by an application to an IME window to set the position of the status window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETSTATUSWINDOWPOS;
lParam = (LPARAM) &pts;

Parameters

&pts
Pointer to a POINTS structure that contains the x- and y-coordinates of the status window position.

Return Values

Zero indicates success. Nonzero indicates failure.


IMN_CHANGECANDIDATE

This message is sent to the application when an IME is about to change the content of the candidate window. An application should process this notification message if it displays candidates itself. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

fCandidates = (DWORD) lParam;

Parameters

fCandidates
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be changed.

Return Values

None

Remarks

The IME window changes the appearance of the candidate window when it processes this message. An application can get data about the system window with the ImmGetCandidateListCount and ImmGetCandidateList functions.

See Also

ImmGetCandidateList, ImmGetCandidateListCount, WM_IME_NOTIFY


IMN_CLOSECANDIDATE

This message is sent to the application when an IME is about to close the candidate window. An application should process this message if it displays candidates. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

fCandidates = (DWORD) lParam;

Parameters

fCandidates
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be closed.

Return Values

None

Remarks

By default, the IME window destroys a candidate window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_CLOSESTATUSWINDOW

This message is sent to the application when an input method editor (IME) is about to close the status window. An application should process this notification message if it displays the status window for the IME. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Return Values

None

Remarks

The IME window closes the status window when it processes this message.


IMN_GUIDELINE

This message is sent when an IME is about to show an error message or other data. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

The IME window displays the error message or data string in an information window.

See Also

WM_IME_NOTIFY


IMN_OPENCANDIDATE

This message is sent to the application when an IME is about to open the candidate window. An application should process this message if it displays candidates. The application can retrieve a list of candidates to display by using the ImmGetCandidateList function. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

fCandidates = (DWORD) lParam;

Parameters

fCandidates
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be opened.

Return Values

None

Remarks

By default, the IME window creates a candidate window when it processes this message.

See Also

ImmGetCandidateList, WM_IME_NOTIFY


IMN_OPENSTATUSWINDOW

This message is sent when an IME is about to create the status window. An application processes this message to display the status window for the IME by itself. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Return Values

None

Remarks

The IME window creates a status window when it processes this message and sets the strings to display in the window into the input context. Applications can get data about the status window by using the ImmGetConversionStatus function.


IMN_SETCANDIDATEPOS

This message is sent when the IME is about to move the candidate window. An application should process this message if it displays the candidate window itself. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Syntax

fCandidates = (DWORD) lParam;

Parameters

fCandidates
Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be moved.

Return Values

None

Remarks

The IME window moves the candidate window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_SETCOMPOSITIONFONT

This message is sent when the font of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Return Values

None

Remarks

The application can get font data by using the ImmGetCompositionFont function. The IME window subsequently uses the font to draw the composition string.


IMN_SETCOMPOSITIONWINDOW

This message is sent when the style or position of the composition window is updated. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

The application can get data about the composition form by using the IMC_GETCOMPOSITIONWINDOW message.

See Also

ImmGetCompositionWindow, WM_IME_NOTIFY


IMN_SETCONVERSIONMODE

This message is sent when the conversion mode of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

The application can get conversion mode data by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETOPENSTATUS

This message is sent when the open status of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

The application can get data about the open status by using the ImmGetOpenStatus function.

See Also

ImmGetOpenStatus, WM_IME_NOTIFY


IMN_SETSENTENCEMODE

This message is sent when the sentence mode of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

The application can get data about the sentence mode by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETSTATUSWINDOWPOS

This message is sent when the status window position in the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Return Values

None

Remarks

The application can get data about the status window position by using the IMC_GETSTATUSWINDOWPOS message.


IMR_CANDIDATEFORM

This message is sent to the application through the WM_IME_REQUEST message when a selected input method editor (IME) needs candidate window data.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

lParam = (LPARAM) lpCANDIDATEFORM;

Parameters

lpCANDIDATEFORM
Long pointer to a buffer that contains a CANDIDATEFORM structure. Its dwIndex member contains the index to the referenced candidate window.

Return Values

A nonzero value indicates that the application filled in the CANDIDATEFORM structure in lParam. Zero indicates otherwise.

Remarks

This notification may be sent by the IME to a window that cleared the ISC_SHOWUICANDIDATEWINDOW flag in the WM_SETCONTEXT message handler.


IMR_COMPOSITIONFONT

This message is sent to the application through the WM_IME_REQUEST message when a selected IME needs data about the font used by the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

lParam = (LPARAM) lpLOGFONT;

Parameters

lpLOGFONT
Long pointer to a buffer that contains a LOGFONT structure. The application fills in the values for the current composition window.

Return Values

A nonzero value returns if the application filled in the LOGFONT structure specified by lParam indicates success. Zero indicates otherwise.

Remarks

This notification may be sent by the IME to a window that cleared the ISC_SHOWUICOMPOSITIONWINDOW flag in the WM_SETCONTEXT message handler.


IMR_COMPOSITIONFORM

This message is sent to the application through the WM_IME_REQUEST message when a selected IME needs data about the composition window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

lParam = (LPARAM) lpCOMPOSITIONFORM;

Parameters

lpCOMPOSITIONFORM
Long pointer to a buffer that contains a COMPOSITIONFORM structure.

Return Values

A nonzero value if the application filled in the COMPOSITIONFORM structure in lParam indicates success. Zero indicates otherwise.

Remarks

This notification may be sent by the IME to a window that cleared the ISC_SHOWUICOMPOSITIONWINDOW flag in the WM_SETCONTEXT message handler.


IMR_CONFIRMRECONVERTSTRING

This message is sent to the application through the WM_IME_REQUEST message when the IME needs to change the RECONVERTSTRING structure, which was previously filled in by the application upon receiving the IMR_RECONVERTSTRING message.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

lParam = (LPARAM) lpRECONVERTSTRING;

Parameters

lpRECONVERTSTRING
Long pointer to a buffer that contains the reconversion string

Return Values

A nonzero value indicates that the application has accepted the changed RECONVERTSTRING structure. Zero indicates that the IME uses the original RECONVERTSTRING.

Remarks

After the application has handled IMR_RECONVERTSTRING, the IME may or may not adjust the RECONVERTSTRING structure specified by the application. The IME sends WM_IME_REQUEST with IMR_CONFIRMRECONVERTSTRING to confirm the changes to the RECONVERTSTRING. If the application returns true for IMR_CONFIRMRECONVERTSTRING, the IME will generate a new composition string based on the RECONVERSTRING structure in the IMR_CONFIRMRECONVERTSTRING message. If the application returns false for IMR_CONFIRMRECONVERTSTRING, the IME will generate a new composition string based on the original RECONVERTSTRING structure specified by the application in the IMR_RECONVERTSTRING message.


IMR_RECONVERTSTRING

This message is sent to the application through the WM_IME_REQUEST message when a selected IME needs a string for reconversion.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.1 and later

Syntax

lParam = (LPARAM) lpRECONVERTSTRING;

Parameters

lpRECONVERTSTRING
Long pointer to a buffer that contains the RECONVERTSTRING structure and strings

Return Values

Returns the required size of the RECONVERTSTRING if the application filled the RECONVERTSTRING structure in lParam. Otherwise, returns zero. However, if lParam is NULL, the application must return the required size of the RECONVERTSTRING.

See Also

RECONVERTSTRING, WM_IME_REQUEST


LB_ADDSTRING

This message is sent by an application to add a string to a list box. If the list box does not have the LBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list and the list is sorted.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_ADDSTRING wParam = 0; lParam = (LPARAM)(LPCTSTR) lpsz;

Parameters

lpsz
Long pointer to the null-terminated string to be added.

If you create the list box with an owner-drawn style, but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data instead of the string it would otherwise point to. You can send the LB_GETITEMDATA and LB_SETITEMDATA messages to retrieve or modify the item data.

Return Values

The zero-based index of the string in the list box indicates success. LB_ERR indicates that an error has occurred. LB_ERRSPACE indicates that there is insufficient space to store the new string.

Remarks

Windows CE does not support owner draw list boxes.

See Also

LB_DELETESTRING, LB_INSERTSTRING, LB_SELECTSTRING, WM_COMPAREITEM


LB_DELETESTRING

This message is sent by an application to delete a string in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_DELETESTRING wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the string to be deleted.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

A count of the strings remaining in the list indicates success. LB_ERR indicates that the index parameter specifies an index greater than the number of items in the list.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the system sends a WM_DELETEITEM message to the owner of the list box so the application can free any additional data associated with the item.

See Also

LB_ADDSTRING, LB_INSERTSTRING, WM_DELETEITEM


LB_FINDSTRING

This message is sent by an application to find the first string in a list box that contains the specified prefix.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_FINDSTRING wParam = (WPARAM) indexStart;
lParam = (LPARAM)(LPCTSTR) lpszFind;

Parameters

indexStart
Zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is –1, the entire list box is searched from the beginning.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lpszFind
Long pointer to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The index of the matching item indicates success. LB_ERR indicates an unsuccessful search.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, this message returns the index of the item with a long value (supplied as the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message) that matches the value supplied as the lpszFind parameter.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SELECTSTRING


LB_FINDSTRINGEXACT

This message is sent by an application to find the first list box string that matches the string specified in the lpszFind parameter.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_FINDSTRINGEXACT wParam = (WPARAM) indexStart;
lParam = (LPARAM)(LPCSTR) lpszFind;

Parameters

indexStart
Zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is –1, the entire list box is searched from the beginning.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lpszFind
Long pointer to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The zero-based index of the matching item indicates success. LB_ERR indicates an unsuccessful search.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the action taken by LB_FINDSTRINGEXACT depends on whether the LBS_SORT style is used. If LBS_SORT is used, the system sends WM_COMPAREITEM messages to the list box owner to determine which item matches the specified string. Otherwise, LB_FINDSTRINGEXACT attempts to match the 32-bit value against the value of the lpszFind parameter.

See Also

LB_FINDSTRING, LB_SELECTSTRING, WM_COMPAREITEM


LB_GETANCHORINDEX

This message is sent by an application to retrieve the index of the anchor item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETANCHORINDEX wParam = 0; lParam = 0;

Return Values

The index of the anchor item indicates success.

See Also

LB_SETANCHORINDEX


LB_GETCARETINDEX

This message is sent by an application to determine the index of the item that has the focus rectangle in a multiple-selection list box. The item may or may not be selected.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETCARETINDEX wParam = 0; lParam = 0;

Return Values

The return value is the zero-based index of the list box item that has the focus rectangle. If the list box is a single-selection list box, the return value is the zero-based index of the item selected, if any.

See Also

LB_SETCARETINDEX


LB_GETCOUNT

This message is sent by an application to retrieve the number of items in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETCOUNT wParam = 0; lParam = 0;

Return Values

The number of items in the list box indicates success. LB_ERR indicates that an error has occurred.

Remarks

The returned count is one greater than the index value of the last item (the index is zero-based).


LB_GETCURSEL

This message is sent by an application to retrieve the index of the currently selected item, if any, in a single-selection list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETCURSEL wParam = 0; lParam = 0;

Return Values

In a single-selection list box, the return value is the zero-based index of the currently selected item. If there is no selection, the return value is LB_ERR.

Remarks

Do not send this message to a multiple-selection list box.

To retrieve the indexes of the selected items in a multiple-selection list box, use the LB_GETSELITEMS message. To determine whether the item that has the focus rectangle in a multiple selection list box is selected, use the LB_GETSEL message.

If sent to a multiple-selection list box, LB_GETCURSEL returns the index of the item that has the focus rectangle. If no items are selected, it returns zero.

See Also

LB_GETCARETINDEX, LB_SETCURSEL


LB_GETHORIZONTALEXTENT

This message is sent by an application to retrieve from a list box the width, in pixels, by which the list box can be scrolled horizontally—the scrollable width—if the list box has a horizontal scroll bar.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETHORIZONTALEXTENT wParam = 0; lParam = 0;

Return Values

The scrollable width, in pixels, of the list box indicates success.

Remarks

To respond to the LB_GETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

See Also

LB_SETHORIZONTALEXTENT


LB_GETITEMDATA

This message is sent by an application to retrieve the application-defined 32-bit value associated with the specified list box item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETITEMDATA wParam = (WPARAM) index; lParam = 0;

Parameters

index
Index of the item.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

The return value is the 32-bit value associated with the item, or LB_ERR if an error occurs. If the item is in an owner-drawn list box and was created without the LBS_HASSTRINGS style, this 32-bit value was in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box. Otherwise, it is the value in the lParam of an LB_SETITEMDATA message.

Remarks

Windows CE does not support owner draw.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA


LB_GETITEMHEIGHT

This message is sent by an application to retrieve the height of items in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETITEMHEIGHT wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the list box item. This index is used only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, it must be zero.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

The height, in pixels, of each item in the list box indicates success. The height of the item specified by the index parameter indicates that the list box has the LBS_OWNERDRAWVARIABLE style. LB_ERR indicates that an error has occurred.

Remarks

Windows CE does not support owner draw.

See Also

LB_SETITEMHEIGHT


LB_GETITEMRECT

This message is sent by an application to retrieve the dimensions of the rectangle that bounds a list box item as it is currently displayed in the list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETITEMRECT wParam = (WPARAM) index;
lParam = (LPARAM)(RECT FAR*) lprc;

Parameters

index
Zero-based index of the item.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lprc
Long pointer to a RECT structure to receive the client coordinates for the item in the list box.

Return Values

LB_ERR indicates that an error has occurred.


LB_GETLOCALE

This message is sent by an application to retrieve the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text for list boxes with the LBS_SORT style and of text added by the LB_ADDSTRING message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

LB_GETLOCALE wParam = 0; lParam = 0;

Return Values

The return value is a 32-bit value that specifies the current locale of the list box. The high-order word contains the country code and the low-order word contains the language identifier.

Remarks

The language identifier consists of a sublanguage identifier and a primary language identifier. Use the PRIMARYLANGID macro to extract the primary language identifier from the low-order word of the return value, and the SUBLANGID macro to extract the sublanguage identifier.

See Also

LB_ADDSTRING, LB_SETLOCALE, PRIMARYLANGID, SUBLANGID


LB_GETSEL

This message is sent by an application to retrieve the selection state of an item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETSEL wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the item.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

A value greater than zero indicates that an item has been selected. Zero indicates otherwise. LB_ERR indicates that an error has occurred.

See Also

LB_SETSEL


LB_GETSELCOUNT

This message is sent by an application to retrieve the total number of selected items in a multiple-selection list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETSELCOUNT wParam = 0; lParam = 0;

Return Values

The count of selected items in the list box indicates success. LB_ERR indicates that the list box is a single-selection list box.

See Also

LB_SETSEL


LB_GETSELITEMS

This message is sent by an application to fill a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETSELITEMS wParam = (WPARAM) cItems;
lParam = (LPARAM)(LPINT) lpnItems;

Parameters

cItems
Specifies the maximum number of selected items whose item numbers are to be placed in the buffer.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lpnItems
Long pointer to a buffer large enough for the number of integers specified by the cItems parameter.

Return Values

The number of items placed in the buffer indicates success. LB_ERR indicates that the list box is a single-selection list box.

See Also

LB_GETSELCOUNT


LB_GETTEXT

This message is sent by an application to retrieve a string from a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETTEXT wParam = (WPARAM) index;
lParam = (LPARAM)(LPCTSTR) lpszBuffer;

Parameters

index
Zero-based index of the string to retrieve.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lpszBuffer
long pointer to the buffer to receive the string. The buffer must have sufficient space for the string and a terminating null character. An LB_GETTEXTLEN message can be sent before the LB_GETTEXT message to retrieve the length, in characters, of the string.

Return Values

The length of the string, in characters and excluding the terminating null character, indicates success. LB_ERR indicates that index does not specify a valid index.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter will receive the 32-bit value associated with the item (the item data).

See Also

LB_GETTEXTLEN


LB_GETTEXTLEN

This message is sent by an application to retrieve the length of a string in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETTEXTLEN wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the string.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

The length of the string, in characters and excluding the terminating null character, indicates success. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

LB_ERR indicates that the index parameter does not specify a valid index.

Remarks

Under certain conditions, the return value is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

LB_GETTEXT


LB_GETTOPINDEX

This message is sent by an application to retrieve the index of the first visible item in a list box. Initially the item with index zero is at the top of the list box, but if the list box contents have been scrolled another item may be at the top.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_GETTOPINDEX wParam = 0; lParam = 0;

Return Values

The index of the first visible item in the list box indicates success.

See Also

LB_SETTOPINDEX


LB_INITSTORAGE

This message allocates memory for storing list box items. An application sends this message before adding a large number of items to a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_INITSTORAGE wParam = (WPARAM)(int) cItems;
lParam = (LPARAM)(DWORD) cb;

Parameters

cItems
Specifies the number of items to add.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

cb
Specifies the amount of memory, in bytes, to allocate for item strings.

Return Values

The total number of items for which memory has been preallocated—that is, the total number of items added by all successful LB_INITSTORAGE messages—indicates success. LB_ERRSPACE indicates failure.

Windows NT
For Windows NT version 4.0, this message does not allocate the specified amount of memory; however, it always returns the value specified in the cItems parameter. For Windows NT version 5.0, the message allocates memory and returns the success and error values described above.

Remarks

The lParam parameter is unused in Windows CE.

The LB_INITSTORAGE message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_ADDSTRING, LB_INSERTSTRING, LB_DIR, and LB_ADDFILE messages take the shortest possible time. You can use estimates for the cItems and cb parameters. If you overestimate, the extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the requested amount.

See Also

LB_ADDSTRING, LB_INSERTSTRING


LB_INSERTSTRING

This message is sent by an application to insert a string into a list box. Unlike the LB_ADDSTRING message, the LB_INSERTSTRING message does not cause a list with the LBS_SORT style to be sorted.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_INSERTSTRING wParam = (WPARAM) index;
lParam = (LPARAM)(LPCTSTR) lpsz;

Parameters

index
Zero-based index of the position at which to insert the string. If this parameter is –1, the string is added to the end of the list.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lpsz
Long pointer to the null-terminated string to be inserted.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data instead of the string it would otherwise point to. You can send the LB_GETITEMDATA and LB_SETITEMDATA messages to retrieve or modify the item data.

Return Values

The index of the position at which the string was inserted indicates success. LB_ERR indicates that an error has occurred. LB_ERRSPACE indicates that there is insufficient space to store the new string.

See Also

LB_ADDSTRING, LB_SELECTSTRING


LB_ITEMFROMPOINT

This message is sent by an application to retrieve the zero-based index of the item nearest the specified point in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_ITEMFROMPOINT wParam = 0;
lParam = (LPARAM)MAKELPARAM(xPos, yPos);

Parameters

xPos
Value of the low-order word of lParam. Specifies the x-coordinate of a point, relative to the upper-left corner of the client area of the list box.
yPos
Value of the high-order word of lParam. Specifies the y-coordinate of a point, relative to the upper-left corner of the client area of the list box.

Return Values

The return value contains the index of the nearest item in the low-order word. The high-order word is zero if the specified point is in the client area of the list box, or one if it is outside the client area.


LB_RESETCONTENT

This message is sent by an application to remove all items from a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_RESETCONTENT wParam = 0; lParam = 0;

Return Values

None

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the owner of the list box receives a WM_DELETEITEM message for each item in the list box.

See Also

WM_DELETEITEM


LB_SELECTSTRING

This message is sent by an application to search a list box for an item that begins with the characters in a specified string. If a matching item is found, the item is selected.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SELECTSTRING wParam = (WPARAM) indexStart;
lParam = (LPARAM)(LPCTSTR) lpszFind;

Parameters

indexStart
Zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is –1, the entire list box is searched from the beginning.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

lpszFind
Long pointer to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

Return Values

The index of the selected item indicates a successful search. LB_ERR indicates an unsuccessful search; the current selection is not changed.

Remarks

The list box is scrolled, if necessary, to bring the selected item into view.

Do not use this message with a list box that has the LBS_MULTIPLESEL style.

An item is selected only if its initial characters from the starting point match the characters in the string specified by the lpszFind parameter.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, this message returns the index of the item whose long value (supplied as the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message) matches the value supplied as the lParam parameter of LB_SELECTSTRING.

See Also

LB_ADDSTRING, LB_FINDSTRING, LB_INSERTSTRING


LB_SELITEMRANGE

This message is sent by an application to select one or more consecutive items in a multiple-selection list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SELITEMRANGE wParam = (WPARAM)(BOOL) fSelect;
lParam = MAKELPARAM(wFirst, wLast);

Parameters

fSelect
Boolean that specifies how to set the selection. If set to a nonzero value, the string is selected and highlighted. If set to zero, the highlight is removed and the string is no longer selected.
wFirst
Zero-based index of the first item to select.
wLast
Zero-based index of the last item to select.

Return Values

LB_ERR indicates that an error has occurred.

Remarks

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

See Also

LB_SELITEMRANGEEX, LB_SETSEL


LB_SELITEMRANGEEX

This message is sent by an application to select one or more consecutive items in a multiple-selection list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SELITEMRANGEEX wParam = (WPARAM) wFirst;
lParam = (LPARAM) wLast);

Parameters

wFirst
Zero-based index of the first item to select.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

wLast
Zero-based index of the last item to select.

Return Values

LB_ERR indicates that an error has occurred.

Remarks

If the wFirst parameter is less than the wLast parameter, the specified range of items is selected. If wFirst is greater than wLast, the selection is removed from the specified range of items.

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

See Also

LB_SELITEMRANGE, LB_SETSEL


LB_SETANCHORINDEX

This message is sent by an application to set the position of the anchor item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETANCHORINDEX wParam = (WPARAM) index; lParam = 0;

Parameters

index
Index of the new anchor item.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

Zero indicates success. LB_ERR indicates failure.

See Also

LB_GETANCHORINDEX


LB_SETCARETINDEX

This message is sent by an application to set the focus rectangle to the item at the specified index in a multiple-selection list box. If the item is not visible, it is scrolled into view.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETCARETINDEX wParam = (WPARAM) index;
lParam = MAKELPARAM(fScroll,0);

Parameters

index
Zero-based index of the list box item that is to receive the focus rectangle.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

fScroll
Boolean that is set to FALSE if the item is scrolled until it is fully visible, or to TRUE if the item is scrolled until it is at least partially visible.

Return Values

LB_ERR indicates that an error has occurred.

See Also

LB_GETCARETINDEX


LB_SETCOLUMNWIDTH

This message is sent by an application to a multiple-column list box—created with the LBS_MULTICOLUMN style—to set the width, in pixels, of all columns in the list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETCOLUMNWIDTH wParam = (WPARAM) cxColumn; lParam = 0;

Parameters

cxColumn
Specifies the width, in pixels, of all columns.

Return Values

None

See Also

LB_SETTABSTOPS


LB_SETCURSEL

This message is sent by an application to select a string and scroll it into view, if necessary. When the new string is selected, the list box removes the highlight from the previously selected string.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETCURSEL wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the string that is selected. If the index parameter is –1, the list box is set to have no selection.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

LB_ERR indicates that an error has occurred. If the index parameter is –1, the return value is LB_ERR, even though no error occurred.

Remarks

Use this message only with single-selection list boxes. You cannot use it to set or remove a selection in a multiple-selection list box.

See Also

LB_GETCURSEL


LB_SETHORIZONTALEXTENT

This message is sent by an application to set the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETHORIZONTALEXTENT wParam = (WPARAM) cxExtent;
lParam = 0;

Parameters

cxExtent
Specifies the number of pixels by which the list box can be scrolled.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values.

Return Values

None

Remarks

To respond to the LB_SETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

See Also

LB_GETHORIZONTALEXTENT


LB_SETITEMDATA

This message is sent by an application to set a 32-bit value associated with the specified item in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETITEMDATA wParam = (WPARAM) index;
lParam = (LPARAM) dwData;

Parameters

index
Zero-based index of the item.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

dwData
Specifies the 32-bit value to be associated with the item.

Return Values

LB_ERR indicates that an error has occurred.

Remarks

If the item is in an owner-drawn list box created without the LBS_HASSTRINGS style, this message replaces the 32-bit value contained in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box.

See Also

LB_ADDSTRING, LB_GETITEMDATA, LB_INSERTSTRING


LB_SETITEMHEIGHT

This message is sent by an application to set the height, in pixels, of items in a list box. Otherwise, this message sets the height of all items in the list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETITEMHEIGHT wParam = (WPARAM) index;
lParam = MAKELPARAM(cyItem, 0);

Parameters

index
Zero-based index of the item in the list box. Use this parameter only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, set it to zero.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

cyItem
Specifies the height, in pixels, of the item.

Return Values

LB_ERR indicates that the index or height is invalid.

Remarks

The index parameter must be set to zero.

See Also

LB_GETITEMHEIGHT


LB_SETLOCALE

This message is sent by an application to set the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text for list boxes with the LBS_SORT style and of text added by the LB_ADDSTRING message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

LB_SETLOCALE wParam = (WPARAM) wLocaleID; lParam = 0;

Parameters

wLocaleID
Locale identifier that the list box uses for sorting when adding text.

Return Values

The return value is the previous locale identifier. If the wLocaleID parameter specifies a locale that is not installed on the system, the return value is LB_ERR and the current list box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier.

See Also

LB_ADDSTRING, LB_GETLOCALE, MAKELCID


LB_SETSEL

This message is sent by an application to select a string in a multiple-selection list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETSEL wParam = (WPARAM)(BOOL) fSelect;
lParam = (LPARAM)(UINT) index;

Parameters

fSelect
Boolean that specifies how to set the selection. If set to TRUE, the string is selected and highlighted. If set to FALSE, the highlight is removed and the string is no longer selected.
index
Zero-based index of the string to set. If index is –1, the selection is added to or removed from all strings, depending on the value of fSelect.

Return Values

LB_ERR indicates that an error has occurred.

Remarks

Use this message only with multiple-selection list boxes.

See Also

LB_GETSEL, LB_SELITEMRANGE


LB_SETTABSTOPS

This message is sent by an application to set the tab-stop positions in a list box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETTABSTOPS wParam = (WPARAM) cTabs;
lParam = (LPARAM)(LPINT) lpnTabs;

Parameters

cTabs
Specifies the number of tab stops in the list box.
lpnTabs
Long pointer to the first member of an array of integers containing the tab stops, in dialog template units. The tab stops must be sorted in ascending order; backward tabs are not allowed.

Return Values

TRUE indicates that all the specified tabs are set. FALSE indicates otherwise.

Remarks

To respond to the LB_SETTABSTOPS message, the list box must have been created with the LBS_USETABSTOPS style.

If cTabs parameter is 0 and lpnTabs is NULL, the default tab stop is two dialog template units. If cTabs is 1, the list box will have tab stops separated by the distance specified by lpnTabs.

If lpnTabs points to more than a single value, a tab stop will be set for each value in lpnTabs, up to the number specified by cTabs.

The values specified by the lpnTabs parameter are in dialog template units, which are the device-independent units used in dialog box templates. To convert measurements from dialog template units to screen units (pixels), use the MapDialogRect function.

See Also

GetDialogBaseUnits


LB_SETTOPINDEX

This message is sent by an application to ensure that a particular item in a list box is visible.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LB_SETTOPINDEX wParam = (WPARAM) index; lParam = 0;

Parameters

index
Zero-based index of the item in the list box.

Windows 95 and Windows 98: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size in bytes of the items in a list box is limited only by available memory.

Return Values

LB_ERR indicates that an error has occurred.

Remarks

The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

See Also

LB_GETTOPINDEX


LBN_DBLCLK

This notification message is sent by an application when the user double-clicks a string in a list box. The parent window of the list box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LBN_DBLCLK idListBox = (int)LOWORD(wParam);
hwndListBox = (HWND) lParam;

Parameters

idListBox
Identifier of the list box.
hwndListBox
Handle to the list box.

Remarks

Only a list box that has the LBS_NOTIFY style will send this notification message.

See Also

LBN_SELCHANGE, WM_COMMAND


LBN_ERRSPACE

This notification message is sent by an application when a list box cannot allocate enough memory to meet a specific request. The parent window of the list box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LBN_ERRSPACE idListBox = (int)LOWORD(wParam);
hwndListBox = (HWND) lParam;

Parameters

idListBox
Identifier of the list box.
hwndListBox
Handle to the list box.

See Also

WM_COMMAND


LBN_KILLFOCUS

This notification message is sent by an application when a list box loses the keyboard focus. The parent window of the list box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LBN_KILLFOCUS idListBox = (int)LOWORD(wParam);
hwndListBox = (HWND) lParam;

Parameters

idListBox
Identifier of the list box.
hwndListBox
Handle to the list box.

See Also

LBN_SETFOCUS, WM_COMMAND


LBN_SELCANCEL

This notification message is sent by an application when the user cancels the selection in a list box. The parent window of the list box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LBN_SELCANCEL idListBox = (int)LOWORD(wParam);
hwndListBox = (HWND) lParam;

Parameters

idListBox
Identifier of the list box.
hwndListBox
Handle to the list box.

Remarks

This notification message applies only to list boxes of the LBS_NOTIFY style.

See Also

LBN_DBLCLK, LBN_SELCHANGE, LB_SETCURSEL, WM_COMMAND


LBN_SELCHANGE

This notification message is sent by an application when the selection in a list box is about to change. The parent window of the list box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LBN_SELCHANGE idListBox = (int)LOWORD(wParam);
hwndListBox = (HWND) lParam;

Parameters

idListBox
Identifier of the list box.
hwndListBox
Handle to the list box.

Remarks

This notification message is not sent if the LB_SETCURSEL message changes the selection.

This notification message applies only to a list box that has the LBS_NOTIFY style.

For a multiple-selection list box, the LBN_SELCHANGE notification is sent whenever the user presses an arrow key, even if the selection does not change.

See Also

LBN_DBLCLK, LBN_SELCANCEL, LB_SETCURSEL, WM_COMMAND


LBN_SETFOCUS

This notification message is sent by an application when a list box receives the keyboard focus. The parent window of the list box receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LBN_SETFOCUS idListBox = (int)LOWORD(wParam);
hwndListBox = (HWND) lParam;

Parameters

idListBox
Identifier of the list box.
hwndListBox
Handle to the list box.

See Also

LBN_KILLFOCUS, WM_COMMAND


LVM_APPROXIMATEVIEWRECT

This message calculates the approximate width and height required to display a specified number of items.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_ApproximateViewRect

Syntax

LVM_APPROXIMATEVIEWRECT wParam = (WPARAM)(INT) iCount;
lParam = (LPARAM) MAKELPARAM(cx, cy);

Parameters

iCount
Number of items to be displayed in the control. If this parameter is set to –1, the message uses the total number of items in the control.
cx and cy
Specify the proposed dimensions of the control, in pixels. Either parameter can beset to –1 to allow the message to use the current width or height value.

Return Values

Returns a DWORD value that holds the approximate width and height needed to display the items, in pixels.

Remarks

Setting the size of the list view control based on the dimensions provided by this message can optimize redraw and reduce flicker.


LVM_ARRANGE

This message arranges items in icon view. You can send this message explicitly or by using the ListView_Arrange macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_Arrange

Syntax

LVM_ARRANGE wParam = (WPARAM)(int) code; lParam = 0;

Parameters

code
Specifies alignment. It is one of the following values:
Value
Description
LVA_ALIGNLEFT | Not supported.
LVA_ALIGNTOP | Not supported.
LVA_DEFAULT | Aligns items according to the list view control current alignment styles (the default value).
LVA_SNAPTOGRID | Snaps all icons to the nearest grid position.

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_CREATEDRAGIMAGE

This message creates a drag image list for the specified item. You can send this message explicitly or by using the ListView_CreateDragImage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_CreateDragImage

Syntax

LVM_CREATEDRAGIMAGE wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(LPPOINT) lpptUpLeft;

Parameters

iItem
Index of the item.
lpptUpLeft
Long pointer to a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Values

The handle to the drag image list indicates success. NULL indicates otherwise.


LVM_DELETEALLITEMS

This message removes all items from a list view control. You can send this message explicitly or by using the ListView_DeleteAllItems macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_DeleteAllItems

Syntax

LVM_DELETEALLITEMS wParam = 0; lParam = 0;

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_DELETECOLUMN

This message removes a column from a list view control. You can send this message explicitly or by using the ListView_DeleteColumn macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_DeleteColumn

Syntax

LVM_DELETECOLUMN wParam = (WPARAM)(int) iCol; lParam = 0;

Parameters

iCol
Index of the column to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_DELETEITEM

This message removes an item from a list view control. You can send this message explicitly or by using the ListView_DeleteItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_DeleteItem

Syntax

LVM_DELETEITEM wParam = (WPARAM)(int) iItem; lParam = 0;

Parameters

iItem
Index of the list view item to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_EDITLABEL

This message begins in-place editing of the specified list view item’s text. The message implicitly selects and focuses the specified item. You can send this message explicitly or by using the ListView_EditLabel macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_EditLabel

Syntax

LVM_EDITLABEL wParam = (WPARAM)(int) iItem; lParam = 0;

Parameters

iItem
Index of the list view item. To cancel editing, set iItem to –1.

Return Values

The handle to the edit control that is used to edit the item text indicates success. NULL indicates otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

WM_CANCELMODE


LVM_ENSUREVISIBLE

This message ensures that a list view item is entirely or at least partially visible, scrolling the list view control if necessary. You can send this message explicitly or by using the ListView_EnsureVisible macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_EnsureVisible

Syntax

LVM_ENSUREVISIBLE wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(BOOL) fPartialOk;

Parameters

i
Index of the list view item.
fPartialOK
Boolean that specifies whether the item must be entirely visible. If set to TRUE, no scrolling occurs if the item is at least partially visible.

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_FINDITEM

This message searches for a list view item with the specified characteristics. You can send this message explicitly or by using the ListView_FindItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_FindItem

Syntax

LVM_FINDITEM wParam = (WPARAM)(int) iStart;
lParam = (LPARAM)(const LV_FINDINFO FAR *) plvfi;

Parameters

iStart
Index of the item to begin the search with or –1 to start from the beginning. The specified item is itself excluded from the search.
plvfi
Pointer to an LVFINDINFO structure that contains data about what to search for.

Return Values

The index of the item indicates success. –1 indicates failure.

See Also

LV_FINDINFO


LVM_GETBKCOLOR

This message retrieves the background color of a list view control. You can send this message explicitly or by using the ListView_GetBkColor macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetBkColor

Syntax

LVM_GETBKCOLOR wParam = 0; lParam = 0;

Return Values

The background color of the list view control indicates success.


LVM_GETCALLBACKMASK

This message retrieves the callback mask for a list view control. You can send this message explicitly or by using the ListView_GetCallbackMask macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetCallbackMask

Syntax

LVM_GETCALLBACKMASK wParam = 0; lParam = 0;

Return Values

The callback mask indicates success.


LVM_GETCOLUMN

This message retrieves the attributes of a list view control column. You can send this message explicitly or by using the ListView_GetColumn macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetColumn

Syntax

LVM_GETCOLUMN wParam = (WPARAM)(int) iCol; lParam = (LPARAM)(LV_COLUMN FAR *) pcol;

Parameters

iCol
Index of the column.
pcol
Pointer to an LVCOLUMN structure that specifies the data to retrieve and receives data about the column. The mask member specifies which column attributes to retrieve.

If the mask member specifies the LVCF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

LV_COLUMN


LVM_GETCOLUMNORDERARRAY

This message retrieves the current left-to-right order of columns in a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_GetColumnOrderArray

Syntax

LVM_GETCOLUMNORDERARRAY wParam = (WPARAM) (int) iCount;
lParam = (LPARAM) lpiArray;

Parameters

iCount
Number of columns in the list view control.
lpiArray
Long pointer to a buffer that receives the index values of the columns in the list view control. The buffer must be large enough to hold the total number of columns * sizeof(int).

Return Values

If successful, returns nonzero and the buffer at lpiArray receives the column index of each column in the control, in the order they appear from left to right. Otherwise, the return value is zero.


LVM_GETCOLUMNWIDTH

This message retrieves the width of a column in report or list view. You can send this message explicitly or by using the ListView_GetColumnWidth macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetColumnWidth

Syntax

LVM_GETCOLUMNWIDTH wParam = (WPARAM)(int) iCol; lParam = 0;

Parameters

iCol
Index of the column. This parameter is ignored in list view.

Return Values

The column width indicates success. Zero indicates failure. If this message is sent to a list view control with the LVS_REPORT style and the specified column doesn’t exist, the return value is undefined.


LVM_GETCOUNTPERPAGE

This message calculates the number of items that can fit vertically in the visible area of a list view control when in list or report view. Only fully visible items are counted. You can send this message explicitly or by using the ListView_GetCountPerPage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetCountPerPage

Syntax

LVM_GETCOUNTPERPAGE wParam = 0; lParam = 0;

Return Values

The number of fully visible items indicates success. If the current view is icon or small icon view, the return value is the total number of items in the list view control.


LVM_GETEDITCONTROL

This message retrieves the handle of the edit control being used to edit a list view item’s text. You can send this message explicitly or by using the ListView_GetEditControl macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetEditControl

Syntax

LVM_GETEDITCONTROL wParam = 0; lParam = 0;

Return Values

The handle to the edit control indicates success. NULL indicates otherwise.

If no label is being edited, the return value is NULL. The edit control is not created until after the LVN_BEGINLABELEDIT notification message is sent.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list view control a WM_CANCELMODE message.

See Also

LVM_GetNextItem, LVN_BEGINLABELEDIT, WM_CANCELMODE


LVM_GETEXTENDEDLISTVIEWSTYLE

This message retrieves the extended styles that are currently in use for a specified list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_GetExtendedListViewStyle

Syntax

LVM_GETEXTENDEDLISTVIEWSTYLE wParam = 0; lParam = 0;

Return Values

Returns a DWORD that represents the styles currently in use for a specified list view control. This value can be a combination of extended styles.


LVM_GETHEADER

This message retrieves the handle to the header control used by the list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_GetHeader

Syntax

LVM_GETHEADER wParam = 0; lParam = 0;

Return Values

Returns the handle to the header control.


LVM_GETIMAGELIST

This message retrieves the handle of an image list used for drawing list view items. You can send this message explicitly or by using the ListView_GetImageList macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetImageList

Syntax

LVM_GETIMAGELIST wParam = (WPARAM)(int) iImageList; lParam = 0;

Parameters

iImageList
Image list to retrieve. It is one of the following values:
Value
Description
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.

Return Values

The handle to the specified image list indicates success. NULL indicates otherwise.

Remarks

Windows CE supports a new value for the iImageList parameter (WPARAM). The LVSIL_HEADER constant specifies that the image list to be retrieved is the image list displayed in the list view’s header control in report view.


LVM_GETISEARCHSTRING

This message retrieves the incremental search string of a list view control. You can send this message explicitly or by using the ListView_GetISearchString macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetISearchString

Syntax

LVM_GETISEARCHSTRING wParam = 0; lParam = (LPARAM)(LPSTR) lpsz;

Parameters

lpsz
Long pointer to a buffer that receives the incremental search string.

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

Return Values

The number of characters in the incremental search string indicates success. Zero indicates that the list view control is not in incremental search mode.


LVM_GETITEM

This message retrieves some or all of a list view item’s attributes. You can send this message explicitly or by using the ListView_GetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItem

Syntax

LVM_GETITEM wParam = 0; lParam = (LPARAM)(LV_ITEM FAR*) pitem;

Parameters

pitem
Pointer to an LVITEM structure that specifies the data to retrieve and receives data about the list view item.

When the message is sent, the iItem and iSubItem members identify the item or subitem to retrieve data about, and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LVITEM structure.

If the mask member specifies the LVIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

LV_ITEM


LVM_GETITEMCOUNT

This message retrieves the number of items in a list view control. You can send this message explicitly or by using the ListView_GetItemCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItemCount

Syntax

LVM_GETITEMCOUNT wParam = 0; lParam = 0;

Return Values

The number of items indicates success.


LVM_GETITEMPOSITION

This message retrieves the position of a list view item. You can send this message explicitly or by using the ListView_GetItemPosition macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItemPosition

Syntax

LVM_GETITEMPOSITION wParam = (WPARAM)(int) i;
lParam = (LPARAM)(POINT FAR *) ppt;

Parameters

i
Index of the list view item.
ppt
Pointer to a POINT structure that receives the position of the item’s upper-left corner, in view coordinates.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

POINT


LVM_GETITEMRECT

This message retrieves the bounding rectangle for all or part of an item in the current view. You can send this message explicitly or by using the ListView_GetItemRect macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItemRect

Syntax

LVM_GETITEMRECT wParam = (WPARAM)(int) i;
lParam = (LPARAM)(LPRECT) prc;

Parameters

i
Index of the list view item.
prc
Pointer to a RECT structure that receives the bounding rectangle. When the message is sent, the left member of this structure is used to determine the portion of the list view item for which to retrieve the bounding rectangle. This will be one of the code values defined in ListView_GetItemRect.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

RECT


LVM_GETITEMSPACING

This message determines the spacing between items in a list view control. You can send this message explicitly or by using the ListView_GetItemSpacing macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItemSpacing

Syntax

LVM_GETITEMSPACING wParam = (WPARAM)(BOOL) fSmall;
lParam = 0;

Parameters

fSmall
Boolean that specifies the view for which to retrieve the item spacing. Set to TRUE for small icon view, or to FALSE for icon view.

Return Values

Returns the amount of spacing between items. The horizontal spacing is contained in the low-order word and the vertical spacing is contained in the high-order word.


LVM_GETITEMSTATE

This message retrieves the state of a list view item. You can send this message explicitly or by using the ListView_GetItemState macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItemState

Syntax

LVM_GETITEMSTATE wParam = (WPARAM)(int) i;
lParam = (LPARAM)(UINT) mask;

Parameters

i
Index of the list view item.
mask
State data to retrieve. It is a combination of the following values:
Value
Description
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.
LVIS_OVERLAYMASK | Use this mask to retrieve the item’s overlay image index.
LVIS_STATEIMAGEMASK | Use this mask to retrieve the item’s state image index.

An item’s state data includes a set of bit flags as well as image list indexes that indicate the item’s state image and overlay image.

Return Values

Returns the current state for the specified item. The only valid bits in the return value are those that correspond to the bits set in the mask parameter.


LVM_GETITEMTEXT

This message retrieves the text of a list view item or subitem. You can send this message explicitly or by using the ListView_GetItemText macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetItemText

Syntax

LVM_GETITEMTEXT wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(LV_ITEM FAR *) pitem;

Parameters

iItem
Index of the list view item.
pitem
Pointer to an LVITEM structure. The iSubItem member specifies the index of a subitem, or it can be zero to get the item label. The pszText member points to a buffer that receives the text, and the cchTextMax member specifies the size of the buffer.

Return Values

If you send this message explicitly, it returns the length of the retrieved string.

If you can send this message implicitly by using the ListView_GetItemText macro, there is no return value.


LVM_GETNEXTITEM

This message searches for a list view item that has the specified properties and bears the specified relationship to a specified item. You can send this message explicitly or by using the ListView_GetNextItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetNextItem

Syntax

LVM_GETNEXTITEM wParam = (WPARAM)(int) iStart;
lParam = MAKELPARAM((UINT)flags,0);

Parameters

iStart
Index of the item to begin the search with, or –1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.
flags
Specifies the relationship to the item specified in iStart. This is the following value:
Value
Description
LVNI_ALL Searches for a subsequent item by index (the default value).

The physical relationship to iStart is specified with one of the following values:
Value
Description
LVNI_ABOVE | Searches for an item that is above the specified item.
LVNI_BELOW | Searches for an item that is below the specified item.
LVNI_TOLEFT | Searches for an item to the left of the specified item.
LVNI_TORIGHT | Searches for an item to the right of the specified item.

The state of the item to find is specified with one or a combination of the following values:
Value
Description
LVNI_CUT | The item has the LVIS_CUT state flag set.
LVNI_DROPHILITED | The item has the LVIS_DROPHILITED state flag set.
LVNI_FOCUSED | The item has the LVIS_FOCUSED state flag set.
LVNI_SELECTED | The item has the LVIS_SELECTED state flag set.

If an item does not have all of the specified state flags set, the search continues with the next item.

Return Values

The index of the next item indicates success. –1 indicates failure.


LVM_GETORIGIN

This message retrieves the current view origin for a list view control. You can send this message explicitly or by using the ListView_GetOrigin macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetOrigin

Syntax

LVM_GETORIGIN wParam = 0; lParam = (LPARAM)(LPPOINT) lpptOrg;

Parameters

lpptOrg
Long pointer to a POINT structure that receives the view origin

Return Values

TRUE indicates success. FALSE indicates that the current view is list or report view.


LVM_GETSELECTEDCOUNT

This message determines the number of selected items in a list view control. You can send this message explicitly or by using the ListView_GetSelectedCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetSelectedCount

Syntax

LVM_GETSELECTEDCOUNT wParam = 0; lParam = 0;

Return Values

Returns the number of selected items


LVM_GETSELECTIONMARK

This message retrieves the selection mark from a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_GetSelectionMark

Syntax

LVM_GETSELECTIONMARK Param = 0; lParam = 0;

Return Values

Returns the zero-based selection mark, or –1 if there is no selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts.


LVM_GETSTRINGWIDTH

This message determines the width of a specified string, using the specified list view control’s current font. You can send this message explicitly or by using the ListView_GetStringWidth macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetStringWidth

Syntax

LVM_GETSTRINGWIDTH wParam = 0;
lParam = (LPARAM)(LPCSTR) psz;

Parameters

psz
Pointer to a null-terminated string

Return Values

The string width indicates success. Zero indicates failure.


LVM_GETSUBITEMRECT

This message retrieves data about the bounding rectangle for a subitem in a list view control. This message is intended to be used only with list view controls that use the LVS_REPORT style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_GetSubItemRect

Syntax

LVM_GETSUBITEMRECT wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(LPRECT) lpRect;

Parameters

iItem
Index of the subitem parent item
lpRect
Long pointer to a RECT structure that receives the subitem bounding rectangle data. The members of RECT must be initialized according to the member and value relationships shown in the following table.
Member
Value
top | The one-based index of the subitem
left | Flag value (see following). Indicates the portion of the list view subitem for which to retrieve the bounding rectangle.

Value
Description
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon
LVIR_LABEL | Returns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.

Return Values

Nonzero indicates success. Zero indicates otherwise.


LVM_GETTEXTBKCOLOR

This message retrieves the text background color of a list view control. You can send this message explicitly or by using the ListView_GetTextBkColor macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetTextBkColor

Syntax

LVM_GETTEXTBKCOLOR wParam = 0; lParam = 0;

Return Values

Returns the background color of the text

See Also

COLORREF


LVM_GETTEXTCOLOR

This message retrieves the text color of a list view control. You can send this message explicitly or by using the ListView_GetTextColor macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetTextColor

Syntax

LVM_GETTEXTCOLOR wParam = 0; lParam = 0;

Return Values

Returns the text color

See Also

COLORREF


LVM_GETTOPINDEX

This message retrieves the index of the topmost visible item when in list or report view. You can send this message explicitly or by using the ListView_GetTopIndex macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetTopIndex

Syntax

LVM_GETTOPINDEX wParam = 0; lParam = 0;

Return Values

The index of the item indicates success. Zero indicates the list view control is in icon or small icon view.


LVM_GETVIEWRECT

This message retrieves the bounding rectangle of all items in the list view control. The list view must be in icon or small icon view. You can send this message explicitly or by using the ListView_GetViewRect macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_GetViewRect

Syntax

LVM_GETVIEWRECT wParam = 0;
lParam = (LPARAM)(RECT FAR *) prc;

Parameters

prc
Pointer to a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list view control.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

RECT


LVM_HITTEST

This message determines which list view item, if any, is at a specified position. You can send this message explicitly or by using the ListView_HitTest macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_HitTest

Syntax

LVM_HITTEST wParam = 0;
lParam = (LPARAM)(LV_HITTESTINFO FAR *) pinfo;

Parameters

pinfo
Pointer to an LVHITTESTINFO structure that contains the position to hit test and receives hit test result data.

Return Values

The index of the item at the specified position, if any, indicates success. –1 indicates failure.

See Also

LV_HITTESTINFO


LVM_INSERTCOLUMN

This message inserts a new column in a list view control. You can send this message explicitly or by using the ListView_InsertColumn macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_InsertColumn

Syntax

LVM_INSERTCOLUMN wParam = (WPARAM)(int) iCol;
lParam = (LPARAM)(const LV_COLUMN FAR *) pcol;

Parameters

iCol
Index of the new column
pcol
Pointer to an LVCOLUMN structure that contains the attributes of the new column

Return Values

The index of the new column indicates success. –1 indicates failure.

See Also

LV_COLUMN


LVM_INSERTITEM

This message inserts a new item in a list view control. You can send this message explicitly or by using the ListView_InsertItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_InsertItem

Syntax

LVM_INSERTITEM wParam = 0;
lParam = (LPARAM)(const LV_ITEM FAR *) pitem;

Parameters

pitem
Pointer to an LVITEM structure that specifies the attributes of the list view item. The iItem member specifies the index of the new item.

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems; the iSubItem member of the LVITEM structure must be zero.

Return Values

The index of the new item indicates success. -1 indicates failure.

See Also

LV_ITEM


LVM_REDRAWITEMS

This message forces a list view control to redraw a range of items. You can send this message explicitly or by using the ListView_RedrawItems macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_RedrawItems

Syntax

LVM_REDRAWITEMS wParam = 0;
lParam = MAKELPARAM((int)iFirst, (int)iLast);

Parameters

iFirst
Index of the first item to redraw
iLast
Index of the last item to redraw

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

UpdateWindow


LVM_SCROLL

This message scrolls the content of a list view control. You can send this message explicitly or by using the ListView_Scroll macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_Scroll

Syntax

LVM_SCROLL wParam = 0; lParam = MAKELPARAM((int) dx, (int) dy);

Parameters

dx
Specifies the amount of horizontal scrolling in pixels. If the list view control is in list view, this value specifies the number of columns to scroll.
dy
Specifies the amount of vertical scrolling in pixels

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_SETBKCOLOR

This message sets the background color of a list view control. You can send this message explicitly or by using the ListView_SetBkColor macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetBkColor

Syntax

LVM_SETBKCOLOR wParam = 0;
lParam = (LPARAM)(COLORREF) clrBk;

Parameters

clrBk
Background color to set or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors.

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_SETCALLBACKMASK

This message sets the callback mask for a list view control. You can send this message explicitly or by using the ListView_SetCallbackMask macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetCallbackMask

Syntax

LVM_SETCALLBACKMASK wParam = (WPARAM)(UINT) mask;
lParam = 0;

Parameters

mask
Value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. It can be any combination of the following constants:
Constant
Description
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus.
LVIS_SELECTED | The item is selected.
LVIS_OVERLAYMASK | The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK | The application stores the image list index of the current state image for each item.

The callback mask of a list view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list view control stores all item state data. After creating a list view control and initializing its items, you can send the LVM_SETCALLBACKMASK message to change the callback mask. To get the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information about overlay images and state images, see List View Image Lists.

For more information on overlay images, state images, and list view callbacks, see the Windows CE User Interface Services Guide.

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_SETCOLUMN

This message sets the attributes of a list view column. You can send this message explicitly or by using the ListView_SetColumn macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetColumn

Syntax

LVM_SETCOLUMN wParam = (WPARAM)(int) iCol;
lParam = (LPARAM)(const LV_COLUMN FAR *) pcol;

Parameters

iCol
Index of the column
pcol
Pointer to an LVCOLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.

If the mask member specifies the LVCF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

LV_COLUMN


LVM_SETCOLUMNORDERARRAY

This message sets the left-to-right order of columns in a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_SetColumnOrderArray

Syntax

LVM_SETCOLUMNORDERARRAY wParam = (WPARAM) (int) iCount;
lParam = (LPARAM) (LPINT) lpiArray;

Parameters

iCount
Size, in elements, of the buffer at lpiArray
lpiArray
Long pointer to an array that specifies the order in which columns should be displayed, in left-to-right order. For example, if the contents of the array are {2,0,1}, the control displays column 2, column 0, and column 1 in that order.

Return Values

Nonzero indicates success. Zero indicates otherwise.


LVM_SETCOLUMNWIDTH

This message changes the width of a column in report or list view. You can send this message explicitly or by using the ListView_SetColumnWidth macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetColumnWidth

Syntax

LVM_SETCOLUMNWIDTH wParam = (WPARAM)(int) iCol;
lParam = MAKELPARAM((int) cx, 0);

Parameters

iCol
Index of the column. In list view, the iCol parameter must be –1.
cx
New width of the column, in list view coordinates, or one of the following values:
Value
Description
LVSCW_AUTOSIZE | Automatically sizes the column
LVSCW_AUTOSIZE_USEHEADER | Automatically sizes the column to fit the header text


LVM_SETEXTENDEDLISTVIEWSTYLE

This message sets extended styles in list view controls. It does not return a value.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_SetExtendedListViewStyle

Syntax

LVM_SETEXTENDEDLISTVIEWSTYLE
wParam = (WPARAM)dwExMask; lParam = (LPARAM)dwExStyle;

Parameters

dwExMask
Specifies which styles in dwExStyle are to be affected. Only the extended styles in dwExMask will be changed. All other styles will be maintained as is. If this parameter is zero, then all of the styles in dwExStyle will be affected.
dwExStyle
Specifies the extended list view control style. This parameter can be a combination of extended styles

The dwExMask parameter allows you to modify one or more extended styles without having to retrieve the existing styles first. For example: if you pass LVS_EX_FULLROWSELECT for dwExMask and 0 for dwExStyle, the LVS_EX_FULLROWSELECT style will be cleared, but all other styles will remain the same.

Return Values

Returns a DWORD value that contains the previous extended list view control styles

Remarks

For backward compatibility reasons, the ListView_SetExtendedListViewStyle macro has not been updated to use dwExMask.


LVM_SETICONSPACING

This message sets the spacing between icons in list view controls that have the LVS_ICON style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_SetIconSpacing

Syntax

LVS_SETICONSPACING wParam = 0;
lParam = (LPARAM) MAKELONG(cx, cy);

Parameters

cx
Distance, in pixels, to set between icons on the x-axis. Setting this value to –1 resets the cx parameter to default spacing.
cy
Distance, in pixels, to set between icons on the y-axis. Setting this value to –1 resets the cy parameter to default spacing.

Return Values

Returns a DWORD value that contains the previous cx in the low-order word, and the previous cy in the high-order word.

Remarks

Values for cx and cy are relative to the upper-left corner of an icon bitmap. Therefore, to set spacing between icons that do not overlap, the cx or cy values must include the size of the icon, plus the amount of empty space desired between icons. Values that do not include the width of the icon will result in overlaps.


LVM_SETIMAGELIST

This message assigns a new image list to a list view control. You can send this message explicitly or by using the ListView_SetImageList macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetImageList

Syntax

LVM_SETIMAGELIST wParam = (WPARAM)(int) iImageList;
lParam = (LPARAM)(HIMAGELIST) himl;

Parameters

iImageList
Type of image list. It is one of the following values:
Value
Description
LVSIL_NORMAL | Image list with large icons
LVSIL_SMALL | Image list with small icons
LVSIL_STATE | Image list with state images

himl
Handle to the image list to assign

Return Values

The handle to the image list previously associated with the control indicates success. NULL indicates otherwise.

Remarks

Windows CE supports a new value for the iImageList parameter (WPARAM). The LVSIL_HEADER constant specifies that, in report view, the image list will be displayed in the list view’s header control.


LVM_SETITEM

This message sets some or all of a list view item’s attributes. You can send this message explicitly or by using the ListView_SetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetItem

Syntax

LVM_SETITEM wParam = 0;
lParam = (LPARAM)(const LV_ITEM FAR *) pitem;

Parameters

pitem
Pointer to an LVITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change and the state member contains the values for those states.

To set the attributes of a list view item, set the iItem member of the LVITEM structure to the index of the item, and set the iSubItem member to zero. For an item, you can set the state, pszText, iImage, and lParam members of the LVITEM structure.

See Also

LV_ITEM


LVM_SETITEMCOUNT

This message prepares a list view control for adding a large number of items. In a regular list view control, it causes the control to allocate memory for the specified number of items. In a virtual list view control, available in Windows CE versions 2.0 and later, it sets the number of virtual items in the control. You can send this message explicitly or use the ListView_SetItemCount or ListView_SetItemCountEx macros.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later (updated in 2.0)
Related macro: | ListView_SetItemCount or ListView_SetItemCountEx

Syntax

LVM_SETITEMCOUNT wParam = (WPARAM) (int) cItems;
lParam = (LPARAM) dwFlags;

Parameters

cItems
Number of items the list view control will ultimately contain
dwFlags
Version 4.70. Specifies the behavior of the list view control after resetting the item count. It can be a combination of the following values:
Value
Description
LVSICF_NOINVALIDATEALL | The list view control will not repaint unless affected items are currently in view.
LVSICF_NOSCROLL | The list view control will not change the scroll position when the item count changes.

If the list view control was created without the LVS_OWNERDATA style, sending this message causes the control to allocate its internal data structures for the specified number of items. This prevents the control from having to allocate the data structures every time an item is added.

If the list view control was created with the LVS_OWNERDATA style (a virtual list view), sending this message sets the virtual number of items that the control contains.

cItems
Number of items that the list view control will ultimately contain
dwFlags
For Windows CE version 1.0, set this value to 0.

For Windows CE versions 2.0 and later, this value specifies the behavior of the list view control after resetting the item count. This value can be a combination of the following:
Value
Description
LVSICF_NOINVALIDATEALL | The list view control will not repaint unless affected items are currently in view.
LVSICF_NOSCROLL | The list view control will not change the scroll position when the item count changes.

Return Values

In Windows CE version 1.0, this message has no return value.

In Windows CE versions 2.0 and later, nonzero indicates success. Zero indicates failure.

Remarks

Windows CE versions 2.0 and later support virtual list views, which you create using the LVS_OWNERDATA style. In a virtual list view, this function sets the number of items in the virtual list view, but does not allocate any memory.

The dwFlags parameter is intended only for list view controls that use the LVS_OWNERDATA and either LVS_REPORT or LVS_LIST styles.


LVM_SETITEMPOSITION

This message moves an item to a specified position in a list view control, which must be in icon or small icon view. You can send this message explicitly or by using the ListView_SetItemPosition macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetItemPosition

Syntax

LVM_SETITEMPOSITION wParam = (LPARAM)(int) i;
lParam = MAKELPARAM((int) x, (int) y);

Parameters

i
Index of the list view item
x and y
Specifies the new position of the item’s upper-left corner, in view coordinates

Return Values

TRUE indicates success. FALSE indicates failure.


LVM_SETITEMPOSITION32

This message moves an item to a specified position in a list view control, which must be in icon or small icon view. This message differs from the LVM_SETITEMPOSITION message in that it uses 32-bit coordinates. You can send this message explicitly or by using the ListView_SetItemPosition32 macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetItemPosition32

Syntax

LVM_SETITEMPOSITION32 wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(LPPOINT) lpptNewPos;

Parameters

iItem
Index of the list view item for which to set the position
lpptNewPos
Long pointer a POINT structure that contains the new position of the item, in list view coordinates

Return Values

None

See Also

LVM_SETITEMPOSITION


LVM_SETITEMSTATE

This message changes the state of an item in a list view control. You can send this message explicitly or by using the ListView_SetItemState macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetItemState

Syntax

LVM_SETITEMSTATE wParam = (WPARAM)(int) i;
lParam = (LPARAM)(LV_ITEM FAR *) pitem;

Parameters

i
Index of the list view item. If this parameter is –1, then the state change is applied to all items.
pitem
Pointer to an LVITEM structure. The stateMask member specifies which state bits to change, and the state member contains the new values for those bits. The other members are ignored.

Return Values

If you send this message explicitly, TRUE indicates success. FALSE indicates failure.


LVM_SETITEMTEXT

This message changes the text of a list view item or subitem. You can send this message explicitly or by using the ListView_SetItemText macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetItemText

Syntax

LVM_SETITEMTEXT wParam = (WPARAM)(int) i;
lParam = (LPARAM)(LV_ITEM FAR *) pitem;

Parameters

i
Index of the list view item
pitem
Pointer to an LVITEM structure. The iSubItem member is the index of the subitem, or it can be zero to set the item label. The pszText member is the address of a null-terminated string containing the new text; it can also be NULL.

The pszText member can also be LPSTR_TEXTCALLBACK to indicate a callback item for which the parent window stores the text. In this case, the list view control sends the parent an LVN_GETDISPINFO notification message when it needs the text.

Return Values

If you send this message explicitly, TRUE indicates success. FALSE indicates failure.


LVM_SETSELECTIONMARK

This message sets the selection mark in a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_SetSelectionMark

Syntax

LVM_SETSELECTIONMARK wParam = 0;
lParam = (LPARAM)(INT) iIndex;

Parameters

iIndex
Zero-based index of the new selection mark

The selection mark is the item index from which a multiple selection starts. This message does not affect the selection state of the item.

Return Values

Returns the previous selection mark, or –1 if there is no previous selection mark.


LVM_SETTEXTBKCOLOR

This message sets the background color of text in a list view control. You can send this message explicitly or by using the ListView_SetTextBkColor macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetTextBkColor

Syntax

LVM_SETTEXTBKCOLOR wParam = 0;
lParam = (LPARAM)(COLORREF) clrText;

Parameters

clrText
New text color

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

COLORREF


LVM_SETTEXTCOLOR

This message sets the text color of a list view control. You can send this message explicitly or by using the ListView_SetTextColor macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SetTextColor

Syntax

LVM_SETTEXTCOLOR wParam = 0;
lParam = (LPARAM)(COLORREF) clrText;

Parameters

clrText
New text color

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

COLORREF


LVM_SORTITEMS

This message sorts list view items using an application-defined comparison function. The index of each item changes to reflect the new sequence. You can send this message explicitly or by using the ListView_SortItems macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_SortItems

Syntax

LVM_SORTITEMS wParam = (WPARAM)(LPARAM) lParamSort;
lParam = (LPARAM)(PFNLVCOMPARE) pfnCompare;

Parameters

lParamSort
Application-defined value passed to the comparison function.
pfnCompare
Pointer to the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort);

The lParam1 parameter is the 32-bit value associated with the first item being compared, and the lParam2 parameter is the value associated with the second item. These are the values specified in the lParam member of the items’ LVITEM structure when they were inserted into the list. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.


LVM_SUBITEMHITTEST

This message determines which list view item or subitem is at a specified position.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | ListView_SubItemHitTest

Syntax

LVM_SUBITEMHITTEST wParam = 0;
lParam = (LPARAM)(LVHITTESTINFO FAR *)pInfo;

Parameters

pInfo
Pointer to an LVHITTESTINFO structure. The POINT structure within LVHITTESTINFO should be set to the client coordinates to be hit-tested.

Return Values

Returns the index of the item or subitem tested, if any, or –1 otherwise. If an item or subitem is at the specified coordinates, the members of the LVHITTESTINFO structure will be filled with the applicable hit data.


LVM_UPDATE

This message updates a list view item. If the list view control has the LVS_AUTOARRANGE style, this macro causes the list view control to be arranged. You can send this message explicitly or by using the ListView_Update macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | ListView_Update

Syntax

LVM_UPDATE wParam = (WPARAM) iItem; lParam = 0;

Parameters

iItem
Index of the item to update

Return Values

TRUE indicates success. FALSE indicates failure.


LVN_BEGINDRAG

This notification message notifies a list view control parent window that a drag and drop operation is being initiated. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_BEGINDRAG pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Values

None

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_BEGINLABELEDIT

This notification message notifies a list view control parent window about the start of label editing for an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_BEGINLABELEDIT pdi = (LV_DISPINFO FAR *) lParam;

Parameters

pdi
Pointer to an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item being edited.

Return Values

TRUE prevents the user from editing the label. FALSE enables the user to edit the label.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_COLUMNCLICK

This notification message notifies a list view control parent window that a column was tapped. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_COLUMNCLICK pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure. The iItem member is –1, and the iSubItem member identifies the column. All other members are zero.

Return Values

None

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_DELETEALLITEMS

This notification message notifies a list view control parent window that all items in the control were deleted. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_DELETEALLITEMS pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure. The iItem member is –1, and the other members are zero.

A list view control sends the LVN_DELETEALLITEMS notification message when it is destroyed or when it receives the LVM_DELETEALLITEMS message. If LVN_DELETEALLITEMS does not return TRUE, the control will also send an LVN_DELETEITEM notification message as each item is deleted.

Return Values

To suppress subsequent LVN_DELETEITEM notification messages, return TRUE.

To receive subsequent LVN_DELETEITEM notification messages, return FALSE.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_DELETEITEM

This notification message notifies a list view control parent window that an item was deleted. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_DELETEITEM pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure. The iItem member identifies the item being deleted. All other members of this structure are zero.

Return Values

None

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ENDDRAG

This notification message notifies a list view control parent window about the end of default processing for a drag and drop operation. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_ENDDRAG pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NM_LISTVIEW structure. The iItem member identifies the dragged item, and the ptAction member specifies the screen coordinates of the drop location. The other members are zero.

Return Values

None

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ENDLABELEDIT

This notification message notifies a list view control parent window about the end of label editing for an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_ENDLABELEDIT pdi = (LV_DISPINFO FAR *) lParam;

Parameters

pdi
Pointer to an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item being edited. The pszText member of item contains a valid value when the LVN_ENDLABELEDIT message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LVITEM structure.

If the user cancels editing, the pszText member of the LVITEM structure is NULL; otherwise, pszText is the address of the edited text.

Return Values

If the pszText member of the LVITEM structure is non-NULL, return TRUE to set the item's label to the edited text. Return FALSE to reject the edited text and revert to the original label.

If the pszText member of the LVITEM structure is NULL, the return value is ignored.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_GETDISPINFO

This notification message requests a list view control parent window to provide data needed to display or sort an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_GETDISPINFO pnmv = (LV_DISPINFO FAR *) lParam;

Parameters

pnmv
Pointer to an NMLVDISPINFO structure. On input, the LVITEM structure contained in this structure specifies the type of data required and identifies the item or subitem of interest.

Use the LVITEM structure to return the requested data to the control. If your message handler sets the LVIF_DI_SETITEM flag in the mask member of the LVITEM structure, the list view control stores the requested data and will not ask for it again.

Return Values

None

Remarks

A list view control sends the LVN_GETDISPINFO notification to retrieve item data stored by the application rather than the control. The data can be text or icon data for an item. It can also be item state data. See the LVM_SETCALLBACKMASK message for more information on implementing item state on a callback basis.

For more information on list view callbacks, see the Windows CE User Interface Services Guide.

See Also

LV_DISPINFO, WM_NOTIFY


LVN_INSERTITEM

This notification message notifies a list view control parent window that a new item was inserted. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_INSERTITEM pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure. The iItem member identifies the new item, and the other members are zero.

Return Values

None

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ITEMACTIVATE

This notification message is sent by a list view control when the user activates an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

LVN_ITEMACTIVATE lpnmlv = (LPNMLISTVIEW)lParam;

Parameters

lpnmlv
Long pointer to an NMLISTVIEW structure that contains notification data. The iItem, iSubItem and ptAction members contain data about the activated item. If the item was activated from the keyboard, the ptAction member will contain –1 in its x and y members.

Return Values

The application receiving this notification must return zero.


LVN_ITEMCHANGED

This notification message notifies a list view control parent window that an item has changed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_ITEMCHANGED pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure that identifies the item and specifies which of its attributes have changed.

Return Values

None

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ITEMCHANGING

This notification message notifies a list view control parent window that an item is changing. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_ITEMCHANGING pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMLISTVIEW structure that identifies the item and specifies which of its attributes are changing.

Return Values

TRUE prevents the change. FALSE accepts the change.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_KEYDOWN

This notification message notifies a list view control parent window that a key has been pressed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_KEYDOWN pnkd = (LV_KEYDOWN FAR *) lParam;

Parameters

pnkd
Pointer to an NMLVKEYDOWN structure.

Return Values

None

See Also

LV_KEYDOWN, WM_KEYDOWN, WM_KEYUP


LVN_MARQUEEBEGIN

This message notifies a list view control parent window that a bounding box, or marquee, selection has begun. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

LVN_MARQUEEBEGIN pnmv = (NM_LISTVIEW FAR *) lParam;

Parameters

pnmv
Pointer to an NMHDR structure.

Return Values

To accept the notification message, return zero. To quit the bounding box selection, return nonzero.

Remarks

A “bounding box selection” is the process of clicking the list view window’s client area and dragging to select multiple items simultaneously.


LVN_ODCACHEHINT

This notification message is sent by a virtual list view control when the contents of its display area have changed. For example, a list view control sends this notification when the user scrolls the control display. This message is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

LVN_ODCACHEHINT pCachehint = (NMLVCACHEHINT *)lParam;

Parameters

pCachehint
Pointer to an NMLVCACHEHINT structure that contains data about the range of items to be cached.

Return Values

The application receiving this notification must return zero.

Remarks

Handling this message allows the application to update the item data held in cache so that it is readily available when an LVN_GETDISPINFO notification message is sent.

Note that this message is not always an exact representation of the items that will be requested by LVN_GETDISPINFO. Therefore, if the requested item is not cached while handling LVN_GETDISPINFO, the application must be prepared to supply the requested data from a source outside the cache.


LVN_ODFINDITEM

This notification message is sent by a virtual list view control when it needs the owner to find a particular callback item. For example, the control will send this notification when the it receives shortcut keyboard input, or when it receives an LVM_FINDITEM message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

LVN_ODFINDITEM pFindInfo = (PNMLVFINDITEM) lParam;

Parameters

pFindInfo
Pointer to an NMLVFINDITEM structure that includes data used for the search.

Return Values

Return the index of the item found, or –1 if no item is found

Remarks

Search data is sent in the form of an LVFINDINFO structure, which is a member of the NMLVFINDITEM structure.


LVN_ODSTATECHANGED

This notification message is sent by a list view control when the state of an item or range of items has changed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

LVN_ODSTATECHANGED
lpStateChange = (LPNMLVODSTATECHANGE) lParam;

Parameters

lpStateChange
Long pointer to an NMLVODSTATECHANGE structure that contains data about the item or items that have changed

Return Values

The application receiving this notification must return zero.


LVN_SETDISPINFO

This notification message notifies a list view control parent window that it must update the data it maintains for an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

LVN_SETDISPINFO pnmv = (LV_DISPINFO FAR *) lParam;

Parameters

pnmv
Pointer to an NMLVDISPINFO structure that specifies data for the changed item. The item member of this structure is an LVITEM structure that contains data about the item that was changed. The pszText member of item contains a valid value, regardless of whether the LVIF_TEXT flag is set in the mask member of this structure.

Return Values

None

See Also

LV_DISPINFO, WM_NOTIFY


MCM_GETCOLOR

This message retrieves the color for a specified portion of a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetColor

Syntax

MCM_GETCOLOR wParam = (WPARAM)(INT)iColor; lParam = 0;

Parameters

iColor
Specifies which month calendar color to retrieve. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Retrieves the background color displayed between months.
MCSC_MONTHBK | Retrieves the background color displayed within the month.
MCSC_TEXT | Retrieves the color used to display text within a month.
MCSC_TITLEBK | Retrieves the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Retrieves the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Retrieves the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. Otherwise, this message returns –1.


MCM_GETCURSEL

This message retrieves the system time portrayed by the currently selected date.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetCurSel

Syntax

MCM_GETCURSEL wParam = 0;
lParam = (LPARAM) (LPSYSTEMTIME) lpSysTime;

Parameters

lpSysTime
Long pointer to a SYSTEMTIME structure that receives the system time information. The time members of this structure are not modified.

Return Values

Nonzero indicates success. Zero indicates otherwise. This message always fails when applied to month calendar controls set to the MCS_MULTISELECT style.


MCM_GETFIRSTDAYOFWEEK

This message retrieves the first day of the week for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetFirstDayOfWeek

Syntax

MCM_GETFIRSTDAYOFWEEK wParam = 0; lParam = 0;

Return Values

Returns a DWORD value that contains two values. The high-order word is a BOOL that is nonzero if the first day of the week is set to something other than LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low-order word is an INT value that represents the first day of the week, as shown in the following table.

Value
Day of the week
0 | Sunday
1 | Monday
2 | Tuesday
3 | Wednesday
4 | Thursday
5 | Friday
6 | Saturday


MCM_GETMAXSELCOUNT

This message retrieves the maximum selectable date range that is set for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetMaxSelCount

Syntax

MCM_GETMAXSELCOUNT wParam = 0; lParam = 0;

Return Values

Returns an INT value that represents the total number of days that can be selected for the control.

Remarks

You can change the selectable date range using the MCM_SETMAXSELCOUNT message.


MCM_GETMAXTODAYWIDTH

This message retrieves the maximum width of the “Today” string in a month calendar control. This includes the label text and the date text.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetMaxTodayWidth

Syntax

MCM_GETMAXTODAYWIDTH wParam = 0; lParam = 0;

Return Values

Returns the width of the “Today” string, in pixels.


MCM_GETMINREQRECT

This message retrieves the minimum size required to display a full month in a month calendar control. Size information is presented in the form of a RECT structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetMinReqRect

Syntax

MCM_GETMINREQRECT wParam = 0;
lParam = (LPARAM) (LPRECT) lpRectInfo;

Parameters

lpRectInfo
Long pointer to a RECT structure that receives bounding rectangle information.

Return Values

Returns nonzero and lpRectInfo receives the applicable bounding information if successful. The message returns zero upon failure.

Remarks

The top and left members of lpRectInfo will always be zero. The right and bottom members represent the minimum cx and cy required for the control.

The minimum required window size for a month calendar control depends on the currently selected font.


MCM_GETMONTHDELTA

This message retrieves the “scroll rate” for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetMonthDelta

Syntax

MCM_GETMONTHDELTA wParam = 0; lParam = 0;

Return Values

If the month delta was previously set using the MCM_SETMONTHDELTA message, returns an INT value that represents the month calendar’s current scroll rate. If the month delta was not previously set using the MCM_SETMONTHDELTA message or the month delta was reset to the default, returns an INT value that represents the current number of months visible.


MCM_GETMONTHRANGE

This message, using SYSTEMTIME structures, retrieves date information that represents the high and low limits of a month calendar control’s display.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetMonthRange

Syntax

MCM_GETMONTHRANGE wParam = (WPARAM)(DWORD) dwFlag;
lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

dwFlag
Specifies the scope of the range limits to be retrieved. It is one of the following values:
Value
Description
GMR_DAYSTATE | Includes preceding and trailing months of visible range that are only partially displayed.
GMR_VISIBLE | Includes only those months that are entirely displayed.

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that receives the lower and upper limits of the scope specified by dwFlag. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures are not modified.

Return Values

Returns an INT that represents the range, in months, spanned by the two limits returned at lprgSysTimeArray.


MCM_GETRANGE

This message retrieves the minimum and maximum allowable dates set for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetRange

Syntax

MCM_GETRANGE wParam = 0;
lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that receives the date limit information. The minimum limit is set in lprgSysTimeArray[0], and lprgSysTimeArray[1] receives the maximum limit. If either element is set to all zeros, then no corresponding limit is set for the month calendar control. The time members of these structures are not modified.

Return Values

Returns a DWORD that can be zero (no limits are set) or a combination of the following values that specify limit information:

GDTR_MAX
A maximum limit is set for the control; lprgSysTimeArray[0] is valid and contains the applicable date information.
GDTR_MIN
A minimum limit is set for the control; lprgSysTimeArray[1] is valid and contains the applicable date information.


MCM_GETSELRANGE

This message retrieves date information that represents the upper and lower limits of the date range currently selected by the user

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetSelRange

Syntax

MCM_GETSELRANGE wParam = 0;
lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that receives the lower and upper limits of the user’s selection. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures are not modified.

Return Values

Nonzero indicates success. Zero indicates otherwise. MCM_GETSELRANGE fails if applied to a month calendar control that does not use the MCS_MULTISELECT style.


MCM_GETTODAY

This message retrieves the date information for the date specified as “today” for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_GetToday

Syntax

MCM_GETTODAY wParam = 0;
lParam = (LPARAM)(LPSYSTEMTIME) lpToday;

Parameters

lpToday
Long pointer to a SYSTEMTIME structure that receives the date information. The time members of this structure are not modified.

Return Values

Nonzero indicates success. Zero indicates otherwise.


MCM_HITTEST

This message determines which portion of a month calendar control is at a specified point on the screen.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_HitTest

Syntax

MCM_HITTEST wParam = 0;
lParam = (LPARAM)(PMCHITTESTINFO) pMCHitTest;

Parameters

pMCHitTest
Pointer to an MCHITTESTINFO structure. Upon sending the message, the cbSize member must equal sizeof(MCHITTESTINFO), and pt must be set to the point you want to hit test.

Return Values

Sets values in members of the MCHITTESTINFO structure at pMCHitTest and returns a DWORD value that is one of the following values:

MCHT_CALENDAR
The specified point was within the calendar.
MCHT_CALENDARBK
The specified point was in the calendar’s background.
MCHT_CALENDARDATE
The specified point was on a particular date within the calendar. The SYSTEMTIME structure at lpMCHitTest->st is set to the date at the specified point.
MCHT_CALENDARDATENEXT
The specified point was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_CALENDARDATEPREV
The specified point was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_CALENDARDAY
The specified point was over a day abbreviation (“Fri”). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the top row.
MCHT_CALENDARWEEKNUM
The specified point was over a week number (The MCS_WEEKNUMBERS style only.) The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the leftmost column.
MCHT_NEXT
The specified point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_NOWHERE
The specified point was either not on the month calendar control, or in an inactive portion of the control.
MCHT_PREV
The specified point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLE
The specified point was over a month’s title.
MCHT_TITLEBK
The specified point was over the background of a month’s title.
MCHT_TITLEBTNNEXT
The specified point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_TITLEBTNPREV
The specified point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLEMONTH
The specified point was in the a month’s title bar, over a month name.
MCHT_TITLEYEAR
The specified point was in a month’s title bar, over the year value.
MCHT_TODAYLINK
The specified point was on the “today” link at the bottom of the month calendar control.

Remarks

The uHit member of the MCHITTESTINFO structure at pMCHitTest will equal the return value.


MCM_SETCOLOR

This message sets the color for a specified portion of a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetColor

Syntax

MCM_SETCOLOR wParam = (WPARAM)(INT) iColor;
lParam = (LPARAM)(COLORREF) clr;

Parameters

iColor
Specifies which month calendar color to set. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Retrieves the background color displayed between months.
MCSC_MONTHBK | Retrieves the background color displayed within the month.
MCSC_TEXT | Retrieves the color used to display text within a month.
MCSC_TITLEBK | Retrieves the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Retrieves the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Retrieves the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

clr
COLORREF value that represents the color that is set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, this message returns –1.


MCM_SETCURSEL

This message sets the currently selected date for a month calendar control. If the specified date is not in view, the control updates the display to bring it into view.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetCurSel

Syntax

MCM_SETCURSEL wParam = 0;
lParam = (LPARAM)(LPSYSTEMTIME) lpSysTime;

Parameters

lpSysTime
Long pointer to a SYSTEMTIME structure that contains the date to be set as the current selection. The time members of this structure are ignored.

Return Values

Nonzero indicates success. Zero indicates otherwise. This message fails if applied to a month calendar control that uses the MCS_MULTISELECT style.


MCM_SETDAYSTATE

This message sets the display for days in all months that are currently visible within a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetDayState

Syntax

MCM_SETDAYSTATE wParam = (WPARAM) iMonths;
lParam = (LPARAM)(LPMONTHDAYSTATE) lpDayStateArray;

Parameters

iMonths
Indicates how many elements are in the array that lpDayStateArray points to.
lpDayStateArray
Long pointer to an array of MONTHDAYSTATE values that define how the month calendar control will draw each day in its display.

The array at lpDayStateArray must contain as many elements as the value returned by the following macro.

Return Values

Sets the month calendar’s display and returns nonzero if successful. Otherwise it returns zero.

Remarks

Keep in mind that the array at lpDayStateArray must contain MONTHDAYSTATE values that correspond with all months currently in the control’s display, in chronological order. This includes the two months only partially displayed before the first month and after the last month. For more information about preparing your array, see “Preparing the MONTHDAYSTATE Array.”


MCM_SETFIRSTDAYOFWEEK

This message sets the first day of the week for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetFirstDayOfWeek

Syntax

MCM_SETFIRSTDAYOFWEEK wParam = 0;
lParam = (LPARAM)(INT) iDay;

Parameters

iDay
INT value representing which day is to be set as the first day of the week. It is one of the following values:
Value
Day of the week
0 | Sunday
1 | Monday
2 | Tuesday
3 | Wednesday
4 | Thursday
5 | Friday
6 | Saturday

Return Values

Returns a DWORD value that contains two values. The high-order word is a BOOL that is nonzero if the previous first day of the week did not equal LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low-order word is an INT value that represents the previous day of the week number (see list under iDay).

Remarks

If the first day of the week is set to anything other than the default (LOCALE_IFIRSTDAYOFWEEK), the control will not automatically update first-day-of-the-week changes based on locale changes.


MCM_SETMAXSELCOUNT

This message sets the maximum number of days that can be selected in a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetMaxSelCount

Syntax

MCM_SETMAXSELCOUNT wParam = (WPARAM)(INT) iMax;
lParam = 0;

Parameters

iMax
INT value that is set to represent the maximum number of selectable days.

Return Values

Returns nonzero if successful, and returns zero otherwise. This message fails if applied to a month calendar control that does not use the MCS_MULTISELECT style.


MCM_SETMONTHDELTA

This message sets the “scroll rate” for a month calendar control. The scroll rate is the number of months that a month calendar control moves its display when the user clicks a scroll button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetMonthDelta

Syntax

MCM_SETMONTHDELTA wParam = (WPARAM)(INT) iDelta; lParam = 0;

Parameters

iDelta
Number of months to be set as the control’s scroll rate. If this value is zero, the month delta is reset to the default, which is the number of months displayed in the control.

Return Values

Returns an INT value that represents the previous scroll rate. If the scroll rate has not been previously set, the return value is zero.


MCM_SETRANGE

This message sets the minimum and maximum allowable dates for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetRange

Syntax

MCM_SETRANGE wParam = (WPARAM)(SHORT) fWhichLimit;
lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

fWhichLimit
Specifies which limit dates are being set. It is one or both of the following values:
Value
Description
GDTR_MAX | The maximum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[1] must contain date information.
GDTR_MIN | The minimum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[0] must contain date information.

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that contains date limit information. The maximum limit must be in lpSysTimeArray[1] if GDTR_MAX is specified, and lpSysTimeArray[0] must contain the minimum limit if GDTR_MIN is specified. The time members of these structures are ignored.

Return Values

Nonzero indicates success. Zero indicates otherwise.


MCM_SETSELRANGE

This message sets the selection for a month calendar control to a specified date range.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetSelRange

Syntax

MCM_SETSELRANGE wParam = 0;
lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that contains date information representing the selection limits. The first selected date must be specified in lpSysTimeArray[0], and the last selected date must be specified in lpSysTimeArray[1]. The time members of these structures are ignored.

Return Values

Nonzero indicates success. Zero indicates otherwise. This message fails if applied to a month calendar control that does not use the MCS_MULTISELECT style.


MCM_SETTODAY

This message sets the “today” selection for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | MonthCal_SetToday

Syntax

MCM_SETTODAY wParam = 0;
Param = (LPARAM)(LPSYSTEMTIME) lpSysTime;

Parameters

lpSysTime
Long pointer to a SYSTEMTIME structure that contains the date to be set as the “today” selection for the control. If this parameter is set to NULL, the control returns to the default setting. The time members of this structure are ignored.

If the “today” selection is set to any date other than the default, the following conditions apply.

Return Values

The return value for this message is not used.

Remarks

The control will not automatically update the “today” selection when the time passes midnight for the current day.

The control will not automatically update its display based on locale changes.


MCN_GETDAYSTATE

This notification message is sent by a month calendar control to request information about how individual days should be displayed. It is sent only by month calendar controls that use the MCS_DAYSTATE style, and is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

MCN_GETDAYSTATE lpNMDayState = (LPNMDAYSTATE) lParam;

Parameters

lpNMDayState
Long pointer to an NMDAYSTATE structure. The structure contains information about the time frame for which the control needs information, and receives the address of an array that provides such data.

Remarks

Handling this notification message allows your application to customize its display by specifying that certain days be displayed in bold. For more information about processing this message, see “Processing the MCN_GETDAYSTATE Notification Message.”


MCN_SELCHANGE

This notification message is sent by a month calendar control whenever the currently selected date or range of dates changes. It is sent in the form of a WM_NOTIFY message.

For example, the control sends MCN_SELCHANGE when the user explicitly changes his or her selection within the current month, or when the selection is implicitly changed in response to next/previous month navigation.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

MCN_SELCHANGE lpNMSelChange = (LPNMSELCHANGE) lParam;

Parameters

lpNMSelChange
Long pointer to an NMSELCHANGE structure that contains information about the currently selected date range.

Remarks

This notification message is similar to MCN_SELECT, but is sent in response to any selection change, whereas MCN_SELECT is sent only for an explicit date selection.


MCN_SELECT

This notification message is sent by a month calendar control whenever the user makes an explicit date selection within a month calendar control. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

MCN_SELECT lpNMSelChange = (LPNMSELCHANGE) lParam;

Parameters

lpNMSelChange
Long pointer to an NMSELCHANGE structure that contains information about the currently selected date range.

Remarks

This notification message is similar to MCN_SELCHANGE, but is sent only in response to a user’s explicit date selections, whereas MCN_SELCHANGE applies to any selection change.


NM_BASE

This notification message is sent by the HTML viewer control when it encounters a base tag in an HTML document.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 2.0 and later

Syntax

NM_BASE NM_HTMLVIEW *pnmHtmlView= (NM_HTMLVIEW *)lParam; szHREFText = pnmHtmlView->szTarget;
switch(pnmHtmlView->hdr.code) { case NM_META: };

Parameters

pnmHtmlView
Pointer to an NM_HTMLVIEW structure that contains information about the NM_BASE notification message.
szHREFText
Null-terminated string that contains the contents of the HREF parameter of the BASE tag in the HTML document.

Return Values

This notification message does not return a value.

See Also

NM_HTMLVIEW


NM_CLICK

This notification message is sent by a list view control when the user clicks an item with the left mouse button. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

NM_CLICK lpnmlv = (LPNMLISTVIEW) lParam;

Parameters

lpnmlv
Long pointer to an NMLISTVIEW structure that contains additional information about this notification message. The iItem, iSubItem and ptAction members of this structure contain information about the item.

Return Values

The return value for this notification is not used.

Remarks

This notification is identical to the standard NM_CLICK notification except that the list view supplies a NMLISTVIEW structure instead of an NMHDR structure for the lParam.


NM_CONTEXTMENU

This notification message is sent by the HTML viewer control when a user ALT+Taps in the viewer window.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 2.0 and later

Syntax

NM_CONTEXTMENU NM_HTMLCONTEXT
*pnmHtmlContext = (NM_HTMLCONTEXT*)lParam;

Parameters

pnmHtmlContext
Pointer to an NM_HTMLCONTEXT structure that contains information about the NM_CONTEXTMENU notification message.

Return Values

This notification message does not return a value.

See Also

HTMLCONTEXT, INLINEIMAGEINFO


NM_CUSTOMDRAW

This notification message is sent by some common controls to notify their parent windows about drawing operations. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

#ifdef LIST_VIEW_CUSTOM_DRAW
lpNMCustomDraw = (LPNMLVCUSTOMDRAW) lParam;
#elif TREE_VIEW_CUSTOM_DRAW
lpNMCustomDraw = (LPNMTVCUSTOMDRAW) lParam;
#else
lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;
#endif

Parameters

lpNMCustomDraw
Long pointer to a Custom Draw-related structure that contains information about the drawing operation. List view controls use the NMLVCUSTOMDRAW structure, and all other supported controls use the NMCUSTOMDRAW structure.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:

CDRF_DODEFAULT
The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW
The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE
The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE
The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT
The control will notify the parent after painting an item.

When dwDrawStage equals CDDS_ITEMPREPAINT:

CDRF_NEWFONT
Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing Fonts And Colors.
CDRF_SKIPDEFAULT
Your application drew the item manually. The control will not draw the item.

Remarks

Currently header, list view, rebar, toolbar, trackbar, and tree view controls support Custom Draw functionality.


NM_HOTSPOT

This notification message is sent by the HTML viewer control if the user taps on a link or submits a form.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

NM_HOTSPOT NM_HTMLVIEW *pnmHtmlView = (NM_HTMLVIEW *)lParam; szHREFText = pnmHtmlView->szTarget; szPostData = pnmHtmlView->szData; switch(pnmHtmlView->hdr.code) { case NM_HOTSPOT: };

Parameters

pnmHtmlView
Pointer to an NM_HTMLVIEW structure that contains information about the NM_HOTSPOT notification message.
szHREFText
Null-terminated string that contains the contents of the HREF field in the HTML text.
szPostData
Null-terminated string that contains the query data for a POST form submission.

Return Value

This message does not return a value.

Remarks

The szTarget member of the NM_HTMLVIEW structure will contain the HREF text. On the click from an anchor, the HREF text will be the contents of the HREF field. For a GET form submission, the HREF text will include the form query data. For a POST form submission, the HREF text will include only the base that is contained in the <FORM> tag, and the query data will be passed in the szData member of the NM_HTMLVIEW structure.

See Also

DTM_ANCHOR, NM_HTMLVIEW


NM_INLINE_IMAGE

This notification message is sent by the HTML viewer control to notify the application to load the image.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

NM_INLINE_IMAGE NM_HTMLVIEW *pnmHtmlView = (NM_HTMLVIEW *)lParam; szSRCText = pnmHtmlView->szTarget; dwCookieValue = pnmHtmlView->dwCookie; switch(pnmHtmlView->hdr.code) { case NM_INLINE_IMAGE: };

Parameters

pnmHtmlView
Pointer to an NM_HTMLVIEW structure that contains information about the NM_INLINE_IMAGE notification message.
szSRCText
Null-terminated string that contains the text from the SRC parameter of the IMG tag in the HTML text.
dwCookieValue
Specifies a cookie value that must be passed in the DTM_SETIMAGE or DTM_IMAGEFAIL message, from the application to the HTML control.

Return Values

This message does not return a value.

See Also

DTM_IMAGEFAIL, DTM_SETIMAGE, NM_HTMLVIEW


NM_INLINE_SOUND

This notification message is sent by the HTML viewer control to notify the application to load the sound.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

NM_INLINE_SOUND NM_HTMLVIEW *pnmHtmlView = (NM_HTMLVIEW *)lParam; szSRCText = pnmHtmlView->szTarget; dwLoopCount = pnmHtmlView->dwCookie; switch(pnmHtmlView->hdr.code) { case NM_INLINE_SOUND: };

Parameters

pnmHtmlView
Pointer to an NM_HTMLVIEW structure that contains information about the NM_INLINE_SOUND notification message.
szSRCText
Null-terminated string that contains the text from the SRC parameter of the BGSOUND tag in the HTML text.
dwLoopCount
Specifies the loop count value from the LOOP parameter of the BGSOUND tag.

Return Values

This message does not return a value.

See Also

NM_HTMLVIEW


NM_KEYDOWN

This notification message is sent by a control when the control has the keyboard focus and the user presses a key. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

NM_KEYDOWN lpnmk = (LPNMKEY) lParam;

Parameters

lpnmk
Long pointer to an NMKEY structure that contains additional information about the key that caused the notification message.

Return Values

Return nonzero to prevent the control from processing the key or zero otherwise.

Remarks

This notification is not sent by all controls. Currently, only the toolbar sends this notification.


NM_META

This notification message is sent by the HTML viewer control to notify the application and provide the HTTP-EQUIV and CONTENT parameters of the META tag in the HTML document.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

NM_META NM_HTMLVIEW *pnmHtmlView = (NM_HTMLVIEW *)lParam; szHTTPEQUIV = pnmHtmlView->szTarget; szCONTENT = pnmHtmlView->szData; switch(pnmHtmlView->hdr.code) { case NM_META: };

Parameters

pnmHtmlView
Pointer to an NM_HTMLVIEW structure that contains information about the NM_META notification message.
szHTTPEQUIV
Null-terminated string that contains the contents of the HTTP-EQUIV parameter of the META tag in the HTML document.
szCONTENT
Null-terminated string that contains the contents of the CONTENT parameter of the META tag in the HTML document.

Return Values

This message does not return a value.

Remarks

The HTML control sends the NM_TITLE message once for each META tag in the HTML document.

See Also

NM_HTMLVIEW


NM_TITLE

This notification message is sent by the HTML viewer control to notify the application and provide the title of the HTML document.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

NM_TITLE NM_HTMLVIEW *pnmHtmlView = (NM_HTMLVIEW *)lParam;
szTitle = pnmHtmlView->szTarget;
switch(pnmHtmlView->hdr.code) { case NM_TITLE: };

Parameters

pnmHtmlView
Pointer to an NM_HTMLVIEW structure that contains information about the NM_TITLE notification message.
szTitle
Null-terminated string that contains the title of the HTML document.

Return Values

This message does not return a value.

Remarks

The HTML control does not send the NM_TITLE message if the TITLE tag is missing from the HTML document.

See Also

NM_HTMLVIEW


NMUPDOWN

This structure contains information specific to up-down control notification messages. It is identical to and replaces the NM_UPDOWN structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _NM_UPDOWN {
 NMHDR hdr;
 int iPos;
 int iDelta;
} NMUPDOWN, FAR *LPNMUPDOWN;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iPos
Signed integer value that represents the up-down control’s current position.
iDelta
Signed integer value that represents the proposed change in the up-down control’s position.

Remarks

The address of this structure is specified as the lParam parameter of the WM_NOTIFY message that is used to send the UDN_DELTAPOS notification message.


PBM_DELTAPOS

This message advances the current position of a progress bar by a specified increment and redraws the bar to reflect the new position.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

PBM_DELTAPOS nIncrement = (WPARAM) wParam;

Parameters

nIncrement
Amount to advance the position.

Return Values

The previous position indicates success.


PBM_GETPOS

This message retrieves the current position of the progress bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

PBM_GETPOS wParam = 0; lParam = 0;

Return Values

Returns a UINT that represents the current position of the progress bar.


PBM_GETRANGE

This message retrieves information about the current high and low limits of a specified progress bar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

PBM_GETRANGE wParam = (WPARAM)(BOOL) fWhichLimit;
lParam = (LPARAM)(PPBRANGE) ppBRange;

Parameters

fWhichLimit
Boolean that specifies which limit value is to be used as the message’s return value. It is one of the following values:
Value
Description
TRUE | Return the low limit.
FALSE | Return the high limit.

ppBRange
Pointer to a pointer to a PBRANGE structure that is to be filled with the high and low limits of the progress bar control. If this parameter is set to NULL, the control will return only the limit specified by fWhichLimit.

Return Values

Returns an INT that represents the limit value specified by fWhichLimit. If lParam is not NULL, lParam must point to a PBRANGE structure that is to be filled with both limit values.


PBM_SETPOS

This message sets the current position for a progress bar and redraws the bar to reflect the new position.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

PBM_SETPOS nNewPos = (WPARAM) wParam;

Parameters

nNewPos
Signed integer that becomes the new position.

Return Values

The previous position indicates success.


PBM_SETRANGE

This message sets the minimum and maximum values for a progress bar and redraws the bar to reflect the new range.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

PBM_SETRANGE (nMinRange, nMaxRange) = (MAKELPARAM) lParam;

Parameters

nMinRange
Minimum range value. By default, the minimum value is zero.
nMaxRange
Maximum range value. By default, the maximum value is 100.

Return Values

The previous range values indicate success. Zero indicates otherwise. The low-order word specifies the previous minimum value, and the high-order word specifies the previous maximum value.


PBM_SETRANGE32

This message sets the range of a progress bar control to a 32-bit value.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

PBM_SETRANGE32 wParam = (WPARAM)(int) iLowLim;
lParam = (LPARAM)(int) iHighLim;

Parameters

iLowLim
Specifies a 32-bit value that represents the low limit to be set for the progress bar control.
iHighLim
Specifies a 32-bit value that represents the high limit to be set for the progress bar control.

Return Values

Returns a DWORD that holds the previous 16-bit low limit in its low-order word, and the previous 16-bit high limit in its high-order word. If the previous ranges were 32-bit values, the return value consists of the low-order words of both 32-bit limits.

Remarks

To retrieve the entire high and low 32-bit values, use the PBM_GETRANGE message.


PBM_SETSTEP

This message specifies the step increment for a progress bar. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM_STEPIT message. By default, the step increment is set to 10.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

PBM_SETSTEP nStepInc = (WPARAM) wParam;

Parameters

nStepInc
New step increment.

Return Values

The previous step increment indicates success.

See Also

PBM_STEPIT


PBM_STEPIT

This message advances the current position for a progress bar by the step increment and redraws the bar to reflect the new position. An application sets the step increment by sending the PBM_SETSTEP message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

PBM_STEPIT

Return Values

The previous position indicates success.

See Also

PBM_SETSTEP


PSM_ADDPAGE

This message adds a new page to the end of an existing property sheet. You can send this message explicitly or by using the PropSheet_AddPage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_AddPage

Syntax

PSM_ADDPAGE wParam = 0;
lParam = (LPARAM)(HPROPSHEETPAGE)hpage

Parameters

hpage
Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Values

None.


PSM_APPLY

This message simulates the choice of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_Apply

Syntax

PSM_APPLY wParam = 0; lParam = 0;

Return Values

TRUE indicates that all pages successfully applied the changes. FALSE indicates failure.

Remarks

The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages. You can send the PSM_APPLY message explicitly or by using the PropSheet_Apply macro.


PSM_CANCELTOCLOSE

This message disables the Cancel button and changes the text of the OK button to “Close.” An application sends this message after applying a change that cannot be canceled. You can send this message explicitly or by using the PropSheet_CancelToClose macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_CancelToClose

Syntax

PSM_CANCELTOCLOSE

Return Values

None.


PSM_CHANGED

This message informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button. You can send this message explicitly or by using the PropSheet_Changed macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_Changed

Syntax

PSM_CHANGED wParam = (WPARAM)(HWND) hwndPage; lParam = 0;

Parameters

hwndPage
Handle to the page that has changed.

Return Values

None.

See Also

PSM_UNCHANGED


PSM_GETCURRENTPAGEHWND

This message retrieves a handle to the window of the current page of a property sheet. You can send this message explicitly or by using the PropSheet_GetCurrentPageHwnd macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_GetCurrentPageHwnd

Syntax

PSM_GETCURRENTPAGEHWND wParam = 0; lParam = 0;

Return Values

Returns a handle to the window of the current property sheet page.

Use the PSM_GETCURRENTPAGEHWND message with modeless property sheets to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

DestroyWindow, PropertySheet


PSM_GETTABCONTROL

This message retrieves the handle of the tab control of a property sheet. You can send this message explicitly or by using the PropSheet_GetTabControl macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_GetTabControl

Syntax

PSM_GETTABCONTROL wParam = 0; lParam = 0;

Return Values

Returns the handle to the tab control.


PSM_ISDIALOGMESSAGE

This message passes a message to a property sheet dialog box and indicates whether the dialog processed the message. You can send this message explicitly or by using the PropSheet_IsDialogMessage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_IsDialogMessage

Syntax

PSM_ISDIALOGMESSAGE wParam = 0; lParam = (LPARAM) pMsg;

Parameters

pMsg
Pointer to an MSG structure that contains the message to be checked.

Return Values

TRUE indicates that the message has been processed. FALSE indicates that the message has not been processed.

Remarks

Your message loop should use the PSM_ISDIALOGMESSAGE message with modeless property sheets to pass messages to the property sheet dialog box.

If the return value indicates that the message was processed, it must not be passed to the DispatchMessage function.

See Also

DispatchMessage, MSG, PropertySheet, TranslateMessage


PSM_PRESSBUTTON

This message simulates the choice of a property sheet button. You can send this message explicitly or by using the PropSheet_PressButton macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_PressButton

Syntax

PSM_PRESSBUTTON wParam = (WPARAM)(int) iButton; lParam = 0;

Parameters

iButton
Index of the button to select. It is one of the following values:
Value
Description
PSBTN_APPLYNOW | Selects the Apply Now button.
PSBTN_BACK | Selects the Back button.
PSBTN_CANCEL | Selects the Cancel button.
PSBTN_FINISH | Selects the Finish button.
PSBTN_HELP | Selects the Help button.
PSBTN_NEXT | Selects the Next button.
PSBTN_OK | Selects the OK button.

Return Values

None.


PSM_QUERYSIBLINGS

This message is sent to a property sheet, which then forwards the message to each of its pages. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. You can send this message explicitly or by using the PropSheet_QuerySiblings macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_QuerySiblings

Syntax

PSM_QUERYSIBLINGS wParam = (WPARAM) param1;
lParam = (LPARAM) param2;

Parameters

param1
First application-defined parameter.
param2
Second application-defined parameter.

Return Values

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.


PSM_REBOOTSYSTEM

This message indicates that system needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_REBOOTSYSTEM message explicitly or by using the PropSheet_RebootSystem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_RebootSystem

Syntax

PSM_REBOOTSYSTEM wParam = 0; lParam = 0;

Return Values

None.

Remarks

This message causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user clicks the OK button to close the property sheet.

See Also

PSM_RESTARTWINDOWS, PSN_APPLY, PSN_KILLACTIVE, PropertySheet


PSM_REMOVEPAGE

This message removes a page from a property sheet. You can send this message explicitly or by using the PropSheet_RemovePage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_RemovePage

Syntax

PSM_REMOVEPAGE wParam = (WPARAM)(int) index;
lParam = (LPARAM)(HPROPSHEETPAGE)hpage;

Parameters

index
Zero-based index of the page to remove.
hpage
Handle of the page to remove.

Return Values

None.

Remarks

An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

See Also

PSM_ADDPAGE


PSM_RESTARTWINDOWS

This message indicates that Windows needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_RESTARTWINDOWS message explicitly or by using the PropSheet_RestartWindows macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_RestartWindows

Syntax

PSM_RESTARTWINDOWS wParam = 0; lParam = 0;

Return Values

None.

See Also

PSM_REBOOTSYSTEM, PSN_APPLY, PSN_KILLACTIVE, PropertySheet


PSM_SETCURSEL

This message activates the specified page in a property sheet. You can send this message explicitly or by using the PropSheet_SetCurSel macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_SetCurSel

Syntax

PSM_SETCURSEL wParam = (WPARAM)(int) index;
lParam = (LPARAM)(HPROPSHEETPAGE) hpage;

Parameters

index
Zero-based index of the page to activate.
hpage
Handle of the page to activate.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

See Also

PSN_KILLACTIVE, PSN_SETACTIVE


PSM_SETCURSELID

This message activates the specified page in a property sheet based on the resource identifier of the page. You can send this message explicitly or by using the PropSheet_SetCurSelByID macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_SetCurSelByID

Syntax

PSM_SETCURSELID wParam = 0; lParam = (LPARAM)(int) id;

Parameters

id
Resource identifier of the page to activate.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

PSN_KILLACTIVE, PSN_SETACTIVE


PSM_SETFINISHTEXT

This message sets the text of the Finish button in a wizard property sheet, shows and enables the button, and hides the Next and Back buttons. You can send this message explicitly or by using the PropSheet_SetFinishText macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | PropSheet_SetFinishText

Syntax

PSM_SETFINISHTEXT wParam = 0;
lParam = (LPARAM) (LPSTR) lpszText;

Parameters

lpszText
Long pointer to the null-terminated string that contains the new text for the Finish button.

Return Values

None.

See Also

DM_SETDEFID, PropSheet_SetFinishText


PSM_SETTITLE

This message sets the title of a property sheet. You can send this message explicitly or by using the PropSheet_SetTitle macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_SetTitle

Syntax

PSM_SETTITLE wParam = (WPARAM)(DWORD) dwStyle;
lParam = (LPARAM)(LPCSTR) lpszText;

Parameters

dwStyle
Indicates whether to include the prefix “Properties for” with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.
lpszText
Long pointer to a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Values

None.


PSM_SETWIZBUTTON

This message enables or disables the Back, Next, and Finish buttons in a wizard property sheet. You can send or post this message explicitly to a wizard property sheet, or you can use the PropSheet_SetWizButtons macro to post the message.

Syntax

PSM_SETWIZBUTTONS wParam = 0;
lParam = (LPARAM)(DWORD) dwFlags;

Parameters

dwFlags
Specifies the buttons to display and enable. It is one of the following flags:
Value
Description
PSWIZB_BACK | Enables the Back button.
PSWIZB_NEXT | Enables the Next button.
PSWIZB_FINISH | Displays an enabled Finish button in place of the Next button.
PSWIZB_DISABLEDFINISH | Displays a disabled Finish button in place of the Next button.

A wizard property sheet displays the Back button and either the Next or Finish button, which means that the PSWIZB_BACK flag is coupled with one of the other three flags.

Return Values

None.

Remarks

If you send the PSM_SETWIZBUTTON message during your handling of the PSN_SETACTIVE notification message, use the PostMessage function rather than the SendMessage function. Otherwise, the system does not update the buttons properly. At any other time, you can use SendMessage to send PSM_SETWIZBUTTON.

See Also

PostMessage, PropSheet_SetWizButtons, SendMessage


PSM_UNCHANGED

This message informs a property sheet that information in a page has reverted to the previously saved state. The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet. You can send this message explicitly or by using the PropSheet_UnChanged macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | PropSheet_UnChanged

Syntax

PSM_UNCHANGED wParam = (WPARAM)(HWND) hwndPage;
lParam = 0;

Parameters

hwndPage
Handle to the page that has reverted to the previously saved state.

Return Values

None.

See Also

PSM_CHANGED


PSN_APPLY

This notification message indicates that the user chose the OK or Apply Now button and wants all changes to take effect. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

PSN_APPLY lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lppsn
Long pointer to a PSHNOTIFY structure that contains information about the notification. The lParam member of this structure does not contain any information. The hwndFrom member of the hdr member of this structure contains the handle to the property sheet.

Return Values

Returns the PSNRET_INVALID_NOCHANGEPAGE value to prevent the changes from taking effect and to return the focus to the page, or the PSNRET_NOERROR value to accept the changes and allow the property sheet to be destroyed.

Remarks

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

A page should not call the EndDialog function when processing this notification message.

The property sheet is destroyed if the user clicks the OK button and the application returns the PSNRET_NOERROR value in response to this notification.

To receive this notification, a page must set the DWL_MSGRESULT value to FALSE in response the PSN_KILLACTIVE notification message.

See Also

EndDialog, NMHDR, PSN_KILLACTIVE, SetWindowLong


PSN_HELP

This notification message notifies a page that the user has chosen the Help button. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

PSN_HELP lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lppsn
Long pointer to a PSHNOTIFY structure that contains information about the notification. The lParam member of this structure does not contain any information. The hwndFrom member of the hdr member of this structure contains the handle to the property sheet.

Return Values

None.

See Also

NMHDR


PSN_KILLACTIVE

This notification message notifies a page that it is about to lose the activation either because another page is being activated or the user has chosen the OK button. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

PSN_KILLACTIVE lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lppsn
Long pointer to a PSHNOTIFY structure that contains information about the notification. The lParam member of this structure does not contain any information. The hwndFrom member of the hdr member of this structure contains the handle to the property sheet.

Return Values

TRUE to prevents the page from losing the activation. FALSE allows the page to lose activation.

Remarks

An application should validate the information the user has typed.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

See Also

NMHDR, SetWindowLong


PSN_QUERYCANCEL

This notification message indicates that the user chose the Cancel button. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

PSN_QUERYCANCEL lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lppsn
Long pointer to a PSHNOTIFY structure that contains information about the notification. The lParam member of this structure does not contain any information. The i member of the hdr member of this structure contains the handle to the property sheet.

Return Values

TRUE prevents the cancel operation. FALSE allows the cancel operation.

Remarks

A property sheet page can use this notification message to ask the user to verify the cancel operation.


PSN_RESET

This notification message notifies a page that the user has chosen the Cancel button and the property sheet is about to be destroyed. All changes made since the user last chose the Apply Now button are canceled. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

PSN_RESET lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lppsn
Long pointer to a PSHNOTIFY structure that contains information about the notification. If this notification is in response to the Close button being pressed, the lParam member of this structure will contain a non-zero value. If this notification is in response to the Cancel button being pressed, the lParam member of this structure will contain zero. The hwndFrom member of the hdr member of this structure contains the handle to the property sheet.

Return Values

None.

Remarks

An application can use this notification message as an opportunity to perform cleanup operations.

A page should not call the EndDialog function when processing this notification message.

See Also

EndDialog, NMHDR, SetWindowLong


PSN_SETACTIVE

This notification message notifies a page that it is about to be activated. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later

Syntax

PSN_SETACTIVE lpnmhdr = (NMHDR FAR *) lParam;

Parameters

lppsn
Long pointer to a PSHNOTIFY structure that contains information about the notification. The lParam member of this structure does not contain any information. The hwndFrom member of the hdr member of this structure contains the handle to the property sheet.

Return Values

Returns zero to accept the activation, or -1 to activate the next or the previous page (depending on whether the user clicked the Next or Back button). To set the activation to a particular page, return the resource identifier of the page.

Remarks

The PSN_SETACTIVE notification message is sent before the page is visible. An application can use this notification to initialize data in the page.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

See Also

NMHDR, SetWindowLong, WM_INITDIALOG


RB_DELETEBAND

This message deletes a band from a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_DELETEBAND wParam = (WPARAM)(UINT) uBand; lParam = 0;

Parameters

uBand
Zero-based index of the band to be deleted.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_GETBANDBORDERS

This message retrieves the borders of a band. The result of this message can be used to calculate the usable area in a band.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETBANDBORDERS wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

uBand
Zero-based index of the band for which the borders will be retrieved.
lprc
Long pointer to a RECT structure that receives the band borders. If the rebar control has the RBS_BANDBORDERS style, each member of this structure will receive the number of pixels on the corresponding side of the band that are used by the band. If the rebar control does not have the RBS_BANDBORDERS style, only the left member of this structure receives valid information.

Return Values

The return value is not used.


RB_GETBANDCOUNT

This message retrieves the count of bands currently in the rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETBANDCOUNT wParam = 0; lParam = 0;

Return Values

Returns a UINT value that represents the number of bands assigned to the control.


RB_GETBANDINFO

This message retrieves information about a specified band in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETBANDINFO wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;

Parameters

uBand
Zero-based index of the band for which the information is retrieved.
lprbbi
Long pointer to a REBARBANDINFO structure that receives the requested band information. Set the cbSize member of this structure to sizeof(REBARBANDINFO) and set the fMask parameter to the items you want to retrieve before sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_GETBARHEIGHT

This message retrieves the height the rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETBARHEIGHT wParam = 0; lParam = 0;

Return Values

Returns a UINT value that represents the height, in pixels, of the control.


RB_GETBARINFO

This message retrieves information about the rebar control and the image list it uses.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETBARINFO wParam = 0;
lParam = (LPARAM)(LPREBARINFO) lprbi;

Parameters

lprbi
Long pointer to a REBARINFO structure that receives the rebar control information. Set the cbSize member of this structure to sizeof(REBARINFO) before sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_GETBKCOLOR

This message retrieves a rebar control’s default background color.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETBKCOLOR wParam = 0; lParam = 0;

Return Values

Returns a COLORREF value that represent the current default background color.


RB_GETRECT

This message retrieves the bounding rectangle for a specified band in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETRECT wParam = (WPARAM)(INT) iBand;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

iBand
Zero-based index of a band in the rebar control.
lprc
Long pointer to a RECT structure that receives the bounds of the rebar band.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_GETROWCOUNT

This message retrieves the number of band rows in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETROWCOUNT wParam = 0; lParam = 0;

Return Values

Returns a UINT value that represents the number of band rows in the control.


RB_GETROWHEIGHT

This message retrieves the height of a specified row in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETROWHEIGHT wParam = (WPARAM)(UINT) uRow; lParam = 0;

Parameters

uRow
Zero-based index of a band. The height of the row that contains the specified band will be retrieved.

Return Values

Returns a UINT value that represents the row height, in pixels.

Remarks

To retrieve the number of rows in a rebar control, use the RB_GETROWCOUNT message.


RB_GETTEXTCOLOR

This message retrieves a rebar control’s default text color.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_GETTEXTCOLOR wParam = 0; lParam = 0;

Return Values

Returns a COLORREF value that represent the current default text color.


RB_HITTEST

This message determines which portion of a rebar band is at a specified point on the screen, if a rebar band exists at that point.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_HITTEST wParam = 0;
lParam = (LPARAM)(LPRBHITTESTINFO) lprbht;

Parameters

lprbht
Long pointer to an RBHITTESTINFO structure. Before sending the message, the pt member of this structure must be initialized to the point that is hit tested, in client coordinates.

Return Values

Returns the zero-based index of the band at the specified point, or –1 if no rebar band was at the point.


RB_IDTOINDEX

This message converts a band identifier to a band index in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_IDTOINDEX wParam = (WPARAM)(UINT) uBandID; lParam = 0;

Parameters

uBandID
Application-defined identifier of the band in question. This is the value that is passed in the wID member of the REBARBANDINFO structure when the band was inserted.

Return Values

Returns the zero-based band index if successful, or –1 otherwise. If duplicate band IDs exist, the first one is returned.


RB_INSERTBAND

This message inserts a new band in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_INSERTBAND wParam = (WPARAM)(UINT) uIndex;
lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;

Parameters

uIndex
Zero-based index of the location where the band will be inserted. If you set this parameter to –1, the control will add the new band at the last location.
lprbbi
Long pointer to a REBARBANDINFO structure that defines the band to be inserted. Set the cbSize member of this structure to sizeof(REBARBANDINFO) before sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_MAXIMIZEBAND

This message resizes a band in a rebar control to its ideal or largest size.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_MAXIMIZEBAND wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(BOOL) fIdeal;

Parameters

uBand
Zero-based index of the band to be maximized.
fIdeal
Boolean that specifies whether the ideal width of the band should be used when the band is maximized. If this value is nonzero, the ideal width is used. If this value is zero, the band is made as large as possible.

Return Values

The return value is not used.


RB_MINIMIZEBAND

This message resizes a band in a rebar control to its smallest size.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_MINIMIZEBAND wParam = (WPARAM)(UINT) uBand; lParam = 0;

Parameters

uBand
Zero-based index of the band to be minimized.

Return Values

The return value is not used.


RB_SETBANDINFO

This message sets characteristics of an existing band in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SETBANDINFO wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;

Parameters

uBand
Zero-based index of the band to receive the new settings.
lprbbi
Long pointer to a REBARBANDINFO structure that contains the new settings. Set the cbSize member of this structure to sizeof(REBARBANDINFO) before sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_SETBARINFO

This message sets the characteristics of a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SETBARINFO wParam = 0;
lParam = (LPARAM)(LPREBARINFO) lprbi;

Parameters

lprbi
Long pointer to a REBARINFO structure that contains the information to be set. Set the cbSize member of this structure to sizeof(REBARINFO) before sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.

Remarks

When the fMask member of the REBARINFO structure specifies an invalid value, this message returns TRUE when it should return FALSE.


RB_SETBKCOLOR

This message sets a rebar control’s default background color.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SETBKCOLOR wParam = 0; lParam = (LPARAM)(COLORREF)clrBk;

Parameters

clrBk
COLORREF value that represents the new default background color.

Return Values

Returns a COLORREF value that represents the previous default background color.

Remarks

The rebar control’s default background color is used to draw the background in a rebar control and all bands that are added after this message has been sent. The default background color for a particular band can be overridden by setting the RBBIM_COLORS flag in fMask and setting clrBack in the REBARBANDINFO structure when a band is added or modified.


RB_SETPARENT

This message sets a rebar control’s parent window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SETPARENT wParam = (WPARAM)(HWND) hwndParent; lParam = 0;

Parameters

hwndParent
Handle to the parent window to be set.

Return Values

Returns the handle to the previous parent window, or NULL if there is no previous parent.

Remarks

The rebar control sends notification messages to the window you specify with this message. This message does not change the actual parent that was set when the control was created.


RB_SETTEXTCOLOR

This message sets a rebar control’s default text color.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SETTEXTCOLOR wParam = 0;
lParam = (LPARAM)(COLORREF)clrText;

Parameters

clrText
COLORREF value that represents the new default text color.

Return Values

Returns a COLORREF value that represents the previous default text color.

Remarks

The rebar control’s default text color is used to draw the text in a rebar control and all bands that are added after this message has been sent. The default text color for a particular band can be overridden by setting the RBBIM_COLORS flag in fMask and setting clrFore in the REBARBANDINFO structure when a band is added or modified.


RB_SHOWBAND

This message shows or hides a specified band in a rebar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SHOWBAND wParam = (WPARAM)(INT) iBand;
lParam = (LPARAM)(BOOL) fShow;

Parameters

iBand
Zero-based index of a band in the rebar control.
fShow
Boolean that indicates if the band should be shown or hidden. If this value is nonzero, the band is shown. Otherwise, the band is hidden.

Return Values

Nonzero indicates success. Zero indicates otherwise.


RB_SIZETORECT

This message tries to fit a rebar control to a specified rectangle.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RB_SIZETORECT wParam = 0; lParam = (LPARAM)(LPRECT) prc;

Parameters

prc
Pointer to a RECT structure that specifies the rectangle that the rebar control should be sized to.

Return Values

Returns nonzero if a layout change occurred, or zero otherwise.

Remarks

The rebar bands will be wrapped as necessary to fit the rectangle. Bands that have the RBBS_VARIABLEHEIGHT style will be resized as evenly as possible to fit the rectangle.


RBN_AUTOSIZE

This message is sent to the parent by a rebar control created with the RBS_AUTOSIZE style when the rebar automatically resizes itself. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RBN_AUTOSIZE lpnmas = (LPNMRBAUTOSIZE) lParam;

Parameters

lpnmas
Long pointer to a NMRBAUTOSIZE structure that contains information about the resize operation.

Return Values

The return value for this notification is not used.


RBN_BEGINDRAG

This message is sent by a rebar control when the user begins dragging a band. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RBN_BEGINDRAG lpnmrb = (LPNMREBAR)lParam;

Parameters

lpnmrb
Long pointer to a NMREBAR structure that contains information about the notification.

Return Values

Return zero to allow the rebar to continue the drag operation or nonzero to abort the drag operation.


RBN_ENDDRAG

This message is sent by a rebar control when the user stops dragging a band. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RBN_ENDDRAG lpnmrb = (LPNMREBAR)lParam;

Parameters

lpnmrb
Long pointer to a NMREBAR structure that contains information about the notification.

Return Values

The return value for this notification is not used.


RBN_HEIGHTCHANGE

This notification message is sent by a rebar control when its height has changed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RBN_HEIGHTCHANGE lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Long pointer to an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.

Remarks

Rebar controls that use the CCS_VERT style send this notification message when their width changes.


RBN_LAYOUTCHANGED

This notification message is sent by a rebar control when you change the layout of the control’s bands. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

RBN_LAYOUTCHANGED lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Long pointer to an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.


SB_GETBORDERS

This message retrieves the current widths of the horizontal and vertical borders of a status window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_GETBORDERS wParam = 0; lParam = (LPARAM)(LPINT) aBorders;

Parameters

aBorders
Address of an integer array that has three elements. The first element receives the width of the horizontal border, the second receives the width of the vertical border, and the third receives the width of the border between rectangles.

Return Values

TRUE indicates success. FALSE indicates failure.


SB_GETPARTS

This message retrieves a count of the parts in a status window. The message also retrieves the coordinate of the right edge of the specified number of parts.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_GETPARTS wParam = (WPARAM) nParts;
lParam = (LPARAM)(LPINT) aRightCoord;

Parameters

nParts
Number of parts for which to retrieve coordinates. If this parameter is greater than the number of parts in the window, the message retrieves coordinates for existing parts only.
aRightCoord
Address of an integer array that has the same number of elements as parts specified by nParts. Each element in the array receives the client coordinate of the right edge of the corresponding part. If an element is set to –1, the position of the right edge for that part extends to the right edge of the window. To retrieve the current number of parts, set this parameter to zero.

Return Values

The number of parts in the window indicates success. Zero indicates failure.

See Also

SB_SETPARTS


SB_GETRECT

This message retrieves the bounding rectangle of a part in a status window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_GETRECT wParam = (WPARAM) iPart;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

iPart
Zero-based index of the part whose bounding rectangle is to be retrieved.
lprc
Long pointer to a RECT structure that receives the bounding rectangle.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

RECT


SB_GETTEXT

This message retrieves the text from the specified part of a status window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_GETTEXT wParam = (WPARAM) iPart;
lParam = (LPARAM)(LPSTR) szText;

Parameters

iPart
Zero-based index of the part from which to retrieve text.
szText
Address of the buffer that receives the text. This parameter is a null-terminated string.

Return Values

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of the following values:

Value
Description
0 | The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS | The text is drawn without borders.
SBT_POPOUT | The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING | Displays text using right-to-left reading order on Hebrew or Arabic systems.

See Also

SB_GETTEXTLENGTH, SB_SETTEXT


SB_GETTEXTLENGTH

This message retrieves the length, in characters, of the text from the specified part of a status window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_GETTEXTLENGTH wParam = (WPARAM) iPart; lParam = 0;

Parameters

iPart
Zero-based index of the part from which to retrieve text.

Return Values

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of the following values:

Value
Description
0 | The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS | The text is drawn without borders.
SBT_OWNERDRAW | The text is drawn by the parent window.
SBT_POPOUT | The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING | Displays text using right-to-left reading order on Hebrew or Arabic systems.

See Also

SB_GETTEXT, SB_SETTEXT


SB_ISSIMPLE

This message checks a status window control to determine if it is in simple mode.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

SB_ISSIMPLE wParam = 0; lParam = 0;

Return Values

Returns nonzero if the status window control is in simple mode, or zero otherwise.


SB_SETMINHEIGHT

This message sets the minimum height of a status window’s drawing area.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_SETMINHEIGHT wParam = (WPARAM) minHeight; lParam = 0;

Parameters

minHeight
Minimum height, in pixels, of the window.

Return Values

None.


SB_SETPARTS

This message sets the number of parts in a status window and the coordinate of the right edge of each part.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_SETPARTS wParam = (WPARAM) nParts;
lParam = (LPARAM)(LPINT) aWidths;

Parameters

nParts
Number of parts to set (cannot be greater than 255).
aWidths
Address of an integer array that has the same number of elements as parts specified by nParts. Each element in the array specifies the position, in client coordinates, of the right edge of the corresponding part. If an element is –1, the position of the right edge for that part extends to the right edge of the window.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

SB_GETPARTS


SB_SETTEXT

This message sets the text in the specified part of a status window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_SETTEXT wParam = (WPARAM) iPart | uType;
lParam = (LPARAM)(LPSTR) szText;

Parameters

iPart
Zero-based index of the part to set. If this value is 255, the status window is assumed to be a simple window having only one part.
uType
Type of drawing operation. It is one of the following values:
Value
Description
0 | The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS | The text is drawn without borders.
SBT_OWNERDRAW | The text is drawn by the parent window.
SBT_POPOUT | The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING | Displays text using right-to-left reading order on Hebrew or Arabic systems.

szText
Null-terminated string that specifies the text to set. If uType is SBT_OWNERDRAW, this parameter represents 32 bits of data. The parent window must interpret the data and draw the text when it receives the WM_DRAWITEM message. The text for each part is limited to 127 characters.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

SB_GETTEXT, WM_DRAWITEM


SB_SIMPLE

This message specifies whether a status window displays simple text or displays all window parts set by a previous SB_SETPARTS message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

SB_SIMPLE wParam = (WPARAM)(BOOL) fSimple; lParam = 0;

Parameters

fSimple
Boolean value that is set to TRUE if the window displays simple text, or to FALSE if it displays multiple parts.

Return Values

FALSE indicates that an error has occurred.

See Also

SB_SETPARTS


SBM_GETPOS

This message is sent by an application to retrieve the current position of the scroll box of a scroll bar control. The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 0 through 100 and the scroll box is in the middle of the bar, the current position is 50.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

SBM_GETPOS wParam = 0; lParam = 0;

Return Values

The current position of the scroll box in the scroll bar indicates success.

See Also

SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_GETRANGE

This message is sent by an application to a scroll bar control to retrieve the minimum and maximum position values for the control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

SBM_GETRANGE wParam = (WPARAM) (LPINT) lpnMinPos;
lParam = (LPARAM) (LPINT) lpnMaxPos;

Parameters

lpnMinPos
Long pointer to a value that receives the minimum scrolling position.
lpnMaxPos
Long pointer to a value that receives the maximum scrolling position.

Return Values

None.

See Also

SBM_GETPOS, SBM_SETPOS, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_GETSCROLLINFO

This message is sent by an application to retrieve the parameters of a scroll bar.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

SBM_GETSCROLLINFO wParam = 0;
lParam = (LPARAM) (LPSCROLLINFO) lpsi;

Parameters

lpsi
Long pointer to a SCROLLINFO structure. Before sending the message, set the cbSize member of the structure to sizeof(SCROLLINFO), and set the fMask member to specify the scroll bar parameters to retrieve. Before returning, the message copies the specified parameters to the appropriate members of the structure.

The fMask member can be a combination of the following values:
Value
Description
SIF_ALL | Combines SIF_PAGE, SIF_POS, SIF_RANGE, and SIF_TRACKPOS.
SIF_PAGE | Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS | Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE | Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
SIF_TRACKPOS | Copies the current scroll box tracking position to the nTrackPos member of the SCROLLINFO structure pointed to by lpsi.

Return Values

TRUE indicates that the message retrieved at least one value. FALSE indicates otherwise.

Remarks

The messages that indicate scroll-bar position, WM_HSCROLL and WM_VSCROLL, provide only 16 bits of position data. However, the SCROLLINFO structure used by SBM_GETSCROLLINFO, SBM_SETSCROLLINFO, GetScrollInfo, and SetScrollInfo provides 32 bits of scroll-bar position data. You can use these messages and functions while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll-bar position data.

To get the 32-bit position of the scroll box (thumb) during a SB_THUMBTRACK notification in a WM_HSCROLL or WM_VSCROLL message, send SBM_GETSCROLLINFO with the SIF_TRACKPOS value in the fMask member of the SCROLLINFO structure. The message returns the tracking position of the scroll box in the nTrackPos member of the SCROLLINFO structure. This allows you to get the position of the scroll box as the user moves it. Alternatively, you can use the GetScrollInfo function to get the same information.

See Also

SBM_SETSCROLLINFO, SCROLLINFO


SBM_SETPOS

This message is sent by an application to a scroll bar control to set the position of the scroll box (thumb) and, if requested, redraw the scroll bar to reflect the new position of the scroll box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

SBM_SETPOS wParam = (WPARAM) nPos;
lParam = (LPARAM) (BOOL) fRedraw;

Parameters

nPos
Specifies the new position of the scroll box. It must be within the scrolling range.
fRedraw
Boolean value that specifies whether the scroll bar should be redrawn to reflect the new scroll box position. If set to TRUE, the scroll bar is redrawn. If set to FALSE, the scroll bar is not redrawn.

Return Values

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

If the scroll bar control is redrawn by a subsequent call to another function, setting the fRedraw parameter to FALSE is useful.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_SETRANGE

This message is sent by an application to a scroll bar control to set the minimum and maximum position values for the control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

SBM_SETRANGE wParam = (WPARAM) nMinPos;
lParam = (LPARAM) nMaxPos;

Parameters

nMinPos
Specifies the minimum scrolling position.
fMaxPos
Specifies the maximum scrolling position.

Return Values

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

The default minimum and maximum position values are zero. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

If the minimum and maximum position values are equal, the scroll bar control is hidden and, in effect, disabled.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGEREDRAW


SBM_SETRANGEREDRAW

This message is sent by an application to a scroll bar control to set the minimum and maximum position values and to redraw the control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

SBM_SETRANGEREDRAW wParam = (WPARAM) nMinPos;
lParam = (LPARAM) nMaxPos

Parameters

nMinPos
Specifies the minimum scrolling position.
fMaxPos
Specifies the maximum scrolling position.

Return Values

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

The default minimum and maximum position values are zero. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

If the minimum and maximum position values are equal, the scroll bar control is hidden and, in effect, disabled.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGE


SBM_SETSCROLLINFO

This message is sent by an application to set the parameters of a scroll bar.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

SBM_SETSCROLLINFO wParam = (WPARAM) fRedraw;
lParam = (LPARAM) (LPSCROLLINFO) lpsi;

Parameters

fRedraw
Boolean value that specifies whether the scroll bar is redrawn to reflect the new scroll box position. If set to TRUE, the scroll bar is redrawn. If set to FALSE, the scroll bar is not redrawn.
lpsi
Long pointer to a SCROLLINFO structure. Before sending the message, set the cbSize member of the structure to sizeof(SCROLLINFO), set the fMask member to indicate the parameters to set, and specify the new parameter values in the appropriate members.

The fMask member can be a combination of the following values:
Value
Description
SIF_DISABLENOSCROLL | Disables the scroll bar instead of removing it, if the scroll bar’s new parameters make the scroll bar unnecessary.
SIF_PAGE | Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS | Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE | Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.

Return Values

The current position of the scroll box indicates success.

Remarks

The messages that indicate scroll-bar position, WM_HSCROLL and WM_VSCROLL, provide only 16 bits of position data. However, the SCROLLINFO structure used by SBM_GETSCROLLINFO, SBM_SETSCROLLINFO, GetScrollInfo, and SetScrollInfo provides 32 bits of scroll-bar position data. You can use these messages and functions while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll-bar position data.

In Windows CE version 2.0, if you pass a null pointer in the lpsi parameter (lParam), SBM_SETSCROLLINFO returns zero, rather than the current position of the scroll box. For Windows CE versions 2.10 and later, the current position of the scroll box is returned.

See Also

SBM_GETSCROLLINFO, SCROLLINFO


SBN_SIMPLEMODECHANGE

This notification message sent by a status window control when the simple mode changes due to a SB_SIMPLE message. The SBN_SIMPLEMODECHANGE notification message is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

SBN_SIMPLEMODECHANGE lpnmh = (NMHDR*) lParam;

Parameters

lpnmh
Long pointer to an NMHDR structure that contains information about the notification.


STM_GETIMAGE

This message is sent by an application to retrieve the handle of the image associated with a static control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

STM_GETIMAGE wParam = (WPARAM) fImageType; lParam = 0;

Parameters

fImageType
Specifies the type of image to retrieve. It is one of the following values:
  • IMAGE_BITMAP
  • IMAGE_ICON

Return Values

A handle to the image, if any, indicates success. NULL indicates otherwise.

See Also

STM_SETIMAGE


STM_SETIMAGE

This message is sent by an application to associate a new image—icon or bitmap—with a static control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

STM_SETIMAGE wParam = (WPARAM) fImageType;
lParam = (LPARAM)(HANDLE) hImage;

Parameters

fImageType
Specifies the type of image to associate with the static control. It is one of the following values:
  • IMAGE_BITMAP
  • IMAGE_ICON
hImage
Handle to the image to associate with the static control.

Return Values

A handle to the image previously associated with the static control, if any, indicates success. NULL indicates otherwise.

See Also

STM_GETIMAGE


STN_CLICKED

This notification message is sent when the user clicks a static control that has the SS_NOTIFY style. The parent window of the control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

STN_CLICKED idStatic = (int) LOWORD(wParam);
hwndStatic = (HWND) LOWORD(lParam);

Parameters

idStatic
Identifier of the static control.
hwndStatic
Handle to the static control.

See Also

WM_COMMAND


STN_DISABLE

This notification message is sent when a static control is disabled. The static control must have the SS_NOTIFY style to receive this notification message. The parent window of the control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

STN_DISABLE idStatic = (int)LOWORD(wParam);
hwndStatic = (HWND)LOWORD(lParam);

Parameters

idStatic
Identifier of the static control.
hwndStatic
Handle to the static control.

See Also

STN_ENABLE, WM_COMMAND


STN_ENABLE

This notification message is sent when a static control is enabled. The static control must have the SS_NOTIFY style to receive this notification message. The parent window of the control receives this notification message through the WM_COMMAND message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

STN_ENABLE idStatic = (int)LOWORD(wParam);
hwndStatic = (HWND)LOWORD(lParam);

Parameters

idStatic
Identifier of the static control.
hwndStatic
Handle to the static control.

See Also

STN_DISABLE, WM_COMMAND


TB_ADDBITMAP

This message adds one or more images to the list of button images available for a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ADDBITMAP wParam = (WPARAM) nButtons;
lParam = (LPARAM)(LPTBADDBITMAP) lptbab;

Parameters

nButtons
Number of button images in the bitmap. If lptbab specifies a system-defined bitmap, this parameter is ignored.
lptbab
Long pointer to a TBADDBITMAP structure that contains the identifier of a bitmap resource and the handle to the module instance with the executable file that contains the bitmap resource.

Return Values

The index of the first new image indicates success. –1 indicates failure.

Remarks

The bitmap specified in the lptbab parameter can contain multiple images. The number of images in the bitmap must be specified in the nButtons parameter.

The bitmap width should be nButtons multiplied by the image width, and the bitmap height should be equal to the image height.

The default image width is 16 pixels and the default image height is 15 pixels. The default image width and height can be changed using TB_SETBITMAPSIZE. If the size of the bitmap is not the default or if you have multiple images in a bitmap, you must call TB_SETBITMAPSIZE to change the default size settings.

See Also

CreateWindowEx, TBADDBITMAP, TB_BUTTONSTRUCTSIZE, TB_SETBITMAPSIZE


TB_ADDBUTTONS

This message adds one or more buttons to a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ADDBUTTONS wParam = (WPARAM)(UINT) uNumButtons;
lParam = (LPARAM)(LPTBBUTTON) lpButtons;

Parameters

uNumButtons
Number of buttons to add.
lpButtons
Long pointer to an array of TBBUTTON structures that contain information about the buttons to add. There must be the same number of elements in the array as buttons specified by uNumButtons.

Return Values

True indicates success. FALSE indicates failure.

See Also

CreateWindowEx, TBBUTTON, TB_BUTTONSTRUCTSIZE


TB_ADDSTRING

This message adds a new string to the list of strings available for a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ADDSTRING wParam = (WPARAM)(HINSTANCE) hinst;
lParam = (LPARAM)MAKELONG(idString,0);

Parameters

hinst
Handle to the module instance with an executable file that contains the string resource. If idString points to one or more strings to add, this parameter is zero.
idString
Resource identifier of the string resource, or the address of a buffer that contains one or more null-terminated strings to add to the list, depending on the value of hinst. The last string must be terminated with two null characters.

Return Values

The index of the first new string indicates success. –1 indicates failure.

Remarks

The resource identifier in the idString parameter has to reference a single string without substrings or separators.


TB_AUTOSIZE

This message causes a toolbar to be resized.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_AUTOSIZE wParam = 0; lParam = 0;

Return Values

None.


TB_BUTTONCOUNT

This message retrieves a count of the buttons currently in the toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_BUTTONCOUNT wParam = 0; lParam = 0;

Return Values

The count of the buttons indicates success.


TB_BUTTONSTRUCTSIZE

This message specifies the size of the TBBUTTON structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_BUTTONSTRUCTSIZE wParam = (WPARAM) cb; lParam = 0;

Parameters

cb
Size, in bytes, of the TBBUTTON structure.

Return Values

None.

Remarks

The system uses the size to determine which version of the common control dynamic-link library (DLL) is being used.

See Also

CreateWindowEx, TB_ADDBITMAP, TB_ADDBUTTONS, TBBUTTON


TB_CHANGEBITMAP

This message changes the bitmap for a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_CHANGEBITMAP wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELPARAM(iBitmap,0);

Parameters

idButton
Command identifier of the button that is to receive a new bitmap.
iBitmap
Zero-based index of an image in the toolbar's image list. The system displays the specified image in the button.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_CHECKBUTTON

This message checks or unchecks a specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_CHECKBUTTON wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELONG(fCheck,0);

Parameters

idButton
Command identifier of the button to check.
fCheck
Check flag. If set to TRUE, the check is added. If set to FALSE, the check is removed.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_COMMANDTOINDEX

This message retrieves the zero-based index for the button associated with the specified command identifier.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_COMMANDTOINDEX wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier associated with the button.

Return Values

The zero-based index for the button indicates success.


TB_DELETEBUTTON

This message deletes a button from the toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_DELETEBUTTON wParam = (WPARAM) iButton; lParam = 0;

Parameters

iButton
Zero-based index of the button to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_ENABLEBUTTON

This message enables or disables the specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ENABLEBUTTON wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELONG(fEnable,0);

Parameters

idButton
Command identifier of the button to enable or disable.
fEnable
Enable flag. If set to TRUE, the button is enabled. If set to FALSE, the button is disabled.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_GETBITMAP

This message retrieves the index of the bitmap associated with a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETBITMAP wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button whose bitmap index is to be retrieved.

Return Values

The index of the bitmap indicates success. Zero indicates failure.


TB_GETBITMAPFLAGS

This message retrieves the flags for the current bitmap.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETBITMAPFLAGS wParam = 0; lParam = 0;

Return Values

Returns a DWORD value that contains the bitmap flags. If this value is zero, the toolbar is using a small bitmap. If the TBBF_LARGE flag is set, the toolbar is using a large bitmap.


TB_GETBUTTON

This message retrieves information about the specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETBUTTON wParam = (WPARAM) iButton;
lParam = (LPARAM)(LPTBBUTTON) lpButton;

Parameters

iButton
Zero-based index of the button for which to retrieve information.
lpButton
Long pointer to the TBBUTTON structure that receives the button information.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TBBUTTON


TB_GETBUTTONINFO

This message retrieves the information for a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETBUTTONINFO wParam = (WPARAM)(INT) iID;
lParam = (LPARAM)(LPTBBUTTONINFO) lptbbi;

Parameters

iID
Button identifier.
lptbbi
Long pointer to a TBBUTTONINFO structure that receives the button information. The cbSize and dwMask members of this structure must be filled in prior to sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_GETBUTTONSIZE

This message retrieves the current width and height of toolbar buttons, in pixels.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETBUTTONSIZE wParam = 0; lParam = 0;

Return Values

Returns a DWORD value that contains the width and height values in the low-order word and high-order word, respectively.


TB_GETBUTTONTEXT

This message retrieves the text of a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETBUTTONTEXT wParam = (WPARAM) idButton;
lParam = (LPARAM)(LPSTR) lpszText;

Parameters

idButton
Command identifier of the button for which to retrieve text.
lpszText
Long pointer to a buffer that receives the button text.

Return Values

The length—in characters and not including the terminating null character—of the string copied to the specified buffer indicates success. –1 indicates failure.


TB_GETDISABLEDIMAGELIST

This message retrieves the image list that a toolbar control uses to display disabled buttons.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETDISABLEDIMAGELIST wParam = 0; lParam = 0;

Return Values

Returns the handle to the disabled image list or NULL if no disabled image list is set.


TB_GETIMAGELIST

This message retrieves the image list that a toolbar control uses to display buttons in their default state. A toolbar control uses this image list to display buttons in their default state; that is, when they are not hot or disabled.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETIMAGELIST wParam = 0; lParam = 0;

Return Values

Returns the handle to the image list or NULL if no image list is set.


TB_GETITEMRECT

This message retrieves the bounding rectangle of a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETITEMRECT wParam = (WPARAM) iButton;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

iButton
Zero-based index of the button for which to retrieve information.
lprc
Long pointer to a RECT structure that receives the coordinates of the bounding rectangle.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

RECT


TB_GETRECT

This message retrieves the bounding rectangle for a specified toolbar button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETRECT wParam = (WPARAM)(INT) iID;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

iID
Button identifier.
lprc
Returns nonzero if successful, or zero otherwise. A RECT structure that receives the bounding rectangle information.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_GETROWS

This message retrieves the number of rows of buttons in a toolbar with the TBSTYLE_WRAPABLE style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETROWS wParam = 0; lParam = 0;

Return Values

The number of rows indicates success.


TB_GETSTATE

This message retrieves information about the state of the specified button in a toolbar, such as whether it is enabled, pressed, or checked.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETSTATE wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button for which to retrieve information.

Return Values

The button state information indicates success. –1 indicates failure. The button state information can be a combination of values. For information about toolbar button state values, see the Windows CE User Interface Services Guide.


TB_GETSTYLE

This message retrieves the styles currently in use for a toolbar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETSTYLE wParam = 0; lParam = 0;

Return Values

Returns a DWORD value that is a combination of toolbar control styles.


TB_GETTEXTROWS

This message retrieves the maximum number of text rows that can be displayed on a toolbar button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_GETTEXTROWS wParam = 0; lParam = 0;

Return Values

Returns an INT value representing the maximum number of text rows that the control displays for a button.


TB_GETTOOLTIPS

This message retrieves the handle to the ToolTip control, if any, associated with the toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_GETTOOLTIPS

Return Values

Returns the handle to the ToolTip control, or NULL if the toolbar has no associated ToolTip.


TB_HIDEBUTTON

This message hides or shows the specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_HIDEBUTTON wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELONG(fShow,0);

Parameters

idButton
Command identifier of the button to hide or show.
fShow
Show flag. If set to TRUE, the button is hidden. If set to FALSE, the button is shown.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_HIGHLIGHTBUTTON

This message sets the highlight state of a specified button in a toolbar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_HIGHLIGHTBUTTON wParam = (WPARAM) idButton;
lParam = (LPARAM) MAKELONG(fHighlight,0);

Parameters

idButton
Command identifier for a toolbar button.
fHighlight
Boolean that specifies the highlight state to be set. If this value is TRUE, the button is highlighted; if FALSE, the button is set to its default state.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_INDETERMINATE

This message sets or clears the indeterminate state of the specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_INDETERMINATE wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELONG(fIndeterminate,0);

Parameters

idButton
Command identifier of the button for which indeterminate state is to be set or cleared.
fIndeterminate
Indeterminate flag. If set to TRUE, the indeterminate state is set. If set to FALSE, the state is cleared.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_INSERTBUTTON

This message inserts a button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_INSERTBUTTON wParam = (WPARAM) iButton;
lParam = (LPARAM)(LPTBBUTTON) lpButton;

Parameters

iButton
Zero-based index of a button. The message inserts the new button to the left of this button.
lpButton
Long pointer to a TBBUTTON structure that contains information about the button to insert.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TBBUTTON


TB_ISBUTTONCHECKED

This message determines whether the specified button in a toolbar is checked.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ISBUTTONCHECKED wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Nonzero indicates that the button is checked. Zero indicates otherwise.


TB_ISBUTTONENABLED

This message determines whether the specified button in a toolbar is enabled.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ISBUTTONENABLED wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Nonzero indicates that the button is enables. Zero indicates that the button is disabled.


TB_ISBUTTONHIDDEN

This message determines whether the specified button in a toolbar is hidden.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ISBUTTONHIDDEN wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Nonzero indicates that the button is hidden. Zero indicates otherwise.


TB_ISBUTTONHIGHLIGHTED

This message checks the highlight state of a toolbar button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_ISBUTTONHIGHLIGHTED wParam = (WPARAM) idButton;
lParam = 0;

Parameters

idButton
Command identifier for a toolbar button.

Return Values

Nonzero indicates that the button is highlighted. Zero indicates otherwise.


TB_ISBUTTONINDETERMINATE

This message determines whether the specified button in a toolbar is indeterminate.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ISBUTTONINDETERMINATE wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Nonzero indicates that the button is indeterminate. Zero indicates otherwise.


TB_ISBUTTONPRESSED

This message determines whether the specified button in a toolbar is pressed.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_ISBUTTONPRESSED wParam = (WPARAM) idButton; lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Nonzero indicates that the button is pressed. Zero indicates otherwise.


TB_LOADIMAGES

This message loads bitmaps into a toolbar control’s image list.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_LOADIMAGES wParam = (WPARAM)(INT) iBitmapID;
lParam = (LPARAM)(HINSTANCE) hinst;

Parameters

iBitmapID
Identifier of a bitmap that contains the images to be loaded. If hinst is HINST_COMMCTRL, this parameter specifies a set of standard toolbar button bitmaps, shown in the following list. Otherwise, this parameter must be the identifier of a bitmap resource that will be added to the image list as a single image.
Value
Description
IDB_STD_LARGE_COLOR | Standard bitmaps in large size
IDB_STD_SMALL_COLOR | Standard bitmaps in small size
IDB_VIEW_LARGE_COLOR | View bitmaps in large size
IDB_VIEW_SMALL_COLOR | View bitmaps in small size

hinst
Program instance handle to the calling application. This parameter can be HINST_COMMCTRL to load a standard image list.

Return Values

Returns an INT value that represents the count of images in the image list, not including the one just added. Returns zero if the toolbar has no image list or if the existing image list is empty.

Remarks

If your application specifies HINST_COMMCTRL, then you must use the proper image index values when you prepare TBBUTTON structures prior to sending the TB_ADDBUTTONS message. For a list of image index values for these preset bitmaps, see “Toolbar Standard Button Image Index Values.”

Windows CE does not support IDB_HIST_LARGE_COLOR and IDB_HIST_SMALL_COLOR values for the iBitmapID parameter.


TB_PRESSBUTTON

This message releases the specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_PRESSBUTTON wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELONG(fPress,0);

Parameters

idButton
Command identifier of the button to press or release.
fPress
Press flag. If set to TRUE, the button is pressed. If set to FALSE, the button is released.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_REPLACEBITMAP

This message replaces an existing bitmap with a new bitmap.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_REPLACEBITMAP wParam = 0;
lParam = (LPARAM) (LPTBREPLACEBITMAP) ptbrb;

Parameters

ptbrb
Pointer to a TBREPLACEBITMAP structure that contains the information of the bitmap to be replaced and the new bitmap.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_SETBITMAPSIZE

This message sets the size of the bitmapped images to be added to a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETBITMAPSIZE wParam = 0;
lParam = (LPARAM)MAKELONG(dxBitmap,dyBitmap);

Parameters

dxBitmap
Specifies the width, in pixels, of the bitmapped images.
dyBitmap
Specifies the height, in pixels, of the bitmapped images.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The default image width is 16 pixels and the default image height is 15 pixels. If the size of the bitmap is not the default or if you have multiple images in a bitmap, you must call TB_SETBITMAPSIZE to change the default size settings. Otherwise, the bitmap or image is truncated or is not displayed.


TB_SETBUTTONINFO

This message sets the information for an existing button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETBUTTONINFO wParam = (WPARAM)(INT) iID;
lParam = (LPARAM)(LPTBBUTTONINFO) lptbbi;

Parameters

iID
Button identifier.
lptbbi
Long pointer to a TBBUTTONINFO structure that contains the new button information. The cbSize and dwMask members of this structure must be filled in prior to sending this message.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_SETBUTTONSIZE

This message sets the size of the buttons to be added to a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETBUTTONSIZE wParam = 0;
lParam = (LPARAM)MAKELONG(dxButton,dyButton);

Parameters

dxButton
Specifies the width, in pixels, of the buttons.
dyButton
Specifies the height, in pixels, of the buttons.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_SETBUTTONWIDTH

This message sets the minimum and maximum button widths in the toolbar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETBUTTONWIDTH wParam = 0;
lParam = (LPARAM)(DWORD) MAKELONG(cxMin,cxMax);

Parameters

cxMin
Minimum button width, in pixels. Toolbar buttons are never narrower than this value.
cxMax
Maximum button width, in pixels. If button text is too wide, the control displays it with ellipsis points.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_SETCMDID

This message sets the command identifier of a toolbar button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETCMDID wParam = (WPARAM)(UINT) index;
lParam = (WPARAM)(UINT) cmdId;

Parameters

index
Zero-based index of the button for which the command identifier is to be set.
cmdId
Command identifier.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_SETDISABLEDIMAGELIST

This message sets the image list that the toolbar control will use to display disabled buttons.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETDISABLEDIMAGELIST wParam = 0;
lParam = (LPARAM)(HIMAGELIST) himlNewDisabled;

Parameters

himlNewDisabled
Handle to the image list to be set.

Return Values

Returns the handle to the image list previously used to display disabled buttons, or NULL if no image list was previously set.


TB_SETDRAWTEXTFLAGS

This message sets the text drawing flags for the toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETDRAWTEXTFLAGS wParam = (WPARAM)(DWORD) dwMask;
lParam = (LPARAM)(DWORD) dwDTFlags;

Parameters

dwMask
A combination of one or more of the DT_* flags, specified in DrawText, that specifies which bits in dwDTFlags are used when drawing the text.
dwDTFlags
A combination of one or more of the DT_* flags, specified in DrawText, that specify how the button text will be drawn. This value is passed to DrawText when the button text is drawn.

Return Values

Returns the previous text drawing flags.

Remarks

The dwMask parameter allows you to specify which flags will be used when drawing the text, even if these flags are turned off. For example, if you do not want the DT_CENTER flag used when drawing text, you would add the DT_CENTER flag to dwMask and not specify the DT_CENTER flag in dwDTFlags. This prevents the control from passing the DT_CENTER flag to DrawText.


TB_SETIMAGELIST

This message sets the image list that the toolbar will use to display buttons that are in their default state.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETIMAGELIST wParam = 0;
lParam = (LPARAM)(HIMAGELIST) himlNew;

Parameters

himlNew
Handle to the image list that will be set. If this parameter is NULL, no images are displayed in the buttons.

Return Values

Returns the handle to the image list previously used to display buttons in their default state, or NULL if no image list was previously set.

Remarks

A toolbar control uses himlNew to display buttons in their default state; that is, when they are not hot or disabled.


TB_SETINDENT

This message sets the indentation for the first button in a toolbar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETINDENT wParam = (WPARAM)(INT) iIndent; lParam = 0;

Parameters

iIndent
Specifies the indentation, in pixels.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_SETMAXTEXTROWS

This message sets the maximum number of text rows displayed on a toolbar button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETMAXTEXTROWS wParam = (WPARAM)(INT) iMaxRows;
lParam = 0;

Parameters

iMaxRows
Maximum number of rows to be set.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TB_SETPARENT

This message sets the parent window for a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETPARENT wParam = (WPARAM)(HWND) hwndParent; lParam = 0;

Parameters

hwndParent
Handle to the window to receive notification messages.

Return Values

The return value is a handle to the previous notification window, or NULL if there is no previous notification window.


TB_SETROWS

This message sets the number of rows of buttons in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETROWS wParam = (WPARAM)MAKEWPARAM(cRows,fLarger); lParam = (LPARAM)(LPRECT) lprc;

Parameters

cRows
Number of rows requested. The minimum number of rows is one, and the maximum number of rows is equal to the number of buttons in the toolbar.
fLarger
Flag that indicates whether to create more rows than requested when the system cannot create the number of rows specified by cRows. If set to TRUE, the system creates more rows. If set to FALSE, the system creates fewer rows.
lprc
Long pointer to a RECT structure that receives the bounding rectangle of the toolbar after the rows are set.

Return Values

None.

See Also

RECT


TB_SETSTATE

This message sets the state for the specified button in a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETSTATE wParam = (WPARAM) idButton;
lParam = (LPARAM)MAKELONG(fState,0);

Parameters

idButton
Command identifier of the button.
fState
State flags. This parameter can be a combination of values. For information about toolbar button state values, see the Windows CE User Interface Services Guide.

Return Values

TRUE indicates success. FALSE indicates failure.


TB_SETSTYLE

This message sets the style for a toolbar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TB_SETSTYLE wParam = 0; lParam = (LPARAM)(DWORD) dwStyle;

Parameters

dwStyle
Specifies the styles to be set for the control. It can be a combination of toolbar control styles.


TB_SETTOOLTIPS

This message adds an array of ToolTip strings to a toolbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TB_SETTOOLTIPS uNumToolTip = (UINT) wParam lpToolTips = (LPTSTR) lParam

Parameters

hwndToolTip
Handle to the ToolTip control.

Return Values

None.

Remarks

The TB_SETTOOLTIPS message in Windows CE is different from the TB_SETTOOLTIPS message in Windows 95 and Windows NT.

Windows CE does not support ToolTip controls, so instead of taking a handle to a ToolTip control as its sole parameter, the TB_SETTOOLTIPS message in Windows CE takes both a wParam and an lParam. The wParam represents the number of ToolTip strings to associate with the toolbar, and the lParam is the array of strings to be displayed as ToolTips.

In Windows CE, only toolbar buttons can have ToolTip strings; menus and combo boxes cannot.

The TB_SETTOOLTIPS message uses the memory address passed in the lpToolTips parameter. Do not release the memory allocated for the ToolTip string array until the program exits.


TBM_CLEARSEL

This message clears the current selection in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_CLEARSEL wParam = (WPARAM)(BOOL) fRedraw; lParam = 0;

Parameters

fRedraw
Redraw flag. If set to TRUE, the trackbar is redrawn after the selection is cleared.

Return Values

None.

Remarks

A trackbar can have a selection range only if you specified the TBS_ENABLESELRANGE style when you created it.

See Also

TBM_SETSEL


TBM_CLEARTICS

This message removes the current tick marks from a trackbar. This message does not remove the first and last tick marks, which are created automatically by the trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_CLEARTICS wParam = (WPARAM)(BOOL) fRedraw; lParam = 0;

Parameters

fRedraw
Redraw flag. If set to TRUE, the trackbar is redrawn after the tick marks are cleared. If set to FALSE, the message clears the tick marks but does not redraw the trackbar.

Return Values

None.

See Also

TBM_SETTIC


TBM_GETBUDDY

This message retrieves the handle to a trackbar control buddy window at a specified location. The specified location is relative to the control’s orientation, horizontal or vertical.

Syntax

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

TBM_GETBUDDY wParam = (WPARAM)(BOOL) fLocation; lParam = 0;

Parameters

fLocation
Boolean that specifies which buddy window handle is retrieved, by relative location. It is one of the following values:
Value
Description
TRUE | Retrieves the handle to the buddy to the left of the trackbar. If the trackbar control uses the TBS_VERT style, the message will retrieve the buddy above the trackbar.
FALSE | Retrieves the handle to the buddy to the right of the trackbar. If the trackbar control uses the TBS_VERT style, the message will retrieve the buddy below the trackbar.

Return Values

Returns the handle to the buddy window at the location specified by fLocation, or NULL if no buddy exists at that location.


TBM_GETCHANNELRECT

This message retrieves the size and position of the bounding rectangle for a trackbar’s channel. The channel is the area over which the slider moves. It contains the highlight when a range is selected.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETCHANNELRECT wParam = 0;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

lprc
Long pointer to a RECT structure. The message fills this structure with the channel’s bounding rectangle, in client coordinates of the trackbar’s window.

Return Values

None.

See Also

TBM_GETTHUMBRECT


TBM_GETLINESIZE

This message retrieves the size of the line for a trackbar. The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETLINESIZE wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the line size for the trackbar.

Remarks

The default setting for the line size is 1.

The trackbar also sends the TB_LINEUP and TB_LINEDOWN notification messages to its parent window when the user presses the arrow keys.

See Also

TBM_SETLINESIZE


TBM_GETNUMTICS

This message retrieves the number of tick marks in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETNUMTICS wParam = 0; lParam = 0;

Return Values

The number of tick marks indicates success.

See Also

TBM_GETPTICS, TBM_SETTIC


TBM_GETPAGESIZE

This message retrieves the size of the page for a trackbar. The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETPAGESIZE wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the page size for the trackbar.

Remarks

The trackbar also sends the TB_PAGEUP and TB_PAGEDOWN notification messages to its parent window when it receives keyboard or mouse input that scrolls the page.

See Also

TBM_SETPAGESIZE


TBM_GETPOS

This message retrieves the current position of the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETPOS wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the current logical position of the trackbar’s slider.

See Also

TBM_SETPOS


TBM_GETPTICS

This message retrieves the address of the array that contains the positions of tick marks for a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETPTICS wParam = 0; lParam = 0;

Return Values

Returns the address of an array of DWORD values. The elements of the array specify the logical positions of the trackbar’s tick marks, not including the first and last tick marks created by the trackbar. The logical positions can be any of the integer values in the trackbar’s range of minimum to maximum slider positions.

See Also

TBM_GETTIC


TBM_GETRANGEMAX

This message retrieves the maximum position for the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETRANGEMAX wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the maximum position in the trackbar’s range of minimum to maximum slider positions.

See Also

TBM_GETRANGEMIN, TBM_SETRANGEMAX


TBM_GETRANGEMIN

This message retrieves the minimum position for the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETRANGEMIN wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the minimum position in the trackbar’s range of minimum to maximum slider positions.

See Also

TBM_GETRANGEMAX, TBM_SETRANGEMIN


TBM_GETSELEND

This message retrieves the ending position of the current selection in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETSELEND wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the ending position of the current selection range.

Remarks

A trackbar can have a selection range only if you specified the TBS_ENABLESELRANGE style when you created it.

See Also

TBM_GETSELSTART, TBM_SETSELEND


TBM_GETSELSTART

This message retrieves the starting position of the current selection in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETSELSTART wParam = 0; lParam = 0;

Return Values

Returns a 32-bit value that specifies the starting position of the current selection range.

Remarks

A trackbar can have a selection range only if you specified the TBS_ENABLESELRANGE style when you created it.

See Also

TBM_GETSELEND, TBM_SETSELSTART


TBM_GETTHUMBLENGTH

This message retrieves the length of the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETTHUMBLENGTH wParam = 0; lParam = 0;

Return Values

The length, in pixels, of the slider indicates success.

See Also

TBM_SETTHUMBLENGTH


TBM_GETTHUMBRECT

This message retrieves the size and position of the bounding rectangle for the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETTHUMBRECT wParam = 0;
lParam = (LPARAM)(LPRECT) lprc;

Parameters

lprc
Long pointer to a RECT structure. The message fills this structure with the bounding rectangle of the trackbar’s slider, in client coordinates of the trackbar’s window.

Return Values

None.

See Also

TBM_GETCHANNELRECT


TBM_GETTIC

This message retrieves the position of a tick mark in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETTIC wParam = (WPARAM)(WORD) iTic; lParam = 0;

Parameters

iTic
Zero-based index that identifies a tick mark. Valid indexes are in the range from zero to two less than the tick count returned by the TBM_GETNUMTICS message.

Return Values

The logical position of the specified tick mark indicates success. –1 indicates that iTic does not specify a valid index.

See Also

TBM_SETTIC


TBM_GETTICPOS

This message retrieves the current physical position of a tick mark in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_GETTICPOS wParam = (WPARAM)(WORD) iTic; lParam = 0;

Parameters

iTic
Zero-based index that identifies a tick mark. Valid indexes are in the range from zero to two less than the tick count returned by the TBM_GETNUMTICS message.

Return Values

Returns the distance, in client coordinates, from the left or top of the trackbar’s client area to the specified tick mark. The return value is the x-coordinate of the tick mark for a horizontal trackbar or the y-coordinate for a vertical trackbar. –1 indicates that iTic is not a valid index.

See Also

TBM_GETTIC


TBM_SETBUDDY

This message assigns a window as the buddy window for a trackbar control. Trackbar buddy windows are automatically displayed in a location relative to the control’s orientation, horizontal or vertical.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TBM_SETBUDDY wParam = (WPARAM)(BOOL) fLocation;
lParam = (LPARAM)(HWND) hwndBuddy;

Parameters

fLocation
Boolean that specifies the location at which to display the buddy window. It is one of the following values:
Value
Description
TRUE | The buddy appears to the left of the trackbar if the trackbar control uses the TBS_HORZ style. If the trackbar uses the TBS_VERT style, the buddy appears above the trackbar control.
FALSE | The buddy appears to the right of the trackbar if the trackbar control uses the TBS_HORZ style. If the trackbar uses the TBS_VERT style, the buddy appears below the trackbar control.

hwndBuddy
Handle to the window to be set as the trackbar control’s buddy.

Return Values

Returns the handle to the window that was previously assigned to the control at that location.

Remarks

Trackbar controls support up to two buddy windows. This can be useful when you must display text or images at each end of the control.


TBM_SETLINESIZE

This message sets the size of the line for a trackbar. The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETLINESIZE wParam = 0; lParam = (LONG) lLineSize;

Parameters

lLineSize
New line size.

Return Values

Returns a 32-bit value that specifies the previous line size.

Remarks

The default setting for the line size is 1.

The trackbar also sends the TB_LINEUP and TB_LINEDOWN notification messages to its parent window when the user presses the arrow keys.

See Also

TBM_GETLINESIZE


TBM_SETPAGESIZE

This message sets the size of the page for a trackbar. The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notification messages.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETPAGESIZE wParam = 0; lParam = (LONG) lPageSize;

Parameters

lPageSize
New page size.

Return Values

Returns a 32-bit value that specifies the previous page size.

Remarks

The trackbar also sends the TB_PAGEUP and TB_PAGEDOWN notification messages to its parent window when it receives keyboard or mouse input that scrolls the page.

See Also

TBM_GETPAGESIZE


TBM_SETPOS

This message sets the current position of the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETPOS wParam = (WPARAM)(BOOL) fPosition;
lParam = (LPARAM)(LONG) lPosition;

Parameters

fPosition
Redraw flag. If set to TRUE, the message redraws the control with the slider at the position given by lPosition. If set to FALSE, the message does not redraw the slider at the new position.

The message sets the value of the slider position (as returned by the TBM_GETPOS message) regardless of the fPosition parameter.

lPosition
New logical position of the slider. Valid logical positions are the integer values in the trackbar’s range of minimum to maximum slider positions. If this value is outside the control’s maximum and minimum range, the position is set to the maximum or minimum value.

Return Values

None.

See Also

TBM_GETPOS


TBM_SETRANGE

This message sets the range—minimum and maximum positions—for the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETRANGE wParam = (WPARAM)(BOOL) fRedraw;
lParam = (LPARAM)MAKELONG(lMinimum,lMaximum);

Parameters

fRedraw
Redraw flag. If set to TRUE, the trackbar is redrawn after the range is set. If set to FALSE, the message sets the range but does not redraw the trackbar.
lMinimum
Minimum position for the slider.
lMaximum
Maximum position for the slider.

Return Values

None.

Remarks

If the current slider position is outside the new range, the TBM_SETRANGE message sets the slider position to the new maximum or minimum value.

See Also

TBM_SETRANGEMAX, TBM_SETRANGEMIN


TBM_SETRANGEMAX

This message sets the maximum position for the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETRANGEMAX wParam = (WPARAM) fRedraw;
lParam = (LPARAM) lMaximum;

Parameters

fRedraw
Redraw flag. If set to TRUE, the trackbar is redrawn after the range is set. If set to FALSE, the message sets the range but does not redraw the trackbar.
lMaximum
Maximum position for the slider.

Return Values

None.

Remarks

If the current slider position is greater than the new maximum, the TBM_SETRANGEMAX message sets the slider position to the new maximum value.

See Also

TBM_GETRANGEMAX, TBM_SETRANGE, TBM_SETRANGEMIN


TBM_SETRANGEMIN

This message sets the minimum position for the slider in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETRANGEMIN wParam = (WPARAM) fRedraw;
lParam = (LPARAM) lMinimum;

Parameters

fRedraw
Redraw flag. If set to TRUE, the message redraws the trackbar after the range is set. If set to FALSE, the message sets the range but does not redraw the trackbar.
lMinimum
Minimum position for the slider.

Return Values

None.

Remarks

If the current slider position is less than the new minimum, the TBM_SETRANGEMIN message sets the slider position to the new minimum value.

See Also

TBM_GETRANGEMIN, TBM_SETRANGE, TBM_SETRANGEMAX


TBM_SETSEL

This message sets the starting and ending positions for the current selection in a trackbar. This message is ignored if the trackbar does not have the TBS_ENABLESELRANGE style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETSEL wParam = (WPARAM)(BOOL) fRedraw;
lParam = (LPARAM)MAKELONG(lMinimum,lMaximum);

Parameters

fRedraw
Redraw flag. If set to TRUE, the message redraws the trackbar after the selection range is set. If set to FALSE, the message sets the selection range but does not redraw the trackbar.
lMinimum
Starting logical position for the selection range.
lMaximum
Ending logical position for the selection range.

Return Values

None.

See Also

TBM_SETSELEND, TBM_SETSELSTART


TBM_SETSELEND

This message sets the ending position of the current selection in a trackbar. This message is ignored if the trackbar does not have the TBS_ENABLESELRANGE style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETSELEND wParam = (WPARAM)(BOOL) fRedraw;
lParam = (LPARAM)(LONG) lEnd;

Parameters

fRedraw
Redraw flag. If set to TRUE, the message redraws the trackbar after the selection range is set. If set to FALSE, the message sets the selection range but does not redraw the trackbar.
lEnd
Ending logical position of the selection range.

Return Values

None.

See Also

TBM_GETSELEND, TBM_SETSELSTART


TBM_SETSELSTART

This message sets the starting position of the current selection in a trackbar. This message is ignored if the trackbar does not have the TBS_ENABLESELRANGE style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETSELSTART wParam = (WPARAM)(BOOL) fRedraw;
lParam = (LPARAM)(LONG) lStart;

Parameters

fRedraw
Redraw flag. If set to TRUE, the message redraws the trackbar after the selection range is set. If set to FALSE, the message sets the selection range but does not redraw the trackbar.
lStart
Starting position of the selection range.

Return Values

None.

See Also

TBM_GETSELSTART, TBM_SETSELEND


TBM_SETTHUMBLENGTH

This message sets the length of the slider in a trackbar. This message is ignored if the trackbar does not have the TBS_FIXEDLENGTH style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETTHUMBLENGTH wParam = (WPARAM)(UINT) iLength;
lParam = 0;

Parameters

iLength
Length, in pixels, of the slider.

Return Values

None.

See Also

TBM_GETTHUMBLENGTH


TBM_SETTIC

This message sets the position of a tick mark in a trackbar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETTIC wParam = 0; lParam = (LPARAM)(LONG) lPosition;

Parameters

lPosition
Position of the tick mark. This parameter can be any of the integer values in the trackbar’s range of minimum to maximum slider positions.

Remarks

A trackbar creates its own first and last tick marks. Do not use this message to set the first and last tick marks.

Return Values

TRUE indicates that the tick mark is set. FALSE indicates otherwise.

See Also

TBM_CLEARTICS, TBM_GETPTICS, TBM_GETTIC


TBM_SETTICFREQ

This message sets the interval frequency for tick marks in a trackbar. For example, if the frequency is set to two, a tick mark is displayed for every other increment in the trackbar’s range. The default setting for the frequency is one; that is, every increment in the range is associated with a tick mark.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBM_SETTICFREQ wParam = (WPARAM) wFreq;
lParam = 0;

Parameters

wFreq
Frequency of the tick marks.

Return Values

None.

See Also

TBM_SETTIC


TBN_BEGINDRAG

This notification message notifies a toolbar’s parent window that the user has begun dragging a button in a toolbar. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBN_BEGINDRAG ptbn = (TBNOTIFY FAR *) lParam;

Parameters

lpnmtb
Long pointer to an NMTOOLBAR structure. The iItem member contains the command identifier of the button being dragged.

Return Values

None.

See Also

TBNOTIFY, WM_NOTIFY


TBN_DROPDOWN

This notification message sent by a toolbar control when the user clicks a button that uses the TBSTYLE_DROPDOWN style. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

TBN_DROPDOWN lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Long pointer to an NMTOOLBAR structure that contains information about this notification. For this notification message, only the hdr and iItem members of this structure are valid.

Return Values

Returns FALSE to allow the toolbar control to display the drop-down list; returns TRUE to prevent the control from displaying the list.


TBN_ENDDRAG

This notification message notifies the toolbar’s parent window that the user has stopped dragging a button in a toolbar. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBN_ENDDRAG ptbn = (TBNOTIFY FAR *) lParam;

Parameters

lpnmtb
Long pointer to an NMTOOLBAR structure. The iItem member contains the command identifier of the button being dragged.

Return Values

None.

See Also

TBNOTIFY, WM_NOTIFY


TBN_GETBUTTONINFO

This notification message retrieves toolbar customization information and notifies the toolbar’s parent window of any changes being made to the toolbar. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TBN_GETBUTTONINFO ptbn = (TBNOTIFY FAR *) lParam;

Parameters

lpnmtb
Long pointer to an NMTOOLBAR structure. The iItem member specifies a zero-based index that provides a count of the buttons the Customize Toolbar dialog box displays as both available and present on the toolbar.

The pszText member specifies the address of the current button text, and cchText specifies its length in characters. The application should fill the structure with information about the button.

Return Value

TRUE indicates that button information was copied to the specified structure. FALSE indicates otherwise.

See Also

TBNOTIFY, WM_NOTIFY


TCM_ADJUSTRECT

This message calculates a tab control’s display area specified a window rectangle or calculates the window rectangle that would correspond to a specified display area. You can send this message explicitly or by using the TabCtrl_AdjustRect macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_AdjustRect

Syntax

TCM_ADJUSTRECT wParam = (WPARAM)(BOOL) fLarger;
lParam = (LPARAM)(LPRECT) prc;

Parameters

fLarger
Operation to perform. If set to TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If set to FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc
Pointer to a RECT structure that specifies the specified rectangle and receives the calculated rectangle.

Return Values

None.

See Also

RECT


TCM_DELETEALLITEMS

This message removes all items from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteAllItems macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_DeleteAllItems

Syntax

TCM_DELETEALLITEMS wParam = 0; lParam = 0;

Return Values

TRUE indicates success. FALSE indicates failure.


TCM_DELETEITEM

This message removes an item from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_DeleteItem

Syntax

TCM_DELETEITEM wParam = (WPARAM)(int) iItem; lParam = 0;

Parameters

iItem
Index of the item to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


TCM_DESELECTALL

This message resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | TabCtrl_DeselectAll

Syntax

TCM_DESELECTALL wParam = (WPARAM) (DWORD) fExcludeFocus;
lParam = 0;

Parameters

fExcludeFocus
Boolean that specifies the scope of the item deselection. If this parameter is set to FALSE, all tab buttons are reset. If it is set to TRUE, then all tab items except for the one currently selected are reset.

Return Values

The return value for this message is not used.


TCM_GETCURFOCUS

This message returns the index of the item that has the focus in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurFocus macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetCurFocus

Syntax

TCM_GETCURFOCUS wParam = 0; lParam = 0;

Return Values

Returns the index of the tab item that has the focus.


TCM_GETCURSEL

This message determines the currently selected tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurSel macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetCurSel

Syntax

TCM_GETCURSEL wParam = 0; lParam = 0;

Return Values

The index of the selected tab indicates success. –1 indicates that no tab is selected.


TCM_GETEXTENDEDSTYLE

This message retrieves the extended styles that are currently in use for the tab control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | TabCtrl_GetExtendedStyle

Syntax

TCM_GETEXTENDEDSTYLE wParam = 0; lParam = 0;

Return Values

Returns a DWORD value that represents the extended styles currently in use for the tab control. This value is a combination of tab control extended styles.


TCM_GETIMAGELIST

This message retrieves the image list associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetImageList macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetImageList

Syntax

TCM_GETIMAGELIST wParam = 0; lParam = 0;

Return Values

The handle to the image list indicates success. NULL indicates otherwise.


TCM_GETITEM

This message retrieves information about a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetItem

Syntax

TCM_GETITEM wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(TC_ITEM FAR *) pitem;

Parameters

iItem
Index of the tab.
pitem
Pointer to a TCITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TC_ITEM


TCM_GETITEMCOUNT

This message retrieves the number of tabs in the tab control. You can send this message explicitly or by using the TabCtrl_GetItemCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetItemCount

Syntax

TCM_GETITEMCOUNT wParam = 0; lParam = 0;

Return Values

The number of items indicates success. Zero indicates otherwise.


TCM_GETITEMRECT

This message retrieves the bounding rectangle for a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItemRect macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetItemRect

Syntax

TCM_GETITEMRECT wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(RECT FAR *) prc;

Parameters

iItem
Index of the tab.
prc
Pointer to a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

RECT


TCM_GETROWCOUNT

This message retrieves the current number of rows of tabs in a tab control. You can send this message explicitly or by using the TabCtrl_GetRowCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_GetRowCount

Syntax

TCM_GETROWCOUNT wParam = 0; lParam = 0;

Return Values

Returns the number of rows of tabs.


TCM_HIGHLIGHTITEM

This message sets the highlight state of a tab item.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | TabCtrl_HighlightItem

Syntax

TCM_HIGHLIGHTITEM wParam = (WPARAM) idItem;
lParam = (LPARAM) MAKELONG(fHighlight,0);

Parameters

idItem
Zero-based index of a tab control item.
fHighlight
Boolean that specifies whether the highlight state is to be set. If this value is TRUE, the tab is highlighted; if FALSE, the tab is set to its default state.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TCM_HITTEST

This message determines which tab, if any, is at a specified screen position. You can send this message explicitly or by using the TabCtrl_HitTest macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_HitTest

Syntax

TCM_HITTEST wParam = 0;
lParam = (LPARAM)(TC_HITTESTINFO FAR *) pinfo;

Parameters

pinfo
Pointer to a TCHITTESTINFO structure that specifies the screen position to test.

Return Values

The index of the tab indicates success. –1 indicates that no tab is at the specified position.

See Also

TC_HITTESTINFO


TCM_INSERTITEM

This message inserts a new tab in a tab control. You can send this message explicitly or by using the TabCtrl_InsertItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_InsertItem

Syntax

TCM_INSERTITEM wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(const TC_ITEM FAR*) pitem;

Parameters

iItem
Index of the new tab.
pitem
Pointer to a TCITEM structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

Return Values

The index of the new tab indicates success. –1 indicates otherwise.

See Also

TC_ITEM


TCM_REMOVEIMAGE

This message removes an image from a tab control’s image list. You can send this message explicitly or by using the TabCtrl_RemoveImage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_RemoveImage

Syntax

TCM_REMOVEIMAGE | wParam = (WPARAM)(int) iImage; lParam = 0;

Parameters

iImage
Index of the image to remove.

Return Values

None.


TCM_SETCURFOCUS

This message sets the focus to a specified tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurFocus macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetCurFocus

Syntax

TCM_SETCURFOCUS iItem = (int) (WPARAM) wParam;

Parameters

iItem
Index of the tab that gets the focus.

Return Values

None.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, TCM_SETCURFOCUS sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See Also

TabCtrl_GetCurFocus, TCM_GETCURFOCUS, TCN_SELCHANGE, TCN_SELCHANGING


TCM_SETCURSEL

This message selects a tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurSel macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetCurSel

Syntax

TCM_SETCURSEL wParam = (WPARAM)(int) iItem; lParam = 0;

Parameters

iItem
Index of the tab to select.

Return Values

The index of the previously selected tab indicates success. –1 indicates otherwise.

See Also

TCN_SELCHANGE, TCN_SELCHANGING


TCM_SETEXTENDEDSTYLE

This message sets the extended styles that the tab control will use.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | TabCtrl_SetExtendedStyle

Syntax

TCM_SETEXTENDEDSTYLE wParam = (WPARAM)dwExMask;
lParam = (LPARAM)dwExStyle;

Parameters

dwExMask
Specifies which styles in dwExStyle are to be affected. Only the extended styles in dwExMask will be changed. All other styles will be maintained as is. If this parameter is zero, then all of the styles in dwExStyle will be affected.
dwExStyle
Specifies the extended tab control styles. This value is a combination of Tab Control extended styles.
dwExMask
Allows you to modify one or more extended styles without having to retrieve the existing styles first. For example: if you pass TCS_EX_FLATSEPARATORS for dwExMask and 0 for dwExStyle, the TCS_EX_FLATSEPARATORS style will be cleared, but all other styles will remain the same.

For backward compatibility reasons, the TabCtrl_SetExtendedStyle macro has not been updated to use dwExMask.

Return Values

Returns a DWORD value that contains the previous tab control extended styles.


TCM_SETIMAGELIST

This message assigns an image list to a tab control. You can send this message explicitly or by using the TabCtrl_SetImageList macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetImageList

Syntax

TCM_SETIMAGELIST wParam = 0;
lParam = (LPARAM)(HIMAGELIST) himl;

Parameters

himl
Handle to the image list to assign to the tab control.

Return Values

The handle to the previous image list indicates success. NULL indicates that there is no previous image list.


TCM_SETITEM

This message sets some or all of a tab’s attributes. You can send this message explicitly or by using the TabCtrl_SetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetItem

Syntax

TCM_SETITEM wParam = (WPARAM)(int) iItem;
lParam = (LPARAM)(TC_ITEM FAR *) pitem;

Parameters

iItem
Index of the item.
pitem
Pointer to a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TC_ITEM


TCM_SETITEMEXTRA

This message sets the number of bytes per tab reserved for application-defined data in a tab control. You can send this message explicitly or by using the TabCtrl_SetItemExtra macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetItemExtra

Syntax

TCM_SETITEMEXTRA wParam = (WPARAM)(int) cb; lParam = 0;

Parameters

cb
Number of extra bytes.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

See Also

TC_ITEM, TC_ITEMHEADER


TCM_SETITEMSIZE

This message sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can send this message explicitly or by using the TabCtrl_SetItemSize macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetItemSize

Syntax

TCM_SETITEMSIZE wParam = 0; lParam = MAKELPARAM(cx,cy);

Parameters

cx and cy
New width and height, in pixels.

Return Values

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.


TCM_SETMINTABWIDTH

This message sets the minimum width of items in a tab control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related macro: | TabCtrl_SetMinTabWidth

Syntax

TCM_SETMINTABWIDTH wParam = 0; lParam = (LPARAM) (INT) cx;

Parameters

cx
Minimum width to be set for a tab control item. If this parameter is set to –1, the control uses the default tab width.

Return Values

Returns an INT value that represents the previous minimum tab width.


TCM_SETPADDING

This message sets the amount of space (padding) around each tab’s icon and label in a tab control. You can send this message explicitly or by using the TabCtrl_SetPadding macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TabCtrl_SetPadding

Syntax

TCM_SETPADDING wParam = 0; lParam = MAKELPARAM(cx,cy);

Parameters

cx and cy
Amount of horizontal and vertical padding, in pixels.

Return Values

None.


TCN_KEYDOWN

This notification message notifies a tab control’s parent window that a key has been pressed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TCN_KEYDOWN pnm = (TC_KEYDOWN FAR *) lParam;

Parameters

pnm
Pointer to an NMTCKEYDOWN structure.

Return Value

None.

See Also

TC_KEYDOWN, WM_NOTIFY


TCN_SELCHANGE

This notification message notifies a tab control’s parent window that the currently selected tab has changed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TCN_SELCHANGE idTabCtl = (int)LOWORD(wParam);
hwndTabCtl = (HWND) lParam;

Parameters

lpnmhdr
Long pointer to an NMHDR structure. The hwndFrom member is the handle to the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGE.

Return Values

None.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

WM_NOTIFY


TCN_SELCHANGING

This notification message notifies a tab control’s parent window that the currently selected tab is about to change. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TCN_SELCHANGE idTabCtl = (int)LOWORD(wParam);
hwndTabCtl = (HWND) lParam;

Parameters

lpnmhdr
Long pointer to an NMHDR structure. The hwndFrom member is the handle to the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGING.

Return Value

TRUE prevents the selection from changing. FALSE allows the selection to change.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

WM_NOTIFY


TVM_CREATEDRAGIMAGE

This message creates a dragging bitmap for the specified item in a tree view control, creates an image list for the bitmap, and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can send this message explicitly or by using the TreeView_CreateDragImage macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_CreateDragImage

Syntax

TVM_CREATEDRAGIMAGE wParam = 0;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

hitem
Handle to the item that receives the new dragging bitmap.

Return Values

The handle to the image list to which the dragging bitmap was added indicates success. NULL indicates otherwise.

See Also

ImageList_Add, ImageList_Create, SendMessage


TVM_DELETEITEM

This message removes an item from a tree view control. You can send this message explicitly or by using the TreeView_DeleteItem or TreeView_DeleteAllItems macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macros: | TreeView_DeleteItem TreeView_DeleteAllItems

Syntax

TVM_DELETEITEM wParam = 0;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

hitem
Handle to the item to delete. If hitem is the TVI_ROOT value, all items are deleted from the tree view control.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

SendMessage, TVN_DELETEITEM, TVN_ENDLABELEDIT


TVM_EDITLABEL

This message begins in-place editing of the specified item’s text, replacing the text of the item with a single-line edit control containing the text. This message implicitly selects and focuses the specified item. You can send this message explicitly or by using the TreeView_EditLabel macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_EditLabel

Syntax

TVM_EDITLABEL wParam = 0;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

hitem
Handle to the item to edit.

Return Values

The handle to the edit control used to edit the item text indicates success. NULL indicates otherwise.

Remarks

This message sends a TVN_BEGINLABELEDIT notification message to the parent of the tree view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

See Also

TVN_BEGINLABELEDIT, TVN_ENDLABELEDIT


TVM_ENDEDITLABELNOW

This message ends the editing of a tree view item’s label. You can send this message explicitly or by using the TreeView_EndEditLabelNow macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_EndEditLabelNow

Syntax

TVM_ENDEDITLABELNOW wParam = (WPARAM)(BOOL) fCancel; lParam = 0;

Parameters

fCancel
Boolean value that indicates whether the editing is canceled without being saved to the label. If set to TRUE, the system cancels editing without saving the changes. If set to FALSE, the system saves the changes to the label.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TVN_ENDLABELEDIT


TVM_ENSUREVISIBLE

This message ensures that a tree view item is visible, expanding the parent item or scrolling the tree view control, if necessary. You can send this message explicitly or by using the TreeView_EnsureVisible macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_EnsureVisible

Syntax

TVM_ENSUREVISIBLE wParam = 0;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

hitem
Handle to the item.

Return Values

Nonzero indicates that the system scrolled the items in the tree view control and no items were expanded. Zero indicates otherwise.

See Also

TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TVM_EXPAND

This message expands or collapses the list of child items, if any, associated with the specified parent item. You can send this message explicitly or by using the TreeView_Expand macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later (updated in 2.0)
Related macro: | TreeView_Expand

Syntax

TVM_EXPAND wParam = (WPARAM)(UINT) flag;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

flag
Action flag. It is one or more of the following values:
Value
Description
TVE_COLLAPSE | Collapses the list.
TVE_COLLAPSERESET | Collapses the list and removes the child items. This flag must be used with the TVE_COLLAPSE flag.
TVE_EXPAND | Expands the list.
TVE_EXPANDPARTIAL | Version 4.70. Partially expands the list. In this state, the child items are visible and the parent item's plus symbol is displayed. This flag must be used in combination with the TVE_EXPAND flag.
TVE_TOGGLE | Collapses the list if it is expanded or expands it if it is collapsed.

hItem
Handle to the parent item to expand or collapse.

Return Values

Nonzero indicates that a change took place. Zero indicates otherwise.

Remarks

In Windows CE versions 2.0 and later, you can use the new TVE_EXPANDPARTIAL flag in the flag parameter.

When the TVE_EXPANDPARTIAL flag is set, the child items are visible and parent item's plus symbol is displayed. This flag must be used in combination with the TVE_EXPAND flag.

The TVM_EXPAND message will cause the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to be generated if the item being expanded does not have the TVIS_EXPANDEDONCE state bit set. This state gets set when a parent item is expanded for the first time. Using TVE_COLLAPSE and TVE_COLLAPSERESET with TVM_EXPAND will cause the TVIS_EXPANDEDONCE state to be reset.

See Also

TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TVM_GETCOUNT

This message retrieves a count of the items in a tree view control. You can send this message explicitly or by using the TreeView_GetCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetCount

Syntax

TVM_GETCOUNT wParam = 0; lParam = 0;

Return Values

Returns the count of items.


TVM_GETEDITCONTROL

This message retrieves the handle of the edit control being used to edit a tree view item’s text. You can send this message explicitly or by using the TreeView_GetEditControl macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetEditControl

Syntax

TVM_GETEDITCONTROL wParam = 0; lParam = 0;

Return Values

The handle to the edit control indicates success. NULL indicates otherwise.


TVM_GETIMAGELIST

This message retrieves the handle of the normal or state image list associated with a tree view control. You can send this message explicitly or by using the TreeView_GetImageList macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetImageList

Syntax

TVM_GETIMAGELIST wParam = (WPARAM) iImage; lParam = 0;

Parameters

iImage
Type of image list to retrieve. It is one of the following values:
Value
Description
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.

Return Values

Returns an HIMAGELIST handle to the specified image list.

See Also

TVM_SETIMAGELIST


TVM_GETINDENT

This message retrieves the amount, in pixels, that child items are indented relative to their parent items. You can send this message explicitly or by using the TreeView_GetIndent macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetIndent

Syntax

TVM_GETINDENT wParam = 0; lParam = 0;

Return Values

Returns the amount of indentation.

See Also

TVM_SETINDENT


TVM_GETISEARCHSTRING

This message retrieves the incremental search string for a tree view control. The tree view control uses the incremental search string to select an item based on characters entered by the user. You can send this message explicitly or by using the TreeView_GetISearchString macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetISearchString

Syntax

TVM_GETISEARCHSTRING wParam = 0;
lParam = (LPARAM)(LPSTR) lpsz;

Parameters

lpsz
Long pointer to the buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string.


TVM_GETITEM

This message retrieves some or all of a tree view item’s attributes. You can send this message explicitly or by using the TreeView_GetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetItem

Syntax

TVM_GETITEM wParam = 0;
lParam = (LPARAM)(TV_ITEM FAR*) pitem;

Parameters

pitem
Pointer to a TVITEM structure that specifies the information to retrieve and receives information about the item. When the message is sent, the hItem member identifies the item to retrieve information about and the mask member specifies the attributes to retrieve.

If the mask member specifies the TVIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the TVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TV_ITEM


TVM_GETITEMRECT

This message retrieves the bounding rectangle for a tree view item and indicates whether the item is visible. You can send this message explicitly or by using the TreeView_GetItemRect macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetItemRect

Syntax

TVM_GETITEMRECT wParam = (WPARAM)(BOOL) fItemRect;
lParam = (LPARAM)(RECT FAR*) prc;

Parameters

fItemRect
Boolean value that specifies the portion of the item for which to retrieve the bounding rectangle. If set to TRUE, the bounding rectangle includes only the text of the item. If set to FALSE, it includes the entire line that the item occupies in the tree view control.
prc
Pointer to a RECT structure that, when sending the message, contains the handle of the item to retrieve the rectangle for. For more information on how to place the item handle in this parameter, see the Remarks section. After returning from the message, this parameter contains the bounding rectangle. The coordinates are relative to the upper-left corner of the tree view control.

Return Values

TRUE indicates that the item is visible and the bounding rectangle was successfully retrieved. Otherwise, the message returns FALSE and does not retrieve the bounding rectangle.

Remarks

When sending this message, the prc parameter contains the handle of the item that the rectangle is being retrieved for. The handle is placed in prc as shown in the following code example:

RECT rc;
*(HTREEITEM*)&rc = hTreeItem;
SendMessage(hwndTreeView, TVM_GETITEMRECT, FALSE, (LPARAM)&rc);

See Also

RECT


TVM_GETNEXTITEM

This message retrieves the tree view item that bears the specified relationship to a specified item. You can send this message explicitly or by using the TreeView_GetNextItem macro or one of the related macros.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macros: | TreeView_GetNextItem TreeView_GetChild TreeView_GetDropHilite TreeView_GetFirstVisible TreeView_GetNextSibling TreeView_GetNextVisible TreeView_GetParent TreeView_GetPrevSibling TreeView_GetPrevVisible TreeView_GetRoot TreeView_GetSelection

Syntax

TVM_GETNEXTITEM wParam = (WPARAM)(UINT) flag;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

flag
Specifies the item to retrieve. It is one of the following values:
Value
Description
TVGN_CARET | Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD | Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE | Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilight macro to send this message.
TVGN_FIRSTVISIBLE | Retrieves the first item that is visible in the tree view window. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_LASTVISIBLE | Version 4.71. Retrieves the last expanded item in the tree. This does not retrieve the last item visible in the tree view window. You can use the TreeView_GetLastVisible macro to send this message.
TVGN_NEXT | Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE | Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT | Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS | Retrieves the previous sibling item. You can use the TreeView_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE | Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT | Retrieves the topmost or very first item of the tree view control. You can use the TreeView_GetRoot macro to send this message.

hitem
Handle to an item.

Return Values

The handle to the item indicates success. NULL indicates otherwise.


TVM_GETVISIBLECOUNT

This message retrieves the number of items that can be fully visible in the client window of the tree-view control. You can send this message explicitly or by using the TreeView_GetVisibleCount macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_GetVisibleCount

Syntax

TVM_GETVISIBLECOUNT wParam = 0; lParam = 0;

Return Values

Returns the number of items that can be fully visible in the client window of the tree view control.

Remarks

The number of items that can be fully visible may be greater than the number of items in the control. The control calculates this value by dividing the height of the client window by the height of an item.

Note that the return value is the number of items that can be fully visible. If you can see all of 20 items and part of one more item, the return value is 20.


TVM_HITTEST

This message determines the location of the specified point relative to the client area of a tree view control. You can send this message explicitly or by using the TreeView_HitTest macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_HitTest

Syntax

TVM_HITTEST wParam = 0;
lParam = (LPARAM)(LPTV_HITTESTINFO) lpht;

Parameters

lpht
Long pointer to a TVHITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit test value that indicates the location of the specified point. For a list of hit test values, see the description of the TVHITTESTINFO structure.

Return Values

The handle to the tree view item that occupies the specified point indicates success. NULL indicates that no item occupies the point.

See Also

TV_HITTESTINFO


TVM_INSERTITEM

This message inserts a new item in a tree view control. You can send this message explicitly or by using the TreeView_InsertItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_InsertItem

Syntax

TVM_INSERTITEM wParam = 0;
lParam = (LPARAM)(LPTV_INSERTSTRUCT) lpis;

Parameters

lpis
Long pointer to a TVINSERTSTRUCT structure that specifies the attributes of the tree view item.

Return Values

The handle to the new item indicates success. NULL indicates otherwise.

See Also

TV_INSERTSTRUCT, TVN_ENDLABELEDIT


TVM_SELECTITEM

This message selects the specified tree view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag and drop operation. You can send this message explicitly or by using the TreeView_Select, TreeView_SelectItem, or TreeView_SelectDropTarget macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macros: | TreeView_Select TreeView_SelectItem TreeView_SelectDropTarget

Syntax

TVM_SELECTITEM wParam = (WPARAM) flag;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

flag
Action flag. It is one of the following values:
Value
Description
TVGN_CARET | Sets the selection to the specified item. The tree view control's parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages.
TVGN_DROPHILITE | Redraws the specified item in the style used to indicate the target of a drag-and-drop operation.
TVGN_FIRSTVISIBLE | Ensures that the specified item is visible, and, if possible, displays it at the top of the control's window. Tree view controls display as many items as will fit in the window. If the specified item is near the bottom of the control's hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

hitem
Handle to an item. If hitem is NULL, the control is set to have no selected item.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the control's parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

See Also

TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TVM_SETIMAGELIST

This message sets the normal or state image list for a tree view control and redraws the control using the new images. You can send this message explicitly or by using the TreeView_SetImageList macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_SetImageList

Syntax

TVM_SETIMAGELIST wParam = (WPARAM) iImage;
lParam = (LPARAM)(HIMAGELIST) himl;

Parameters

iImage
Type of image list to set. It is one of the following values:
Value
Description
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.

himl
Handle to the image list. If himl is NULL, the message removes the specified image list from the tree view control.

Return Values

The handle to the previous image list, if any, indicates success. NULL indicates otherwise.

See Also

TVM_GETIMAGELIST


TVM_SETINDENT

This message sets the width of indentation for a tree view control and redraws the control to reflect the new width. You can send this message explicitly or by using the TreeView_SetIndent macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_SetIndent

Syntax

TVM_SETINDENT wParam = (WPARAM) indent; lParam = 0;

Parameters

indent
Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Values

The return value is not used.

See Also

TVM_GETINDENT


TVM_SETITEM

This message sets some or all of a tree view item's attributes. You can send this message explicitly or by using the TreeView_SetItem macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_SetItem

Syntax

TVM_SETITEM wParam = 0;
lParam = (LPARAM)(const TV_ITEM FAR*) pitem;

Parameters

pitem
Pointer to a TVITEM structure that contains the new item attributes. The hItem member identifies the item, and the mask member specifies which attributes to set.

If mask specifies the TVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states to change and the state member contains the values for those states.

Return Values

TRUE indicates success. FALSE indicates success.

See Also

TV_ITEM


TVM_SORTCHILDREN

This message sorts the child items of the specified parent item in a tree view control. You can send this message explicitly or by using the TreeView_SortChildren macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_SortChildren

Syntax

TVM_SORTCHILDREN wParam = (WPARAM) fReserved;
lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

fRecurse
Reserved for future use; set to zero.
hitem
Handle to the parent item whose child items are to be sorted.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TVM_SORTCHILDRENCB


TVM_SORTCHILDRENCB

This message sorts tree view items using an application-defined callback function that compares the items. You can send this message explicitly or by using the TreeView_SortChildrenCB macro.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related macro: | TreeView_SortChildrenCB

Syntax

TVM_SORTCHILDRENCB wParam = (WPARAM) fReserved;
lParam = (LPARAM)(LPTV_SORTCB) psort;

Parameters

fRecurse
Reserved for future use; set to zero.
psort
Pointer a TVSORTCB structure. The lpfnCompare member is the address of the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TVSORTCB.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TV_ITEM, TV_SORTCB, TVM_SORTCHILDREN


TVN_BEGINDRAG

This notification message notifies a tree view control’s parent window that a drag-and-drop operation is being initiated. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_BEGINDRAG pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv
Pointer to an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the item being dragged in the hItem, state, and lParam members. The ptDrag member specifies the current screen coordinates of the mouse.

Return Values

The return value is ignored.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_BEGINLABELEDIT

This notification message notifies a tree view control’s parent window about the start of label editing for an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_BEGINLABELEDIT ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

ptvdi
Pointer to an NMTVDISPINFO structure. The item member is a TVITEM structure that contains valid information about the item being edited in the hItem, state, lParam, and pszText members.

Return Values

TRUE cancels label editing.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EDITLABEL, TVN_ENDLABELEDIT, WM_NOTIFY


TVN_DELETEITEM

This notification message notifies a tree view control’s parent window that an item has been deleted. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_DELETEITEM pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv
Pointer to an NMTREEVIEW structure. The itemOld member is a TVITEM structure whose hItem and lParam members contain valid information about the item being deleted.

Return Values

The return value is ignored.

See Also

NM_TREEVIEW, TV_ITEM, TVM_DELETEITEM, WM_NOTIFY


TVN_ENDLABELEDIT

This notification message notifies a tree view control’s parent window about the end of label editing for an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_ENDLABELEDIT ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

ptvdi
Pointer to an NMTVDISPINFO structure. The item member of this structure is a TVITEM structure whose hItem, lParam, and pszText members contain valid information about the item that was edited.

If label editing was canceled, the pszText member of the TVITEM structure is NULL; otherwise, pszText is the address of the edited text.

Return Values

If the pszText member is non-NULL, return TRUE to set the item's label to the edited text. Return FALSE to reject the edited text and revert to the original label.

Remarks

If the pszText member is NULL, the return value is ignored.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EDITLABEL, TVN_BEGINLABELEDIT, WM_NOTIFY


TVN_GETDISPINFO

This notification message requests that a tree view control’s parent window provide information needed to display or sort an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_GETDISPINFO ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

lptvdi
Long pointer to an NMTVDISPINFO structure. The item member is a TVITEM structure whose mask, hItem, state, and lParam members specify the type of information required. You must fill the members of the structure with the appropriate information.

Return Values

The return value is ignored.

Remarks

This notification is sent under the following circumstances:

  • If the pszText member of the item's TVITEM structure is the LPSTR_TEXTCALLBACK value, the control sends this notification to retrieve the item's text. In this case, the mask member of lptvdi will have the TVIF_TEXT flag set.
  • If the iImage or iSelectedImage member of the item's TVITEM structure is the I_IMAGECALLBACK value, the control sends this notification to retrieve the index of an item's icons in the control's image list. In this case, if the item is selected, the mask member of lptvdi will have the TVIF_SELECTEDIMAGE flag set. If the item is not selected, the mask member of lptvdi will have the TVIF_IMAGE flag set.
  • If the cChildren member of the item's TVITEM structure is the I_CHILDRENCALLBACK value, the control sends this notification to retrieve a value that indicates whether the item has child items. In this case, the mask member of lptvdi will have the TVIF_CHILDREN flag set.

See Also

TV_DISPINFO, TVN_SETDISPINFO, WM_NOTIFY


TVN_ITEMEXPANDED

This notification message notifies a tree view control’s parent window that a parent item's list of child items has expanded or collapsed. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_ITEMEXPANDED pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv
Pointer to an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list expanded or collapsed. For a list of possible values, see the description of the TVM_EXPAND message.

Return Values

The return value is ignored.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EXPAND, TVN_ITEMEXPANDING, WM_NOTIFY


TVN_ITEMEXPANDING

This notification message notifies a tree view control’s parent window that a parent item's list of child items is about to expand or collapse. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_ITEMEXPANDING pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv
Pointer to an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list is to expand or collapse. For a list of possible values, see the description of the TVM_EXPAND message.

Return Values

TRUE prevents the list from expanding or collapsing.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EXPAND, TVN_ITEMEXPANDED, WM_NOTIFY


TVN_KEYDOWN

This notification message notifies a tree view control’s parent window that the user pressed a key and the tree view control has the input focus. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_KEYDOWN ptvkd = (TV_KEYDOWN FAR *) lParam

Parameters

ptvkd
Pointer to an NMTVKEYDOWN structure. The wVKey member specifies the virtual-key code.

Return Values

If the wVKey member of ptvkd is a character key code, the character will be used as part of an incremental search. Return nonzero to exclude the character from the incremental search, or zero to include the character in the search. For all other keys, the return value is ignored.

See Also

TV_KEYDOWN, WM_NOTIFY


TVN_SELCHANGED

This notification message notifies a tree view control’s parent window that the selection has changed from one item to another. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_SELCHANGED pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv
Pointer to an NMTREEVIEW structure. The itemOld and itemNew members of the NMTREEVIEW structure are TVITEM structures that contain information about the previously selected item and the newly selected item. Only the mask, hItem, state, and lParam members of these structures are valid. The stateMask members of the TVITEM structures specified by itemOld and itemNew are undefined on input.

The action member of the NMTREEVIEW structure indicates the type of action that caused the selection to change. It is one of the following values:
Value
Description
TVC_BYKEYBOARD | By a keystroke.
TVC_BYMOUSE | By a mouse click.
TVC_UNKNOWN | Unknown.

Return Values

The return value is ignored.

See Also

NM_TREEVIEW, TVN_SELCHANGING, WM_NOTIFY


TVN_SELCHANGING

This notification message notifies a tree view control’s parent window that the selection is about to change from one item to another. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_SELCHANGING pnmtv = (NM_TREEVIEW FAR *) lParam

Parameters

pnmtv
Pointer to an NMTREEVIEW structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

Return Values

TRUE prevents the selection from changing.

See Also

NM_TREEVIEW, TVN_SELCHANGED, WM_NOTIFY


TVN_SETDISPINFO

This notification message notifies a tree view control’s parent window that it must update the information it maintains about an item. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

TVN_SETDISPINFO ptvdi = (TV_DISPINFO FAR *) lParam

Parameters

lptvdi
Long pointer to an NMTVDISPINFO structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

Return Values

The return value is ignored.

See Also

TV_DISPINFO, TVN_GETDISPINFO, WM_NOTIFY


UDM_GETACCEL

This message retrieves acceleration information for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_GETACCEL wParam = (WPARAM) cAccels;
lParam = (LPARAM)(LPUDACCEL) paAccels;

Parameters

cAccels
Number of elements in the array specified by paAccels.
paAccels
Pointer to an array of UDACCEL structures that receive acceleration information.

Return Values

The return value is the number of accelerator structures retrieved.

If the cAccels parameter is zero and the paAccels parameter is NULL, the return value is the number of accelerators currently set for the control.

See Also

UDACCEL, UDM_SETACCEL


UDM_GETBASE

The UDM_GETBASE message retrieves the current radix base—that is, either base 10 or 16—for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_GETBASE wParam = 0; lParam = 0;

Return Values

The current base value indicates success.

See Also

UDM_SETBASE_


UDM_GETBUDDY

This message retrieves the handle of the current buddy window.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_GETBUDDY wParam = 0; lParam = 0;

Return Values

The handle to the current buddy window indicates success.

See Also

UDM_SETBUDDY


UDM_GETPOS

This message retrieves the current position of an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_GETPOS wParam = 0; lParam = 0;

Return Values

The return value is the current position in the low-order word. If an error occurred, the high-order word is nonzero.

See Also

UDM_SETPOS


UDM_GETRANGE

This message retrieves the minimum and maximum positions, or the range, for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_GETRANGE wParam = 0; lParam = 0;

Return Values

The return value is a 32-bit value that contains the minimum and maximum positions. The low-order word is the maximum position for the control, and the high-order word is the minimum position.

See Also

UDM_SETRANGE


UDM_GETRANGE32

This message retrieves the 32-bit range of an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

UDM_GETRANGE32 wParam = (WPARAM)(LPINT) pLow;
lParam = (LPARAM)(LPINT) pHigh;

Parameters

pLow
Pointer to an integer that receives the lower limit of the up-down control range. This parameter may be NULL.
pHigh
Pointer to an integer that receives the upper limit of the up-down control range. This parameter may be NULL.

Return Values

None


UDM_SETACCEL

This message sets the acceleration for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_SETACCEL wParam = (WPARAM) nAccels;
lParam = (LPARAM)(LPUDACCEL) aAccels;

Parameters

nAccels
Number of UDACCEL structures specified by aAccels.
aAccels
Pointer to an array of UDACCEL structures that contain acceleration information. Elements should be sorted in ascending order based on the nSec member.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

UDACCEL, UDM_GETACCEL


UDM_SETBASE

This message sets the radix base for an up-down control. The base value determines whether the buddy window displays numbers in decimal or hexadecimal digits. Hexadecimal numbers are always unsigned, and decimal numbers are signed.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_SETBASE wParam = (WPARAM) nBase; lParam = 0;

Parameters

nBase
New base value for the control. This parameter can be 10 for decimal or 16 for hexadecimal.

Return Values

The previous base value indicates success. Zero indicates that an invalid base was given.

See Also

UDM_GETBASE


UDM_SETBUDDY

This message sets the buddy window for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_SETBUDDY wParam = (WPARAM)(HWND) hwndBuddy; lParam = 0;

Parameters

hwndBuddy
Handle to the new buddy window.

Return Values

The handle to the previous buddy window indicates success.

Remarks

If hwndBuddy is not NULL, it must specify an edit control because up/down controls can only be buddied with edit controls.

See Also

UDM_GETBUDDY


UDM_SETPOS

This message sets the current position for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_SETPOS wParam = 0;
lParam = (LPARAM)MAKELONG((short)nPos,0);

Parameters

nPos
New position for the up-down control. This parameter must be in the range specified by the upper and lower limits for the control.

Return Values

The previous position indicates success.

See Also

UDM_GETPOS


UDM_SETRANGE

This message sets the minimum and maximum positions, or the range, for a up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDM_SETRANGE wParam = 0;
lParam = (LPARAM)MAKELONG((short)nUpper,(short)nLower);

Parameters

nUpper and nLower
Maximum position and minimum position for the up-down control. Neither position can be greater than the UD_MAXVAL value or less than the UD_MINVAL value. In addition, the difference between the two positions cannot exceed UD_MAXVAL.

Return Values

None

See Also

UDM_GETRANGE


UDM_SETRANGE32

This message sets the 32-bit range of an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

UDM_SETRANGE32 wParam = (WPARAM)(int) iLow;
lParam = (LPARAM)(int) iHigh;

Parameters

iLow
Integer value that represents the new lower limit of the up-down control range.
iHigh
Integer value that represents the new upper limit of the up-down control range.

Return Values

None


UDN_DELTAPOS

This notification message is sent by the OS to the parent window of an up-down control when the position of the control is about to change. This happens when the user requests a change in the value by pressing the control's up or down arrow. It is sent in the form of a WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UDN_DELTAPOS pnmud = (NM_UPDOWN FAR *) lParam

Parameters

lpnmud
Long pointer to an NMUPDOWN structure that contains information about the position change.

The iPos member of this structure contains the current position of the control. The iDelta member of the structure is a signed integer that contains the proposed change in position. If the user has clicked the up button, this is a positive value. If the user has clicked the down button, this is a negative value.

Return Values

Nonzero prevents the change in the control's position. Zero accepts the change.

Remarks

The UDN_DELTAPOS notification is sent before the WM_HSCROLL message, which actually changes the control's position. This enables you to examine, accept, modify, or reject the change.

See Also

NM_UPDOWN, WM_COMMAND, WM_VSCROLL


WM_ACTIVATE

This message is sent when a window is being activated or deactivated. This message is sent first to the window procedure of the top-level window being deactivated; it is then sent to the window procedure of the top-level window being activated.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_ACTIVATE fActive = LOWORD(wParam);
fMinimized = (BOOL)HIWORD(wParam); hwnd = (HWND) lParam;

Parameters

fActive
Value of the low-order word of wParam. Specifies whether the window is being activated or deactivated. It is one of the following values:
Value
Description
WA_ACTIVE | Activated by some method other than a mouse click (for example, by a call to the SetActiveWindow function or by use of the keyboard interface to select the window).
WA_CLICKACTIVE | Activated by a mouse click
WA_INACTIVE | Deactivated

fMinimized
Value of the high-order word of wParam. Specifies the minimized state of the window being activated or deactivated. A nonzero value indicates the window is minimized.
hwndPrevious
Handle to the window being activated or deactivated, depending on the value of the fActive parameter. If the value of fActive is WA_INACTIVE, hwndPrevious is the handle to the window being activated. If the value of fActive is WA_ACTIVE or WA_CLICKACTIVE, hwndPrevious is the handle to the window being deactivated. This handle can be NULL.

Return Values

An application should return zero if it processes this message.

Default Action
If the window is being activated and is not minimized, the DefWindowProc function sets the keyboard focus to the window.

Remarks

The fMinimized parameter must be zero.

If the window is activated by a mouse click, it also receives a WM_MOUSEACTIVATE message.

See Also

DefWindowProc


WM_APP

This message is used by applications to help define private messages, usually of the form WM_APP+X, where X is an integer value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_APP 0x8000

Remarks

The WM_APP constant is used to distinguish between message values that are reserved for use by the system and values that can be used by an application to send messages within a private window class. There are five ranges of message numbers.

Range
Description
From 0 through WM_USER –1 | Messages reserved for use by the system.
From WM_USER through 0x7FFF | Integer messages for use by private window classes.
WM_APP through 0xBFFF | Messages available for use by applications.
0xC000 through 0xFFFF | String messages for use by applications.
Greater than 0xFFFF | Reserved by the system for future use.

Message numbers in the first range (from 0 through WM_USER –1) are system-defined. Values not explicitly defined in this range are reserved for use by the system.

Message numbers in the second range (WM_USER through 0x7FFF) can be defined and used by an application to send messages within a private window class. These values cannot be used to define messages that are meaningful throughout an application, because some predefined window classes already define values in this range. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use these values. Messages in this range should not be sent to other applications unless the applications have been designed to exchange messages and to attach the same meaning to the message numbers.

Message numbers in the third range (from 0x8000 through 0xBFFF) are available for application to use as private messages. Message in this range do not conflict with system messages.

Message numbers in the fourth range (from 0xC000 through 0xFFFF) are defined at run time when an application calls the RegisterWindowMessage function to retrieve a message number for a string. All applications that register the same string can use the associated message number for exchanging messages. The actual message number, however, is not a constant and cannot be assumed to be the same between different sessions.

Message numbers in the fifth range (greater than 0xFFFF) are reserved for use by the system.

See Also

WM_USER


WM_CANCELMODE

This message is sent to the focus window when a dialog box or message box is displayed; this enables the focus window to cancel modes, such as stylus capture.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CANCELMODE

Return Values

An application should return zero if it processes this message.

Default Action
The DefWindowProc function cancels internal processing of standard scroll bar input, cancels internal menu processing, and releases the mouse capture.

See Also

DefWindowProc, ReleaseCapture


WM_CAPTURECHANGED

This message is sent to the window losing the capture.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CAPTURECHANGED hwndNewCapture = (HWND) lParam;

Parameters

hwndNewCapture
Handle to the window gaining the mouse capture

Return Values

An application should return zero if it processes this message.

Remarks

A window receives this message even if it calls ReleaseCapture itself. An application should not attempt to set the mouse capture in response to this message.

When it receives this message, a window should redraw itself, if necessary, to reflect the new mouse-capture state.

See Also

ReleaseCapture, SetCapture


WM_CHAR

This message is posted to the window with the keyboard focus when a WM_KEYDOWN message is translated by the TranslateMessage function. WM_CHAR contains the character code of the key that was pressed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CHAR chCharCode = (TCHAR) wParam; lKeyData = lParam;

Parameters

chCharCode
Specifies the character code of the key.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Remarks

Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the lKeyData parameter is generally not useful to applications. The information in the high-order word applies only to the most recent WM_KEYDOWN message that precedes the posting of the WM_CHAR message.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_KEYDOWN


WM_CHARTOITEM

This message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_CHAR message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CHARTOITEM nKey = LOWORD(wParam); nCaretPos = HIWORD(wParam); hwndListBox = (HWND) lParam;

Parameters

nKey
Value of the low-order word of wParam. Specifies the value of the key the user pressed.
nCaretPos
Value of the high-order word of wParam. Specifies the current position of the caret.
hwndListBox
Handle to the list box

Return Values

The return value specifies the action that the application performed in response to the message. A return value of –1 or –2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. A return value of 0 or greater specifies the zero-based index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the given item.

Default Action
The DefWindowProc function returns –1.

Remarks

Only owner-drawn list boxes that do not have the LBS_HASSTRINGS style can receive this message.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, WM_CHAR, WM_VKEYTOITEM


WM_CLEAR

This message is sent by an application to an edit control or combo box to delete, or clear, the current selection, if any, from the edit control.

Syntax

WM_CLEAR wParam = 0; lParam = 0;

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Return Values

None

Remarks

The deletion performed by the WM_CLEAR message can be undone by sending the edit control an EM_UNDO message.

To delete the current selection and place the deleted content on the clipboard, use the WM_CUT message.

When sent to a combo box, the WM_CLEAR message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

EM_UNDO, WM_COPY, WM_CUT, WM_PASTE


WM_CLOSE

This message is sent as a signal that a window or an application should terminate.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CLOSE wParam = 0; lParam = 0;

Return Values

An application should return zero if it processes this message.

Default Action
The DefWindowProc function calls the DestroyWindow function to destroy the window.

Remarks

An application can prompt the user for confirmation, prior to destroying a window, by processing the WM_CLOSE message and calling the DestroyWindow function only if the user confirms the choice.

See Also

DefWindowProc, DestroyWindow


WM_COMMAND

This message is sent when the user selects a command item from a menu, when a control sends a notification message to its parent window, or when an accelerator keystroke is translated.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_COMMAND wNotifyCode = HIWORD(wParam); wID = LOWORD(wParam); hwndCtl = (HWND) lParam;

Parameters

wNotifyCode
Value of the high-order word of wParam. Specifies the notification code if the message is from a control. If the message is from an accelerator, this parameter is 1. If the message is from a menu, this parameter is 0.
wID
Value of the low-order word of wParam. Specifies the identifier of the menu item, control, or accelerator.
hwndCtl
Handle to the control sending the message if the message is from a control. Otherwise, this parameter is NULL.

Return Values

An application should return zero if it processes this message.

Remarks

Accelerator keystrokes that select items from the window menu are translated into WM_SYSCOMMAND messages.

If an accelerator keystroke occurs that corresponds to a menu item when the window that owns the menu is minimized, no WM_COMMAND message is sent. However, if an accelerator keystroke occurs that does not match any of the items in the window’s menu or in the window menu, a WM_COMMAND message is sent, even if the window is minimized.

If an application enables a menu separator, the system sends a WM_COMMAND message with the low-word of the wParam parameter set to zero when the user selects the separator.


WM_COMPAREITEM

This message is sent by the OS to determine the relative position of a new item in the sorted list of an owner-drawn combo box or list box. When the application adds a new item, Windows sends this message to the owner of a combo box or list box created with the CBS_SORT or LBS_SORT style.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_COMPAREITEM idCtl = wParam;
lpcis = (LPCOMPAREITEMSTRUCT) lParam;

Parameters

idCtl
Identifier of the control that sent the WM_COMPAREITEM message.
lpcis
Long pointer to a COMPAREITEMSTRUCT structure that contains the identifiers and application-supplied data for two items in the combo or list box.

Return Values

The return value indicates the relative position of the two items. It is one of the following:

Value
Meaning
–1 | Item 1 precedes item 2 in the sorted order.
0 | Items 1 and 2 are equivalent in the sorted order.
1 | Item 1 follows item 2 in the sorted order.

Remarks

When the owner of an owner-drawn combo box or list box receives this message, the owner returns a value indicating which of the items specified by the COMPAREITEMSTRUCT structure will appear before the other. Typically, the system sends this message several times until it determines the exact position for the new item.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.


WM_COPY

This message is sent by an application to an edit control or combo box to copy the current selection to the clipboard in CF_UNICODETEXT format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_COPY wParam = 0; lParam = 0;

Return Values

None

Remarks

When sent to a combo box, the WM_COPY message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_CUT, WM_PASTE


WM_COPYDATA

This message is sent when an application passes data to another application.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_COPYDATA wParam = (WPARAM)(HWND) hwndFrom;
lParam = (LPARAM)(PCOPYDATASTRUCT) pcds;

Parameters

hwnd
Handle to the window passing the data.
pcds
Pointer to a COPYDATASTRUCT structure that contains the data to be passed.

Return Values

If the receiving application processes this message, it should return TRUE; otherwise, it should return FALSE.

Remarks

An application must use the SendMessage function to send this message, not the PostMessage function.

The data being passed must not contain pointers or other references to objects not accessible to the application receiving the data.

While this message is being sent, the referenced data must not be changed by another thread of the sending process.

The receiving application should consider the data read-only. The pcds parameter is valid only during the processing of the message. The receiving application should not free the memory referenced by pcds. If the receiving application must access the data after SendMessage returns, it must copy the data into a local buffer.

For Windows CE versions 1.0 through 2.11, pcds cannot be a global or static variable. This causes the COPYDATASTRUCT structure to be corrupt when it reaches its destination. Later versions of Windows CE do not have this restriction.

See Also

PostMessage, SendMessage


WM_CREATE

This message is sent when an application requests that a window be created by calling the CreateWindowEx or CreateWindow function. The window procedure of the new window receives this message after the window is created, but before the window becomes visible. The message is sent before the CreateWindowEx or CreateWindow function returns.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CREATE lpcs = (LPCREATESTRUCT) lParam;

Parameters

lpcs
Pointer to a CREATESTRUCT structure that contains information about the window being created. The members of CREATESTRUCT are identical to the Parameters of the CreateWindowEx function.

Return Values

If an application processes this message, it should return 0 to continue creation of the window. If the application returns –1, the window is destroyed and the CreateWindowEx or CreateWindow function returns a NULL handle.

Remarks

Some members of the CREATESTRUCT structure to which the lpcs points are restricted. See the CreateWindow function for details.

See Also

CreateWindow, CreateWindowEx, CREATESTRUCT


WM_CTLCOLORBTN

This message is sent to the parent window of a button when the button is about to be drawn. By responding to this message, the parent window can set a button’s text and background colors.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CTLCOLORBTN hdcButton = (HDC) wParam; hwndButton = (HWND) lParam;

Parameters

hdcButton
Handle to the display context for the button.
hwndButton
Handle to the button.

Return Values

If an application processes this message, it must return a handle to a brush. The system uses the brush to paint the background of the button.

Default Action
The DefWindowProc function selects the default system colors for the button.

Remarks

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLORBTN message is never sent between threads. It is sent only within one thread.

The text color of a check box or radio button applies to the box or button, its check mark, and the text. The focus rectangle for these buttons remains the system default color (typically black). The text color of a group box applies to the text but not to the line that defines the box. The text color of a push button applies only to its focus rectangle; it does not affect the color of the text.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORDLG

This message is sent to a dialog box before Windows draws the dialog box. By responding to this message, the dialog box can set its text and background colors by using the given display device context handle. The DefWindowProc function selects the default system colors for the dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CTLCOLORDLG hdcDlg = (HDC) wParam;
hwndDlg = (HWND) lParam;

Parameters

hdcDlg
Handle to the device context for the dialog box
hwndDlg
Handle to the dialog box

Return Values

If an application processes this message, it must return the handle of a brush. The system uses the brush to paint the background of the dialog box.

Default Action
The DefWindowProc function selects the default system colors for the dialog box.

Remarks

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLORDLG message is never sent between threads. It is sent only within one thread.

Note that the WM_CTLCOLORDLG message is sent to the dialog box itself; all of the other WM_CTLCOLOR* messages are sent to the owner of the control.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc


WM_CTLCOLOREDIT

This message is sent to the parent window of an edit control when the control is about to be drawn. By responding to this message, the parent window can use the specified device context handle to set the text and background colors of the edit control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CTLCOLOREDIT hdcEdit = (HDC) wParam; hwndEdit = (HWND) lParam;

Parameters

hdcEdit
Handle to the device context for the edit control window.
hwndEdit
Handle to the edit control.

Return Values

If an application processes this message, it must return the handle of a brush. The system uses the brush to paint the background of the edit control.

Default Action
The DefWindowProc function selects the default system colors for the edit control.

Remarks

Read-only or disabled edit controls do not send the WM_CTLCOLOREDIT message; instead, they send the WM_CTLCOLORSTATIC message. However, for compatibility purposes, the system sends the WM_CTLCOLOREDIT message for read-only and disabled edit controls if the application was designed for Windows 3.1 or earlier.

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLOREDIT message is never sent between threads, it is only sent within the same thread.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORLISTBOX

This message is sent to the parent window of a list box before Windows draws the list box. By responding to this message, the parent window can set the text and background colors of the list box by using the specified display device context handle.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CTLCOLORLISTBOX hdcLB = (HDC) wParam; hwndLB = (HWND) lParam;

Parameters

hdcLB
Handle to the device context for the list box
hwndLB
Handle to the list box

Return Values

If an application processes this message, it must return a handle to a brush. The system uses the brush to paint the background of the list box.

Default Action
The DefWindowProc function selects the default system colors for the list box.

Remarks

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLORLISTBOX message is never sent between threads. It is sent only within one thread.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORMSGBOX

This message is sent to the owner window of a message box before Windows draws the message box. By responding to this message, the owner window can set the text and background colors of the message box by using the specified display device context handle.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CTLCOLORMSGBOX hdcMB = (HDC) wParam; hwndMB = (HWND) lParam;

Parameters

hdcMB
Handle to the device context for the message box
hwndMB
Handle to the message box

Return Values

If an application processes this message, it must return the handle of a brush. The system uses the brush to paint the background of the message box.

Default Action
The DefWindowProc function selects the default system colors for the message box.

Remarks

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLORMSGBOX message is never sent between threads. It is sent only within one thread.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORSCROLLBAR

This message is sent to the parent window of a scroll bar control when the control is about to be drawn. By responding to this message, the parent window can use the specified display context handle to set the background color of the scroll bar control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CTLCOLORSCROLLBAR hdcSB = (HDC) wParam; hwndSB = (HWND) lParam;

Parameters

hdcSB
Handle to the device context for the scroll bar control.
hwndSB
Handle to the scroll bar.

Return Values

If an application processes this message, it must return the handle to a brush. The system uses the brush to paint the background of the scroll bar control.

Default Action
The DefWindowProc function selects the default system colors for the scroll bar control.

Remarks

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLORSCROLLBAR message is never sent between threads; it is only sent within the same thread.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSTATIC


WM_CTLCOLORSTATIC

This message is sent to the parent window of a static control when the control is about to be drawn. By responding to this message, the parent window can use the specified device context handle to set the text and background colors of the static control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_CTLCOLORSTATIC hdcStatic = (HDC) wParam; hwndStatic = (HWND) lParam;

Parameters

hdcStatic
Handle to the device context for the static control window.
hwndStatic
Handle to the static control.

Return Values

If an application processes this message, the return value is a handle to a brush that the system uses to paint the background of the static control.

Default Action
The DefWindowProc function selects the default system colors for the static control.

Remarks

Edit controls that are not read-only or disabled do not send the WM_CTLCOLORSTATIC message; instead, they send the WM_CTLCOLOREDIT message. However, for compatibility purposes, the system sends the WM_CTLCOLOREDIT message for read-only and disabled edit controls if the application was designed for Windows 3.1 or earlier.

The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed.

The WM_CTLCOLORSTATIC message is never sent between threads; it is sent only within the same thread.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. If the dialog box procedure returns FALSE, then default message handling is performed. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR


WM_CUT

This message is sent by an application to an edit control or combo box to delete (cut) the current selection, if any, in the edit control and copy the deleted text to the clipboard in CF_UNICODETEXT format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_CUT wParam = 0; lParam = 0;

Return Values

None

Remarks

The deletion performed by the WM_CUT message can be undone by sending the edit control an EM_UNDO message.

To delete the current selection without placing the deleted text on the clipboard, use the WM_CLEAR message.

When sent to a combo box, the WM_CUT message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

EM_UNDO, WM_CLEAR, WM_COPY, WM_PASTE


WM_DEADCHAR

This message is posted to the window with the keyboard focus when a WM_KEYUP message is translated by the TranslateMessage function. WM_DEADCHAR specifies a character code generated by a dead key. A dead key is a key that generates a character, such as the umlaut (double-dot), that is combined with another character to form a composite character. For example, the umlaut-O character is generated by typing the dead key for the umlaut character, and then typing the O key.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_DEADCHAR chCharCode = (TCHAR) wParam; lKeyData = lParam;

Parameters

chCharCode
Specifies the character code generated by the dead key.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Remarks

The WM_DEADCHAR message typically is used by applications to give the user feedback about each key pressed. For example, an application can display the accent in the current character position without moving the caret.

Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the lKeyData parameter is generally not useful to applications. The information in the high-order word applies only to the most recent WM_KEYDOWN message that precedes the posting of the WM_DEADCHAR message.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_KEYDOWN, WM_KEYUP, WM_SYSDEADCHAR


WM_DELETEITEM

This message is sent to the owner of a list box or combo box when the list box or combo box is destroyed or when items are removed by the LB_DELETESTRING, LB_RESETCONTENT, CB_DELETESTRING, or CB_RESETCONTENT message. Windows sends a WM_DELETEITEM message for each deleted item. Windows sends the WM_DELETEITEM message for any deleted list box or combo box item with nonzero item data.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_DELETEITEM idCtl = wParam; lpdis = (LPDELETEITEMSTRUCT) lParam;

Parameters

idCtl
Identifier of the control that sent the WM_DELETEITEM message.
lpdis
Long pointer to a DELETEITEMSTRUCT structure that contains information about the item deleted from a list box.

Return Values

An application should return TRUE if it processes this message.

See Also

CB_DELETESTRING, CB_RESETCONTENT, DELETEITEMSTRUCT, LB_DELETESTRING, LB_RESETCONTENT


WM_DESTROY

This message is sent when a window is being destroyed. It is sent to the window procedure of the window being destroyed after the window is removed from the screen.

This message is sent first to the window being destroyed and then to the child windows, if any, as they are destroyed. During the processing of the message, it can be assumed that all child windows still exist.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_DESTROY wParam = 0; lParam = 0;

Return Values

An application should return zero if it processes this message.

Remarks

In Windows CE, DefWindowProc does not automatically call PostQuitMessage in its handling of WM_DESTROY.

If the window being destroyed is part of the clipboard viewer chain (set by calling the SetClipboardViewer function), the window must remove itself from the chain by processing the ChangeClipboardChain function before returning from the WM_DESTROY message.

See Also

DestroyWindow, PostQuitMessage, WM_CLOSE


WM_DESTROYCLIPBOARD

This message is sent to the clipboard owner when a call to the EmptyClipboard function empties the clipboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_DESTROYCLIPBOARD wParam = 0; lParam = 0;

Return Values

If an application processes this message, it should return zero.

See Also

EmptyClipboard


WM_DRAWITEM

This message is sent to the owner window of an owner-drawn button or menu when a visual aspect of the button or menu has changed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_DRAWITEM idCtl = (UINT) wParam;
lpdis = (LPDRAWITEMSTRUCT) lParam;

Parameters

idCtl
Identifier of the control that sent the WM_DRAWITEM message. If the message was sent by a menu, this parameter is zero.
lpdis
Long pointer to a DRAWITEMSTRUCT structure containing information about the item to be drawn and the type of drawing required.

Return Values

An application should return TRUE if it processes this message.

Default Action
The DefWindowProc function draws the focus rectangle for an owner-drawn list box item.

Remarks

In the case of a menu item, the receiver of this message is responsible for erasing the background if necessary.

In Windows CE version 2.0, the hDC member of the DRAWITEMSTRUCT structure pointed to by the lParam is initialized to the grayed or highlighted status of the current item.

The itemAction member of the DRAWITEMSTRUCT structure specifies the drawing operation that an application should perform.

Before returning from processing this message, an application should ensure that the device context identified by the hDC member of the DRAWITEMSTRUCT structure is in the default state.

See Also

DRAWITEMSTRUCT


WM_ENABLE

This message is sent when an application changes the enabled state of a window. It is sent to the window whose enabled state is changing. This message is sent before the EnableWindow function returns, but after the enabled state—the WS_DISABLED style bit—of the window has changed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_ENABLE fEnabled = (BOOL) wParam;

Parameters

fEnabled
Boolean value that specifies whether the window has been enabled or disabled. Set to TRUE if the window has been enabled, or to FALSE if the window has been disabled.

Return Values

An application should return zero if it processes this message.

See Also

EnableWindow


WM_ENTERMENULOOP

This message informs an application's main window procedure that a menu modal loop has been entered.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_ENTERMENULOOP fIsTrackPopupMenu = (BOOL) wParam;

Parameters

fIsTrackPopupMenu
Boolean that specifies whether the window menu was entered using the TrackPopupMenu function. Set to TRUE if the window menu was entered using TrackPopupMenu, or to FALSE if it was not.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

DefWindowProc, WM_EXITMENULOOP


WM_ERASEBKGND

This message is sent by an application when the window background must be erased, for example, when a window is resized. The message is sent to prepare an invalidated portion of a window for painting.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_ERASEBKGND hdc = (HDC) wParam;

Parameters

hdc
Handle to the device context.

Return Values

An application should return nonzero if it erases the background; otherwise, it should return zero.

Remarks

The DefWindowProc function erases the background by using the class background brush specified by the hbrBackground member of the WNDCLASS structure. If hbrBackground is NULL, the application should process the WM_ERASEBKGND message and erase the background.

An application should return nonzero in response to WM_ERASEBKGND if it processes the message and erases the background; this indicates that no further erasing is required. If the application returns zero, the window will remain marked for erasing. (Typically, this indicates that the fErase member of the PAINTSTRUCT structure will be TRUE.)

See Also

BeginPaint, DefWindowProc, PAINTSTRUCT, WNDCLASS


WM_EXITMENULOOP

This message informs an application's main window procedure that a menu modal loop has been exited.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_EXITMENULOOP fIsTrackPopupMenu = (BOOL) wParam;

Parameters

fIsTrackPopupMenu
Boolean that specifies whether the menu involved is a shortcut menu. Set to TRUE if it is a shortcut menu, or to FALSE otherwise.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

DefWindowProc, WM_ENTERMENULOOP


WM_FONTCHANGE

This message is sent by an application to all top-level windows in the system after changing the pool of font resources.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_FONTCHANGE wParam = 0; lParam = 0;

Remarks

An application that adds or removes fonts from the system (for example, by using the AddFontResource or RemoveFontResource function) should send this message to all top-level windows.

To send the WM_FONTCHANGE message to all top-level windows, an application can call the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

See Also

AddFontResource, RemoveFontResource, SendMessage


WM_GETDLGCODE

This message is sent to the dialog box procedure associated with a control. Normally, Windows handles all arrow-key and TAB-key input to the control. By responding to the WM_GETDLGCODE message, an application can take control of a particular type of input and process the input itself.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_GETDLGCODE wParam = 0; lParam = 0;

Parameters

pMsg
NULL if the system is performing a query, or is otherwise a pointer to an MSG structure.

Return Values

One or more of the values, indicating which type of input the application processes and described in the following table, is returned.

Value
Description
DLGC_BUTTON | Button.
DLGC_DEFPUSHBUTTON | Default push button.
DLGC_HASSETSEL | EM_SETSEL messages.
DLGC_RADIOBUTTON | Radio button.
DLGC_STATIC | Static control.
DLGC_UNDEFPUSHBUTTON | Non-default push button.
DLGC_WANTALLKEYS | All keyboard input.
DLGC_WANTARROWS | Direction keys.
DLGC_WANTCHARS | WM_CHAR messages.
DLGC_WANTMESSAGE | All keyboard input (the application passes this message in the MSG structure to the control).
DLGC_WANTTAB | TAB key.

Default Action
The DefWindowProc function returns zero.

Remarks

Although the DefWindowProc function always returns zero in response to the WM_GETDLGCODE message, the window procedure for the predefined control classes return a code appropriate for each class.

The WM_GETDLGCODE message and the returned values are useful only with user-defined dialog box controls or standard controls modified by subclassing.

See Also

DefWindowProc, EM_SETSEL, WM_CHAR


WM_GETFONT

This message is sent by an application to a control to retrieve the font with which the control is currently drawing its text.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_GETFONT wParam = 0; lParam = 0;

Return Values

The return value is a handle to the font used by the control, or NULL if the control is using the system font.

See Also

WM_SETFONT


WM_GETICON

This message is sent to a window to retrieve the handle of the big or small icon associated with a window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_GETICON fType = (BOOL) wParam;

Parameters

fType
Specifies the type of icon being retrieved. It is one of the following values:
Value
Description
ICON_BIG | Retrieves the large icon for the window.
ICON_SMALL | Retrieves the small icon for the window.

Return Values

The return value is a handle to the large or small icon, depending on the value of fType. When an application receives this message, it can return a handle to a large or small icon, or pass the message to DefWindowProc.

Default Action
DefWindowProc returns a handle to the large or small icon associated with the window, depending on the value of fType.

Remarks

Icons are stored per window class, not per window.

When an application receives this message, it can return a handle to a large or small icon, or pass the message to DefWindowProc.

See Also

DefWindowProc, WM_SETICON


WM_GETTEXT

This message is sent by an application to copy the text that corresponds to a window into a buffer provided by the caller.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_GETTEXT wParam = (WPARAM) cchTextMax;
lParam = (LPARAM) lpszText;

Parameters

cchTextMax
Specifies the maximum number of characters to be copied, including the terminating null character.
lpszText
Long pointer to the buffer that is to receive the text.

Return Values

The return value is the number of characters copied.

Default Action
The DefWindowProc function copies the text associated with the window into the specified buffer and returns the number of characters copied.

Remarks

For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To copy the text of an item in a list box, an application can use the LB_GETTEXT message.

When the WM_GETTEXT message is sent to a static control with the SS_ICON style, a handle to the icon will be returned in the first four bytes of the buffer pointed to by lpszText. This is true only if the WM_SETTEXT message has been used to set the icon.

In a rich edit control, if the text to be copied exceeds 64K, use either the message EM_STREAMOUT or EM_GETSELTEXT.

See Also

DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXT, WM_GETTEXTLENGTH, WM_SETTEXT


WM_GETTEXTLENGTH

This message is sent by an application to determine the length, in characters, of the text associated with a window. The length does not include the terminating null character.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_GETTEXTLENGTH wParam = 0; lParam = 0;

Return Values

The length, in characters, of the text indicates success.

Default Action
The DefWindowProc function returns the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

Remarks

For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To determine the length of an item in a list box, an application can use the LB_GETTEXTLEN message.

Under certain conditions, the DefWindowProc function returns a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of DBCS characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXT, LB_GETTEXTLEN, WM_GETTEXT


WM_HELP

This message indicates that the user pressed the F1 key. If a menu is active when F1 is pressed, WM_HELP is sent to the window associated with the menu; otherwise, WM_HELP is sent to the window that has the keyboard focus. If no Window has the keyboard focus, WM_HELP is sent to the currently active window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_HELP lphi = (LPHELPINFO) lParam;

Parameters

lphi
Long pointer to a HELPINFO structure that contains information about the menu item, control, dialog box, or window for which Help is requested.

Return Values

Returns TRUE

Remarks

The DefWindowProc function passes WM_HELP to the parent window of a child window or to the owner of a top-level window.

See Also

DefWindowProc


WM_HIBERNATE

This message is sent to an application when system resources are running low. An application should attempt to release as many resources as possible when sent this message by unloading dialog boxes, destroying windows, or freeing up as much local storage as possible without killing the internal state.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_HIBERNATE wParam = 0; lParam = 0;

Remarks

The application leaves this state either by receiving a WM_ACTIVATE message, in which case it is the application’s responsibility to attain the state it was in before the hibernate, or by getting a WM_CLOSE message, in which case the application will exit properly.

See Also

WM_ACTIVATE, WM_CLOSE


WM_HOTKEY

This message is posted when the user presses a hot key registered by the RegisterHotKey function. The message is placed at the top of the message queue associated with the thread that registered the hot key.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_HOTKEY idHotKey = (int) wParam;
fuModifiers = (UINT) LOWORD(lParam);
uVirtKey = (UINT) HIWORD(lParam);

Parameters

idHotKey
Hot key identifier that generated the message. If the message was generated by a system-defined hot key, the idHotKey parameter is one of the following values:
Value
Description
IDHOT_SNAPDESKTOP | The “snap desktop” hot key was pressed.
IDHOT_SNAPWINDOW | The “snap window” hot key was pressed.

fuModifiers
Specifies the keys that were to be pressed in combination with the key specified by the nVirtKey parameter to generate the WM_HOTKEY message. The fuModifiers parameter can be a combination of the following values:
Value
Description
MOD_ALT | Either ALT key was held down.
MOD_CONTROL | Either CTRL key was held down.
MOD_SHIFT | Either SHIFT key was held down.
MOD_WIN | Either WINDOWS key was held down. These keys are labeled with the Microsoft Windows logo.

uVirtKey
Specifies the virtual key code of the hot key.

Remarks

WM_HOTKEY is unrelated to the WM_GETHOTKEY and WM_SETHOTKEY hot keys. The WM_HOTKEY message is sent for generic hot keys while the WM_SET\GETHOTKEY messages relate to window activation hot keys.

See Also

RegisterHotKey


WM_HSCROLL

This message is sent to a window when a scroll event occurs in the window’s standard horizontal scroll bar. This message is also sent to the owner of a horizontal scroll bar control when a scroll event occurs in the control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_HSCROLL nScrollCode = (int)LOWORD(wParam); nPos = (short int)HIWORD(wParam); hwndScrollBar = (HWND) lParam;

Parameters

nScrollCode
Value of the low-order word of wParam. Specifies a scroll bar value that indicates the user’s scrolling request. It is be one of the following values:
Value
Description
SB_ENDSCROLL | Ends scroll.
SB_LEFT | Scrolls to the upper left.
SB_RIGHT | Scrolls to the lower right.
SB_LINELEFT | Scrolls left by one unit.
SB_LINERIGHT | Scrolls right by one unit.
SB_PAGELEFT | Scrolls left by the width of the window.
SB_PAGERIGHT | Scrolls right by the width of the window.
SB_THUMBPOSITION | The user has dragged the scroll box (thumb) and released the mouse button. The nPos parameter indicates the position of the scroll box at the end of the drag operation.
SB_THUMBTRACK | The user is dragging the scroll box. This message is sent repeatedly until the user releases the mouse button. The nPos parameter indicates the position that the scroll box has been dragged to.

nPos
Value of the high-order word of wParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, nPos is not used.
hwndScrollBar
If the message is sent by a scroll bar, then hwndScrollBar is the handle to the scroll bar control. If the message is not sent by a scroll bar, hwndScrollBar is NULL.

Return Values

An application should return zero if it processes this message.

Remarks

The SB_THUMBTRACK notification message is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the content of the window, it must also reset the position of the scroll box by using the SetScrollPos function.

Note that the WM_HSCROLL message carries only 16 bits of scroll box position data. Thus, applications that rely solely on WM_HSCROLL (and WM_VSCROLL) for scroll position data have a practical maximum position value of 65,535.

However, because the SetScrollInfo, SetScrollPos, SetScrollRange, GetScrollInfo, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollInfo for a description of the technique.

See Also

SetScrollPos, SetScrollRange, WM_VSCROLL


WM_IME_CHAR

This message is sent to an application when the IME gets a character of the conversion result. Unlike the WM_CHAR message, this message can include double-byte as well as single-byte character values.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

chCharCode1 = (WORD) wParam;
lKeyData = lParam;

Parameters

chCharCode1 and chCharCode2
(For double-byte character sets) Single- or double-byte character value. For a double-byte character, chCharCode1 contains the lead byte.
chCharCode1
(For Unicode) Unicode character value.
lKeyData
Repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown following:
Value
Description
0–15 | Repeat count: Since the first byte and second byte is continuous, this is always 1.
16–23 | Scan Code: Scan code for a complete FE character.
24–28 | Not used.
29 | Context code.
31 | Conversion state.

Remarks

If the WM_IME_CHAR message includes a double-byte character and the application passes this message to DefWindowProc, the IME converts this message into two WM_CHAR messages, each containing one byte of the double-byte character.


WM_IME_COMPOSITION

This message is sent to an application when the IME changes composition status as a result of a key stroke. An application should process this message if it displays composition characters itself. Otherwise, it should send the message to the IME window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

WM_IME_COMPOSITION chDBCS = (WORD) wParam;
fFlags = (BOOL) lParam;

Parameters

chDBCS
DBCS character that represents the latest change to the composition string.
fFlags
Change flag that indicates how the composition string or character changed. It can be one or more of the following values:
GCS_COMPSTR | GCS_SETCURSORPOS
GCS_COMPATTR | GCS_RESULTSTR
GCS_COMPCLAUSE | GCS_RESULTCLAUSE
GCS_COMPREADSTR | GCS_RESULTREADSTR
GCS_COMPREADATTR | GCS_RESULTREADCLAUSE
GCS_COMPREADCLAUSE | GCR_ERRORSTR
GCS_TYPINGINFO | GCR_INFOSTR

Return Values

None

Remarks

Windows CE applications cannot create IME windows.

For more information about these values, see the “IME Composition String Values” table in Input Method Editor Constants.Windows CE applications cannot create IME windows.

The fFlags parameter can also be a combination of the following values:

CS_INSERTCHAR
Specifies that the given composition character should be inserted at the current insertion point. An application should display the composition character if it processes this message.
CS_NOMOVECARET
Specifies that the application must not move the caret position as a result of processing the message. For example, if an IME specifies a combination of CS_INSERTCHAR and CS_NOMOVECARET, the application should insert the given character at the current caret position but should not move caret to the next position. A subsequent WM_IME_COMPOSITION message with GCS_RESULTSTR will replace this character.

If the application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to the default IME window. The IME window processes this message by updating its appearance based on the change flag given. An application can call ImmGetCompositionString to retrieve the new composition status.

If none of the GCS_* values are set, the message indicates that the current composition has been canceled and applications that draw the composition string should delete the string.

See Also

DefWindowProc, ImmGetCompositionString


WM_IME_COMPOSITIONFULL

This message is sent to an application when the IME window finds no space to extend the area for the composition window. The application should use the IMC_SETCOMPOSITIONWINDOW message to specify how to display the window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Return Values

None

Remarks

The wParam and lParam Parameters are not used. The IME window, not the IME, sends this notification message by using the SendMessage message.

See Also

SendMessage


WM_IME_CONTROL

This message directs the IME window to carry out the requested command. An application uses this message to control the IME window created by the application.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

wParam = (WPARAM) (DWORD) dwCommand;
lParam = (LPARAM) (DWORD) i;

Parameters

dwCommand
Specifies a command value. It is of the following values:
IMC_GETCANDIDATEPOS | IMC_OPENSTATUSWINDOW
IMC_GETCOMPOSITIONFONT | IMC_SETCANDIDATEPOS
IMC_GETCOMPOSITIONWINDOW | IMC_SETCOMPOSITIONFONT
IMC_GETCONVERSIONMODE | IMC_SETCOMPOSITIONWINDOW
IMC_GETOPENSTATUS | IMC_SETCONVERSIONMODE
IMC_GETSENTENCEMODE | IMC_SETOPENSTATUS
IMC_GETSTATUSWINDOWPOS | IMC_SETSENTENCEMODE
IMC_CLOSESTATUSWINDOW | IMC_SETSTATUSWINDOWPOS

For more information about these commands, see the individual descriptions.

dwData
Specifies a command-specific value.

Return Values

Returns a command-specific value


WM_IME_ENDCOMPOSITION

This message is sent to an application when the IME ends composition. An application should process this message if it displays composition characters itself.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

Windows CE applications cannot create IME windows.

The wParam and lParam parameters are not used.

If an application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to default IME window.

See Also

DefWindowProc


WM_IME_KEYDOWN

This message is sent to an application by the IME to notify the application of a key press. The Parameters and return value for this message are identical to the WM_KEYDOWN message. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYDOWN message. This message is usually generated by the IME to keep message order.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

WM_IME_KEYDOWN nVirtKey = (int) wParam;lKeyData = lParam;

Parameters

nVirtKey
Virtual-key code.
lKeyData
Key data.

See Also

DefWindowProc


WM_IME_KEYUP

This message is sent to an application by the IME to notify the application of a key release. The Parameters and return value for this message are identical to the WM_KEYUP message. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYUP message. This message is usually generated by the IME to keep message order.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

WM_IME_KEYUP nVirtKey = (int) wParam lKeyData = lParam;

Parameters

nVirtKey
Virtual-key code.
lKeyData
Key data.

See Also

DefWindowProc


WM_IME_NOTIFY

This message is sent to an application to notify it of changes to the IME window. An application processes this message if it is responsible for managing the IME window.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

WM_IME_NOTIFY dwCommand = (DWORD) wParam;
dwData = (DWORD) lParam;

Parameters

dwCommand
Specifies one of the following command values:
IMN_CHANGECANDIDATE IMN_SETCANDIDATEPOS
IMN_CLOSECANDIDATE IMN_SETCOMPOSITIONFONT
IMN_CLOSESTATUSWINDOW IMN_SETCOMPOSITIONWINDOW
IMN_GUIDELINE IMN_SETCONVERSIONMODE
IMN_OPENCANDIDATE IMN_SETOPENSTATUS
IMN_OPENSTATUSWINDOW IMN_SETSENTENCEMODE
IMN_PRIVATE IMN_SETSTATUSWINDOWPOS

For more information about these commands, see the corresponding descriptions.

dwData
Specifies a command-specific value.

Return Values

Returns a command-specific value.

IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE, IMN_OPENSTATUSWINDOW, IMN_SETCANDIDATEPOS, IMN_SETCOMPOSITIONFONT, IMN_SETCOMPOSITIONWINDOW, IMN_SETCONVERSIONMODE, IMN_SETOPENSTATUS, IMN_SETSENTENCEMODE, IMN_SETSTATUSWINDOWPOS

Remarks

Windows CE supports the following values for the dwCommand parameter:

IMN_CHANGECANDIDATE | IMN_SETCANDIDATEPOS
IMN_CLOSECANDIDATE | IMN_SETCOMPOSITIONWINDOW
IMN_OPENCANDIDATE | IMN_SETCONVERSIONMODE
IMN_PRIVATE | IMN_SETOPENSTATUS
 | IMN_SETSENTENCEMODE


WM_IME_REQUEST

This message requests information about the state of the IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

dwRequest = (WPARAM) (DWORD)wParam;
dwDate = (LPARAM) (DWORD) lParam;

Parameters

dwRequest
Specifies a request value. It is of the following values:
IMR_CANDIDATEFORM | IMR_DOCUMENTFEED
IMR_COMPOSITIONFONT | IMR_QUERYCHARPOSITION
IMR_COMPOSITIONFORM IMR_RECONVERTSTRING
IMR_CONFIRMRECONVERTSTRING

dwData
Specifies request-specific data. For more information about this data, see the description for each request value.

Return Values

Returns a request-specific value. For more information about this data, see the description for each request value.


WM_IME_SELECT

This message is sent to an application when the system is about to change the current IME. An application that has created an IME window should pass this message to that window so that it can retrieve the keyboard layout handle for the newly selected IME.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later

Syntax

fSeleft = (BOOL) wParam; hKL = (HANDLE) lParam;

Parameters

fSelect
Boolean that is set to TRUE if the specified IME is selected, or to FALSE if the specified IME is no longer selected.
hKL
Handle to the keyboard layout associated with the IME.

Return Values

None

Remarks

The DefWindowProc function processes this message by passing the information to the default IME window.


WM_IME_SETCONTEXT

This message is sent to an application when a window of the application is activated.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Syntax

WM_IME_SETCONTEXT fSet = (BOOL) wParam;
iShow = (DWORD) lParam;

Parameters

fSet
Boolean that is set to TRUE if the input context is active, or to a FALSE, the context is inactive.
iShow
Show flags. It can be a combination of the following values:
Value
Description
ISC_SHOWUICOMPOSITIONWINDOW | Shows the composition window by UI window.
ISC_SHOWUIGUIDWINDOW | Shows the guide window by UI window
ISC_SHOWUISOFTKBD | Shows the soft keyboard by UI window
ISC_SHOWUICANDIDATEWINDOW | Shows the candidate window of Index 0 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 1 | Shows the candidate window of Index 1 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 2 | Shows the candidate window of Index 2 by UI window.
ISC_SHOWUICANDIDATEWINDOW << 3 | Shows the candidate window of Index 3 by UI window.

If the application draws the composition window, the default IME window does not need to show its composition window. In this case, the application must clear the ISC_SHOWUICOMPOSITIONWINDOW value from the lParam parameter before passing the message to the DefWindowProc or ImmIsUIMessage functions.

Return Values

Returns the value returned by DefWindowProc or ImmIsUIMessage.

Remarks

Windows CE applications should pass this message to the DefWindowProc function.

See Also

DefWindowProc, ImmIsUIMessage


WM_IME_STARTCOMPOSITION

This message is sent immediately before the IME generates composition string as a result of a key stroke. The message is a notification to an IME window to open its composition window. An application should process this message if it displays composition characters itself.

At a Glance

Header file: | Imm.h
Windows CE versions: | 2.10 and later (Japanese version 1.0 and later)

Return Values

None

Remarks

The wParam and lParam Parameters are not used.

If an application has created an IME window, it should pass the WM_IME_STARTCOMPOSITION message to that window. The DefWindowProc function processes this message by passing it to the default IME window.

Remarks

Windows CE applications cannot create IME windows.

See Also

DefWindowProc


WM_IN_INFO

A process that registers for IM notifications receives this window message when the size or position of an input method (IM) changes. This message is also received when an IM’s state changes and specifies an icon to display for the new state.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.10 and later

Syntax

WM_IM_INFO wParam = (WPARAM) flag; lParam = (LPARAM) pdata;

Parameters

flag
Identifies the type of change incurred by the IM. It is one of the following values:
Value
Description
IM_POSITION | The size or position of the IM has changed.
IM_WIDEIMAGE | The IM has selected a new wide image (32x16 pixels) to associate with its current state.
IM_NARROWIMAGE | The IM has selected a new narrow image (16x16 pixels) to associate with its current state.

pdata
Pointer to data related to the specific type of change incurred by the IM. It is one of the following values:
Value
Description
IM_POSITION | The lParam parameter is not used. To retrieve the current position of the IM window, call the SipGetInfo function.
IM_WIDEIMAGE | The lParam parameter is set to the handle of a wide image icon.
IM_NARROWIMAGE | The lParam parameter is set to the handle of a narrow image icon.

Return Values

When an application processes this message, it should return zero.


WM_INITDIALOG

This message is sent to the dialog box procedure immediately before a dialog box is displayed. Dialog box procedures typically use this message to initialize controls and carry out any other initialization tasks that affect the appearance of the dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_INITDIALOG hwndFocus = (HWND) wParam;lInitParam = lParam;

Parameters

hwndFocus
Handle to the control to receive the default keyboard focus. The system assigns the default keyboard focus only if the dialog box procedure returns TRUE.
lInitParam
Specifies additional initialization data. This data is passed to the system as the lParamInit parameter in a call to the CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, or DialogBoxParam function used to create the dialog box. For property sheets, this parameter is a pointer to the PROPSHEETPAGE structure used to create the page. This parameter is zero if any other dialog box creation function is used.

Return Values

The dialog box procedure should return TRUE to direct the system to set the keyboard focus to the control given by hwndFocus. Otherwise, it should return FALSE to prevent the system from setting the default keyboard focus.

The dialog box procedure should return the value directly. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

Remarks

The control to receive the default keyboard focus is always the first control in the dialog box that is visible, not disabled, and that has the WS_TABSTOP style. When the dialog box procedure returns TRUE, the system checks the control to ensure that the procedure has not disabled it. If it has been disabled, the system sets the keyboard focus to the next control that is visible, not disabled, and has the WS_TABSTOP.

An application can return FALSE only if it has set the keyboard focus to one of the controls of the dialog box.

See Also

CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, DialogBoxParam, SetFocus


WM_INITMENUPOPUP

This message is sent when a pop-up menu is about to become active. This enables an application to modify the pop-up menu before it is displayed, without changing the entire menu.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_INITMENUPOPUP hmenuPopup = (HMENU) wParam;
uPos = (UINT)LOWORD(lParam);
fSystemMenu = (BOOL)HIWORD(lParam);

Parameters

hmenuPopup
Handle to the drop-down menu or submenu.
uPos
Value of the low-order word of lParam. Specifies the zero-based relative position of the menu item that opens the drop-down menu or submenu.
fSystemMenu
Value of the high-order word of lParam. Boolean that specifies whether the drop-down menu is the window menu (also known as the System menu or the Control menu). Set to TRUE if the menu is the window menu, or to FALSE otherwise.

Return Values

An application should return zero if it processes this message.

Remarks

The fSystemMenu parameter is always FALSE.


WM_KEYDOWN

This message is posted to the window with the keyboard focus when a nonsystem key is pressed. A nonsystem key is a key that is pressed when the ALT key is not pressed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_KEYDOWN nVirtKey = (int) wParam; lKeyData = lParam;

Parameters

nVirtKey
Specifies the virtual-key code of the nonsystem key.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Default Action
If the F10 key is pressed, the DefWindowProc function sets an internal flag. When DefWindowProc receives the WM_KEYUP message, the function checks whether the internal flag is set and, if so, sends a WM_SYSCOMMAND message to the top-level window. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

Because of the autorepeat feature, more than one WM_KEYDOWN message may be posted before a WM_KEYUP message is posted. The previous key state (bit 30) can be used to determine whether the WM_KEYDOWN message indicates the first down transition or a repeated down transition.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

DefWindowProc, WM_CHAR, WM_KEYUP


WM_KEYFIRST

Keyboard message filter value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Remarks

Use the WM_KEYFIRST and WM_KEYLAST messages to filter for keyboard messages when using the GetMessage and PeekMessage functions.


WM_KEYLAST

Keyboard message filter value.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Remarks

Use the WM_KEYFIRST and WM_KEYLAST messages to filter for keyboard messages when using the GetMessage and PeekMessage functions.


WM_KEYUP

This message is posted to the window with the keyboard focus when a nonsystem key is released. A nonsystem key is a key that is pressed when the ALT key is not pressed, or a keyboard key that is pressed when a window has the keyboard focus.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_KEYUP nVirtKey = (int) wParam; lKeyData = lParam;

Parameters

nVirtKey
Specifies the virtual-key code of the nonsystem key.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Default Action
The DefWindowProc function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

DefWindowProc, WM_KEYDOWN


WM_KILLFOCUS

This message is sent to a window immediately before it loses the keyboard focus.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_KILLFOCUS hwndGetFocus = (HWND) wParam;

Parameters

hwndGetFocus
Handle to the window that receives the keyboard focus; can be NULL.

Return Values

An application should return zero if it processes this message.

Remarks

If an application is displaying a caret, the caret should be destroyed at this point.

See Also

SetFocus, WM_SETFOCUS


WM_LBUTTONDBLCLK

This message is posted when the user double-taps the touch-screen while the stylus is pressed to the touch screen in the client area of a window. If the stylus is not captured, the message is posted to the window beneath the stylus position. Otherwise, the message is posted to the window that has captured the mouse.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_LBUTTONDBLCLK fwKeys = wParam; xPos = LOWORD(lParam); yPos = HIWORD(lParam);

Parameters

fwKeys
Indicates whether various virtual keys are down. It is any combination of the following values:
Value
Description
MK_CONTROL | Set if the CTRL key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the SHIFT key is down.

xPos
Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.
yPos
Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

An application should return zero if it processes this message.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_LBUTTONDBLCLK messages, which the system generates when the user presses, releases, and again presses the left mouse button within the system’s double-click time limit. Double-clicking the left mouse button actually generates four messages: WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, and WM_LBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, WM_LBUTTONDOWN, WM_LBUTTONUP


WM_LBUTTONDOWN

This message is posted when the user presses the touch-screen in the client area of a window. If the stylus event is not captured, the message is posted to the window beneath the stylus position. Otherwise, the message is posted to the window that has the capture.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_LBUTTONDOWN fwKeys = wParam; xPos = LOWORD(lParam);
yPos = HIWORD(lParam);

Parameters

fwKeys
Indicates whether various virtual keys are down. It is any combination of the following values:
Value
Description
MK_CONTROL | Set if the CTRL key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_SHIFT | Set if the SHIFT key is down.

xPos
Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.
yPos
Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

An application should return zero if it processes this message.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, POINTS, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONUP


WM_LBUTTONUP

This message is posted when the user releases the stylus from the touch-screen while the stylus is pressed to the touch screen in the client area of a window. If stylus input is not captured, the message is posted to the window that contains the stylus tip. If stylus input is captured, the message is posted to the window that has the capture.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_LBUTTONUP fwKeys = wParam; xPos = LOWORD(lParam); yPos = HIWORD(lParam);

Parameters

fwKeys
Indicates whether various virtual keys are down. It is any combination of the following values:
Value
Description
MK_CONTROL | Set if the CTRL key is down.
MK_SHIFT | Set if the SHIFT key is down.

xPos
Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.
yPos
Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Values

An application should return zero if it processes this message.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, POINTS, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONDOWN


WM_MEASUREITEM

This message is sent to the owner window of an owner-drawn button or menu item when the control or menu is created.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_MEASUREITEM idCtl = (UINT) wParam; lpmis = (LPMEASUREITEMSTRUCT) lParam;

Parameters

idCtl
Contains the value of the CtlID member of the MEASUREITEMSTRUCT structure pointed to by the lpmis parameter. This value identifies the control that sent the WM_MEASUREITEM message.

If the value is zero, the message was sent by a menu. If the value is nonzero, the message was sent by a combo box or by a list box. If the value is nonzero, and the value of the itemID member of the MEASUREITEMSTRUCT pointed to by lpmis is (UINT) –1, the message was sent by a combo edit field.

lpmis
Long pointer to a MEASUREITEMSTRUCT structure that contains the dimensions of the owner-drawn control or menu item.

Return Values

An application should return TRUE if it processes this message.

Remarks

When the owner window receives the WM_MEASUREITEM message, the owner fills in the MEASUREITEMSTRUCT structure pointed to by the lParam parameter of the message and returns; this informs the system of the dimensions of the control. If a list box or combo box is created with the LBS_OWNERDRAWVARIABLE or CBS_OWNERDRAWVARIABLE style, this message is sent to the owner for each item in the control; otherwise, this message is sent once.

The system sends the WM_MEASUREITEM message to the owner window of combo boxes and list boxes created with the OWNERDRAWFIXED style before sending the WM_INITDIALOG message. As a result, when the owner receives this message, the system has not yet determined the height and width of the font used in the control; function calls and calculations requiring these values should occur in the main function of the application or library.


WM_MENUCHAR

This message is sent when a menu is active and the user presses a key that does not correspond to any mnemonic or accelerator key. This message is sent to the window that owns the menu.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_MENUCHAR chUser = (char)LOWORD(wParam);
fuFlag = (UINT)HIWORD(wParam); hmenu = (HMENU) lParam;

Parameters

chUser
Value of the low-order word of wParam. Specifies the character code that corresponds to the key the user pressed.
fuFlag
Value of the high-order word of wParam. Specifies the type of the active menu and must be:
Value
Description
MF_POPUP Drop-down menu, submenu, or shortcut menu

hmenu
Handle to the active menu.

Return Values

An application that processes this message should return one of the following values in the high-order word of the return value:

Value
Description
MNC_IGNORE | Informs the system that it should discard the character the user pressed and create a short beep on the system speaker.
MNC_CLOSE | Informs the system that it should close the active menu.
MNC_EXECUTE | Informs the system that it should choose the item specified in the low-order word of the return value. The owner window receives a WM_COMMAND message.
MNC_SELECT | Informs the system that it should select the item specified in the low-order word of the return value.

Remarks

The low-order word is ignored if the high-order word contains 0 or 1. An application should process this message when an accelerator is used to select a menu item that displays a bitmap.


WM_MOUSEMOVE

This message is posted to a window when the stylus moves while the tip is down. If stylus input is not captured, the message is posted to the window that contains the stylus tip. If stylus input is captured, the message is posted to the window that has the capture.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_MOUSEMOVE fwKeys = wParam; xPos = LOWORD(lParam); yPos = HIWORD(lParam);

Parameters

fwKeys
Indicates whether various virtual keys are down. It is any combination of the following values:
Value
Description
MK_CONTROL | Set if the CTRL key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_SHIFT | Set if the SHIFT key is down.

xPos
Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.
yPos
Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Remarks

The MAKEPOINTS macro can be used to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, POINTS, SetCapture


WM_MOVE

This message is sent after a window has been moved.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_MOVE xPos = (int)LOWORD(lParam); yPos = (int)HIWORD(lParam);

Parameters

xPos
Value of the low-order word of lParam. Specifies the x-coordinate of the upper-left corner of the client area of the window.
yPos
Value of the high-order word of lParam. Specifies the y-coordinate of the upper-left corner of the client area of the window.

Return Values

An application should return zero if it processes this message.

Remarks

The xPos and yPos Parameters are given in screen coordinates for overlapped and pop-up windows and in parent-client coordinates for child windows.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

POINTS


WM_NEXTDLGCTL

This message is sent to a dialog box procedure to set the keyboard focus to a different control in the dialog box.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_NEXTDLGCTL wCtlFocus = wParam;
fHandle = (BOOL) LOWORD(lParam);

Parameters

wCtlFocus
If the fHandle parameter is TRUE, the wCtlFocus parameter identifies the control that receives the focus. If fHandle is FALSE, wCtlFocus is a flag that indicates whether the next or previous control with the WS_TABSTOP style receives the focus. If wCtlFocus is zero, the next control receives the focus; otherwise, the previous control with the WS_TABSTOP style receives the focus.
fHandle
Boolean value that indicates how the system uses the wCtlFocus parameter. If the fHandle parameter is TRUE, wCtlFocus is a handle associated with the control that receives the focus; otherwise, wCtlFocus is a flag that indicates whether the next or previous control with the WS_TABSTOP style receives the focus.

Return Values

An application should return zero if it processes this message.

Remarks

The effect of this message differs from that of the SetFocus function because WM_NEXTDLGCTL modifies the border around the control.

Do not use the SendMessage function to send a WM_NEXTDLGCTL message if your application will concurrently process other messages that set the focus. Use the PostMessage function instead.

See Also

PostMessage, SendMessage, SetFocus


WM_NOTIFY

This message informs the parent window of a control that an event has occurred in the control or that the control requires some kind of information.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_NOTIFY idCtrl = (int) wParam; pnmh = (LPNMHDR) lParam;

Parameters

idCtrl
Identifier of the common control sending the message. This identifier is not guaranteed to be unique. An application should use the hwndFrom or idFrom member of the NMHDR structure (passed as the lParam parameter) to identify the control.
pnmh
Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.

Return Values

The return value is ignored with the exception of notification messages that specify otherwise.

See Also

NMHDR


WM_PAINT

This message is sent by an application when Windows or another application makes a request to paint a portion of an application's window. The message is sent when the UpdateWindow function is called, or by the DispatchMessage function when the application obtains a WM_PAINT message by using the GetMessage or PeekMessage function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_PAINT hdc = (HDC) wParam;

Parameters

hdc
Handle to the device context to draw in. If this parameter is NULL, use the default device context. This parameter is used by some common controls to enable drawing in a device context other than the default device context. Other windows can safely ignore this parameter.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function validates the update region. The function may also send the WM_NCPAINT message to the window procedure if the window frame must be painted and send the WM_ERASEBKGND message if the window background must be erased.

The system sends this message when there are no other messages in the application's message queue. DispatchMessage determines where to send the message; GetMessage determines which message to dispatch. GetMessage returns the WM_PAINT message when there are no other messages in the application's message queue, and DispatchMessage sends the message to the appropriate window procedure.

A window may receive internal paint messages as a result of calling RedrawWindow with the RDW_INTERNALPAINT flag set. In this case, the window may not have an update region. An application should call the GetUpdateRect function to determine whether the window has an update region. If GetUpdateRect returns zero, the application should not call the BeginPaint and EndPaint functions.

An application must check for any necessary internal painting by looking at its internal data structures for each WM_PAINT message, because a WM_PAINT message may have been caused by both a non-NULL update region and a call to RedrawWindow with the RDW_INTERNALPAINT flag set.

The system sends an internal WM_PAINT message only once. After an internal WM_PAINT message is returned from GetMessage or PeekMessage or is sent to a window by UpdateWindow, the system does not post or send further WM_PAINT messages until the window is invalidated or until RedrawWindow is called again with the RDW_INTERNALPAINT flag set.

For some common controls, the default WM_PAINT message processing checks the wParam parameter. If wParam is non-NULL, the control assumes that the value is an HDC and paints using that device context.

See Also

BeginPaint, DefWindowProc, DispatchMessage, EndPaint, GetMessage, GetUpdateRect, PeekMessage, UpdateWindow, WM_ERASEBKGND


WM_PALETTECHANGED

This message is sent by the OS to all top-level and overlapped windows after the window with the keyboard focus realizes its logical palette. This message enables windows that do not have the keyboard focus to realize their logical palettes and update their client areas.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_PALETTECHANGED hwndPalChg = (HWND) wParam;

Parameters

hwndPalChg
Handle to the window that caused the system palette to change.

Remarks

This message must be sent to all top-level and overlapped windows, including the one that changed the system palette. If any child windows use a color palette, this message must be passed on to them as well.

To avoid creating an infinite loop, a window that receives this message must not realize its palette, unless it determines that wParam does not contain its own window handle.

See Also

WM_QUERYNEWPALETTE


WM_PASTE

This message is sent by an application to an edit control or combo box to copy the current content of the clipboard to the edit control at the current caret position. Data is inserted only if the clipboard contains data in CF_UNICODETEXT format.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_PASTE wParam = 0; lParam = 0;

Return Values

None

Remarks

When sent to a combo box, the WM_PASTE message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_COPY, WM_CUT


WM_QUERYNEWPALETTE

This message informs a window that it is about to receive the keyboard focus, giving the window the opportunity to realize its logical palette when it receives the focus.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_QUERYNEWPALETTE

Return Values

TRUE indicates that the window realizes its logical palette. FALSE indicates otherwise.

See Also

WM_PALETTECHANGED


WM_QUIT

This message indicates a request to terminate an application and is generated when the application calls the PostQuitMessage function. It causes the GetMessage function to return zero.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_QUIT nExitCode = (int) wParam;

Parameters

nExitCode
Specifies the exit code given in the PostQuitMessage function.

Return Values

This message does not have a return value, because it causes the message loop to terminate before the message is sent to the application’s window procedure.

See Also

GetMessage, PostQuitMessage


WM_RASDIALEVENT

This message is sent by the OS to a window procedure when a change of state event occurs during a Remote Access Service (RAS) connection process, and a window has been specified to handle notifications of such events by using the notifier parameter of RasDial.

The two message parameters are equivalent to the Parameters of the same names that are used with RasDialFunc and RasDialFunc1 callback functions.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_RASDIALEVENT rasconnstate = (RASCONNSTATE) wParam; dwError = (DWORD) lParam;

Parameters

rasconnstate
Equivalent to the rasconnstate parameter of the RasDialFunc and RasDialFunc1 callback functions. Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial RAS connection process is about to enter.
dwError
Equivalent to the dwError parameter of the RasDialFunc and RasDialFunc1 callback functions. A nonzero value indicates the error that has occurred, or zero if no error has occurred.

RasDial sends this message with dwError set to zero upon entry to each connection state. If an error occurs within a state, the message is sent again for the state, this time with a nonzero dwError value.

Return Values

An application should return TRUE if it processes this message.

See Also

RasDial, RASCONNSTATE


WM_RENDERALLFORMATS

This message is sent to the clipboard owner before it is destroyed, if the clipboard owner has delayed rendering one or more clipboard formats. For the content of the clipboard to remain available to other applications, the clipboard owner must render data in all the formats it is capable of generating, and place the data on the clipboard by calling the SetClipboardData function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_RENDERALLFORMATS wParam = 0; lParam = 0;

Return Values

If an application processes this message, it should return zero.

Remarks

When responding to a WM_RENDERALLFORMATS message, the clipboard owner must call the OpenClipboard and EmptyClipboard functions before calling SetClipboardData.

When the application returns, the system removes any unrendered formats from the list of available clipboard formats. For information about delayed rendering, see SetClipboardData.

See Also

SetClipboardData, WM_RENDERFORMAT


WM_RENDERFORMAT

This message is sent to the clipboard owner if it has delayed rendering a specific clipboard format and if an application has requested data in that format. The clipboard owner must render data in the specified format and place it on the clipboard by calling the SetClipboardData function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_RENDERFORMAT uFormat = (UINT) wParam1;

Parameters

uFormat
Specifies the clipboard format to be rendered.

Return Values

If an application processes this message, it should return zero.

Remarks

When responding to a WM_RENDERFORMAT message, the clipboard owner must not open the clipboard before calling SetClipboardData.

See Also

SetClipboardData, WM_RENDERALLFORMATS


WM_SETCURSOR

This message is sent to a window if the mouse causes the cursor to move within a window and mouse input is not captured.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_SETCURSOR hwnd = (HWND) wParam;nHittest =
LOWORD (lParam);wMouseMsg = HIWORD (lParam);

Parameters

hwnd
Handle to the window that contains the cursor.
nHittest
Value of the low-order word of lParam. Specifies the hit-test code.
wMouseMsg
Value of the high-order word of lParam. Specifies the identifier of the mouse message.

Return Values

Default Action
The DefWindowProc function passes the WM_SETCURSOR message to a parent window before processing. If the parent window returns TRUE, further processing is halted. Passing the message to a window’s parent window gives the parent window control over the cursor’s setting in a child window. The DefWindowProc function also uses this message to set the cursor to an arrow if it is not in the client area, or to the registered class cursor if it is in the client area. If the low-order word of the lParam parameter is HTERROR and the high-order word of lParam specifies that one of the mouse buttons is pressed, DefWindowProc calls the MessageBeep function.

Remarks

The high-order word of lParam is zero when the window enters menu mode.


WM_SETFOCUS

This message is sent to a window after it has gained the keyboard focus.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SETFOCUS hwndLoseFocus = (HWND) wParam;

Parameters

hwndLoseFocus
Handle to the window that has lost the keyboard focus. This parameter can be NULL.

Return Values

An application should return zero if it processes this message.

Remarks

To display a caret, an application should call the appropriate caret functions when it receives the WM_SETFOCUS message.

See Also

SetFocus, WM_KILLFOCUS


WM_SETFONT

This message is sent by an application to specify the font that a control is to use when drawing text.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SETFONT wParam = (WPARAM) hfont; lParam = MAKELPARAM(fRedraw,0);

Parameters

hfont
Handle to the font. If this parameter is NULL, the control uses the default system font to draw text.
fRedraw
Specifies whether the control should be redrawn immediately upon setting the font. If set to TRUE, the control to redraw itself.

Return Values

None

Remarks

Dialog boxes do not support DS_SETFONT. Applications can set the font for their controls manually.

The WM_SETFONT message applies to all controls, not just those in dialog boxes.

The best time for the owner of a dialog box control to set the font of the control is when it receives the WM_INITDIALOG message. The application should call the DeleteObject function to delete the font when it is no longer needed; for example, after it destroys the control.

The size of the control does not change as a result of receiving this message. To avoid clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before it sets the font.

When a dialog box uses the DS_SETFONT style to set the text in its controls, the system sends the WM_SETFONT message to the dialog box procedure before it creates the controls. An application can create a dialog box that contains the DS_SETFONT style by calling any of the following functions:

  • CreateDialogIndirect
  • CreateDialogIndirectParam
  • DialogBoxIndirect
  • DialogBoxIndirectParam

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DeleteObject, DialogBoxIndirect, DialogBoxIndirectParam, WM_INITDIALOG, DLGTEMPLATE


WM_SETICON

This message is sent by an application to associate a new big or small icon with a window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SETICON wParam = (WPARAM)(BOOL) fType;
lParam = (LPARAM)(HICON) hicon;

Parameters

fType
Specifies the type of icon being set. It is one of the following values:
Value
Description
ICON_BIG | Sets the large icon for the window.
ICON_SMALL | Sets the small icon for the window.

hicon
Handle to the new large or small icon. If this parameter is NULL, the icon indicated by fType is removed.

Return Values

The return value is a handle to the previous large or small icon, depending on the value of fType. NULL indicates that the window previously had no icon of the type indicated by fType.

Default Action
The DefWindowProc function returns a handle to the previous large or small icon associated with the window, depending on the value of fType.

Remarks

Icons are stored per window class, not per window.

See Also

DefWindowProc, WM_GETICON


WM_SETREDRAW

This message is sent by an application to a window to enable changes in that window to be redrawn or to prevent changes in that window from being redrawn.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SETREDRAW wParam = (WPARAM) fRedraw; lParam = 0;

Parameters

fRedraw
Specifies the state of the redraw flag. If set to TRUE, the redraw flag is set. If set to FALSE, the flag is cleared.

Return Values

An application should return zero if it processes this message.

Remarks

The window manager provides no default processing for this message. However, certain controls do support this message, listbox, treeview and combo box.

This message sets or clears the redraw flag. If the redraw flag is cleared, the content of the given window is not updated after each change, and the window is not repainted until the redraw flag is set. For example, an application that must add several items to a list box can clear the redraw flag, add the items, and then set the redraw flag. Finally, the application can call the InvalidateRect function to cause the list box to be repainted.

See Also

InvalidateRect


WM_SETTEXT

This message is sent by an application to set the window text.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SETTEXT wParam = 0; lParam = (LPARAM)(LPCTSTR) lpsz;

Parameters

lpsz
Long pointer to a null-terminated string that contains the window text.

Return Values

The return value is TRUE if the text is set. It is FALSE (for an edit control), LB_ERRSPACE (for a list box), or CB_ERRSPACE (for a combo box) if insufficient space is available to set the text in the edit control. It is CB_ERR if this message is sent to a combo box without an edit control.

Default Action
The DefWindowProc function sets and displays the window text.

Remarks

For an edit control, the text is the contents of the edit control. For a combo box, the text is the contents of the edit-control portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title.

This message does not change the current selection in the list box of a combo box. An application should use the CB_SELECTSTRING message to select the item in a list box that matches the text in the edit control.

The DefWindowProc function returns zero for this message.

See Also

DefWindowProc, CB_SELECTSTRING, WM_GETTEXT


WM_SETTINGCHANGE

This message is sent by the OS to all top-level windows after a system-wide change has been made. The WM_SETTINGCHANGE message is the same as the older WM_WININICHANGE message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SETTINGCHANGE wParam = wFlag; lParam = (LPARAM)(LPCTSTR) pszSection;

Parameters

wFlag
When the system sends the message as a result of a SystemParametersInfo call, this parameter is a flag that indicates the system parameter that was changed. For a list of values, see the SystemParametersInfo function.

When an application sends the message, this parameter must be NULL.

pszMetrics
Pointer to a null-terminated string that indicates the area that contains the system parameter that was changed. For example, this string can be the name of a registry key or the name of a section in the Win.ini file.

This parameter is not particularly useful in determining which system parameter changed. For example, when the string is a registry name, it typically indicates only the leaf node in the registry, not the whole path. In addition, some applications send this message with lParam set to NULL. In general, when you receive this message, you should check and reload any system parameter settings used by your application.

Return Values

An application should return zero if it processes this message.

Remarks

The wParam parameter is set to NULL.

The lParam parameter is a constant, defined in Winuser.h, rather than a pointer to a string. For Windows CE versions 2.10 and later, lParam is not used.

At this time, the only value defined for lParam is INI_INTL, which indicates that a user has made a change to the regional settings in the control panel. This message is sent to all running applications. An application does not need to send this message.

On a Palm-size PC and for Windows CE versions 2.10 and later, WM_SETTINGCHANGE is sent to all top-level windows when changes are made to the following input panel elements:

  • Input method (IM)
  • Visibility
  • Docking
  • Size

A change in the input panel information sets wFlags to SPI_SETSIPINFO, whereas a change in the current IM sets the flag to SPI_SETCURRENTIM.. An application can change the input panel size in response to this message. However, for performance reasons, inactivated applications—for example, applications not currently in the foreground—should cache any input panel changes and delay updating the window until the application is reactivated. When notified of the change in the input panel state, an activated application may want to query the current input panel state before making the final adjustment. Do so by calling the SHSipInfo function on a Palm-size PC and SipGetInfo for other Windows CE–based devices.

On the Palm-size PC, when the user changes the application button mappings, a WM_SETTINGCHANGE message is broadcast to all top-level windows with wParam being set to SPI_APPBUTTONCHANGE and lParam to zero.

Calls to functions that change the WIN.INI file might be mapped to the registry instead. This mapping occurs when the WIN.INI file and the section being changed are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
Windows NT\CurrentVersion\IniFileMapping

The change in the storage location has no effect on the behavior of this message.

See Also

SendMessage


WM_SIZE

This message is sent to a window after its size has changed.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SIZE fwSizeType = wParam; nWidth = LOWORD(lParam); nHeight = HIWORD(lParam);

Parameters

fwSizeType
Specifies the type of resizing requested. It must be the following value:
Value
Description
SIZE_RESTORED The window has been resized, but neither the SIZE_MINIMIZED nor SIZE_MAXIMIZED value applies.

nWidth
Value of the low-order word of lParam. Specifies the new width of the client area.
nHeight
Value of the high-order word of lParam. Specifies the new height of the client area.

Return Values

An application should return zero if it processes this message.

Remarks

If the SetScrollPos or MoveWindow function is called for a child window as a result of the WM_SIZE message, the bRedraw parameter should be nonzero to cause the window to be repainted.

Although the width and height of a window are 32-bit values, the nWidth and nHeight Parameters of the WM_SIZE message contain only the low-order 16 bits.

See Also

MoveWindow, SetScrollPos


WM_STYLECHANGED

This message is sent to a window after the SetWindowLong function has changed one or more of the window’s styles.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_STYLECHANGED wStyleType = wParam; lpss = (LPSTYLESTRUCT) lParam;

Parameters

wStyleType
Specifies whether the window’s styles or extended styles have changed. It is a combination of the following values:
Value
Description
GWL_EXSTYLE | The window’s extended styles have changed.
GWL_STYLE | The window’s styles have changed.

lpss
Long pointer to a STYLESTRUCT structure that contains the new styles for the window. An application can examine the styles, but can not change them.

Return Values

An application should return zero if it processes this message.

See Also

SetWindowLong, STYLESTRUCT


WM_SYSCHAR

This message is posted to the window with the keyboard focus when a WM_SYSKEYDOWN message is translated by the TranslateMessage function. It specifies the character code of a system character key—that is, a character key that is pressed while the ALT key is down.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SYSCHAR chCharCode = (TCHAR) wParam; lKeyData = lParam;

Parameters

chCharCode
Specifies the character code of the window menu key.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a standard key message instead of a system character-key message. This enables accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; the PRINT SCRN key; the BREAK key; the NUMLOCK key; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateAccelerator, TranslateMessage, WM_SYSKEYDOWN


WM_SYSCOLORCHANGE

This message is sent to all top-level windows when a change is made to a system color setting.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_SYSCOLORCHANGE

Remarks

The system sends a WM_PAINT message to any window that is affected by a system color change.

Applications that have brushes using the existing system colors should delete those brushes and recreate them using the new system colors.

Top level windows that use common controls must forward the WM_SYSCOLORCHANGE message to the controls; otherwise, the controls will not be notified of the color change. This ensures that the colors used by your common controls are consistent with those used by other user interface objects. For example, a toolbar control uses the "3D Objects" color to draw its buttons. If the user changes the 3D Objects color but the WM_SYSCOLORCHANGE message is not forwarded to the toolbar, the toolbar buttons will remain in their original color while the color of other buttons in the system changes.

See Also

WM_PAINT


WM_SYSCOMMAND

This message is sent to a window when the user chooses a command from the window menu, formerly known as the system or control menu, or when the user chooses the maximize button or the minimize button.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

WM_SYSCOMMAND uCmdType = wParam; xPos = LOWORD(lParam); yPos = HIWORD(lParam);

Parameters

uCmdType
Specifies the type of system command requested. It is one of the following values.
Value
Description
SC_CLOSE | Closes the window.
SC_KEYMENU | Retrieves the window menu as a result of a keystroke.

xPos
Specifies the horizontal position of the cursor, in screen coordinates, if a window menu command is chosen with the mouse. Otherwise, the xPos parameter is not used.
yPos
Specifies the vertical position of the cursor, in screen coordinates, if a window menu command is chosen with the mouse. This parameter is –1 if the command is chosen using a system accelerator, or zero if using a mnemonic.

Return Values

An application should return zero if it processes this message.

Remarks

The DefWindowProc function carries out the window menu request for the predefined actions specified in the previous table.

In WM_SYSCOMMAND messages, the four low-order bits of the uCmdType parameter are used internally by the system. To obtain the correct result when testing the value of uCmdType, an application must combine the value 0xFFF0 with the uCmdType value by using the bitwise AND operator.

The menu items in a window menu can be modified by using the GetSystemMenu, AppendMenu, InsertMenu, InsertMenuItem, and SetMenuItem functions. Applications that modify the window menu must process WM_SYSCOMMAND messages.

An application can carry out any system command at any time by passing a WM_SYSCOMMAND message to DefWindowProc. Any WM_SYSCOMMAND messages not handled by the application must be passed to DefWindowProc. Any command values added by an application must be processed by the application and cannot be passed to DefWindowProc.

Accelerator keys that are defined to choose items from the window menu are translated into WM_SYSCOMMAND messages; all other accelerator keystrokes are translated into WM_COMMAND messages.

See Also

AppendMenu, DefWindowProc, GetSystemMenu, InsertMenu, WM_COMMAND


WM_SYSDEADCHAR

This message is sent to the window with the keyboard focus when a WM_SYSKEYDOWN message is translated by the TranslateMessage function. WM_SYSDEADCHAR specifies the character code of a system dead key—that is, a dead key that is pressed while holding down the ALT key.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SYSDEADCHAR chCharCode = (TCHAR) wParam;
lKeyData = lParam;

Parameters

chCharCode

Specifies the character code generated by the system dead key—that is, a dead key that is pressed while holding down the ALT key.

lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Remarks

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_DEADCHAR, WM_SYSKEYDOWN


WM_SYSKEYDOWN

This message is posted to the window with the keyboard focus when the user holds down the ALT key and then presses another key. It also occurs when no window currently has the keyboard focus; in this case, the WM_SYSKEYDOWN message is sent to the active window. The window that receives the message can distinguish between these two contexts by checking the context code in the lKeyData parameter.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SYSKEYDOWN nVirtKey = (int) wParam; lKeyData = lParam;

Parameters

nVirtKey
Specifies the virtual-key code of the key being pressed.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Default Action
The DefWindowProc function examines the given key and generates a WM_SYSCOMMAND message if the key is either TAB or ENTER.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a normal key message instead of a character-key message. This enables accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

Because of automatic repeat, more than one WM_SYSKEYDOWN message may occur before a WM_SYSKEYUP message is sent. The previous key state (bit 30) can be used to determine whether the WM_SYSKEYDOWN message indicates the first down transition or a repeated down transition.

For enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lParam parameter.

This message is also sent when the user presses the F10 key without the ALT key.

See Also

DefWindowProc, TranslateAccelerator, WM_SYSKEYUP


WM_SYSKEYUP

This message is posted to the window with the keyboard focus when the user releases a key that was pressed while the ALT key was held down. It also occurs when no window currently has the keyboard focus; in this case, the WM_SYSKEYUP message is sent to the active window. The window that receives the message can distinguish between these two contexts by checking the context code in the lKeyData parameter.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_SYSKEYUP nVirtKey = (int) wParam; lKeyData = lParam;

Parameters

nVirtKey
Specifies the virtual-key code of the key being released.
lKeyData
Specifies the repeat count, context code, previous key-state flag, and transition-state flag, as shown in the following table.
Value
Description
0–15 | Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
29 | Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30 | Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31 | Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Return Values

An application should return zero if it processes this message.

Default Action
The DefWindowProc function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a normal key message instead of a character-key message. This enables accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

For non-U.S. enhanced 102-key keyboards, the right ALT key is handled as a CTRL+ALT key. The following table shows the sequence of messages that result when the user presses and releases this key.

Message
Virtual-key code
WM_KEYDOWN | VK_CONTROL
WM_KEYDOWN | VK_MENU
WM_KEYUP | VK_CONTROL
WM_SYSKEYUP | VK_MENU

See Also

DefWindowProc, TranslateAccelerator, WM_SYSKEYDOWN


WM_UNDO

This message is sent by an application to an edit control to undo the last operation. When this message is sent to an edit control, the previously deleted text is restored or the previously added text is deleted.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_UNDO wParam = 0; lParam = 0;

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

WM_CLEAR, WM_COPY, WM_CUT, WM_PASTE


WM_USER

This message is used by applications to help define private messages.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_USER

Remarks

Windows CE does not support the RegisterWindowMessage function.

There are five ranges of message numbers:

Range
Description
0 through WM_USER –1 | Messages reserved for use by the system.
WM_USER through 0x7FFF | Integer messages for use by private window classes.
WM_APP through 0xBFFF | Messages available for use by applications.
0xC000 through 0xFFFF | String messages for use by applications.
Greater than 0xFFFF | Reserved by the system for future use.

Message numbers in the first range (0 through WM_USER –1) are defined by the system. Values in this range that are not explicitly defined are reserved for future use by the system.

Message numbers in the second range (WM_USER through 0x7FFF) can be defined and used by an application to send messages within a private window class. These values cannot be used to define messages that are meaningful throughout an application, because some predefined window classes already define values in this range. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use these values. Messages in this range should not be sent to other applications unless the applications have been designed to exchange messages and to attach the same meaning to the message numbers.

Message numbers in the third range (0x8000 through 0xBFFF) are available for application to use as private messages. Message in this range do not conflict with system messages.

Message numbers in the fourth range (0xC000 through 0xFFFF) are defined at run time when an application calls the RegisterWindowMessage function to retrieve a message number for a string. All applications that register the same string can use the associated message number for exchanging messages. The actual message number, however, is not a constant and cannot be assumed to be the same between different sessions.

Message numbers in the fifth range (greater than 0xFFFF) are reserved for future use by the system.


WM_VKEYTOITEM

This message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_KEYDOWN message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_VKEYTOITEM vkey = LOWORD(wParam); nCaretPos = HIWORD(wParam); hwndLB = lParam;

Parameters

vkey
Value of the low-order word of wParam. Specifies the virtual-key code of the key the user pressed.
nCaretPos
Value of the high-order word of wParam. Specifies the current position of the caret.
hwndLB
Handle to the list box

Return Values

The return value specifies the action that the application performed in response to the message. A return value of –2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. A return value of –1 indicates that the list box should perform the default action in response to the keystroke. A return value of 0 or greater specifies the index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the given item.

Default Action
The DefWindowProc function returns –1.

Remarks

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

See Also

DefWindowProc, WM_KEYDOWN


WM_VSCROLL

This message is sent to a window when a scroll event occurs in the window’s standard vertical scroll bar. This message is also sent to the owner of a vertical scroll bar control when a scroll event occurs in the control.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_VSCROLL nScrollCode = (int)LOWORD(wParam); nPos = (short int)HIWORD(wParam); hwndScrollBar = (HWND) lParam;

Parameters

nScrollCode
Value of the low-order word of wParam. Specifies a scroll bar value that indicates the user’s scrolling request. It is one of the following values:
Value
Description
SB_BOTTOM | Scrolls to the lower right
SB_ENDSCROLL | Ends scroll
SB_LINEDOWN | Scrolls one line down
SB_LINEUP | Scrolls one line up
SB_PAGEDOWN | Scrolls one page down
SB_PAGEUP | Scrolls one page up
SB_THUMBPOSITION | The user has dragged the scroll box (thumb) and released the mouse button. The nPos parameter indicates the position of the scroll box at the end of the drag operation.
SB_THUMBTRACK | The user is dragging the scroll box. This message is sent repeatedly until the user releases the mouse button. The nPos parameter indicates the position that the scroll box has been dragged to.
SB_TOP | Scrolls to the upper left

nPos
Value of the high-order word of wParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, nPos is not used.
hwndScrollBar
If the message is sent by a scroll bar, then hwndScrollBar is the handle to the scroll bar control. If the message is not sent by a scroll bar, hwndScrollBar is NULL.

Return Values

An application should return zero if it processes this message.

Remarks

The SB_THUMBTRACK notification message is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the content of the window, it must also reset the position of the scroll box by using the SetScrollPos function.

Note that the WM_VSCROLL message carries only 16 bits of scroll box position data. Thus, applications that rely solely on WM_VSCROLL (and WM_HSCROLL) for scroll position data have a practical maximum position value of 65,535.

However, because the SetScrollInfo, SetScrollPos, SetScrollRange, GetScrollInfo, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollInfo for a description of the technique.

See Also

WM_HSCROLL


WM_WINDOWPOSCHANGED

This message is sent to a window whose size, position, or place in the z-order has changed as a result of a call to the SetWindowPos function or another window-management function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_WINDOWPOSCHANGED lpwp = (LPWINDOWPOS) lParam;

Parameters

lpwp
Long pointer to a WINDOWPOS structure that contains information about the window’s new size and position.

Return Values

An application should return zero if it processes this message.

Default Action

The DefWindowProc function sends the WM_SIZE and WM_MOVE messages to the window.

Remarks

The WM_SIZE and WM_MOVE messages are not sent if an application handles the WM_WINDOWPOSCHANGED message without calling DefWindowProc. It is more efficient to perform any move or size change processing during the WM_WINDOWPOSCHANGED message without calling DefWindowProc.

See Also

DefWindowProc, SetWindowPos, WINDOWPOS, WM_MOVE, WM_SIZE


CommandBar_AddButtons

This macro adds one or more buttons to the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_AddButtons(HWND hwndCB, UINT uNumButtons, LPTBBUTTON lpButtons);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
uNumButtons
Unsigned integer that contains the number of buttons to add.
lpButtons
Long pointer to an array of TBBUTTON structures that contain information about the buttons to add. There must be the same number of elements in the array as specified in the uNumButtons parameter.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

CommandBar_Create, CommandBar_InsertButton, TBBUTTON


CommandBar_AddToolTips

This macro adds ToolTip strings to the command bar. A ToolTip control is a small pop-up window that displays a line of descriptive text giving the purpose of a button on the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_AddToolTips(HWND hwndCB, UINT uNumToolTips, LPTSTR lpToolTips);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
uNumToolTips
Unsigned integer that contains the number of ToolTip strings in the array specified in the lpToolTips parameter.
lpToolTips
Array of long pointers to strings that are displayed when the ToolTip control is active. The array must contain the same number of elements as specified in the uNumToolTips parameter.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Only command-bar buttons can have ToolTip strings; menus and combo boxes cannot.

CommandBar_AddtoolTips does not copy the array of ToolTip strings you pass to it. It uses the memory address you pass in the lpToolTips parameter. Do not release the memory allocated for the ToolTip string array until the program exits.

See Also

CommandBar_Create


CommandBar_Destroy

This macro destroys the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

void CommandBar_Destroy(HWND hwndCB);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.

Return Values

None.

Remarks

The CommandBar_Destroy function calls the DestroyWindow function to destroy the command bar. If the command bar’s parent window is being destroyed, it is not necessary to call CommandBar_Destroy.

See Also

CommandBar_Create, DestroyWindow


CommandBands_Height

This macro retrieves the height in pixels of a command bands control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

UINT CommandBands_Height (HWND hwndCmdBands);

Parameters

hwndCmdBand
Window handle to the command bands control. This handle is returned when the command bands control is created by the CommandBands_Create function.

Return Values

The height, in pixels, of the command bands control.

Remarks

Because the command bar occupies part of the client area of an application’s main window, you should call this macro to determine the actual size of the client area.


CommandBar_InsertButton

This macro inserts a button into the command bar.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_InsertButton(HWND hwndCB, int iButton, LPTBBUTTON lpButton);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.
iButton
Zero-based index of a button in the command bar. CommandBar_InsertButton inserts the new button to the left of this button.
lpButton
Long pointer to a TBBUTTON structure that contains information about the button to insert.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

CommandBar_AddButtons, CommandBar_Create, CommandBar_InsertComboBox, CommandBar_InsertMenubar, TBBUTTON


CommandBar_IsVisible

This macro ascertains whether or not the command bar is visible.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CommandBar_IsVisible(HWND hwndCB);

Parameters

hwndCB
Handle to the command bar’s window. This handle is returned by the CommandBar_Create function when the command bar is created.

Return Values

TRUE indicates that the command bar’s parent window has the WS_VISIBLE style. FALSE indicates that the command bar is hidden.

Remarks

Because this macro only determines whether the window has the WS_VISIBLE style, it may return TRUE even if the window is obscured by other windows.

See Also

CommandBar_Create, CommandBar_Show


DateTime_GetMonthCal

This macro retrieves the handle to a date and time picker’s (DTP) child month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_GETMONTHCAL

Syntax

HWND DateTime_GetMonthCal( HWND hwndDP );

Parameters

hwndDP
Handle to a DTP control.

Return Values

Returns the handle to a DTP control’s child month calendar control.

Remarks

DTP controls create a child month calendar control when the user clicks the drop-down arrow. When the month calendar is no longer needed, it is destroyed. Therefore, your application must not rely on a static handle to the DTP’s child month calendar.


DateTime_GetMonthCalColor

This macro retrieves the color for a specified portion of the month calendar within a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_GETMCCOLOR

Syntax

COLORREF DateTime_GetMonthCalColor( HWND hwndDP, int iColor );

Parameters

hwndDP
Handle to a DTP control.
iColor
INT value that specifies which month calendar color to retrieve. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Retrieves the background color displayed between months.
MCSC_MONTHBK | Retrieves the background color displayed within the month.
MCSC_TEXT | Retrieves the color used to display text within a month.
MCSC_TITLEBK | Retrieves the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Retrieves the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Retrieves the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. Otherwise, the macro returns –1.


DateTime_GetMonthCalFont

This macro retrieves the font that the date and time picker (DTP) control’s child month calendar control is currently using.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_GETMCFONT

Syntax

HFONT DateTime_GetMonthCalFont(HWND hwndDP)

Parameters

hwndDP
Handle to a DTP control.

Return Values

Returns an HFONT value that is the handle to the current font.


DateTime_GetRange

This macro retrieves the current minimum and maximum allowable system times for a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_GETRANGE

Syntax

DWORD DateTime_GetRange(HWND hwndDT,
LPSYSTEMTIME lpSysTimeArray);

Parameters

hwndDT
Handle to a DTP control.
lpSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures.

Return Values

Returns a DWORD value that is a combination of GDTR_MIN or GDTR_MAX. The first element of the SYSTEMTIME array contains the minimum allowable time. The second element of the SYSTEMTIME array contains the maximum allowable time.


DateTime_GetSystemtime

This macro retrieves the currently selected time from a date and time picker (DTP) control and places it in a specified SYSTEMTIME structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_GETSYSTEMTIME

Syntax

DWORD DateTime_GetSystemtime(HWND hwndDP,
LPSYSTEMTIME lpSysTime);

Parameters

hwndDP
Handle to a DTP control.
lpSysTime
Long pointer to the SYSTEMTIME structure that receives the system time information.

Return Values

Returns a DWORD value that equals GDT_VALID if the time information was successfully placed in the specified structure; or the message can return GDT_NONE if the control was set to the DTS_SHOWNONE style and the control check box was not selected.


DateTime_SetFormat

This macro sets the display of a date and time picker (DTP) control based on a specified format string.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_SETFORMAT

Syntax

BOOL DateTime_SetFormat(HWND hwndDT, LPCTSTR lpszFormat );

Parameters

hwndDT
Handle to a DTP control.
lpszFormat
Long pointer to a null-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style. The format string is a combination of string fragments. It is interpreted literally, with the exception of the following string fragments.
Value
Description
“d” | The one- or two-digit day.
“dd” | The two-digit day. Single-digit day values are preceded by a zero.
“ddd” | The three-character weekday abbreviation.
“dddd” | The full weekday name.
“h” | The one- or two-digit hour in 12-hour format.
“hh” | The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
“H” | The one- or two-digit hour in 24-hour format.
“HH” | The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
“m” | The one- or two-digit minute.
“mm” | The two-digit minute. Single-digit values are preceded by a zero.
“M” | The one- or two-digit month number.
“MM” | The two-digit month number. Single-digit values are preceded by a zero.
“MMM” | The three-character month abbreviation.
“MMMM” | The full month name.
“t” | The one-letter AM/PM abbreviation (that is, “AM” is displayed as “A”).
“tt” | The two-letter AM/PM abbreviation (that is, “AM” is displayed as “AM”).
“X” | A callback field. The control still uses the other valid format characters, and queries the owner to fill in the “X” portion. Therefore, the owner must be prepared to handle the DTN_WMKEYDOWN, DTN_FORMAT, and DTN_FORMATQUERY notification messages. Multiple “X” characters can be used to signify unique callback fields.
“y” | The year is displayed as the last two digits, but with no leading zero for years less than 10.
“yy” | The last two digits of the year (that is, 1998 would be displayed as “98”).
“yyy” | The full year (that is, 1998 would be displayed as “1998”).

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

It is acceptable to include extra characters within the format string to produce a richer display. However, any nonformat characters must be enclosed within single quotes. For example, the format string “ ‘Today is: ‘hh’:’m’:’s ddddMMMdd’, ‘yyy” would produce output like “Today is: 04:22:31 Tuesday Mar 23, 1996”.

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L”yyyy” and L”yy” (the ‘L’ indicates a Unicode (16-bit characters) string). If L”y” is passed in, the function assumes L”yy”. If L”yyy” is passed in, the function assumes L”yyyy”. If more than 4 date (“dddd”) or 4 month (L”MMMM”) pictures are passed in, then the function defaults to L”dddd” or L”MMMM”.

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as “May ‘93”, the format string would be: L”MMMM ‘‘‘‘yy” The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

Note A DTP control tracks locale changes when it is using the default format string. If you set a custom format string, it will not be updated in response to locale changes.


DateTime_SetMonthCalColor

This macro sets the color for a specified portion of the month calendar within a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_SETMCCOLOR

Syntax

COLORREF DateTime_SetMonthCalColor(HWND hwndDP, int iColor, COLORREF cl );

Parameters

hwndDP
Handle to a DTP control.
iColor
INT value that specifies which month calendar color to set. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Sets the background color displayed between months.
MCSC_MONTHBK | Sets the background color displayed within the month.
MCSC_TEXT | Sets the color used to display text within a month.
MCSC_TITLEBK | Sets the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Sets the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Sets the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

clr
COLORREF value that represents the color that will be set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, this message returns –1.


DateTime_SetMonthCalFont

This macro sets the font to be used by the date and time picker (DTP) control’s child month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_SETMCFONT

Syntax

void DateTime_SetMonthCalFont(HWND hwndDP, HFONT hFont, LPARAM MAKELONG(hRedraw, 0));

Parameters

hwndDP
Handle to a DTP control.
hFont
Handle to the font that will be set.
fRedraw
Value that specifies whether the control should be redrawn immediately upon setting the font. If set to TRUE, the control redraws itself.


DateTime_SetRange

This macro sets the minimum and maximum allowable system times for a date and time picker (DTP) control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_SETRANGE

Syntax

BOOL DateTime_SetRange(HWND hwndDT, DWORD flags, LPSYSTEMTIME lpSysTimeArray);

Parameters

hwndDT
Handle to a DTP control.
flags
Value that specifies which range values are valid. It can be a combination of the following values:
Value
Description
GDTR_MIN | The first element in the SYSTEMTIME structure array is valid and will be used to set the minimum allowable system time.
GDTR_MAX | The second element in the SYSTEMTIME structure array is valid and will be used to set the maximum allowable system time.

lpSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures. The first element of the SYSTEMTIME array contains the minimum allowable time. The second element of the SYSTEMTIME array contains the maximum allowable time. It is not necessary to fill an array element that is not specified in the flags parameter.

Return Values

Nonzero indicates success. Zero indicates otherwise.


DateTime_SetSystemtime

This macro sets a date and time picker (DTP) control to a specified date and time.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | DTM_SETSYSTEMTIME

Syntax

BOOL DateTime_SetSystemtime(HWND hwndDT, DWORD flag, LPSYSTEMTIME lpSysTime);

Parameters

hwndDT
Handle to a DTP control.
flag
Value that specifies the action that should be performed. It is one of the following values:
Value
Description
GDT_VALID | Set the DTP control according to the data within the SYSTEMTIME structure pointed to by lpSysTime.
GDT_NONE | Set the DTP control to “no date” and clear its check box. lpSysTime is ignored when this flag is specified. This flag applies only to DTP controls that are set to the DTS_SHOWNONE style.

lpSysTime
Long pointer to a SYSTEMTIME structure that contains the system time information by which to set the DTP control.

Return Values

Nonzero indicates success. Zero indicates otherwise.


Header_CreateDragImage

This macro creates a transparent version of an item image within an existing header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_CREATEDRAGIMAGE

Syntax

HIMAGELIST Header_CreateDragImage(HWND hwndHD, int iIndex);

Parameters

hwndHD
Handle to a header control.
iIndex
Zero-based index of the item within the header control. The image assigned to this item is used as the basis for the transparent image.

Return Values

Returns a handle to an image list that contains the new image as its only element.


Header_DeleteItem

This macro deletes an item from a header control. You can use this macro or send the HDM_DELETEITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | HDM_DELETEITEM

Syntax

BOOL Header_DeleteItem( hwndHD, index );

Parameters

hwndHD
Handle to the header control.
index
Index of the item to delete.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The Header_DeleteItem macro is defined as follows:

#define Header_DeleteItem(hwndHD, index)        \
    (BOOL)SendMessage((hwndHD), HDM_DELETEITEM, (WPARAM)(int)(index), 0L)


Header_GetImageList

This macro retrieves the handle to the image list that has been set for an existing header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_GETIMAGELIST

Syntax

HIMAGELIST Header_GetImageList(HWND hwndHD);

Parameters

hwndHD
Handle to a header control.

Return Values

Returns the handle to the image list that is set for the header control.


Header_GetItem

This macro retrieves information about an item in a header control. You can use this macro or send the HDM_GETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | HDM_GETITEM

Syntax

BOOL Header_GetItem( hwndHD, index, phdi );

Parameters

hwndHD
Handle to the header control.
index
Index of the item for which information is to be retrieved.
phdi
Pointer to an HDITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The Header_GetItem macro is defined as follows:

#define Header_GetItem(hwndHD, index, phdi)        \
    (BOOL)SendMessage((hwndHD), HDM_GETITEM,        \
    (WPARAM)(int)(index), (LPARAM)(LPHDITEM)(phdi))


Header_GetItemCount

This macro retrieves a count of the items in a header control. You can use this macro or send the HDM_GETITEMCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | HDM_GETITEMCOUNT

Syntax

int Header_GetItemCount( hwndHD );

Parameters

hwndHD
Handle to the header control.

Return Values

The number of items indicates success. –1 indicates failure.

Remarks

The Header_GetItemCount macro is defined as follows:

#define Header_GetItemCount(hwndHD)        \
        (int)SendMessage((hwndHD), HDM_GETITEMCOUNT, 0, 0L)


Header_GetItemRect

This macro retrieves the bounding rectangle for a specified item in a header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_GETITEMRECT

Syntax

BOOL Header_GetItemRect(HWND hwndHD, int iIndex,
LPRECT lpItemRect);

Parameters

hwndHD
Handle to a header control.
iIndex
Zero-based index of the header control item for which to retrieve the bounding rectangle.
lpItemRect
Long pointer to a RECT structure that receives the bounding rectangle information.

Return Values

Nonzero indicates success. Zero indicates otherwise.


Header_GetOrderArray

This macro retrieves the current left-to-right order of items in a header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_GETORDERARRAY

Syntax

BOOL Header_GetOrderArray(HWND hwndHD, int iSize, int *lpiArray);

Parameters

hwndHD
Handle to a header control.
iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Long pointer to a buffer that receives the index values of the items in the header. The buffer should be big enough to hold the total number of items * sizeof(int). For example, the following code fragment will reserve enough memory to hold the index values.

Return Values

Returns nonzero if successful, and the buffer at lpiArray receives the item number of each item in the header control, in the order in which they appear from left to right. The macro returns zero otherwise.

Example

int iItems,
    *lpiArray ;
// Get memory for buffer
if((iItems = SendMessage(hwndHD, HDM_GETITEMCOUNT, 0,0))!=-1)
    if(!(lpiArray = calloc(iItems,sizeof(int))))
MessageBox(hwnd, "Out of memory.","Error", MB_OK);


Header_InsertItem

This macro inserts a new item into a header control. You can use this macro or send the HDM_INSERTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | HDM_INSERTITEM

Syntax

int Header_InsertItem( hwndHD, index, phdi );

Parameters

hwndHD
Handle to the header control.
index
Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.
phdi
Pointer to an HDITEM structure that contains information about the new item.

Return Values

The index of the new item indicates success. –1 indicates failure.

Remarks

The Header_InsertItem macro is defined as follows:

#define Header_InsertItem(hwndHD, index, phdi)    \
    (int)SendMessage((hwndHD), HDM_INSERTITEM, (WPARAM)(int)(index), \
    (LPARAM)(const LPHDITEM)(phdi))


Header_Layout

This macro retrieves the size and position of a header control within a specified rectangle. This macro is used to determine the appropriate dimensions for a new header control that is to occupy the specified rectangle. You can use this macro or send the HDM_LAYOUT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | HDM_LAYOUT

Syntax

BOOL Header_Layout( hwndHD, playout );

Parameters

hwndHD
Handle to the header control.
playout
Pointer to an HDLAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The Header_Layout macro is defined as follows:

#define Header_Layout(hwndHD, playout) \
    (BOOL)SendMessage((hwndHD), HDM_LAYOUT, 0, \
    (LPARAM)(PLHDLAYOUT)(playout))


Header_OrderToIndex

This macro retrieves an index value for an item based on its order in the header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_ORDERTOINDEX

Syntax

int Header_OrderToIndex(HWND hwndHD, int iOrder);

Parameters

hwndHD
Handle to a header control.
iOrder
Order that the item appears within the header control, from left to right. The index value of the item in the far left column would be 0, the next item to the right would be 1, and so on.

Return Values

Returns an INT that specifies the index of the item. If iOrder is invalid, (that is, negative or too large) the return value equals iOrder.


Header_SetHotDivider

This macro changes the color of a divider between header items to indicate the destination of an external drag-and-drop operation.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_SETHOTDIVIDER

Syntax

int Header_SetHotDivider(HWND hwndHD, BOOL flag,
DWORD dwInputValue);

Parameters

hwndHD
Handle to a header control.
flag
Boolean value that specifies how dwInputValue is to be interpreted.
dwInputValue
Value held here is interpreted depending on the value of flag.

If flag is TRUE, then dwInputValue represents the x- and y- client coordinates of the pointer. The x-coordinate is in the low-order word, and the y-coordinate is in the high-order word. Upon receiving the message, the header control highlights the appropriate divider based on the dwInputValue coordinates.

If flag is FALSE, then dwInputValue represents the integer index of the divider that will be highlighted.

Return Values

Returns the index of the divider that the control highlighted.

Remarks

A header control set to the HDS_DRAGDROP style produces this effect automatically. This message is intended to be used when the owner of the control handles drag-and-drop operations manually.


Header_SetImageList

This macro assigns an image list to an existing header control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_SETIMAGELIST

Syntax

HIMAGELIST Header_SetImageList(HWND hwndHD,
HIMAGELIST himl);

Parameters

hwndHD
Handle to a header control.
himl
Handle to an image list.

Return Values

Returns the handle to the image list previously assigned to the header control, or NULL if there is no previous image list.


Header_SetItem

This macro sets the attributes of the specified item in a header control. You can use this macro or send the HDM_SETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later (updated in 2.0)
Related message: | HDM_SETITEM

Syntax

BOOL Header_SetItem( hwndHD, index, phdi );

Parameters

hwndHD
Handle to a header control.
iIndex
Current index of the item for which attributes are to be changed.
phdItem
Pointer to an HDITEM structure that contains item information. When this message is sent, the mask member of the structure must be set to indicate which attributes are being set.

Return Values

Nonzero indicates success. Zero indicates failure.

Remarks

In Windows CE version 2.0, this macro supports item order and image list information. By using the iImage and iOrder members of the new HDITEM structure you pass in the phdi parameter, you can control the order in which items are displayed and specify images to appear with items.

The HDITEM structure that supports this macro supports item order and image list information. By using these members, you can control the order in which items are displayed and specify images to appear with items.

See Also

HDITEM


Header_SetOrderArray

This macro sets the left-to-right order of header items.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | HDM_SETORDERARRAY

Syntax

BOOL Header_SetOrderArray(HWND hwndHD, int iSize, int *lpiArray);

Parameters

hwndHD
Handle to a header control.
iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Long pointer to an array that specifies the order in which items should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays item 2, item 0, and item 1 in that order.

Return Values

Nonzero indicates success. Zero indicates otherwise.


ImageList_AddIcon

This macro adds an icon to an image list. ImageList_AddIcon calls the ImageList_ReplaceIcon function.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

int WINAPI ImageList_AddIcon( HIMAGELIST himl, HICON hicon );

Parameters

himl
Handle to the image list. If this parameter identifies a masked image list, the macro copies both the image and mask bitmaps of the icon or cursor. If this parameter identifies a nonmasked image list, the macro copies only the image bitmap.
hicon
Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Values

The index of the new image indicates success. –1 indicates failure.

Remarks

In Windows CE, you can only use this macro with icons, not cursors.

Because the system does not save hicon, you can destroy it after the macro returns if the icon was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

The ImageList_AddIcon macro is defined as follows:

#define ImageList_AddIcon(himl, hicon) ImageList_ReplaceIcon(himl, –1, hicon)

See Also

ImageList_Create_wcesdk_win32_ImageList_Create, LoadIcon_wcesdk_Win32_LoadIcon


ImageList_ExtractIcon

This macro calls the ImageList_GetIcon function to create an icon based on an image and mask in an image list.

At a Glance

Header file: | Commctrl.h
Versions: | 1.0 and later

Syntax

HICON WINAPI ImageList_ExtractIcon(HINSTANCE hi, HIMAGELIST himl, int i);

Parameters

hi
[in] Not used; set to 0.
himl
[in] Handle to the image list.
i
[in] Index of the image.

Return Values

The handle of the icon indicates success. NULL indicates failure.

Remarks

In Windows CE, you can only use the ImageList_ExtractIcon macro to create an icon, not a cursor.

ImageList_ExtractIcon is not supported for emulation.

See Also

ImageList_GetIcon


ImageList_LoadBitmap

This macro calls the ImageList_LoadImage function to create an image list from the specified bitmap resource.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HIMAGELIST WINAPI ImageList_LoadBitmap(HINSTANCE hi,
LPCSTR lpbmp, int cx, int cGrow, COLORREF crMask);

Parameters

hi
[in] Handle to the instance that contains the bitmap resource. This parameter is NULL if you are loading an OEM bitmap.
lpbmp
[in] Long pointer to the image to load.

If the hi parameter is non-NULL, lpbmp is the address of a null-terminated string that contains the name of the image resource in the hi module.

If hi is NULL, the low-order word of this parameter must be the identifier of an OEM bitmap to load. To create this value, use the MAKEINTRESOURCE macro with one of the OEM bitmap identifiers defined in WINUSER.H. These identifiers have the OBM_ prefix.

cx
[in] Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified bitmap.
cGrow
[in] Number of images by which the image list can grow when the system needs to make room for new images. This parameter represents the number of new images that the resized image list can contain.
crMask
[in] Color used to generate a mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to 1. If this parameter is the CLR_NONE value, no mask is generated.

Return Values

The handle to the image list indicates success. NULL indicates failure.

Remarks

This macro is not supported for emulation.

See Also

ImageList_LoadImage


ImageList_RemoveAll

This function removes an image from an image list. ImageList_RemoveAll is a function that calls the ImageList_Remove function.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ImageList_RemoveAll(himl);

Parameters

himl
[in] Handle to the image list, and the index of the image to remove.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

ImageList_Remove


INDEXTOOVERLAYMASK

This macro prepares the index of an overlay mask so that the ImageList_Draw or ImageList_DrawEx function can use it.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UINT INDEXTOOVERLAYMASK( UINT iOverlay );

Parameters

iOverlay
Index of an overlay mask.

Remarks

The INDEXTOOVERLAYMASK macro is defined as follows:

#define INDEXTOOVERLAYMASK(i) ((i) << 8)

See Also

ImageList_Draw, ImageList_DrawEx, ImageList_SetOverlayImage


INDEXTOSTATEIMAGEMASK

This macro prepares the index of a state image so that a tree-view control or list-view control can use the index to retrieve the state image for an item.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

UINT INDEXTOSTATEIMAGEMASK( UINT i );

Parameters

i
Index of a state image.

Remarks

The INDEXTOSTATEIMAGEMASK macro is defined as follows:

#define INDEXTOSTATEIMAGEMASK(i) ((i) << 12)


ListView_ApproximateViewRect

This macro calculates the approximate width and height required to display a specified number of items.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_APPROXIMATEVIEWRECT

Syntax

DWORD ListView_ApproximateViewRect(HWND hwndLV, int cx, int cy,
int iCount);

Parameters

hwndLV
Handle to a list view control.
iCount
Number of items to be displayed in the control. If this parameter is –1, the message uses the total number of items in the control.
cx and cy
Proposed dimensions of the control, in pixels. Either parameter can be –1 to allow the message to use the current width or height value.

Return Values

Returns a DWORD value that holds the approximate width and height needed to display the items, in pixels.


ListView_Arrange

This macro arranges items in icon view. You can use this macro or send the LVM_ARRANGE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_ARRANGE

Syntax

BOOL ListView_Arrange( HWND hwnd, UINT code );

Parameters

hwnd
Handle to the list view control.
code
Specifies alignment. It is one of the following values:
Value
Description
LVA_ALIGNLEFT | Aligns items along the left edge of the window.
LVA_ALIGNTOP | Aligns items along the top edge of the window.
LVA_DEFAULT | Aligns items according to the list view control’s current alignment styles (the default value).
LVA_SNAPTOGRID | Snaps all icons to the nearest grid position.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_CreateDragImage

This macro creates a drag image list for the specified item. You can use this macro or send the LVM_CREATEDRAGIMAGE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_CREATEDRAGIMAGE

Syntax

HIMAGELIST ListView_CreateDragImage( HWND hwnd, int iItem,
LPPOINT lpptUpLeft );

Parameters

hwnd
Handle to the list view control.
iItem
Index of the item.
lpptUpLeft
Long pointer to a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Values

The handle to the drag image list indicates success. NULL indicates failure.


ListView_DeleteAllItems

This macro removes all items from a list view control. You can use this macro or send the LVM_DELETEALLITEMS message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_DELETEALLITEMS

Syntax

BOOL ListView_DeleteAllItems( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When a list view control receives the LVM_DELETEALLITEMS message, it sends the LVN_DELETEALLITEMS notification message to its parent window.


ListView_DeleteColumn

This macro removes a column from a list view control. You can use this macro or send the LVM_DELETECOLUMN message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_DELETECOLUMN

Syntax

BOOL ListView_DeleteColumn( HWND hwnd, int iCol );

Parameters

hwnd
Handle to the list view control.
iCol
Index of the column to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_DeleteItem

This macro removes an item from a list view control. You can use this macro or send the LVM_DELETEITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_DELETEITEM

Syntax

BOOL ListView_DeleteItem( HWND hwnd, int iItem );

Parameters

hwnd
Handle to the list view control.
iItem
Index of the list view item to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_EditLabel

This macro begins in-place editing of the specified list view item’s text. The message implicitly selects and focuses the specified item. You can use this macro or send the LVM_EDITLABEL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_EDITLABEL

Syntax

HWND ListView_EditLabel( HWND hwnd, int iItem );

Parameters

hwnd
Handle to the list view control.
iItem
Index of the list view item. To cancel editing, set iItem to –1.

Return Values

The handle to the edit control that is used to edit the item text indicates success. NULL indicates failure.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

WM_CANCELMODE


ListView_EnsureVisible

This macro ensures that a list view item is either entirely or partially visible, scrolling the list view control if necessary. You can use this macro or send the LVM_ENSUREVISIBLE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_ENSUREVISIBLE

Syntax

BOOL ListView_EnsureVisible( HWND hwnd, int i, BOOL fPartialOK );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item.
fPartialOK
Boolean value that specifies whether the item must be entirely visible. If set to TRUE, no scrolling occurs if the item is at least partially visible.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_FindItem

This macro searches for a list view item with the specified characteristics. You can use this macro or send the LVM_FINDITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_FINDITEM

Syntax

int ListView_FindItem( HWND hwnd, int iStart,
const LV_FINDINFO FAR* plvfi );

Parameters

hwnd
Handle to the list view control.
iStart
Index of the item after which to begin the search, or –1 to start from the beginning.
plvfi
Pointer to an LVFINDINFO structure that contains information about what to search for.

Return Values

The index of the item indicates success. –1 indicates failure.


ListView_GetBkColor

This macro retrieves the background color of a list view control. You can use this macro or send the LVM_GETBKCOLOR message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETBKCOLOR

Syntax

COLORREF ListView_GetBkColor( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

Returns the background color of the list view control.


ListView_GetCallbackMask

This macro retrieves the callback mask for a list view control. You can use this macro or send the LVM_GETCALLBACKMASK message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETCALLBACKMASK

Syntax

UINT ListView_GetCallbackMask( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

Returns the callback mask.

See Also

LVM_SETCALLBACKMASK


ListView_GetCheckState

This macro determines if an item in a list view control is selected. This should be used only for list view controls that have the LVS_EX_CHECKBOXES style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ListView_GetCheckState(HWND hwndLV, UINT iIndex);

Parameters

hwndLV
Handle to a list view control.
iIndex
Index of the item for which to retrieve the check state.

Return Values

Returns nonzero if the specified item is selected, or zero otherwise. If this macro is applied to a list view control that does not have check boxes enabled, the return value is not reliable.


ListView_GetColumn

This macro retrieves the attributes of a list view control’s column. You can use this macro or send the LVM_GETCOLUMN message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETCOLUMN

Syntax

BOOL ListView_GetColumn( HWND hwnd, int iCol,
LV_COLUMN FAR* pcol );

Parameters

hwnd
Handle to the list view control.
iCol
Index of the column.
pcol
Pointer to an LVCOLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.

If the mask member specifies the LVCF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_GetColumnOrderArray

This macro retrieves the current left-to-right order of columns in a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_GETCOLUMNORDERARRAY

Syntax

BOOL ListView_GetColumnOrderArray(HWND hwndLV, int iCount,
int *lpiArray);

Parameters

hwndLV
Handle to a list view control.
iCount
Number of columns in the list view control.
lpiArray
Long pointer to a buffer that will receive the index values of the columns in the list view control. The buffer must be large enough to hold the total number of columns * sizeof(int).

Return Values

Returns nonzero and the buffer at lpiArray receives the column index of each column in the control, in the order they appear from left to right if successful. Otherwise, the return value is zero.


ListView_GetColumnWidth

This macro retrieves the width of a column in report or list view. You can use this macro or send the LVM_GETCOLUMNWIDTH message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETCOLUMNWIDTH

Syntax

int ListView_GetColumnWidth( HWND hwnd, int iCol );

Parameters

hwnd
Handle to the list view control.
iCol
Index of the column. This parameter is ignored in list view.

Return Values

The column width indicates success. Zero indicates failure. If this macro is used on a list view control with the LVS_REPORT style and the specified column does not exist, the return value is undefined.


ListView_GetCountPerPage

This macro calculates the number of items that can fit vertically in the visible area of a list view control when in list or report view. Only fully visible items are counted. You can use this macro or send the LVM_GETCOUNTPERPAGE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETCOUNTPERPAGE

Syntax

int ListView_GetCountPerPage( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

The number of fully visible items indicates success. The total number of items in the list view control indicates that the current view is icon or small icon view.


ListView_GetEditControl

This macro retrieves the handle to the edit control being used to edit a list view item’s text. You can use this macro or send the LVM_GETEDITCONTROL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETEDITCONTROL

Syntax

HWND ListView_GetEditControl( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Remarks

If no label is being edited, the return value is NULL. The edit control is not created until after the LVN_BEGINLABELEDIT notification message is sent.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list view control a WM_CANCELMODE message.

The list view item being edited is the currently focused item—that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

Return Values

The handle to the edit control indicates success. NULL indicates failure.


ListView_GetExtendedListViewStyle

This macro retrieves the extended styles that are currently in use for a specified list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_GETEXTENDEDLISTVIEWSTYLE

Syntax

DWORD ListView_GetExtendedListViewStyle(HWND hwndLV);

Parameters

hwndLV
Handle to a list view control.

Return Values

Returns a DWORD value that represents the styles currently in use for a specified list view control. This can be a combination of extended styles.


ListView_GetHeader

This macro retrieves the handle to the header control used by a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_GETHEADER

Syntax

HWND ListView_GetHeader(hwndLV);

Parameters

hwndLV
Handle to a list view control.

Return Values

Returns the handle to the header control.


ListView_GetImageList

This macro retrieves the handle to an image list used for drawing list view items. You can use this macro or send the LVM_GETIMAGELIST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETIMAGELIST

Syntax

HIMAGELIST ListView_GetImageList( HWND hwnd, int iImageList );

Parameters

hwnd
Handle to the list view control.
iImageList
Image list to retrieve. It is one of the following values:
Value
Description
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.

Return Values

The handle to the specified image list indicates success. NULL indicates failure.

Remarks

Windows CE supports a new value for the iImageList parameter. The LVSIL_HEADER constant specifies that the image list to be retrieved is the image list displayed in the list view’s header control in report view.


ListView_GetISearchString

This macro retrieves the incremental search string of a list-view control. You can use this macro or send the LVM_GETISEARCHSTRING message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETISEARCHSTRING

Syntax

BOOL ListView_GetISearchString( HWND hwnd, LPSTR lpsz );

Parameters

hwnd
Handle to the list view control.
lpsz
Long pointer to a buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string, or zero if the list view control is not in incremental search mode.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A time-out period is associated with each character that the user types. If the time-out period elapses before the user types another character, the incremental search string is reset.


ListView_GetItem

This macro retrieves some or all of a list view item’s attributes. You can use this macro or send the LVM_GETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEM

Syntax

BOOL ListView_GetItem( HWND hwnd, LV_ITEM FAR* pitem );

Parameters

hwnd
Handle to the list view control.
pitem
Pointer to an LVITEM structure that specifies the information to retrieve and receives information about the list view item.

When the LVM_GETITEM message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LVITEM structure.

If the mask member specifies the LVIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_GetItemCount

This macro retrieves the number of items in a list view control. You can use this macro or send the LVM_GETITEMCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEMCOUNT

Syntax

int ListView_GetItemCount( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

Returns the number of items.


ListView_GetItemPosition

This macro retrieves the position of a list view item. You can use this macro or send the LVM_GETITEMPOSITION message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEMPOSITION

Syntax

BOOL ListView_GetItemPosition( HWND hwnd, int i, POINT FAR* ppt );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item.
ppt
Pointer to a POINT structure that receives the position of the item’s upper-left corner, in view coordinates.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_GetItemRect

This macro retrieves the bounding rectangle for all or part of an item in the current view. You can use this macro or send the LVM_GETITEMRECT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEMRECT

Syntax

BOOL ListView_GetItemRect( HWND hwnd, int i, RECT FAR* prc, int code );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item.
prc
Pointer to a RECT structure that receives the bounding rectangle. When the LVM_GETITEMRECT message is sent, the left member of this structure contains the value of the code parameter.
code
Portion of the list view item for which to retrieve the bounding rectangle. It is one of the following values:
Value
Description
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL | Returns the bounding rectangle of the item text.
LVIR_SELECTBOUNDS | Returns the union of the LVIR_ICON and LVIR_LABEL rectangles, but excludes columns in details view.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_GetItemSpacing

This macro determines the spacing between items in a list view control. You can use this macro or send the LVM_GETITEMSPACING message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEMSPACING

Syntax

DWORD ListView_GetItemSpacing( HWND hwnd, BOOL fSmall );

Parameters

hwnd
Handle to the list view control.
fSmall
Boolean value that specifies the view for which to retrieve the item spacing. Set to TRUE for small icon view, or to FALSE for icon view.

Return Values

Returns the amount of spacing between items.


ListView_GetItemState

This macro retrieves the state of a list view item. You can use this macro or send the LVM_GETITEMSTATE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEMSTATE

Syntax

UINT WINAPI ListView_GetItemState( HWND hwnd, int i, UINT mask );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item.
mask
State information to retrieve. It can be a combination of the following values:
Value
Description
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.
LVIS_OVERLAYMASK | Use this mask to retrieve the item’s overlay image index.
LVIS_STATEIMAGEMASK | Use this mask to retrieve the item’s state image index.

Return Values

Returns the current state for the specified item. The only valid bits in the return value are those that correspond to the bits set in the mask parameter.

Remarks

An item’s state information includes a set of bit flags as well as image list indexes that indicate the item’s state image and overlay image.

See Also

ListView_SetItemState


ListView_GetItemText

This macro retrieves the text of a list view item or subitem. You can use this macro or send the LVM_GETITEMTEXT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETITEMTEXT

Syntax

void WINAPI ListView_GetItemText( HWND hwnd, int iItem, int iSubItem,
LPSTR pszText, int cchTextMax );

Parameters

hwnd
Handle to the list view control.
iItem
Index of the list view item.
iSubItem
Index of the subitem, or zero to retrieve the item label.
pszText
Pointer to the buffer that receives the item or subitem text.
cchTextMax
Size of the buffer, in bytes.

Return Values

The ListView_GetItemText macro does not return a value. If you send the LVM_GETITEMNEXT message explicitly, it returns the length of the retrieved string.

See Also

LVITEM


ListView_GetNextItem

This macro searches for a list view item that has the specified properties and bears the specified relationship to a specified item. You can use this macro or send the LVM_GETNEXTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETNEXTITEM

Syntax

int ListView_GetNextItem( HWND hwnd, int iStart, UINT flags );

Parameters

hwnd
Handle to the list view control.
iStart
Index of the item with which to begin the search, or -1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.
flags
Geometric relation of the requested item to the specified item and, if specified, the state of the requested item. For a list of possible values, see the description of the flags parameter in the LVM_GETNEXTITEM message. If an item does not have all of the specified state flags set, the search continues with the next item.

Return Values

The index of the next item indicates success. –1 indicates failure.


ListView_GetOrigin

This macro retrieves the current view origin for a list view control. You can use this macro or send the LVM_GETORIGIN message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETORIGIN

Syntax

BOOL ListView_GetOrigin( HWND hwnd, LPPOINT lpptOrg );

Parameters

hwnd
Handle to the list view control.
lpptOrg
Long pointer to a POINT structure that receives the view origin.

Return Values

TRUE indicates success. FALSE indicates that the current view is list or report view.


ListView_GetSelectedCount

This macro determines the number of selected items in a list view control. You can use this macro or send the LVM_GETSELECTEDCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETSELECTEDCOUNT

Syntax

UINT ListView_GetSelectedCount( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

Returns the number of selected items.


ListView_GetSelectionMark

This macro retrieves the selection mark from a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_GETSELECTIONMARK

Syntax

INT ListView_GetSelectionMark(HWND hwndLV);

Parameters

hwndLV
Handle to a list view control.

Return Values

Returns the zero-based selection mark, or -1 if there is no selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts.


ListView_GetStringWidth

This macro determines the width of a specified string, using the specified list view control’s current font. You can use this macro or send the LVM_GETSTRINGWIDTH message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETSTRINGWIDTH

Syntax

int ListView_GetStringWidth( HWND hwnd, LPCSTR psz );

Parameters

hwnd
Handle to the list view control.
psz
Pointer to a null-terminated string.

Return Values

The string width indicates success. Zero indicates failure.

Remarks

The ListView_GetStringWidth macro returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in a call to the ListView_SetColumnWidth macro, the string will be truncated. To get the column width that can contain the string without truncating it, you must add padding to the returned string width.


ListView_GetSubItemRect

This macro retrieves information about the rectangle that surrounds a subitem in a list view control. This macro is intended to be used only on list view controls that use the LVS_REPORT style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_GETSUBITEMRECT

Syntax

BOOL ListView_GetSubItemRect( HWND hwndLV, int iItem, int iSubItem,
int code, LPRECT lpRect);

Parameters

hwndLV
Handle to a list view control.
iItem
Index of the subitem’s parent item.
iSubItem
One-based index of the subitem.
code
Portion of the list view subitem for which to retrieve the bounding rectangle information. It is one of the following values:
Value
Description
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL | Returns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.

lpRect
Long pointer to a RECT structure that receives the subitem bounding rectangle information.

Return Values

Nonzero indicates success. Zero indicates otherwise.


ListView_GetTextBkColor

This macro retrieves the text background color of a list view control. You can use this macro or send the LVM_GETTEXTBKCOLOR message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETTEXTBKCOLOR

Syntax

COLORREF ListView_GetTextBkColor( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

Returns the background color of the text.


ListView_GetTextColor

This macro retrieves the text color of a list view control. You can use this macro or send the LVM_GETTEXTCOLOR message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETTEXTCOLOR

Syntax

COLORREF ListView_GetTextColor( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

Returns the text color.


ListView_GetTopIndex

This macro retrieves the index of the topmost visible item when in list or report view. You can use this macro or send the LVM_GETTOPINDEX message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETTOPINDEX

Syntax

int ListView_GetTopIndex( HWND hwnd );

Parameters

hwnd
Handle to the list view control.

Return Values

The index of the item indicates success. Zero indicates that the list view control is in icon or small icon view.


ListView_GetViewRect

This macro retrieves the bounding rectangle of all items in the list view control. The list view must be in icon or small icon view. You can use this macro or send the LVM_GETVIEWRECT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_GETVIEWRECT

Syntax

BOOL ListView_GetViewRect( HWND hwnd, RECT FAR* prc );

Parameters

hwnd
Handle to the list view control.
prc
Pointer to a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list view control.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_HitTest

This macro determines which list view item, if any, is at a specified position. You can use this macro or send the LVM_HITTEST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_HITTEST

Syntax

int ListView_HitTest( HWND hwnd, LV_HITTESTINFO FAR* pinfo );

Parameters

hwnd
Handle to the list view control.
pinfo
Pointer to an LVHITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

Return Values

The index of the item at the specified position, if any, indicates success. –1 indicates failure.


ListView_InsertColumn

This macro inserts a new column in a list view control. You can use this macro or send the LVM_INSERTCOLUMN message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_INSERTCOLUMN

Syntax

int ListView_InsertColumn( HWND hwnd, int iCol,
const LV_COLUMN FAR* pcol );

Parameters

hwnd
Handle to the list view control.
iCol
Index of the new column.
pcol
Pointer to an LVCOLUMN structure that contains the attributes of the new column.

Return Values

The index of the new column indicates success. –1 indicates failure.


ListView_InsertItem

This macro inserts a new item in a list view control. You can use this macro or send the LVM_INSERTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_INSERTITEM

Syntax

int ListView_InsertItem( HWND hwnd, const LV_ITEM FAR* pitem );

Parameters

hwnd
Handle to the list view control.
pitem
Pointer to an LVITEM structure that specifies the attributes of the list view item. The iItem member of the structure specifies the index of the new item.

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems; the iSubItem member of the LVITEM structure must be zero.

Return Values

The index of the new item indicates success. –1 indicates failure.

Remarks

If a list view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INNSETITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEM structure.


ListView_RedrawItems

This macro forces a list view control to redraw a range of items. You can use this macro or send the LVM_REDRAWITEMS message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_REDRAWITEMS

Syntax

BOOL ListView_RedrawItems( HWND hwnd, int iFirst, int iLast );

Parameters

hwnd
Handle to the list view control.
iFirst
Index of the first item to redraw.
iLast
Index of the last item to redraw.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The specified items are not actually redrawn until the list view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.


ListView_Scroll

This macro scrolls the content of a list view control. You can use this macro or send the LVM_SCROLL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SCROLL

Syntax

BOOL ListView_Scroll( HWND hwnd, int dx, int dy );

Parameters

hwnd
Handle to the list view control.
dx
Specifies the amount of horizontal scrolling in pixels. If the list view control is in list view, this value specifies the number of columns to scroll.
dy
Specifies the amount of vertical scrolling in pixels.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When the list view control is in report view, the control can only be scrolled vertically in whole line increments. Therefore, the dy parameter will be rounded to the nearest number of pixels that form a whole line increment. For example, if the height of a line is 16 pixels and 8 is passed for dy, the list will be scrolled by 16 pixels (1 line). If 7 is passed for dy, the list will be scrolled 0 pixels (0 lines).


ListView_SetBkColor

This macro sets the background color a list view control. You can use this macro or send the LVM_SETBKCOLOR message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETBKCOLOR

Syntax

BOOL ListView_SetBkColor( HWND hwnd, COLORREF clrBk );

Parameters

hwnd
Handle to the list view control.
clrBk
Background color to set or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_SetCallbackMask

This macro changes the callback mask for a list view control. You can use this macro or send the LVM_SETCALLBACKMASK message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETCALLBACKMASK

Syntax

BOOL ListView_SetCallbackMask( HWND hwnd, UINT mask );

Parameters

hwnd
Handle to the list view control.
mask
Value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. It can be any combination of the following constants:
Value
Description
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus.
LVIS_SELECTED | The item is selected.
LVIS_OVERLAYMASK | The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK | The application stores the image list index of the current state image for each item.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The callback mask of a list view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control’s items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list view control stores all item state information. After creating a list view control and initializing its items, you can use the ListView_SetCallbackMask macro or LVM_SETCALLBACKMASK message to change the callback mask. To get the current callback mask, send the LVM_GETCALLBACKMASK message.

See Also

LVN_GETDISPINFO


ListView_SetColumn

This macro sets the attributes of a list view column. You can use this macro or send the LVM_SETCOLUMN message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETCOLUMN

Syntax

BOOL ListView_SetColumn( HWND hwnd, int iCol,
LV_COLUMN FAR* pcol );

Parameters

hwnd
Handle to the list view control.
iCol
Index of the column.
pcol
Pointer to an LVCOLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.

If the mask member specifies the LVCF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_SetColumnOrderArray

This macro sets the left-to-right order of columns in a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_SETCOLUMNORDERARRAY

Syntax

BOOL ListView_SetColumnOrderArray(HWND hwndLV, int iCount,
int *lpiArray);

Parameters

hwndLV
Handle to a list view control.
iCount
Number of columns in the list view control.
lpiArray
Long pointer to an array that specifies the order in which columns should be displayed, in left-to-right order. For example, if the contents of the array are {2,0,1}, the control displays column 2, column 0, and column 1 in that order.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_SetColumnWidth

This macro changes the width of a column in report or list view. You can use this macro or send the LVM_SETCOLUMNWIDTH message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETCOLUMNWIDTH

Syntax

BOOL ListView_SetColumnWidth( HWND hwnd, int iCol, int cx );

Parameters

hwnd
Handle to the list view control.
iCol
Index of the column. In list view, the iCol parameter must be –1.
cx
New width of the column, in list view coordinates, or one of the following values:
Value
Description
LVSCW_AUTOSIZE | Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER | Automatically sizes the column to fit the header text.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

ListView_SetColumnWidth converts the cx parameter to a 16-bit value.


ListView_SetExtendedListViewStyle

This macro sets extended styles for list view controls.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_SETEXTENDEDLISTVIEWSTYLE

Syntax

void ListView_SetExtendedListViewStyle(HWND hwndLV,
DWORD dwExStyle);

Parameters

hwndLV
Handle to the list view control that will receive the style change.
dwExStyle
Specifies the extended list view control style. This parameter can be a combination of extended styles.


ListView_SetIconSpacing

This macro sets the spacing between icons in list view controls set to the LVS_ICON style.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_SETICONSPACING

Syntax

DWORD ListView_SetIconSpacing(HWND hwndLV, int cx, int cy);

Parameters

hwndLV
Handle to a list view control.
cx
Distance, in pixels, to set between icons on the x-axis.
cy
Distance, in pixels, to set between icons on the y-axis.

Return Values

Returns a DWORD value that contains the previous cx in the low-order word, and the previous cy in the high-order word.

Remarks

The cx and cy parameters are relative to the upper-left corner of an icon bitmap. Therefore, to set spacing between icons that do not overlap, the cx or cy values must include the size of the icon, plus the amount of empty space desired between icons. Values that do not include the width of the icon will result in overlaps.


ListView_SetImageList

This macro assigns an image list to a list view control. You can use this macro or send the LVM_SETIMAGELIST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETIMAGELIST

Syntax

HIMAGELIST ListView_SetImageList( HWND hwnd, HIMAGELIST himl,
int iImageList );

Parameters

hwnd
Handle to the list view control.
himl
Handle to the image list to assign.
iImageList
Type of image list. It is one of the following values:
Value
Description
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.

Return Values

The handle to the image list previously associated with the control indicates success. NULL indicates failure.

Remarks

Windows CE supports a new value for the iImageList parameter. The LVSIL_HEADER constant specifies that, in report view, the image list will be displayed in the list view’s header control.


ListView_SetItem

This macro sets some or all of a list view item’s attributes. You can also use ListView_SetItem to set the text of a subitem. You can use this macro or send the LVM_SETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETITEM

Syntax

BOOL ListView_SetItem( HWND hwnd, const LV_ITEM FAR* pitem );

Parameters

hwnd
Handle to the list view control.
pitem
Pointer to an LVITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change, and the state member contains the values for those states.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

To set the attributes of a list view item, set the iItem member of the LVITEM structure to the index of the item, and set the iSubItem member to zero. For an item, you can use the state, pszText, iImage, and lParam members of the LVITEM structure to modify these item parameters.

To set the text of a subitem, set the iItem and iSubItem members to indicate the specific subitem, and use the pszText member to specify the text. Alternatively, you can use the ListView_SetItemText macro to set the text of a subitem. You cannot set the state or lParam members for subitems because subitems do not have these attributes. In version 4.70 and later, you can set the iImage member for subitems. The subitem image will be displayed if the list view control has the LVS_EX_SUBITEMIMAGES extended style. Previous versions will ignore the subitem image.


ListView_SetItemCount

This macro prepares a list view control for adding a large number of items. You can use this macro or send the LVM_SETITEMCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETITEMCOUNT

Syntax

void ListView_SetItemCount( HWND hwnd, int cItems );

Parameters

hwndLV
Handle to a list view control.
cItems
Number of items for which the list view control should allocate memory.

Return Values

None.

Remarks

If the list view control was created without the LVS_OWNERDATA style, this macro causes the control to allocate its internal data structures for the specified number of items. This prevents the control from having to allocate the data structures every time an item is added.

If the list view control was created with the LVS_OWNERDATA style , the ListView_SetItemCountEx macro should be used.

In Windows CE versions 2.0 and later, if the list view control is a virtual list view (has the LVS_OWNERDATA style), use the ListView_SetItemCountEx macro instead.

See Also

ListView_SetItemCountEx


ListView_SetItemCountEx

This macro sets the virtual number of items in a virtual list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_SETITEMCOUNT

Syntax

void ListView_SetItemCountEx(HWND hwndLV, int cItems,
DWORD dwFlags);

Parameters

hwndLV
Handle to a virtual list view control.
cItems
Number of items that the list view control will contain.
dwFlags
Specifies the behavior of the list view control after resetting the item count. It can be one or a combination of the following values:
Value
Description
LVSICF_NOINVALIDATEALL | The list view control will not repaint unless affected items are currently in view.
LVSICF_NOSCROLL | The list view control will not change the scroll position when the item count changes.

Remarks

This macro is intended only for list view controls that use the LVS_OWNERDATA and LVS_REPORT or LVS_LIST styles.

If the list view control was created with the LVS_OWNERDATA style, this macro sets the virtual number of items that the control contains.

If the list view control was created without the LVS_OWNERDATA style, the ListView_SetItemCount macro should be used.


ListView_SetItemPosition

This macro moves an item to a specified position in a list view control, which must be in icon or small icon view. You can use this macro or send the LVM_SETITEMPOSITION message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETITEMPOSITION

Syntax

BOOL ListView_SetItemPosition( HWND hwnd, int i, int x, int y );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item.
x and y
New position of the item’s upper-left corner, in view coordinates.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the list view control has the LVS_AUTOARRANGE style, the list view control is arranged after the position of the item is set.


ListView_SetItemPosition32

This macro moves an item to a specified position in a list view control, which must be in icon or small icon view. This macro differs from the ListView_SetItemPosition macro in that it uses 32-bit coordinates. You can use this macro or send the LVM_SETITEMPOSITION32 message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETITEMPOSITION32

Syntax

void ListView_SetItemPosition32( HWND hwnd, int iItem, int x, int y );

Parameters

hwnd
Handle to the list view control.
iItem
Index of the list view item for which to set the position.
x and y
New horizontal and vertical coordinates of the item.

Return Values

None.

See Also

POINT


ListView_SetItemState

This macro changes the state of an item in a list view control. You can use this macro or send the LVM_SETITEMSTATE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETITEMSTATE

Syntax

BOOL WINAPI ListView_SetItemState( HWND hwnd, int i, UINT state, UINT mask );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item. If this parameter is –1, then the state change is applied to all items.
state
New state bits for the item. The mask parameter indicates the valid bits of the state parameter. The macro ignores bits in the state parameter if the corresponding bit is not set in the mask parameter.

The low-order byte contains a set of bit flags that indicate the item’s state. This byte can be a combination of the following values:
Value
Description
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.

Bits 8 through 11 of the state parameter specify the one-based index of an overlay image in the control’s image lists. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed over the item’s icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To specify an overlay index, use the INDEXTOOVERLAYMASK macro.

Bits 12 through 15 of the state parameter specify the one-based index of an image in the control’s state image list. The state image is displayed next to an item’s icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To specify a state image index, use the INDEXTOSTATEIMAGEMASK macro.

mask
Bits of the state parameter that you want to set or clear. You can use ListView_SetItemState both to set and to clear bits. To set an item’s overlay image index, set the LVIS_OVERLAYMASK bits. To set an item’s state image index, set the LVIS_STATEIMAGEMASK bits.

Return Values

None.

Remarks

An item’s state value includes a set of bit flags that indicate the item’s state. The state value can also include image list indexes that indicate the item’s state image and overlay image.

The mask parameter specifies the state bits you want to modify, and the state parameter specifies the new value for those bits. To set a bit in the item’s internal state, set it in both the mask and state parameters. To clear a bit in the item’s internal state, set it in the mask parameter and clear it in the state parameter. To leave a bit unchanged in the item’s internal state, clear it in the mask parameter.

See Also

ListView_GetItemState


ListView_SetItemText

This macro changes the text of a list view item or subitem. You can use this macro or send the LVM_SETITEMTEXT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETITEMTEXT

Syntax

void WINAPI ListView_SetItemText( HWND hwnd, int i, int iSubItem, LPCSTR pszText );

Parameters

hwnd
Handle to the list view control.
i
Index of the list view item.
iSubItem
Index of the subitem. To set the item label, set iSubItem to zero.
pszText
Pointer to a null-terminated string that contains the new text.

This parameter can be LPSTR_TEXTCALLBACK to indicate a callback item for which the parent window stores the text. In this case, the list view control sends the parent an LVN_GETDISPINFO notification message when it needs the text.

This parameter can be NULL.

Return Values

None.


ListView_SetSelectionMark

This macro sets the selection mark in a list view control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_SETSELECTIONMARK

Syntax

INT ListView_SetSelectionMark(HWND hwndLV, INT iIndex);

Parameters

hwndLV
Handle to a list view control.
iIndex
Zero-based index of the list view item to be selected.

Return Values

Returns the previous selection mark, or –1 if there is no previous selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts. This macro does not affect the selection state of the item.


ListView_SetTextBkColor

This macro sets the background color of text in a list view control. You can use this macro or send the LVM_SETTEXTBKCOLOR message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETTEXTBKCOLOR

Syntax

BOOL ListView_SetTextBkColor( HWND hwnd, COLORREF clrText );

Parameters

hwnd
Handle to the list view control.
clrText
New text color.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_SetTextColor

This macro sets the text color of a list view control. You can use this macro or send the LVM_SETTEXTCOLOR message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SETTEXTCOLOR

Syntax

BOOL ListView_SetTextColor( HWND hwnd, COLORREF clrText );

Parameters

hwnd
Handle to the list view control.
clrText
New text color.

Return Values

TRUE indicates success. FALSE indicates failure.


ListView_SortItems

This macro uses an application-defined comparison function to sort the items of a list view control. The index of each item changes to reflect the new sequence. You can use this macro or send the LVM_SORTITEMS message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_SORTITEMS

Syntax

BOOL ListView_SortItems( HWND hwnd, PFNLVCOMPARE pfnCompare,
LPARAM lParamSort );

Parameters

hwnd
Handle to the list view control.
pfnCompare
Pointer to the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.
lParamSort
Application-defined value that is passed to the comparison function.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort);

The lParam1 parameter is the 32-bit value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items’ LVITEM structure when they were inserted into the list. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.


ListView_SubItemHitTest

This macro determines which list view item or subitem is located at a specified position.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | LVM_SUBITEMHITTEST

Syntax

INT ListView_SubItemHitTest(HWND hwndLV,
LPLVHITTESTINFO pInfo);

Parameters

hwndLV
Handle to the list view control that will be hit-tested.
pInfo
Pointer to an LVHITTESTINFO structure. The POINT structure within LVHITTESTINFO must be set to the client coordinates to be hit-tested.

Return Values

Returns the index of the item or subitem tested, if any, or –1 otherwise. If an item or subitem is at the specified coordinates, the fields of the LVHITTESTINFO structure will be filled with the applicable hit information.


ListView_Update

This macro updates a list view item. If the list view control has the LVS_AUTOARRANGE style, this macro causes the list view control to be arranged. You can use this macro or send the LVM_UPDATE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | LVM_UPDATE

Syntax

BOOL ListView_Update( HWND hwnd, int iItem );

Parameters

hwnd
Handle to the list view control.
iItem

Index of the item to update.

Return Values

TRUE indicates success. FALSE indicates failure.


MonthCal_GetColor

This macro retrieves the color for a specified portion of a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETCOLOR

Syntax

COLORREF MonthCal_GetColor(HWND hwndMC, INT iColor);

Parameters

hwndMC
Handle to a month calendar control.
iColor
INT value that specifies which month calendar color to retrieve. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Retrieves the background color displayed between months.
MCSC_MONTHBK | Retrieves the background color displayed within the month.
MCSC_TEXT | Retrieves the color used to display text within a month.
MCSC_TITLEBK | Retrieves the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Retrieves the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Retrieves the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

Return Values

Upon success, this macro returns a COLORREF value that represents the color setting for the specified portion of the month calendar control. The macro returns –1 upon failure.


MonthCal_GetCurSel

This macro retrieves the system time portrayed by the currently selected date.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETCURSEL

Syntax

BOOL MonthCal_GetCurSel(HWND hwndMC,
LPSYSTEMTIME lpSysTime);

Parameters

hwndMC
Handle to a month calendar control.
lpSysTime
Long pointer to a SYSTEMTIME structure that will receive the system time information.

Return Values

Nonzero indicates success. Zero indicates otherwise. This macro will always fail when applied to month calendar controls that are set to the MCS_MULTISELECT style.


MonthCal_GetFirstDayOfWeek

This macro retrieves the first day of the week for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETFIRSTDAYOFWEEK

Syntax

DWORD MonthCal_GetFirstDayOfWeek(HWND hwndMC);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

Returns a DWORD value that contains two values. The high-order word is a BOOL that is nonzero if the first day of the week is set to something other than LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low-order word is an INT value that represents the first day of the week. The low-order word will be one of the values shown in the following table.

Value
Day
0 | Monday
1 | Tuesday
2 | Wednesday
3 | Thursday
4 | Friday
5 | Saturday
6 | Sunday


MonthCal_GetMaxSelCount

This macro retrieves the maximum selectable date range that is set for a month calendar control. You can use this macro or send the MCM_GETMAXSELCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETMAXSELCOUNT

Syntax

DWORD MonthCal_GetMaxSelCount(HWND hwndMC);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

You can change the selectable date range using the MCM_SETMAXSELCOUNT message.

Returns an INT value that represents the total number of days that can be selected for the control.


MonthCal_GetMaxTodayWidth

This macro retrieves the maximum width of the “Today” string in a month calendar control. This includes the label text and the date text.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETMAXTODAYWIDTH

Syntax

DWORD MonthCal_GetMaxTodayWidth(HWND hwndMC);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

Returns the width of the “Today” string, in pixels.


MonthCal_GetMinReqRect

This macro retrieves the minimum size required to display a full month in a month calendar control. Size information is presented in the form of a RECT structure.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETMINREQRECT

Syntax

BOOL MonthCal_GetMinReqRect(HWND hwndMC, LPRECT lpRectInfo);

Parameters

hwndMC
Handle to a month calendar control.
lpRectInfo
Long pointer to a RECT structure that will receive bounding rectangle information.

Return Values

Returns nonzero and lpRectInfo receives the applicable bounding information if successful. Otherwise, the macro returns zero.

Remarks

The top and left members of the RECT structure specified by lpRectInfo will always be zero. The right and i members represent the minimum cx and cy required for the control.

The minimum required window size for a month calendar control depends on the currently selected font.


MonthCal_GetMonthDelta

This macro retrieves the “scroll rate” for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETMONTHDELTA

Syntax

INT MonthCal_GetMonthDelta(HWND hwndMC);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

If the month delta was previously set using the MonthCal_SetMonthDelta macro, returns an INT value that represents the month calendar’s current scroll rate. If the month delta was not previously set using the MonthCal_SetMonthDelta macro or the month delta was reset to the default, returns an INT value that represents the current number of months visible.


MonthCal_GetMonthRange

This macro retrieves date information (using SYSTEMTIME structures) that represents the high and low limits of a month calendar control’s display.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETMONTHRANGE

Syntax

DWORD MonthCal_GetMonthRange(HWND hwndMC, DWORD dwFlag, LPSYSTEMTIME lprgSysTimeArray);

Parameters

hwndMC
Handle to a month calendar control.
dwFlag
Specifies the scope of the range limits to be retrieved. It is one of the following values:
Value
Description
GMR_DAYSTATE | Include preceding and trailing months of visible range that are only partially displayed.
GMR_VISIBLE | Include only those months that are entirely displayed.

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the scope specified by dwFlag. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structure are not modified.

Return Values

Returns an INT that represents the range, in months, spanned by the two limits returned at lprgSysTimeArray.


MonthCal_GetRange

This macro retrieves the minimum and maximum allowable dates set for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETRANGE

Syntax

DWORD MonthCal_GetRange(HWND hwndMC,
LPSYSTEMTIME lprgSysTimeArray);

Parameters

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that will receive the date limit information. The minimum limit is set in lprgSysTimeArray[0], and lprgSysTimeArray[1] receives the maximum limit. If either element is set to all zeros, then no corresponding limit is set for the month calendar control. The time members of these structures are not modified.

Return Values

Returns a DWORD that can be zero (no limits are set) or a combination of the following values that specify limit information:

GDTR_MAX
There is a maximum limit set for the control; lprgSysTimeArray[0] is valid and contains the applicable date information.
GDTR_MIN
There is a minimum limit set for the control; lprgSysTimeArray[1] is valid and contains the applicable date information.


MonthCal_GetSelRange

This macro retrieves date information that represents the upper and lower limits of the date range currently selected by the user.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETSELRANGE

Syntax

BOOL MonthCal_GetSelRange(HWND hwndMC,
LPSYSTEMTIME lprgSysTimeArray);

Parameters

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the user’s selection. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures will not be modified.

Return Values

Nonzero indicates success. Zero indicates otherwise. MonthCal_GetSelRange will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.


MonthCal_GetToday

This macro retrieves the date information for the date specified as “today” for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_GETTODAY

Syntax

BOOL MonthCal_GetToday(HWND hwndMC, LPSYSTEMTIME lpToday);

Parameters

hwndMC
Handle to a month calendar control.
lpToday
Long pointer to a SYSTEMTIME structure that will receive the date information.

Return Values

Nonzero indicates success. Zero indicates otherwise.


MonthCal_HitTest

This macro determines which portion of a month calendar control is at a specified point on the screen.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_HITTEST

Syntax

DWORD MonthCal_HitTest(HWND hwndMC,
PMCHITTESTINFO pMCHitTest);

Parameters

hwndMC
Handle to a month calendar control.
pMCHitTest
Pointer to an MCHITTESTINFO structure. Upon sending the macro, the cbSize member must equal sizeof(MCHITTESTINFO), and pt must be set to the point you want to hit test.

Return Values

Sets values in members of the MCHITTESTINFO structure at pMCHitTest and returns one of the following DWORD values:

MCHT_CALENDARBK
The specified point was in the calendar’s background.
MCHT_CALENDARDATE
The specified point was on a particular date within the calendar. The SYSTEMTIME structure at lpMCHitTest->st is set to the date at the specified point.
MCHT_CALENDARDATENEXT
The specified point was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_CALENDARDATEPREV
The specified point was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_CALENDARDAY
The specified point was over a day abbreviation (“Fri”). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the top row.
MCHT_CALENDARWEEKNUM
The specified point was over a week number (the MCS_WEEKNUMBERS style only). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the leftmost column.
MCHT_NOWHERE
The specified point was either not on the month calendar control, or in an inactive portion of the control.
MCHT_TITLEBK
The specified point was over the background of a month’s title.
MCHT_TITLEBTNNEXT
The specified point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_TITLEBTNPREV
The specified point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLEMONTH
The specified point was in a month’s title bar, over a month name.
MCHT_TITLEYEAR
The specified point was in a month’s title bar, over the year value.

The uHit member of the MCHITTESTINFO structure at pMCHitTest will equal the return value.


MonthCal_SetColor

This macro sets the color for a specified portion of a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETCOLOR

Syntax

COLORREF MonthCal_SetColor(HWND hwndMC, INT iColor, COLORREF clr);

Parameters

hwndMC
Handle to a month calendar control.
iColor
INT value that specifies which month calendar color to set. It is one of the following values:
Value
Description
MCSC_BACKGROUND | Retrieves the background color displayed between months.
MCSC_MONTHBK | Retrieves the background color displayed within the month.
MCSC_TEXT | Retrieves the color used to display text within a month.
MCSC_TITLEBK | Retrieves the background color displayed in the calendar’s title.
MCSC_TITLETEXT | Retrieves the color used to display text within the calendar’s title.
MCSC_TRAILINGTEXT | Retrieves the color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

clr
COLORREF value that represents the color that will be set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, this macro returns –1.


MonthCal_SetCurSel

This macro sets the currently selected date for a month calendar control. If the specified date is not in view, the control updates the display to bring it into view.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETCURSEL

Syntax

BOOL MonthCal_SetCurSel(HWND hwndMC,
LPSYSTEMTIME lpSysTime);

Parameters

hwndMC
Handle to a month calendar control.
lpSysTime
Long pointer to a SYSTEMTIME structure that contains the date to be set as the current selection. The time members of this structure are ignored.

Return Values

Nonzero indicates success. Zero indicates otherwise. This macro will fail if applied to a month calendar control that uses the MCS_MULTISELECT style.


MonthCal_SetDayState

This macro sets the display for days in all months that are currently visible within a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETDAYSTATE

Syntax

BOOL MonthCal_SetDayState(HWND hwndMC, INT iMonths, LPMONTHDAYSTATE lpDayStateArray);

Parameters

hwndMC
Handle to a month calendar control.
iMonths
INT value that indicates how many elements are in the array that lpDayStateArray points to.
lpDayStateArray
Long pointer to an array of MONTHDAYSTATE values that define how the month calendar control will draw each day in its display.

Return Values

Nonzero if successful. If the macro fails, it returns zero.

Remarks

The array at lpDayStateArray must contain as many elements as the value returned by the following macro:

MonthCal_GetMonthRange(hwndMC, GMR_DAYSTATE, NULL);

The preceding macro returns the total number of months that are in complete or partial view within the month calendar’s display.

Keep in mind that the array at lpDayStateArray must contain MONTHDAYSTATE values that correspond with all months currently in the control’s display, in chronological order. This includes the two months only partially displayed before the first month and after the last month.


MonthCal_SetFirstDayOfWeek

This macro sets the first day of the week for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETFIRSTDAYOFWEEK

Syntax

DWORD MonthCal_SetFirstDayOfWeek(HWND hwndMC, INT iDay);

Parameters

hwndMC
Handle to a month calendar control.
iDay
INT value that specified which day is to be set as the first day of the week. It is one of the following values:
Value
Day
0 | Monday
1 | Tuesday
2 | Wednesday
3 | Thursday
4 | Friday
5 | Saturday
6 | Sunday

Return Values

Returns a DWORD value that contains two values. The high-order word is a BOOL that is nonzero if the previous first day of the week did not equal LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low-order word is an INT value that represents the previous day-of-the-week number (see list under iDay).

Remarks

If the first day of the week is set to anything other than the default (LOCALE_IFIRSTDAYOFWEEK), the control will not automatically update first-day-of-the-week changes based on locale changes.


MonthCal_SetMaxSelCount

This macro sets the maximum number of days that can be selected in a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETMAXSELCOUNT

Syntax

BOOL MonthCal_SetMaxSelCount(HWND hwndMC, UINT iMax);

Parameters

hwndMC
Handle to a month calendar control.
iMax
INT value that will be set to represent the maximum number of selectable days.

Return Values

Nonzero indicates success. Zero indicates otherwise. This macro will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.


MonthCal_SetMonthDelta

This macro sets the “scroll rate” for a month calendar control. The scroll rate is the number of months that a month calendar control moves its display when the user clicks a scroll button.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETMONTHDELTA

Syntax

INT MonthCal_SetMonthDelta(HWND hwndMC, INT iDelta);

Parameters

hwndMC
Handle to a month calendar control.
iDelta
Value representing the number of months to be set as the control’s scroll rate. If this value is zero, the month delta is reset to the default, which is the number of months displayed in the control.

Return Values

Returns an INT value that represents the previous scroll rate. If the scroll rate has not been previously set, the return value is zero.


MonthCal_SetRange

This macro sets the minimum and maximum allowable dates for a month calendar control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETRANGE

Syntax

BOOL MonthCal_SetRange(HWND hwndMC, DWORD fWhichLimit, LPSYSTEMTIME lprgSysTimeArray);

Parameters

hwndMC
Handle to a month calendar control.
fWhichLimit
Values that specify which limit dates are being set. It is one or both of the following values:
Value
Description
GDTR_MAX | The maximum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[1] must contain date information.
GDTR_MIN | The minimum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[0] must contain date information.

lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that contains date limit information. The maximum limit must be in lpSysTimeArray[1] if GDTR_MAX is specified, and lpSysTimeArray[0] must contain the minimum limit if GDTR_MIN is specified. The time members of these structure are ignored.

Return Values

Nonzero indicates success. Zero indicates otherwise.


MonthCal_SetSelRange

This macro sets the selection for a month calendar control to a specified date range.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETSELRANGE

Syntax

BOOL MonthCal_SetSelRange(HWND hwndMC,
LPSYSTEMTIME lprgSysTimeArray);

Parameters

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Long pointer to a two-element array of SYSTEMTIME structures that contains date information representing the selection limits. The first selected date must be specified in lpSysTimeArray[0], and the last selected date must be specified in lpSysTimeArray[1]. The time members of these structures are ignored.

Return Values

Nonzero indicates success. Zero indicates otherwise. This macro will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.


MonthCal_SetToday

This macro sets the “today” selection for a month calendar control, because the control does not automatically update the “today” selection when the time passes midnight for the current day.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | MCM_SETTODAY

Syntax

void MonthCal_SetToday(HWND hwndMC, LPSYSTEMTIME lpSysTime);

Parameters

hwndMC
Handle to a month calendar control.
lpSysTime
Long pointer to a SYSTEMTIME structure that contains the date to be set as the “today” selection for the control. If this parameter is set to NULL, the control returns to the default setting. The time members of this structure are ignored.

If the “today” selection is set to any date other than the default, the following conditions apply.

Remarks

The control will not automatically update its display based on locale changes.


PropSheet_AddPage

This macro adds a new page to the end of an existing property sheet. You can use this macro or send the PSM_ADDPAGE message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_ADDPAGE

Syntax

BOOL PropSheet_AddPage( hPropSheetDlg, hpage );

Parameters

hPropSheetDlg
Handle to the property sheet.
hpage
Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Values

None.

Remarks

The new page should be no larger than the largest page currently in the property sheet because the property sheet is not resized to fit the new page.


PropSheet_Apply

This macro simulates the choice of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded. The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages. You can use this macro or send the PSM_APPLY message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_APPLY

Syntax

BOOL PropSheet_Apply( hPropSheetDlg );

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

TRUE indicates that all pages successfully applied the changes. FALSE indicates failure.


PropSheet_CancelToClose

This macro disables the Cancel button and changes the text of the OK button to Close. An application sends the PSM_CANCELTOCLOSE message after applying a change that cannot be canceled. You can use this macro or send the PSM_CANCELTOCLOSE message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_CANCELTOCLOSE

Syntax

VOID PropSheet_CancelToClose( hPropSheetDlg );

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

None.


PropSheet_Changed

This macro informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button. You can use this macro or send the PSM_CHANGED message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_CHANGED

Syntax

BOOL PropSheet_Changed( hPropSheetDlg, hwndPage );

Parameters

hPropSheetDlg
Handle to the property sheet.
hwndPage
Handle to the page that has changed.

Return Values

None.


PropSheet_GetCurrentPageHwnd

This macro retrieves a handle to the window of the current page of a property sheet. You can use this macro or send the PSM_GETCURRENTPAGEHWND message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_GETCURRENTPAGEHWND

Syntax

HWND PropSheet_GetCurrentPageHwnd( hDlg );

Parameters

hDlg
Handle to the property sheet.

Return Values

A handle to the window of the current property sheet page indicates success.

Remarks

Use the PropSheet_GetCurrentPageHwnd macro with modeless property sheets to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PropSheet_GetCurrentPageHwnd returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

PropertySheet


PropSheet_GetTabControl

This macro retrieves the handle to the tab control of a property sheet. You can use this macro or send the PSM_GETTABCONTROL message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_GETTABCONTROL

Syntax

HWND PropSheet_GetTabControl( hPropSheetDlg );

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

The handle to the tab control indicates success.


PropSheet_IsDialogMessage

This macro passes a message to a property sheet dialog box and indicates whether the dialog processed the message. You can use this macro or send the PSM_ISDIALOGMESSAGE message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_ISDIALOGMESSAGE

Syntax

BOOL PropSheet_IsDialogMessage( hDlg, pMsg );

Parameters

hDlg
Handle to the property sheet.
pMsg
Pointer to an MSG structure that contains the message to be checked.

Return Values

TRUE indicates that the macro has been processed. FALSE indicates the macro has not been processed.

Remarks

Your message loop should use the PSM_ISDIALOGMESSAGE message with modeless property sheets to pass messages to the property sheet dialog box.

If the return value indicates that the PSM_ISDIALOGMESSAGE message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See Also

PropertySheet


PropSheet_PressButton

This macro simulates the choice of a property sheet button. You can use this macro or send the PSM_PRESSBUTTON message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_PRESSBUTTON

Syntax

BOOL PropSheet_PressButton( hPropSheetDlg, iButton );

Parameters

hPropSheetDlg
Handle to the property sheet.
iButton
Index of the button to select. It is one of the following values:
Value
Description
PSBTN_APPLYNOW | Selects the Apply Now button.
PSBTN_BACK | Selects the Back button.
PSBTN_CANCEL | Selects the Cancel button.
PSBTN_FINISH | Selects the Finish button.
PSBTN_HELP | Selects the Help button.
PSBTN_NEXT | Selects the Next button.
PSBTN_OK | Selects the OK button.

Return Values

None.


PropSheet_QuerySiblings

This macro causes a property sheet to send the PSM_QUERYSIBLINGS message to each of its pages. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. You can use this macro or send the PSM_QUERYSIBLINGS message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_QUERYSIBLINGS

Syntax

int PropSheet_QuerySiblings( hPropSheetDlg, param1, param2 );

Parameters

hPropSheetDlg
Handle to the property sheet.
param1
First application-defined parameter.
param2
Second application-defined parameter.

Return Values

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.


PropSheet_RebootSystem

This macro indicates that the system needs to be restarted for the changes to take effect. You can use this macro or send the PSM_REBOOTSYSTEM message explicitly. An application should send the PSM_REBOOTSYSTEM message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_REBOOTSYSTEM

Syntax

void PropSheet_RebootSystem( hPropSheetDlg );

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

None.

Remarks

This macro causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user clicks the OK button to close the property sheet. It is the application’s responsibility to reboot the system.

This macro supersedes all PropSheet_RebootSystem macros that precede or follow it.

See Also

PSM_RESTARTWINDOWS


PropSheet_RemovePage

This macro removes a page from a property sheet. You can use this macro or send the PSM_REMOVEPAGE message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_REMOVEPAGE

Syntax

void PropSheet_RemovePage( hPropSheetDlg, index, hpage );

Parameters

hPropSheetDlg
Handle to the property sheet.
index
Zero-based index of the page to remove.
hpage
Handle to the page to remove.

Return Values

None.

Remarks

An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.


PropSheet_RestartWindows

This macro sends a PSM_RESTARTWINDOWS message indicating that Windows needs to be restarted for changes to take effect. You can use this macro or send the PSM_RESTARTWINDOWS message explicitly. An application should send the PSM_RESTARTWINDOWS message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_RESTARTWINDOWS

Syntax

void PropSheet_RestartWindows( hPropSheetDlg );

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

None.

Remarks

The PSM_RESTARTWINDOWS message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user clicks the OK button to close the property sheet. It is the application’s responsibility to reboot the system.


PropSheet_SetCurSel

This macro activates the specified page in a property sheet. You can use this macro or send the PSM_SETCURSEL message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_SETCURSEL

Syntax

BOOL PropSheet_SetCurSel( hPropSheetDlg, hpage, index );

Parameters

hPropSheetDlg
Handle to the property sheet.
index
Zero-based index of the page to activate.
hpage
Handle to the page to activate.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.


PropSheet_SetCurSelByID

This macro activates the specified page in a property sheet based on the resource identifier of the page. You can use this macro or send the PSM_SETCURSELID message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_SETCURSELID

Syntax

BOOL PropSheet_SetCurSelByID( hPropSheetDlg, id );

Parameters

hPropSheetDlg
Handle to the property sheet.
id
Resource identifier of the page to activate.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.


PropSheet_SetFinishText

This macro sets the text of the Finish button in a wizard property sheet, shows and enables the button, and hides the Next and Back buttons. You can use this macro or explicitly send the PSM_SETFINISHTEXT message.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 2.0 and later
Related message: | PSM_SETFINISHTEXT

Syntax

VOID PropSheet_SetFinishText( hPropSheetDlg, lpszText );

Parameters

hPropSheetDlg
Handle to the property sheet.
lpszText
Long pointer to the new text for the Finish button.

Return Values

None.

Remarks

This macro causes the DM_SETDEFID message to be sent to the property sheet dialog box. The wParam parameter specifies the identifier of the Finish button.

See Also

DM_SETDEFID, PSM_SETFINISHTEXT


PropSheet_SetTitle

This macro sets the title of a property sheet. You can use this macro or send the PSM_SETTITLE message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_SETTITLE

Syntax

void PropSheet_SetTitle( hPropSheetDlg, dwStyle, lpszText );

Parameters

hPropSheetDlg
Handle to the property sheet.
dwStyle
Indicates whether to include the prefix “Properties for” with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.
lpszText
Long pointer to a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Values

None.


PropSheet_SetWizButtons

This macro posts the PSM_SETWIZBUTTON message to a wizard property sheet. The PSM_SETWIZBUTTON message enables or disables the Back, Next, and Finish buttons in a wizard property sheet. You can use this macro or explicitly send or post the PSM_SETWIZBUTTON message.

Syntax

VOID PropSheet_SetWizButtons( HWND hPropSheetDlg DWORD dwFlags);

Parameters

hPropSheetDlg
Handle to the property sheet.
dwFlags
Specifies the buttons to display and enable. It is one of the following flags:
Value
Description
PSWIZB_BACK | Enables the Back button.
PSWIZB_NEXT | Enables the Next button.
PSWIZB_FINISH | Displays an enabled Finish button in place of the Next button.
PSWIZB_DISABLEDFINISH | Displays a disabled Finish button in place of the Next button.

A wizard property sheet displays the Back button and either the Next or Finish button, which means that the PSWIZB_BACK flag is coupled with one of the other three flags.

Return Values

None.

See Also

PSM_SETWIZBUTTON


PropSheet_UnChanged

This macro informs a property sheet that informationin a page has reverted to the previously saved state. The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet. You can use this macro or send the PSM_UNCHANGED message explicitly.

At a Glance

Header file: | Prsht.h
Windows CE versions: | 1.0 and later
Related message: | PSM_UNCHANGED

Syntax

void PropSheet_UnChanged( hPropSheetDlg, hwndPage );

Parameters

hPropSheetDlg
Handle to the property sheet.
hwndPage
Handle to the page that has reverted to the previously saved state.

Return Values

None.


TabCtrl_AdjustRect

This macro calculates a tab control’s display area Nonzero indicates success. Zero indicates otherwise. a window rectangle, or calculates the window rectangle that would correspond to a specified display area. You can use this macro or send the TCM_ADJUSTRECT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_ADJUSTRECT

Syntax

void TabCtrl_AdjustRect( HWND hwnd, BOOL fLarger, RECT FAR *prc);

Parameters

hwnd
Handle to the tab control.
fLarger
Boolean value that specifies the operation to perform. If set to TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If set to FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc
Pointer to a RECT structure that specifies the Nonzero indicates success. Zero indicates otherwise. rectangle and receives the calculated rectangle.

Return Values

None.


TabCtrl_DeleteAllItems

This macro removes all items from a tab control. You can use this macro or send the TCM_DELETEALLITEMS message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_DELETEALLITEMS

Syntax

BOOL TabCtrl_DeleteAllItems( HWND hwnd );

Parameters

hwnd
Handle to the tab control.

Return Values

TRUE indicates success. FALSE indicates failure.


TabCtrl_DeleteItem

This macro removes an item from a tab control. You can use this macro or send the TCM_DELETEITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_DELETEITEM

Syntax

BOOL TabCtrl_DeleteItem( HWND hwnd, int iItem );

Parameters

hwnd
Handle to the tab control.
iItem
Index of the item to delete.

Return Values

TRUE indicates success. FALSE indicates failure.


TabCtrl_DeselectAll

This macro resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | TCM_DESELECTALL

Syntax

void TabCtrl_DeselectAll(HWND hwndTab, UINT fExcludeFocus);

Parameters

hwndTab
Handle to the tab control.
fExcludeFocus
Value that specifies the scope of the item deselection. If set to FALSE, all tab items will be reset. If set to TRUE, all but the currently selected tab item will be reset.


TabCtrl_GetExtendedStyle

This macro retrieves the extended styles that are currently in use for the tab control. You can use this macro or send the TCM_GETEXTENDEDSTYLE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | TCM_GETEXTENDEDSTYLE

Syntax

DWORD TabCtrl_GetExtendedStyle( HWND hwndTab);

Parameters

hwndTab
Handle to the tab control.

Return Values

Returns a DWORD that represents the extended styles currently in use for the tab control. This value is a combination of tab control extended styles.


TabCtrl_GetCurFocus

This macro returns the index of the item that has the focus in a tab control. You can use this macro or send the TCM_GETCURFOCUS message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETCURFOCUS

Syntax

int TabCtrl_GetCurFocus( HWND hwnd );

Parameters

hwnd
Handle to the tab control.

Return Values

The index of the tab item that has the focus indicates success.

Remarks

The item that has the focus may be different from the selected item.


TabCtrl_GetCurSel

This macro determines the currently selected tab in a tab control. You can use this macro or send the TCM_GETCURSEL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETCURSEL

Syntax

int TabCtrl_GetCurSel( HWND hwnd );

Parameters

hwnd
Handle to the tab control.

Return Values

The index of the selected tab indicates success. –1 indicates that no tab is selected.


TabCtrl_GetImageList

This macro retrieves the image list associated with a tab control. You can use this macro or send the TCM_GETIMAGELIST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETIMAGELIST

Syntax

HIMAGELIST TabCtrl_GetImageList( HWND hwnd );

Parameters

hwnd
Handle to the tab control.

Return Values

The handle to the image list indicates success. NULL indicates failure.


TabCtrl_GetItem

This macro retrieves information about a tab in a tab control. You can use this macro or send the TCM_GETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETITEM

Syntax

BOOL TabCtrl_GetItem( HWND hwnd, int iItem, TC_ITEM FAR* pitem);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the tab.
pitem
Pointer to a TCITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return Values

TRUE indicates success. FALSE indicates failure.


TabCtrl_GetItemCount

This macro retrieves the number of tabs in the tab control. You can use this macro or send the TCM_GETITEMCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETITEMCOUNT

Syntax

int TabCtrl_GetItemCount( HWND hwnd);

Parameters

hwnd
Handle to the tab control.

Return Values

The number of tabs indicates success. Zero indicates failure.


TabCtrl_GetItemRect

This macro retrieves the bounding rectangle for a tab in a tab control. You can use this macro or send the TCM_GETITEMRECT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETITEMRECT

Syntax

BOOL TabCtrl_GetItemRect( HWND hwnd, int iItem, RECT FAR *prc);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the tab.
prc
Pointer to a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return Values

TRUE indicates success. FALSE indicates failure.


TabCtrl_GetRowCount

This macro retrieves the current number of rows of tabs in a tab control. You can use this macro or send the TCM_GETROWCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_GETROWCOUNT

Syntax

int TabCtrl_GetRowCount( HWND hwnd);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MUTLILINE style can have multiple rows of tabs.


TabCtrl_HighlightItem

This macro sets the highlight state of a tab item.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | TCM_HIGHLIGHTITEM

Syntax

BOOL TabCtrl_HighlightItem(HWND hwndTab, INT idItem,
WORD fHighlight);

Parameters

hwndTab
Handle to the tab control.
idItem
Zero-based index of a tab control item.
fHighlight
Value that specifies the highlight state to be set. If this value is nonzero, the tab is highlighted. If this value is zero, the tab is set to its default state.

Return Values

Nonzero indicates success. Zero indicates otherwise.


TabCtrl_HitTest

This macro determines which tab, if any, is at a specified screen position. You can use this macro or send the TCM_HITTEST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_HITTEST

Syntax

int TabCtrl_HitTest( HWND hwnd, TC_HITTESTINFO FAR *pinfo);

Parameters

hwnd
Handle to the tab control.
pinfo
Pointer to a TCHITTESTINFO structure that specifies the screen position to test.

Return Values

The index of the tab indicates success. –1 indicates that no tab is at the specified position.


TabCtrl_InsertItem

This macro inserts a new tab in a tab control. You can use this macro or send the TCM_INSERTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_INSERTITEM

Syntax

int TabCtrl_InsertItem( HWND hwnd, int iItem,
const TC_ITEM FAR *pitem);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the new tab.
pitem
Pointer to a TCITEM structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

Return Values

The index of the new tab indicates success. –1 indicates failure.


TabCtrl_RemoveImage

This macro removes an image from a tab control’s image list. You can use this macro or send the TCM_REMOVEIMAGE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_REMOVEIMAGE

Syntax

void TabCtrl_RemoveImage( HWND hwnd, int iImage);

Parameters

hwnd
Handle to the tab control.
iImage
Index of the image to remove.

Return Values

None.

Remarks

The tab control updates each tab’s image index, so each tab remains associated with the same image as before. If a tab is using the image being removed, the tab will be set to have no image.


TabCtrl_SetCurFocus

This macro sets the focus to a specified tab in a tab control. You can use this macro or send the TCM_SETCURFOCUS message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETCURFOCUS

Syntax

VOID TabCtrl_SetCurFocus( HWND hwnd, int iItem );

Parameters

hwnd
Handle to the tab control.
iItem
Zero-based index of the tab that gets the focus.

Return Values

None.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, the TabCtrl_SetCurFocus macro sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See Also

TabCtrl_GetCurFocus, TCM_GETCURFOCUS


TabCtrl_SetCurSel

This macro selects a tab in a tab control. You can use this macro or send the TCM_SETCURSEL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETCURSEL

Syntax

int TabCtrl_SetCurSel( HWND hwnd, int iItem);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the tab to select.

Return Values

The index of the previously selected tab indicates success. –1 indicates failure.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using the TCM_SETCUSEL message.


TabCtrl_SetExtendedStyle

This macro sets the extended styles that the tab control will use.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | TCM_SETEXTENDEDSTYLE

Syntax

DWORD TabCtrl_SetExtendedStyle(WND hwndTab, DWORD dwExStyle);

Parameters

hwndTab
Handle to the tab control.
dwExStyle
Contains the new tab control extended styles. It is a combination of tab control extended styles.

Return Values

DWORD that contains the previous tab control extended styles.


TabCtrl_SetImageList

This macro assigns an image list to a tab control. You can use this macro or send the TCM_SETIMAGELIST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETIMAGELIST

Syntax

BOOL TabCtrl_SetImageList( HWND hwnd, HIMAGELIST himl);

Parameters

hwnd
Handle to the tab control.
himl
Handle to the image list to assign to the tab control.

Return Values

The handle to the previous image list indicates success. NULL indicates that there is no previous image list.


TabCtrl_SetItem

This macro sets some or all of a tab’s attributes. You can use this macro or send the TCM_SETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETITEM

Syntax

BOOL TabCtrl_SetItem( HWND hwnd, int iItem, TC_ITEM FAR *pitem);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the item.
pitem
Pointer to a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

TRUE indicates success. FALSE indicates failure.


TabCtrl_SetItemExtra

This macro sets the number of bytes per tab reserved for application-defined data in a tab control. You can use this macro or send the TCM_SETITEMEXTRA message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETITEMEXTRA

Syntax

BOOL TabCtrl_SetItemExtra( HWND hwnd, int cb);

Parameters

hwnd
Handle to the tab control.
cb
Number of extra bytes.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.


TabCtrl_SetItemSize

This macro sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can use this macro or send the TCM_SETITEMSIZE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETITEMSIZE

Syntax

DWORD TabCtrl_SetItemSize( HWND hwnd, int cx, int cy);

Parameters

hwnd
Handle to the tab control.
cx and cy
New width and height, in pixels.

Return Values

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.


TabCtrl_SetMinTabWidth

This macro sets the minimum width of items in a tab control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 2.0 and later
Related message: | TCM_SETMINTABWIDTH

Syntax

int TabCtrl_SetMinTabWidth(HWND hwndTab, INT cx);

Parameters

hwndTab
Handle to the tab control.
cx
Minimum width to be set for a tab control item. If this parameter is set to –1, the control will use the default tab width.

Return Values

Integer that represents the previous minimum tab width.


TabCtrl_SetPadding

This macro sets the amount of space (padding) around each tab’s icon and label in a tab control. You can use this macro or send the TCM_SETPADDING message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TCM_SETPADDING

Syntax

void TabCtrl_SetPadding( HWND hwnd, int cx, int cy);

Parameters

hwnd
Handle to the tab control.
cx and cy
Amount of horizontal and vertical padding, in pixels.

Return Values

None.


TreeView_CreateDragImage

This macro creates a dragging bitmap for the specified item in a tree-view control, creates an image list for the bitmap, and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can use this macro or send the TVM_CREATEDRAGIMAGE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_CREATEDRAGIMAGE

Syntax

HIMAGELIST TreeView_CreateDragImage( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to the item that receives the new dragging bitmap.

Return Values

The handle to the image list to which the dragging bitmap was added indicates success. NULL indicates failure.

Remarks

If you create a tree view control without an associated image list, you cannot use the TreeView_CreateDragImage macro to create the image to display during a drag operation. You must implement your own method of creating a drag cursor.


TreeView_DeleteAllItems

This macro removes an item from a tree-view control. You can use this macro, the TreeView_DeleteItem macro, or send the TVM_DELETEITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_DELETEITEM

Syntax

BOOL TreeView_DeleteAllItems( hwnd);

Parameters

hwndTV
Handle to the tree view control.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.


TreeView_DeleteItem

This macro removes an item from a tree-view control. You can use this macro, the TreeView_DeleteAllItems macro, or send the TVM_DELETEITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_DELETEITEM

Syntax

BOOL TreeView_DeleteItem( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to the item to delete. If hitem is the TVI_ROOT value, all items are deleted from the tree view control.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.


TreeView_EditLabel

This macro begins in-place editing of the specified item’s text, replacing the text of the item with a single-line edit control containing the text. This macro implicitly selects and focuses the specified item. You can use this macro or send the TVM_EDITLABEL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_EDITLABEL

Syntax

HWND TreeView_EditLabel( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to the item to edit.

Return Values

The handle to the edit control used to edit the item text indicates success. NULL indicates failure.

Remarks

This macro sends a TVN_BEGINLABELEDIT notification message to the parent of the tree view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you call this macro. Focus can be set using the SetFocus function.


TreeView_EndEditLabelNow

This macro ends the editing of a tree-view item’s label. You can use this macro or send the TVM_ENDEDITLABELNOW message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_ENDEDITLABELNOW

Syntax

BOOL TreeView_EndEditLabelNow( hwnd, fCancel);

Parameters

hwndTV
Handle to the tree view control.
fCancel
Variable that indicates whether the editing is canceled without being saved to the label. If set to is TRUE, the system cancels editing without saving the changes. If set to FALSE, the system saves the changes to the label.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

This macro causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree view control.


TreeView_EnsureVisible

This macro ensures that a tree-view item is visible, expanding the parent item or scrolling the tree-view control, if necessary. You can use this macro or send the TVM_ENSUREVISIBLE message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_ENSUREVISIBLE

Syntax

BOOL TreeView_EnsureVisible( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to the item.

Return Values

Nonzero indicates that the system scrolled the items in the tree view control and no items were expanded. Zero indicates otherwise.

Remarks

If the TreeView_EnsureVisible macro expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.


TreeView_Expand

This macro expands or collapses the list of child items, if any, associated with the specified parent item. You can use this macro or send the TVM_EXPAND message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_EXPAND

Syntax

BOOL TreeView_Expand( hwnd, hitem, flag);

Parameters

hwndTV
Handle to a tree view control.
hItem
Handle to the parent item that will be expanded or collapsed.
flag
Action flag. For a list of possible values, see the description of the flag parameter in TVM_EXPAND.
Value
Description
TVE_EXPANDPARTIAL Child items are visible and parent item’s plus symbol is displayed. This flag must be used in combination with the TVE_EXPAND flag.

Return Values

Nonzero indicates that a change took place. Zero indicates otherwise.

Remarks

The TreeView_Expand macro will cause the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to be generated if the item being expanded does not have the TVIS_EXPANDEDONCE state bit set. This state gets set when a parent item is expanded for the first time. Using TVE_COLLAPSE and TVE_COLLAPSERESET with TreeView_Expand will cause the TVIS_EXPANDEDONCE state to be reset.

If the item already has the TVIS_EXPANDEDONCE state set, the TreeView_Expand macro will not cause the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to be generated.


TreeView_GetChild

This macro retrieves the first child item of the specified tree-view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CHILD flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetChild( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to a tree view item.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent, TreeView_GetPrevSibling


TreeView_GetCount

This macro retrieves a count of the items in a tree-view control. You can use this macro or send the TVM_GETCOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETCOUNT

Syntax

UINT TreeView_GetCount( hwnd);

Parameters

hwndTV
Handle to the tree view control.

Return Values

Returns the count of items.


TreeView_GetDropHilite

This macro retrieves the tree-view item that is the target of a drag-and-drop operation. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_DROPHILITE flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetDropHilite( hwnd );

Parameters

hwndTV
Handle to the tree view control.

Return Values

The handle to the item indicates success. NULL indicates failure.


TreeView_GetEditControl

This macro retrieves the handle to the edit control being used to edit a tree-view item’s text. You can use this macro or send the TVM_GETEDITCONTROL message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETEDITCONTROL

Syntax

HWND TreeView_GetEditControl( hwnd );

Parameters

hwndTV
Handle to the tree view control.

Return Values

The handle to the edit control indicates success. NULL indicates failure.


TreeView_GetFirstVisible

This macro retrieves the first visible item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_FIRSTVISIBLE flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetFirstVisible( hwnd);

Parameters

hwndTV
Handle to the tree view control.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetNextVisible, TreeView_GetPrevVisible, TVM_GETITEMRECT


TreeView_GetImageList

This macro retrieves the handle to the normal or state image list associated with a tree-view control. You can use this macro or send the TVM_GETIMAGELIST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETIMAGELIST

Syntax

HIMAGELIST TreeView_GetImageList( hwnd, iImage );

Parameters

hwndTV
Handle to the tree view control.
iImage
Type of image list to retrieve. It is one of the following values:
Value
Description
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item’s selected or nonselected image.

Return Values

Returns an HIMAGELIST handle to the specified image list.

See Also

TreeView_SetImageList


TreeView_GetIndent

This macro retrieves the amount, in pixels, that child items are indented relative to their parent items. You can use this macro or send the TVM_GETINDENT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETINDENT

Syntax

UINT TreeView_GetIndent( hwnd );

Parameters

hwndTV
Handle to the tree view control.

Return Values

Returns the amount of indentation.


TreeView_GetISearchString

This macro retrieves the incremental search string for a tree-view control. The tree-view control uses the incremental search string to select an item based on characters typed by the user. You can use this macro or send the TVM_GETISEARCHSTRING message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETISEARCHSTRING

Syntax

BOOL TreeView_GetISearchString( hwnd, lpsz );

Parameters

hwndTV
Handle to the tree view control.
lpsz
Long pointer to the buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string.

Remarks

If the tree view control is not in incremental search mode, the return value is zero.


TreeView_GetItem

This macro retrieves some or all of a tree-view item’s attributes. You can use this macro or send the TVM_GETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETITEM

Syntax

BOOL TreeView_GetItem( hwnd, pitem);

Parameters

hwndTV
Handle to the tree view control.
pitem
Pointer to a TVITEM structure that specifies the information to retrieve and receives information about the item. When the TVM_GETITEM message is sent, the hItem member identifies the item to retrieve information about, and the mask member specifies the attributes to retrieve.

If the mask member specifies the TVIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the TVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

Return Values

TRUE indicates success. FALSE indicates failure.


TreeView_GetItemRect

This macro retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible. You can use this macro or send the TVM_GETITEMRECT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETITEMRECT

Syntax

BOOL TreeView_GetItemRect( hwnd, hitem, prc, fItemRect);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to the tree view item.
prc
Pointer to a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree view control.
fItemRect
Value that specifies the portion of the item for which to retrieve the bounding rectangle. If set to TRUE, the bounding rectangle includes only the text of the item. If set to FALSE, it includes the entire line that the item occupies in the tree view control.

Return Values

TRUE indicates that the item is visible and the bounding rectangle is successfully retrieved. FALSE indicates that the TVM_GETITEMRECT message does not retrieve the bounding rectangle.


TreeView_GetNextItem

This macro retrieves the tree-view item that bears the specified relationship to a specified item. You can use this macro, use one of the TreeView_Get macros described below, or send the TVM_GETNEXTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetNextItem( hwnd, hitem, flag);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item.
flag
Flag that specifies the item to retrieve. It is one of the following values:
Value
Description
TVGN_CARET | Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD | Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE | Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilight macro to send this message.
TVGN_FIRSTVISIBLE | Retrieves the first visible item. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_NEXT | Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE | Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT | Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS | Retrieves the previous sibling item. You can use the TreeVIew_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE | Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT | Retrieves the topmost or very first item of the tree view control. You can use the TreeView_GetRoot macro to send this message.

Return Values

The handle to the item indicates success. NULL indicates failure.


TreeView_GetNextSibling

This macro retrieves the next sibling item of a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXT flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetNextSibling( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetParent, TreeView_GetPrevSibling


TreeView_GetNextVisible

This macro retrieves the next visible item that follows a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXTVISIBLE flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetNextVisible( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetPrevVisible


TreeView_GetParent

This macro retrieves the parent item of the specified tree-view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PARENT flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetParent( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetPrevSibling


TreeView_GetPrevSibling

This macro retrieves the previous sibling item of a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUS flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetPrevSibling( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent


TreeView_GetPrevVisible

This macro retrieves the first visible item that precedes a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUSVISIBLE flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetPrevVisible( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetNextVisible


TreeView_GetRoot

This macro retrieves the topmost or very first item of the tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_ROOT flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetRoot( hwnd);

Parameters

hwndTV
Handle to the tree view control.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetNextItem


TreeView_GetSelection

This macro retrieves the currently selected item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CARET flag.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

HTREEITEM TreeView_GetSelection( hwnd);

Parameters

hwndTV
Handle to the tree view control.

Return Values

The handle to the item indicates success. NULL indicates failure.

See Also

TreeView_GetNextItem


TreeView_GetVisibleCount

This macro obtains the number of items that can be fully visible in the client window of a tree-view control. You can use this macro or send the TVM_GETVISIBLECOUNT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_GETNEXTITEM

Syntax

UINT TreeView_GetVisibleCount( hwnd);

Parameters

hwndTV
Handle to the tree view control.

Return Values

Returns the number of items that can be fully visible in the client window of the tree view control.

Remarks

The number of items that can be fully visible may be greater than the number of items in the control. The control calculates this value by dividing the height of the client window by the height of an item.

Note that the return value is the number of items that can be fully visible. If you can see all of 20 items and part of one more item, the return value is 20.


TreeView_HitTest

This macro determines the location of the specified point relative to the client area of a tree-view control. You can use this macro or send the TVM_HITTEST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_HITTEST

Syntax

HTREEITEM TreeView_HitTest( hwnd, lpht);

Parameters

hwndTV
Handle to the tree view control.
lpht
Long pointer to a TVHITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit test value that indicates the location of the specified point. For a list of hit test values, see the description of the TVHITTESTINFO structure.

Return Values

The handle to the tree view item that occupies the specified point indicates success. NULL indicates that no item occupies the point.


TreeView_InsertItem

This macro inserts a new item in a tree-view control. You can use this macro or send the TVM_INSERTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_INSERTITEM

Syntax

HTREEITEM TreeView_InsertItem( hwnd, lpis);

Parameters

hwndTV
Handle to the tree view control.
lpis
Long pointer to a TVINSERTSTRUCT structure that specifies the attributes of the tree view item.

Return Values

The handle to the new item indicates success. NULL indicates failure.

See Also

TVN_ENDLABELEDIT


TreeView_Select

This macro selects the specified tree-view item, scrolls the item into the view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro or the TreeView_SelectItem, TreeView_SelectSetFirstVisible, or treeView_SelectDropTarget macros, or you can send the TVM_SELECTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SELECTITEM

Syntax

BOOL TreeView_Select( hwnd, hitem, flag);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.
flag
Action flag. It is one of the following values:
Value
Description
TVGN_CARET | Sets the selection to the Nonzero indicates success. Zero indicates otherwise. item. The control’s parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages.
TVGN_DROPHILITE | Redraws the Nonzero indicates success. Zero indicates otherwise. item in the style used to indicate the target of a drag-and-drop operation.
TVGN_FIRSTVISIBLE | Ensures that the specified item is visible, and, if possible, displays it at the top of the control’s window. Tree view controls display as many items as will fit in the window. If the specified item is near the bottom of the control’s hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.


TreeView_SelectDropTarget

This macro redraws a specified tree-view control item in the style used to indicate the target of a drag-and-drop operation. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SELECTITEM

Syntax

BOOL TreeView_SelectDropTarget( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_DROPHILITE value.


TreeView_SelectItem

This macro selects the specified tree-view item. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SELECTITEM

Syntax

BOOL TreeView_SelectItem( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When you call the TreeView_SelectItem macro, the control’s parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_CARET value.


TreeView_SelectSetFirstVisible

This macro scrolls the tree-view control vertically to ensure that the specified item is visible. If possible, the specified item becomes the first visible item at the top of the control’s window. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SELECTITEM

Syntax

BOOL TreeView_SelectSetFirstVisible( hwnd, hitem);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Tree view controls display as many items as will fit in the window. If the specified item is near the bottom of the control’s hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

If the specified item is the child of a collapsed parent item, the parent’s list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectSetFirstVisible macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_FIRSTVISIBLE value.


TreeView_SetImageList

This macro sets the normal or state image list for a tree-view control and redraws the control using the new images. You can use this macro or send the TVM_SETIMAGELIST message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SETIMAGELIST

Syntax

HIMAGELIST TreeView_SetImageList( hwnd, himl, iImage);

Parameters

hwndTV
Handle to the tree view control.
himl
Handle to the image list. If himl is NULL, the message removes the specified image list from the tree view control.
iImage
Type of image list to set. It is one of the following values:
Value
Description
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item’s selected or nonselected image.

Return Values

The HIMAGELIST handle to the previous image list, if any, indicates success. NULL indicates failure.

See Also

TreeView_GetImageList, TVM_GETIMAGELIST


TreeView_SetIndent

This macro sets the width of indentation for a tree-view control and redraws the control to reflect the new width. You can use this macro or send the TVM_SETINDENT message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SETINDENT

Syntax

BOOL TreeView_SetIndent( hwnd, indent);

Parameters

hwndTV
Handle to the tree view control.
indent
Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Values

The return value is not used.


TreeView_SetItem

This macro sets some or all of a tree-view item’s attributes. You can use this macro or send the TVM_SETITEM message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SETITEM

Syntax

BOOL TreeView_SetItem( hwnd, pitem);

Parameters

hwndTV
Handle to the tree view control.
pitem
Pointer to a TVITEM structure that contains the new item attributes. The hItem member identifies the item, and the mask member specifies which attributes to set.

If mask specifies the TVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states to change and the state member contains the values for those states.

Return Values

Zero indicates success. -1 indicates failure.


TreeView_SortChildren

This macro sorts the child items of the specified parent item in a tree-view control. You can use this macro or send the TVM_SORTCHILDREN message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SORTCHILDREN

Syntax

BOOL TreeView_SortChildren( hwnd, hitem, fReserved);

Parameters

hwndTV
Handle to the tree view control.
hitem
Handle to the parent item whose child items are to be sorted.
fRecurse
Reserved for future use; set to zero.

Return Values

TRUE indicates success. FALSE indicates failure.


TreeView_SortChildrenCB

This macro sorts tree-view items using an application-defined callback function that compares the items. You can use this macro or send the TVM_SORTCHILDRENCB message explicitly.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later
Related message: | TVM_SORTCHILDRENCB

Syntax

BOOL TreeView_SortChildrenCB( hwnd, psort, fRecurse);

Parameters

hwndTV
Handle to the tree view control.
psort
Pointer to a TVSORTCB structure. The lpfnCompare member is the address of the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TVSORTCB.
fRecurse
Reserved for future use; set to zero.

Return Values

TRUE indicates success. FALSE indicates failure.


Virtual-Key Codes

The following table shows the symbolic constant names, hexadecimal values, and keyboard equivalents for the virtual-key codes used by the Microsoft Windows CE operating system. The codes are listed in numeric order.

Virtual-Key Codes
Symbolic constant name
Value (hexadecimal)
Touch screen or keyboard equivalent
VK_LBUTTON | 01 | Touch screen
VK_CANCEL | 03 | Control-break processing
—— 05-07 Undefined
VK_BACK | 08 | BACKSPACE key
VK_TAB | 09 | TAB key
—— 0A-0B Undefined
VK_CLEAR | 0C | CLEAR key
VK_RETURN | 0D | ENTER key
—— 0E-0F Undefined
VK_SHIFT | 10 | SHIFT key
VK_CONTROL | 11 | CTRL key
VK_MENU | 12 | ALT key
VK_CAPITAL | 14 | CAPS LOCK key
—— 15-19 Reserved for Kanji systems
—— 1A Undefined
VK_ESCAPE | 1B | ESC key
—— 1C-1F Reserved for Kanji systems
VK_SPACE | 20 | SPACEBAR key
VK_PRIOR | 21 | PAGE UP key
VK_NEXT | 22 | PAGE DOWN key
VK_END | 23 | END key
VK_HOME | 24 | HOME key
VK_LEFT | 25 | LEFT ARROW key
VK_UP | 26 | UP ARROW key
VK_RIGHT | 27 | RIGHT ARROW key
VK_DOWN | 28 | DOWN ARROW key
VK_SELECT | 29 | SELECT key
—— 2A Original equipment manufacturer (OEM)– specific
VK_EXECUTE | 2B | EXECUTE key
VK_SNAPSHOT | 2C | PRINT SCREEN key for Windows 3.0 and later
VK_HELP | 2F | HELP key
VK_0 | 30 | 0 key
VK_1 | 31 | 1 key
VK_2 | 32 | 2 key
VK_3 | 33 | 3 key
VK_4 | 34 | 4 key
VK_5 | 35 | 5 key
VK_6 | 36 | 6 key
VK_7 | 37 | 7 key
VK_8 | 38 | 8 key
VK_9 | 39 | 9 key
—— 3A-40 Undefined
VK_A | 41 | A key
VK_B | 42 | B key
VK_C | 43 | C key
VK_D | 44 | D key
VK_E | 45 | E key
VK_F | 46 | F key
VK_G | 47 | G key
VK_H | 48 | H key
VK_I | 49 | I key
VK_J | 4A | J key
VK_K | 4B | K key
VK_L | 4C | L key
VK_M | 4D | M key
VK_N | 4E | N key
VK_O | 4F | O key
VK_P | 50 | P key
VK_Q | 51 | Q key
VK_R | 52 | R key
VK_S | 53 | S key
VK_T | 54 | T key
VK_U | 55 | U key
VK_V | 56 | V key
VK_W | 57 | W key
VK_X | 58 | X key
VK_Y | 59 | Y key
VK_Z | 5A | Z key
—— 5B-5F Undefined
VK_NUMPAD0 | 60 | Numeric keypad 0 key
VK_NUMPAD1 | 61 | Numeric keypad 1 key
VK_NUMPAD2 | 62 | Numeric keypad 2 key
VK_NUMPAD3 | 63 | Numeric keypad 3 key
VK_NUMPAD4 | 64 | Numeric keypad 4 key
VK_NUMPAD5 | 65 | Numeric keypad 5 key
VK_NUMPAD6 | 66 | Numeric keypad 6 key
VK_NUMPAD7 | 67 | Numeric keypad 7 key
VK_NUMPAD8 | 68 | Numeric keypad 8 key
VK_NUMPAD9 | 69 | Numeric keypad 9 key
VK_MULTIPLY | 6A | Asterisk (*) key
VK_ADD | 6B | Plus sign (+) key
VK_SEPARATOR | 6C | Separator key
VK_SUBTRACT | 6D | Minus sign (–) key
VK_DECIMAL | 6E | Period (.) key
VK_DIVIDE | 6F | Slash mark (/) key
—— 88-8F Unassigned
—— 92-B9 Unassigned
—— BA-C0 OEM-specific
—— C1-DA Unassigned
—— DB-E4 OEM-specific
—— E5 Unassigned
—— E6 OEM-specific
—— E7-E8 Unassigned
—— E9-F5 OEM-specific
VK_ATTN | F6
VK_CRSEL | F7
VK_EXSEL | F8
VK_EREOF | F9
VK_PLAY | FA
VK_ZOOM | FB
VK_NONAME | FC
VK_PA1 | FD
VK_EM_CLEAR | FE
VK_LWIN | 5B
VK_RWIN | 5C
VK_APPS | 5D
VK_LSHIFT | A0
VK_RSHIFT | A1
VK_LCONTROL | A2
VK_RCONTROL | A3
VK_LMENU | A4
VK_RMENU | A5


accept

This function accepts a connection on a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

SOCKET accept(SOCKET s, struct sockaddr *addr, int *addrlen);

Parameters

s
[in] Descriptor that identifies a socket that has been placed in a listening state with the listen function. The connection is actually made with the socket that is returned by accept.
addr
[out] Optional pointer to a buffer that receives the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family established when the socket was created. Set to NULL for IrSocket implementation.
addrlen
[out] Optional pointer to an integer that contains the length of the address addr. Set to NULL for IrSocket implementation.

Return Values

The return value is a handle for the socket on which the actual connection is made. INVALID_SOCKET indicates failure. To get a specific error value, call WSAGetLastError. The following table shows common error values.

Value
Description
WSANOTINITIALISED | A successful WSAStartup must occur before calling accept.
WSAENETDOWN | The network subsystem has failed.
WSAEFAULT | The addrlen parameter is too small or addr is not a valid part of the user address space.
WSAEINPROGRESS | A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL | The listen function was not invoked prior to accept.
WSAEMFILE | The queue is nonempty upon entry to accept and there are no descriptors available.
WSAENOBUFS | No buffer space is available.
WSAENOTSOCK | The descriptor is not a socket.
WSAEOPNOTSUPP | The referenced socket is not a type that supports connection-oriented service.
WSAEWOULDBLOCK | The socket is marked as nonblocking and no connections are present to be accepted.

Windows CE does not support the WSAEINTR error value.

The integer referred to by addrlen initially contains the amount of space pointed to by addr. On return it contains the actual length in bytes of the address returned.

Remarks

For Infrared Sockets (IrSock), set the addr and addrlen parameters to NULL.

The accept function extracts the first connection on the queue of pending connections on socket s. It then creates a new socket and returns a handle to the new socket. The newly created socket is the socket that will handle the actual connection and has the same properties as socket s. The newly created socket s does not have the listening socket’s group identifier, if any was applied.

The accept function can block the caller until a connection is present if no pending connections are present on the queue, and the socket is marked as blocking. If the socket is marked nonblocking and no pending connections are present on the queue, accept returns the WSAEWOULDBLOCK error value. The socket handle returned from a successful accept call cannot be used to accept further connections. The original socket remains open to listen for new connection requests.

The parameter addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned.

The accept function is used with connection-oriented socket types such as SOCK_STREAM.

If addr and/or addrlen are equal to NULL, then no information about the remote address of the accepted socket is returned.

See Also

bind, connect, listen, select, socket


AcceptSecurityContext

This function enables the server component of a transport application to establish a security context between the server and a remote client. The remote client uses the InitializeSecurityContext function to start the process of establishing a security context. The server may need one or more reply tokens from the remote client to complete the establishment of the security context.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS AcceptSecurityContext( PCredHandle phCredential,
PCtxtHandle phContext, PSecBufferDesc pInput, ULONG fContextReq,
ULONG TargetDataRep, PCtxtHandle phNewContext,
PSecBufferDesc pOutput, PULONG pfContextAttr, PTimeStamp ptsExpiry );

Parameters

phCredential
[in] Pointer to the handle to the server's credentials. The server calls the AcquireCredentialsHandle function to retrieve this handle.
phContext
[in] Pointer to the handle of a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer is NULL. On the second call, this is the handle to the partially formed context that was returned in the phNewContext parameter by the first call.
pInput
[in] Pointer to a SecBufferDesc structure that contains the input buffer descriptor. Depending on the security package, this parameter may be NULL if no initial token is ready.
fContextReqs
[in] Set of bit flags that specify the attributes that the server requires for the context to be established. This value can include a combination of the following flags:
ASC_REQ_ALLOCATE_MEMORY | ASC_REQ_INTEGRITY
ASC_REQ_CALL_LEVEL | ASC_REQ_MUTUAL_AUTH
ASC_REQ_CONFIDENTIALITY | ASC_REQ_REPLAY_DETECT
ASC_REQ_CONNECTION | ASC_REQ_STREAM
ASC_REQ_DATAGRAM | ASC_REQ_SEQUENCE_DETECT
ASC_REQ_DELEGATE | ASC_REQ_USE_DCE_STYLE
ASC_REQ_EXTENDED_ERROR | ASC_REQ_USE_SESSION_KEY

TargetDataRep
[in] Indicates the data representation (byte ordering, and so on) on the target. You can specify SECURITY_NATIVE_DREP to indicate that the native format is in use.
phNewContext
[out] Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer receives the new context handle. On the second call, this parameter can be the same as the handle specified in the phContext parameter.
pOutput
[in] Pointer to a SecBufferDesc structure that contains the output buffer descriptor.
pfContextAttributes
[out] Pointer to a variable that receives a set of bit flags indicating the attributes of the established context. For more information about context requirements, see Cryptography. This value can include any of the following flags:
ASC_RET_ALLOCATED_MEMORY | ASC_RET_MUTUAL_AUTH
ASC_RET_CALL_LEVEL | ASC_RET_REPLAY_DETECT
ASC_RET_CONFIDENTIALITY | ASC_RET_SEQUENCE_DETECT
ASC_RET_CONNECTION | ASC_RET_STREAM
ASC_RET_DATAGRAM | ASC_RET_USED_DCE_STYLE
ASC_RET_DELEGATE | ASC_RET_USE_SESSION_KEY
ASC_RET_EXTENDED_ERROR | ASC_RET_THIRD_LEG_FAILED
ASC_RET_INTEGRITY

ptsExpiry
[out] Pointer to a PTimeStamp variable that receives the expiration time of the context. The security provider should always return this value in local time.

Return Values

Upon success, one of the values described in the following table is returned.

Value
Description
SEC_E_OK The security context was successfully established.
SEC_I_CONTINUE_NEEDED
SEC_I_COMPLETE_NEEDED
SEC_I_COMPLETE_AND_CONTINUE

Upon failure, one of the error values described in the following table is returned.

Value
Description
SEC_E_INVALID_TOKEN | The token passed to the function is invalid.
SEC_E_INVALID_HANDLE | The handle passed to the function is invalid.
SEC_E_LOGON_DENIED | The logon failed.
SEC_E_INTERNAL_ERROR | The Local Security Authority cannot be contacted.
SEC_E_NO_AUTHENTICATING_AUTORITY | No authority could be contacted for authentication.

Remarks

The AcceptSecurityContext function is the server counterpart to the InitializeSecurityContext function.

When a request comes in, the server uses the fContextReq parameter to specify what it requires of the session. In this fashion, a server can specify that clients must be capable of using a confidential or integrity-checked session, and it can fail clients that cannot meet that demand. As an alternative, a server can require nothing, and whatever the client can provide or requires is returned in the pfContextAttr parameter.

For a package that supports three-leg mutual authentication, the calling sequence is as follows:

  • The client transmits a token to the server.
  • The server calls AcceptSecurityContext the first time, generating a reply token.
  • The client passes this token in a second call to InitializeSecurityContext, which generates a final token.
  • The server uses this token in the final call to AcceptSecurityContext to complete the session.

LAN Manager and Windows NT use another authentication style.

  • The client connects to negotiate a protocol.
  • The server calls AcceptSecurityContext to set up a context and generate a challenge to the client.
  • The client calls InitializeSecurityContext and creates the response.
  • The server then calls AcceptSecurityContext the final time to allow the security package to verify that the response is appropriate for the challenge.

See Also

InitializeSecurityContext


AcquireCredentialsHandle

This function allows applications to acquire a handle to preexisting credentials associated with the user on whose behalf the call is made. These preexisting credentials are established through a system logon not described here. However, this is different from “login to the network” and does not imply gathering of credentials.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS AcquireCredentialsHandle(
SEC_CHAR * pszPrincipal, SEC_CHAR * pszPackage,
ULONG fCredentialUse, PLUID pvLogonID, PVOID pAuthData,
PVOID pGetKeyFn, VOID pvGetKeyArgument, PCredHandle phCredential,
PTimeStamp ptsExpiry );

Parameters

pszPrincipal
[in] Pointer to a null-terminated string that specifies the name of the principal whose credentials the handle will reference. Note that if the process requesting the handle does not have access to the credentials, the function returns an error. A null string indicates that the process requires a handle to the credentials of the user under whose security context it is executing.
pszPackage
[in] Pointer to a null-terminated string that specifies the name of the security package with which these credentials will be used. This is a security package name returned in the Name member of a SecPkgInfo structure returned by the EnumerateSecurityPackages function.
fCredentialUse
[in] Flag that indicates how these credentials will be used. This parameter can one of the following values:
  • CRED_INBOUND
  • CRED_OUTBOUND
  • CRED_BOTH

The credentials created with the CRED_INBOUND option can be used only for validating incoming calls. They cannot be used for accessing objects.

pvLogonId
[in] Void pointer to a Windows NT–style logon identifier, an LUID. This parameter is provided for file-system processes such as network redirectors. This parameter can be NULL.
pAuthData
[in] Pointer to package-specific data. This parameter can be NULL, indicating that the default credentials for that package should be used. The NTLM SSP accepts a pointer to a SEC_WINNT_AUTH_IDENTITY structure, containing the user name, domain name and password.
pGetKeyFn
[in] Pointer to a SEC_GET_KEY_FN function to retrieve the key for the function. The security package can call this function, as provided by the RPC run-time transport application. This parameter can be NULL if the transport application does not support callbacks to retrieve credentials.
pvGetKeyArgument
[in] Specifies the pointer argument that the security provider should pass to the GetKey function. This parameter can be NULL.
phCredential
[out] Pointer to CredHandle structure that receives the credential handle.
ptsExpiry
[out] Pointer to a TimeStamp variable that receives the time at which the returned credentials expire. The value returned in this member depends on the security package. The security provider should always return this value in local time.

Return Values

SEC_E_OK indicates success.

Upon failure, one of the error values described in the following table is returned.

Value
Description
SEC_E_UNKNOWN_CREDENTIALS | The credentials supplied to the package were not recognized.
SEC_E_NO_CREDENTIALS | No credentials are available in the security package.
SEC_E_NOT_OWNER | The caller of the function does not own the necessary credentials.
SEC_E_INSUFFICIENT_MEMORY | Not enough memory is available to complete this request.
SEC_E_INTERNAL_ERROR | The Local Security Authority cannot be contacted.
SEC_E_SECPKG_NOT_FOUND | The requested security package does not exist.

Remarks

The AcquireCredentialsHandle function returns a handle to the credentials of a principal (user, client) as used by a specific security package. The handle returned can be used in subsequent calls to the AcceptSecurityContext and InitializeSecurityContext functions.

The AcquireCredentialsHandle function will not let a process obtain a handle to credentials that are not related to the process; in other words, a process cannot get the credentials of another user who is logged on to the same computer. There is no way to determine whether a process is a Trojan horse if it is executed by the user.

The AcquireCredentialsHandle function uses the following algorithm to determine whether to grant the request for a handle to the credentials.

When you no longer need the returned credentials, call the FreeCredentialsHandle function.

See Also

FreeCredentialsHandle


ApplyControlToken

This function provides a way to apply a control token to a security context. A token can be received when the security context is being established by means of InitializeSecurityContext, or with a per-message security service, such as verify or unseal.

This function also allows additional or replacement tokens to be applied to a context.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS ApplyControlToken( PCtxtHandle phContext,
PSecBufferDesc pInput );

Parameters

phContext
[in] Pointer to the handle to the context to which the token is applied.
pInput
[in] Pointer to a SecBufferDesc structure with a pointer to a SecBuffer structure that contains the input token to apply to the context.

Return Values

SEC_E_OK indicates success. A nonzero error value indicates failure.

Remarks

The ApplyControlToken function may modify the context based on this token.

See Also

SecBufferDesc


bind

This function associates a local address with a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int bind(SOCKET s, const struct sockaddr *addr, int namelen);

Parameters

s
[in] Descriptor that identifies an unbound socket.
name
[in] Address to assign to the socket from the SOCKADDR structure.
namelen
[in] Length of the name.

Return Values

Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:

  • The Af_irda.h must be explicitly included.
  • The sockaddr_irda structure is used in the addr parameter.
  • The WSAENETDOWN error value is not supported.
  • There is no wildcard address equivalent to INADDR_ANY.
  • IrSockets clients must not call bind.
  • If the service name is of the form “LSAP-SELXXX” where XXX is a decimal integer in the range 1-127, the address indicates a specific LSAP-SEL. LSAP-SELXXX service names will cause no IAS calls. The socket will be bound directly to the specified LSAP-SEL, bypassing IAS. Windows CE reserves LSAP-SEL0 for IAS and LSAP-SEL3 for internal use.

The bind function is used on an unconnected socket before subsequent calls to the connect or listen functions. It is used to bind to either connection-oriented (stream) or connectionless (datagram) sockets. When a socket is created with a call to the socket function, it exists in a name space (address family), but it has no name assigned to it. Use the bind function to establish the local association of the socket by assigning a local name to an unnamed socket.

A name consists of three parts when using the Internet address family: the address family, a host address, and a port number that identifies the application.

If an application does not care what local address is assigned, specify the manifest constant value ADDR_ANY for the sa_data member of the name parameter. This allows the underlying service provider to use any appropriate network address, potentially simplifying application programming in the presence of multihomed hosts (that is, hosts that have more than one network interface and address).

For TCP/IP, if the port is specified as zero, the service provider assigns a unique port to the application with a value between 1024 and 5000. The application can use getsockname after calling bind to learn the address and the port that has been assigned to it. If the Internet address is equal to INADDR_ANY, getsockname may not necessarily supply the address until the socket is connected, since several addresses can be valid if the host is multihomed. Binding to a specific port number other than port 0 is discouraged for client applications, since there is a danger of conflicting with another socket already using that port number.

See Also

connect, listen, getsockname, setsockopt, socket, SOCKADDR, SOCKADDR_IN, SOCKADDR_IRDA


ClearCommBreak

This function restores character transmission for a specified communications device and places the transmission line in a nonbreak state.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ClearCommBreak(HANDLE hFile);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

A communications device is placed in a break state by the SetCommBreak or EscapeCommFunction function. Character transmission is then suspended until the break state is cleared by calling ClearCommBreak.

See Also

ClearCommError, CreateFile, EscapeCommFunction, SetCommBreak


ClearCommError

This function retrieves information about a communications error and reports the current status of a communications device. The function is called when a communications error occurs, and it clears the error flag of the device to enable additional input and output (I/O) operations.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ClearCommError(HANDLE hFile, LPDWORD lpErrors, LPCOMSTAT lpStat);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
lpErrors
[out] Long pointer to a 32-bit variable to be filled with a mask indicating the type of error. This parameter can be one or more of the following error codes:
Error code
Description
CE_BREAK | The hardware detected a break condition.
CE_FRAME | The hardware detected a framing error.
CE_IOE | An I/O error occurred during communications with the device.
CE_MODE | The requested mode is not supported, or the hFile parameter is invalid. If this value is specified, it is the only valid error.
CE_OVERRUN | A character-buffer overrun has occurred. The next character is lost.
CE_RXOVER | An input buffer overflow has occurred. There is either no room in the input buffer, or a character was received after the end-of-file (EOF) character.
CE_RXPARITY | The hardware detected a parity error.
CE_TXFULL | The application tried to transmit a character, but the output buffer was full.

lpStat
[out] Long pointer to a COMSTAT structure in which the device’s status information is returned. If lpStat is NULL, no status information is returned.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If a communications port has been set up with a TRUE value for the fAbortOnError member of the setup DCB structure, the communications software will terminate all read and write operations on the communications port when a communications error occurs. No new read or write operations will be accepted until the application acknowledges the communications error by calling the ClearCommError function.

The ClearCommError function fills the status buffer pointed to by the lpStat parameter with the current status of the communications device specified by the hFile parameter.

Windows CE does not support the CE_DNS, CE_OPP, and CE_PTO error codes.

See Also

ClearCommBreak, COMSTAT, CreateFile, DCB


closesocket

This function closes a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int closesocket (SOCKET s);

Parameters

s
[in] Descriptor that identifies a socket to close.

Return Values

Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Windows CE does not support the WSAEINTR error value.

Remarks

For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:

  • The Af_irda.h file must be explicitly included.
  • The WSAENETDOWN error value is not supported.
  • The standard linger options are supported.

    Although IrDA does not provide a graceful close, IrSock defers closing until the receive queues are purged. Thus, an application can send data and immediately call the closesocket function confident that the receiver will copy the data before receiving an FD_CLOSE message.

The closesocket function closes a socket. Use it to release the socket descriptor s so that further references to s will fail with the error WSAENOTSOCK. Any pending blocking or asynchronous calls issued by any thread in this process are canceled without posting any notification messages.

An application should always have a matching call to closesocket for each successful call to socket to return any socket resources to the system.

The semantics of closesocket are affected by the socket options SO_LINGER and SO_DONTLINGER as follows (SO_DONTLINGER is enabled by default; SO_LINGER is disabled).

Option
Interval
Type of close
Wait for close?
SO_DONTLINGER | Do not care | Graceful | No
SO_LINGER | Zero | Hard | No
SO_LINGER | Nonzero | Graceful | Yes

If SO_LINGER is set with a zero time-out interval (that is, the LINGER structure members l_onoff is not zero and l_linger is zero), closesocket is not blocked even if queued data has not yet been sent or acknowledged. This is called a hard or abortive close, because the socket's virtual circuit is reset immediately, and any unsent data is lost. Any recv call on the remote side of the circuit will fail with WSAECONNRESET.

If SO_LINGER is set with a nonzero time-out interval on a blocking socket, the closesocket call blocks on a blocking socket until the remaining data has been sent or until the time-out expires. This is called a graceful disconnect. If the time-out expires before all data has been sent, the Windows Sockets implementation terminates the connection before closesocket returns.

Enabling SO_LINGER with a nonzero time-out interval on a nonblocking socket is not recommended. In this case, the call to closesocket will fail with an error of WSAEWOULDBLOCK if the close operation cannot be completed immediately. If closesocket fails with WSAEWOULDBLOCK the socket handle is still valid, and a disconnect is not initiated. The application must call closesocket again to close the socket. If SO_DONTLINGER is set on a stream socket by setting the l_onoff member of the LINGER structure to zero, the closesocket call will return immediately and does not receive WSAWOULDBLOCK whether the socket is blocking or nonblocking. However, any data queued for transmission will be sent, if possible, before the underlying socket is closed. This is also called a graceful disconnect. In this case, the Windows Sockets provider cannot release the socket and other resources for an arbitrary period, thus affecting applications that expect to use all available sockets. This is the default behavior (SO_DONTLINGER is set by default).

Note To assure that all data is sent and received on a connection, an application should call shutdown before calling closesocket. Also note, an FD_CLOSE network event is not posted after closesocket is called.

Here is a summary of closesocket behavior:

  • If SO_DONTLINGER enabled (the default setting) it always returns immediately – connection is gracefully closed in the background.
  • If SO_LINGER enabled with a zero time-out: it always returns immediately - connection is reset/terminated.
  • If SO_LINGER enabled with nonzero time-out:
    • with blocking socket it blocks until all data sent or time-out expires.
    • with nonblocking socket it returns immediately that indicates failure.

For additional information please see Graceful shutdown, linger options, and socket closure for more information.

See Also

accept, socket, ioctlsocket, setsockopt


CommitUrlCacheEntry

This function stores data in the specified file in the Internet cache and associates it with the given URL.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL CommitUrlCacheEntry ( LPCTSTR lpszUrlName,
LPCTSTR lpszLocalFileName, FILETIME ExpireTime,
FILETIME LastModifiedTime, DWORD CacheEntryType,
LPBYTE lpHeaderInfo, DWORD dwHeaderSize,
LPCTSTR lpszFileExtension, DWORD dwReserved);

Parameters

lpszUrlName
[in] Address of a string variable that contains the source name of the cache entry. The name string must be unique and should not contain any escape characters.
lpszLocalFileName
[in] Address of a string variable that contains the name of the local file that is being cached. This should be the same name as that returned by CreateUrlCacheEntry.
ExpireTime
[in] FILETIME structure that contains the expire date and time (in Greenwich mean time) of the file that is being cached. If the expire date and time is unknown, set this parameter to zero.
LastModifiedTime
[in] FILETIME structure that contains the last modified date and time (in Greenwich mean time) of the URL that is being cached. If the last modified date and time is unknown, set this parameter to zero.
CacheEntryType
[in] Unsigned long integer value that contains the cache type bitmask. Currently, the cache entry type values have not been finalized, so this value does not serve a real purpose at this point, except for STICKY_CACHE_ENTRY. This can be a combination of the following values:
COOKIE_CACHE_ENTRY | TRACK_CACHE_ENTRY
EDITED_CACHE_ENTRY | TRACK_OFFLINE_CACHE_ENTRY
NORMAL_CACHE_ENTRY | TRACK_ONLINE_CACHE_ENTRY
SPARCE_CACHE_ENTRY | URLHISTORY_CACHE_ENTRY
STICKY_CACHE_ENTRY

lpHeaderInfo
[in] Address of the buffer containing the header information. If this parameter is not NULL, the header information is treated as extended attributes of the URL and is returned in the INTERNET_CACHE_ENTRY_INFO structure.
dwHeaderSize
[in] Unsigned long integer value that contains the size of the header information. If lpHeaderInfo is not NULL, this value is assumed to indicate the size of the buffer that will store the header information. An application can maintain headers as part of the data and provide dwHeaderSize together with a NULL value for lpHeaderInfo.
lpszFileExtension
[in] Address of a buffer that contains information maintained in the cache database for future use.
dwReserved
[in] Reserved. Must be set to zero.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the cache storage is full, this function invokes cache cleanup to make space for this new file. If the cache entry already exists, the function overwrites the entry if it is not in use. An entry is in use when it has been retrieved with RetrieveUrlCacheEntryFile.

Clients that add entries to the cache should set the headers to at least "HTTP/1.0 200 OK\r\n\r\n"; otherwise, client applications which use the Win32 Internet functions may disregard the entry.

See Also

CreateUrlCacheEntry , DeleteUrlCacheEntry


CompleteAuthToken

This function completes an authentication token. This function is used by protocols, like the Distributed Computing Environment (DCE), that need to revise the security information after the transport application has updated some message parameters.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS CompleteAuthToken( PCtxtHandle phContext,
PSecBufferDesc pToken);

Parameters

phContext
Pointer to the handle of the context that needs to be completed.
pToken
Pointer to a SecBufferDesc structure that contains the buffer descriptor for the entire message.

Return Values

SEC_E_OK indicates success.

Upon failure, one of the error values described in the following table is returned.

Value
Description
SEC_E_INVALID_HANDLE | The handle passed to the function is invalid.
SEC_E_INVALID_TOKEN | The token pased to the function is invalid.
SEC_E_INTERNAL_ERROR

Remarks

The client of a transport application calls the CompleteAuthToken function to allow the security package to update a checksum or similar operation after all the protocol headers have been updated by the transport application. The client should call this function only if the InitializeSecurityContext call returned SEC_I_COMPLETE_NEEDED or SEC_I_COMPLETE_AND_CONTINUE.

See Also

InitializeSecurityContext


connect

This function establishes a connection to a peer.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int connect (SOCKET s, const struct sockaddr *name, int namelen);

Parameters

s
[in] Descriptor that identifies an unconnected socket.
name
[in] Name of the socket to connect to.
namelen
[in] Length of the name parameter.

Return Values

Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Windows CE does not support the WSAEINTR error value.

On a blocking socket, the return value indicates success or failure of the connection attempt.

With a nonblocking socket, the connection attempt cannot be completed immediately. In this case, connect will return SOCKET_ERROR, and WSAGetLastError will return WSAEWOULDBLOCK. In this case, use the select function to determine the completion of the connection request by checking to see if the socket is writeable.

Until the connection attempt completes on a nonblocking socket, all subsequent calls to connect on the same socket will fail with the error value WSAEALREADY, and WSAEISCONN when the connection completes successfully. Due to ambiguities the Windows Sockets Specification 1.1, error values returned from connect while a connection is already pending may vary among implementations. As a result, it is not recommended that applications use multiple calls to connect to detect connection completion. If they do, they must be prepared to handle WSAEINVAL and WSAEWOULDBLOCK error values the same way that they handle WSAEALREADY, to assure robust execution.

If the error value returned indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application can call connect again for the same socket.

Remarks

For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:

  • The Af_irda.h file must be explicitly included.
  • If WSAENETDOWN is returned, an existing IrDA connection was detected at the media access level.
  • If WSAEADDRINUSE is returned, active connections to a device with a different address exist.
  • If WSAEINPROGRESS is returned, IAS name resolution failed because another IAS query is in progress. Retry the operation at one second intervals.
  • If WSAEISCONN is returned, the socket is already connected or an exclusive/multiplexed mode change failed.

IrSock implements the connect function with addresses of the form sockaddr_irda. Typically, a client application will create a socket with the socket function, scan the immediate vicinity for IrDA devices with the IRLMP_ENUMDEVICES socket option, choose a device from the returned list, form an address, and call connect. There is no difference in blocking and non-blocking semantics.

The connect function is used to create a connection to the specified destination. If the socket, s, is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound.

For connection-oriented sockets (for example, type SOCK_STREAM), an active connection is initiated to the foreign host using name (an address in the name space of the socket; for a detailed description, please see bind and SOCKADDR). When the socket call completes successfully, the socket is ready to send and receive data. If the address member of the structure specified by the name parameter is all zeroes, connect will return the error WSAEADDRNOTAVAIL. Any attempt to re-connect an active connection will fail with the error value WSAEISCONN.

For connection-oriented, nonblocking sockets, it is often not possible to complete the connection immediately. In such a case, this function returns the error WSAEWOULDBLOCK. However, the operation proceeds. When the success or failure outcome becomes known and the client uses the select function, success is reported in the writefds set and failure is reported in the exceptfds set.

For a connectionless socket (for example, type SOCK_DGRAM), the operation performed by connect is merely to establish a default destination address that can be used on subsequent send and recv calls. Any datagrams received from an address other than the destination address specified will be discarded. If the address member of the structure specifed by name is all zeroes, the socket will be disconnected. Then, the default remote address will be indeterminate, so send and recv calls will return the error value WSAENOTCONN. However, sendto and recvfrom can still be used. The default destination can be changed by simply calling connect again, even if the socket is already connected. Any datagrams queued for receipt are discarded if name is different from the previous connect.

For connectionless sockets, name can indicate any valid address, including a broadcast address. However, to connect to a broadcast address, a socket must use setsockopt to enable the SO_BROADCAST option. Otherwise, connect will fail with the error value WSAEACCES.

When a connection between sockets is broken, the sockets should be discarded and recreated. When a problem develops on a connected socket, the application must discard and recreate the needed sockets in order to return to a stable point.

See Also

accept, bind, getsockname, recv, socket, select, send


CreateUrlCacheEntry

This function creates a local file name for saving the cache entry based on the specified URL and the file extension.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL CreateUrlCacheEntry ( LPCTSTR lpszUrlName,
DWORD dwExpectedFileSize, LPCTSTR lpszFileExtension,
LPSTR lpszFileName, DWORD dwReserved);

Parameters

lpszUrlName
[in] Address of a string variable that contains the source name of the cache entry. The name string must be unique and should not contain any escape characters.
dwExpectedFileSize
[in] Unsigned long integer value that contains the expected size of the file needed to store the data corresponding to the source entity. If the expected size is unknown, set this value to zero.
lpszFileExtension
[in] Address of a buffer that contains information maintained in the cache database for future use.
lpszFileName
[out] Address of a buffer that receives the file name. The buffer should be large enough (MAX_PATH) to store the path of the created file.
dwReserved
[in] Reserved. Must be set to zero.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

After this function is called, the application can write directly into the file in local storage. When the file is completely received, you should call CommitUrlCacheEntry to commit the entry in the cache.

See Also

CommitUrlCacheEntry , DeleteUrlCacheEntry


CreateUrlCacheGroup

This function generates cache group identifications.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

GROUPID CreateUrlCacheGroup ( DWORD dwFlags,
LPVOID lpReserved);

Parameters

dwFlags
[in] Unsigned long integer value that contains the flags to control the creation of the cache group. This can be set to CACHEGROUP_FLAG_GIDONLY, which generates a unique GROUPID, but does not create a physical group.
lpReserved
[in] Reserved. Must be set to NULL.

Return Values

Returns a valid GROUPID if successful, or FALSE otherwise.

See Also

DeleteUrlCacheGroup


CryptAcquireContext

This function is used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned handle can then be used to make calls to the selected CSP.

This function performs two operations. It first attempts to find a CSP with the characteristics described in the dwProvType and pszProvider parameters. If the CSP is found, then the function attempts to find a key container within the CSP matching the name specified by the pszContainer parameter.

This function can also be used to create and destroy key containers, depending on the value of the dwFlags parameter.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOLEAN CRYPTFUNC CryptAcquireContext (HCRYPTPROV *phProv,
LPCTSTR pszContainer, LPCTSTR pszProvider, DWORD dwProvType,
DWORD dwFlags );

Parameters

phProv
[out] Address to which the function copies a handle to the CSP.
pszContainer
[in] Pointer to the null-terminated string that contains the key container name, which identifies the key container to the CSP. This name is independent of the method used to store the keys. Some CSPs will store their key containers internally (in hardware), some will use the system registry, and others will use the file system. pszContainer is to be set to NULL when dwFlags is set to CRYPT_VERIFYCONTEXT.

If this parameter is NULL, then a default key container name will be used.

An application can obtain the name of the acquired key container at a later time by reading the PP_CONTAINER CSP parameter with the CryptGetProvParam function.

pszProvider
[in] Pointer to the null-terminated string that contains the provider name, which specifies the CSP to be used.

If this parameter is NULL then the user default provider is used. For more information about connecting to CSPs, see Cryptography.

An application can obtain the name of the acquired CSP at a later time by reading the PP_NAME CSP parameter with the CryptGetProvParam function.

dwProvType
[in] Specifies the type of provider to acquire. The following provider types are predefined.
PROV_RSA_FULL | PROV_SSL
PROV_RSA_SIG | PROV_EC_ECDSA_SIG
PROV_DSS | PROV_EC_ECNRA_SIG
PROV_DSS_DH | PROV_EC_ECDSA_FULL
PROV_FORTEZZA | PROV_EC_ECNRA_FULL
PROV_MS_EXCHANGE | PROV_SPYRUS_LYNKS
PROV_RSA_SCHANNEL

dwFlags
[in] Specifies a bitmask of flags. This parameter is normally set to zero, but some applications set one or more of the following flags:
Flag
Description
CRYPT_VERIFYCONTEXT. | If this flag is set, then the application will have no access to the private keys and the pszContainer parameter must be set to NULL.
This option is intended to be used with applications that will not be using private keys.
When CryptAcquireContext is called, many CSPs will require input from the owning user before granting access to the private keys in the key container. For example, the private keys may be encrypted, requiring a password from the user before they can be used. However, if the CRYPT_VERIFYCONTEXT flag is specified, access to the private keys is not required and the user interface can be bypassed.
CRYPT_NEWKEYSET. | If this flag is set, then a new key container will be created with the name specified by pszContainer. If pszContainer is NULL, then a key container with the default name will be created. See CRYPT_MACHINE_KEYSET for information on combining flags.
CRYPT_MACHINE_KEYSET. | By default, keys are stored for the current user. The CRYPT_MACHINE_KEYSET flag can be set and combined with all of the other flags to indicate that the keys are persisted for the computer and not for any particular user. Combined with the CRYPT_NEWKEYSET flag, the CRYPT_MACHINE_KEYSET flag can access keys for a service.
CRYPT_DELETEKEYSET. | If this flag is set, then the key container specified by pszContainer is deleted. If pszContainer is NULL, then the key container with the default name is deleted. All key pairs in the key container are also destroyed.
When the CRYPT_DELETEKEYSET flag is set, the value returned in phProv is undefined and, thus, the CryptReleaseContext function need not be called afterwards.

Note When key containers are created, most CSPs will not automatically create any public/private key pairs. These keys must be created as a separate step with the CryptGenKey function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory during the operation.
NTE_BAD_FLAGS | The dwFlags parameter has an illegal value.
NTE_BAD_KEYSET | The key container could not be opened and may not exist.
NTE_BAD_KEYSET_PARAM | The pszContainer or pszProvider parameter is set to an illegal value.
NTE_BAD_PROV_TYPE | The value of the dwProvType parameter is out of range. All provider types must be from 1 to 999, inclusive.
NTE_BAD_SIGNATURE | The provider DLL signature could not be verified. Either the DLL or the digital signature has been tampered with.
NTE_EXISTS | The dwFlags parameter is CRYPT_NEWKEYSET, but the key container already exists.
NTE_FAIL | The function failed in some unexpected way.
NTE_KEYSET_ENTRY_BAD | The pszContainer key container was found but is corrupt.
NTE_KEYSET_NOT_DEF | The key container specified by pszContainer does not exist.
NTE_NO_MEMORY | The CSP ran out of memory during the operation.
NTE_PROV_DLL_NOT_FOUND | The provider DLL file does not exist or is not on the current path.
NTE_PROV_TYPE_ENTRY_BAD | The provider type specified by dwProvType is corrupt. This error may relate to either the user default CSP list or the machine default CSP list.
NTE_PROV_TYPE_NO_MATCH | The provider type specified by dwProvType does not match the provider type found. Note that this error can only occur when pszProvider specifies an actual CSP name.
NTE_PROV_TYPE_NOT_DEF | No entry exists for the provider type specified by dwProvType.
NTE_PROVIDER_DLL_FAIL | The provider DLL file could not be loaded, and may not exist. If it exists, then the file is not a valid DLL.
NTE_SIGNATURE_FILE_BAD | An error occurred while loading the DLL file image, prior to verifying its signature.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
BYTE pbData[1000];
DWORD cbData;

// Get a handle to the default PROV_RSA_FULL provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 return;
}

// Read the name of the default CSP.
cbData = 1000;
if(!CryptGetProvParam(hProv, PP_NAME, pbData, &cbData, 0)) {
 printf("Error %x reading CSP name!\n", GetLastError());
 return;
}
printf("Provider name: %s\n", pbData);

// Read the name of the default key container.
cbData = 1000;
if(!CryptGetProvParam(hProv, PP_CONTAINER, pbData, &cbData, 0)) {
 printf("Error %x reading key container name!\n", GetLastError());
 return;
}
printf("Key Container name: %s\n", pbData);

// Perform cryptographic operations.
...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
 printf("Error %x during CryptReleaseContext!\n", GetLastError());
 return;
}

// ****************************************************************

// Get a handle to the Microsoft Base Cryptographic Provider and the
// "KC1" key container.
if(!CryptAcquireContext(&hProv, TEXT("KC1"), MS_DEF_PROV,
 PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 return;
}

// Perform cryptographic operations.
...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
 printf("Error %x during CryptReleaseContext!\n", GetLastError());
 return;
}

// ****************************************************************

// Get a handle to the default provider. Create a new key container
// named "KC2". Note that this key container will be empty until keys
// are explicitly created with the CryptGenKey function.
lstrcpy(szProv, );
lstrcpy(szContainer, );
if(!CryptAcquireContext(&hProv, TEXT("KC2"), NULL, PROV_RSA_FULL,
 CRYPT_NEWKEYSET)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 return;
}

// Perform cryptographic operations.
...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
 printf("Error %x during CryptReleaseContext!\n", GetLastError());
 return;
}

Remarks

Windows CE does not support the ANSI version of this function.

See Also

CryptGenKey, CryptGetProvParam, CryptReleaseContext


CryptContextAddRef

This function is used to add one to the reference count on an HCRYPTPROV handle.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptContextAddRef( HCRYPTPROV hProv,
DWORD *pdwReserved, DWORD dFlags );

Parameters

hProv
[in] HCRYPTPROV handle for which the reference count is being incremented.
pdwReserved
[in] Reserved for future use; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table.

Value
Description
ERROR_INVALID_PARAMETER One of the parameters contains an invalid value. This is most often an illegal pointer.

Remarks

CryptContextAddRef is used to increase the reference count on a HCRYPTPROV handle so that multiple calls to CryptReleaseContext are required to actually release the handle.

Example

HCRYPTPROV hProv = 0;

// Acquire a context handle
if (!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_SIG, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError);
 return;
}

if (!CryptContextAddRef(&hProv, NULL, 0)) {
 printf("Error %x during CryptContextAddRef!\n", GetLastError);
 return;
}

...

// The first call to CryptReleaseContext will not release the provider handle
// since the reference count has been bumped up.
if (!CryptReleaseContext(hProv, 0)) {
 printf("Error %x during CryptReleaseContext!\n", GetLastError);
 return;
}

// Release the provider handle.
if (!CryptReleaseContext(hProv, 0)) {
 printf("Error %x during CryptReleaseContext!\n", GetLastError);
 return;
}

See Also

CryptAcquireContext, CryptReleaseContext


CryptCreateHash

This function is used to initiate the hashing of a stream of data. It returns to the caller a handle to a cryptographic service provider (CSP) hash object. This handle can also be used in subsequent calls to CryptHashData and CryptHashSessionKey in order to hash streams of data and session keys.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptCreateHash ( HCRYPTPROV hProv,
ALG_ID Algid, HCRYPTKEY hKey, DWORD dwFlags,
HCRYPTHASH *phHash );

Parameters

hProv
[in] Handle to the CSP to use. An application obtains this handle by using the CryptAcquireContext function.
Algid
[in] Identifier of the hash algorithm to use.

The valid values for this parameter will vary, depending on the CSP that is used. See the "Remarks" section for the list of default algorithms.

hKey
[in] If the type of hash algorithm is a keyed hash, such as the HMAC or MAC algorithm, the key for the hash should be passed in this parameter. For nonkeyed algorithms, this parameter should be set to zero.

For keyed algorithms, the key must be to a block cipher, such as RC2, that has a cipher mode of CBC.

dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
phHash
[out] Address to which the function copies a handle to the new hash object.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory during the operation.
NTE_BAD_ALGID | The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_KEY | A keyed hash algorithm (such as CALG_MAC) is specified by Algid and the hKey parameter is either zero or it specifies an invalid key handle. This error code will also be returned if the key is to a stream cipher, or if the cipher mode is anything other than CBC.
NTE_NO_MEMORY | The CSP ran out of memory during the operation.

Remarks

The Microsoft Base Cryptographic Provider defines the following hashing algorithms.

Constant
Description
CALG_HMAC | HMAC, a keyed hash algorithm
CALG_MAC | Message Authentication Code
CALG_MD2 | MD2
CALG_MD5 | MD5
CALG_SHA | US DSA Secure Hash Algorithm
CALG_SHA1 | Same as CALG_SHA
CALG_SSL3_SHAMD5 | SSL3 client authentication

The computation of the actual hash is done with the CryptHashData and CryptHashSessionKey functions. These require a handle to the hash object. After all the data has been added to the hash object, any of the following operations can be performed:

  • The hash value can be retrieved by using CryptGetHashParam.
  • A session key can be derived by using CryptDeriveKey.
  • The hash can be signed by using CryptSignHash.
  • A signature can be verified by using CryptVerifySignature.

After one of the functions from this list has been called, CryptHashData and CryptHashSessionKey may not be called.

Example

See CryptHashSessionKey

See Also

CryptAcquireContext, CryptDeriveKey, CryptDestroyHash, CryptGetHashParam, CryptHashData, CryptHashSessionKey, CryptSignHash, CryptVerifySignature


CryptDecrypt

This function is used to decrypt data that was previously encrypted with the CryptEncrypt function.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptDecrypt( HCRYPTKEY hKey,
HCRYPTHASH hHash, BOOL Final, DWORD dwFlags, BYTE *pbData,
DWORD *pdwDataLen );

Parameters

hKey
[in] Handle to the key to use for the decryption. An application obtains this handle by using either the CryptGenKey or CryptImportKey function.

This key specifies the decryption algorithm that is used.

hHash
[in] Handle to a hash object. This parameter is used only if a hash of the data is to be computed. For more information, see Remarks.

If no hash is to be done, this parameter must be zero.

Final
[in] Boolean value that specifies whether this is the last section in a series being decrypted. This will be TRUE if this is the last or only block. If it is not, then it will be FALSE. For more information, see Remarks.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
pbData
[in/out] Pointer to the buffer that holds the data to be decrypted. After the decryption has been performed, the plaintext is placed back in this same buffer.

The number of encrypted bytes in this buffer is specified by pcbData.

pdwDataLen
[in/out] Pointer to the data length. Before calling this function, the caller should set this parameter to the number of bytes to be decrypted. Upon return, this address will contain the number of bytes of plaintext generated.

When a block cipher is used, this data length must be a multiple of the block size, unless this is the final section of data to be decrypted and the Final flag is TRUE.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The hKey session key specifies an algorithm that this CSP does not support.
NTE_BAD_DATA | The data to be decrypted is invalid. For example, when a block cipher is used and the Final flag is FALSE, the value specified by pdwDataLen must be a multiple of the block size. This error can also be returned when the padding is found to be invalid.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_HASH | The hHash parameter contains an invalid handle.
NTE_BAD_KEY | The hKey parameter does not contain a valid handle to a key.
NTE_BAD_LEN | The size of the output buffer is too small to hold the generated plaintext.
NTE_BAD_UID | The CSP context that was specified when the key was created cannot be found.
NTE_DOUBLE_ENCRYPT | The application attempted to decrypt the same data twice.
NTE_FAIL | The function failed in some unexpected way.

Remarks

If data is to be decrypted and hashed simultaneously, a handle to a hash object can be passed in the hHash parameter. The hash value will be updated with the decrypted plaintext. This option is useful when simultaneously decrypting and verifying a signature.

Before calling CryptDecrypt, the application should obtain a handle to the hash object by calling the CryptCreateHash function. After the decryption is complete, the hash value can be obtained (through CryptGetHashParam), it can be signed (through CryptSignHash), or it can be used to verify a digital signature (through CryptVerifySignature).

When a large amount of data needs to be decrypted, it can be done in sections. This is done by calling CryptDecrypt repeatedly. The Final parameter should be set to TRUE only on the last invocation of CryptDecrypt, so the decryption engine can properly finish the decryption process. The following extra actions are performed when Final is TRUE:

  • If the key is a block cipher key, the data will be padded to a multiple of the block size of the cipher. To find the block size of a cipher, use CryptGetKeyParam to get the KP_BLOCKLEN parameter of the key.
  • If the cipher is operating in a chaining mode, the next CryptDecrypt operation will reset the cipher's feedback register to the KP_IV value of the key.
  • If the cipher is a stream cipher, the next CryptDecrypt call will reset the cipher to its initial state.

Example

For encypting and decrypting examples, see Cryptography.

See Also

CryptCreateHash, CryptEncrypt, CryptGenKey, CryptGetKeyParam, CryptGetHashParam, CryptImportKey, CryptSignHash, CryptVerifySignature


CryptDeriveKey

This function generates cryptographic keys derived from base data. This function guarantees that all keys generated from the same base data are identical, provided the same cryptographic service provider (CSP) and algorithms are used. The base data can be a password or any other user data.

This function is the same as CryptGenKey, except that the generated session keys are derived from base data instead of being random. Another difference is that the CryptDeriveKey function cannot be used to generate public/private key pairs.

A handle to the session key is returned in phKey. This handle can then be used as needed with any of the other CryptoAPI functions that require key handles.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptDeriveKey( HCRYPTPROV hProv,
ALG_ID Algid, HCRYPTHASH hBaseData, DWORD dwFlags,
HCRYPTKEY *phKey );

Parameters

hProv
[in] Handle to the application's CSP. An application obtains this handle by using the CryptAcquireContext function.
Algid
[in] Identifier for the algorithm for which the key is to be generated.

The valid values for this parameter will vary, depending on the CSP that is used. See the "Remarks" section for a list of common algorithm identifiers.

hBaseData
[in] Handle to a hash object that has been fed the exact base data.

To obtain this handle, an application must first create a hash object with CryptCreateHash and then add the base data to the hash object with CryptHashData. For more information about hashing and digital signatures, see Cryptography.

dwFlags
[in] Specifies the type of key generated. This parameter can be zero, or you can specify one or more of the following flags by using the bitwise OR operator to combine them:
Value
Description
CRYPT_EXPORTABLE. | If this flag is set, then the session key can be transferred out of the CSP into a key BLOB through the CryptExportKey function. Because keys generally must be exportable, this flag should usually be set.
If this flag is not set, then the session key will not be exportable. This means the key will be available only within the current session and only the application that created it will be able to use it.
This flag does not apply to public/private key pairs
CRYPT_CREATE_SALT. | Typically, when a session key is made from a hash value, there are a number of leftover bits. For example, if the hash value is 128 bits and the session key is 40 bits, there will be 88 bits left over.
If this flag is set, then the key will be assigned a salt value based on the unused hash value bits. You can retrieve this salt value by using the CryptGetKeyParam function with the dwParam parameter set to KP_SALT.
If this flag is not set, then the key will be given a salt value of zero.
When keys with nonzero salt values are exported (by using CryptExportKey), the salt value must also be obtained and kept with the key BLOB.
CRYPT_NO_SALT. | Specifies that a no salt value gets allocated for a 40-bit symmetric key.
CRYPT_USER_PROTECTED. | If this flag is set, then the user will be notified through a dialog box or another method when certain actions are attempted by using this key. The precise behavior is specified by the CSP being used. Prior to Microsoft Internet Explorer 4.0, Microsoft Cryptographic Providers ignore this flag. Starting with Microsoft Internet Explorer 4.0, Microsoft Providers support this flag value.
CRYPT_UPDATE_KEY. | Some CSPs use session keys that are derived from multiple hash values. When this is the case, CryptDeriveKey must be called multiple times.
If this flag is set, a new session key is not generated. Instead, the key specified by phKey is modified. The precise behavior of this flag is dependent on the type of key being generated and on the particular CSP being used.
The Microsoft Cryptographic Providers ignore this flag.

phKey
[out] Address to which the function copies the handle of the newly generated key.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS | The dwFlags parameter contains an invalid value.
NTE_BAD_HASH | The hBaseData parameter does not contain a valid handle to a hash object.
NTE_BAD_HASH_STATE | An attempt was made to add data to a hash object that is already marked "finished."
NTE_BAD_UID | The hProv parameter does not contain a valid context handle.
NTE_FAIL | The function failed in some unexpected way.

Remarks

To generate a key for a symmetric encryption algorithm, use the Algid parameter to specify the algorithm. The algorithms available will most likely be different for each CSP. If you are using the Microsoft Base Cryptographic Provider, use one of the following values to specify the algorithm.

Value
Description
CALG_RC2 | RC2 block cipher
CALG_RC4 | RC4 stream cipher

When keys are generated for symmetric block ciphers, the key by default will be set up in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk-encrypting data. To change these parameters, use the CryptSetKeyParam function.

After the CryptDeriveKey function has been called, no more data can be added to the hash object. The CryptDestroyHash function should be called at this point to destroy the hash object.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
HCRYPTHASH hHash = 0;
CHAR szPassword[ ] = "apple-camshaft";
DWORD dwLength;

// Get a handle to user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
 printf("Error %x during CryptCreateHash!\n", GetLastError());
 goto done;
}

// Hash the password string.
dwLength = strlen(szPassword);
if(!CryptHashData(hHash, (BYTE *)szPassword, dwLength, 0)) {
 printf("Error %x during CryptHashData!\n", GetLastError());
 goto done;
}

// Create a block cipher session key based on the hash of the password.
if(!CryptDeriveKey(hProv, CALG_RC2, hHash, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptDeriveKey!\n", GetLastError());
 goto done;
}

// Use 'hKey' to encrypt or decrypt a message.
...

done:

// Destroy the hash object.
if(hHash != 0) CryptDestroyHash(hHash);

// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptCreateHash, CryptDestroyHash, CryptDestroykey, CryptExportKey, CryptGenKey, CryptGetKeyParam, CryptHashData, CryptSetKeyParam


CryptDestroyHash

This function destroys the hash object referenced by the hHash parameter. Once a hash object has been destroyed, it can no longer be used and its handle is useless from then on.

All hash objects should be destroyed with the CryptDestroyHash function when the application is finished with them.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptDestroyHash ( HCRYPTHASH hHash );

Parameters

hHash
[in] Handle to the hash object to be destroyed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_BUSY | The hash object specified by hHash is currently being used by another process.
ERROR_INVALID_HANDLE | The hHash parameter specifies an invalid handle.
ERROR_INVALID_PARAMETER | The hHash parameter contains an invalid value.
NTE_BAD_ALGID | The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_UID | The CSP context that was specified when the hash object was created cannot be found.

Remarks

When a hash object is destroyed, many CSPs will scrub the memory in the CSP where the hash object was held. The CSP memory is then freed.

There should be a one-to-one correspondence between calls to CryptCreateHash and CryptDestroyHash.

Example

See CryptHashSessionKey.

See Also

CryptCreateHash, CryptHashData, CryptSignHash


CryptDestroyKey

This function releases the handle referenced by the hKey parameter. Once a key handle has been released, it becomes invalid and cannot be used again.

If the handle refers to a session key, or to a public key that has been imported into the cryptographic service provider (CSP) through CryptImportKey, the CryptDestroyKey function destroys the key and frees the memory that the key occupied. Many CSPs scrub the memory where the key was held before freeing it.

On the other hand, if the handle refers to a public/private key pair obtained from CryptGetUserKey, the underlying key pair is not destroyed by the CryptDestroyKey function. Only the handle is destroyed.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptDestroyKey( HCRYPTKEY hKey );

Parameters

hKey
[in] Handle to the key to be destroyed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | The hKey parameter specifies an invalid handle.
ERROR_INVALID_PARAMETER | The hKey parameter contains an invalid value.
NTE_BAD_KEY | The hKey parameter does not contain a valid handle to a key.
NTE_BAD_UID | The CSP context that was specified when the key was created cannot be found.

Remarks

Keys take up memory in both the operating system's memory space and the CSP's memory space. Some CSPs will be implemented in hardware with very limited memory resources. For this reason, it is important that applications destroy all keys with the CryptDestroyKey function when they are finished with them.

Example

See CryptHashSessionKey.

See Also

CryptDeriveKey, CryptGenKey, CryptGetUserKey, CryptImportKey


CryptDuplicateHash

This function is used to make an exact copy of a hash and the state the hash is in.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptDuplicateHash( HCRYPTHASH hHash,
DWORD *pdwReserved, DWORD dwFlags, HCRYPTHASH phHash );

Parameters

hHash
[in] Handle to the hash to be duplicated.
pdwReserved
[in] Reserved for future use; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.
phHash
[out] Pointer to the handle to the duplicated hash.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_CALL_NOT_IMPLEMENTED | Since this is a new function, existing CSPs may not implement it. This error is returned if the CSP does not support this function.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_HASH | The handle to the original hash is not valid.

Remarks

CryptDuplicateHash is used to make copies of hashes and the exact state of the hash. An example of how this function might be used is that a caller may want to generate two hashes, but both hashes have to start with some common data hashed. A hash could be created, the common data hashed, a duplicate made with the CryptDuplicateHash function, and then the data unique to each hash would be hashed.

CryptDestroyHash must be called to destroy any hashes that are created with CryptDuplicateHash. Destroying the original hash does not cause the duplicate hash to be destroyed. Once a duplicate hash is made it is separate from the original hash. There is no shared state between the two hashes.

Example

HCRYPTPROV hProv = 0;
HCRYPTHASH hOriginalHash = 0;
HCRYPTHASH hDuplicateHash = 0;
DWORD dwErr;

// Create a hash.
if (!CryptCreateHash(hProv, CALG_SHA1, 0, &hOriginalHash))
 {printf("ERROR - CryptCreateHash: %X\n", GetLastError());
 return;}

// Hash common data.
if (!CryptHashData(hOriginalHash, (BYTE*)"Common Data", sizeof("Common Data"), 0))
 {printf("ERROR - CryptHashData: %X\n", GetLastError());
 return;}

// Duplicate the hash.
if (!CryptDuplicateHash(hOriginalHash, NULL, 0, &hDuplicateHash))
 {printf("ERROR - CryptDuplicateHash: %X\n", GetLastError());
 return;}

// Hash some data with the original hash.
if (!CryptHashData(hOriginalHash, (BYTE*)"Some Data", sizeof("Some Data"), 0))
 {printf("ERROR - CryptHashData: %X\n", GetLastError());
 return;}

// Hash other data with the duplicate hash.
if (!CryptHashData(hDuplicateHash, (BYTE*)"Other Data", sizeof("Other Data"), 0))
 {printf("ERROR - CryptHashData: %X\n", GetLastError());
 return;}

...

// Destroy the original hash.
if (!CryptDestroyHash (hOriginalHash))
 {printf("ERROR - CryptDestroyHash: %X\n", GetLastError());
 return;}

// Destroy the duplicate hash.
if (!CryptDestroyHash(hDuplicateHash))
 {printf("ERROR - CryptDestroyHash: %X\n", GetLastError());
 return;}

See Also

CryptDestroyHash


CryptDuplicateKey

This function is used to make an exact copy of a key and the state the key is in. Some keys have an associated state, for example, an initialization vector and/or a salt value.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptDuplicateHash ( HCRYPTKEY hKey,
DWORD *pdwReserved, DWORD dwFlags, HCRYPTKEY *phkey );

Parameters

hKey
[in] Handle to the key to be duplicated.
pdwReserved
[in] Reserved for future use; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
phKey
[out] Pointer to the handle to the duplicated key.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_CALL_NOT_IMPLEMENTED | Since this is a new function, existing CSPs may not implement it. This error is returned if the CSP does not support this function.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_KEY | The handle to the original key is not valid.

Remarks

CryptDuplicateKey is used to make copies of keys and the exact state of the key. An example of how this function might be used is that a caller may want to encrypt two separate messages with the same key, but with different salt values. The key could be generated, a duplicate would be made with the CryptDuplicateKey function, and then the appropriate salt value would be set on each key with the CryptSetKeyParam function.

CryptDestroyKey must be called to destroy any keys that are created with CryptDuplicateKey. Destroying the original key does not cause the duplicate key to be destroyed. Once a duplicate key is made, it is separate from the original key. There is no shared state between the two keys.

Example

HCRYPTPROV hProv = 0;
HCRYPTKEY hOriginalKey = 0;
HCRYPTKEY hDuplicateKey = 0;
DWORD dwErr;

// Generate a key.
if (!CryptGenKey(hProv, CALG_RC4, 0, &hOriginalKey))
 {printf("ERROR - CryptGenKey: %X\n", GetLastError());
 return;}

// Duplicate the key.
if (!CryptDuplicateKey(hOriginalKey, NULL, 0, &hDuplicateKey))
 {printf("ERROR - CryptDuplicateKey: %X\n", GetLastError());
 return;}

...

// Destroy the original key.
if (!CryptDestroyKey(hOriginalKey))
 {printf("ERROR - CryptDestroyKey: %X\n", GetLastError());
 return;}

// Destroy the duplicate key.
if (!CryptDestroyKey(hDuplicateKey))
 {printf("ERROR - CryptDestroyKey: %X\n", GetLastError());
 return;}

See Also

CryptDestroyKey


CryptEncrypt

This function is used to encrypt data. The algorithm used to encrypt the data is designated by the key held by the cryptographic service provider (CSP) module, which is referenced by the hKey parameter.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptEncrypt( HCRYPTKEY hkey,
HCRYPTHASH hHash, BOOL Final, DWORD dwFlags, BYTE *pbData,
DWORD *pdwDataLen, DWORD dwBufLen );

Parameters

hKey
[in] Handle to the key to use for the encryption. An application obtains this handle by using either the CryptGenKey or the CryptImportKey function.

This key specifies the encryption algorithm that is used.

hHash
[in] Handle to a hash object. This parameter is used only if a hash of the data is to be computed at the same time the encryption is being performed. For more information, see Remarks.

If no hash is to be done, this parameter must be zero.

Final
[in] Boolean value that specifies whether this is the last section in a series being encrypted. This should be TRUE if this is the last or only block, and FALSE if it is not. For more information, see Remarks.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
pbData
[in/out] Pointer to the buffer that holds the data to be encrypted. After the encryption has been performed, the encrypted data is placed back in this same buffer.

The size of this buffer is specified by dwBufLen. The number of bytes of data to be encrypted is specified by pdwDataLen.

This parameter can be NULL if all you are doing is determining the number of bytes required for the returned data.

pdwDataLen
[in/out] Pointer to the data length. Before calling this function, the caller should set this parameter to the number of bytes to be encrypted. Upon return, this address will contain the number of bytes of encrypted data.

If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError) and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.

If pbData is NULL, then no error is returned, and the function stores the size of the data, in bytes, in the variable pointed to be pdwDataLen. This lets an application determine the correct buffer size unambiguously.

When a block cipher is used, this data length must be a multiple of the block size, unless this is the final section of data to be encrypted and the Final flag is TRUE.

dwBufLen
[in] Specifies the number of bytes in the pbData buffer.

Note that, depending on the algorithm used, the encrypted text can be slightly larger than the original plaintext. In this case, the pbData buffer needs to be sized accordingly.

As a rule, if a stream cipher is used the ciphertext will be the same size as the plaintext. If a block cipher is used, the ciphertext will be up to a "block length" larger than the plaintext.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The hKey session key specifies an algorithm that this CSP does not support.
NTE_BAD_DATA | The data to be encrypted is invalid. For example, when a block cipher is used and the Final flag is FALSE, the value specified by pdwDataLen must be a multiple of the block size.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_HASH | The hHash parameter contains an invalid handle.
NTE_BAD_HASH_STATE | An attempt was made to add data to a hash object that is already marked "finished."
NTE_BAD_KEY | The hKey parameter does not contain a valid handle to a key.
NTE_BAD_LEN | The size of the output buffer is too small to hold the generated ciphertext.
NTE_BAD_UID | The CSP context that was specified when the key was created cannot be found.
NTE_DOUBLE_ENCRYPT | The application attempted to encrypt the same data twice.
NTE_FAIL | The function failed in some unexpected way.
NTE_NO_MEMORY | The CSP ran out of memory during the operation.

Remarks

If data is to be hashed and encrypted simultaneously, a handle to a hash object can be passed in the hHash parameter. The hash value will be updated with the plaintext passed in. This option is useful when generating signed and encrypted text.

Before calling CryptEncrypt, the application should obtain a handle to the hash object by calling the CryptCreateHash function. After the encryption is complete, the hash value can be obtained through the CryptGetHashParam function or the hash can be signed using the CryptSignHash function.

When a large amount of data needs to be encrypted, it can be done in sections. This is done by calling CryptEncrypt repeatedly. The Final parameter should be set to TRUE only on the last invocation of CryptEncrypt, so the encryption engine can properly finish the encryption process. The following extra actions are performed when Final is TRUE:

  • If the key is a block cipher key, the data will be padded to a multiple of the block size of the cipher. To find the block size of a cipher, use CryptGetKeyParam to get the KP_BLOCKLEN parameter of the key.
  • If the cipher is operating in a chaining mode, the next CryptEncrypt operation will reset the cipher's feedback register to the KP_IV value of the key.
  • If the cipher is a stream cipher, the next CryptEncrypt will reset the cipher to its initial state.

See Also

CryptCreateHash, CryptDecrypt, CryptGenKey, CryptGetHashParam, CryptImportKey, CryptSignHash


CryptEnumProviders

This function is used to enumerate the providers on a machine.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptEnumProviders( DWORD dwIndex,
DWORD *pdwReserved, DWORD dwFlags, DWORD *pdwProvType,
LPTSTR pszProvName, DWORD *pcbProvName );

Parameters

dwIndex
[in] Specifies the index of the next provider to be enumerated.
pdwReserved
[in] Reserved for future use; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
pdwProvType
[in] Pointer to the DWORD value that designates the type of the enumerated provider.
pszProvName
[out] Pointer to a buffer that receives the data from the enumerated provider. A null-terminated string.

This parameter can be NULL to set the size of the name for memory allocation purposes.

pcbProvName
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pszProvName parameter. When the function returns, the variable pointed to by the pcbProvName parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_MORE_DATA | The pszProvName buffer was not large enough to hold the provider name.
ERROR_NO_MORE_ITEMS | There are no more items to enumerate.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory.
NTE_BAD_FLAGS | dwFlags has an unrecognized value.
NTE_FAIL | Something was wrong with the type registration.

Remarks

CryptEnumProviders is used to enumerate the providers on a machine. The provider types may be enumerated by using CryptEnumProviderTypes.

Windows CE does not support the ANSI version of this function.

Example

long i;
LPTSTR pszName;
DWORD dwType;
DWORD cbName;
DWORD dwErr;

// Loop through enumerating provider types.
for (i=0;;i++)
{
if (!CryptEnumProviders(
 i, // in- dwIndex
 NULL, // in- pdwReserved- set to NULL
 0, // in- dwFlags- set to 0
 &dwType, // out- pdwProvType
 NULL, // out- pszProvName- NULL on the first call
 &cbName // in, out-pcbProvName
 ))
 {if (ERROR_NO_MORE_ITEMS != (dwErr = GetLastError()))
 {printf("ERROR - CryptEnumProviders : %X\n", dwErr);
 }
 break;
 }

if (NULL == (pszName = (LPTSTR)LocalAlloc(LMEM_ZEROINIT, cbName)))
 {printf("ERROR - LocalAlloc failed!\n");
 }

if (!CryptEnumProviders(
 i,
 NULL,
 0,
 &dwType,
 pszName,
 &cbName // pcbProvName- size of pszName
 ))
 {if (ERROR_NO_MORE_ITEMS != (dwErr = GetLastError()))
 {printf("ERROR - CryptEnumProviders : %X\n", dwErr);
 }
 LocalFree(pszName);
 break;
 }
printf ("Provider %s is type %d\n", pszName, dwType);
LocalFree(pszName);
}

See Also

CryptEnumProviderTypes


CryptEnumProviderTypes

This function is used to enumerate the types of providers supported on the machine.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptEnumProviderTypes( DWORD dwIndex,
DWORD *pdwReserved, DWORD dwFlags, DWORD *pdwProvType,
LPTSTR pszTypeName, DWORD *pcbTypeName );

Parameters

dwIndex
[in] Specifies the index of the next provider type to be enumerated.
pdwReserved
[in] Reserved for future use ; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
pdwProvType
[in] Pointer to the DWORD value that designates the enumerated provider type.
pszTypeName
[out] Pointer to a buffer that receives the data from the enumerated provider type. A null-terminated string. There are provider types which may not have friendly names and in this case no name will be returned and the returned value pointed to by pcbTypeName will be 0.

This parameter can be NULL if you want to get the size of the name for memory allocation purposes.

pcbTypeName
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pszTypeName parameter. When the function returns, the variable pointed to by the pcbTypeName parameter contains the number of bytes stored in the buffer. There are provider types which may not have friendly names and in this case no name will be returned and the returned value pointed to by pcbTypeName will be 0.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_NO_MORE_ITEMS | There are no more items to enumerate.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory.
NTE_BAD_FLAGS | dwFlags has an unrecognized value.
NTE_FAIL | Something was wrong with the type registration.

Remarks

CryptEnumProviderTypes is used to enumerate the provider types on a machine. Once this is done, the providers for a specific type may be enumerated by using CryptEnumProviders.

Windows CE does not support the ANSI version of this function.

Example

long i;
DWORD dwErr;

// Loop through enumerating provider types.
for (i=0;;i++)
{
if (!CryptEnumProviderTypes(i, NULL, 0, &dwType, NULL, NULL))
 {if (ERROR_NO_MORE_ITEMS != (dwErr = GetLastError()))
 {printf("ERROR - CryptEnumProviderTypes : %X\n", dwErr);
 }
 break;
 }
printf ("Provider Type %d\n", dwType);
}

See Also

CryptEnumProviders


CryptExportKey

This function is used to export cryptographic keys out of a cryptographic service provider (CSP) in a secure manner.

A handle to the key to be exported is passed into the function and the function returns a key Binary Large Object (BLOB) to the caller. This key BLOB can be sent over a nonsecure transport or stored in a nonsecure storage location. The key BLOB is useless until the intended recipient uses the CryptImportKey function on it, which then imports the key into the recipient’s CSP.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptExportKet( HCRYPTKEY hKey,
HCRYPTKEY hExpKey, DWORD dwBlobType, DWORD dwFlags,
BYTE *pbData, DWORD *pdwDataLen );

Parameters

hKey
[in] Handle to the key to be exported.
hExpKey
[in] Handle to a cryptographic key belonging to the destination user. The key data within the key BLOB created is encrypted by using this key. This ensures that only the destination user will be able to make use of the key BLOB.

Most often, this will be the key exchange public key of the destination user. However, certain protocols in some CSPs require that a session key belonging to the destination user be used for this purpose. (Neither the Microsoft Base Cryptographic Provider or the Microsoft Enhanced Cryptographic Provider currently support this.)

If the key BLOB type specified by dwBlobType is PUBLICKEYBLOB, then this parameter is unused and should be set to zero.

If the key BLOB type specified by dwBlobType is PRIVATEKEYBLOB, then this is typically a handle to a session key that is to be used to encrypt the key BLOB. Some CSPs allow this parameter to be zero, in which case the application should encrypt the private key BLOB manually so as to protect it.

To determine how Microsoft Cryptographic Providers respond to this parameter, see Cryptography.

dwBlobType
[in] Specifies the type of key BLOB to be exported. This must be one of the following constants:
Constant
Description
SIMPLEBLOB | used to transport session keys.
PUBLICKEYBLOB | used to transport public keys.
PRIVATEKEYBLOB | used to transport public/private key pairs.
OPAQUEBLOB | used to store session keys in a Schannel CSP. OPAQUEBLOBs are non-transferrable and must be used within the CSP that generated the BLOB.

For more information about exchanging cryptographic keys, see Cryptography.

dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
pbData
[out] Pointer to a buffer that receives the key BLOB.

This parameter can be NULL to set the size of this information for memory allocation purposes.

pdwcbDataLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA | If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwcbDataLen.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_KEY | One or both of the keys specified by hKey and hExpKey are invalid.
NTE_BAD_KEY_STATE | You do not have permission to export the key. That is, when the hKey key was created, the CRYPT_EXPORTABLE flag was not specified.
NTE_BAD_PUBLIC_KEY | The key BLOB type specified by dwBlobType is PUBLICKEYBLOB, but hExpKey does not contain a public key handle.
NTE_BAD_TYPE | The dwBlobType parameter specifies an unknown BLOB type.
NTE_BAD_UID | The CSP context that was specified when the hKey key was created cannot be found.
NTE_NO_KEY | A session key is being exported and the hExpKey parameter does not specify a public key.

Example

#include <wincrypt.h>

HCRYPTPROV hProv; // Handle to CSP
HCRYPTKEY hKey; // Handle to session key
HCRYPTKEY hXchgKey; // Handle to receiver's exchange public key
BYTE *pbKeyBlob = NULL;
DWORD dwBlobLen;
...
// Determine the size of the key BLOB and allocate memory.
if(!CryptExportKey(hKey, hXchgKey, SIMPLEBLOB, 0, NULL, &dwBlobLen)) {
 printf("Error %x computing BLOB length!\n", GetLastError());
 ...
}
if((pbKeyBlob = malloc(dwBlobLen)) == NULL) {
 printf("Out of memory!\n");
 ...
}

// Export the key into a simple key BLOB.
if(!CryptExportKey(hKey, hXchgKey, SIMPLEBLOB, 0, pbKeyBlob, &dwBlobLen)) {
 printf("Error %x during CryptExportKey!\n", GetLastError());
 ...
}

See Also

CryptImportKey


CryptGenKey

This function generates random cryptographic keys for use with the cryptographic service provider (CSP) module. A handle to the key is returned in phKey. This handle can then be used as needed with any of the other CryptoAPI functions requiring key handles.

When calling this function, the application is required to specify the algorithm. Because this algorithm type is kept bundled with the key, the application does not need to specify the algorithm later when the actual cryptographic operations are performed.

The maximum size of an RSA signature is 16,384 bits.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUN CryptGenKey( HCRYPTPROV hProv, ALG_ID Algid,
DWORD dwFlags, HCRYPTKEY *phKey );

Parameters

hProv
[in] Handle to the application's CSP. An application obtains this handle by using the CryptAcquireContext function.
Algid
[in] Identifier for the algorithm for which the key is to be generated.

The valid values for this parameter will vary, depending on the CSP that is used. See the "Remarks" section for a list of common algorithm identifiers.

dwFlags
[in] Specifies the type of key generated.

The sizes of RSA signature and key exchange keys may be set when the key is generated. The key size is set with the upper 16 bits of the dwFlags parameter and these 16 bits represent the length of the key (modulus) in bits. So if a 2048 bit RSA signature key is to be generated then the value 0x08000000 would be combined together with the dwFlags parameter in bitwise OR operation. Notice that the upper 16 bits of 0x08000000 is 0x0800, or 2048 in decimal notation. If none of the upper 16 bits are set, then the default key size is generated. If a key larger than the max (16,384 signature, 512 key exchange) or smaller than the min (384 sig and key exchange) is given, the call fails with ERROR_INVALID_PARAMETER.

This parameter can be zero, or you can specify one or more of the following flags by using the bitwise OR operator to combine them:
Flag
Description
CRYPT_EXPORTABLE. | If this flag is set, then the key can be transferred out of the CSP into a key BLOB by using the CryptExportKey function. Because session keys generally must be exportable, this flag should usually be set when they are created.
If this flag is not set, then the key will not be exportable. For a session key, this means that the key will be available only within the current session and only the application that created it will be able to use it. For a public/private key pair, this means that the private key cannot be transported or backed up.
This flag applies only to session key and private key BLOBs. It does not apply to public keys, which are always exportable.
CRYPT_CREATE_SALT. | If this flag is set, then the key will be assigned a random salt value automatically. You can retrieve this salt value by using the CryptGetKeyParam function with the dwParam parameter set to KP_SALT.
If this flag is not set, then the key will be given a salt value of zero.
When keys with nonzero salt values are exported (through CryptExportKey), then the salt value must also be obtained and kept with the key BLOB.
CRYPT_NO_SALT. | Specifies that a no salt value gets allocated for a 40-bit symmetric key.
CRYPT_USER_PROTECTED. | The Microsoft Windows CE Cryptographic Providers ignore this flag.
CRYPT_PREGEN. | Specifies an initial Diffie-Hellman or DSS key generation. Useful only with Diffie-Hellman/DSS CSPs.

phKey
[out] Address to which the function copies the handle of the newly generated key.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS | The dwFlags parameter contains an invalid value.
NTE_BAD_UID | The hProv parameter does not contain a valid context handle.
NTE_FAIL | The function failed in some unexpected way.

Remarks

To generate a key to be used with a symmetric encryption algorithm (that is, a session key), use the Algid parameter to specify the algorithm. The algorithms available will most likely be different for each CSP. If you are using the Microsoft Base Cryptographic Provider, one of the following values can be used to specify the algorithm.

Value
Description
CALG_RC2 | RC2 block cipher
CALG_RC4 | RC4 stream cipher

If you are using the Microsoft Enhanced Cryptographic Provider, you can additionally use the following values

Value
Description
CALG_DES | DES block cipher
CALG_3DES | Triple DES block cipher
CALG_3DES_112 | Triple DES two key block cipher

If you are using a Diffie-Hellman CSP, use one of the following values.

Value
Description
CALG_DH_SF | Specifies a "Store and Forward" Diffie-Hellman key.
CALG_DH_EPHEM | Specifies an "Ephemeral" Diffie-Hellman key.

When keys are generated for symmetric block ciphers, the key by default will be set up in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk encrypting data. To change these parameters, use the CryptSetKeyParam function.

In addition to generating keys for symmetric algorithms, the CryptGenKey function can also generate keys for public-key algorithms. The use of public-key algorithms is restricted to key exchange and digital signatures. Each CryptoAPI client generally possesses one key pair for each of these operations. To generate one of these key pairs, set the Algid parameter to one of the following values.

Value
Description
AT_KEYEXCHANGE | Key exchange
AT_SIGNATURE | Digital signature

Note When key specifications AT_KEYEXCHANGE and AT_SIGNATURE are specified for the Algid parameter, the algorithm identifiers that are used to generate the key depend on the provider used. As a result, for these key specifications, the values returned from CryptGetKeyParam (when the KP_ALGID parameter is specified) depend on the provider used.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;

// Get a handle to user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Create a block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptGenKey!\n", GetLastError());
 goto done;
}

// Use 'hKey' to encrypt or decrypt a message.
...

done:

// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptDestroyKey, CryptExportKey, CryptGetKeyParam, CryptImportKey, CryptSetKeyParam


CryptGenRandom

This function fills a buffer with random bytes.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CrptGenRandom( HCRYPTPROV hProv,
DWORD dwLen, BYTE *pbBuffer );

Parameters

hProv
[in] Handle to the application's CSP. An application obtains this handle by using the CryptAcquireContext function.
dwLen
[in] Specifies the number of bytes of random data to be generated.
pbBuffer
[in/out] Pointer to the buffer that the function copies the random data to. This buffer must be at least dwLen bytes in length.

Optionally, the application can fill this buffer with data to use as an auxiliary random seed. This is explained further in the "Remarks" section.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_UID | The hProv parameter does not contain a valid context handle.
NTE_FAIL | The function failed in some unexpected way.

Remarks

The data produced by this function is cryptographically random. It is far more random than the data generated by the typical random number generator such as the one shipped with your "C" compiler.

This function is often used to generate random initialization vectors and salt values.

Seeding the Random Number Generator

All software random number generators work in fundamentally the same way. They start with a random number, known as the seed, and then use an algorithm to generate a pseudo-random sequence of bits based on it. The most difficult part of this process is to get a seed that is truly random. This is usually based on user input latency, or the jitter from one or more hardware components.

If your application has access to a good random source, then it can fill the pbBuffer buffer with some amount of random data before calling CryptGenRandom. The CSP will then use this data to further randomize its internal seed. Failing to initialize the pbBuffer buffer before calling CryptGenRandom is acceptable.

Example

See CryptSetKeyParam.

See Also

CryptAcquireContext , CryptGenKey, CryptSetKeyParam


CryptGetDefaultProvider

This function is used to determine the default cryptographic service provider (CSP) either for the current user or the machine for a given provider type. The name of the default CSP for the type specified in the dwProvType parameter is returned.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptGetDefaultProvider( DWORD dwProvType,
DWORD *pdwReserved, DWORD dwFlags, LPTSTR pszProvName,
DWORD *pcbProvName );

Parameters

dwProvType
[in] Specifies the provider type of the CSP specified by the pszProvName parameter.
pdwReserved
[in] Reserved for future use; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. It is one of the following values:
Value
Description
CRYPT_MACHINE_DEFAULT | Causes the machine default CSP of the given type to be returned.
CRYPT_USER_DEFAULT | Causes the user default CSP of the given type to be returned.

pszProvName
[out] Pointer to a buffer that receives the null-terminated string that contains the name of the default CSP.

This parameter can be NULL to set the size of the name for memory allocation purposes.

pcbProvName
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pszProvName parameter. When the function returns, the variable pointed to by the pcbProvName parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA | The buffer for the name is not large enough.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory.
NTE_BAD_FLAGS | dwFlags has an unrecognized value.

Remarks

CryptGetDefaultProvider is used to determine which installed CSP is currently set as the default for the current user or the machine. This information will most often be used for display to the user.

Windows CE does not support the ANSI version of this function.

Example

LPTSTR pszName;
DWORD cbName;

// Get the name of the default CSP specified for the PROV_RSA_SIG
// type for the machine.
cbName = 0;
if (!CryptGetDefaultProvider(PROV_RSA_SIG, NULL, CRYPT_MACHINE_DEFAULT,
 NULL, &cbName))
 {printf("Error %x during CryptGetDefaultProvider!\n", GetLastError);
 return;
 }

if (NULL == (pszProvName = (LPTSTR)LocalAlloc(LMEM_ZEROINIT, cbName)))
 {printf("Error during memory allocation\n");
 return;
 }

if (!CryptGetDefaultProvider(PROV_RSA_SIG, NULL, CRYPT_MACHINE_DEFAULT,
 NULL, &cbName))
 {printf("Error %x during CryptGetDefaultProvider!\n", GetLastError);
 return;
 }

// Display this information to the user
...

See Also

CryptSetProviderEx, CryptSetProvider


CryptGetHashParam

This function retrieves data that governs the operations of a hash object. The actual hash value can also be retrieved by using this function.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptGethashParam( HCRYPTHASH hHash,
DWORD dwParam, BYTE *pbData, DWORD *pdwdataLen,
DWORD dwFlags );

Parameters

hHash
[in] Handle to the hash object on which to query parameters.
dwParam
[in] Specifies the parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[out] Pointer to a buffer that receives the specified parameter data. The form of this data will vary, depending on the parameter number.

This parameter can be NULL to set the size of this information for memory allocation purposes.

pdwDataLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA | If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID | The CSP context that was specified when the hash was created cannot be found.

Remarks

The dwParam value can be set to one of the following hash parameter types:

  • HP_ALGID. The hash algorithm. The pbData buffer will contain an ALG_ID value indicating that the algorithm was specified when the hash object was created. See the CryptCreateHash function for a list of hash algorithms.
  • HP_HASHSIZE. The hash value size. The pbData buffer will contain a DWORD value indicating the number of bytes in the hash value. This value will usually be 16 or 20, depending on the hash algorithm.
  • Applications should retrieve this parameter just before the HP_HASHVAL parameter so the correct amount of memory can be allocated.
  • HP_HASHVAL. The hash value. The pbData buffer will contain the hash value or message hash for the hash object specified by hHash. This value is generated based on the data supplied earlier to the hash object through the CryptHashData and CryptHashSessionKey functions.

    After this parameter has been retrieved, the hash object is marked "finished" and no more data can be added to it.

Note Some CSPs may add additional parameters that can be queried through this function.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTHASH hHash = 0;
BYTE *pbHash = NULL;
DWORD dwHashLen;
#define BUFFER_SIZE 256
BYTE pbBuffer[BUFFER_SIZE];
DWORD dwCount;
DWORD i;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}
// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
 printf("Error %x during CryptBeginHash!\n", GetLastError());
 goto done;
}

// Fill the buffer with test data.
for(i = 0 ; i < BUFFER_SIZE ; i++) {
 pbBuffer[i] = (BYTE)i;
}

// Put the hash in buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {
 printf("Error %x during CryptHashData!\n", GetLastError());
 goto done;
}

// Read the hash value size and allocate memory.
dwCount = sizeof(DWORD);
if(!CryptGetHashParam(hHash, HP_HASHSIZE, (BYTE *)&dwHashLen,
 &dwCount, 0)) {
 printf("Error %x during reading hash size!\n", GetLastError());
 goto done;
}
if((pbHash = malloc(dwHashLen)) == NULL) {
 printf("Out of memory!\n");
 goto done;
}

// Read the hash value.
if(!CryptGetHashParam(hHash, HP_HASHVAL, pbHash, &dwHashLen, 0)) {
 printf("Error %x during reading hash value!\n", GetLastError());
 goto done;
}

// Print the hash value.
for(i = 0 ; i < dwHashLen ; i++) {
 printf("%2.2x ",pbHash[i]);
}
printf("\n");

done:

// Free memory.
if(pbHash !=NULL) free(pbHash);

// Destroy the hash object.
if(hHash) CryptDestroyHash(hHash);
// Release the CSP handle.
if(hProv) CryptReleaseContext(hProv,0);

See Also

CryptCreateHash, CryptGetKeyParam, CryptHashData, CryptHashSessionKey, CryptSetHashParam


CryptGetKeyParam

This function lets applications retrieve data that governs the operations of a key. Note that in the Microsoft Cryptographic Service Providers, the base symmetric keying material is not obtainable by this or any other function.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptGetKeyParam( HCRYPTKEY hKey,
DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen,
DWORD dwFlags );

Parameters

hKey
[in] Handle to the key on which to query parameters.
dwParam
[in] Specifies the parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[out] Pointer to a buffer that receives the parameter data. The function will copy the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

This parameter can be NULL to set the size of this information for memory allocation purposes.

pdwDataLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA | If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_KEY or NTE_NO_KEY | The key specified by the hKey parameter is invalid.
NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID | The CSP context that was specified when the key was created cannot be found.

Remarks

For all key types, the dwParam value can be set to one of the following key parameter types.

KP_ALGID
Key algorithm. The pbData buffer will contain an ALG_ID value indicating the algorithm that was specified when the key was created. Note that when key specifications AT_KEYEXCHANGE and AT_SIGNATURE are specified for the Algid parameter, the algorithm identifiers that are used to generate the key depend on the provider used. As a result, for these key specifications the values returned from CryptGetKeyParam (when the KP_ALGID parameter is specified) depend on the provider used.
KP_BLOCKLEN
If a session key is specified by hKey, this parameter returns the block length, in bits, of the cipher. The pbData buffer will contain a DWORD value indicating the block length. For stream ciphers, this value will always be zero.

If a public/private key pair is specified by hKey, this parameter returns the key pair's encryption granularity in bits. For example, the Microsoft Base Cryptographic Provider generates 512-bit RSA key pairs, so a value of 512 is returned for these keys. If the public-key algorithm does not support encryption, the value returned by this parameter is undefined.

KP_KEYLEN
Used to get the actual length of a key in bits, The length of the key is located in the DWORD pointed to by pbData. This parameter can be used to get the length of any key type.
KP_SALT
The salt value. The pbData buffer will contain a BYTE array indicating the current salt value. The size of the salt value will vary depending on the CSP and algorithm being used.

Salt values do not apply to public/private key pairs.

KP_PERMISSIONS
Key permissions. The pbData buffer will contain a DWORD value with zero or more permission flags set. Refer to the table at the end of this section for a description of each of these flags.

If a DSS key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_P
The pbData buffer will contain the prime modulus P from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.
KP_Q
The pbData buffer will contain the prime Q from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.
KP_G
The pbData buffer will contain the generator G from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

If a block cipher session key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_EFFECTIVE_KEYLEN
Used to query the effective key length of an RC2 key. The value of the effective key length is returned as a DWORD pointed to by the pbData parameter.
KP_IV
The initialization vector. The pbData buffer will contain a BYTE array indicating the current initialization vector. This array contains block_length/8 elements. For example, if the block length is 64 bits, the initialization vector will consist of eight bytes.
KP_PADDING
The padding mode. The pbData buffer will contain a DWORD value indicating the padding method used by the cipher. Following are the padding modes currently defined:

PKCS5_PADDING—PKCS 5 (sec 6.2) padding method.

KP_MODE
The cipher mode. The pbData buffer will contain a DWORD value indicating the mode of the cipher. Refer to the following table for a list of valid cipher modes.
KP_MODE_BITS
The number of bits to feed back. The pbData buffer will contain a DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher modes are used.

The following table lists the common values for the KP_MODE parameter. These cipher modes are discussed in Cryptography.

Cipher mode
Description
CRYPT_MODE_ECB | Electronic codebook
CRYPT_MODE_CBC | Cipher block chaining
CRYPT_MODE_OFB | Output feedback mode
CRYPT_MODE_CFB | Cipher feedback mode

The following table lists the flags in the bit field that are obtained when the KP_PERMISSIONS parameter is read. These permission flags are ignored by the Microsoft Base Cryptographic Provider. However, custom CSPs can use these flags to restrict operations on keys.

Permission flag
Description
CRYPT_ENCRYPT | Allow encryption.
CRYPT_DECRYPT | Allow decryption.
CRYPT_EXPORT | Allow key to be exported.
CRYPT_READ | Allow parameters to be read.
CRYPT_WRITE | Allow parameters to be set.
CRYPT_MAC | Allow MACs to be used with key.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;

// Get a handle to user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Create a random block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptGenKey!\n", GetLastError());
 goto done;
}

// Read the cipher mode.
dwCount = sizeof(DWORD);
if(!CryptGetKeyParam(hKey, KP_MODE, &dwMode, &dwCount, 0)) {
 printf("Error %x during CryptGetKeyParam!\n", GetLastError());
 goto done;
}
assert(dwCount==sizeof(BYTE));

// Print out the cipher mode.
printf("Default cipher mode: %d\n", dwMode);

// Read the initialization vector.
dwCount = 16;
if(!CryptGetKeyParam(hKey, KP_IV, pbData, &dwCount, 0)) {
 printf("Error %x during CryptGetKeyParam!\n", GetLastError());
 goto done;
}
// Print out the initialization vector.
printf("Default IV:");
for(i=0;i<dwCount;i++) printf("%2.2x ",pbData[i]);
printf("\n");

done:

// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptSetKeyParam


CryptGetProvParam

This function lets applications retrieve parameters that govern the operations of a cryptographic service provider (CSP).

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptGetProvParam( HCRYPTPROV hProv,
DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen,
DWORD dwFlags );

Parameters

hProv
[in] Handle to the CSP on which to query parameters.
dwParam
[in] Specifies the parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[out] Pointer to a buffer that receives the specified parameter data. The form of this data will vary, depending on the parameter number.

This parameter can be NULL to set the size of this information for memory allocation purposes.

pdwDataLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Note When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is set, the pdwDataLen parameter works somewhat differently. If pbData is NULL or the value pointed to by pdwDataLen is too small, the value returned in this parameter is the size of the largest item in the enumeration list instead of the size of the item currently being read.

When one of the enumeration parameters is read and the pbData parameter is NULL, the CRYPT_FIRST flag must be specified in order for the size information to be correctly retrieved.

dwFlags
[in] Specifies a bitmask of flags.

When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is set, then the CRYPT_FIRST flag can be specified. When this flag is set, the first item in the enumeration list is returned. If this flag is not set, then the next item in the list is returned.

When the enumeration parameter PP_ENUMCONTAINERS is set, then the CRYPT_MACHINE_KEYSET flag can be specified. This flag can be set to enumerate the key containers associated with a computer rather than the key containers associated with the current user.

When the dwParam is PP_KEYSET_SEC_DESCR, the security descriptor on the key container where the keys are stored is retrieved. For this case, dwFlags is used to pass in the SECURITY_INFORMATION bit flags (can be combined with a bitwise OR operation).

typedef DWORD SECURITY_INFORMATION;
Value
Description
OWNER_SECURITY_INFORMATION | Indicates the owner identifier of the object is being referenced.
GROUP_SECURITY_INFORMATION | Indicates the primary group identifier of the object is being referenced.
DACL_SECURITY_INFORMATION | Indicates the discretionary ACL of the object is being referenced.
SACL_SECURITY_INFORMATION | Indicates the system ACL of the object is being referenced.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA | If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.
ERROR_NO_MORE_ITEMS | The end of the enumeration list has been reached. No valid data has been placed in the pbData buffer. This error is returned only when dwParam equals PP_ENUMALGS or PP_ENUMCONTAINERS.
NTE_BAD_FLAGS | The dwFlags parameter specifies an invalid flag.
NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID | The CSP context specified by hProv is invalid.

Remarks

The parameter number contained in the dwParam parameter can be set to one of the following values:

PP_CONTAINER
The key container name. When this parameter is specified, the function fills the pbData buffer with the name of the current key container. This name is in the form of a zero-terminated CHAR string.

This string is exactly the same as the one passed in the pszContainer parameter of the CryptAcquireContext function in order to specify that the current key container be used. This parameter is often read in order to determine the name of the default key container.

PP_ENUMALGS
The algorithm information. When this parameter is specified, the function fills the pbData buffer with information about one of the algorithms supported by the CSP. The PP_ENUMALGS parameter must be read repeatedly to enumerate all the supported algorithms. The algorithms are not enumerated in any particular order.

The first time that the PP_ENUMALGS parameter is read, the CRYPT_FIRST flag should be specified. This will ensure that information about the first algorithm in the enumeration list is returned. The PP_ENUMALGS parameter can then be repeatedly read in order to retrieve the information about the rest of the algorithms. When the CryptGetProvParam function fails with ERROR_NO_MORE_ITEMS, then the end of the enumeration list has been reached. A code sample illustrating this is located in the "Example" section.

When calling CryptGetProvParam with the PP_ENUMALGS flag in the dwParam parameter the dwBits field should be changed to the length of the default key sizes.

The following code fragment indicates the format of the data that the function returns in the pbData buffer:

ALG_ID aiAlgid;
DWORD dwBits;
DWORD dwNameLen;
CHAR szName[dwNameLen];

The following list defines each of these fields.
Field
Description
aiAlgid | Algorithm identifier. This is the value that is passed to the CryptGenKey, CryptDeriveKey, or CryptCreateHash functions in order to specify that a particular algorithm be used.
DwBits | Specifies the number of bits in the keys used by the algorithm.
If this is a hash algorithm, this value indicates the number of bits in the hash values generated by this algorithm.
DwNameLen | Specifies the number of characters in the algorithm name, including the terminating zero.
SzName | Null-terminated string that contains the name of the algorithm.

PP_ENUMCONTAINERS
The key container names. When this parameter is specified, the function fills the pbData buffer with the name of one of the key containers maintained by the CSP. This name is in the form of a zero-terminated CHAR string. The PP_ENUMCONTAINERS parameter must be read repeatedly to enumerate all the container names.

These container names are enumerated in the same way as are the CSP's supported algorithms. Refer to the PP_ENUMALGS entry for more information.

PP_IMPTYPE
The CSP implementation type. The pbData buffer will contain a DWORD value that indicates how the CSP is implemented. Common values are:
  • CRYPT_IMPL_HARDWARE
  • CRYPT_IMPL_SOFTWARE
  • CRYPT_IMPL_MIXED
  • CRYPT_IMPL_UNKNOWN
PP_NAME
The CSP name. When this parameter is specified, the function fills the pbData buffer with the name of the CSP. This name is in the form of a zero-terminated CHAR string.

This string is identical to the one passed in the pszProvider parameter of the CryptAcquireContext function in order to specify that the current CSP be used. For example, the Microsoft Base Cryptographic Provider will return "Microsoft Base Cryptographic Provider v1.0" when this parameter is read.

PP_VERSION
The CSP version number. The pbData buffer will contain a DWORD value that indicates the version number of the CSP. The least significant byte contains the minor version number and the next most significant byte the major version number. For example, version 1.0 would be represented here as 0x00000100.

To maintain backward compatibility with earlier versions of these providers, the name retains the "v1.0" designation in later versions. This can be seen in the wincrypt.h header file. Version 2.0 of this provider is currently shipping. To see which version of the provider you have, make a call to CryptGetProvParam with the dwParam argument set to PP_VERSION. For example, if 0x00000200 is returned in pbData, then you have version 2.0.

Algorithm Identifiers

When enumerating algorithms (dwParam == PP_ENUMALGS), your application may need to determine the class of a particular algorithm. For example, you may want to display a list of encryption algorithms to the user and disregard the rest. This can be done with the GET_ALG_CLASS(x) macro. This macro takes an algorithm identifier as an argument and returns a code indicating the general class of algorithm that the identifier belongs to. Common return values include:

  • ALG_CLASS_DATA_ENCRYPT
  • ALG_CLASS_HASH
  • ALG_CLASS_KEY_EXCHANGE
  • ALG_CLASS_SIGNATURE

The following table lists the algorithms supported by the Microsoft Base Cryptographic Provider along with the class of each algorithm.

Name
Identifier
Class
"MD2" | CALG_MD2 | ALG_CLASS_HASH
"MD5" | CALG_MD5 | ALG_CLASS_HASH
"SHA" | CALG_SHA | ALG_CLASS_HASH
"MAC" | CALG_MAC | ALG_CLASS_HASH
"RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE
"RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE
"RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT
"RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT

If your application does not recognize an algorithm identifier, it is not recommended that you use the algorithm. Making use of an unknown cryptographic algorithm can sometimes produce unpredictable results.

Example

This example shows how the list of algorithms supported by a particular CSP is accessed by an application:

HCRYPTPROV hProv; // Handle to CSP
DWORD dwAlgCount;
BYTE *ptr = NULL;
DWORD i;
ALG_ID aiAlgid;
DWORD dwBits;
DWORD dwNameLen;
CHAR szName[100]; // Often allocated dynamically
BYTE pbData[1000]; // Often allocated dynamically
DWORD cbData;
DWORD dwFlags;
CHAR *pszAlgType = NULL;

// Enumerate the supported algorithms.
for(i=0 ; ; i++) {
 // Set the CRYPT_FIRST flag the first time through the loop.
 if(i == 0) {
 dwFlags = CRYPT_FIRST;
 } else {
 dwFlags = 0;
 }

// Retrieve information about an algorithm.
 cbData = 1000;
 if(!CryptGetProvParam(hProv, PP_ENUMALGS, pbData, &cbData, dwFlags)) {
 if(GetLastError() == ERROR_NO_MORE_ITEMS) {
 // Exit the loop.
 break;
 } else {
 printf("Error %x reading algorithm!\n", GetLastError());
 return;
 }
 }

 // Extract algorithm information from the 'pbData' buffer.
 ptr = pbData;
 aiAlgid = *(ALG_ID *)ptr;
 ptr += sizeof(ALG_ID);
 dwBits = *(DWORD *)ptr;
 ptr += sizeof(DWORD);
 dwNameLen = *(DWORD *)ptr;
 ptr += sizeof(DWORD);
 strncpy(szName, ptr, dwNameLen);

 // Determine the algorithm type.
 switch(GET_ALG_CLASS(aiAlgid)) {
 case ALG_CLASS_DATA_ENCRYPT: pszAlgType = "Encrypt ";
  break;
 case ALG_CLASS_HASH: pszAlgType = "Hash ";
  break;
 case ALG_CLASS_KEY_EXCHANGE: pszAlgType = "Exchange ";
  break;
 case ALG_CLASS_SIGNATURE: pszAlgType = "Signature";
  break;
 default: pszAlgType = "Unknown ";
 }

 // Print information about the algorithm.
 printf("Algid:%8.8xh, Bits:%-4d, Type:%s, NameLen:%-2d, Name:%s\n",
 aiAlgid, dwBits, pszAlgType, dwNameLen, szName
 );
}

See Also

CryptAcquireContext, CryptCreateHash, CryptDeriveKey, CryptGenKey, CryptGetKeyParam, CryptSetProvParam


CryptGetUserKey

This function retrieves a handle to a permanent user key pair, such as the user’s signature key pair.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptGetUserKey( HCRYPTPROV hProv,
DWORD dwKeySpec, HCRYPTKEY *phUserKey );

Parameters

hProv
[in] Handle to the application's CSP. An application obtains this handle by using the CryptAcquireContext function.
dwKeySpec
[in] Specifies the key to retrieve. The following keys are retrievable from almost all providers:
  • AT_KEYEXCHANGE. Exchange key pair.
  • AT_SIGNATURE. Signature key pair.

Additionally, some providers allow access to other user-specific keys through this function. See the documentation on the specific provider for details.

phUserKey
[out] Address that the function copies the handle of the retrieved key to.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_KEY | The dwKeySpec parameter contains an invalid value.
NTE_BAD_UID | The hProv parameter does not contain a valid context handle.
NTE_NO_KEY | The key requested by the dwKeySpec parameter does not exist.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTKEY hSignKey = 0;
HCRYPTKEY hXchgKey = 0;

// Get a handle to the user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Get a handle to the signature key.
if(!CryptGetUserKey(hProv, AT_SIGNATURE, &hSignKey)) {
 printf("Error %x during CryptGetUserKey!\n", GetLastError());
 goto done;
}

// Get a handle to the key exchange key.
if(!CryptGetUserKey(hProv, AT_KEYEXCHANGE, &hXchgKey)) {
 printf("Error %x during CryptGetUserKey!\n", GetLastError());
 goto done;
}

// Use the 'hSignKey' to verify a signature, or use 'hXchgKey' to export a key to yourself.
...

done:

// Destroy the signature key handle.
if(hSignKey != 0) CryptDestroyKey(hSignKey);

// Destroy the key exchange key handle.
if(hXchgKey != 0) CryptDestroyKey(hXchgKey);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptDestroyKey, CryptGenKey


CryptHashData

This function is used by applications to feed data to a specified hash object. This function and CryptHashSessionKey can be called multiple times to compute the hash on long streams or on discontinuous streams.

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptHashData( HCRYPTHASH hHash, BYTE *pbData,
DWORD dwDataLen, DWORD dwFlags );

Parameters

hHash
[in] Handle to the hash object. An application obtains this handle by using the CryptCreateHash function.
pbData
[in] Pointer to the data to be hashed.
dwDataLen
[in] Specifies the number of bytes of data to be hashed. This must be zero if the CRYPT_USERDATA flag is set.
dwFlags
[in] Specifies a bitmask of flags.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS | The dwFlags parameter contains an invalid value.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_HASH_STATE | An attempt was made to add data to a hash object that is already marked "finished."
NTE_BAD_KEY | A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key is destroyed before the hashing operation is complete.
NTE_BAD_LEN | The CRYPT_USERDATA flag is set and the dwDataLen parameter has a nonzero value.
NTE_BAD_UID | The CSP context that was specified when the hash object was created cannot be found.
NTE_FAIL | The function failed in some unexpected way.
NTE_NO_MEMORY | The CSP ran out of memory during the operation.

Example

See CryptGetHashParam.

See Also

CryptCreateHash, CryptHashSessionKey, CryptSignHash


CryptHashSessionKey

This function is used to compute the cryptographic hash on a key object. This function can be called multiple times with the same hash handle to compute the hash on multiple keys. Calls to CryptHashSessionKey can be interspersed with calls to CryptHashData.

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptHashSessionKey( HCRYPTHASH hHash,
HCRYPTKEY hKey, DWORD dwFlags );

Parameters

hHash
[in] Handle to the hash object. An application obtains this handle by using the CryptCreateHash function.
hKey
[in] Handle to the key object to be hashed.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_HASH_STATE | An attempt was made to add data to a hash object that is already marked "finished."
NTE_BAD_KEY | A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key is destroyed before the hashing operation is complete.
NTE_BAD_UID | The CSP context that was specified when the hash object was created cannot be found.
NTE_FAIL | The function failed in some unexpected way.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTHASH hHash = 0;
HCRYPTKEY hKey = 0;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
 printf("Error %x during CryptBeginHash!\n", GetLastError());
 goto done;
}

// Create a random session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptGenKey!\n", GetLastError());
 goto done;
}

// Compute the cryptographic hash on the key object.
if(!CryptHashSessionKey(hHash, hKey, 0)) {
 printf("Error %x during CryptHashSessionKey!\n", GetLastError());
 goto done;
}

// Use the hash of the key object. For instance, additional
// data could be hashed and sent in a message to several recipients.
// The recipients will be able to verify who the message originator
// is if the key used is also exported to them..
...

done:

// Destroy the hash object.
if(hHash) CryptDestroyHash(hHash);

// Destroy the session key.
if(hKey) CryptDestroyKey(hKey);

// Release the CSP handle.
if(hProv) CryptReleaseContext(hProv,0);

See Also

CryptCreateHash, CryptGenKey, CryptHashData


CryptImportKey

This function is used to transfer a cryptographic key from a key Binary Large Object (BLOB) to the cryptographic service provider (CSP).

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptImportKey( HCRYPTPROV hProv,
BYTE *pbData, DWORD dwDataLen, HCRYPTKEY hImpKey
DWORD dwFlags, HCRYPTKEY *phKey );

Parameters

hProv
[in] Handle to the application's CSP. An application obtains this handle by using the CryptAcquireContext function.
pbData
[in] Pointer to the buffer containing the key BLOB. This key BLOB was generated by the CryptExportKey function, either by this same application or by another application running on a different computer.

This key BLOB consists of a standard header followed by the encrypted key.

dwDataLen
[in] Specifies the length, in bytes, of the key BLOB.
hPubKey
[in] The meaning of this parameter differs, depending on the CSP type and the type of key BLOB being imported.

If a signed key BLOB is being imported, this key is used to validate the signature of the key BLOB. In this case, this parameter should contain a handle to the key exchange public key of the party that created the key BLOB.

If the key BLOB is encrypted with the key exchange key pair (for example, a SIMPLEBLOB), then this parameter may be the handle to the key exchange key.

If the key BLOB is encrypted with a session key (for example, an encrypted PRIVATEKEYBLOB), then this parameter should contain a handle to this session key.

If the key BLOB is not encrypted (for example, a PUBLICKEYBLOB), then this parameter is not used, and should be zero.

dwFlags
[in] Specifies a bitmask of flags. This parameter is currently used only when a public/private key pair is being imported into the CSP (in the form of a PRIVATEKEYBLOB). In this case, if the key being imported is eventually to be re-exported, then the CRYPT_EXPORTABLE flag must be placed in this parameter. If this flag is not used then calls to CryptExportKey with the key handle will fail.
CRYPT_NO_SALT.
Specifies that a no-salt value gets allocated for a 40-bit symmetric key.
phKey
[out] Address to which the function copies a handle to the key that was imported.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_ALGID | The simple key BLOB you are trying to import is not encrypted with the expected key exchange algorithm.
NTE_BAD_DATA | Either the algorithm that works with the public key you are trying to import is not supported by this CSP, or an attempt was made to import a session key that was encrypted with something other than one of YOUR public keys.
NTE_BAD_FLAGS | The dwFlags parameter specified is invalid.
NTE_BAD_TYPE | The key BLOB type is not supported by this CSP and is possibly invalid.
NTE_BAD_UID | The hProv parameter does not contain a valid context handle.
NTE_BAD_VER | The key BLOB's version number does not match the CSP version. This usually indicates that the CSP needs to be upgraded.

Example

#include <wincrypt.h>

FILE *hSourceFile = NULL;
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
BYTE *pbKeyBlob = NULL;
DWORD dwBlobLen;

// Open the file, getting the file handle 'hSourceFile'.
...

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Read the key BLOB length from the file and allocate memory.
fread(&dwBlobLen, sizeof(DWORD), 1, hSourceFile);
pbKeyBlob = malloc(dwBlobLen);

// Read the key BLOB from the file.
fread(pbKeyBlob, 1, dwBlobLen, hSourceFile);

// Import the key BLOB into the CSP.
if(!CryptImportKey(hProv, pbKeyBlob, dwBlobLen, 0, 0, &hKey)) {
 printf("Error %x during CryptImportKey!\n", GetLastError());
 free(pbKeyBlob);
 goto done;
}

// Free memory.
free(pbKeyBlob);

// Use 'hKey' to perform cryptographic operations.
...

done:

// Destroy the session key.
if(hKey) CryptDestroyKey(hKey);

// Release the provider handle.
if(hProv) CryptReleaseContext(hProv, 0);

See Also

CryptAcquireContext, CryptDestroyKey, CryptExportKey


CryptReleaseContext

This function is used to release a handle to a cryptographic service provider (CSP) and a key container.

This should be performed when the application is finished using the CSP. After this function is called, the CSP handle specified by the hProv parameter is no longer valid. Neither the key container nor any key pairs are destroyed by this function.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptReleaseContext( HCRYPTPROV hProv,
DWORD dwFlags );

Parameters

hProv
[in] Handle to the application's CSP. This is the handle the application obtains by using the CryptAcquireContext function.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_BUSY | The CSP context specified by hProv is currently being used by another process.
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_UID | The hProv parameter does not contain a valid context handle.

Remarks

After this function has been called, the session is over, and all existing session keys and hash objects that were created by using the hProv handle become invalid. In practice, all of these objects should be destroyed (with the CryptDestroyKey and CryptDestroyHash functions) before the CryptReleaseContext function is called.

Example

See CryptHashSessionKey.

See Also

CryptAcquireContext, CryptDestroyKey, CryptDestroyHash


CryptSetHashParam

This function customizes the operations of a hash object. Currently, only a single parameter is defined for this function.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptSetHashParam( HCRYPTHASH hHash,
DWORD dwParam, BYTE *pbData, DWORD dwFlags );

Parameters

hHash
[in] Handle to the hash object on which to set parameters.
dwParam
[in] Specifies the parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[in] Pointer to a parameter data buffer. Place the parameter data in this buffer before calling CryptSetHashParam. The form of this data will vary, depending on the parameter number.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_BUSY | The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID | The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL | The function failed in some unexpected way.

Remarks

The dwParam parameter can be set to one of the following values:

HP_HMAC_INFO
The pbData buffer should contain a pointer to an HMAC_INFO structure that specifies the cryptographic hash algorithm and the inner and outer strings to be used.
HP_HASHVAL
Hash value. The pbData buffer should contain a byte array containing a hash value to place directly into the hash object. Before setting this parameter, the size of the hash value should be determined by reading the HP_HASHSIZE parameter with the CryptGetHashParam function.

Some CSPs will not support this capability. Occasionally, it is convenient to sign a hash value that has been generated elsewhere. This is the usual sequence of operations:

  1. The application creates a hash object with CryptCreateHash.
  2. It specifies a hash value by setting the HP_HASHVAL parameter.
  3. It signs the hash value by using CryptSignHash, obtaining a digital signature block.
  4. It destroys the hash object by using CryptDestroyHash.

Note Some CSP types may add additional parameters that can be set with this function.

Example

// EXAMPLE CODE FOR USING CryptSetHashParam
// Set up the variables.
HCRYPTHASH     hHash; // A handle to the hash object on which to set
 // parameters
DWORD dwParam; // dwParam- paramater # can be HP_HMAC_INFO-
 // initialized elsewhere
BYTE pbData[16]; // The parameter data buffer
DWORD dwFlags = 0;// set to zero
BOOL Return;
Return = CryptSetHashParam(hHash, dwParam, pbData, dwFlags);
if (Return) {
 cout<< "function succeeds"<< endl;
}
else {
 cout<< "retrieve error"<< endl;
}

See Also

CryptCreateHash, CryptDestroyHash, CryptGetHashParam, CryptSetKeyParam, CryptSignHash


CryptSetKeyParam

This function customizes various aspects of a key's operations.

Generally, this function is used to set session-specific parameters on symmetric keys.

The Microsoft Base Cryptographic Provider has no parameters that can be set on key exchange or signature keys. However, custom providers may define parameters that can be set on these keys.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptSetKeyParam( HCRYPTKEY hKey,
DWORD dwParam, BYTE *pbData, DWORD dwFlags );

Parameters

hKey
[in] Handle to the key on which to set parameters.
dwParam
[in] Specifies the parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[in] Pointer to the parameter data buffer. Place the parameter data in this buffer before calling CryptSetKeyParam. The form of this data will vary, depending on the parameter number.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_BUSY | The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_DATA | Either the algorithm that works with the public key you are trying to import is not supported by this CSP, or an attempt was made to import a session key that was encrypted with something other than one of your public keys.
NTE_BAD_KEY | The hKey parameter does not contain a valid handle to a key.
NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID | The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL | The function failed in some unexpected way.
NTE_FIXEDPARAMETERS | Some CSPs will have hard coded P, Q, and G values. If this is the case, then using the KP_P, KP_Q, and KP_G for the value of dwParam will cause this error.

Remarks

For all session key types, the dwParam value can be set to one of the following key parameter types.

KP_SALT
The salt value. The pbData buffer should contain a BYTE array specifying a new salt value. This value is made part of the session key. The size of the salt value will vary depending on the CSP being used, so before setting this parameter, it should be read by using CryptGetKeyParam in order to determine its size.

When you suspect that the base data used for derived keys is less than ideal, salt values are often used to make the session keys more unique. This makes dictionary attacks more difficult.

When using the Microsoft Base Cryptographic Provider, this parameter defaults to zero.

KP_SALT_EX
To set a salt value, a user can call the CryptSetKeyParam function with the KP_SALT_EX parameter value specified and with the pbData parameter pointing to a CRYPTOAPI_BLOB structure containing the salt.
KP_PERMISSIONS
The key permissions flags. The pbData buffer should contain a DWORD value specifying zero or more permission flags. Refer to the CryptGetKeyParam function for a description of these flags.

When using the Microsoft Base Cryptographic Provider, this parameter defaults to 0xFFFFFFFF.

If a DSS key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_P
The pbData buffer should contain a pointer to the prime modulus P from the DSS key BLOB that is to be set. The data is in the form of a BLOB structure where the pbData member is the value and the cbData member is the length of the value. The value is expected with no header information and in little endian form.
KP_Q
The pbData buffer should contain a pointer to the prime Q from the DSS key BLOB that is to be set. The data is in the form of a BLOB structure where the pbData member is the value and the cbData member is the length of the value. The value is expected with no header information and in little endian form.
KP_G
The pbData buffer should contain a pointer to the generator G from the DSS key BLOB that is to be set The data is in the form of a BLOB structure, where the pbData member is the value and the cbData member is the length of the value. The value is expected with no header information and in little endian form.
KP_X
Once the P, Q, and G values have been set, a call can be made to CryptSetKeyParam specifying the KP_X value for dwParam and NULL for the pbData parameter. This will cause the X and Y values to be generated.

If a block cipher session key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_EFFECTIVE_KEYLEN
This parameter may be used only with RC2 keys and has been added due to the previous implementation of CryptSetKeyParam in the Microsoft® Windows NT® version 4.0 Service Pack 2 MS Enhanced Provider. In that implementation the RC2 keys in the Enhanced Provider were 128 bits in strength, but the effective key length used to expand keys into the key table was only 40 bits. This reduced the strength of the algorithm to 40 bits.

To maintain backward compatibility, the previous implementation will remain as is. However, the effective key length may be set to be greater than 40 bits by using this parameter value in the CryptSetKeyParam call. The effective key length is passed in the pbData parameter as a pointer to a DWORD with the effective key length value. The minimum effective key length on the Microsoft Base Cryptographic Provider is 1 and the maximum is 40. In the MS Enhanced Provider the minimum is 1 and the maximum is 1024. The key length must be set prior to encrypting or decrypting with the key.

KP_IV
The initialization vector. The pbData buffer should contain a BYTE array specifying the initialization vector. This array should contain block_length/8 elements. For example, if the block length is 64 bits, the initialization vector will consist of eight bytes.

When using the Microsoft Base Cryptographic Provider, this parameter defaults to zero.

KP_PADDING
The padding mode. The pbData buffer should contain a DWORD value specifying the padding method to be used by the cipher. Following are the padding modes currently defined:

PKCS5_PADDING. PKCS 5 (sec 6.2) padding method.

When using the Microsoft Base Cryptographic Provider, this parameter defaults to PKCS5_PADDING.

KP_MODE
The cipher mode. The pbData buffer should contain a DWORD value specifying the cipher mode to be used. Refer to the CryptGetKeyParam function for a list of the defined cipher modes.

When using the Microsoft Base Cryptographic Provider, this parameter defaults to CRYPT_MODE_CBC.

KP_MODE_BITS
The number of bits to feed back. The pbData buffer contains a DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher mode is used.

When using the Microsoft Base Cryptographic Provider, this parameter defaults to eight.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;

// Get a handle to the user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Create a random block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptGenKey!\n", GetLastError());
 goto done;
}

// Set the cipher mode.
dwMode = CRYPT_MODE_ECB;
if(!CryptSetKeyParam(hKey, KP_MODE, &dwMode, 0)) {
 printf("Error %x during CryptSetKeyParam!\n", GetLastError());
 goto done;
}

// Generate a random initialization vector.
if(!CryptGenRandom(hProv, 8, pbData)) {
 printf("Error %x during CryptGenRandom!\n", GetLastError());
 goto done;
}

// Set the initialization vector.
if(!CryptSetKeyParam(hKey, KP_IV, pbData, 0)) {
 printf("Error %x during CryptSetKeyParam!\n", GetLastError());
 goto done;
}

// Use 'hKey' to encrypt a message.
...

done:

// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptGenKey, CryptGetKeyParam


CryptSetProvider

This function is used to specify the current user default cryptographic service provider (CSP). Typical applications do not use this function. It is intended for use solely by administrative applications.

After this function has been called, any calls this user subsequently makes to CryptAcquireContext specifying the dwProvType provider type but not a provider name result in the pszProvName provider being used.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptSetProvider( LPCTSTR pszProvName,
DWORD dwProvType );

Parameters

pszProvName
[in] Pointer to the null-terminated string that contains the name of the new default CSP. This CSP should have already been installed on the computer.
dwProvType
[in] Specifies the provider type of the CSP defined in the pszProvName parameter.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory during the operation.
Error values returned from the RegCreateKeyEx function. | See RegCreateKeyEx.
Error values returned from the RegSetValueEx function. | See RegSetValueEx.

Remarks

Typical applications do not usually specify a CSP name when calling the CryptAcquireContext function. This gives the users a certain amount of freedom in that they can select a CSP that has an appropriate level of security.

This means that a call to CryptSetProvider will often determine the CSP of a given type used by all applications that run from that point on. With this being the case, the CryptSetProvider function should never be called without the user's consent.

Windows CE does not support the ANSI version of this function.

Example

HCRYPTPROV hProv = 0;

// Specify the default PROV_RSA_SIG provider. Note that this assumes
// that a CSP with a type of PROV_RSA_SIG and named "Joe's Provider"
// has already been installed.
if(!CryptSetProvider(TEXT("Joe's Provider"), PROV_RSA_SIG)) {
 printf("Error %x during CryptSetProvider!\n", GetLastError());
 return;
}

// Get a handle to the provider that you just made the default.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_SIG, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 return;
}

...

// Release the provider handle.
if(!CryptReleaseContext(hProv, 0)) {
 printf("Error %x during CryptReleaseContext!\n", GetLastError());
 return;
}

See Also

CryptAcquireContext


CryptSetProviderEx

This function is used to specify either the current user default cryptographic service provider (CSP) or the machine default CSP.

A current user default CSP takes precedence over the machine default. If the current user default CSP is specified, then after this function has been called, any calls this user subsequently makes to CryptAcquireContext specifying the dwProvType provider type but not a provider name result in the pszProvName provider being used. In the case where the machine default is specified, subsequent calls to CryptAcquireContext by a user with no default CSP as described above result in the pszProvName provider being used.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptSetProviderEx( LPCTSTR pszProvName,
DWORD dwProvType, DWORD *pdwReserved, DWORD dwFlags );

Parameters

pszProvName
[in] Pointer to the null-terminated string that contains the name of the new default CSP. This CSP should have already been installed on the computer.
dwProvType
[in] Specifies the provider type of the CSP specified by the pszProvName parameter.
pdwReserved
[in] Reserved for future use ; set to NULL.
dwFlags
[in] Specifies a bitmask of flags. It is one of the following values:
Value
Description
CRYPT_MACHINE_DEFAULT | Causes the machine default CSP of the given type to be set.
CRYPT_USER_DEFAULT | Causes the user default CSP of the given type to be set.
CRYPT_DELETE_DEFAULT | Can be used in conjunction with CRYPT_MACHINE_DEFAULT or CRYPT_USER_DEFAULT to delete the default.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_NOT_ENOUGH_MEMORY | The operating system ran out of memory.

Remarks

Most applications will not specify a CSP name when calling the CryptAcquireContext function. This gives the users a certain amount of freedom in that they can select a CSP that has an appropriate level of security.

This means that calls to CryptSetProviderEx will often determine the CSP of a given type used by all applications from that point on. With this being the case, CryptSetProviderEx should never be called without the user's consent.

Windows CE does not support the ANSI version of this function.

Example

HCRYPTPROV hProv = 0;

// Specify the default PROV_RSA_SIG provider for the machine. Note that this assumes that a
// CSP with a type of PROV_RSA_SIG and named "Joe's Provider" has already been installed.
if (!CryptSetProviderEx(TEXT("Joe's Provider"), PROV_RSA_SIG, NULL,
 CRYPT_MACHINE_DEFAULT))
 {printf("Error %x during CryptSetProviderEx!\n", GetLastError);
 return;
 }

// Get a handle to the provider you just made default
if (!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_SIG, 0))
 {printf("Error %x during CryptAcquireContext!\n", GetLastError);
 return;
 }

...

// Release the provider handle.
if (!CryptReleaseContext(hProv, 0))
 {printf("Error %x during CryptReleaseContext!\n", GetLastError);
 return;
 }

See Also

CryptAcquireContext, CryptSetProvider


CryptSetProvParam

This function customizes the operations of a cryptographic service provider (CSP).

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CRYPTFUNC CryptoSetProvParam( HCRYPTPROV hProv,
DWORD dwParam, BYTE *pbData, DWORD dwFlags );

Parameters

hProv
[in] Handle to the CSP on which to set parameters.
dwParam
[in] Specifies the parameter number to set. The following values are currently defined (see "Remarks" for additional details):
Value
Description
PP_CLIENT_HWND | Specifies that a window handle is contained in pbData.
PP_KEYSET_SEC_DESCR | Specifies that the security descriptor on the entry where the stored key set is being assigned, and its value is contained in pbData.

pbData
[in] Pointer to the parameter data buffer. Place the parameter data in this buffer before calling CryptSetProvParam. The form of this data will vary, depending on the parameter number.
dwFlags
[in] Specifies a bitmask of flags. When dwParam is PP_KEYSET_SEC_DESCR, dwFlags contains the SECURITY_INFORMATION applicable bit flags (can be combined with a bitwise OR operation), as defined in the Win32 Programmer's Reference. See CryptGetProvParam for additional details.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_BUSY | The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID | The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL | The function failed in some unexpected way.

Remarks

Microsoft Cryptographic Service Providers do not support the PP_CLIENT_HWND or PP_KEYSET_SEC_DESCR flags.

See Also

CryptAcquireContext, CryptGetProvParam, CryptSetKeyParam


CryptSignHash

This function is used to sign a piece of data. Because all signature algorithms are asymmetric and therefore slow, the CryptoAPI does not let data be signed directly. Instead, you must first hash the data and then use CryptSignHash to sign the hash value.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptSignHash( HCRYPTHASH hHash,
DWORD dwKeySpec, PCTSTR sDecription, DWORD dwFlags,
BYTE *pbSignature, DWORD *pdwSigLen );

Parameters

hHash
[in] Handle to the hash object to be signed.
dwKeySpec
[in] Specifies the key pair to use to sign the hash. The following keys can be specified.
Value
Description
AT_KEYEXCHANGE | Exchange private key
AT_SIGNATURE | Signature private key

The signature algorithm used is specified when the key pair was originally created.

The only signature algorithm that the Microsoft Base Cryptographic Provider supports is the RSA Public-Key algorithm.

sDescription
[in] No longer used; set to NULL to prevent security vulnerabilities. However, it is still supported for backward compatibility in the Microsoft Base Cryptographic Provider.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.
pbSignature
[out] Pointer to a buffer that receives the signature data.

This parameter can be NULL to set the size of this information for memory allocation purposes.

pdwSigLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pdwSigLen parameter. When the function returns, the variable pointed to by the pdwSigLen parameter contains the number of bytes stored in the buffer.

Note that when processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA | If the buffer specified by the pbSignature parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, into the variable pointed to by pdwSigLen.
NTE_BAD_ALGID | The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_UID | The CSP context that was specified when the hash object was created cannot be found.
NTE_NO_KEY | The private key specified by dwKeySpec does not exist.
NTE_NO_MEMORY | The CSP ran out of memory during the operation.

Remarks

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object. The CryptHashData or CryptHashSessionKey function is then used to add the data or session keys to the hash object.

After this function has been completed, the only hash function that can be called using the hHash handle is the CryptDestroyHash function.

Windows CE does not support the ANSI version of this function.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
#define BUFFER_SIZE 256
BYTE pbBuffer[BUFFER_SIZE];
HCRYPTHASH hHash = 0;
BYTE *pbSignature = NULL;
DWORD dwSigLen;
LPTSTR szDescription = TEXT("Test Data");
DWORD i;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Fill the buffer with test data.
for(i = 0 ; i < BUFFER_SIZE ; i++) {
 pbBuffer[i] = (BYTE)i;
}

// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
 printf("Error %x during CryptCreateHash!\n", GetLastError());
 goto done;
}

// Compute the cryptographic hash of the buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {
 printf("Error %x during CryptHashData!\n", GetLastError());
 goto done;
}

// Determine the size of the signature and allocate memory.
dwSigLen= 0;
if(!CryptSignHash(hHash, AT_SIGNATURE, TEXT(""), 0, NULL,
 &dwSigLen)) {
 printf("Error %x during CryptSignHash!\n", GetLastError());
 if(GetLastError()!=NTE_BAD_LEN) goto done;
}
if((pbSignature = malloc(dwSigLen)) == NULL) {
 printf("Out of memory!\n");
 goto done;
}

// Sign the hash object.
if(!CryptSignHash(hHash, AT_SIGNATURE, szDescription, 0, pbSignature,
 &dwSigLen)) {
 printf("Error %x during CryptSignHash!\n", GetLastError());
 goto done;
}

// Store or transmit the signature, test buffer, and description string.
...

done:

// Free memory to be used to store signature.
if(pbSignature != NULL) free(pbSignature);

// Destroy the hash object.
if(hHash != 0) CryptDestroyHash(hHash);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

See Also

CryptCreateHash, CryptDestroyHash, CryptHashData, CryptHashSessionKey, CryptVerifySignature


CryptVerifySignature

This function is used to verify a signature against a hash object.

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object. The CryptHashData and/or CryptHashSessionKey functions are then used to add the data and/or session keys to the hash object.

After this function has been completed, the only hash function that can be called by using the hHash handle is the CryptDestroyHash function.

At a Glance

Header file: | Wincrypt.h
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI CryptVerifySignature( HCRYPTHASH hHash,
BYTE *pbSignature, DWORD dwSigLen, HCRYPTKEY hPubKey,
LPCTSTR sDescription, DWORD dwFlags );

Parameters

hHash
[in] Handle to the hash object to verify against.
pbSignature
[in] Pointer to the signature data to be verified.
dwSigLen
[in] Specifies the number of bytes in the pbSignature signature data.
hPubKey
[in] Handle to the public key to use to authenticate the signature. This public key must belong to the key pair that was originally used to create the digital signature.
sDescription
[in] No longer used; set to NULL to prevent security vulnerabilities. However, it is still supported for backward compatibility in the Microsoft Base Cryptographic Provider.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value
Description
ERROR_INVALID_HANDLE | One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER | One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS | The dwFlags parameter is nonzero.
NTE_BAD_HASH | The hash object specified by the hHash parameter is invalid.
NTE_BAD_KEY | The hPubKey parameter does not contain a handle to a valid public key.
NTE_BAD_SIGNATURE The signature was not verified. This could be because the data itself has changed, the Meaning string did not match, or the wrong public key was specified by hPubKey.

This error can also be returned if the hashing or signature algorithms do not match the ones used to create the signature.
NTE_BAD_UID | The CSP context that was specified when the hash object was created cannot be found.
NTE_NO_MEMORY | The CSP ran out of memory during the operation.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
#define BUFFER_SIZE 256
BYTE pbBuffer[BUFFER_SIZE];
HCRYPTHASH hHash = 0;
HCRYPTKEY hPubKey = 0;
BYTE *pbSignature = NULL;
DWORD dwSigLen;
LPTSTR szDescription = NULL;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Load 'pbBuffer' with 'BUFFER_SIZE' bytes of test data. This must
// be the same data that was originally signed.
...
// Point 'pbSignature' at the signature created by a previous call
// to CryptSignHash. Set 'dwSigLen' to the number of bytes in the
// signature.
...

// Point 'szDescription' at the text describing the data being
// signed. This must be the same description text that was originally
// passed to CryptSignHash.
...

// Get the public key of the user who created the digital signature
// and import it into the CSP by using CryptImportKey. This will return
// a handle to the public key in 'hPubKey'.
...

// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
 printf("Error %x during CryptCreateHash!\n", GetLastError());
 goto done;
}

// Compute the cryptographic hash of the buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {
 printf("Error %x during CryptHashData!\n", GetLastError());
 goto done;
}

// Validate the digital signature.
if(!CryptVerifySignature(hHash, pbSignature, dwSigLen, hPubKey,
 szDescription, 0)) {
 if(GetLastError() == NTE_BAD_SIGNATURE) {
 printf("Signature not validated!\n");
 } else {
 printf("Error %x during CryptVerifySignature!\n",
 GetLastError());
 }
} else {
 printf("Signature validated\n");
}

done:
...

// Release the public key.
if(hPubKey != 0) CryptDestroyKey(hPubKey);

// Destroy the hash object.
if(hHash != 0) CryptDestroyHash(hHash);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

Remarks

Windows CE does not support the ANSI version of this function.

See Also

CryptCreateHash, CryptDestroyHash, CryptHashData, CryptHashSessionKey, CryptSignHash


DeleteSecurityContext

This function deletes local data structures associated with the specified security context.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS DeleteSecurityContext( PCtxtHandle phContext );

Parameters

phContext
[in] Pointer to the context handle to delete

Return Values

SEC_E_OK indicates success. Upon failure, SEC_E_INVALID_HANDLE indicates that the handle passed to the function is invalid.

Remarks

The DeleteSecurityContext function terminates a security context. No further use of the context is accepted.


DeleteUrlCacheEntry

This function removes the file associated with the source name from the cache, if the file exists.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL DeleteUrlCacheEntry ( LPCTSTR lpszUrlName );

Parameters

lpszUrlName
[in] Address of a string variable that contains the cache entry source name. The name string must be unique and cannot contain escape characters.

Return Values

Returns TRUE if successful, or FALSE otherwise

See Also

CommitUrlCacheEntry , CreateUrlCacheEntry


DeleteUrlCacheGroup

This function releases the specified GROUPID and associated state in the cache index file.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL DeleteUrlCacheGroup ( GROUPID GroupId,
DWORD dwFlags, LPVOID lpReserved);

Parameters

GroupId
[in] GROUPID value associated with the cache group to be released.
dwFlags
[in] Unsigned long integer value containing the flags to control the cache group deletion. This can be set to CACHEGROUP_FLAG_FLUSHURL_ONDELETE, which deletes all cache entries associated with this group, unless the entry belongs to another group.
lpReserved
[in] Reserved; set to NULL.

Return Values

Returns TRUE if successful, or FALSE otherwise

See Also

CreateUrlCacheGroup


EnumerateSecurityPackages

This function returns an array of SecPkgInfo structures that describe the security packages available to the client.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS EnumerateSecurityPackages( PULONG pcPackages,
PSecPkgInfo *ppPackageInfo );

Parameters

pcPackages
[out] Pointer to a ULONG variable that receives the number of packages returned
ppPackageInfo
[out] Pointer to a variable that receives a pointer to an array of SecPkgInfo structures. Each structure contains data that describes a security package available from the security provider.

Return Values

SEC_E_OK indicates success. A nonzero error value indicates failure.

Remarks

The SecPkgInfo structures provide data that the caller can use to determine which security package best satisfies the caller’s requirements.

The caller can use the Name member of a SecPkgInfo structure to specify a security package in a call to the AcquireCredentialsHandle function.

The caller must assume that the security provider includes all available security packages in the single call to EnumerateSecurityPackages.

The caller must call the FreeContextBuffer function to free the buffer returned in ppPackageInfo.

See Also

AcquireCredentialsHandle, FreeContextBuffer, SecPkgInfo


EscapeCommFunction

This function directs a specified communication device to perform an extended function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EscapeCommFunction(HANDLE hFile, DWORD dwFunc);

Parameters

hFile
[in] Handle to the communication device. The CreateFile function returns this handle.
dwFunc
[in] Specifies the extended function code to perform. It can be one of the following values:
Value
Description
SETIR | Sets the serial port to infrared (IR) mode.
CLRIR | Sets port to normal serial mode.
CLRDTR | Clears the DTR (Data Terminal Ready) signal.
CLRRTS | Clears the RTS (Request To Send) signal.
SETDTR | Sends the DTR (Data Terminal Ready) signal.
SETRTS | Sends the RTS (Request To Send) signal.
SETXOFF | Causes transmission to act as if an XOFF character has been received.
SETXON | Causes transmission to act as if an XON character has been received.
SETBREAK | Suspends character transmission and places the transmission line in a break state until the ClearCommBreak function is called (or EscapeCommFunction is called with the CLRBREAK extended function code). The SETBREAK extended function code is identical to the SetCommBreak function. This extended function does not flush data that has not been transmitted.
CLRBREAK | Restores character transmission and places the transmission line in a nonbreak state. The CLRBREAK extended function code is identical to the ClearCommBreak function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error data, call GetLastError.

See Also

ClearCommBreak, CreateFile, SetCommBreak


FindCloseUrlCache

This function closes the specified cache enumeration handle.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL FindCloseUrlCache( HANDLE hEnumHandle);

Parameters

hEnumHandle
[in] Handle returned by a previous call to the FindFirstUrlCacheEntry function

Return Values

Returns TRUE if successful, or FALSE otherwise

See Also

FindFirstUrlCacheEntry


FindFirstUrlCacheEntry

This function begins the enumeration of the Internet cache.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

HANDLE FindFirstUrlCacheEntry( LPCTSTR lpszUrlSearchPattern,
LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
LPDWORD lpdwFirstCacheEntryInfoBufferSize);

Parameters

lpszUrlSearchPattern
[in] Address of a string that contains the source name pattern to search for. This can be set to "cookie:" or "visited:" to enumerate the cookies and Uniform Resource Locator (URL) History entries in the cache. If this parameter is NULL, the function uses *.*.
lpFirstCacheEntryInfo
[out] Address of an INTERNET_CACHE_ENTRY_INFO structure.
lpdwFirstCacheEntryInfoBufferSize
[in/out] Address of an unsigned long integer variable that specifies the lpFirstCacheEntryInfo buffer size, in bytes. When the function returns, the variable contains the number of bytes copied to the buffer, or the required buffer size.

Return Values

If successful, this function returns a handle that the application can use in the FindNextUrlCacheEntry function to retrieve subsequent cache entries. If the function fails, the return value is NULL.

ERROR_INSUFFICIENT_BUFFER indicates that the size of lpFirstCacheEntryInfo as specified by lpdwFirstCacheEntryInfoBufferSize is not sufficient to contain all the data. The value returned in lpdwFirstCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the data.

Remarks

This function and FindNextUrlCacheEntry return variable size data. If ERROR_INSUFFICIENT_BUFFER is returned, the application should allocate a buffer of the size specified by lpdwFirstCacheEntryInfoBufferSize.

See Also

FindNextUrlCacheEntry


FindFirstUrlCacheEntryEx

This function begins a filtered enumeration of the Internet cache.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

HANDLE FindFirstUrlCacheEntryEx( LPCWSTR lpszUrlSearchPattern,
DWORD dwFlags, DWORD dwFilter, GROUPID GroupId, LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
LPDWORD lpdwFirstCacheEntryInfoBufferSize,
LPVOID lpGroupAttributes, LPDWORD pcbGroupAttributes, LPVOID lpReserved);

Parameters

lpszUrlSearchPattern
[in] Address of a string that contains the source name pattern to search for. This can be set to "cookie:" or "visited:" to enumerate the cookies and Uniform Resource Locator (URL) History entries in the cache. If this parameter is NULL, the function uses *.*.
dwFlags
[in] Unsigned long integer value containing the flags controlling the enumeration. No flags are currently implemented. Must be set to zero.
dwFilter
[in] Unsigned long integer value that indicates the cache entry types accepted. This can be a combination of cache entry types:
Value
Description
COOKIE_CACHE_ENTRY | Cookie cache entry.
NORMAL_CACHE_ENTRY | Normal cache entry; can be deleted to recover space for new entries.
STICKY_CACHE_ENTRY | Sticky cache entry; exempt from scavenging.
TRACK_OFFLINE_CACHE_ENTRY | Not currently implemented.
TRACK_ONLINE_CACHE_ENTRY | Not currently implemented.
URLHISTORY_CACHE_ENTRY | Visited link cache entry.

GroupId
[in] GROUPID value indicating the cache group to enumerate. Set the value to zero to enumerate all entries not grouped.
lpFirstCacheEntryInfo
[out] Address of an INTERNET_CACHE_ENTRY_INFO structure.
lpdwFirstCacheEntryInfoBufferSize
[in/out] Address of an unsigned long integer variable that specifies the lpFirstCacheEntryInfo buffer size, in bytes. When the function returns, the variable contains the number of bytes copied to the buffer, or the required buffer size.
lpGroupAttributes
Reserved; set to NULL.
pcbGroupAttributes
Reserved; set to NULL.
lpReserved
Reserved; set to NULL.

Return Values

Returns a valid handle if successful, or NULL otherwise

Remarks

At the end of the enumeration, the application should call FindCloseUrlCache.

See Also

FindCloseUrlCache, FindNextUrlCacheEntry


FindNextUrlCacheEntry

This function retrieves the next entry in the Internet cache.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL FindNextUrlCacheEntry ( HANDLE hEnumHandle,
LPINTERNET_CACHE_ENTRY_INFO lpNextCacheEntryInfo,
LPDWORD lpdwNextCacheEntryInfoBufferSize );

Parameters

hEnumHandle
[in] Enumeration handle obtained from a previous call to FindFirstUrlCacheEntry.
lpNextCacheEntryInfo
[out] Address of an INTERNET_CACHE_ENTRY_INFO structure that receives cache entry data.
lpdwNextCacheEntryInfoBufferSize
[in/out] Address of an unsigned long integer variable that specifies the lpNextCacheEntryInfo buffer size, in bytes. When the function returns, the variable contains the number of bytes copied to the buffer, or the required buffer size.

Return Values

Returns TRUE if successful, or FALSE otherwise

See Also

FindFirstUrlCacheEntry


FindNextUrlCacheEntryEx

This function finds the next cache entry in a cache enumeration started by the FindFirstUrlCacheEntryEx function.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOLAPI FindNextUrlCacheEntryEx ( HANDLE hEnumHandle,
LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
LPDWORD lpdwFirstCacheEntryInfoBufferSize, LPVOID lpGroupAttributes
LPDWORD pcbGroupAttributes, LPVOID lpReserved );

Parameters

hEnumHandle
[in] Enumeration handle obtained from a previous call to FindFirstUrlCacheEntryEx.
lpFirstCacheEntryInfo
[out] Address of the buffer to hold the INTERNET_CACHE_ENTRY_INFO structure in which the cache entry data is stored.
lpdwFirstCacheEntryInfoBufferSize
[in/out] Address of an unsigned long integer variable that specifies the buffer size, in bytes.
lpGroupAttributes
Reserved; set to NULL.
pcbGroupAttributes
Reserved; set to NULL.
lpReserved
Reserved; set to NULL.

Return Values

Returns TRUE if successful, or FALSE otherwise

Remarks

At the end of the enumeration, the application should call FindCloseUrlCache.

See Also

FindFirstUrlCacheEntryEx, FindCloseUrlCache


FreeContextBuffer

This function enables callers of security provider functions to free a memory buffer allocated by the security provider. For example, the InitializeSecurityContext function may allocate a buffer for returning the outbound context token.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS FreeContextBuffer( PVOID pvContextBuffer);

Parameters

pvContextBuffer
Void pointer to memory allocated by the security provider

Return Values

SEC_E_OK indicates success. A nonzero error value indicates failure.

Remarks

The FreeContextBuffer function can free memory allocated by a security package.

See Also

InitializeSecurityContext


FreeCredentialsHandle

This function notifies the security system that credentials are no longer required. An application calls this function to free the credential handle acquired in the call to the AcquireCredentialsHandle function. When all references to this credential set have been removed, the credentials themselves can be removed.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS FreeCredentialsHandle( PCredHandle phCredential);

Parameters

phCredential
Pointer to the credential handle obtained by using the AcquireCredentialsHandle function

Return Values

SEC_E_OK indicates success. Upon failure, SEC_E_INVALID_HANDLE indicates that the handle passed to the function is invalid.

Remarks

The FreeCredentialsHandle function enables the security system to free resources associated with the credential handle.

See Also

AcquireCredentialsHandle


FtpCommand

This function issues an arbitrary FTP command to the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpCommand(HINTERNET hConnect, BOOL fExpectResponse, DWORD dwFlags, LPCTSTR lpszCommand, DWORD dwContext);

Parameters

hConnect
[in] Valid handle for an FTP session.
fExpectResponse
[in] Boolean that specifies if a data response is expected. If fExpectResponse is TRUE, a data response is expected, and the application can call the InternetReadFile function to read the response.
dwFlag
[in] Specifies the conditions under which the data connection takes place. The following flags can be set:
Value
Description
FTP_TRANSFER_TYPE_ASCII | Data connection using the FTP ASCII ,Type A, transfer method. Control and formatting data is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY | Data connection using the FTP Image, Type I, transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.

LpszCommand
[in] Long pointer to the null-terminated string that contains an FTP command, for example, “PWD \r\n”.
dwContext
[in] Specifies an application-defined value that associates the FTP command in a status callback.

Remarks

Inetftp.dll is available only for Intel x86 processors.

The dwContext parameter accepts status callbacks to the application, but all requests are handled synchronously.


FtpCreateDirectory

This function creates a new directory on the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpCreateDirectory(HINTERNET hConnect, LPCTSTR lpszDirectory);

Parameters

hConnect
[in] Valid handle to an FTP session. This handle must have been returned by a previous call to the InternetConnect function.
lpszDirectory
[in] Long pointer to a null-terminated string that contains the name of the directory to create on the remote system. This can be either a fully qualified path or a name relative to the current directory.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError. If the error message indicates that the FTP server denied the request to create a directory, use the InternetGetLastResponseInfo function to determine the cause.

Remarks

Inetftp.dll is available only for Intel x86 processors.

An application should use the FtpGetCurrentDirectory function to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpCreateDirectory translates the directory name separators to the appropriate character before they are used.


FtpDeleteFile

This function deletes a file stored on the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpDeleteFile(HINTERNET hConnect, LPCTSTR lpszFileName);

Parameters

hConnect
[in] Valid handle to an FTP session. This handle must have been returned by a previous call to the InternetConnect function.
lpszFileName
[in] Long pointer to a null-terminated string that contains the file name to delete on the remote system.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError.

Remarks

Inetftp.dll is available only for Intel x86 processors.

The lpszFile parameter can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpDeleteFile translates the directory name separators to the appropriate character before they are used.


FtpFindFirstFile

This function searches the specified directory of the specified FTP session. File and directory entries are returned to the application in the WIN32_FIND_DATA structure.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpFindFirstFile(HINTERNET hConnect, LPCTSTR lpszSearchFile , LPWIN32_FIND_DATA lpFindFileData , DWORD dwFlags, DWORD dwContext);

Parameters

hConnect
[in] Valid handle to an FTP session returned by the InternetConnect function.
lpszSearchFile
[in] Long pointer to a null-terminated string that specifies a valid directory path or file name for the FTP server file system. The string can contain wildcards, but blank spaces are not accepted. If the value of lpszSearchFile is NULL or if it is an empty string, it will find the first file in the current directory on the server.
lpFindFileData
[out] Long pointer to a WIN32_FIND_DATA structure that receives data about the found file or directory.
dwFlags
[in] Specifies an application-defined value that associates this search with an application. It is one of the following values:
Value
Description
INTERNET_FLAG_DONT_CACHE | Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK | Forces a reload if there was no Expires time and no Last-Modified time returned by the server when determining whether to reload the item from the network.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE | Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD | Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE | Causes the FTP resource to be reloaded from the server.

dwContext
[in] Specifies an application-defined value that associates this search with application data. This parameter is used only if the application has already called the InternetSetStatusCallback function to set up a status callback function. All status requests are handled synchronously.

Return Values

A valid handle for the request if the directory enumeration was started indicates success. NULL indicates failure. To get extended error data, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.

Remarks

Inetftp.dll is available only for Intel x86 processors.

This function enumerates both files and directories.

FtpFindFirstFile is similar to the Win32 FindFirstFile function. Note, however, that only one FtpFindFirstFile can occur at a time within a given FTP session. The enumerations, therefore, are correlated with the FTP session handle. This is because the FTP protocol accepts only one directory enumeration per session.

After calling FtpFindFirstFile and until calling the InternetCloseHandle function, the application cannot call FtpFindFirstFile again on the given FTP session handle. If a call is made to FtpFindFirstFile on that handle, the function will fail with ERROR_FTP_TRANSFER_IN_PROGRESS.

After beginning a directory enumeration with FtpFindFirstFile, the InternetFindNextFile function can be used to continue the enumeration.

InternetCloseHandle closes the handle returned by FtpFindFirstFile. If InternetCloseHandle closes the handle before InternetFindNextFile fails with ERROR_NO_MORE_FILES, the directory enumeration will be terminated.

Because the FTP protocol provides no standard means of enumerating, common file data, such as file creation date and time, is not always available or correct. When this happens, FtpFindFirstFile and InternetFindNextFile fill in unavailable data with an estimate. For example, creation and last access dates will often be the same as the file modification date.

The application cannot call FtpFindFirstFile between calls to FtpOpenFile and InternetCloseHandle.

See Also

InternetSetStatusCallback


FtpGetCurrentDirectory

This function retrieves the current directory for the specified FTP session.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpGetCurrentDirectory(HINTERNET hConnect, LPCTSTR lpszDirectory, LPDWORD lpdwDirectoryLength);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszCurrentDirectory
[out] Long pointer to a buffer that receives the null-terminated string that contains the absolute path to the current directory.
lpdwCurrentDirectory
[in/out] Long pointer to a variable that specifies the buffer length, in characters, for the current directory string. The buffer length must include room for a terminating null character. Using a length of MAX_PATH is sufficient for all paths. When the function returns, the variable receives the number of characters copied into the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError.

Remarks

Inetftp.dll is available only for Intel x86 processors.

If the lpszCurrentDirectory buffer is not large enough, lpdwCurrentDirectory receives the number of bytes required to retrieve the full, current directory name.


FtpGetFile

This function retrieves a file from the FTP server and stores it under the specified file name, creating a new local file in the process.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpGetFile(HINTERNET hConnect, LPCTSTR lpszRemoteFile, LPCTSTR lpszNewFile, BOOL fFailIfExists, DWORD dwFlagsAndAttributes, DWORD dwFlags, DWORD dwContext);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszRemoteFile
[in] Long pointer to a null-terminated string that contains the file name to retrieve from the remote system.
lpszNewFile
[in] Long pointer to a null-terminated string that contains the file name to create on the local system.
fFailIfExists
[in] Boolean that specifies if the function should proceed if a local file of the specified name already exists. If fFailIfExists is TRUE and the local file exists, FtpGetFile fails.
dwLocalFlagsAndAttributes
[in] Specifies the file attributes for the new file. Can be a combination of the FILE_ATTRIBUTE_* flags used by the CreateFile function.
dwInternetFlags
[in] Specifies how the function will handle the file download. The first set of flag values indicates the conditions under which the transfer occurs. These transfer type flags can be used in combination with the second set of flags that control caching. The application can select one of these transfer type values:
Value
Description
FTP_TRANSFER_TYPE_ASCII | Transfers the file using FTP ASCII, Type A, transfer method. Control and formatting data is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY | Transfers the file using FTP Image, Type I, transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN | Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII | Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY | Transfers the file as binary.
The following flags determine how the file caching will be done. A combination of the following flags can be used with the transfer type flag. Possible values are described in the following table.
INTERNET_FLAG_DONT_CARE | Does not add the returned entity to the cache. Identical to the preferred value INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK | Forces a reload if there was no Expires time and no Last-Modified time returned by the server when determining whether to reload the item from the network.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE | Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD | Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE | Causes the FTP resource to be reloaded from the server.

dwContext
[in] Specifies an application-defined value that associates this search with application data. This is used only if the application has already called InternetSetStatusCallback to set up a status callback function. All status requests are handled synchronously.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError.

Remarks

Inetftp.dll is available only for Intel x86 processors.

FtpGetFile is a high-level routine that handles all the bookkeeping and overhead associated with reading a file from an FTP server and storing it locally. An application that needs to retrieve file data only or that requires close control over the file transfer should use the FtpOpenFile and InternetReadFile functions.

If the dwTransferType parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data converts control and formatting characters to local equivalents. The default transfer is binary mode, where the file is downloaded in the same format as it is stored on the server.

Both lpszRemoteFile and lpszNewFile can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpGetFile translates the directory name separators to the appropriate character before they are used.


FtpOpenFile

This function initiates access to a remote file for writing or reading.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpOpenFile(HINTERNET hConnect, LPCTSTR lpszFileName, DWORD dwAccess, DWORD dwFlags, DWORD dwContext);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszFileName
[in] Long pointer to a null-terminated string that contains the name of the file to access on the remote system.
fdwAccess
[in] Value that determines how the file will be accessed. This can be GENERIC_READ or GENERIC_WRITE, but not both.
dwFlags
[in] Specifies the conditions under which the transfers occur. The application should select one transfer type and flags that control file caching. The transfer type can be one of the following values:
Value
Description
FTP_TRANSFER_TYPE_ASCII | Transfers the file using FTP ASCII, Type A, transfer method. Control and formatting data is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY | Transfers the file using FTP Image, Type I, transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN | Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII | Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY | Transfers the file as binary.
One or more of the values described in the following table are used by an application to control file caching.
INTERNET_FLAG_DONT_CACHE | Does not cache the data, either locally or in gateways. Identical to the preferred value INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK | Forces a reload if there was no Expires time and no Last-Modified time returned by the server when determining whether to reload the item from the network.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE | Does not cache the data, either locally or in gateways.
INTERNET_FLAG_RELOAD | Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE | Causes the FTP resource to be reloaded from the server.

dwContext
[in] Specifies an application-defined value that associates this search with application data. This is only used if the application has already called InternetSetStatusCallback to set up a status callback function. All status requests are handled synchronously.

Return Values

A handle indicates success. NULL indicates failure. To get extended error data, call GetLastError.

Remarks

Inetftp.dll is available only for Intel x86 processors.

FtpOpenFile should be used in the following situations:

An application has data it needs to send to an FTP server to be created as a file on the FTP server, but the application does not have a local file containing the data. After the file is opened with FtpOpenFile, the application uses InternetWriteFile to send the FTP file data to the server.

An application needs to retrieve a file from the server into application-controlled memory, instead of writing the file to disk. The application uses InternetReadFile after using FtpOpenFile to open the file.

An application needs a fine level of control over a file transfer. For example, the application may need to display a progress indicator when downloading a file to indicate to the user that the file transfer is, or is not, proceeding correctly.

After calling FtpOpenFile and until calling InternetCloseHandle, all other calls to FTP functions on the same FTP session handle will fail and set the error message to ERROR_FTP_TRANSFER_IN_PROGRESS.

Only one file can be open in a single FTP session. Therefore, no file handle is returned and the application simply uses the FTP session handle when necessary.

The lpszFile parameter can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpOpenFile translates the directory name separators to the appropriate character before they are used.

The InternetCloseHandle function is used to close the handle returned by FtpOpenFile. If InternetCloseHandle closes the handle before all the data has been transferred, the transfer is terminated.


FtpPutFile

This function stores a file on the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpPutFile(HINTERNET hConnect, LPCTSTR lpszLocalFile, LPCTSTR lpszNewRemoteFile, DWORD dwFlags, DWORD dwContext);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszLocalFile
[in] Long pointer to a null-terminated string that contains the file name to send from the local system.
lpszNewRemoteFile
[in] Long pointer to a null-terminated string that contains the file name to create on the remote system.
dwFlags
[in] Specifies the conditions under which the transfer occurs. Can be a combination of the following values:
Value
Description
INTERNET_FLAG_DONT_CACHE | Does not add the returned entity to the cache. Identical to the preferred value INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK | Forces a reload if there was no Expires time and no Last-Modified time returned by the server when determining whether to reload the item from the network.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE | Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD | Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCRONIZE | Performs a conditional download of the file.
INTERNET_FLAG_TRANSFER_ASCII | Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY | Transfers the file as binary.

dwContext
[in] Specifies an application-defined value that associates this search with application data. This parameter is used only if the application has already called InternetSetStatusCallback to set up a status callback. All status requests are handled synchronously.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError.

Remarks

Inetftp.dll is available only for Intel x86 processors.

FtpPutFile is a high-level routine that handles all the bookkeeping and overhead associated with reading a file locally and storing it on an FTP server. An application that needs to send file data only, or that requires close control over the file transfer, should use the FtpOpenFile and InternetWriteFile functions.

If the dwTransferType parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data converts control and formatting characters to local equivalents.

Both lpszNewRemoteFile and lpszLocalFile can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpPutFile translates the directory name separators to the appropriate character before they are used.


FtpRemoveDirectory

This function removes the specified directory on the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpRemoveDirectory(HINTERNET hConnect, LPCTSTR lpszDirectory);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszDirectory
[in] Long pointer to a null-terminated string that contains the name of the directory to remove on the remote system. This can be either a fully qualified path or a name relative to the current directory.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError. If the error message indicates that the FTP server denied the request to remove a directory, use InternetGetLastResponseInfo to determine the cause.

Remarks

Inetftp.dll is available only for Intel x86 processors.

An application should use the FtpGetCurrentDirectory function to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpRemoveDirectory translates the directory name separators to the appropriate character before they are used.


FtpRenameFile

This function renames a file stored on the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpRenameFile(HINTERNET hConnect, LPCTSTR lpszExisting, LPCTSTR lpszNew);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszExisting
[in] Long pointer to a null-terminated string that contains the file name to be changed on the remote FTP server.
lpszNew
[in] Long pointer to a null-terminated string that contains the new name for the remote file.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError.

Remarks

Inetftp.dll is available only for Intel x86 processors.

The lpszExisting and lpszNew parameters can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpRenameFile translates the directory name separators to the appropriate character before they are used.


FtpSetCurrentDirectory

This function changes to a different working directory on the FTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI FtpSetCurrentDirectory(
HINTERNET hConnect, LPCTSTR lpszDirectory);

Parameters

hConnect
[in] Valid handle to an FTP session.
lpszDirectory
[in] Long pointer to a null-terminated string that contains the name of the directory to change to on the remote system. This can be either a fully qualified path or a name relative to the current directory.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error data, call GetLastError. If the error message indicates that the FTP server denied the request to remove a directory, use InternetGetLastResponseInfo to determine the cause.

Remarks

Inetftp.dll is available only for Intel x86 processors.

An application should use the FtpGetCurrentDirectory function to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backward slash (\) or forward slash (/) can be used as the directory separator for either name. FtpSetCurrentDirectory translates the directory name separators to the appropriate character before they are used.


GetCommMask

This function retrieves the event mask value for a specified communication device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCommMask(HANDLE hFile, LPDWORD lpEvtMask);

Parameters

hFile
[in] Handle to the communication device. The CreateFile function returns this handle.
lpEvtMask
[out] Long pointer to the 32-bit variable to be filled with a mask of events currently enabled. This parameter can be one or more of the following values:
Value
Description
EV_BREAK | A break was detected on input.
EV_CTS | The CTS (Clear To Send) signal changed state.
EV_DSR | The DSR (Data Set Ready) signal changed state.
EV_ERR | A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_RING | A ring indicator was detected.
EV_RLSD | The RLSD (Receive Line Signal Detect) signal changed state.
EV_RXCHAR | A character was received and placed in the input buffer.
EV_RXFLAG | The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY | The last character in the output buffer was sent.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error data, call GetLastError.

Remarks

The GetCommMask function uses a 32-bit mask variable to indicate the set of events that can be monitored for a particular communication resource. A handle to the communication resource can be specified in a call to the WaitCommEvent function, which waits for an event to occur. To modify the event mask of a communication resource, use the SetCommMask function.

See Also

CreateFile, DCB, SetCommMask, WaitCommEvent


GetCommModemStatus

This function retrieves modem control-register values.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCommModemStatus(HANDLE hFile, LPDWORD lpModemStat);

Parameters

hFile
[in] Handle to the communication device. The CreateFile function returns this handle.
lpModemStat
[out] Long pointer to a 32-bit variable that specifies the current state of the modem control-register values. This parameter can be a combination of the following values:
Value
Description
MS_CTS_ON | The CTS (Clear To Send) signal is on.
MS_DSR_ON | The DSR (Data Set Ready) signal is on.
MS_RING_ON | The ring indicator signal is on.
MS_RLSD_ON | The RLSD (Receive Line Signal Detect) signal is on.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error data, call GetLastError.

Remarks

The GetCommModemStatus function is useful when using the WaitCommEvent function to monitor the CTS, DSR, DSR, or ring indicator signals. To detect when these signals change state, use WaitCommEvent and then use GetCommModemStatus to determine the state after a change occurs.

The function fails if the hardware does not support the control-register values.

See Also

CreateFile, WaitCommEvent


GetCommProperties

This function fills a buffer with communication properties data for a specified communication device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCommProperties(HANDLE hFile,
LPCOMMPROP lpCommProp);

Parameters

hFile
[in] Handle to the communication device. The CreateFile function returns this handle.
lpCommProp
[out] Long pointer to a COMMPROP structure in which the communication properties data is returned. This data can be used in subsequent calls to the SetCommState, SetCommTimeouts, or SetupComm function to configure the communication device.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error data, call GetLastError.

Remarks

GetCommProperties returns data from a device driver about the configuration settings supported by the driver.

See Also

COMMPROP, CreateFile, SetCommState, SetCommTimeouts, SetupComm


GetCommState

This function fills in a device-control block (a DCB structure) with the current control settings for a specified communication device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCommState(HANDLE hFile, LPDCB lpDCB);

Parameters

hFile
[in] Handle to the communication device. The CreateFile function returns this handle.
lpDCB
[out] Long pointer to the DCB structure in which the control settings data is returned.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error data, call GetLastError.

See Also

CreateFile, DCB, SetCommState


GetCommTimeouts

This function retrieves the time-out parameters for all read and write operations on a specified communication device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetCommTimeouts(HANDLE hFile,
LPCOMMTIMEOUTS lpCommTimeouts);

Parameters

hFile
[in] Handle to the communication device. The CreateFile function returns this handle.
lpCommTimeouts
[out] Long pointer to a COMMTIMEOUTS structure in which the time-out data is returned.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error data, call GetLastError.

Remarks

For more information about time-out values for communication devices, see the SetCommTimeouts function.

See Also

CreateFile, COMMTIMEOUTS, SetCommTimeouts


gethostbyaddr

This function retrieves the host data corresponding to a network address.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct hostent * gethostbyaddr(const char *addr, int len, int type);

Parameters

addr
[in] Pointer to an address in network byte order.
len
[in] Address length.
type
[in] Address type.

Return Values

A pointer to the HOSTENT structure indicates no error occurred. A NULL pointer indicates failure. To get a specific error value, call the WSAGetLastError function.

Remarks

The gethostbyaddr function returns a pointer to the HOSTENT structure that contains the name and address corresponding to the given network address. All strings are null-terminated.

See Also

gethostbyname, gethostname, inet_addr , WSAStartup


gethostbyname

This function gets host data corresponding to a host name.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct hostent * gethostbyname(const char *name);

Parameters

name
[out] Pointer to the null-terminated string that contains the host name to resolve.

Return Values

A pointer to the HOSTENT structure indicates no error occurred. A NULL pointer indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The gethostbyname function returns a pointer to a HOSTENT structure—a structure allocated by Windows Sockets. The HOSTENT structure contains the results of a successful search for the host specified in the name parameter.

The application must never attempt to modify this structure, or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, so the application should copy data it needs before issuing other Windows Sockets function calls.

The gethostbyname function cannot resolve IP address strings passed to it. Such a request is treated exactly as if an unknown host name were passed. Use inet_addr to convert an IP address string the string to an actual IP address, then use another function, gethostbyaddr, to obtain the contents of the HOSTENT structure.

The gethostbyname function resolves the string returned by a successful call to gethostname.

Note Japanese Version Winsock calls to get the machine IP address will fail if the machine name is entered in Japanese characters.

See Also

gethostbyaddr, inet_ntoa, WSAStartup


gethostname

This function returns the standard host name for the local computer.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int gethostname (char *name, int namelen);

Parameters

name
[out] Pointer to a buffer that receives the local host name.
namelen
[in] Buffer length.

Return Values

Zero indicates no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The gethostname function returns the local host name into the buffer specified by the name parameter. The host name is returned as a null-terminated string. The host name form is dependent on the Windows Sockets provider—it can be a simple host name, or it can be a fully qualified domain name. However, it is guaranteed that the name returned will be successfully parsed by gethostbyname.

Note If no local host name has been configured, gethostname must succeed and return a token host name that gethostbyname can resolve.

See Also

gethostbyname, WSAStartup


getpeername

This function gets the peer address to which a socket is connected.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int getpeername(SOCKET s, struct sockaddr *name, int *namelen);

Parameters

s
[in] Descriptor that identifies a connected socket.
name
[out] Structure that receives the peer name.
namelen
[in/out] Pointer to the name structure size.

Return Values

Zero indicates no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The getpeername function retrieves the peer name connected to the socket s and stores it in the a SOCKADDR structure identified by name. The getpeername function can be used only on a connected socket. For datagram sockets, only the name of a peer specified in a previous connect call will be returned—any name specified by a previous sendto call will not be returned by getpeername.

On call, the namelen argument contains the name buffer size, in bytes. On return, the namelen parameter contains the actual size, in bytes, of the name returned.

See Also

bind, getsockname, socket


getsockname

This function gets the local address for a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int getsockname (SOCKET s, struct sockaddr *name, int *namelen);

Parameters

s
[in] Descriptor that identifies a bound socket.
name
[out] Receives the socket address (name).
namelen
[in/out] name buffer size.

Return Values

Zero indicates no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The getsockname function retrieves the current name for the specified socket descriptor in name. It is used on the bound or connected socket specified by the s parameter. The local association is returned. This call is especially useful when a connect call has been made without doing a bind first; the getsockname function provides the only way to determine the local association set by the system.

On call, the namelen argument contains the name buffer size, in bytes. On return, the namelen parameter contains the actual name parameter size, in bytes.

The getsockname function does not always return data about the host address when the socket has been bound to an unspecified address, unless the socket has been connected with connect or accept (for example, using ADDR_ANY). A Windows Sockets application must not assume that the address will be specified unless the socket is connected. The address used for the socket is unknown unless the socket is connected when used in a multihomed host. If the socket is using a connectionless protocol, the address may not be available until I/O occurs on the socket.

See Also

accept, bind, connect, getpeername, socket, WSAStartup


getsockopt

This function retrieves a socket option.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int getsockopt (SOCKET s, int level, int optname, char *optval, int *optlen);

Parameters

s
[in] Descriptor that identifies a socket.
level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET, IPPROTO_TCP, and IPPROTO_IP.

In Windows CE, the following level values are available when the level is IPPROTO_IP:
Value
Description
IP_MULTICAST_TTL | Time to Live for a multicast packet. Retrieves the number of hops for which a multicast message survives before it is discarded. Use int for optval.
IP_MULTICAST_IF | Address of the outgoing multicast-capable interface. This address is used for subsequent multicasts. Use unsigned long for optval.
IP_MULTICAST_LOOP | Status of the socket’s loop behavior during multicast. Use unsigned long for optval.

optname
[in] Socket option for which the value is to be retrieved.
optval
[out] Pointer to the buffer in which the value for the requested option is to be returned.
optlen
[in/out] Pointer to the optval buffer size.

Return Values

Zero indicates no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Windows CE Remarks

For IrSockets implementation:

  • The Af_irda.h file must be included.
  • The WSAENETDOWN return value is not supported.

IrSockets supports several special socket options:

Value
Type
Meaning
IRLMP_ENUMDEVICES | * DEVICELIST | Describes devices in range.
IRLMP_IAS_QUERY | * IAS_QUERY | Retrieve IAS attributes.
IRLMP_SEND_PDU_LEN | * int | Retrieves the maximum number of bytes that can be sent in any one send() call while in IRLMP_IRLPT_MODE (printing). This value should be retrieved after the connect() completes, but before data is sent.

The DEVICELIST structure is an extendible array of device descriptions. IrSockets fills in as many device descriptions as can fit in the supplied buffer and returns in the optlen result parameter the required size if the buffer is of insufficient size. The device description consists of a device identifier necessary to form a sockaddr_irda structure and a displayable string describing the device.

The IAS_QUERY structure is used to retrieve a single attribute of a single class. The application specifies the device and class to query and the attribute and attribute type. It is expected that the application allocates a buffer of the necessary size for the returned parameters.

Many SO level socket options are meaningless to IrSockets. Only SO_LINGER and SO_DONTLINGER are specifically supported.

Remarks

The getsockopt function retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in optval. Options can exist at multiple protocol levels, but they are always present at the uppermost socket level. Options affect socket operations, such as the packet routing and out-of-band data transfer.

The value associated with the selected option is returned in the buffer optval. The integer pointed to by optlen should originally contain the size of this buffer; on return, it will be set to the size of the value returned. For SO_LINGER, this will be the size of a LINGER structure. For most other options, it will be the size of an integer.

The application is responsible for allocating memory space pointed to directly, or indirectly by any parameters it specified.

If the option was never set with setsockopt, then getsockopt returns the default value for the option.

The following options are supported for getsockopt. The Type column identifies the type of data addressed by optval.

level = SOL_SOCKET

Value
Type
Description
SO_ACCEPTCONN | BOOL | Socket is listening.
SO_BROADCAST | BOOL | Socket is configured for the transmission of broadcast messages.
SO_DEBUG | BOOL | Debugging is enabled.
SO_DONTLINGER | BOOL | If TRUE, the SO_LINGER option is disabled.
SO_DONTROUTE | BOOL | Routing is disabled.
SO_ERROR | int | Retrieves error status and clear.
SO_GROUP_ID | GROUP | The group identifier to which this socket belongs.
SO_GROUP_PRIORITY | int | The relative priority for sockets that are part of a socket group.
SO_KEEPALIVE | BOOL | Keepalives are being sent.
SO_LINGER | struct LINGER | Returns the current linger options.
SO_MAX_MSG_SIZE | unsigned int | Maximum size of a message for message-oriented socket types (for example, SOCK_DGRAM). Has no meaning for stream oriented sockets.
SO_OOBINLINE | BOOL | Out-of-band data is being received in the normal data stream.
SO_RCVBUF | int | Buffer size for receives.
SO_REUSEADDR | BOOL | The socket can be bound to an address which is already in use.
SO_SNDBUF | int | Buffer size for sends.
SO_TYPE | int | The socket type (for example, SOCK_STREAM).
PVD_CONFIG | Service Provider Dependent | An opaque data structure object from the service provider associated with socket s. This object stores the current service provider configuration data. The exact format of this data structure is service provider specific.

level = IPPROTO_TCP

Value
Type
Description
TCP_NODELAY BOOL Disables the Nagle algorithm for send coalescing.

BSD options not supported for getsockopt are as follows.

Value
Type
Meaning
SO_RCVLOWAT | int | Receive low water mark.
SO_RCVTIMEO | int | Receive time-out.
SO_SNDLOWAT | int | Send low water mark.
SO_SNDTIMEO | int | Send time-out.
TCP_MAXSEG | int | Get TCP maximum segment size.

Calling getsockopt with an unsupported option will result in an error value of WSAENOPROTOOPT being returned by WSAGetLastError.

SO_DEBUG
Windows Sockets service providers are encouraged, but not required, to supply output debug data if the SO_DEBUG option is set by an application. The mechanism for generating the debug data and the form it takes are beyond the scope of this document.
SO_ERROR
The SO_ERROR option returns and resets the per socket based error value, which is different from the per thread based error value that is handled using the WSAGetLastError and WSASetLastError function calls. A successful call using the socket does not reset the socket based error value returned by the SO_ERROR option.
SO_GROUP_ID
This option is reserved for future use with socket groups. This option is also exclusive to getsockopt. It indicates the group identifier to which this socket belongs. Socket group identifiers are unique across all processes for a given service provider. If this socket is not a group socket, the value is NULL.
SO_GROUP_PRIORITY
This option is reserved for future use with socket groups. Group priority indicates the priority of the specified socket relative to other sockets within the socket group. Values are non-negative integers, with zero corresponding to the highest priority. Priority values represent a hint to the underlying service provider about how potentially scarce resources should be allocated. For example, when two or more sockets are ready to transmit data, the highest priority socket (lowest value for SO_GROUP_PRIORITY) should be serviced first, with the remainder serviced in turn according to their relative priorities.

The WSAENOPROTOOPT error value is indicated for non group sockets or for service providers that do not support group sockets.

SO_KEEPALIVE
An application can request that a TCP/IP service provider enable the use of keep-alive packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alive: if it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Host—Communication Layers. If a connection is dropped as the result of keep-alives, the error value WSAENETRESET is returned to calls in progress on the socket, and subsequent calls will fail with WSAENOTCONN.
SO_LINGER
SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application gets the current behavior by retrieving a LINGER structure (pointed to by the optval parameter).
SO_MAX_MSG_SIZE
This is a get-only socket option that indicates the maximum outbound (send) size of a message for message-oriented socket types (for example, SOCK_DGRAM) as implemented by a particular service provider. It has no meaning for byte stream oriented sockets. There is no provision to find out the maximum inbound message size.
SO_SNDBUF
When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller). The call to setsockopt can succeed even if the implementation did not provide the whole amount requested. An application must call this function with the same option to check the buffer size actually provided.
SO_REUSEADDR
By default, a socket cannot be bound (see bind) to a local address already in use. On occasion, however, it can be necessary to re-use an address in this way. Because every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be rejected because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. The option is interpreted only at the time of the bind. It is therefore unnecessary, but harmless, to set the option on a socket that is not to be bound to an existing address, and setting or resetting the option after the bind has no effect on this or any other socket.
PVD_CONFIG
This option retrieves an opaque data structure object from the service provider associated with socket s. This object stores the current service provider configuration data. The exact data structure format is service provider-specific.
TCP_NODELAY

The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle algorithm is disabled if the TCP_NODELAY option is enabled, and vice versa. The Nagle algorithm, as described in RFC 896, is very effective in reducing the number of small packets sent by a host. The process involves buffering send data when there is unacknowledged data already in route or buffering send data until a full-size packet can be sent. It is highly recommended that Windows Sockets implementations enable the Nagle Algorithm by default because, for the majority of application protocols, the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and setsockopt with the same option can be used to turn it off. These are applications where many small messages are sent, and the time delays between the messages are maintained.

See Also

setsockopt, socket, WSAStartup


GetUrlCacheEntryInfo

This function retrieves data about a cache entry.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL GetUrlCacheEntryInfo ( LPCTSTR lpszUrlName,
LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
LPDWORD lpdwCacheEntryInfoBufferSize );

Parameters

lpszUrlName
[in] Address of a string that contains the cache entry name. This string should not contain escape characters.
lpCacheEntryInfo
[in] Address of an INTERNET_CACHE_ENTRY_INFO structure that receives data about the cache entry.
lpdwCacheEntryInfoBufferSize
[in/out] Address of an unsigned long integer variable that specifies the lpCacheEntryInfo buffer size, in bytes. When the function returns, the variable contains the number of bytes copied to the buffer, or the required buffer size.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

This function does not parse a Uniform Resource Locator (URL), so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL http://example.com/example.htm#sample was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

See Also

SetUrlCacheEntryInfo


GetUrlCacheEntryInfoEx

This function searches for the Uniform Resource Locator (URL) after translating any cached redirections applied in offline mode by the HttpSendRequest function.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL GetUrlCacheEntryInfoEx ( LPCSTR lpszUrl,
LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
LPDWORD lpdwCacheEntryInfoBufSize, LPSTR lpszReserved,
LPDWORD lpdwReserved, LPVOID lpReserved, DWORD dwFlags );

Parameters

lpszUrl
[in] Address of a string that contains the cache entry name. This string should not contain escape characters.
lpCacheEntryInfo
[out] Address of an INTERNET_CACHE_ENTRY_INFO structure that receives data about the cache entry.
lpdwCacheEntryInfoBufSize
[in/out] Address of an unsigned long integer variable that specifies the lpCacheEntryInfo buffer size, in bytes. When the function returns, the variable contains the number of bytes copied to the buffer, or the required buffer size.
lpszReserved
[out] Reserved; set to NULL.
lpdwReserved
[in/out] Reserved; set to NULL.
lpReserved
Reserved; set to NULL.
dwFlags
Reserved; set to zero.

Return Values

Returns TRUE if the URL was located, or FALSE otherwise.

See Also

HttpSendRequest, SetUrlCacheEntryInfo


htonl

This function converts a u_long from host byte order to network byte order.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

u_long htonl (u_long hostlong);

Parameters

hostlong
[in] 32-bit number in host byte order.

Return Values

The value in TCP/IP’s network byte order indicates success.

Remarks

The htonl function takes a 32-bit number in host byte order and returns a 32-bit number in the network byte order used in TCP/IP networks.

See Also

htons, ntohl, ntohs


htons

This function converts a u_short from host byte order to network byte order.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

u_short htons (u_short hostshort);

Parameters

hostshort
[in] 16-bit number in host byte order.

Return Values

The value in TCP/IP network byte order indicates success.

Remarks

The htons function takes a 16-bit number in host byte order and returns a 16-bit number in network byte order used in TCP/IP networks.

See Also

htonl, ntohl, ntohs


HttpAddRequestHeaders

This function adds one or more Hypertext Transfer Protocol (HTTP) request headers to the HTTP request handle.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI HttpAddRequestHeaders(
HINTERNET hHttpRequest, LPCTSTR lpszHeaders,
DWORD dwHeadersLength, DWORD dwModifiers);

Parameters

hHttpRequest
[in] Open HTTP request handle returned by HttpOpenRequest.
lpszHeaders
[in] Long pointer to the null-terminated strings that contains headers to append to the request. Each header must be terminated by a CR/LF (carriage return/line feed) pair.
dwHeadersLength
[in] Specifies the length, in characters, of lpszHeaders. If this parameter is -1L, the function assumes that lpszHeaders is zero-terminated (ASCIIZ), and the length is computed.
dwModifiers
[in] Specifies the values used to modify the semantics of this function. Can be a combination of the following values:
Value
Description
HTTP_ADDREQ_FLAG_ADD | Adds the header if it does not exist. Used with HTTP_ADDREQ_FLAG_REPLACE.
HTTP_ADDREQ_FLAG_ADD_IF_NEW | Adds the header only if it does not already exist; otherwise, an error is returned.
HTTP_ADDREQ_FLAG_COALESCE | Coalesces headers of the same name.
HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA | Coalesces headers of the same name. For example, adding "Accept: text/*" followed by "Accept: audio/*" with this flag results in the formation of the single header "Accept: text/*, audio/*". This causes the first header found to be coalesced. It is up to the calling application to ensure a cohesive scheme with respect to coalesced/separate headers.
HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON | Coalesces headers of the same name using a semicolon.
HTTP_ADDREQ_FLAG_REPLACE | Replaces or removes a header. If the header value is empty and the header is found, it is removed. If not empty, the header value is replaced.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

HttpAddRequestHeaders appends additional, free-format headers to the HTTP request handle and is intended for use by sophisticated clients that need detailed control over the exact request sent to the HTTP server.

Note that for basic HttpAddRequestHeaders, the application can pass in multiple headers in a single buffer. If the application is trying to remove or replace a header, only one header can be supplied in lpszHeaders.

See Also

HttpSendRequest


HttpEndRequest

This function ends an HTTP request that was initiated by HttpSendRequestEx.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL HttpEndRequest (HINTERNET hRequest,
LPINTERNET_BUFFERS lpBuffersOut, DWORD dwFlags,
DWORD dwContext);

Parameters

hRequest
[in] HINTERNET handle returned by HttpOpenRequest and sent by HttpSendRequestEx.
lpBuffersOut
[out] Optional. Address of an INTERNET_BUFFERS structure.
dwFlags
[in] Unsigned long integer value that contains the flags that control this function. Can be one of the following values:
Value
Description
HSR_ASYNC | Identical to WININET_API_FLAG_ASYNC.
HSR_SYNC | Identical to WININET_API_FLAG_SYNC.
HSR_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT.
HSR_INITIATE | Iterative operation (completed by HttpEndRequest).
HSR_DOWNLOAD | Download resource to file.
HSR_CHUNKED | Send chunked data.

dwContext
[in] Unsigned long integer variable that contains the application-defined context value for applications that register a status callback function.

Return Values

Returns TRUE if successful, or FALSE otherwise.

See Also

HttpSendRequestEx


HttpOpenRequest

This function opens an HTTP request handle.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

HINTERNET WINAPI HttpOpenRequest(
HINTERNET hHttpSession, LPCTSTR lpszVerb, LPCTSTR lpszObjectName, LPCTSTR lpszVersion, LPCTSTR lpszReferrer,
LPCTSTR * lplpszAcceptTypes, DWORD dwFlags, DWORD dwContext);

Parameters

hHttpSession
[in] Handle to an HTTP session returned by InternetConnect.
lpszVerb
[in] Long pointer to a null-terminated string that contains the verb to use in the request. If this parameter is NULL, the function uses "GET" as the verb.
lpszObjectName
[in] Long pointer to a null-terminated string that contains the name of the target object of the specified verb. This is generally a file name, an executable module, or a search specifier.
lpszVersion
[in] Long pointer to a null-terminated string that contains the HTTP version. If this parameter is NULL, the function uses "HTTP/1.0" as the version.
lpszReferer
[in] Long pointer to a null-terminated string that specifies the address (URL) of the document from which the URL in the request (lpszObjectName) was obtained. If this parameter is NULL, no "referrer" is specified.
lplpszAcceptTypes
[in] Long pointer to a null-terminated array of string pointers indicating content types accepted by the client. If this parameter is NULL, no types are accepted by the client. Servers interpret a lack of accept types to indicate that the client accepts only documents of type "text/*" (that is, only text documents, and not pictures or other binary files).
dwFlags
[in] Specifies a bitmask of Internet flags. Can be any of the following values:
Value
Description
INTERNET_FLAG_CACHE_IF_NET_FAIL | Return the resource from the cache if the network request for the resource fails due to an ERROR_INTERNET_CONNECTION_RESET or ERROR_INTERNET_CANNOT_CONNECT.
INTERNET_FLAG_DONT_CACHE | Not supported. Data is never cached.
INTERNET_FLAG_HYPERLINK | Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_IGNORE_CERT_CN_INVALID | Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID | Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP | Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS | Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs.
INTERNET_FLAG_KEEP_CONNECTION | Uses keep-alive semantics, if available, for the connection. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication.
INTERNET_FLAG_MAKE_PERSISTENT | Not supported.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_AUTH | Does not attempt authentication automatically.
INTERNET_FLAG_NO_AUTO_REDIRECT | Does not automatically handle redirection in HttpSendRequest.
INTERNET_FLAG_NO_CACHE_WRITE | Does not add the returned entity to the cache.
INTERNET_FLAG_NO_COOKIES | Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database.
INTERNET_FLAG_NO_UI | Disables the cookie dialog box.
INTERNET_FLAG_PRAGMA_NOCACHE | Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy.
INTERNET_FLAG_READ_PREFETCH | This flag is currently disabled.
INTERNET_FLAG_RELOAD | Not supported. Data is always from the wire and caching is not supported.
INTERNET_FLAG_RESYNCHRONIZE | Reloads HTTP resources if the resource has been modified since the last time it was downloaded.
INTERNET_FLAG_SECURE | Uses SSL/PCT transaction semantics.

dwContext
[in] Specifies the application-defined value that associates this operation with any application data.

Return Values

A valid, non-NULL HTTP request handle indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

HttpOpenRequest creates a new HTTP request handle and stores the specified parameters in that handle. An HTTP request handle holds a request to be sent to an HTTP server and contains all RFC822/MIME/HTTP headers to be sent as part of the request.

Use the InternetCloseHandle function to close the handle returned by HttpOpenRequest. InternetCloseHandle cancels all outstanding I/O on the handle.

The lpszReferer parameter to InternetOpen is used as the referrer for the HTTP request.

The dwContext parameter allows for progress status callbacks to the application, but all requests will be handled synchronously.

When establishing a Secure Sockets Layer (SSL) or Private Communications Technology, HttpOpenRequest uses the INTERNET_FLAG_SECURE option in addition to all other options.

The following dwFlags values can be used in HttpOpenRequest to ignore invalid certificate errors:

INTERNET_FLAG_IGNORE_CERT_CN_INVALID
Ignores errors caused when the certificate host name of the server does not match the host name in the request.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
Ignores errors caused by an expired server certificate.

See Also

HttpAddRequestHeaders, HttpQueryInfo, InternetReadFile


HttpQueryInfo

This function queries for information about an HTTP request.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI HttpQueryInfo(HINTERNET hRequest,
DWORD dwInfoLevel, LPVOID lpBuffer , LPDWORD lpdwBufferLength,
LPDWORD lpdwIndex );

Parameters

hRequest
[in] Open HTTP request handle returned by HttpOpenRequest or InternetOpenUrl.
dwInfoLevel
[in] Specifies a combination of the attribute to query and the flags that modify the request. The attributes can be any of the following values:
Value
Description
HTTP_QUERY_ACCEPT | Retrieves the acceptable media types for the response.
HTTP_QUERY_ACCEPT_CHARSET | Retrieves the acceptable character sets for the response.
HTTP_QUERY_ACCEPT_ENCODING | Retrieves the acceptable content-coding values for the response.
HTTP_QUERY_ACCEPT_LANGUAGE | Retrieves the acceptable natural languages for the response.
HTTP_QUERY_ACCEPT_RANGES | Retrieves the types of range requests that are accepted for a resource.
HTTP_QUERY_AGE | Retrieves the Age response-header field, which contains the sender's estimate of the amount of time since the response was generated at the origin server.
HTTP_QUERY_ALLOW | Receives the methods supported by the server.
HTTP_QUERY_AUTHORIZATION | Retrieves the authorization credentials used for a request.
HTTP_QUERY_CACHE_CONTROL | Retrieves the cache control directives.
HTTP_QUERY_CONNECTION | Retrieves any options that are specified for a particular connection and must not be communicated by proxies over further connections.
HTTP_QUERY_COOKIE | Retrieves any cookies associated with the request.
HTTP_QUERY_CONTENT_BASE | Retrieves the base URI for resolving relative URLs within the entity.
HTTP_QUERY_CONTENT_DESCRIPTION | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_CONTENT_DISPOSITION | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_CONTENT_ENCODING | Receives any additional content codings that have been applied to the entire resource.
HTTP_QUERY_CONTENT_ID | Receives the content identification.
HTTP_QUERY_CONTENT_LANGUAGE | Receives the language that the content is in.
HTTP_QUERY_CONTENT_LENGTH | Receives the size of the resource, in bytes.
HTTP_QUERY_CONTENT_LOCATION | Retrieves the resource location for the entity enclosed in the message.
HTTP_QUERY_CONTENT_MD5 | Retrieves a MD5 digest of the entity-body for the purpose of providing an end-to-end message integrity check (MIC) for the entity-body.
HTTP_QUERY_CONTENT_RANGE | Retrieves the location in the full entity-body where the partial entity-body should be inserted and the total size of the full entity-body.
HTTP_QUERY_CONTENT_TRANSFER_ENCODING | Receives the additional content coding that has been applied to the resource.
HTTP_QUERY_CONTENT_TYPE | Receives the content type of the resource (such as text/html).
HTTP_QUERY_COST | No longer implemented.
HTTP_QUERY_DATE | Receives the date and time at which the message was originated.
HTTP_QUERY_DERIVED_FROM | No longer supported.
HTTP_QUERY_ETAG | Retrieves the entity tag for the associated entity.
HTTP_QUERY_EXPIRES | Receives the date and time after which the resource should be considered outdated.
HTTP_QUERY_FORWARDED | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_FROM | Retrieves the e-mail address for the human user who controls the requesting user agent if the From header is given.
HTTP_QUERY_HOST | Retrieves the Internet host and port number of the resource being requested.
HTTP_QUERY_IF_MATCH | Retrieves the contents of the If-Match request-header field.
HTTP_QUERY_IF_MODIFIED_SINCE | Retrieves the contents of the If-Modified-Since header.
HTTP_QUERY_IF_NONE_MATCH | Retrieves the contents of the If-None-Match request-header field.
HTTP_QUERY_IF_RANGE | Retrieves the contents of the If-Range request-header field. This header allows the client application to check if the entity related to a partial copy of the entity in the client application's cache has not been updated. If the entity has not been updated, send the parts that the client application is missing. If the entity has been updated, send the entire updated entity.
HTTP_QUERY_IF_UNMODIFIED_SINCE | Retrieves the contents of the If-Unmodified-Since request-header field.
HTTP_QUERY_LINK | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_LAST_MODIFIED | Receives the date and time at which the server believes the resource was last modified.
HTTP_QUERY_LOCATION | Retrieves the absolute URI used in a Location response-header.
HTTP_QUERY_MAX | Retrieves the maximum value of an HTTP_QUERY_* value.
HTTP_QUERY_MAX_FORWARDS | Retrieves the number of proxies or gateways that can forward the request to the next inbound server.
HTTP_QUERY_MESSAGE_ID | No longer implemented.
HTTP_QUERY_MIME_VERSION | Receives the version of the MIME protocol that was used to construct the message.
HTTP_QUERY_ORIG_URI | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_PRAGMA | Receives the implementation-specific directives that may apply to any recipient along the request/response chain.
HTTP_QUERY_PROXY_AUTHENTICATE | Retrieves the authentication scheme and realm returned by the proxy.
HTTP_QUERY_PROXY_AUTHORIZATION | Retrieves the header that is used to identify the user to a proxy that requires authentication.
HTTP_QUERY_PUBLIC | Receives methods available at this server.
HTTP_QUERY_RANGE | Retrieves the byte range of an entity.
HTTP_QUERY_RAW_HEADERS | Receives all the headers returned by the server. Each header is terminated by "\0". An additional "\0" terminates the list of headers.
HTTP_QUERY_RAW_HEADERS_CRLF | Receives all the headers returned by the server. Each header is separated by a carriage return/line feed (CR/LF) sequence.
HTTP_QUERY_REFERER | Receives the URI of the resource where the requested URI was obtained.
HTTP_QUERY_REFRESH | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_REQUEST_METHOD | Receives the verb that is being used in the request, typically GET or POST.
HTTP_QUERY_RETRY_AFTER | Retrieves the amount of time the service is expected to be unavailable.
HTTP_QUERY_SERVER | Retrieves information about the software used by the origin server to handle the request.
HTTP_QUERY_SET_COOKIE | Receives the value of the cookie set for the request.
HTTP_QUERY_STATUS_CODE | Receives the status code returned by the server.
HTTP_QUERY_STATUS_TEXT | Receives any additional text returned by the server on the response line.
HTTP_QUERY_TITLE | Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_TRANSFER_ENCODING | Retrieves the type of transformation that has been applied to the message body so it can be safely transferred between the sender and recipient.
HTTP_QUERY_UPGRADE | Retrieves the additional communication protocols that are supported by the server.
HTTP_QUERY_URI | Receives some or all of the Uniform Resource Identifiers (URIs) by which the Request-URI resource can be identified.
HTTP_QUERY_USER_AGENT | Retrieves information about the user agent that made the request.
HTTP_QUERY_VARY | Retrieves the header that indicates that the entity was selected from a number of available representations of the response using server-driven negotiation.
HTTP_QUERY_VERSION | Receives the last response code returned by the server.
HTTP_QUERY_VIA | Retrieves the intermediate protocols and recipients between the user agent and the server on requests, and between the origin server and the client on responses.
HTTP_QUERY_WARNING | Retrieves additional information about the status of a response that may not be reflected by the response status code.
HTTP_QUERY_WWW_AUTHENTICATE | Retrieves the authentication scheme and realm returned by the server.

The following modifiers can be used with the information values:
Value
Description
HTTP_QUERY_CUSTOM | Causes HttpQueryInfo to search for the header name specified in lpvBuffer and store the header information in lpvBuffer.
HTTP_QUERY_FLAG_COALESCE | Not supported.
HTTP_QUERY_FLAG_NUMBER | Returns the data as a 32-bit number for headers whose value is a number, such as the status code.
HTTP_QUERY_FLAG_REQUEST_HEADERS | Queries request headers only.
HTTP_QUERY_FLAG_SYSTEMTIME | Returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data. Use for headers whose value is a date/time string, such as "Last-Modified-Time".

lpBuffer
[in\out] Long void pointer to the buffer that receives the information.
lpdwBufferLength
[in\out] Long pointer to a value that contains the length of the data buffer. When the function returns, this parameter contains the address of a value specifying the length of the information written to the buffer. When the function returns strings, the following rules apply:
  • If the function succeeds, lpdwBufferLength specifies the length of the string, in characters, minus 1 for the terminating null.
  • If the function fails and ERROR_INSUFFICIENT_BUFFER is returned, lpdwBufferLength specifies the number of bytes that the application must allocate to receive the string.
lpdwIndex
[in\out] Long pointer to a zero-based header index used to enumerate multiple headers with the same name. When calling the function, this parameter is the index of the specified header to return. When the function returns, this parameter is the index of the next header. If the next index cannot be found, ERROR_HTTP_HEADER_NOT_FOUND is returned.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

HttpQueryInfo is used to return response or request headers from an HTTP request.

You can retrieve different types of data from HttpQueryInfo:

  • strings (default)
  • SYSTEMTIME (for Data: Expires:, headers)
  • DWORD (for STATUS_CODE, CONTENT_LENGTH, and so on if HTTP_QUERY_INFO_NUMBER has been used)

See Also

HttpOpenRequest


HttpSendRequest

This function sends the specified request to the HTTP server.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI HttpSendRequest(HINTERNET hRequest, LPCTSTR lpszHeaders , DWORD dwHeadersLength, LPVOID lpOptional, DWORD dwOptionalLength);

Parameters

hRequest
[in] Open HTTP request handle returned by HttpOpenRequest.
lpszHeaders
[in] Long pointer to null-terminated strings that contain additional headers to be appended to the request. This parameter can be NULL if there are no additional headers to append.
dwHeadersLength
[in] Specifies the length, in characters, of the additional headers. If this parameter is -1L and lpszHeaders is not NULL, the function assumes that lpszHeaders is zero-terminated (ASCIIZ), and the length is calculated.
lpOptional
[in] Long pointer to any optional data to send immediately after the request headers. This parameter is generally used for POST and PUT operations. The optional data can be the resource or information being posted to the server. This parameter can be NULL if there is no optional data to send.
dwOptionalLength
[in] Specifies the length, in bytes, of the optional data. This parameter can be zero if there is no optional data to send.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

HttpSendRequest sends the specified request to the HTTP server and allows the client to specify additional headers to send along with the request.

The function also lets the client specify optional data to send to the HTTP server immediately following the request headers. This feature is generally used for "write" operations such as PUT and POST. When using optional data, be aware of the following caveat: the size of the optional data buffer, specified with the dwOptionalLength parameter, must be either less than 32 bytes or greater than approximately 150 bytes. Otherwise, the HttpSendRequest function fails.

Another caveat requires that the optional data buffer begin with '/r/n'. This ensures that header and buffer is separated by '/r/n/r/n' as required by RFC 2068.

After the request is sent, the status code and response headers from the HTTP server are read. These headers are maintained internally and are available to client applications through the HttpQueryInfo function.

An application can use the same HTTP request handle in multiple calls to HttpSendRequest, but the application must read all data returned from the previous call before calling the function again.

See Also

InternetReadFile


HttpSendRequestEx

This function sends the specified request to the HTTP server and allows chunked transfers.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL HttpSendRequestEx (HINTERNET hRequest, LPINTERNET_BUFFERS lpBuffersIn,
LPINTERNET_BUFFERS lpBuffersOut, DWORD dwFlags,
DWORD dwContext);

Parameters

hRequest
[in] HINTERNET handle returned by HttpOpenRequest.
lpBuffersIn
[in] Optional. Address of an INTERNET_BUFFERS structure.
lpBuffersOut
[out] Optional. Address of an INTERNET_BUFFERS structure.
dwFlags
[in] Can be one of the following values:
Value
Description
HSR_ASYNC | Identical to WININET_API_FLAG_ASYNC.
HSR_SYNC | Identical to WININET_API_FLAG_SYNC.
HSR_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT.
HSR_INITIATE | Iterative operation (completed by HttpEndRequest).
HSR_DOWNLOAD | Download resource to file.
HSR_CHUNKED | Send chunked data.

dwContext
[in] Unsigned long integer variable that contains the application-defined context value, if a status callback function has been registered.

Return Values

Returns TRUE if successful, or FALSE otherwise.

See Also

HttpEndRequest, HttpOpenRequest, HttpSendRequest


IcmpCloseHandle

This function closes an Internet Control Message Protocol (ICMP) handle opened by IcmpCreateFile.

At a Glance

Header file: | Icmpapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI IcmpCloseHandle (HANDLE IcmpHandle);

Parameters

IcmpHandle
[in] ICMP handle opened by IcmpCreateFile.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

IcmpCreateFile


IcmpCreateFile

This function creates a handle on which Internet Control Message Protocol (ICMP) requests can be issued.

At a Glance

Header file: | Icmpapi.h
Windows CE versions: | 2.0 and later

Syntax

HANDLE WINAPI IcmpCreateFile (VOID);

Return Values

An ICMP handle indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

See Also

GetLastError


IcmpSendEcho

This function sends an Internet Control Message Protocol (ICMP) echo request, and returns one or more replies.

At a Glance

Header file: | Icmpapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WINAPI IcmpSendEcho (HANDLE IcmpHandle
IPAddr DestinationAddress LPVOID RequestData WORD RequestSize PIP_OPTION_INFORMATION RequestOptions LPVOID ReplyBuffer DWORD ReplySize DWORD Timeout);

Parameters

IcmpHandle
[in] ICMP handle opened by IcmpCreateFile.
DestinationAddress
[in] Specifies the destination of the echo request.
RequestData
[in] Buffer that contains the data to be sent in the request.
RequestSize
[in] Number of bytes in the RequestData buffer.
RequestOptions
[in] Pointer to the IP header options for the request; may be NULL.
ReplyBuffer
[out] Buffer to hold any replies to the request. When the function returns, the buffer will contain one or more ICMP_ECHO_REPLY structures, followed by options and data.
ReplySize
[out] Size, in bytes, of the reply buffer. The buffer must be large enough to accommodate at least one ICMP_ECHO_REPLY structure plus eight additional bytes (the size of an ICMP error message).
Timeout
[in] Time, in milliseconds, to wait for replies.

Return Values

The number of replies received and stored in the reply buffer indicates success. Zero indicates failure. Extended error information is available through GetLastError.

See Also

ICMPCreateFile , GetLastError


inet_addr

This function converts a string containing a dotted address into a network address in the format of an IN_ADDR structure.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

unsigned long inet_addr (const char *cp);

Parameters

cp
[in] Null-terminated string that represents a number expressed in the Internet standard ".'' (dotted) notation.

Return Values

An unsigned long value containing a suitable binary representation of the specified Internet address indicates that no error occurred. INADDR_NONE indicates that the string in the cp parameter does not contain a legitimate Internet address, for example, if a portion of an "a.b.c.d" address exceeds 255.

Remarks

The inet_addr function interprets the character string specified by the cp parameter. This string represents a numeric Internet address expressed in the Internet standard ".'' notation. The value returned is a number suitable for use as an Internet address. All Internet addresses are returned in IP’s network order (bytes ordered from left to right).

Internet Addresses

Values specified using the ".'' notation take one of the following forms:

a.b.c.d a.b.c a.b a

When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When an Internet address is viewed as a 32-bit integer quantity on the Intel architecture, the bytes referred to above appear as "d.c.b.a''. That is, the bytes on an Intel processor are ordered from right to left.

The parts that make up an address in "." notation can be decimal, octal or hexadecimal as specified in the C language. Numbers that start with "0x" or "0X" imply hexadecimal. Numbers that start with "0" imply octal. All other numbers are interpreted at decimal.

"4.3.2.16" | decimal
"004.003.002.020" | octal
"0x4.0x3.0x2.0x10" | hexadecimal
"4.003.002.0x10" | mix

Note The following notations are only used by Berkeley, and nowhere else on the Internet. In the interests of compatibility with their software, they are supported as specified.

When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as "128.net.host''.

When a two-part address is specified, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as "net.host''.

When only one part is given, the value is stored directly in the network address without any byte rearrangement.

See Also

inet_ntoa, IN_ADDR


inet_ntoa

This function converts a network address into a string in dotted format.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

char * inet_ntoa (struct in_addr in);

Parameters

in
[in] Structure that represents an Internet host address.

Return Values

A char pointer to a static buffer containing the text address in standard ".'' notation indicates that no error occurred. NULL indicates failure.

Remarks

The inet_ntoa function takes an Internet address structure specified by the in parameter and returns an ASCII string representing the address in ".'' (dot) notation as in "a.b.c.d''. The string returned by inet_ntoa resides in memory that is allocated by Windows Sockets. The application should not make any assumptions about the way in which the memory is allocated. The data is guaranteed to be valid until the next Windows Sockets function call within the same thread, but no longer. Therefore, the data should be copied before another Windows Sockets call is made.

See Also

inet_addr, IN_ADDR


InitializeSecurityContext

This function initiates the outbound security context from a credential handle. The function establishes a security context between the client application and a remote peer. InitializeSecurityContext returns a token that the client must pass to the remote peer, which in turn submits it to the local security implementation through the AcceptSecurityContext call. The token generated should be considered opaque by all callers.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS InitializeSecurityContext( PCredHandle phCredential,
PCtxtHandle phContext, SEC_CHAR * pszTargetName, ULONG fContextReq,
ULONG Reserved1, ULONG TargetDataRep, PSecBufferDesc pInput, ULONG Reserved2, PCtxtHandle phNewContext, PSecBufferDesc pOutput,
PULONG pfContextAttr, PTimeStamp ptsExpiry );

Parameters

phCredential
Pointer to the handle to the credentials to use to create the context. The client retrieves this handle by calling the AcquireCredentialsHandle function.
phContext
Pointer to the handle of a CtxtHandle structure. On the first call to InitializeSecurityContext, this pointer is NULL. On the second call, this parameter is the handle to the partially formed context returned in the phNewContext parameter by the first call.
pszTargetName
Pointer to a null-terminated string that indicates the target of the context. The name is security-package specific.
fContextReq
Set of bit flags that indicate the requirements of the context. Not all packages can support all requirements. For more information about context requirements, see Cryptography. This parameter can include any of the following values:
ISC_REQ_ALLOCATE_MEMORY | ISC_REQ_MUTUAL_AUTH
ISC_REQ_CALL_LEVEL | ISC_REQ_PROMPT_FOR_CREDS
ISC_REQ_CONFIDENTIALITY | ISC_REQ_REPLAY_DETECT
ISC_REQ_CONNECTION | ISC_REQ_SEQUENCE_DETECT
ISC_REQ_DATAGRAM | ISC_REQ_STREAM
ISC_REQ_DELEGATE | ISC_REQ_USE_DCE_STYLE
ISC_REQ_EXTENDED_ERROR | ISC_REQ_USE_SESSION_KEY
ISC_REQ_INTEGRITY | ISC_REQ_USE_SUPPLIED_CREDS

Reserved1
Reserved; set to zero.
TargetDataRep
Indicates the data representation (byte ordering, and so on) on the target. The constant SECURITY_NATIVE_DREP may be supplied by the transport application, indicating that the native format is in use.
pInput
Pointer to a SecBufferDesc structure that contains pointers to the buffers supplied as input to the package. The transport application should provide as much input as possible, although some packages may not be interested in the nonsecurity portions. This parameter is optional, particularly on the first call to InitializeSecurityContext.
Reserved2
Reserved; set to zero.
phNewContext
Pointer to the handle of a CtxtHandle structure. On the first call to InitializeSecurityContext, this pointer receives the new context handle. On the second call, this can be the same as the handle specified in the phContext parameter.
pOutput
Pointer to a SecBufferDesc structure that contains pointers to the buffers that receive the output data. If a buffer was typed as READWRITE in the input, it will be there on output. The system will allocate a buffer for the security token if requested (through ISC_REQ_ALLOCATE_MEMORY), and fill in the address in the buffer descriptor for the security token.
pfContextAttributes
Pointer to a variable that receives a set of bit flags indicating the attributes of the established context. For more information about context requirements, see Cryptography. This value can include any of the following flags:
ISC_RET_ALLOCATED_MEMORY | ISC_RET_MUTUAL_AUTH
ISC_RET_CALL_LEVEL | ISC_RET_REPLAY_DETECT
ISC_RET_CONFIDENTIALITY | ISC_RET_SEQUENCE_DETECT
ISC_RET_CONNECTION | ISC_RET_STREAM
ISC_RET_DATAGRAM | ISC_RET_USED_COLLECTED_CREDS
ISC_RET_DELEGATE | ISC_RET_USED_DCE_STYLE
ISC_RET_EXTENDED_ERROR | ISC_RET_USE_SESSION_KEY
ISC_RET_INTEGRITY | ISC_RET_USED_SUPPLIED_CREDS
ISC_RET_INTERMEDIATE_RETURN

ptsExpiry
Pointer to a TimeStamp variable that receives the expiration time of the context. The security provider should always return this value in local time.

Return Values

Upon success, one of the values described in the following table is returned.

Value
Description
SEC_E_OK | The security context was successfully initialized. There is no need for another InitializeSecurityContext call, and no response from the server is expected.
SEC_I_CONTINUE_NEEDED | The client must send the output token to the server, and then pass the token returned by the server in a second call to InitializeSecurityContext.
SEC_I_COMPLETE_NEEDED | The client must finish building the message, and then call the CompleteAuthToken function.
SEC_I_COMPLETE_AND_CONTINUE | The client must call CompleteAuthToken, then pass the output to the server, and finally make a second call to InitializeSecurityContext.

Upon failure, one of the error values described in the following table is returned.

Value
Description
SEC_E_INVALID_HANDLE | The handle passed to the function is invalid.
SEC_E_TARGET_UNKNOWN | The target was not recognized.
SEC_E_LOGON_DENIED | The logon failed.
SEC_E_INTERNAL_ERROR | The Local Security Authority cannot be contacted.
SEC_E_NO_CREDENTIALS | No credentials are available in the security package.
SEC_E_NO_AUTHENTICATING_AUTHORITY | No authority could be contacted for authentication.

Remarks

The InitializeSecurityContext function is used by a client to initialize an outbound context.

For a two-leg security package, the calling sequence is as follows:

  1. The client calls the function with phContext set to NULL and fills in the buffer descriptor with the input message.
  2. The security package examines the parameters and constructs an opaque token, placing it in the TOKEN element in the buffer array. If the fContextReq parameter includes the ISC_REQ_ALLOCATE_MEMORY flag, the security package allocates the memory and returns the pointer in the TOKEN element.
  3. The client sends the token returned in the pOutput buffer to the target server. The server then passes the token as an input argument in a call to the AcceptSecurityContext function.
  4. AcceptSecurityContext may return a token, which the server sends to the client for a second call to InitializeSecurityContext.

For a three-leg (mutual authentication) security package, the calling sequence is as follows:

  1. The client calls the function as described earlier, but the package will return the SEC_I_CONTINUE_NEEDED success code.
  2. The client then sends the output token to the server and waits for the server's reply.
  3. Upon receipt of the server's response, the client calls InitializeSecurityContext again, with phContext set to the handle that was returned from the first call. The token received from the server is supplied in the pInput parameter. If the server has successfully responded, then the security package will respond with success, otherwise, it will invalidate the context.

To initialize a security context, more than one call to this function may be required, depending on the underlying authentication mechanism as well as the "choices" specified in the fContextReq parameter.

The fContextReq and pfContextAttributes are bit masks representing various context attributes. For more information about context requirements, see Cryptography. The pfContextAttributes parameter is valid on any successful return, but only on the final successful return should you examine the flags pertaining to security aspects of the context. Intermediate returns can set, for example, the ISC_RET_ALLOCATED_MEMORY flag.

The caller is responsible for determining whether the final context attributes are sufficient; if, for example, confidentiality was requested, but could not be established, some applications may choose to shut down the connection immediately.

When the ISC_REQ_PROMPT_FOR_CREDS flag is set, the security package attempts to prompt the user for the credentials to use for the connection. If the caller is not an interactive user (for example, a noninteractive service), this flag is ignored. During the prompt, the package may inquire if the supplied credentials should be retained; if so, the package can store them away for future use, relieving the user of having to enter credentials later. This behavior, if supported, should be configurable for environments in which the credentials cannot or should not be stored away.

If the ISC_REQ_USE_SUPPLIED_CREDS flag is set, the security package should look for a SECBUFFER_PKG_PARAMS buffer type in the pInput input buffer. This is not a generic solution, but it allows for a strong pairing of security package and application when appropriate.

If the ISC_REQ_ALLOCATE_MEMORY was specified, the caller must free the memory by calling the FreeContextBuffer function.

For example, the input token could be the challenge from a LAN Manager or Windows NT file server. In this case, the output token would be the NTLM encrypted response to the challenge.

The action the client takes depends on the return code from this function. If the return code is SEC_E_OK, there will be no second InitializeSecurityContext call, and no response from the server is expected. If the return code is SEC_I_CONTINUE_NEEDED, the client expects a token in response from the server, and passes it in a second call to InitializeSecurityContext. The SEC_I_COMPLETE_NEEDED return code indicates that the client must finish building the message, and call the CompleteAuthToken function. The SEC_I_COMPLETE_AND_CONTINUE code, of course, incorporates both of these actions.

If the connection is rejected by the server, the client must call the DeleteSecurityContext function at that time to free any resources.

See Also

AcceptSecurityContext, CompleteAuthToken, DeleteSecurityContext, FreeContextBuffer


InitSecurityInterface

This function returns a pointer to a Security Service Provider Interface (SSPI) dispatch table. This function enables clients to use SSPI without binding directly to an implementation of the interface.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

PSecurityFunctionTable InitSecurityInterface(VOID);

Return Values

A pointer to a SecurityFunctionTable structure indicates success. NULL indicates failure.


InternetCanonicalizeUrl

This function converts a URL to a canonical form, including conversion of unsafe characters into escape sequences.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetCanonicalizeUrl(
LPCTSTR lpszUrl, LPTSTR lpszBuffer, LPDWORD lpdwBufferLength, DWORD dwFlags);

Parameters

lpszUrl
Long pointer to the null-terminated string that contains the input URL to canonicalize.
lpszBuffer
Long pointer to the buffer that receives the null-terminated string that contains the resulting canonicalized URL.
lpdwBufferLength
Long pointer to the length, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length of the lpszBuffer buffer—the length does not include the terminating null. If the function fails, this parameter receives the required length, in bytes, of the lpszBuffer buffer—the required length includes the terminating null.
dwFlags
Specifies control canonicalization. Can be one of the following values:
Value
Description
ICU_BROWSER_MODE | Does not encode or decode characters after "#" or "?", and does not remove trailing white space after "?". If this value is not specified, the entire URL is encoded, and trailing white space is removed.
ICU_DECODE | Converts all %XX sequences to characters, including escape sequences, before the URL is parsed.
ICU_ENCODE_SPACES_ONLY | Encodes spaces only.
ICU_NO_ENCODE | Does not convert unsafe characters to escape sequences.
ICU_NO_META | Does not remove meta sequences (such as "." and "..") from the URL.

If no flags are specified (dwFlags = 0), the function converts all unsafe characters and meta sequences (such as \.,\ .., and \...) to escape sequences.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible error values for GetLastError are described in the following table.

Value
Meaning
ERROR_BAD_PATHNAME | The URL could not be canonicalized.
ERROR_INSUFFICIENT_BUFFER | Canonicalized URL is too large to fit in the buffer provided. The *lpdwBufferLength parameter is set to the size, in bytes, of the buffer required to hold the resultant, canonicalized URL.
ERROR_INTERNET_INVALID_URL | The format of the URL is invalid.
ERROR_INVALID_PARAMETER | Bad string, buffer, buffer size, or flags parameter.

Windows CE Remarks

The lpdwBufferLength parameter refers to count of characters. If the function succeeds, this parameter receives the length, in characters, of the lpszBuffer buffer excluding the terminating null. If the function fails, this parameter receives the required length, in characters, of the lpszBuffer buffer, including the terminating null.

Remarks

InternetCanonicalizeUrl always encodes by default, even if the ICU_DECODE flag has been specified. To decode without re-encoding, use ICU_DECODE | ICU_NO_ENCODE. If the ICU_DECODE flag is used without ICU_NO_ENCODE, the URL is decoded before being parsed; unsafe characters then are re-encoded after parsing. This function will handle arbitrary protocol schemes, but to do so it must make inferences from the unsafe character set.

The application calling InternetCanonicalizeUrl should track the usage of this function on a particular URL. If unsafe characters in a URL have been converted to escape sequences, using InternetCanonicalizeUrl again on the URL (with no flags) will cause the escape sequences to be converted to another escape sequence. For example, a blank space in a URL would be converted to the escape sequence "%20". Calling InternetCanonicalizeUrl again on the URL would cause the escape sequence "%20" to be converted to the escape sequence "%2520", because the "%" sign is an unsafe character that is reserved for escape sequences and is replaced by the function with the escape sequence "%25".


InternetCloseHandle

This function closes a single Internet handle or a subtree of Internet handles.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetCloseHandle(HINTERNET hInternet);

Parameters

hInternet
Valid Internet handle to be closed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The function terminates any pending operations on the handle and discards any outstanding data. If a thread is blocking a call to Wininet.dll, another thread in the application can call InternetCloseHandle on the Internet handle being used by the first thread to cancel the operation and unblock the first thread.

If there is a status callback registered for the handle being closed and the handle was created with a non-NULL context value, an INTERNET_STATUS_HANDLE_CLOSING callback will be made. This indication will be the last callback made from a handle and indicates that the handle is being destroyed.

If asynchronous requests are pending for the handle or any of its child handles, the handle cannot be closed immediately, but it will be invalidated. Any new requests attempted using the handle will return with an ERROR_INVALID_HANDLE notification. The asynchronous requests will complete with INTERNET_STATUS_REQUEST_COMPLETE. Applications must be prepared to receive any INTERNET_STATUS_REQUEST_COMPLETE indications on the handle before the final INTERNET_STATUS_HANDLE_CLOSING indication is made, which indicates that the handle is completely closed.

An application can call GetLastError to determine if requests are pending. If GetLastError returns ERROR_IO_PENDING, there were outstanding requests when the handle was closed.

See Also

FtpFindFirstFile, FtpOpenFile, HttpOpenRequest, InternetConnect


InternetCombineUrl

This function combines a base and relative URL into a single URL. The resultant URL is canonicalized.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetCombineUrl(
LPCTSTR lpszBaseUrl, LPCTSTR lpszRelativeUrl, LPTSTR lpszBuffer,
LPDWORD lpdwBufferLength, DWORD dwFlags);

Parameters

lpszBaseUrl
Long pointer to the null-terminated string that contains the base URL to be combined.
lpszRelativeUrl
Long pointer to the null-terminated string that contains the relative URL to be combined.
lpszBuffer
Long pointer to a buffer that receives the null-terminated string that contains the resulting URL.
lpdwBufferLength
Long pointer to the size, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length, in characters, of the resultant combined URL—the length does not include the terminating null character. If the function fails, this parameter receives the length, in bytes, of the required buffer—the length includes the terminating null character.
dwFlags
Specifies the operation of the function. It is one of the following values:
Value
Description
ICU_BROWSER_MODE | Does not encode or decode characters after "#" or "?", and does not remove trailing white space after "?". If this value is not specified, the entire URL is encoded and trailing white space is removed.
ICU_DECODE | Converts all %XX sequences to characters, including escape sequences, before the URL is parsed.
ICU_ENCODE_SPACES_ONLY | Encodes spaces only.
ICU_NO_ENCODE | Does not convert unsafe characters to escape sequences.
ICU_NO_META | Does not remove meta sequences (such as "." and "..") from the URL.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible error values for GetLastError are described in the following table.

Value
Description
ERROR_BAD_PATHNAME | The URLs could not be combined.
ERROR_INSUFFICIENT_BUFFER | The buffer supplied to the function was insufficient or NULL. The DWORD indicated by the lpdwBufferLength parameter will contain the number of bytes required to hold the resultant, combined URL.
ERROR_INTERNET_INVALID_URL | The format of the URL is invalid.
ERROR_INVALID_PARAMETER | Bad string, buffer, buffer size, or flags parameter.

Windows CE Remarks

The lpdwBufferLength parameter refers to the count of characters.

See Also

InternetCanonicalizeUrl


InternetConnect

This function opens an FTP or HTTP session for a specified site.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

HINTERNET WINAPI InternetConnect(
HINTERNET hInternet, LPCTSTR lpszServerName,
INTERNET_PORT nServerPort, LPCTSTR lpszUserName ,
LPCTSTR lpszPassword , DWORD dwService, DWORD dwFlags,
DWORD dwContext);

Parameters

hInternet
Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.
lpszServerName
Long pointer to a null-terminated string that contains the host name of an Internet server. Alternately, the string can contain the IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).
nServerPort
Number of the TCP/IP port on the server to connect to. It is one of the following values. These flags set only the port that will be used. The service is set by the value of dwService.
Value
Description
INTERNET_DEFAULT_FTP_PORT | Uses the default port for FTP servers (port 21).
INTERNET_DEFAULT_HTTP_PORT | Uses the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT | Uses the default port for HTTPS servers (port 443).
INTERNET_DEFAULT_SOCKS_PORT | Uses the default port for SOCKS firewall servers (port 1080).
INTERNET_INVALID_PORT_NUMBER | Uses the default port for the service specified by dwService.

lpszUserName
Long pointer to a null-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP; a NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is "anonymous".
lpszPassword
Long pointer to a null-terminated string that contains the password to use to log on. If both lpszPassword and lpszUserName are NULL, the function uses the default "anonymous" password. In the case of FTP, the default password is the user's e-mail name. If lpszPassword is NULL, but lpszUserName is not NULL, the function uses a blank password. The behavior for the four possible settings of lpszUserName and lpszPassword is described in the following table.
lpszUserName
lpszPassword
User name sent to FTP server
Password sent to FTP server
NULL | NULL | "anonymous" | User's e-mail name
Non-NULL string NULL lpszUserName ""
NULL | Non-NULL string | ERROR | ERROR
Non-NULL string | Non-NULL string | lpszUserName | lpszPassword

dwService
Specifies the type of service to access. It is one of the following values:
Value
Description
INTERNET_SERVICE_FTP | FTP service.
INTERNET_SERVICE_HTTP | HTTP service.

dwFlags
Flags specific to the service used. When the value of dwService is INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE causes the application to use passive FTP semantics.
dwContext
Specifies the application-defined value that is used to identify the application context for the returned handle in callbacks.

Return Values

A valid handle to the FTP or HTTP session if the connection indicates success. NULL indicates failure. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo to determine why access to the service was denied.

Windows CE Remarks

The InternetConnect function returns a valid handle to the FTP or HTTP session if the connection is successful, or NULL otherwise.

The dwService parameter accepts INTERNET_SERVICE_FTP and INTERNET_SERVICE_HTTP as the types of service/protocol for use in the connection. However, it does not accept INTERNET_SERVICE_GOPHER, as GOPHER is not supported in Windows CE.

If DwFlags is set with INTERNET_FLAG_PASSIVE, the data transfers for the current FTP session occur in passive mode. INTERNET_FLAG_SECURE is not supported.

The dwContext parameter allows for progress status callbacks to the application, but all requests are handled synchronously.

When establishing a Secure Sockets Layer (SSL) or Private Communications Technology, InternetConnect uses INTERNET_DEFAULT_HTTPS_PORT instead of INTERNET_INVALID_PORT_NUMBER or INTERNET_DEFAULT_HTTP_PORT.

Remarks

The InternetConnect function is required before communicating with any Internet service.

Having a connect function for all protocols, even those that do not use persistent connections, lets an application communicate common information about several requests by using a single function call. In addition, this allows for future versions of Internet protocols that do not require a connection to be established for every client request.

For FTP sites, InternetConnect actually establishes a connection with the server.

For maximum efficiency, applications using the HTTP protocols should try to minimize calls to InternetConnect and avoid calling this function for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect; when the user makes a request to a previously accessed server, that session handle is still available.

An application that needs to display multiline text information sent by an FTP server can use InternetGetLastResponseInfo to retrieve the text.

For FTP connections, if lpszUsername is NULL, InternetConnect sends the string "anonymous" as the user name. If lpszPassword is NULL, InternetConnect attempts to use the user's e-mail name as the password.

To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function disconnects the client from the server and frees all resources associated with the connection.


InternetCrackUrl

This function cracks a URL into its component parts.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetCrackUrl(IN LPCTSTR lpszUrl, IN DWORD dwUrlLength, IN DWORD dwFlags, IN LPURL_COMPONENTS lpUrlComponents);

Parameters

lpszUrl
Long pointer to a null-terminated string that contains the canonical URL to crack.
dwUrlLength
Specifies the length of the lpszUrl string, or zero if lpszUrl is an ASCIIZ string.
dwFlags
Specifies the operation. It is one of the following values:
Value
Description
ICU_DECODE | Converts encoded characters back to their normal form. This can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into.
ICU_ESCAPE | Converts all escape sequences (%xx) to their corresponding characters. This can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into.

lpUrlComponents
Long pointer to a URL_COMPONENTS structure that receives the URL components.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

Always directly call the ANSI version of this function, InternetCrackUrlA.

The required components are indicated by members of the URL_COMPONENTS structure. Each component has a pointer to the value and has a member that stores the length of the stored value. If both the value and the length for a component are equal to zero, that component is not returned. If the pointer to the value of the component is NULL and the value of its corresponding length member is nonzero, the address of the first character of the corresponding component in the lpszUrl string is stored in the pointer, and the length of the component is stored in the length member.

If the pointer contains the address of the user-supplied buffer, the length member must contain the size of the buffer. InternetCrackUrl copies the component into the buffer, and the length member is set to the length of the copied component, minus 1 for the trailing string terminator.

For InternetCrackUrl to work properly, the size of the URL_COMPONENTS structure must be stored in the dwStructSize member.

See Also

FtpOpenFile, InternetCloseHandle, InternetFindNextFile, InternetSetStatusCallback


InternetCreateUrl

This function creates a URL from its component parts.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetCreateUrl(
LPURL_COMPONENTS lpUrlComponents, DWORD dwFlags,
LPTSTR lpszUrl, LPDWORD lpdwUrlLength);

Parameters

lpUrlComponents
Long pointer to a URL_COMPONENTS structure that contains the components from which to create the URL.
dwFlags
Specifies the operation of this function. It can be a combination of these values:
Value
Description
ICU_ESCAPE | Converts all escape sequences (%xx) to their corresponding characters.
ICU_USERNAME | When adding the user name, uses the name that was specified at logon time.
lpszUrl
Long pointer to a buffer that receives the null-terminated string that contains the URL.
lpdwUrlLength
Long pointer to the length, in bytes, of the lpszUrl buffer. When the function returns, this parameter receives the length, in bytes, of the URL string, minus 1 for the terminating character. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to hold the created URL.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

The lpdwUrlLength parameter refers to the count of characters.


InternetErrorDlg

This function displays a dialog box for the error that is passed to it, if an appropriate dialog box exists. If the FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag is used, the function also checks the headers for any hidden errors and displays a dialog box if needed.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

DWORD InternetErrorDlg (HWND hWnd, HINTERNET hRequest,
DWORD dwError, DWORD dwFlags, LPVOID *lppvData);

Parameters

hWnd
[in] Handle to the parent window for any needed dialog box. This parameter can be NULL if no dialog box is needed.
hRequest
[in] [out] HINTERNET handle to the Internet connection used in the call to HttpSendRequest.
dwError
[in] Error value for which to display a dialog box. Can be one of the following values:
Value
Description
ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR | Notifies the user of the zone crossing to and from a secure site.
ERROR_INTERNET_INCORRECT_PASSWORD | Displays a dialog box for obtaining the user's name and password. (On Microsoft Windows® 95, the function first attempts to use any cached authentication information for the server being accessed, before displaying a dialog box.)
ERROR_INTERNET_INVALID_CA | Notifies the user that the Win32® Internet function does not recognize the certificate authority that generated the certificate for this Secure Sockets Layer (SSL) site.
ERROR_INTERNET_POST_IS_NON_SECURE | Displays a warning about posting data to the server through a nonsecure connection.
ERROR_INTERNET_SEC_CERT_CN_INVALID | Indicates that the SSL certificate Common Name (hostname field) is incorrect. Displays an Invalid SSL Common Name dialog box, and lets the user view the incorrect certificate. Also allows the user to select a certificate in response to a server request.
ERROR_INTERNET_SEC_CERT_DATE_INVALID | Tells the user that the SSL certificate has expired.

dwFlags
[in] Unsigned long integer value that contains the action flags. Can be a combination of these values:
Value
Description
FLAGS_ERROR_UI_FILTER_FOR_ERRORS | Scans the returned headers for errors. Call after using HttpSendRequest. This option detects any hidden errors, such as an authentication error.
FLAGS_ERROR_UI_FLAGS_CHANGE_OPTIONS | If the function succeeds, stores the results of the dialog box in the Internet handle.
FLAGS_ERROR_UI_FLAGS_GENERATE_DATA | Queries the Internet handle for needed information. The function constructs the appropriate data structure for the error. (For example, for Cert CN failures, the function grabs the certificate.)
FLAGS_ERROR_UI_SERIALIZE_DIALOGS | Serializes authentication dialog boxes for concurrent requests on a password cache entry. The lppvData parameter should contain the address of a pointer to an INTERNET_AUTH_NOTIFY_DATA structure, and the client should implement a thread-safe, nonblocking callback function.

lppvData
[in] [out] Address of a data structure. The structure can be different for each error that needs to be handled.

Return Values

Returns one of the following values:

ERROR_SUCCESS
The function completed successfully.
ERROR_CANCELLED
The function was cancelled by the user.
ERROR_INTERNET_FORCE_RETRY
The function needs to redo its request.

Remarks

Authentication errors are hidden, since the call to HttpSendRequest will complete successfully, but the status code would indicate that the proxy or server requires authentication. The FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag causes the function to search the headers for status codes that indicate user input is needed.

See Also

HttpSendRequest


InternetFindNextFile

This function continues a file search from a previous call to FtpFindFirstFile.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetFindNextFile(HINTERNET hFind, LPVOID lpvFindData);

Parameters

hFind
Valid handle returned from FtpFindFirstFile or InternetOpenUrl (directories only).
lpvFindData
Long void pointer to the buffer that receives information about the found file or directory. The format of the information placed in the buffer depends on the protocol in use. The FTP protocol returns a WIN32_FIND_DATA structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.

Remarks

This Windows CE Internet API supports the full features of the corresponding Win32 Internet function for an internet handle returned by FtpFindFirstFile.


InternetGetCookie

This function retrieves the cookie for the specified URL.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL InternetGetCookie (LPCTSTR lpszUrl,
LPCTSTR lpszCookieName, LPSTR lpCookieData, LPDWORD lpdwSize);

Parameters

lpszUrl
[in] Address of a string that contains the URL to get cookies for.
lpszCookieName
[in] Address of a string that contains the name of the cookie to get for the specified URL. This has not been implemented in this release.
lpCookieData
[out] Address of the buffer that receives the cookie data. This value can be NULL.
lpdwSize
[in] [out] Address of an unsigned long integer variable that specifies the size of the lpszCookieData buffer. If the function succeeds, the buffer receives the amount of data copied to the lpszCookieData buffer. If lpszCookieData is NULL, this parameter receives a value that specifies the size of the buffer necessary to copy all the cookie data.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

This function does not require a call to InternetOpen. This function checks in the windows\cookies directory for persistent cookies that have an expiration date set sometime in the future. This function also searches memory for any session cookies (cookies that do not have an expiration date) that were created in the same process by InternetSetCookie, since these cookies are not written to any files. Rules for creating cookie files are internal to Win32® Internet functions and might change in the future.

See Also

InternetSetCookie


InternetGetLastResponseInfo

This function retrieves the last Windows CE Internet function error description or server response on the thread calling this function.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetGetLastResponseInfo( LPDWORD lpdwError, LPTSTR lpszBuffer , LPDWORD lpdwBufferLength);

Parameters

lpdwError
Long pointer to a variable that receives an error message pertaining to the operation that failed.
lpszBuffer
Long pointer to a buffer that receives the null-terminated string that contains the error text.
lpdwBufferLength
Long pointer to the size of the lpszBuffer buffer. When the function returns, this parameter contains the size of the string written to the buffer.

Return Values

TRUE indicates that the error text was successfully written to the buffer. FALSE indicates failure. To get extended error information, call GetLastError. If the buffer is too small to hold all the error text, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the lpdwBufferLength parameter contains the minimum buffer size required to return all the error text.

Remarks

The FTP protocol can return additional text information along with most errors. This extended error information can be retrieved by using the InternetGetLastResponseInfo function whenever GetLastError returns ERROR_INTERNET_EXTENDED_ERROR (occurring after an unsuccessful function call).

The buffer pointed to by lpszBuffer must be large enough to hold both the error string and a zero terminator at the end of the string. However, note that the value returned in lpdwBufferLength does not include the terminating zero.

InternetGetLastResponseInfo can be called multiple times until another Win32 Internet function is called on this thread. When another function is called, the internal buffer that is storing the last response information is cleared.


InternetLockRequestFile

This function allows the user to place a lock on the file that is being used.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL InternetLockRequestFile (HINTERNET hInternet,
HANDLE *lphLockRequestInfo );

Parameters

hInternet
[in] HINTERNET handle returned by FtpOpenFile, HttpOpenRequest, or InternetOpenUrl.
lphLockRequestInfo
[out] Address of a handle to store the lock request handle.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the HINTERNET handle passed to hInternet was created using INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE, the function creates a temporary file with the extension .tmp, unless it is an HTTPS resource. If the handle was created using INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE and it is accessing an HTTPS resource, InternetLockRequestFile fails.

See Also

InternetUnlockRequestFile


InternetOpen

This function initializes an application’s use of the Windows CE Internet functions.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

HINTERNET WINAPI InternetOpen(LPCTSTR lpszAgent, DWORD dwAccessType, LPCTSTR lpszProxy , LPCTSTR lpszProxyBypass , DWORD dwFlags);

Parameters

lpszAgent
Long pointer to a null-terminated string that contains the name of the application or entity calling the Internet functions (for example, Microsoft Internet Explorer). This name is used as the user agent in the HTTP protocol.
dwAccessType
Specifies the type of access required. It is one of the following values:
Value
Description
INTERNET_OPEN_TYPE_DIRECT | Resolves all host names locally.
INTERNET_OPEN_TYPE_PRECONFIG | Retrieves the proxy or direct configuration from the registry.
INTERNET_OPEN_TYPE_PRECONFIG_WITH_NO_AUTOPROXY | Retrieves the proxy or direct configuration from the registry and prevents the use of a startup JScript or Internet Setup (INS) file.
INTERNET_OPEN_TYPE_PROXY | Passes requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, the function uses INTERNET_OPEN_TYPE_DIRECT.

lpszProxyName
Long pointer to a null-terminated string that contains the name of the proxy server (or servers) to use if proxy access was specified. If this parameter is NULL, the function reads proxy information from the registry. Do not use an empty string, because InternetOpen will use it as the proxy name. The Win32 Internet functions only recognize CERN type proxies (HTTP only) and the TIS FTP gateway (FTP only). If Microsoft Internet Explorer is installed, the Win32 Internet functions also support SOCKS proxies. FTP requests can be made through a CERN type proxy either by changing them to an HTTP request or by using InternetOpenUrl.
lpszProxyBypass
Long pointer to a null-terminated string that contains an optional list of host names or IP addresses, or both, that should not be routed through the proxy. The list can contain wildcards. Do not use an empty string, because InternetOpen will use it as the proxy bypass list. If this parameter specifies the "<local>" macro as the only entry, the function bypasses any host name that does not contain a period. If this parameter is NULL, the function reads the bypass list from the registry.
dwFlags
Specifies various options affecting the behavior of the function. It can be a combination of these values:
  • INTERNET_FLAG_ASYNC
  • INTERNET_FLAG_FROM_CACHE
  • INTERNET_FLAG_OFFLINE

Return Values

A valid handle, which the application passes on to subsequent Win32 Internet functions, indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

The InternetOpen function makes available most of the functionality of the corresponding Win32 Internet function, including basic direct connections, proxy connections, and pre-configuration proxy settings. The type of internet access is specified by one of the three values assigned to the in parameter, dwAccessType:

INTERNET_OPEN_TYPE_DIRECT
Requests are made directly to the nominated server.
INTERNET_OPEN_TYPE_PROXY
Request are made through the nominated proxy.
INTERNET_OPEN_TYPE_PRECONFIG
Gets configuration from the registry. InternetOpen looks under the HKEY_CURRENT_USER\Comm\Wininet\ProxyServer key to determine the proxy configuration to use. If this key does not exist, or the string is NULL, all requests will be made directly to the nominated server. The string stored in the key must be in the form [<protocol>=][<scheme>://]<proxy>[:<port>].If the proxy server list is not registered in the registry or the string is NULL, Windows CE defaults to the INTERNET_OPEN_TYPE_DIRECT access.

Windows CE does not support multiple proxy servers. Thus, only one proxy can be specified for lpszProxy in the form: [<protocol>=][<scheme>://]<proxy>[:<port>] For example, “http://proxy:80” is allowed, but "ftp=ftp://ftp-gw http=http://jerhico:80" is not.

Windows CE does not support the proxy bypass lists; the lpszProxyBypass parameter must be NULL .

An application can accept the INTERNET_FLAG_ASYNC value for the dwFlags parameter, but only the InternetReadFile and InternetQueryDataAvailable functions can execute asynchronously. All other requests will be completed synchronously. However, it does not take the INTERNET_FLAG_OFFLINE flag as no caching features are available.

Remarks

InternetOpen is the first Win32 Internet function called by an application. It tells the Internet DLL to initialize internal data structures and prepare for future calls from the application. When the application finishes using the Internet functions, it should call InternetCloseHandle to free the handle and any associated resources.

The application can make any number of calls to InternetOpen, although a single call is normally sufficient. The application might need to have separate behaviors defined for each InternetOpen instance, such as different proxy servers configured for each.


InternetOpenUrl

This function begins reading a complete FTP or HTTP Universal Resource Locator (URL). For a relative URL and a base URL separated by blank spaces, InternetCanonicalizeUrl must be invoked first.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

HINTERNET InternetOpenUrl( HINTERNET hInternetSession,
LPCTSTR lpszUrl, LPCTSTR lpszHeaders , DWORD dwHeadersLength, DWORD dwFlags, DWORD dwContext);

Parameters

hInternetSession
Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.
lpszUrl
Long pointer to a null-terminated string that contains the URL to begin reading. Only URLs beginning with ftp:, http:, or https: are supported.
lpszHeaders
Long pointer to a null-terminated string that contains the headers to be sent to the HTTP server. (For more information, see the description of the lpszHeaders parameter in the HttpSendRequest function.)
dwHeadersLength
Specifies the length, in characters, of the additional headers. If this parameter is -1L and lpszHeaders is not NULL, lpszHeaders is assumed to be zero-terminated (ASCIIZ) and the length is calculated.
dwFlags
Specifies a bitmask of action flags. It is one of the following values:
Value
Description
INTERNET_FLAG_DONT_CACHE | Does not cache the data, either locally or in any gateways. Identical to the preferred value INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_EXISTING_CONNECT | If possible, reuses the existing connections to the server for new requests generated by InternetOpenUrl instead of creating a new session for each request. This flag is useful only for FTP connections, since FTP is the only protocol that typically performs multiple operations during the same session. The Win32 Internet API caches a single connection handle for each HINTERNET handle generated by InternetOpen.
INTERNET_FLAG-HYPERLINK | Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_IGNORE_CERT_CN_INVALID | Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules for HTTP requests.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID | Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates for HTTP requests.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP | Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS | Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs.
INTERNET_FLAG_KEEP_CONNECTION | Uses keep-alive semantics, if available, for the connection for HTTP requests. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication.
INTERNET_FLAG_MAKE_PERSISTENT | No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_AUTH | Does not attempt authentication automatically for HTTP requests.
INTERNET_FLAG_NO_AUTO_REDIRECT | Does not automatically handle redirection for HTTP requests only.
INTERNET_FLAG_NO_CACHE_WRITE | Does not cache the data, either locally or in any gateways.
INTERNET_FLAG_NO_COOKIES | Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database for HTTP requests.
INTERNET_FLAG_NO_UI | Disables the cookie dialog box.
INTERNET_FLAG_PASSIVE | Uses passive FTP semantics for FTP files and directories.
INTERNET_FLAG_RAW_DATA | Returns the data as a WIN32_FIND_DATA structure when retrieving FTP directory information. If this flag is not specified or if the call was made through a CERN proxy, InternetOpenUrl returns an HTML version of the directory.
INTERNET_FLAG_PRAGMA_NOCACHE | Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy.
INTERNET_FLAG_READ_PREFETCH | This flag is currently disabled.
INTERNET_FLAG_RELOAD | Gets the data from the wire even if it is locally cached.
INTERNET_FLAG_RESYNCHRONIZE | Reloads HTTP resources if the resource has been modified since the last time it was downloaded. All FTP resources are reloaded.
INTERNET_FLAG_SECURE | Requests secure transactions on the wire with SSL or PCT. This flag applies to HTTP requests only.

dwContext
Application-defined value that is passed, along with the returned handle, to any callback functions.

Return Values

A valid handle to the FTP or HTTP URL indicates that the connection is successfully established. NULL indicates that the connection fails. To get extended error information, call GetLastError. To determine why access to the service was denied, call InternetGetLastResponseInfo.

Windows CE Remarks

Windows CE supports only FTP and HTTP protocols. Only URLs beginning with FTP:, HTTP:, or secure HTTP (HTTPS:): are supported.

Windows CE supports only the following values for the dwFlags parameter:

  • INTERNET_FLAG_RAW_DATA
  • INTERNET_FLAG_SECURE

The dwContext parameter allows for progress status callbacks to the application, but all requests are handled synchronously.

When establishing a Secure Sockets Layer (SSL) or Private Communications Technology, the following two options can be used in InternetOpenUrl to ignore invalid certificate errors:

INTERNET_FLAG_IGNORE_CERT_CN_INVALID
This ignores errors caused when the certificate host name of the server does not match the host name in the request.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
This ignores errors caused by an expired server certificate.

Remarks

This is a general function that an application can use to retrieve data over any of the protocols that the Win32 Internet functions support. This function is particularly useful when the application does not need to access the particulars of a protocol, but only requires the data corresponding to a URL. The InternetOpenUrl function parses the URL string, establishes a connection to the server, and prepares to download the data identified by the URL. The application can then use InternetReadFile (for files) or InternetFindNextFile (for directories) to retrieve the URL data. It is not necessary to call InternetConnect before InternetOpenUrl.

Use InternetCloseHandle to close the handle returned from InternetOpenUrl. However, note that closing the handle before all the URL data has been read results in the connection being terminated.


InternetQueryDataAvailable

This function queries the amount of data available.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetQueryDataAvailable(HINTERNET hFile, LPDWORD lpdwNumberOfBytesAvailable, DWORD dwFlags, DWORD dwContext);

Parameters

hFile
Valid Internet file handle, as returned by InternetOpenUrl, FtpOpenFile, or HttpOpenRequest.
lpdwNumberOfBytesAvailable
Optional. Long pointer to a variable that receives the number of available bytes.
dwFlags
Reserved; set to zero.
dwContext
Reserved; set to zero.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.

Windows CE Remarks

Windows CE stipulates that the hFile parameter must be a valid Internet file handle returned by the FtpOpenFile, FtpFindFirstFile, or HttpOpenRequestt function.

The InternetQueryDataAvailable function can be completed in either synchronous or asynchronous mode.

Remarks

This function returns the number of bytes of data that are available to be read immediately by a subsequent call to InternetReadFile. If there is currently no data available and the end of the file has not been reached, the request waits until data becomes available. The amount of data remaining will not be recalculated until all available data indicated by the call to InternetQueryDataAvailable is read.

For HINTERNET handles created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetQueryDataAvailable can be used.


InternetQueryOption

This function queries an Internet option on the specified handle.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetQueryOption(
HINTERNET hInternet , DWORD dwOption, LPVOID lpBuffer OPTIONAL, LPDWORD lpdwBufferLength);

Parameters

hInternet
Internet handle on which to query information.
dwOption
Specifies the Internet option to query. Can be one of the Option Flags values.
lpBuffer
Long pointer to a buffer that receives the option setting.
lpdwBufferLength
Long pointer to a variable that contains the length of lpBuffer. When the function returns, the variable receives the length of the data placed into lpBuffer. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to hold the created URL.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

The following options may be queried through dwOption:

  • INTERNET_QUERY_OPTION_CALLBACK
  • INTERNET_OPTION_CONTEXT_VALUE
  • INTERNET_OPTION_CONNECT_TIMEOUT
  • INTERNET_OPTION_CONNECT_RETRIES
  • INTERNET_OPTION_CONNECT_BACKOFF
  • INTERNET_OPTION_CONTROL_SEND_TIMEOUT
  • INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
  • INTERNET_OPTION_DATA_SEND_TIMEOUT
  • INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
  • INTERNET_OPTION_READ_BUFFER_SIZE
  • INTERNET_OPTION_WRITE_BUFFER_SIZE
  • INTERNET_OPTION_USERNAME
  • INTERNET_OPTION_PASSWORD
  • INTERNET_OPTION_PROXY
  • INTERNET_OPTION_USER_AGENT
  • INTERNET_OPTION_HANDLE_TYPE
  • INTERNET_OPTION_PARENT_HANDLE

See Also

FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetSetOption


InternetReadFile

This function reads data from a handle opened by the FtpOpenFile, FtpFindFirstFile, or HttpOpenRequest function.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetReadFile(IN HINTERNET hFile, IN LPVOID lpBuffer, IN DWORD dwNumberOfBytesToRead, OUT LPDWORD lpdwNumberOfBytesRead);

Parameters

hFile
Valid handle returned from a previous call to InternetOpenUrl, FtpOpenFile, r HttpOpenRequest.
lpBuffer
Long pointer to a buffer that receives the data read.
dwNumberOfBytesToRead
Specifies the number of bytes to read.
lpNumberOfBytesRead
Long pointer to a variable that receives the number of bytes read. InternetReadFile sets this value to zero before doing any work or error checking.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo when necessary.

Windows CE Remarks

Windows CE supports valid internet handles returned by HTTPOpenRequest, FtpOpenFile, and FtpFindFirstFile.

The InternetReadFile function can be completed in either synchronous or asynchronous mode.

Remarks

If the return value is TRUE and the number of bytes read is zero, the transfer has been completed and there are no more bytes to read on the handle. This is analogous to reaching EOF in a local file. Call InternetCloseHandle to free the connection to the server.

The buffer pointed to by lpBuffer is not always filled by calls to InternetReadFile (sufficient data might not have arrived from the server). When reading HTML data, for the first read posted, the buffer must be large enough to hold the HTML headers. When reading HTML-encoded directory entries, the buffer must be large enough to hold at least one complete entry.

When the item being read is also being cached by a Win32 Internet function, the application must ensure that a read is made for end-of-file so the cache file is committed correctly.

This function always fulfills the user's request. If more data is requested than is available, the function waits until enough data to complete the request is available. The only time that less data is returned than requested is when the end of the file has been reached.

This function can also be used to retrieve FTP directory listings as an HTML document on a handle opened by InternetOpenUrl. The INTERNET_FLAG_RAW_DATA value must not have been specified in the call to InternetOpenUrl.

If the HINTERNET handle stored in hFile was created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetReadFile is used.


InternetReadFileEx

This function reads data from a handle opened by the InternetOpenUrl, FtpOpenFile, or HttpOpenRequest function.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL InternetReadFileEx (HINTERNET hFile,
LPINTERNET_BUFFERS lpBuffersOut, DWORD dwFlags,
DWORD dwContext );

Parameters

hFile
[in] HINTERNET handle returned from a previous call to InternetOpenUrl, FtpOpenFile, or HttpOpenRequest.
lpBuffersOut
[out] Address of an INTERNET_BUFFERS structure that contains the data downloaded.
dwFlags
[in] Unsigned long integer variable that contains the flags controlling the download. Can be one of the following values:
Value
Description
IRF_ASYNC | Identical to WININET_API_FLAG_ASYNC.
IRF_SYNC | Identical to WININET_API_FLAG_SYNC.
IRF_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT.
IRF_NO_WAIT | Do not wait for data. If there is data available, the function returns either the amount of data requested or the amount of data available (whichever is smaller).

dwContext
[in] Unsigned long integer variable that contains the context value used for asynchronous operations.

Return Values

Returns TRUE if successful, or FALSE otherwise.

See Also

InternetReadFile


InternetSetCookie

This function creates a cookie associated with the specified URL.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL InternetSetCookie (LPCTSTR lpszUrl, LPCTSTR lpszCookieName, LPCTSTR lpszCookieData);

Parameters

lpszUrl
[in] Address of a null-terminated string that specifies the URL for which the cookie should be set.
lpszCookieName
[in] Address of a string that contains the name to associate with the cookie data. If this parameter is NULL, no name is associated with the cookie.
lpszCookieData
[in] Address of the actual data to associate with the URL.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Cookies created by this function without an expiration date are stored in memory and are available only in the same process that created them. Cookies that include an expiration date are stored in the windows\cookies directory.

Creating a new cookie might cause a dialog box to appear on the screen if the appropriate registry value, AllowCookies, is set. There is no way to change the registry value from a WinInet function in Windows CE.

See Also

InternetGetCookie


InternetSetFilePointer

This function sets a file position for InternetReadFile. This is a synchronous call; however, subsequent calls to InternetReadFile might block or return pending if the data is not available from the cache and the server does not support random access.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

DWORD InternetSetFilePointer (HINTERNET hFile,
LONG lDistanceToMove, PVOID pReserved, DWORD dwMoveMethod, DWORD dwContext);

Parameters

hFile
[in] Valid HINTERNET handle returned from a previous call to InternetOpenUrl (on an HTTP or HTTPS URL) or HttpOpenRequest (using the GET or HEAD method and passed to HttpSendRequest or HttpSendRequestEx). This handle must not have been created with the INTERNET_FLAG_DONT_CACHE or INTERNET_FLAG_NO_CACHE_WRITE value set.
lDistanceToMove
[in] Long integer value that contains the number of bytes to move the file pointer. A positive value moves the pointer forward in the file; a negative value moves it backward.
pReserved
[in] Reserved. Must be set to NULL.
dwMoveMethod
[in] Unsigned long integer value that indicates the starting point for the file pointer move. Can be one of the following values:
Value
Description
FILE_BEGIN | Starting point is zero or the beginning of the file. If FILE_BEGIN is specified, lDistanceToMove is interpreted as an unsigned location for the new file pointer.
FILE_CURRENT | Current value of the file pointer is the starting point.
FILE_END | Current end-of-file position is the starting point. This method fails if the content length is unknown.

dwContext
Reserved. Must be set to zero.

Return Values

Returns the current file position if the function succeeds, or –1 otherwise.

Remarks

This function cannot be used once the end of file has been reached by InternetReadFile.

For HINTERNET handles created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before this function is used.

This function cannot be used reliably if the content length is unknown, and with chunked transfers.

See Also

InternetReadFile


InternetSetOption

This function sets an internet option on the specified handle.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetSetOption(HINTERNET hInternet, DWORD dwOption, LPVOID lpBuffer, DWORD dwBufferLength);

Parameters

hInternet
Internet handle on which to set information.
dwOption
Specifies the Internet option to set. Can be one of the Option Flags values.
lpBuffer
Long pointer to a buffer that contains the option setting.
dwBufferLength
Specifies the length of the lpBuffer buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

The following options can be set for dwOption:

  • INTERNET_OPTION_CONTEXT_VALUE
  • INTERNET_OPTION_CONNECT_TIMEOUT
  • INTERNET_OPTION_CONNECT_RETRIES
  • INTERNET_OPTION_CONNECT_BACKOFF
  • INTERNET_OPTION_CONTROL_SEND_TIMEOUT
  • INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
  • INTERNET_OPTION_DATA_SEND_TIMEOUT
  • INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
  • INTERNET_OPTION_READ_BUFFER_SIZE
  • INTERNET_OPTION_WRITE_BUFFER_SIZE
  • INTERNET_OPTION_USERNAME
  • INTERNET_OPTION_PASSWORD
  • INTERNET_OPTION_PROXY
  • INTERNET_OPTION_USER_AGENT

See Also

FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetQueryOption


InternetSetStatusCallback

This function sets up a callback function that Windows CE Internet functions can call as progress is made during an operation.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

INTERNET_STATUS_CALLBACK WINAPI InternetSetStatusCallback(HINTERNET hInternet, INTERNET_STATUS_CALLBACK fnInternetCallback);

Parameters

hInternet
Handle for which the callback is to be set.
lpfnInternetCallback
Long pointer to the callback function to call when progress is made, or to return NULL to remove the existing callback function. For more information about the callback function, see INTERNET_STATUS_CALLBACK.

Return Values

The previously defined status callback function indicates success. NULL indicates that there was no previously defined status callback function. INTERNET_INVALID_STATUS_CALLBACK indicates that the callback function is not valid.

Windows CE Remarks

The Windows CE InternetSetStatusCallback supports most features of the corresponding Win32 Internet function. The new status callback is exchanged with the old status callback. An application uses the callback function to indicate the progress of synchronous and asynchronous functions and to indicate the completion of an asynchronous request. In Windows CE only InternetReadFile and InternetQueryDataAvailable support asynchronous operations.

The status callback is used to indicate status to the application. The asynchronous request completion status is only supported for the functions with asynchronous completion: InternetReadFile and InternetQueryDataAvailable.

Remarks

Both synchronous and asynchronous functions use the callback function to indicate the progress of the request, such as resolving a name, connecting to a server, and so on. The callback function is required for an asynchronous operation. The asynchronous request will call back to the application with INTERNET_STATUS_REQUEST_COMPLETE to indicate the request has been completed.

A callback function can be set on any handle, and is inherited by derived handles. A callback function can be changed using InternetSetStatusCallback, providing there are no pending requests that need to use the previous callback value. Note, however, that changing the callback function on a handle does not change the callbacks on derived handles, such as that returned by InternetConnect. You must change the callback function at each level.

Many of the Win32 Internet functions perform several operations on the network. Each operation can take time to complete, and each can fail.

It is sometimes desirable to display status information during a long-term operation. You can display status information by setting up an Internet status callback function that cannot be removed as long as any callbacks or any asynchronous functions are pending.

After initiating InternetSetStatusCallback, the callback function can be accessed from within any Win32 Internet function for monitoring time-intensive network operations.


InternetTimeFromSystemTime

This function formats a date and time according to the specified RFC format — as specified in the Hypertext Transfer Protocol (HTTP) Specification 1.0.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI InternetTimeFromSystemTime(
CONST SYSTEMTIME *pst, DWORD dwRFC, LPTSTR lpszTime,
DWORD cbTime);

Parameters

pst
Pointer to a SYSTEMTIME structure that contains the date and time to format.
dwRFC
Specifies the RFC format used. Currently, the only valid format is INTERNET_RFC1123_FORMAT.
lpszTime
Long pointer to a buffer that receives the null-terminated string that contains the formatted date and time. The buffer should be of size INTERNET_RFC1123_BUFSIZE.
cbTime
Size, in bytes, of the lpszTime buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The cbTime parameter refers to the count of characters.


InternetTimeToSystemTime

This function takes an HTTP time/date string and converts it to a SYSTEMTIME structure.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.0 and later

Syntax

BOOL InternetTimeToSystemTime(LPCTSTR lpszTime, SYSTEMTIME *pst, DWORD dwReserved);

Parameters

lpszTime
Long pointer to a null-terminated date/time string to convert.
pst
Pointer to the converted time.
dwReserved
Reserved; set to zero.

Return Values

TRUE indicates that the string was converted. FALSE indicates failure. To get extended error information, call GetLastError.


InternetUnlockRequestFile

This function unlocks a file that was locked using InternetLockRequestFile.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL InternetUnlockRequestFile (HANDLE hLockRequestInfo);

Parameters

hLockRequestInfo
[in] Lock request handle that was returned by InternetLockRequestFile.

Return Values

Returns TRUE if successful, or FALSE otherwise.

See Also

InternetLockRequestFile


InternetWriteFile

This function writes data to an open Internet file.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL InternetWriteFile (HINTERNET hFile,
LPCVOID lpBuffer, DWORD dwNumberOfBytesToWrite,
LPDWORD lpdwNumberOfBytesWritten);

Parameters

hFile
[in] Valid HINTERNET handle returned from a previous call to FtpOpenFile or an HINTERNET handle sent by HttpSendRequestEx.
lpBuffer
[in] Address of a buffer that contains the data to be written to the file.
dwNumberOfBytesToWrite
[in] Unsigned long integer value that contains the number of bytes to write to the file.
lpdwNumberOfBytesWritten
[out] Address of an unsigned long integer variable that receives the number of bytes written to the buffer. This function sets this value to zero before doing any work or error checking.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the application is sending data, it must call InternetCloseHandle to end the data transfer.

See Also

InternetCloseHandle


ioctlsocket

This function controls the mode of a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int ioctlsocket (SOCKET s, long cmd, u_long *argp);

Parameters

s
[in] Descriptor that identifies a socket.
cmd
[in] Command to perform on the socket s.
argp
[in/out] Pointer to a parameter for cmd.

Return Values

Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The ioctlsocket function can be used on any socket in any state. It is used to set or retrieve operating parameters associated with the socket, independent of the protocol and communications subsystem. Here are the supported commands to use in the cmd parameter and their semantics:

FIONBIO
Use with a nonzero argp parameter to enable the nonblocking mode of socket s. The argp parameter is zero if nonblocking is to be disabled. The argp parameter points to an unsigned long value. When a socket is created, it operates in blocking mode by default (nonblocking mode is disabled). This is consistent with BSD sockets.
FIONREAD
Use to determine the amount of data pending in the network's input buffer that can be read from socket s. The argp parameter points to an unsigned long value in which ioctlsocket stores the result. If s is stream oriented (for example, type SOCK_STREAM), FIONREAD returns the amount of data that can be read in a single call to the recv function; this might not be the same as the total amount of data queued on the socket. If s is message oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.

See Also

getsockopt, socket, setsockopt, WSAStartup


lineAddProvider

This function installs a telephony service provider.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG lineAddProvider( LPCSTR lpszProviderFilename,
HWND hwndOwner, LPDWORD lpdwPermanentProviderID );

Parameters

lpszProviderFilename
A pointer to a NULL-terminated string that contains the path of the service provider to be added.
hwndOwner
A handle to a window in which any dialog boxes that need to be displayed as part of the installation process would be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpdwPermanentProviderID
A pointer to a DWORD-sized memory location into which TAPI writes the permanent provider identifier of the newly installed service provider.

Return Values

Returns zero if the request succeeds, or a negative error number if an error occurs. Possible return values are:

  • LINEERR_INIFILECORRUPT
  • LINEERR_NOMEM
  • LINEERR_INVALPARAM
  • LINEERR_NOMULTIPLEINSTANCE
  • LINEERR_INVALPOINTER
  • LINEERR_OPERATIONFAILED

Remarks

In Windows CE, TAPI uses a function pointer table to call the service provider instead of using exported ordinal entry points. In lineAddProvider, TAPI calls the service provider’s exported TSPI_lineGetProcTable function. This is the only function that a service provider need export. Then TAPI calls the service provider’s TSPI_providerInstall, TSPI_lineNegotiateTSPIVersion, TSPI_providerInit, and TSPI_providerEnumDevices.

See Also

lineInitialize


lineCallbackFunc

This function is a placeholder for the application-supplied function name.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

VOID FAR PASCAL lineCallbackFunc( DWORD hDevice,
DWORD dwMsg, DWORD dwCallbackInstance, DWORD dwParam1,
DWORD dwParam2, DWORD dwParam3 );

Parameters

hDevice
Handle to either a line device or a call associated with the callback. The nature of this handle, line handle or call handle, can be determined by the context provided by dwMsg. Applications must use the DWORD type for this parameter because using the HANDLE type may cause an error.
dwMsg
Specifies a line or call device message.
dwCallbackInstance
Specifies the callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.
dwParam1
Contains message-specific data.
dwParam2
Contains message-specific data.
dwParam3
Contains message-specific data.

Remarks

All callbacks occur in the application context. The callback function must reside in a DLL or application module.


lineClose

This function closes the specified open line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineClose(HLINE hLine);

Parameters

hLine
[in] Handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

  • LINEERR_INVALLINEHANDLE
  • LINEERR_NOMEM
  • LINEERR_OPERATIONFAILED
  • LINEERR_OPERATIONUNAVAIL
  • LINEERR_RESOURCEUNAVAIL
  • LINEERR_UNINITIALIZED

Remarks

If an application calls lineClose while it still has active calls on the opened line, the application's ownership of these calls is revoked. If the application owns these calls, the calls are dropped as well. It is good programming practice for an application to dispose of the calls it owns on an open line by explicitly relinquishing ownership and/or by dropping these calls prior to closing the line.

If the line was closed successfully, a LINE_LINEDEVSTATE message is sent to all applications monitoring the line status for open/close changes. Outstanding asynchronous replies are suppressed.

Service providers may find it useful or necessary to forcibly reclaim line devices from an application that has the line open. This can be useful to prevent an application from monopolizing the line device. If this happens, a LINE_CLOSE message is sent to the application, specifying the line handle of the line device that was closed.

The lineOpen function allocates resources to the invoking application, and applications can be prevented from opening a line if resources are unavailable. Therefore, an application that only occasionally uses a line device, such as for making outgoing calls, should close the line to free resources and enable other applications to open the line.

See Also

lineOpen


lineConfigDialogEdit

This function causes the provider of the specified line device to display a dialog box—attached to hwndOwner of the application—to enable the user to configure parameters related to the line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineConfigDialogEdit (DWORD dwDeviceID, HWND hwndOwner, LPCTSTR lpszDeviceClass, LPVOID const lpDeviceConfigIn, DWORD dwSize, LPVARSTRING lpDeviceConfigOut);

Parameters

dwDeviceID
[in] Specifies the line device to be configured.
hwndOwner
[in] Handle to a window to which the dialog box is attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpszDeviceClass
[in] Pointer to a null-terminated string that identifies a device class name. This device class enables the application to select a specific configuration data applicable to that device class. This parameter is optional and can be left NULL, in which case the highest level configuration is selected. If an empty string is specified, the function fails and returns LINEERR_INVALDEVICECLASS.
lpDeviceConfigIn
[in] Pointer to the opaque configuration data structure returned by lineGetDevConfig, or a previous invocation of lineConfigDialogEdit, in the variable portion of the VARSTRING structure.
dwSize
[in] Specifies the number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig or a previous invocation of lineConfigDialogEdit.
lpDeviceConfigOut
[out] Pointer to the memory location of type VARSTRING, where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig, or a future call to lineConfigDialogEdit, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning data.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_NOMEM
LINEERR_INVALDEVICECLASS | LINEERR_OPERATIONFAILED
LINEERR_INVALPARAM | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALPOINTER | LINEERR_RESOURCEUNAVAIL
LINEERR_NODEVICE | LINEERR_STRUCTURETOOSMALL
LINEERR_NODRIVER | LINEERR_UNINITIALIZED

Remarks

If LINEERR_STRUCTURETOOSMALL is returned, the dwTotalSize member of the VARSTRING structure pointed to by lpDeviceConfigOut does not specify enough memory to contain the entire configuration structure. The dwNeededSize member has been set to the amount required. To the extent that user entries were reflected in data that could not be returned due to insufficient space, those edits are lost; an application should therefore allocate the maximum amount of memory needed by the device class to return its configuration structure.

The lineConfigDialogEdit function causes the service provider to display a modal dialog box, attached to hwndOwner of the application, to enable the user to configure parameters related to the line specified by dwDeviceID.

The lpszDeviceClass parameter enables the application to select a specific subscreen of configuration data applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Communications API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Communications, or at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user does not have to search to find the parameters of interest.

The lpszDeviceClass parameter would be tapi/line or NULL to cause the provider to display the highest level configuration for the line.

With lineConfigDialogEdit, the parameters to edit are passed from the application, and the results are returned to the application, with no impact on active connections. The results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to lineSetDevConfig to affect the current call or next call.

See Also

lineOpen, lineGetID, lineGetDevConfig, lineSetDevConfig, VARSTRING


lineDeallocateCall

This function deallocates the specified call handle.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineDeallocateCall(HCALL hCall);

Parameters

hCall
[in] Call handle to be deallocated. An application with monitoring privileges for a call can always deallocate its handle for that call. An application with owner privilege for a call can deallocate its handle unless it is the sole owner of the call and the call is not in the idle state. The call handle is no longer valid after it has been deallocated.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

  • LINEERR_INVALCALLHANDLE
  • LINEERR_INVALCALLSTATE
  • LINEERR_NOMEM
  • LINEERR_OPERATIONFAILED
  • LINEERR_RESOURCEUNAVAIL
  • LINEERR_UNINITIALIZED

Remarks

The deallocation does not affect the call state of the physical call. It does, however, release internal resources related to the call.

In TAPI versions earlier than 2.0, if the application is the sole owner of a call and the call is not in the idle state, LINEERR_INVALCALLSTATE is returned. In this case, the application can first drop the call using lineDrop and deallocate its call handle afterwards. An application that has monitor privilege for a call can always deallocate its handle for the call.

Note Be aware that leaving the call without an owner can result in the user being unable to terminate the call if there are monitoring applications open preventing TAPI from calling TSPI_lineCloseCall. Use this feature only if the application can determine that the call can be controlled externally by the user. For more information, see LINEADDRCAPFLAGS_CLOSEDROP.

When the lineDeallocateCall function deallocates a call handle, it also suspends further processing of any outstanding LINE_REPLY messages for the call. An application must be designed not to wait indefinitely for LINE_REPLY messages for each corresponding call to an asynchronous function if it also uses the lineDeallocateCall function to deallocate handles.


lineDrop

This function drops or disconnects the specified call. The application has the option to specify user-to-user data to be transmitted as part of the call disconnect.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineDrop(HCALL hCall, LPCTSTR lpsUserUserInfo,
DWORD dwSize);

Parameters

hCall
[in] Handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.
lpsUserUserInfo
[in] Pointer to a string that contains user data to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-to-user data is to be sent. User-to-user data is only sent if supported by the underlying network . For more information, see LINEDEVCAPS. The protocol field for the user-to-user data, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
[in] Specifies the size, in bytes, of the user-to-user data in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user data is sent to the calling party and dwSize is ignored.

Return Values

Zero indicates success. A negative error number indicates that an error has occurred. Possible error values are as follows:

LINEERR_INVALCALLHANDLE | LINEERR_RESOURCEUNAVAIL
LINEERR_OPERATIONUNAVAIL | LINEERR_INVALPOINTER
LINEERR_NOMEM | LINEERR_USERUSERINFOTOOBIG
LINEERR_OPERATIONFAILED | LINEERR_INVALCALLSTATE
LINEERR_NOTOWNER | LINEERR_UNINITIALIZED

Remarks

When invoking lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call can drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call typically transitions to the idle state. Invoking lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

A call in the onholdpending state typically reverts to the connected state. When dropping the consultation call to the third party for a conference call or when removing the third party in a previously established conference call, the provider, and switch, can release the conference bridge and revert the call back to a normal two-party call. If this is the case, hConfCall shifts to the idle state, and the only remaining participating call transitions to the connected state. Some switches automatically release the hold on the other call.

The application has the option to send user-to-user data at the time of the drop. Even if user-to-user data can be sent, there is no guarantee that the network will deliver this data to the remote party.

In various bridged or party-line configurations, when multiple parties are on the call, lineDrop may not actually clear the call. For example, in a bridged situation, a lineDrop operation may not actually drop the call because the status of other stations on the call may govern; instead, the call may simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

See Also

LINE_CALLSTATE, LINE_REPLY


lineGetDevCaps

This function queries a specified line device to determine its telephony capabilities. The returned data is valid for all addresses on the line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineGetDevCaps(HLINEAPP hLineApp, DWORD dwAPIVersion, DWORD dwDeviceID, DWORD dwExtVersion,
LPLINEDEVCAPS lpLineDevCaps);

Parameters

hLineApp
[in] Handle to the application's registration with TAPI.
dwDeviceID
[in] Specifies the line device to be queried.
dwAPIVersion
[in] Specifies the version number of TAPI to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.
dwExtVersion
[in] Not supported; set to zero.
lpLineDevCaps
[out] Pointer to a variable sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities data. Prior to calling lineGetDevCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning data.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_NOMEM
LINEERR_INCOMPATIBLEAPIVERSION | LINEERR_OPERATIONFAILED
LINEERR_INCOMPATIBLEEXTVERSION | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALAPPHANDLE | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALPOINTER | LINEERR_STRUCTURETOOSMALL
LINEERR_NODEVICE | LINEERR_UNINITIALIZED
LINEERR_NODRIVER |

Remarks

Before using lineGetDevCaps, the application must negotiate the TAPI version to use, and, if desired, the extension version to use.

The TAPI and extension version numbers are those under which TAPI and the service provider must operate. If version ranges do not overlap, the application, TAPI, or service-provider versions are incompatible and an error is returned.

One of the members in the LINEDEVCAPS structure returned by this function contains the number of addresses assigned to the specified line device. The actual address identifiers used to reference individual addresses vary from zero through one less than the returned number. The capabilities of each address can be different. Use lineGetAddressCaps for each available <dwDeviceID, dwAddressID> combination to determine the exact capabilities of each address.

See Also

lineNegotiateAPIVersion


lineGetDevConfig

This function returns an opaque data structure object, the contents of which are specific to the line, service provider, and device class. The data structure object stores the current configuration of a media-stream device associated with the line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineGetDevConfig (DWORD dwDeviceID,
LPVARSTRING lpDeviceConfig, LPCTSTR lpszDeviceClass);

Parameters

dwDeviceID
[in] Specifies the line device to be configured.
lpDeviceConfig
[out] Pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning data.
lpszDeviceClass
[out] Pointer to a null-terminated string that specifies the device class of the device whose configuration is requested. Valid device class lineGetID strings are the same as those specified for the function.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_OPERATIONFAILED
LINEERR_INVALDEVICECLASS | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALPOINTER | LINEERR_RESOURCEUNAVAIL
LINEERR_NODEVICE | LINEERR_STRUCTURETOOSMALL
LINEERR_NODRIVER | LINEERR_UNINITIALIZED
LINEERR_NOMEM |

Remarks

For Windows CE, lineGetDevConfig always returns a default configuration for a device. There are two advantages to this behavior. First, if a user chooses the default settings, then an application does not need to store the associated configuration (for example in a connectoid). Second, the lineConfigDialogEdit dialog can be easily made to always come up in the same state.

Call states are device specific.

The lineGetDevConfig function can be used to retrieve a data structure from TAPI that specifies the configuration of a media stream device associated with a particular line device. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in lineSetDevConfig to restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this can work in some instances, it is not guaranteed). An application can use lineConfigDialogEdit to manipulate the configuration.

See Also

lineGetID


lineGetID

This function returns a device identifier for the specified device class associated with the selected line, address, or call.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineGetID(HLINE hLine, DWORD dwAddressID, HCALL hCall, DWORD dwSelect, LPVARSTRING lpDeviceID, LPCTSTR lpszDeviceClass);

Parameters

hLine
[in] Handle to an open line device.
dwAddressID
[in] Specifies an address on the given open line device.
hCall
[in] Handle to a call.
dwSelect
[in] Specifies whether the requested device identifier is associated with the line, address or a single call. The dwSelect parameter can only have a single flag set. This parameter uses the following LINECALLSELECT_* constants:
Value
Description
LINECALLSELECT_LINE | Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS | Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL | Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.

lpDeviceID
[out] Pointer to a memory location of type VARSTRING, where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned data depends on the method used by the device class API for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning data.
lpszDeviceClass
[out] Pointer to a null-terminated string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the System.ini section to identify device classes.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_INVALLINEHANDLE | LINEERR_INVALCALLSELECT
LINEERR_NOMEM | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALADDRESSID | LINEERR_INVALPOINTER
LINEERR_OPERATIONUNAVAIL | LINEERR_STRUCTURETOOSMALL
LINEERR_INVALCALLHANDLE | LINEERR_NODEVICE
LINEERR_OPERATIONFAILED | LINEERR_UNINITIALIZED

Remarks

The lineGetID function can be used to retrieve a line-device identifier when given a line handle. This function can also be used to obtain the device identifier of a phone device or media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with a call, address or line. This identifier can then be used with the appropriate API (such as phone, MIDI, wave) to select the corresponding media device associated with the specified call.

The following table shows device class names.

Device class name
Description
comm * | Communication port
comm/datamodem * | Modem through a communication port
comm/datamodem/portname | Name of the device to which a modem is connected
wave/in | Wave audio device (input only)
wave/out | Wave audio device (output only)
midi/in | Midi sequencer (input only)
midi/out | Midi sequencer (output only)
tapi/line * | Line device
tapi/phone | Phone device
ndis * | Network device
tapi/terminal | Terminal device

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

See Also

lineGetDevConfig, VARSTRING


lineGetTranslateCaps

This function returns address translation capabilities.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineGetTranslateCaps(HLINEAPP hLineApp, DWORD dwAPIVersion, LPLINETRANSLATECAPS lpTranslateCaps);

Parameters

hLineApp
[in] Application handle returned by lineInitialize. If an application has not yet called the lineInitialize function, it can set the hLineApp parameter to NULL.
dwAPIVersion
[in] Specifies the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpTranslateCaps
[out] Pointer to a location to which a LINETRANSLATECAPS structure is loaded. Prior to calling lineGetTranslateCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning data.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_INVALAPPHANDLE | LINEERR_NOMEM
LINEERR_INCOMPATIBLEAPIVERSION | LINEERR_OPERATIONFAILED
LINEERR_INIFILECORRUPT | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALPOINTER | LINEERR_STRUCTURETOOSMALL
LINEERR_NODRIVER |

See Also

lineInitialize


lineInitialize

This function initializes the application’s use of Tapi.dll for subsequent use of the line abstraction. It registers the application’s specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in TAPI.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineInitialize(LPHLINEAPP lphLineApp, HINSTANCE hInstance, LINECALLBACK lpfnCallback, LPCTSTR lpszAppName,
LPDWORD lpdwNumDevs);

Parameters

lphLineApp
[out] Pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
[in] Instance handle of the client application or DLL.
lpfnCallback
[in] Pointer to a callback function that is invoked to determine status and events on the line device, addresses, or calls. For more information, see lineCallbackFunc.
lpszAppName
[in] Pointer to a null-terminated string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This data can be useful for call logging purposes. If lpszAppName is NULL, the application's filename is used instead.
lpdwNumDevs
[out] Pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_INVALAPPNAME | LINEERR_REINIT
LINEERR_OPERATIONFAILED | LINEERR_NODRIVER
LINEERR_INIFILECORRUPT | LINEERR_NODEVICE
LINEERR_RESOURCEUNAVAIL | LINEERR_NOMEM
LINEERR_INVALPOINTER | LINEERR_NOMULTIPLEINSTANCE

Remarks

If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example as a result of adding or removing a telephony service provider), then lineInitialize requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call lineInitialize. If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of anything beyond what is specified by the Basic Telephony subset without first querying their device capabilities using lineGetDevCaps.

Applications should not invoke lineInitialize without subsequently opening a line (at least for monitoring). If the application is not monitoring and not using any devices, it should call lineShutdown so that memory resources allocated by Tapi.dll can be released if unneeded, and Tapi.dll itself can be unloaded from memory while not needed.

Another reason for performing a lineShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. After a reconfiguration has taken place, causing a LINEDEVSTATE_REINIT message to be sent, no applications can open a device until all applications have performed a lineShutdown. If any service provider fails to initialize properly, this function fails and returns the error indicated by the service provider.

See Also

lineGetDevCaps, lineShutdown


lineMakeCall

This function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineMakeCall(HLINE hLine, LPHCALL lphCall,
LPCTSTR lpszDestAddress, DWORD dwCountryCode,
LPLINECALLPARAMS const lpCallParams);

Parameters

hLine
[in] Handle to the open line device on which a call is to be originated.
lphCall
[in] Pointer to an HCALL handle. The handle is only valid after the LINE_REPLY message is received by the application indicating that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application is initially the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously by the reply message).
lpszDestAddress
[in] Pointer to the null-terminated string that contains the destination address. This follows the standard dialable number format. This pointer can be NULL for non-dialed addresses (as with a hot phone). Service providers that have inverse multiplexing capabilities can enable an application to specify multiple addresses at once.
dwCountryCode
[in] Specifies the country code of the called party. If a value of 0 is specified, a default is used by the implementation.
lpCallParams
[in] Pointer to a LINECALLPARAMS structure. This structure enables the application to specify how it wants the call to be set up. If NULL is specified, a default 3.1 kHz voice call is established and an arbitrary origination address on the line is selected. This structure enables the application to select elements such as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller identification data, and dialing parameters.

Return Values

A positive request identifier indicates that the function is completed asynchronously. A negative error number indicates that an error has occurred. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible error values are as follows:

LINEERR_ADDRESSBLOCKED | LINEERR_INVALLINEHANDLE
LINEERR_BEARERMODEUNAVAIL | LINEERR_INVALLINESTATE
LINEERR_CALLUNAVAIL | LINEERR_INVALMEDIAMODE
LINEERR_DIALBILLING | LINEERR_INVALPARAM
LINEERR_DIALDIALTONE | LINEERR_INVALPOINTER
LINEERR_DIALPROMPT | LINEERR_INVALRATE
LINEERR_DIALQUIET | LINEERR_NOMEM
LINEERR_INUSE | LINEERR_OPERATIONFAILED
LINEERR_INVALADDRESS | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALADDRESSID | LINEERR_RATEUNAVAIL
LINEERR_INVALADDRESSMODE | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALBEARERMODE | LINEERR_STRUCTURETOOSMALL
LINEERR_INVALCALLPARAMS | LINEERR_UNINITIALIZED
LINEERR_INVALCOUNTRYCODE | LINEERR_USERUSERINFOTOOBIG

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE_) in the LINEDEVSTATUS structure. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineMakeCall have occurred; for example, none of the dialable address prior to the offending character has been dialed, no hook switch state has changed, and so on.

After dialing has completed, several LINE_CALLSTATE messages are usually sent to the application to notify it about the progress of the call. No generally valid sequence of call-state transitions is specified, as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence can cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call can typically transition directly to connected state.

An application has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device enables the application to originate calls from any of these stations using lineMakeCall.

The call parameters enable the application to make non-voice calls or request special call setup options that are not available by default.

An application can partially dial using lineMakeCall and continue dialing using lineDial. To abandon a call attempt, use lineDrop.

After lineMakeCall returns a success reply message to the application, a LINE_CALLSTATE message is sent to the application to indicate the current state of the call. This state is not necessarily LINECALLSTATE_DIALTONE.

For Windows CE versions 1.0 through 2.11, lineMakeCall does not handle timeouts correctly. If a connection fails after lineMakeCall returns but before the associated LINE_REPLY message is received, a LINE_REPLY message is not generated. Because a LINE_REPLY message is never received, an application does not have the handle for the call. Without a handle, an application cannot call lineDrop nor lineDeallocateCall free call resources. Because call resources are never deallocated, a call fails that is placed on the line before it is closed.

For Windows CE versions 2.12 and later, the timeout problem is addressed by UNIMODEM sending a LINEMAKECALL_TIMEOUT message after eight seconds without a response.

See Also

LINECALLPARAMS


lineNegotiateAPIVersion

This function enables an application to negotiate an TAPI version to use.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineNegotiateAPIVersion(HLINEAPP hLineApp,
DWORD dwDeviceID, DWORD dwAPILowVersion,
DWORD dwAPIHighVersion, LPDWORD lpdwAPIVersion,
LPLINEEXTENSIONID lpExtensionID);

Parameters

hLineApp
[in] Handle to the application's registration with TAPI.
dwDeviceID
[in] Specifies the identifier of the line device to be queried.
dwAPILowVersion
[in] Specifies the least recent TAPI version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwAPIHighVersion
[in] Specifies the most recent TAPI version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwAPIVersion
[out] Pointer to a DWORD-sized location that contains the TAPI version number that was negotiated. If negotiation succeeds, this number is in the range between dwAPILowVersion and dwAPIHighVersion.
lpExtensionID
[out] Ignored; set to NULL.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_
LINEERR_NODRIVER | LINEERR_UNINITIALIZED
LINEERR_INCOMPATIBLEAPIVERSION | LINEERR_NOMEM
LINEERR_OPERATIONFAILED | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALAPPHANDLE | LINEERR_NODEVICE
LINEERR_RESOURCEUNAVAIL |

Remarks

Use lineInitialize to determine the number of line devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function is used to negotiate the TAPI version number to use. It also retrieves the extension identifier supported by the line device, and returns zeros if no extensions are supported. If the application wants to use the extensions defined by the returned extension identifier, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The TAPI version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application and API or service provider versions are incompatible and an error is returned.

See Also

lineInitialize


lineOpen

This function opens the line device specified by its device identifier and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineOpen(HLINEAPP hLineApp, DWORD dwDeviceID,
LPHLINE lphLine, DWORD dwAPIVersion, DWORD dwExtVersion,
DWORD dwCallbackInstance, DWORD dwPrivileges,
DWORD dwMediaModes, LPLINECALLPARAMS const lpCallParams);

Parameters

hLineApp
[in] Handle to the application's registration with TAPI.
dwDeviceID
[in] Species the identifier of the line device to be opened. It must be a valid device identifier.
lphLine
[out] Pointer to an HLINE handle that is then loaded with the handle representing the opened line device. Use this handle to identify the device when invoking other functions on the open line device.
dwAPIVersion
[in] Specifies the TAPI version number under which the application and TAPI have agreed to operate. This number is obtained with lineNegotiateAPIVersion.
dwExtVersion
[in] Unsupported; set to zero.
dwCallbackInstance
[in] Specifies user-instance data passed back to the application with each message associated with this line or with addresses or calls on this line. This parameter is not interpreted by TAPI.
dwPrivileges
[in] Specifies the privilege the application wants for the calls it is notified for. This parameter can be a combination of the LINECALLPRIVILEGE_* constants.
Value
Description
LINECALLPRIVILEGE_NONE | The application can make only outgoing calls.
LINECALLPRIVILEGE_MONITOR | The application can monitor only incoming and outgoing calls.
LINECALLPRIVILEGE_OWNER | The application can own only incoming calls of the types specified in dwMediaModes.
LINECALLPRIVILEGE_MONITOR + LINECALLPRIVILEGE_OWNER | The application can own only incoming calls of the types specified in dwMediaModes, but if it is not an owner of a call, it is a monitor.

Other flag combinations are invalid.

dwMediaModes
[in] Specifies the media mode or modes of interest to the application. This parameter is used to register the application as a potential target for incoming call and call handoff for the specified media mode. This parameter is meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is not). This parameter uses the following LINEMEDIAMODE_* constants:
Value
Description
LINEMEDIAMODE_UNKNOWN | The application can handle calls of unknown media type (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE | The application can handle calls of the interactive voice media type. That is, it manages voice calls with the human user on this end of the call.
LINEMEDIAMODE_AUTOMATEDVOICE | Voice energy is present on the call. The voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM | The application can handle calls with the data-modem media mode.
LINEMEDIAMODE_G3FAX | The application can handle calls of the group 3 fax media type.
LINEMEDIAMODE_TDD | The application can handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX | The application can handle calls of the group 4 fax media type.
LINEMEDIAMODE_DIGITALDATA | The application can handle calls of the digital-data media type.
LINEMEDIAMODE_TELETEX | The application can handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX | The application can handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX | The application can handle calls with the telex media mode.
LINEMEDIAMODE_MIXED | The application can handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI | The application can handle calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW | The media mode of the call is VoiceView.

lpCallParams
[in] Pointer to a structure of type LINECALLPARAMS. This pointer should be set to NULL for Windows CE 2.x.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_ALLOCATED | LINEERR_NODEVICE
LINEERR_BADDEVICEID | LINEERR_NODRIVER
LINEERR_INCOMPATIBLEAPIVERSION | LINEERR_NOMEM
LINEERR_INCOMPATIBLEEXTVERSION | LINEERR_OPERATIONFAILED
LINEERR_INVALAPPHANDLE | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALMEDIAMODE | LINEERR_REINIT
LINEERR_INVALPOINTER | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALPRIVSELECT | LINEERR_STRUCTURETOOSMALL
LINEERR_LINEMAPPERFAILED | LINEERR_UNINITIALIZED

Remarks

If LINEERR_ALLOCATED is returned, the line cannot be opened due to a "persistent" condition, such as that of a serial port being exclusively opened by another process. If LINEERR_RESOURCEUNAVAIL is returned, the line cannot be opened due to a dynamic resource overcommitment such as in DSP processor cycles or memory. This overcommitment can be transitory, caused by monitoring of media mode or tones, and changes in these activities by other applications can make it possible to reopen the line within a short time period. If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example, as a result of adding or removing a telephony service provider), then lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown); at that time the new configuration becomes effective and applications are once again permitted to call lineInitialize.

Opening a line always entitles the application to make calls on any address available on the line. The ability of the application to deal with incoming calls or to be the target of call handoffs on the line is determined by the dwMediaModes parameter. The lineOpen function registers the application as having an interest in monitoring calls or receiving ownership of calls that are of the specified media modes. If the application just wants to monitor calls, then it can specify LINECALLPRIVILEGE_MONITOR. If the application just wants to make outgoing calls, it can specify LINECALLPRIVILEGE_NONE. If the application is willing to control unclassified calls (calls of unknown media mode), it can specify LINECALLPRIVILEGE_OWNER and LINEMEDIAMODE_UNKNOWN. Otherwise, the application should specify the media mode it is interested in handling.

The media modes specified with lineOpen add to the default value for the provider's media mode monitoring for initial incoming call type determination. If a line device is opened with owner privilege and an extension media mode is not registered, then the error LINEERR_INVALMEDIAMODE is returned.

An application that has successfully opened a line device can initiate calls using lineMakeCall.

A single application can specify multiple flags simultaneously to handle multiple media modes. Conflicts can arise if multiple applications open the same line device for the same media mode. These conflicts are resolved by a priority scheme in which the user assigns relative priorities to the applications. Only the highest priority application for a given media mode will ever receive ownership (unsolicited) of a call of that media mode. Ownership can be received when an incoming call first arrives or when a call is handed off.

An application that handles automated voice should also select the interactive voice open mode and be assigned the lowest priority for interactive voice. The reason for this is that service providers report all voice media modes as interactive voice. If media mode determination is not performed by the application for the UNKNOWN media type, and no interactive voice application has opened the line device, voice calls would be unable to reach the automated voice application, and would be dropped.

The same application, or different installations of the same application, can open the same line multiple times with the same or different parameters.

When an application opens a line device it must specify the negotiated TAPI version, which is obtained with a call to lineNegotiateAPIVersion. Version numbering enables the mixing and matching of different application versions with different TAPI versions.

See Also

LINECALLPARAMS, lineGetID, lineInitialize, lineMakeCall, lineNegotiateAPIVersion, lineShutdown


lineSetCurrentLocation

This function sets the location used as the context for address translation.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 2.10 and later

Syntax

LONG lineSetCurrentLocation( HLINEAPP hLineApp, DWORD dwLocation );

Parameters

hLineApp
[in] Application handle returned by lineInitialize. If an application has not yet called the lineInitialize function, it can set the hLineApp parameter to NULL.
dwLocation
[in] Specifies a new value for the CurrentLocation entry in the [Locations] section in the registry. It must contain a valid permanent identifier of a Location entry in the [Locations] section, as obtained from lineGetTranslateCaps. If it is valid, the CurrentLocation entry is updated.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_INIFILECORRUPT | LINEERR_NOMEM
LINEERR_INVALAPPHANDLE | LINEERR_OPERATIONFAILED
LINEERR_INVALLOCATION | LINEERR_RESOURCEUNAVAIL
LINEERR_NODRIVER | LINEERR_UNINITIALIZED


lineSetDevConfig

This function enables the application to restore the configuration of a media-stream device on a line device to a setup previously obtained using the lineGetDevConfig function. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineSetDevConfig (DWORD dwDeviceID,
LPVOID const lpDeviceConfig, DWORD dwSize, LPCTSTR lpszDeviceClass);

Parameters

dwDeviceID
[in] Specifies the line device to be configured.
lpDeviceConfig
[in] Pointer to the opaque configuration data structure that was returned by lineGetDevConfig in the variable portion of the VARSTRING structure.
dwSize
[in] Specifies the number of bytes in the structure pointed to by lpDeviceConfig. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig.
lpszDeviceClass
[in] Pointer to a null-terminated string that specifies the device class of the device whose configuration is to be set. Valid device class strings are the same as those specified for the lineGetID function.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_NODEVICE
LINEERR_NODRIVER | LINEERR_NOMEM
LINEERR_INVALDEVICECLASS | LINEERR_OPERATIONFAILED
LINEERR_INVALLINESTATE | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALPARAM | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALPOINTER | LINEERR_UNINITIALIZED

Remarks

Call states are device specific.

Typically, an application calls lineGetID to identify the media stream device associated with a line, and then calls lineConfigDialogEdit to enable the user to change the device configuration and affect the current call or next call with those changes by passing the output of lineConfigDialogEdit to lineSetDevConfig. When the user wants to call the same destination again, this lineSetDevConfig function can be used to restore the configuration settings selected by the user.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The application must treat it as "opaque" and not manipulate the contents directly. Generally, the structure can be sent using this function only to the same device from which it was obtained. Certain telephony service providers may, however, permit structures to be interchanged between identical devices (that is, multiple ports on the same multiport modem card). Such interchangeability is not guaranteed in any way, even for devices of the same device class.

Some service providers may permit the configuration to be set while a call is active, and others may not.

See Also

lineGetDevConfig, lineGetID, lineConfigDialogEdit, VARSTRING


lineSetStatusMessages

This function enables an application to specify which notification messages the application wants to receive for events related to status changes for the specified line or any of its addresses.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineSetStatusMessages(HLINE hLine, DWORD dwLineStates, DWORD dwAddressStates);

Parameters

hLine
[in] Handle to the line device.
dwLineStates
[in] Specifies for which line-device status changes a message is to be sent to the application. This parameter uses the following LINEDEVSTATE_ constants:
Value
Description
LINEDEVSTATE_OTHER | Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING | The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages that contains this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED | The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED | This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON | The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF | The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE | The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE | The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE | Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN | The line has been opened by some application.
LINEDEVSTATE_CLOSE | The line has been closed by some application.
LINEDEVSTATE_NUMCALLS | The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS | The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS | The terminal settings have changed.
LINEDEVSTATE_ROAMMODE | The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY | The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL | The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC | The line's device-specific data has changed.
LINEDEVSTATE_REINIT | Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices) the application should reinitialize its use of TAPI. New lineInitialize and lineOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the LINE_LINEDEVSTATE message is left NULL for this state change as it applies to any of the lines in the system. Because of the critical nature of LINEDEVSTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.
LINEDEVSTATE_LOCK | The locked status of the line device has changed.
LINEDEVSTATE_REMOVED | Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message that contains this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.

dwAddressStates
[in] Specifies for which address status changes a message is to be sent to the application. This parameter uses the following LINEADDRESSSTATE_ constants:
Value
Description
LINEADDRESSSTATE_OTHER | Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC | The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO | The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE | The address has changed from idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY | The monitored or bridged address has changed from being in use by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS | The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD | The forwarding status of the address has changed (including the number of rings for determining a no-answer condition). The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS | The terminal settings for the address have changed.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_INVALADDRESSSTATE | LINEERR_OPERATIONFAILED
LINEERR_INVALLINEHANDLE | LINEERR_OPERATIONUNAVAIL
LINEERR_INVALLINESTATE | LINEERR_RESOURCEUNAVAIL
LINEERR_NOMEM | LINEERR_UNINITIALIZED

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application receives. By default, address and line status reporting is disabled.

Prior to Windows CE version 2.12, LINEDEVSTATE_ messages are not supported.

See Also

LINE_LINEDEVSTATE, lineInitialize, lineOpen


lineShutdown

This function shuts down the application’s usage of the abstraction of TAPI line API.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineShutdown(HLINEAPP hLineApp);

Parameters

hLineApp
[in] Application's usage handle for the line API.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

  • LINEERR_INVALAPPHANDLE
  • LINEERR_NOMEM
  • LINEERR_RESOURCEUNAVAIL
  • LINEERR_UNINITIALIZED

Remarks

If this function is called when the application has lines open or calls active, the call handles are deleted and TAPI automatically performs the equivalent of a lineClose on each open line. However, it is recommended that applications explicitly close all open lines before invoking lineShutdown. If shutdown is performed while asynchronous requests are outstanding, those requests are canceled.

See Also

lineClose


lineTranslateAddress

This function translates the specified address into a dialable string format.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineTranslateAddress(HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPIVersion, LPCTSTR lpszAddressIn, DWORD dwCard, DWORD dwTranslateOptions, LPLINETRANSLATEOUTPUT lpTranslateOutput);

Parameters

hLineApp
[in] Application handle returned by lineInitialize. If an application has not yet called the lineInitialize function, it can set the hLineApp parameter to NULL.
dwDeviceID
[in] Specifies the device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
[in] Specifies the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpszAddressIn
[in] Pointer to a null-terminated string that contains the address from which the data is to be extracted for translation. Must be in either the canonical address format, or an arbitrary string of dialable digits (non-canonical). This parameter must not be NULL. If the AddressIn contains a subaddress or name field, or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is translated, and the remainder of the string is returned to the application without modification.
dwCard
[in] Unsupported; set to zero.
dwTranslateOptions
[in] Specifies the associated operations to be performed prior to the translation of the address into a dialable string. This parameter uses the following LINETRANSLATEOPTION_ constants:
Value
Description
LINETRANSLATEOPTION_CARDOVERRIDE | If this bit is set, dwCard specifies the permanent identifier of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) that should be used instead of the PreferredCardID specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. The dwCard parameter is ignored if the CARDOVERRIDE bit is not set.
LINETRANSLATEOPTION_CANCELCALLWAITING | Ignored. A user runs a Control Panel application to specify whether a Cancel Call Waiting string is appropriate for the location. A Cancel Call Waiting string is commonly used by data modem and fax applications to prevent interruption of calls by call waiting beeps.
LINETRANSLATEOPTION_FORCELOCAL | If the number is local but would have been translated as a long distance call (LINETRANSLATERESULT_INTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option forces it to be translated as local. This is a temporary override of the toll list setting.
LINETRANSLATEOPTION_FORCELD | If the address could potentially have been a toll call, but would have been translated as a local call (LINETRANSLATERESULT_NOTINTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option forces it to be translated as long distance. This is a temporary override of the toll list setting.

Note If you have set the LINETRANSLATEOPTION_CANCELCALLWAITING bit, it is also advisable to set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags member of the LINECALLPARAMS structure (passed in to lineMakeCall through the lpCallParams parameter). This prevents the line device from using dialable digits to suppress call interrupts.

lpTranslateOutput
[out] Pointer to an application-allocated memory area to contain the output of the translation operation, of type LINETRANSLATEOUTPUT. Prior to calling lineTranslateAddress, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning data.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_INVALPOINTER
LINEERR_INCOMPATIBLEAPIVERSION | LINEERR_NODRIVER
LINEERR_INIFILECORRUPT | LINEERR_NOMEM
LINEERR_INVALADDRESS | LINEERR_OPERATIONFAILED
LINEERR_INVALAPPHANDLE | LINEERR_RESOURCEUNAVAIL
LINEERR_INVALCARD | LINEERR_STRUCTURETOOSMALL
LINEERR_INVALPARAM |

Remarks

This function does not translate multiplexed canonical addresses—that is, two canonical addresses separated by <CRLF>. Only the first address is translated. The other address(es) are ignored.

When an address is specified with a country code but without the local area code, the translation is not as expected. Instead of translating the address as a local call, the system translates the address as a long distance call with no area code. To avoid this behavior, set the LINETRANSLATEOPTION_FORCELOCAL bit or provide the area code for all addresses, including local ones.

See Also

lineInitialize, lineMakeCall, lineNegotiateAPIVersion, LINECALLPARAMS, LINETRANSLATEOUTPUT


lineTranslateDialog

This function displays an application-modal dialog box that enables the user to change the current location, adjust location and calling card parameters, and see the effect on a phone number about to be dialed.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LONG lineTranslateDialog (HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPIVersion, HWND hwndOwner, LPCTSTR lpszAddressIn);

Parameters

hLineApp
[in] Application handle returned by lineInitialize. If you set hLineApp to NULL, this function fails and returns LINERR_INVALAPPHANDLE.
dwDeviceID
[in] Specifies the device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
[in] Specifies the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on the line device indicated by dwDeviceID).
hwndOwner
[in] Handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.
lpszAddressIn
[in] Pointer to a null-terminated string that contains a phone number that is used, in the lower portion of the dialog box, to show the effect of the user's changes on the location parameters. The number must be in canonical format; if noncanonical, the phone number portion of the dialog box is not displayed. This pointer can be left NULL, in which case the phone number portion of the dialog box is not displayed. If the lpszAddressIn parameter contains a subaddress or name field, or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is used in the dialog box.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_BADDEVICEID | LINEERR_INVALPARAM
LINEERR_INCOMPATIBLEAPIVERSION | LINEERR_INVALPOINTER
LINEERR_INIFILECORRUPT | LINEERR_NODRIVER
LINEERR_INUSE | LINEERR_NOMEM
LINEERR_INVALADDRESS | LINEERR_OPERATIONFAILED
LINEERR_INVALAPPHANDLE |

LINEERR_INUSE is returned if the dialog box is already displayed by another application (cannot be open more than once). In these versions, TAPI brings the existing dialog box to the front, and the error indicates that any particulars related to the address passed in by the current application have not been handled, because that address was not processed by the function.

The application must call lineGetTranslateCaps after this function to obtain any changes the user made to the telephony address translation parameters, and call lineTranslateAddress to obtain a dialable string based on the user's new selections.

If any function related to address translation (for example, lineGetTranslateCaps or lineTranslateAddress) returns LINEERR_INIFILECORRUPT, the application should call lineTranslateDialog. The lineTranslateDialog function detects the errors and corrects them, and reports the action taken to the user. LINEERR_INIFILECORRUPT is returned the first time any of these functions are used after installation of Windows CE, because the parameters are uninitialized (lineTranslateDialog takes care of initializing them, using the user-specified default country to select the default country code).

See Also

lineGetTranslateCaps, lineInitialize, lineNegotiateAPIVersion, lineTranslateAddress


listen

This function prepares a socket to listen for incoming connections.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int listen (SOCKET s, int backlog);

Parameters

s
[in] Descriptor that identifies a bound, unconnected socket.
backlog
[in] Maximum length of the queue of pending connections. If this value is SOMAXCONN, then the underlying service provider responsible for socket s will set the backlog to a maximum reasonable value. There is no standard provision to find out the actual backlog value.

Return Values

Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest valid value.

Remarks

For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:

  • The Af_irda.h file must be explicitly included.
  • The WSAENETDOWN return value is not supported.
  • The backlog parameter is currently limited (silently) to 2.

To accept connections, a socket is first created with the socket function and bound to a local address with the bind function, a backlog for incoming connections is specified with listen, and then the connections are accepted with the accept function. Sockets that are connection oriented, those of type SOCK_STREAM for example, are used with listen. The socket s is put into "passive'' mode where incoming connection requests are acknowledged and queued pending acceptance by the process.

The listen function is typically used by servers that can have more than one connection request at a time. If a connection request arrives and the queue is full, the client will receive an error with an indication of WSAECONNREFUSED.

If there are no available socket descriptors, listen attempts to continue to function. If descriptors become available, a later call to listen or accept will refill the queue to the current or most recent "backlog'', if possible, and resume listening for incoming connections.

An application can call listen more than once on the same socket. This has the effect of updating the current backlog for the listening socket. Should there be more pending connections than the new backlog value, the excess pending connections will be reset and dropped.

See Also

accept, bind, connect, socket, WSAStartup


MakeSignature

This function generates a cryptographic checksum of the message, and also includes sequencing information to prevent message loss or insertion. MakeSignature allows the application to choose between several cryptographic algorithms, if supported by the chosen mechanism. The MakeSignature function uses the security context referenced by the context handle.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS MakeSignature( PCtxtHandle phContext,
ULONG fQOP, PSecBufferDesc pMessage, ULONG MessageSeqNo );

Parameters

phContext
Pointer to the handle to the context to use for the message.
fQOP
Specifies package-specific flags that indicate the quality of protection. A security package can use this parameter to enable the selection of cryptographic algorithms.
pMessage
Pointer to a SecBufferDesc structure. On input, the structure references one or more SecBuffer structures that contain the message to be signed. The function does not process buffers with the SECBUFFER_READONLY attribute.

The SecBufferDesc structure also references a SecBuffer structure of type SECBUFFER_TOKEN that receives the signature.

MessageSeqNo
Specifies a sequence number that the transport application assigned to the message. If the transport application does not maintain sequence numbers, this parameter is zero.

Return Values

SEC_E_OK indicates success. A nonzero error value indicates failure.

Remarks

The MakeSignature function generates a signature that is based on the message and the session key for the context.

If the transport application created the security context to support sequence detection and the caller provides a sequence number, the function includes this information in the signature. This protects against reply, insertion, and suppression of messages. The security package will incorporate the sequence number passed down from the transport application.

See Also

VerifySignature


ntohl

This function converts a u_long from network byte order to host byte order.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

u_long ntohl (u_long netlong);

Parameters

netlong
[in] 32-bit number in TCP/IP network byte order.

Return Values

The ntohl function always returns a value in host byte order.

Remarks

The ntohl function takes a 32-bit number in TCP/IP network byte order and returns a 32-bit number in host byte order.

See Also

htonl, htons, ntohs


ntohs

This function converts a u_short from network byte order to host byte order.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

u_short ntohs (u_short netshort);

Parameters

netshort
[in] 16-bit number in TCP/IP network byte order.

Return Values

The ntohs function returns the value in host byte order.

Remarks

The ntohs function takes a 16-bit number in TCP/IP network byte order and returns a 16-bit number in host byte order.

See Also

htonl, htons, ntohl


PurgeComm

This function can discard all characters from the output or input buffer of a specified communications resource. It can also terminate pending read or write operations on the resource.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Parameters

Syntax

BOOL PurgeComm(HANDLE hFile, DWORD dwFlags);

hFile
[in] Handle to the communications resource. The CreateFile function returns this handle.
dwFlags
[in] Specifies the action to take. This parameter can be a combination of the following values:
Value
Description
PURGE_TXABORT | Terminates all outstanding overlapped write operations and returns immediately, even if the write operations have not been completed.
PURGE_RXABORT | Terminates all outstanding overlapped read operations and returns immediately, even if the read operations have not been completed.
PURGE_TXCLEAR | Clears the output buffer (if the device driver has one).
PURGE_RXCLEAR | Clears the input buffer (if the device driver has one).

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If a thread uses PurgeComm to flush an output buffer, the deleted characters are not transmitted. To empty the output buffer while ensuring that the contents are transmitted, call the FlushFileBuffers function (a synchronous operation). Note, however, that FlushFileBuffers is subject to flow control but not to write time-outs, and it will not return until all pending write operations have been transmitted.

See Also

CreateFile


QueryContextAttributes

This function enables a transport application to query a security package for certain attributes of a security context.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS QueryContextAttributes( PCtxtHandle phContext,
ULONG ulAttribute, PVOID pBuffer );

Parameters

phContext
Pointer to the handle to the context to be queried.
ulAttribute
Specifies the attribute of the context to be returned. It is one of the following values:
Value
Description
SECPKG_ATTR_SIZES | Query the sizes of the structures used in the per-message functions. The pBuffer parameter is a pointer to a SecPkgContext_Sizes structure.
SECPKG_ATTR_NAMES | Query the name associated with the context. The pBuffer parameter is a pointer to a SecPkgContext_Names structure.
SECPKG_ATTR_LIFESPAN | Query the life span of the context. pBuffer is a pointer to a SecPkgContext_Lifespan structure.
SECPKG_ATTR_DCE_INFO | Query for authorization data used by DCE services. pBuffer is a pointer to a SecPkgContext_DceInfo structure.
SECPKG_ATTR_STREAM_SIZES | Query the sizes of the various stream components used in the per-message functions. The pBuffer parameter is a pointer to a SecPkgContext_StreamSizes structure.
SECPKG_ATTR_AUTHORITY | Query the name of the authenticating authority. The pBuffer parameter is a pointer to a SecPkgContext_Authority structure.
SECPKG_ATTR_KEY_INFO | Query information about the keys used in a security context. The pBuffer parameter is a pointer to a SecPkgContext_KeyInfo structure.

pBuffer
Pointer to a structure that receives the attributes. The type of structure pointed to depends on the value specified in the ulAttribute parameter.

Return Values

SEC_E_OK indicates success. A nonzero error value indicates failure.

Remarks

The structure pointed to by the pBuffer parameter varies, depending on the attribute being queried. The caller must allocate the structure itself, but the package allocates other pointers that are returned in the structure. Any pointers allocated by the package can be freed by calling the FreeContextBuffer function.

See Also

FreeContextBuffer, SecPkgContext_DceInfo, SecPkgContext_Lifespan, SecPkgContext_Names, SecPkgContext_Sizes, SecPkgContext_StreamSizes


QueryCredentialsAttributes

This function retrieves the attributes of a credential, such as the name associated with the credential.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS QueryCredentialsAttributes(
PCredHandle phCredential, ULONG ulAttribute, PVOID pBuffer );

Parameters

phCredential
Pointer to the handle to the credentials to be queried.
ulAttribute
Specifies the attribute to query. This parameter must be SECPKG_CRED_ATTR_NAMES.
pBuffer
Pointer to a buffer that receives the requested attribute. For the SECPKG_CRED_ATTR_NAMES attribute, pBuffer must point to a SecPkgCredentials_Names structure.

Return Values

SEC_E_OK indicates success.

Upon failure, one of the error values described in the following table is returned.

Value
Description
SEC_E_INVALID_HANDLE | The handle passed to the function is invalid.
SEC_E_INSUFFICIENT_MEMORY | Insufficient memory.

Remarks

The QueryCredentialsAttributes function allows a customer of the security services to determine the name associated with the specified credentials.

The caller must allocate the structure pointed to by the pBuffer parameter. The security provider allocates the buffer for any pointer returned in the pBuffer structure. The caller can call the FreeContextBuffer function to free any pointers allocated by the security provider.

See Also

FreeContextBuffer


QuerySecurityPackageInfo

This function retrieves information about a specified security package. This information includes the bounds on sizes of authentication information, credentials, and contexts.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS QuerySecurityPackageInfo(
SEC_CHAR * pszPackageName, PSecPkgInfo *ppPackageInfo);

Parameters

pszPackageName
Pointer to a null-terminated string that specifies the name of the security package.
ppPackageInfo
Pointer to a variable that receives a pointer to a SecPkgInfo structure containing information about the specified security package.

Return Values

SEC_E_OK indicates success. A nonzero error value indicates failure.

Remarks

The caller must call the FreeContextBuffer function to free the buffer returned in ppPackageInfo.

See Also

FreeContextBuffer, SecPkgInfo


RasDeleteEntry

This function deletes an entry from the phone book.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasDeleteEntry(LPWSTR lpszPhonebook, LPWSTR lpszEntry);

Parameters

lpszPhonebook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
lpszEntry
Pointer to a null-terminated string that contains the name of an existing entry to be deleted.

Return Values

Zero indicates success. A nonzero RAS error code indicates failure.


RasDial

This function establishes a RAS connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasDial(LPRASDIALEXTENSIONS dialExtensions, LPTSTR phoneBookPath, LPRASDIALPARAMS rasDialParam, DWORD NotifierType, LPVOID notifier, LPHRASCONN pRasConn);

Parameters

dialExtensions
This parameter is ignored and should be set to NULL. On Windows CE, RasDial always uses the default behaviors for the RASDIALEXTENSIONS options.
pphoneBook
This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
rasDialParams
Pointer to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.

The caller must set the RASDIALPARAMS structure’s dwSize member to the sizeof(RASDIALPARAMS) to identify the version of the structure being passed.

NotifierType
Specifies the nature of the notifier parameterIf notifier is NULL, NotifierType is ignored. If notifier is not NULL, set NotifierType to the following value:
Value
Description
0xFFFFFFFF
0xFFFFFFFF 		The notifier parameter is a handle to a window to receive progress notification messages. In a progress notification message, wParam indicates the connection state (rasconnstate) which the RAS connection is about to enter, while lParam indicates whether or not an error occurred.
The progress notification message uses the WM_RASDIALEVENT message code.

notifier
Pointer to a window handle to receive RasDial event notificationsIf this parameter is not NULL, RasDial sends the window a for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and uses the window to communicate its progress.

If notifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.

If notifier is not NULL, notifications to the window can occur at any time after the initial call to RasDial. Notifications end when one of the following events occurs:

  • The connection is established. In other words, the RAS connection state is RASCS_Connected.
  • The connection fails. In other words, dwError is nonzero.
  • RasHangUp is called on the connection.

The callback notifications are made in the context of a thread captured during the initial call to RasDial.

pRasConn
Pointer to a variable of type HRASCONN. You must set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into pRasConn.

Return Values

Zero indicates success. In addition, the function stores a handle to the RAS connection into the variable pointed to by pRasConn. A nonzero error value, either from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY, indicates failure.

Remarks

The szCallBackNumber and szPhoneNumber members of the structure pointed to by rasDialParam are not used and should be set to NULL.

RasDial will not automatically display the logon dialog box. This is currently done through the Remote Networking application. Applications are responsible for getting the information from the user.

Windows CE does not support the ERROR_CANNOT_FIND_PHONEBOOK_ENTRY return value.

Errors that occur after the immediate return can be detected by RasGetConnectStatus. Data is available until an application calls RasHangUp to hang up the connection.

An application must eventually call RasHangUp whenever a non-NULL connection handle is stored into pRasConn. This applies even if RasDial returns a nonzero (error) value.

An application can safely call RasHangUp from a RasDial notifier handler. If this is done, however, the hangup does not occur until the routine returns.

See Also

RasGetConnectStatus, RasHangUp, RASDIALPARAMS, WM_RASDIALEVENT


RasEnumConnections

This function lists all active RAS connections. It returns each connection’s handle and phone book entry name.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasEnumConnections(LPRASCONN lprasconn, LPDWORD lpcb, LPDWORD lpcConnections);

Parameters

lprasconn
Long pointer to a buffer that receives an array of RASCONN structures, one for each RAS connection. Before calling the function, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.
lpcb
Long pointer to a variable that that contains the size, in bytes, of the buffer specified by lprasconn. On return, the function sets this variable to the number of bytes required to enumerate the RAS connections.
lpcConnections
Long pointer to a variable that the function sets to the number of RASCONN structures written to the buffer specified by lprasconn.

Return Values

Zero indicates success. A nonzero error value listed in the RAS header file, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY indicates failure.

See Also

RASCONN, RasEnumEntries, RasGetConnectStatus


RasEnumEntries

This function lists all entry names in a remote access phone book.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasEnumEntries(LPWSTR Reserved, LPWSTR lpszPhoneBookPath, LPRASENTRYNAME lprasentryname, LPDWORD lpcb, LPDWORD lpcEntries);

Parameters

Reserved
Reserved; set to NULL.
lpszPhonebook
Windows CE: This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
lprasentryname
Pointer to a buffer that receives an array of RASENTRYNAME structures, one for each phone-book entry. Before calling the function, an application must set the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) in order to identify the version of the structure being passed.
lpcb
Pointer to a variable that that contains the size, in bytes, of the buffer specified by lprasentryname. On return, the function sets this variable to the number of bytes required to successfully complete the call.
lpcEntries
Pointer to a variable that the function, if successful, sets to the number of phone-book entries written to the buffer specified by lprasentryname.

Return Values

Zero indicates success. A nonzero error value listed in the RAS header file, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY indicates failure.

Remarks

The following sample code enumerates the RAS phonebook entries on the current machine. The code initially calls RasEnumEntries to obtain the size of the buffer to pass in. The code then calls RasEnumEntries again, to enumerate the entries. Note that for both calls, the code sets the dwSize member of the first RASENTRY structure in the buffer to sizeof(RASENTRY) to specify the structure version.

lprasentryname = (LPRASENTRYNAME)LocalAlloc(GPTR,, sizeof(RASENTRYNAME));
lprasentryname->dwSize = sizeof(RASENTRYNAME);
if ((nRet = RasEnumEntries(NULL, NULL, lprasentryname, &cb, &cEntries))
    == ERROR_BUFFER_TOO_SMALL)
{
    lprasentryname = (LPRASENTRYNAME)GlobalAlloc(GPTR, cb);
    lprasentryname->dwSize = sizeof(RASENTRYNAME);
}

// Calling RasEnumEntries to enumerate the phonebook entries
nRet = RasEnumEntries(NULL, NULL, lprasentryname, &cb, &cEntries);

if (nRet != ERROR_SUCCESS)
{
    printf("RasEnumEntries failed: Error %d\n", nRet);
}
else
{
    printf("Phone book entries in the default phonebook:\n\n");
    for(i=0;i < cEntries;i++)
    {
        printf("%s\n",lprasentryname->szEntryName);
        lprasentryname++;
    }
}

See Also

RASENTRYNAME, RasEnumConnections


RasGetConnectStatus

This function retrieves information on the current status of the specified remote access connection. An application can use this call to determine when an asynchronous RasDial call has completed.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasGetConnectStatus(HRASCONN rasconn, LPRASCONNSTATUS lprasronnstatus);

Parameters

rasconn
Handle to the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial or RasEnumConnections.
lprasconnstatus
Pointer to a RASCONNSTATUS structure that the function fills with status information. Before calling the function, an application must set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.

Return Values

Zero indicates success. A nonzero error value listed in the RAS header file, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY indicates failure.

See Also

RASCONNSTATUS, RasDial, RasEnumConnections


RasGetEntryDialParams

This function retrieves the connection information saved by the last successful call to the RasDial function for a specified phone book entry.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasGetEntryDialParams(LPWSTR lpszPhoneBook, LPRASDIALPARAMS lpRasDialParams, LPBOOL lpfPassword);

Parameters

lpszPhoneBook
Windows CE: This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
lpRasDialParams
Pointer to a RASDIALPARAMS structure. On input, the dwSize member must specify the size of the RASDIALPARAMS structure, and the szEntryName member must specify a valid phone-book entry. On output, the structure receives the connection parameters associated with the specified phone-book entry.

Note that the szPhoneNumber member of the structure does not receive the phone number associated with the phone-book entry. To get the phone number associated with a phone-book entry, call the RasGetEntryProperties function.

lpfPassword
Pointer to a flag that indicates whether the function retrieved the password associated with the user name for the phone-book entry. The function sets this flag to TRUE if the user’s password was returned in the szPassword member of the RASDIALPARAMS structure pointed to by lpRasDialParams.

Return Values

Zero indicates success. ERROR_BUFFER_INVALID indicates that the lpRasDialParams or lpfPassword pointer is invalid, or the lpRasDialParams buffer is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.

Windows CE Remarks

The szCa l lBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.

When the dwSize member of the RASDIALPARAMS structure, which is pointed to by the lpRasDialParams parameter, is uninitialized or set to an incorrect value, the RasGetEntryDialParams function fails and returns a misleading error value, ERROR_CANNOT_FIND_PHONEBOOK_ENTRY.

See Also

RasDial, RASDIALPARAMS, RasSetEntryDialParams


RasGetEntryProperties

This function retrieves the properties of a phone book entry.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasGetEntryProperties(LPWSTR lpszPhoneBook,
LPWSTR szEntry, LPBYTE lpbEntry, LPDWORD lpdwEntrySize, LPBYTE lpb, LPDWORD lpdwSize);

Parameters

lpszPhoneBook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
szEntry
Pointer to a null-terminated string that contains an existing entry name. If you specify an empty string, ““, the function returns default values in the buffers pointed to by the lpbEntry and lpb parameters.
lpbEntry
Pointer to a RASENTRY structure followed by additional bytes for the alternate phone number list, if there is one. The structure receives the connection data associated with the phone-book entry specified by the szEntry parameter. Before calling the function, set the dwSize member of the structure to sizeof(RASENTRY) to identify the version of the structure. This parameter can be NULL.
lpdwEntrySize
Pointer to a variable that that contains the size, in bytes, of the lpbEntry buffer. On return, the function sets this variable to the number of bytes required.
lpb
Long pointer to a buffer that receives device-specific configuration information. This is opaque TAPI device configuration information that you should not manipulate directly. This parameter can be NULL. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmer’s Reference.
lpdwSize
Long pointer to a variable that that contains the size, in bytes, of the buffer specified by the lpb parameter. On return, the function sets this variable to the number of bytes required. This parameter can be NULL if the lpb parameter s NULL.

To determine the required buffer size, call RasGetEntryProperties with lpb set to NULL and lpdwSize set to zero. The function returns the required buffer size in lpdwSize.

Return Values

Zero indicates success. ERROR_INVALID_PARAMETER indicates that the function was called with an invalid parameter. ERROR_INVALID_SIZE indicates that the value of the dwSize member of the structure specified in lpbEntry is too small. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpbEntry is invalid. ERROR_BUFFER_TOO_SMALL indicates that the buffer size indicated in lpdwEntrySize is too small. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or is missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.

Remarks

For Windows CE version 1.0 and 1.01, the lpb and lpdwSize parameters are ignored and should be set to NULL. To retrieve device specific configuration information use the RasGetEntryDevConfig function.

For Windows CE version 2.0 and later, device configuration information can be retrieved by using the lpb and lpdwSize parameters.

Windows CE does not use the alternate phone number list.

See Also

RASENTRY, RasSetEntryProperties


RasHangUp

The RasHangUp function terminates a remote access connection. The connection is specified with a RAS connection handle. RasHangUp releases all RASAPI32.DLL resources associated with the handle.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasHangUp(HRASCONN Session);

Parameters

Session
Handle to the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

Return Values

Zero indicates success. A nonzero error value listed in the RAS header file or ERROR_INVALID_HANDLE indicates failure.

Remarks

The connection is terminated even if the RasDial call has not yet been completed.

After this call, the Session handle can no longer be used.

See Also

RASCONN, RasDial, RasEnumConnections, RasGetConnectStatus, Sleep


RasRenameEntry

This function changes the name of an entry in the phone book.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasRenameEntry(LPWSTR lpszPhonebook, LPWSTR lpszOldEntry, LPWSTR lpszNewEntry);

Parameters

lpszPhonebook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
lpszOldEntry
Pointer to a null-terminated string that contains an existing entry name.
lpszNewEntry
Pointer to a null-terminated string that contains the new entry name. Before calling RasRenameEntry, call the RasValidateEntryName function to validate the new entry name.

Return Values

Zero indicates success. ERROR_INVALID_NAME indicates that the lpszNewEntry name is invalid. ERROR_ALREADY_EXISTS indicates that an entry with the lpszNewEntry name already exists. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.


RasSetEntryDialParams

This function changes the connection information saved by the last successful call to the RasDial or RasGetEntryDialParams function for a specified phone book entry.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasSetEntryDialParams(LPWSTR lpszPhoneBook, LPRASDIALPARAMS lpRasDialParams, BOOL fRemovePassword);

Parameters

lpszPhoneBook
Windows CE: This parameter is ignored and should be set to NULL. Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.
lpRasDialParams
Pointer to a RASDIALPARAMS structure that contains the connection parameters to be associated with the phonebook entry. RasSetEntryDialParams uses the structure’s members as follows:
dwSize
Specifies the sizeof(RASDIALPARAMS) to identify the version of the structure.
szEntryName
Null-terminated string that identifies the phonebook entry to set parameters for.
szPhoneNumber
Not used; set to NULL.
szCallbackNumber
Not used; set to NULL..
szUserName
Null-terminated string that contains the logon name of the user associated with this entry. If szUserName is an empty string, the user name is not changed.
szPassword
Null-terminated string that contains the password for the user specified by szUserName. If szUserName is an empty string, the password is not changed. If szPassword is an empty string and fRemovePassword is FALSE, the password is set to the empty string. If fRemovePassword is TRUE, the password stored in this phonebook entry for the user specified by szUserName is removed regardless of the that contains of the szPassword string.
szDomain
Null-terminated string that contains the name of the domain to log on to. If szDomain is an empty string, the domain name is not changed.
fRemovePassword
Boolean value that specifies whether to remove the phonebook entry’s stored password for the user specified by lpRasDialParams->szUserName. If fRemovePassword is TRUE, the password is removed.

Return Values

Zero indicates success. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpRasDialParams is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phonebook is corrupted or missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phonebook entry does not exist.

Remarks

The szCallBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.

See Also

RASDIALPARAMS, RasGetEntryDialParams


RasSetEntryProperties

This function changes the connection information for an entry in the phone book or creates a new phone-book entry.

At a Glance

Header file: | Adfunc.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasSetEntryProperties(LPWSTR lpszPhoneBook,
LPWSTR szEntry, LPBYTE lpbEntry, DWORD dwEntrySize, LPBYTE lpb, DWORD dwSize);

Parameters

lpszPhoneBook
This parameter is ignored and should be set to NULL. Phonebook entries are stored in the registry rather than in a phone-book file.
szEntry
Pointer to a null-terminated string that contains an entry name.

If the entry name matches an existing entry, RasSetEntryProperties modifies the properties of that entry.

If the entry name does not match an existing entry, RasSetEntryProperties creates a new phone-book entry. For new entries, call the RasValidateEntryName function to validate the entry name before calling RasSetEntryProperties.

lpbEntry
Pointer to a RASENTRY structure that that contains the new connection data to be associated with the phone-book entry specified by the szEntry parameter.

The structure might be followed by an array of null-terminated alternate phone number strings. The last string is terminated by two consecutive null characters. The dwAlternateOffset member of the RASENTRY structure that contains the offset to the first string.

dwEntrySize
Specifies the size, in bytes, of the buffer specified by the lpRasEntry parameter.
lpb
Pointer to a buffer that contains device-specific configuration information. This is opaque TAPI device configuration information. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmer’s Reference.
dwSize
Specifies the size, in bytes, of the lpb buffer.

Return Values

Zero indicates success. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpbEntry is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or missing components.

Remarks

For Windows CE version 1.0 and 1.01, the lpb and dwSize parameters are ignored and should be set to NULL.

For Windows CE version 2.0 and later, device configuration information can be set by using lpb and dwSize parameters.

Windows CE does not use the alternate phone number list.

See Also

RASENTRY, RasGetEntryProperties, RasValidateEntryName


RasValidateEntryName

This function validates the format of a connection entry name. It must that contains at least one non-white-space alpha-numeric character.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

DWORD RasValidateEntryName(LPWSTR lpszPhonebook,
LPWSTR lpszEntry);

Parameters

lpszPhonebook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
lpszEntry
Pointer to a null-terminated string that contains an entry name. For Windows CE, the entry name must include at least one alphanumeric character and be a valid registry key name. The entry name cannot begin with a backslash (“\”).
Character
Description
| vertical bar
> greater than symbol
< less than symbol
? question mark
* asterisk
\ backward slash
/ forward slash
: colon

Return Values

Zero indicates success. ERROR_INVALID_NAME or ERROR_ALREADY_EXISTS indicates failure.

See Also

RasGetEntryProperties


recv

This function receives data from a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int recv (SOCKET s, char *buf, int len, int flags);

Parameters

s
[in] Descriptor that identifies a connected socket.
buf
[out] Buffer for the incoming data.
len
[in] Length of buf.
flags
[in] Specifies the way in which the call is made.

Return Values

Zero indicates that the connection has been gracefully closed. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The recv function is used to read incoming data on connection-oriented sockets, or connectionless sockets. When using a connection-oriented protocol, the sockets must be connected before calling recv. When using a connectionless protocol, the sockets must be bound and connect must be called to associate the remote address before calling recv.

The local address of the socket must be known. For server applications, use an explicit bind function or an implicit accept function. Explicit binding is discouraged for client applications. For client applications the socket can become bound implicitly to a local address using connect or sendto.

For connection-oriented or connectionless sockets, this function restricts the addresses from which received messages are accepted. The function only returns messages from the remote address specified in the connection. Messages from other addresses are (silently) discarded.

For connection-oriented sockets (type SOCK_STREAM for example), calling recv will return as much information as is currently available—up to the size of the buffer supplied. The application can use the ioctlsocket or WSAIoctl SIOCATMARK command to determine whether any more out-of-band data remains to be read.

For connectionless sockets (type SOCK_DGRAM or other message-oriented sockets), data is extracted from the first enqueued datagram (message) from the destination address specified by the connect function.

If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram, and recv generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost; for reliable protocols, the data is retained by the service provider until it is successfully read by calling recv with a large enough buffer. For TCP/IP, an application cannot receive from any multicast address until after becoming a group member.

If no incoming data is available at the socket, the recv call blocks and waits for data to arrive. When the socket is nonblocking, a value of SOCKET_ERROR is returned with the error value set to WSAEWOULDBLOCK. The select function can be used to determine when more data arrives.

Any data that has already been received and buffered by the transport will be copied into the supplied user buffers. In the case of a blocking socket with no data currently having been received and buffered by the transport, the call will block until data is received. For protocols acting as byte-stream protocols, the stack tries to return as much data as possible, subject to the supplied buffer space and amount of received data available. However, receipt of a single byte is sufficient to unblock the caller. There is no guarantee that more than a single byte will be returned. For message-oriented protocols, a full message is required to unblock the caller.

If the socket is connection oriented and the remote side has shut down the connection gracefully, and all data has been received, a recv will complete immediately with zero bytes received. If the connection has been reset, a recv will fail with the error WSAECONNRESET.

The flags parameter can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. The semantics of this function are determined by the socket options and the flags parameter. Windows CE supports the following flags parameter:

MSG_PEEK
Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. The function then returns the number of bytes currently pending to receive.

See Also

accept, bind, recvfrom, send, select, shutdown, socket, WSAStartup


recvfrom

This function receives a datagram and stores the source address.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int recvfrom (SOCKET s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen);

Parameters

s
[in] Descriptor that identifies a bound socket.
buf
[out] Buffer for the incoming data.
len
[in] Length of buf.
flags
[in] Specifies the way in which the call is made.
from
[out] Optional pointer to a buffer that will hold the source address upon return.
fromlen
[in/out] Optional pointer to the size of the from buffer.

Return Values

Zero indicates that the connection has been gracefully closed. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The recvfrom function reads incoming data on both connected and unconnected sockets and captures the address from which the data was sent. The socket must not be connected. The local address of the socket must be known. For server applications, this is usually done explicitly through bind. Explicit binding is discouraged for client applications. For client applications using this function, the socket can become bound implicitly to a local address through sendto.

For stream-oriented sockets such as those of type SOCK_STREAM, a call to recvfrom returns as much information as is currently available—up to the size of the buffer supplied. The from and fromlen parameters are ignored for connection-oriented sockets.

For message-oriented sockets, data is extracted from the first queued message, up to the size of the buffer supplied. If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram, and recvfrom generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost.

If the from parameter is nonzero and the socket is not connection oriented, (type SOCK_DGRAM for example), the network address of the peer that sent the data is copied to the corresponding SOCKADDR structure. The value pointed to by fromlen is initialized to the size of this structure and is modified, on return, to indicate the actual size of the address stored in the SOCKADDR structure.

If no incoming data is available at the socket, the recvfrom call blocks and waits for data to arrive. When the socket is nonblocking, a value of SOCKET_ERROR is returned with the error value set to WSAEWOULDBLOCK. The select function can be used to determine when more data arrives.

Any data that has already been received and buffered by the transport will be copied into the supplied user buffers. In the case of a blocking socket with no data currently having been received and buffered by the transport, the call will block until data is received. For byte-stream protocols, the stack tries to return as much data as possible, subject to the supplied buffer space and amount of received data available. However, receipt of a single byte is sufficient to unblock the caller. There is no guarantee that more than a single byte will be returned. For message-oriented protocols, a full message is required to unblock the caller.

If the socket is connection oriented and the remote side has shut down the connection gracefully, the call to recvfrom will complete immediately with zero bytes received. If the connection has been reset recvfrom will fail with the error WSAECONNRESET.

The flags parameter can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. The semantics of this function are determined by the socket options and the flags parameter. Windows CE supports the following flags parameter:

MSG_PEEK
Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. The function then returns the number of bytes currently pending to receive.

See Also

bind, recv, select, send, shutdown, socket, WSAStartup


RetrieveUrlCacheEntryFile

This function locks the cache entry file associated with the specified URL.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL RetrieveUrlCacheEntryFile (LPCTSTR lpszUrlName, LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
LPDWORD lpdwCacheEntryInfoBufferSize, DWORD dwReserved);

Parameters

lpszUrlName
[in] Address of a string containing the URL of the resource associated with the cache entry. This must be a unique name. The name string should not contain any escape characters.
lpCacheEntryInfo
[out] Address of a cache entry information buffer. If the buffer is not sufficient, this function returns ERROR_INSUFFICIENT_BUFFER and sets lpdwCacheEntryInfoBufferSize to the number of bytes required.
lpdwCacheEntryInfoBufferSize
[in] [out] Address of an unsigned long integer variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable contains the size of the actual buffer used or required. The caller should check the return value in this parameter. If the return size is less than or equal to the size passed in, all the relevant data has been returned.
dwReserved
[in] Reserved. Must be set to zero.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

This function does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL http://example.com/example.htm#sample was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

The file is locked for the caller when it is retrieved; the caller should unlock the file after it has been used up. The cache manager automatically unlocks the locked files after a certain interval. While the file is locked, the cache manager will not remove the file from the cache. It is important to note that this function can be efficient or expensive, depending on the internal implementation of the cache.

For instance, if the URL data is stored in a packed file that contains data for other URLs, the cache will make a copy of the data to a file in a temporary directory maintained by the cache. The cache will eventually delete the copy. It is recommended that this function be used only in situations where a file name is needed to launch an application.

See Also

UnlockUrlCacheEntryFile


select

This function determines the status of one or more sockets, waiting if necessary.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
const struct timeval *timeout);

Parameters

nfds
[in] Ignored; included only for compatibility with Berkeley sockets.
readfds
[in/out] Optional pointer to a set of sockets to be checked for readability.
writefds
[in/out] Optional pointer to a set of sockets to be checked for writability
exceptfds
[in/out] Optional pointer to a set of sockets to be checked for errors.
timeout
[in] Maximum time for select to wait. NULL blocks indefinitely.

Return Values

Zero indicates that the time limit expired. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The select function is used to determine the status of one or more sockets. For each socket, the caller can request information on read, write, or error status. The set of sockets for which a given status is requested is indicated by an FD_SET structure. The sockets contained within the FD_SET structures must be associated with a single service provider. The select function returns the number of sockets meeting the conditions. A set of macros is provided for manipulating an FD_SET structure. These macros are compatible with those used in the Berkeley software, but the underlying representation is completely different.

The parameter readfds identifies the sockets that are to be checked for readability. If the socket is currently in the listen state, it will be marked as readable if an incoming connection request has been received such that an accept is guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading such that a call to recv or recvfrom is guaranteed not to block.

For connection-oriented sockets, readability can also indicate that a request to close the socket has been received from the peer. If the virtual circuit was closed gracefully, and all data was received, then a recv will return immediately with zero bytes read. If the virtual circuit was reset, then a recv will complete immediately with an error value such as WSAECONNRESET.

The parameter writefds identifies the sockets that are to be checked for writability. If a socket is processing a connect call (nonblocking), a socket is writable if the connection establishment successfully completes. If the socket is not processing a connect call, writability means a send or sendto are guaranteed to succeed. However, they can block on a blocking socket if the len parameter exceeds the amount of outgoing system buffer space available. It is not specified how long these guarantees can be assumed to be valid, particularly in a multithreaded environment.

The parameter exceptfds identifies the sockets that are to be checked for the presence of any exceptional error conditions.

Any two of the parameters, readfds, writefds, or exceptfds, can be given as NULL. At least one must be non-NULL, and any non-NULL descriptor set must contain at least one handle to a socket.

Summary: A socket will be identified in a particular set when select returns if:

readfds:

  • If listen has been called and a connection is pending, accept will succeed
  • Connection has been closed/reset/terminated

writefds:

  • If processing a connect call (nonblocking), connection has succeeded
  • Data can be sent

exceptfds:

  • If processing a connect call (nonblocking), connection attempt failed

Four macros are defined in the header file Winsock.h for manipulating and checking the descriptor sets. The variable FD_SETSIZE determines the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, which can be modified by defining FD_SETSIZE to another value before including Winsock.h.) Internally, socket handles in an FD_SET structure are not represented as bit flags as in Berkeley Unix. Their data representation is opaque. Use of these macros will maintain software portability between different socket environments. The macros to manipulate and check FD_SET contents are:

FD_CLR(s, *set)
Removes the descriptor s from set.
FD_ISSET(s, *set)
Nonzero if s is a member of the set. Otherwise, zero.
FD_SET(s, *set)
Adds descriptor s to set.
FD_ZERO(*set)
Initializes the set to the NULL set.

The parameter time-out controls how long the select can take to complete. If time-out is a null pointer, select will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, time-out points to a TIMEVAL structure that specifies the maximum time that select should wait before returning. When select returns, the contents of the TIMEVAL structure are not altered. If TIMEVAL is initialized to {0, 0}, select will return immediately; this is used to poll the state of the selected sockets. If select returns immediately, then the select call is considered nonblocking and the standard assumptions for nonblocking calls apply.

See Also

accept, connect, recv, recvfrom, send, sendto, setsockopt, WSAStartup


send

This function sends data on a connected socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int send (SOCKET s, const char *buf, int len, int flags);

Parameters

s
[in] Descriptor that identifies a connected socket.
buf
[in] Buffer containing the data to be transmitted.
len
[in] Length of the data in buf.
flags
[in] Specifies the way in which the call is made.

Return Values

The total number of bytes sent, which can be less than the number indicated by len for nonblocking sockets, indicates that no errors occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

For Infrared Sockets (IrSock), the Af_irda.h file must be explicitly included.

The send function is used to write outgoing data on a connected socket. For message-oriented sockets, care must be taken not to exceed the maximum packet size of the underlying provider, which can be obtained by using getsockopt to retrieve the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol, the error WSAEMSGSIZE is returned, and no data is transmitted.

The successful completion of a send does not indicate that the data was successfully delivered.

If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in a nonblocking mode. On nonblocking stream oriented sockets, the number of bytes written can be between 1 and the requested length, depending on buffer availability on both client and server machines. The select function can be used to determine when it is possible to send more data.

Calling send with a zero len parameter is permissible and will be treated by implementations as successful. In such cases, send will return zero as a valid value. For message-oriented sockets, a zero-length transport datagram is sent.

The flags parameter can be used to influence the behavior of the function beyond the options specified for the associated socket. The semantics of this function are determined by the socket options and the flags parameter. Windows CE supports the following flags parameter:

MSG_DONTROUTE
Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.

See Also

bind, recv, recvfrom, socket, select, sendto, shutdown, WSAStartup


sendto

This function sends data to a specific destination.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int sendto (SOCKET s, const char *buf, int len, int flags, const struct sockaddr *to, int token);

Parameters

s
[in] Descriptor that identifies a (possibly connected) socket.
buf
[in] Buffer that contains the data to be transmitted.
len
[in] Length of the data in buf.
flags
[in] Specifies the way in which the call is made.
to
[in] Optional pointer to the address of the target socket.
tolen
[in] Size of the address in to.

Return Values

The total number of bytes sent, which can be less than the number indicated by len, indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The sendto function is used to write outgoing data on a socket. For message-oriented sockets, care must be taken not to exceed the maximum packet size of the underlying subnets, which can be obtained by using getsockopt to retrieve the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol, the error WSAEMSGSIZE is returned and no data is transmitted.

The to parameter can be any valid address in the socket's address family, including a broadcast or any multicast address. To send to a broadcast address, an application must have used setsockopt with SO_BROADCAST enabled. Otherwise, sendto will fail with the error value WSAEACCES. For TCP/IP, an application can send to any multicast address (without becoming a group member).

If the socket is unbound, unique values are assigned to the local association by the system, and the socket is then marked as bound. An application can use getsockname to determine the local socket name in this case.

The successful completion of a sendto does not indicate that the data was successfully delivered.

The sendto function is normally used on a connectionless socket to send a datagram to a specific peer socket identified by the to parameter. Even if the connectionless socket has been previously connected to a specific address, the to parameter overrides the destination address for that particular datagram only. On a connection-oriented socket, the to and tolen parameters are ignored, making sendto equivalent to send.

For Sockets Using IP (Version 4)

To send a broadcast (on a SOCK_DGRAM only), the address in the to parameter should be constructed using the special IP address INADDR_BROADCAST (defined in Winsock.h), together with the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation can occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.

If no buffer space is available within the transport system to hold the data to be transmitted, sendto will block unless the socket has been placed in a nonblocking mode. On nonblocking, stream oriented sockets, the number of bytes written can be between 1 and the requested length, depending on buffer availability on both the client and server systems. The select function can be used to determine when it is possible to send more data.

Calling sendto with a len of zero is permissible and will return zero as a valid value. For message-oriented sockets, a zero-length transport datagram is sent.

The flags parameter can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. The semantics of this function are determined by the socket options and the flags parameter. Windows CE supports the following flags parameter:

MSG_DONTROUTE
Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.

See Also

recv, recvfrom, socket, select, send, shutdown, WSAStartup


SetCommBreak

This function suspends character transmission for a specified communications device and places the transmission line in a break state until the ClearCommBreak function is called.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCommBreak(HANDLE hFile);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

ClearCommBreak, CreateFile


SetCommMask

This function specifies a set of events to be monitored for a communications device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCommMask(HANDLE hFile, DWORD dwEvtMask);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
dwEvtMask
[in] Specifies the events to be enabled. A value of zero disables all events. This parameter can be a combination of the following values:
Value
Description
EV_BREAK | A break was detected on input.
EV_CTS | The CTS (clear-to-send) signal changed state.
EV_DSR | The DSR (data-set-ready) signal changed state.
EV_ERR | A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_RING | A ring indicator was detected.
EV_RLSD | The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR | A character was received and placed in the input buffer.
EV_RXFLAG | The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY | The last character in the output buffer was sent.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The SetCommMask function specifies the set of events that can be monitored for a particular communications resource. A handle to the communications resource can be specified in a call to the WaitCommEvent function, which waits for one of the events to occur. To get the current event mask of a communications resource, use the GetCommMask function.

See Also

CreateFile, DCB, GetCommMask, SetCommState, WaitCommEvent


SetCommState

This function configures a communications device according to the specifications in a device-control block (a DCB structure). The function reinitializes all hardware and control settings, but it does not empty output or input queues.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCommState(HANDLE hFile, LPDCB lpDCB);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
lpDCB
[in] Long pointer to a DCB structure containing the configuration information for the specified communications device.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The SetCommState function uses a DCB structure to specify the desired configuration. The GetCommState function returns the current configuration.

To set only a few members of the DCB structure, you should modify a DCB structure that has been filled in by a call to GetCommState. This ensures that the other members of the DCB structure have appropriate values.

The SetCommState function fails if the XonChar member of the DCB structure is equal to the XoffChar member.

See Also

CreateFile, DCB, GetCommState


SetCommTimeouts

This function sets the time-out parameters for all read and write operations on a specified communications device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetCommTimeouts(HANDLE hFile,
LPCOMMTIMEOUTS lpCommTimeouts);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
lpCommTimeouts
[in] Long pointer to a COMMTIMEOUTS structure that contains the new time-out values.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

COMMTIMEOUTS, GetCommTimeouts, ReadFile


setsockopt

This function sets a socket option.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int setsockopt (SOCKET s, int level, int optname, const char *optval, int optlen);

Parameters

s
[in] Descriptor that identifies a socket.
level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET, IPPROTO_TCP, and IPPROTO_IP. When the level is IPPROTO_IP, the following IP_OPTIONS values are available:
Value
Description
IP_MULTICAST_TTL | Time-to-live for a multicast packet. Specifies the maximum number of hops for which a multicast message survives before it is discarded. Use int for optval.
IP_MULTICAST_IF | Address of the outgoing multicast-capable interface. This address is used for subsequent multicasts. Use unsigned long for optval.
IP_ADD_MEMBERSHIP | The membership request structure used to request a particular multicast group's membership. Use struct ip_mreq for optval.
IP_DROP_MEMBERSHIP | The group whose membership is to be used. Use struct ip_mreq for optval.

optname
[in] Socket option for which the value is to be set.
optval
[in] Pointer to the buffer in which the value for the requested option is supplied.
optlen
[in] Size of the optval buffer.

Return Values

Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

The setsockopt function can also return the following error values:

WSAENOBUFS
No buffer space available. An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full.
WSAEOPNOTSUPP
The option is not supported.
WSANOTINITIALISED
A successful WSAStartup call must occur before using this function.
WSAENETDOWN
The network subsystem has failed. This value is not supported for IrSockets.
WSAEFAULT
The optval parameter is not in a valid part of the process address space or the optlen parameter is too small.
WSAEISCONN
The socket could not switch to secure mode when it connected.
WSAEINPROGRESS
A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL
The level parameter is not valid, or the information in optval is not valid.
WSAENETRESET
The connection has timed out when SO_KEEPALIVE is set.
WSAENOPROTOOPT
The option is unknown or unsupported for the specified provider or socket (see SO_GROUP_PRIORITY limitations). When used in the context of SSL, this error value indicates that the option level is not equal to SO_SOCKET.
WSAENOTCONN
The connection has been reset when SO_KEEPALIVE is set.
WSAENOTSOCK
The descriptor is not a socket.

Remarks

The setsockopt function sets the current value for a socket option associated with a socket of any type, in any state. Although options can exist at multiple protocol levels, they are always present at the uppermost “socket” level. Options affect socket operations, such as whether expedited data (OOB data for example) is received in the normal data stream, and whether broadcast messages can be sent on the socket.

There are two types of socket options: Boolean options that enable or disable a feature or behavior, and options that require an integer value or structure. To enable a Boolean option, optval points to a nonzero integer. To disable the option optval points to an integer equal to zero. The optlen parameter should be equal to sizeof(int) for Boolean options. For other options, optval points to the an integer or structure that contains the desired value for the option, and optlen is the length of the integer or structure.

The following options are supported for setsockopt. For default values of these options, see the description. The Type identifies the type of data addressed by optval.

level = SOL_SOCKET

Value
Type
Description
SO_BROADCAST | BOOL | Allow transmission of broadcast messages on the socket.
SO_DONTLINGER | BOOL | Do not block close waiting for unsent data to be sent. Setting this option is equivalent to setting SO_LINGER with l_onoff set to zero.
SO_DONTROUTE | BOOL | Do not route: send directly to interface.
SO_GROUP_PRIORITY | int | Reserved for future use with socket groups. Specify the relative priority to be established for sockets that are part of a socket group.
SO_KEEPALIVE | BOOL | Send keepalives
SO_LINGER | struct LINGER | Linger on close if unsent data is present.
SO_REUSEADDR | BOOL | Allow the socket to be bound to an address that is already in use. (See bind.)
SO_SNDBUF | int | Specify the total per-socket buffer space reserved for sends. This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window.

level = IPPROTO_TCP

Value
Type
Description
TCP_NODELAY BOOL Disables the Nagle algorithm for send coalescing.

BSD options not supported for setsockopt are:

Value
Type
Meaning
SO_ACCEPTCONN | BOOL | Socket is listening
SO_RCVLOWAT | int | Receive low water mark
SO_SNDLOWAT | int | Send low water mark
SO_SNDTIMEO | int | Send time-out
SO_TYPE | int | Type of the socket

SO_GROUP_PRIORITY
Reserved for future use with socket groups. Group priority indicates the relative priority of the specified socket relative to other sockets within the socket group. Values are non-negative integers, with zero corresponding to the highest priority. Priority values represent a hint to the underlying service provider about how potentially scarce resources should be allocated. For example, whenever two or more sockets are both ready to transmit data, the highest priority socket (lowest value for SO_GROUP_PRIORITY) should be serviced first with the remainder serviced in turn according to their relative priorities.

The WSAENOPROTOOPT error is indicated for nongroup sockets or for service providers that do not support group sockets.

SO_KEEPALIVE
An application can request that a TCP/IP provider enable the use of "keep-alive" packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alives. If it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts—Communication Layers. If a connection is dropped as the result of "keep-alives" the error value WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.
SO_LINGER
The SO_LINGER option controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application sets the desired behavior by creating a LINGER structure (pointed to by the optval parameter) with these members l_onoff and l_linger set appropriately.
SO_REUSEADDR
By default, a socket cannot be bound (see bind) to a local address that is already in use. On occasion, however, it can be necessary to "re-use" an address in this way. Since every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. The option is interpreted only at the time of the bind. It is therefore unnecessary and harmless to set the option on a socket that is not to be bound to an existing address. Setting or resetting the option after the bind has no effect on this or any other socket.
SO_SNDBUF
When a Windows Sockets implementation supports the SO_SNDBUF option, an application can request different buffer sizes (larger or smaller). The call to setsockopt can succeed even when the implementation did not provide the whole amount requested. An application must call getsockopt with the same option to check the buffer size actually provided.
TCP_NODELAY
The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The process involves buffering send data when there is unacknowledged data already "in flight" or buffering send data until a full-size packet can be sent. It is highly recommended that TCP/IP service providers enable the Nagle Algorithm by default, and for the vast majority of application protocols the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and TCP_NODELAY can be used to turn it off. These are applications where many small messages are sent, and the time delays between the messages are maintained. Application writers should not set TCP_NODELAY unless the impact of doing so is well-understood and desired because setting TCP_NODELAY can have a significant negative impact on network and application performance.

To set a socket to secure mode, the option level parameter, level, must set to SO_SOCKET, the option name, optname to SO_SECURE, and the option value, optval, must be a pointer to a DWORD containing SO_SEC_SSL. These settings ensure that the Unified Secure Sockets Layer (SSL) package be used. The following code example shows how to set a socket to secure mode.

DWORD optval = SO_SEC_SSL;
err = setsockopt(
    Socket,
    SOL_SOCKET,
    SO_SECURE,
    &optval,
    sizeof(optval)
    );.

For Infrared Sockets (IrSock), Af_irda.h must be explicitly included.

IrSock provides two settable socket options:

Value
Type
Meaning
IRLMP_IAS_SET | * IAS_SET | Sets IAS attributes.
IRLMP_IRLPT_MODE | * int | In non-zero, enables IrLPT mode for printing to IrDA printers.

The IRLMP_IAS_SET socket option allows the application to set a single attribute of a single class in the local IAS. The application specifies the class to set and the attribute and attribute type. The maximum length of an attribute name is 60 characters however, regardless of the set value for characters beyond the 60th, Windows CE will set these to NULL. That is, these two arrays will be truncated at 60 characters.

The IRLMP_RAW_MODE socket option allows the application to switch between TinyTP mode and unreliable IrLMP mode. If it is not set, IrSockets are assumed to use TinyTP. This option is only available after issuing the socket function and before issuing any other Windows Sockets function.

Many SO_ level socket options are not meaningful to IrSockets. Only SO_LINGER is specifically supported.

See Also

bind, getsockopt, ioctlsocket, socket, WSAStartup


SetupComm

This function initializes the communications parameters for a specified communications device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetupComm(HANDLE hFile, DWORD dwInQueue,
DWORD dwOutQueue);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
dwInQueue
[in] Specifies the recommended size, in bytes, of the device’s internal input buffer.
dwOutQueue
[in] Specifies the recommended size, in bytes, of the device’s internal output buffer.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

After a process uses the CreateFile function to open a handle to a communications device, it can call SetupComm to set the communications parameters for the device. If it does not set them, the device uses the default parameters when the first call to another communications function occurs.

The dwInQueue and dwOutQueue parameters specify the recommended sizes for the internal buffers used by the driver for the specified device. For example, YMODEM protocol packets are slightly larger than 1024 bytes. Therefore, a recommended buffer size might be 1200 bytes for YMODEM communications.

The device driver receives the recommended buffer sizes, but is free to use any input and output (I/O) buffering scheme, as long as it provides reasonable performance and data is not lost due to overrun (except under extreme circumstances). For example, the function can succeed even though the driver does not allocate a buffer, as long as some other portion of the system provides equivalent functionality.

See Also

CreateFile, SetCommState


SetUrlCacheEntryGroup

This function adds or removes entries from a cache group.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL SetUrlCacheEntryGroup (LPCSTR lpszUrlName,
DWORD dwFlags, GROUPID GroupId, LPBYTE pbGroupAttributes, DWORD cbGroupAttributes, LPVOID lpReserved);

Parameters

lpszUrlName
[in] Address of a string value that contains the URL of the cached resource.
dwFlags
[in] Unsigned long integer value that determines whether the entry is added to or removed from a cache group. Can be one of the following values:
Value
Description
INTERNET_CACHE_GROUP_ADD | Adds the cache entry to the cache group.
INTERNET_CACHE_GROUP_REMOVE | Removes the cache entry from the cache group.

GroupId
[in] GROUPID value that indicates the cache group that the entry will be added to or removed from.
pbGroupAttributes
[in] Reserved. Must be set to NULL.
cbGroupAttributes
[in] Reserved. Must be set to zero.
lpReserved
[in] Reserved. Must be set to NULL.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

A cache entry can belong to more than one cache group.


SetUrlCacheEntryInfo

This function sets the specified members of the INTERNET_CACHE_ENTRY_INFO structure.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL SetUrlCacheEntryInfo (LPCSTR lpszUrlName,
LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
DWORD dwFieldControl);

Parameters

lpszUrlName
[in] Address of a string value that contains the URL of the cached resource.
lpCacheEntryInfo
[in] Address of an INTERNET_CACHE_ENTRY_INFO structure containing the values to be assigned to the cache entry designated by lpszUrlName.
dwFieldControl
[in] Unsigned long integer value that contains a bitmask that indicates the members that are to be set. Can be a combination of the following values:
Value
Description
CACHE_ENTRY_ACCTIME_FC | Sets the last access time.
CACHE_ENTRY_ATTRIBUTE_FC | Sets the cache entry type.
CACHE_ENTRY_EXEMPT_DELTA_FC | Sets the exempt delta.
CACHE_ENTRY_EXPTIME_FC | Sets the expire time.
CACHE_ENTRY_HEADERINFO_FC | Not currently implemented.
CACHE_ENTRY_HITRATE_FC | Sets the hit rate.
CACHE_ENTRY_MODTIME_FC | Sets the last modified time.
CACHE_ENTRY_SYNCTIME_FC | Sets the last sync time.

Return Values

Returns TRUE if successful, or FALSE otherwise.

See Also

GetUrlCacheEntryInfo


shutdown

This function disables send or receive operations on a socket. It does not release any system resources used by the socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int shutdown (SOCKET s, int how);

Parameters

s
[in] Descriptor that identifies a socket.
how
[in] Flag that describes what types of operation will no longer be allowed.

Return Values

Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The shutdown function is used on all types of sockets to disable reception, transmission, or both.

If the how parameter is SD_RECEIVE, subsequent calls to the recv function on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP sockets, if there is still data queued on the socket waiting to be received, or data arrives subsequently, the connection is reset, since the data cannot be delivered to the user. For UDP sockets, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.

If the how parameter is SD_SEND, subsequent calls to the send function are disallowed. For TCP sockets, a FIN will be sent after all data is sent and acknowledged by the receiver.

Setting how to SD_BOTH disables both sends and receives as described above.

The shutdown function does not close the socket. Any resources attached to the socket will not be freed until closesocket is invoked.

Note The shutdown function does not block regardless of the SO_LINGER setting on the socket.

An application should not rely on being able to re-use a socket after it has been shut down. In particular, a Windows Sockets provider is not required to support the use of connect on a socket that has been shutdown.

See Also

closesocket, connect, socket, WSAStartup


socket

This function creates a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

SOCKET socket (int af, int type, int protocol);

Parameters

af
[in] Address family specification.
type
[in] Type specification for the new socket.

The following are the only two type specifications supported for Windows Sockets 1.1:
Value
Description
SOCK_STREAM | Provides sequenced, reliable, two-way, connection-based byte streams with an out-of-band data transmission mechanism. Uses TCP for the Internet address family.
SOCK_DGRAM | Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses UDP for the Internet address family.

protocol
[in] Particular protocol to be used with the socket that is specific to the indicated address family.

Return Values

A descriptor referencing the new socket indicates that no error occurred. INVALID_SOCKET indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

For Infrared Sockets (IrSock), this function has the following additional requirements:

  • Af_irda.h must be explicitly included.
  • Set the af parameter to AF_IRDA, and set the protocol parameter to NULL.

The PF_INET and AF_IRDA ARPA Internet address formats are supported.

The socket function causes a socket descriptor and any related resources to be allocated and bound to a specific transport service provider. Windows Sockets will utilize the first available service provider that supports the requested combination of address family, socket type and protocol parameters.

Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before any data can be sent or received on it. A connection to another socket is created with a connect call. Once connected, data can be transferred using send and recv calls. When a session has been completed, a closesocket must be performed.

The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error value set to WSAETIMEDOUT.

Connectionless, message-oriented sockets allow sending and receiving of datagrams to and from arbitrary peers using sendto and recvfrom. If such a socket is connected to a specific peer, datagrams can be sent to that peer using send and can be received only from this peer using recv.

See Also

accept, bind, closesocket, connect, getsockname, getsockopt, ioctlsocket, recvfrom, select, send, sendto, setsockopt, shutdown, WSAStartup


TransmitCommChar

This function transmits a specified character ahead of any pending data in the output buffer of the specified communications device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransmitCommChar(HANDLE hFile, char cChar);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
cChar
[in] Specifies the character to be transmitted.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The TransmitCommChar function is useful for sending an interrupt character (such as a CTRL+C) to a host system.

If the device is not transmitting, TransmitCommChar cannot be called repeatedly. Once TransmitCommChar places a character in the output buffer, the character must be transmitted before the function can be called again. If the previous character has not yet been sent, TransmitCommChar returns an error.

See Also

CreateFile, WaitCommEvent


UnlockUrlCacheEntryFile

This function unlocks the cache entry that was locked while the file was retrieved for use from the cache.

At a Glance

Header file: | Wininet.h
Windows CE versions: | 2.12 and later

Syntax

BOOL UnlockUrlCacheEntryFile (LPCSTR lpszUrlName,
DWORD dwReserved);

Parameters

lpszUrlName
[in] Address of a string that contains the source name of the cache entry that is being unlocked. The name string should not contain any escape characters.
dwReserved
[in] Reserved. Must be set to zero.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The application should not access the file after calling this function.

When this function returns, the cache manager is free to delete the cache entry.

See Also

RetrieveUrlCacheEntryFile


VerifySignature

This function verifies the signature of a message at the other end.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

SECURITY_STATUS VerifySignature( PCtxtHandle phContext,
PSecBufferDesc pMessage, ULONG MessageSeqNo, PULONG pfQOP );

Parameters

phContext
[in] Pointer to the handle to the context to use for the message.
pMessage
[in] Pointer to a SecBufferDesc structure that references a set of SecBuffer structures that contain the message and signature to verify. The signature is in a SecBuffer structure of type SECBUFFER_TOKEN.
MessageSeqNo
[in] Specifies the sequence number expected by the transport application, if any. If the transport application does not maintain sequence numbers, this parameter is zero.
pfQOP
[out] Pointer to a ULONG variable that receives package-specific flags that indicate the quality of protection.

Return Values

SEC_E_OK indicates that the function verified that the message was received in the correct sequence and had not been modified.

If the function determines that the message is not correct according to the information in the signature, one of the error values described in the following table is returned.

Value
Description
SEC_E_OUT_OF_SEQUENCE | The message was not received in the correct sequence.
SEC_E_MESSAGE_ALTERED | The message has been altered.

Remarks

The VerifySignature function verifies that the message received was correct according to the information in the signature.

See Also

MakeSignature


WaitCommEvent

This function waits for an event to occur for a specified communications device. The set of events that are monitored by WaitCommEvent is contained in the event mask associated with the device handle.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WaitCommEvent(HANDLE hFile, LPDWORD lpEvtMask, LPOVERLAPPED lpOverlapped);

Parameters

hFile
[in] Handle to the communications device. The CreateFile function returns this handle.
lpEvtMask
[out] Long pointer to a 32-bit variable that receives a mask indicating the events that occurred. If an error occurs, the value is zero; otherwise, it is one or more of the following values:
Value
Description
EV_BREAK | A break was detected on input.
EV_CTS | The CTS (clear-to-send) signal changed state.
EV_DSR | The DSR (data-set-ready) signal changed state.
EV_ERR | A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_POWER | Power event, which is generated whenever the device is powered on.
EV_RING | A ring indicator was detected.
EV_RLSD | The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR | A character was received and placed in the input buffer.
EV_RXFLAG | The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY | The last character in the output buffer was sent.

lpOverlapped
[in] Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The WaitCommEvent function monitors a set of events for a specified communications resource. To set and query the current event mask of a communications resource, use the SetCommMask and GetCommMask functions. When a communications event that is set by SetCommMask occurs, WaitCommEvent returns.

See Also

CreateFile, DCB, GetCommMask, SetCommMask, SetCommState


WNetAddConnection3

This function makes a connection to a network resource and can specify a local name for the resource.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetAddConnection3(HWND hwndOwner, LPNETRESOURCE lpNetResource, LPTSTR lpPassword, LPTSTR lpUserName, DWORD dwFlags);

Parameters

hwndOwner
[in] Handle to a window that the provider of network resources can use as an owner window for dialog boxes.

The hwndOwner parameter may be NULL.

lpNetResource
[in] Long pointer to a NETRESOURCE data structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure:
Value
Description
dwType | Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
LpLocalName | Long pointer to a null-terminated string that specifies the name of a local device to be redirected, such as “MyDevice” or “LocalShare”. The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without assigning a local name.
LpRemoteName | Long pointer to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length. The string must follow the network provider’s naming conventions.
LpProvider | Long pointer the network provider to connect to. Applications should set this to NULL because the Microsoft Windows Network is the only provider supported.

The WNetAddConnection3 function ignores the other members of the NETRESOURCE structure.

lpPassword
[in] Long pointer to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

If lpPassword points to an empty string, the function does not use a password.

lpUserName
[in] Long pointer to a null-terminated string that specifies a user name to be used in making the connection.

If lpUserName is NULL, the function uses the default user name. For dial-up networking connections, the default user name is the one used to establish the connection. For LAN connections, the default user name is configured in the network control panel. On systems that support a windows user interface, the user is prompted to enter logon credentials if no default credentials exist or if the logon attempt fails using the existing credentials.

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

dwFlags
[in] Specifies connection options. It is the following value:
Value
Description
CONNECT_UPDATE_PROFILE The network resource connection should be remembered.
If this bit flag is set, the registry will store the connection information and make it available when the system reboots.
The operating system does not remember unsuccessful connections or unnamed connections. An unnamed connection occurs when lpLocalName is NULL or points to an empty string.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. Returning an error value provides compatibility with the behavior of the Windows for Workgroups function WNetAddConnection. You can also call the GetLastError function to obtain the same error value. Possible GetLastError values are described in the following table.

Value
Description
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local name specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by lpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BUSY | The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED | The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers or by a called resource.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified in lpLocalName is already in the user profile.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH | The network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK | There is no network present.

Remarks

Windows CE does not support the concept of drive-letters. An application can name a local resource “F:”, but that naming convention has no special significance. The lpLocalName field of the NETRESOURCE structure can contain any string of up to 64 characters long. If the local name is NULL or empty, the resource is connected without a local name. If it is “*”, the default name will be constructed as “<share> on <server>“ extracted from the remote name of “\\server\share”.

Except for nameless connections, the connected resource will appear as a subfolder under the \NETWORK directory. The subfolder is named after the lpLocalName string.

Windows CE supports only the “Microsoft Windows Network” provider. Persistent connections are stored in the registry and not automatically reconnected when the system is rebooted.


WNetCancelConnection2

This function breaks an existing network connection.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetCancelConnection2(LPTSTR lpName, DWORD dwFlags, BOOL fForce);

Parameters

lpName
[in] Long pointer to a null-terminated string that specifies the name of either the local name or the remote network resource to disconnect from. If this parameter specifies a local name, only the specified redirection is broken; otherwise, all connections to the remote network resource are broken.
dwFlags
[in] Specifies a bitmask for the connection type. The following values are defined:
Value
Description
0 | No stored information about the connection is updated.
CONNECT_UPDATE_PROFILE | The system is updated with the information that this is no longer a persistent connection. Disconnecting resources using remote names has no effect on persistent connections.

fForce
[in] Boolean that specifies whether the disconnection should occur even if there are open files or jobs on the connection. If this parameter is FALSE, the function fails if there are open files or jobs.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError values are described in the following table.

Value
Description
ERROR_DEVICE_IN_USE | The device is in use by an active process and cannot be disconnected.
ERROR_NOT_CONNECTED | The name specified by the lpName parameter is not a local or remote network resource, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES | There are open files, and the fForce parameter is FALSE.

Remarks

Connections are not automatically restored when the system is started.


WNetCloseEnum

This function ends a network resource enumeration started by the WNetOpenEnum function.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetCloseEnum(HANDLE hEnum);

Parameters

hEnum
[in] Handle to an enumeration instance. This handle must be returned by the WNetOpenEnum function.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError values are described in the following table.

Value
Description
ERROR_NO_NETWORK | A network is not present.
ERROR_INVALID_HANDLE | The handle specified in hEnum is not valid.

The function returns error values for compatibility with Windows for Workgroups. For compatibility with Win32, the function also sets the error value returned by GetLastError.


WNetConnectionDialog1

This function brings up a general browsing dialog for connecting to network resources.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetConnectionDialog1(LPCONNECTDLGSTRUCT lpConnectDlgStruc);

Parameters

lpConnectDlgStruct
[in] Long pointer to the CONNECTDLGSTRUCT structure, which establishes the browsing dialog parameters.

Return Values

ERROR_SUCCESS indicates success. 0xFFFFFFFF indicates that the user canceled the dialog box. Typically, this dialog box only returns an error if the user cannot enter a dialog session. This is because errors that occur after a session are reported to the user directly. Of the possible error values, ERROR_INVALID_PARAMETER indicates one of the following:

  • CONNDLG_RO_PATH is set and lpConnRes->lpRemoteName does not point to a remote name.
  • Both CONNDLG_PERSIST and CONNDLG_NOT_PERSIST are set.

Other possible values are described in the following table.

Value
Description
ERROR_BAD_DEV_TYPE | The lpConnRes->dwType members of CONNECTDLGSTRUCT are not set to indicate RESOURCETYPE_DISK.
ERROR_BUSY | The network provider is busy, and is possibly initializing. The caller should retry.
ERROR_NO_NETWORK | The network is not present.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to bring up the dialog box.

Remarks

The dwDevNum member of the CONNECTDLGSTRUCT structure pointed to by the lpConnectDlgStruc parameter is ignored.

The dwFlags member of the CONNECTDLGSTRUCT can be either CONNDLG_RO_PATH or 0.


WNetDisconnectDialog

This function starts a general browsing dialog box for disconnecting from network resources. It lists all currently connected and remembered resources and lets the user select which one to disconnect.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetDisconnectDialog( HWND hwnd DWORD dwType );

Parameters

hwnd
[in] Handle to the owning window.
dwType
[in] Ignored; set to zero.

Return Values

ERROR_SUCCESS indicates success. 0xFFFFFFFF indicates that the user canceled out of the dialog box. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Meaning
ERROR_NO_NETWORK | No network is present.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.

Remarks

If the user chooses OK in the dialog box, the requested network disconnection will have been made when WNetDisconnectDialog returns.


WNetDisconnectDialog1

This function attempts to disconnect from a network. If the underlying network returns ERROR_OPEN_FILES, the function prompts the user for confirmation. Users will be informed of any errors.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetDisconnectDialog1(LPDISCDLGSTRUCT lpDiscDlgStruc);

Parameters

lpDiscDlgStruct
[in] Long pointer to the DISCDLGSTRUCT data structure, which specifies the behavior for the disconnect attempt.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Description
ERROR_SUCCESS | The connection is successfully disconnected.
ERROR_CANCELLED | After the user was prompted for a decision to disconnect, the user elected not to disconnect.
ERROR_OPEN_FILES | The function is unable to disconnect because the user is actively using the connection.
ERROR_BUSY | The network provider is busy, and is possibly initializing. The caller should retry.
ERROR_NO_NETWORK | The network is not present.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.


WNetEnumResource

This function continues a network-resource enumeration started by the WNetOpenEnum function.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetEnumResource( HANDLE hEnum, LPDWORD lpcCount,
LPVOID lpBuffer, LPDWORD lpBufferSize);

Parameters

hEnum
[in] Handle to an enumeration instance. This handle must be returned by WNetOpenEnum.
lpcCount
[in/out] Long pointer to a variable specifying the number of entries requested. If the number requested is 0xFFFFFFFF, the function returns as many entries as possible.

When the function finishes successfully, the variable pointed to by this parameter contains the number of entries actually read.

lpBuffer
[in] Long pointer to the buffer that receives the enumeration results, which are returned as an array of NETRESOURCE structures. The buffer is valid until the next call using the handle given by the hEnum parameter. The order of NETRESOURCE structures in the array is not predictable.
lpBufferSize
[in/out] Long pointer to a variable that specifies the size, in bytes, of the lpBuffer parameter. If the buffer is too small to receive even one entry, this parameter receives the required size of the buffer.

Return Values

ERROR_SUCCESS indicates that the enumeration succeeded, and the buffer contains the requested data. The calling application can continue to call WNetEnumResource to complete the enumeration. ERROR_NO_MORE_ITEMS indicates that there are no more entries. In this case, the buffer contents are undefined. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Description
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_INVALID_HANDLE | The handle specified by the hEnum parameter is not valid.
ERROR_NO_NETWORK | No network is present. This condition is tested before hEnum is tested for validity.

The function returns error values for compatibility with Windows for Workgroups. For compatibility with the Win32 API, the function also sets the error value returned by GetLastError.

Remarks

An application cannot set the lpBuffer parameter to NULL and retrieve the required buffer size from the lpBufferSize parameter. Instead, the application should allocate a buffer of a reasonable size—16 kilobytes (K) is typical—and use the value of lpBufferSize for error detection.


WNetGetConnection

This function retrieves the remote name of the network resource associated with a local name.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetGetConnection( LPCTSTR lpLocalName,
LPTSTR lpRemoteName, LPDWORD lpnLength);

Parameters

lpLocalName
[in] Long pointer to a null-terminated string that specifies the local name of the network resource. Set up this resource with the WNetAddConnection3 function.
lpRemoteName
[out] Long pointer to a buffer that receives the null-terminated remote name used to make the connection.
lpnLength
[in/out] Long pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpRemoteName parameter. If the function fails because the buffer is not big enough, this parameter returns the required buffer size.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Description
ERROR_BAD_DEVICE | The string pointed to by the lpLocalName parameter is invalid.
ERROR_NOT_CONNECTED | The network resource specified by lpLocalName is not currently connected and is not a persistent connection.
ERROR_MORE_DATA | The lpRemoteName buffer is too small. The lpnLength parameter points to a variable that contains the required buffer size. More entries are available with subsequent calls.
ERROR_CONNECTION_UNAVAIL | The network resource specified by lpLocalName is not currently connected and is a persistent connection.
ERROR_NO_NETWORK | No network is present.

The WNetGetConnection function returns error values for compatibility with Windows for Workgroups. For compatibility with the Win32 API, the function also sets the error value returned by GetLastError.

Remarks

The WNetGetConnection function can be used to obtain information on network resources, such as printers.

See Also

WNetAddConnection3


WNetGetUniversalName

This function maps a local path for a network resource to a data structure containing the Universal Name Convention based name.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetGetUniversalName(LPCTSTR lpLocalPath,
DWORD dwInfoLevel, LPVOID lpBuffer, LPDWORD lpBufferSize);

Parameters

lpLocalPath
[in] Long pointer to a null-terminated string that is a local name for a network resource. It must point to the subfolder in the \NETWORK directory.

For example, if local name “myShare” has been mapped to a network share, and the network resource of interest is a file named SAMPLE.DOC in the directory \WIN32\EXAMPLES on that share, the local path is myShare:\WIN32\EXAMPLES\SAMPLE.DOC.

dwInfoLevel
[in] Specifies the type of data structure that the function will store in the buffer pointed to by lpBuffer. This parameter can be one of the following values:
Value
Description
UNIVERSAL_NAME_INFO_LEVEL | The function will store a UNIVERSAL_NAME_INFO data structure in the buffer.
REMOTE_NAME_INFO_LEVEL | The function will store a REMOTE_NAME_INFO data structure in the buffer.

The UNIVERSAL_NAME_INFO data structure points to a Universal Naming Convention (UNC) name string.

The REMOTE_NAME_INFO data structure points to a UNC name string and two additional connection information strings.

lpBuffer
[out] Long pointer to a buffer that receives the type of data structure specified by the dwInfoLevel parameter.
lpBufferSize
[in/out] Long pointer to a variable that specifies the size in bytes of the buffer pointed to by lpBuffer.

If the function succeeds, it sets the variable pointed to by lpBufferSize to the size in bytes of the data structure stored in the buffer. If the function fails because the buffer is too small, indicated by the ERROR_MORE_DATA error value, it sets the variable pointed to by lpBufferSize to the required buffer size.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Description
ERROR_BAD_DEVICE | The string pointed to by lpLocalPath is invalid.
ERROR_CONNECTION_UNAVAIL | There is no current connection to the remote device, but there is a remembered, or persistent, connection to it.
ERROR_MORE_DATA | The buffer pointed to by lpBuffer is too small. The function sets the variable pointed to by lpBufferSize to the required buffer size. More entries are available with subsequent calls.
ERROR_NO_NETWORK | No network present.
ERROR_NOT_CONNECTED | The device specified by lpLocalPath is not redirected.

Remarks

A universal form of a local path identifies a network resource in an unambiguous, computer-independent manner. The name can then be passed to processes on other computers, allowing those processes to obtain access to the resource.

The WNetGetUniversalName function currently supports one universal name form: universal naming convention (UNC) names, which look like the following:

\\servername\sharename\path\file

Using the example from the preceding description of the lpLocalPath parameter, if the shared network drive is on a server named COOLSERVER, and the share name is HOTSHARE, the UNC name for the network resource whose local name is myShare:\WIN32\EXAMPLES\SAMPLE.DOC would be

\\coolserver\hotshare\win32\examples\sample.doc

The UNIVERSAL_NAME_INFO data structure contains a pointer to a UNC name string. The REMOTE_NAME_INFO data structure contains a pointer to a UNC name string. It also includes pointers to two other useful strings. A program can pass the REMOTE_NAME_INFO structure’s lpszConnectionInfo member into the WNetAddConnection3 function to connect a local device to the network resource, and then append the string pointed to by the lpszRemainingPath member to the local device string. The resulting string can be passed to Win32 file functions.


WNetGetUser

This function retrieves the user name used to establish a network connection.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetGetUser( LPCTSTR lpName, LPTSTR lpUserName, LPDWORD lpnLength);

Parameters

lpName
[in] Long pointer to a null-terminated string that specifies either a local name that has been redirected to a network resource, or the remote name of a network resource to which a connection has been made without necessarily creating a local name.
lpUserName
[out] Long pointer to a buffer that receives the null-terminated user name.
lpnLength
[in/out] Long pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpUserName. If the call fails because the buffer is not big enough, this variable contains the required buffer size.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Description
ERROR_NOT_CONNECTED | The resource name specified by lpName is not a connected network resource.
ERROR_MORE_DATA | The supplied buffer is not large enough to hold the user name.
ERROR_NO_NETWORK | No network is present.

The function returns error values for compatibility with Windows-based desktop platforms. For compatibility with the Win32 API, the function also sets the error value returned by GetLastError.


WNetOpenEnum

This function starts an enumeration of network resources or existing connections.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

DWORD WNetOpenEnum(DWORD dwScope, DWORD dwType,
DWORD dwUsage, LPNETRESOURCE lpNetResource,
LPHANDLE lphEnum);

Parameters

dwScope
[in] Specifies the scope of the enumeration. This parameter can be one of the following values:
Value
Description
RESOURCE_CONNECTED | All currently connected resources (the dwUsage parameter is ignored).
RESOURCE_GLOBALNET | All resources on the network.
RESOURCE_REMEMBERED | All remembered (persistent) connections (the dwUsage parameter is ignored). These connections may or may not currently be connected.

dwType
[in] Specifies the resource types to enumerate. This parameter can be a combination of the following values:
Value
Description
RESOURCETYPE_ANY | All resources (this value cannot be combined with RESOURCETYPE_DISK or RESOURCETYPE_PRINT).
RESOURCETYPE_DISK | All disk resources.
RESOURCETYPE_PRINT | All print resources.

If the Windows CE network client cannot distinguish between print and disk resources, it may enumerate all resources.

dwUsage
[in] Specifies the resource usage to be enumerated. This parameter can be a combination of the following values:
Value
Description
0 | All resources
RESOURCEUSAGE_CONNECTABLE | All connectable resources
RESOURCEUSAGE_CONTAINER | All container resources

This parameter is ignored if the dwScope parameter is not RESOURCE_GLOBALNET.

lpNetResource
[in] Long pointer to a NETRESOURCE structure specifying the container to enumerate.

If an application needs to enumerate all the network resources, set the lpNetResource parameter to the topmost container, or the root, of the network.

This structure can be filled in by the application or may have been returned by a call to the WNetEnumResource function. The NETRESOURCE structure must specify a container resource; that is, the RESOURCEUSAGE_CONTAINER value must be specified in the dwUsage member.

To enumerate all network resources, an application can begin the enumeration by calling WNetOpenEnum with lpNetResource pointing to a NETRESOURCE structure specifying the root of the network, then using the returned handle with WNetEnumResource to enumerate resources. If one of the resources in the NETRESOURCE array returned by the WNetEnumResource function is a container resource, WNetOpenEnum can be used to open the resource for further enumeration.

If the dwScope parameter is not RESOURCE_GLOBALNET, this parameter must be NULL.

lphEnum
[out] Long pointer to a variable filled with an enumeration handle that can be used in a subsequent call to WNetEnumResource.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. To get extended error information, call GetLastError. Possible GetLastError error values are described in the following table.

Value
Description
ERROR_NOT_CONTAINER | The lpNetResource parameter does not point to a container.
ERROR_INVALID_PARAMETER | Either the dwScope or dwType parameter is invalid, or there is a bad combination of parameters.
ERROR_NO_NETWORK | No network is present.

The function returns error values for compatibility with Windows for Workgroups. For compatibility with the Win32 API, the function also sets the error value returned by GetLastError.

Remarks

The WNetOpenEnum function is used to begin enumeration of the resources in a single container. The following code examples show the hierarchical structure of a Microsoft Windows Network:

LanMan (container, in this case the provider)
 ACCOUNTING (container, in this case the domain)
 \\ACCTSPAY (container, in this case the server)
 PAYFILES (disk)
 LASERJET (print)


WSACleanup

This function terminates the use of Winsock.dll.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int WSACleanup()

Return Values

Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

In a multithreaded environment, WSACleanup terminates Windows Sockets operations for all threads.

Remarks

This function initiates no action and is provided only for compatibility reasons.

An application or DLL is required to perform a successful WSAStartup call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application or DLL must call WSACleanup to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL.

Sockets that were open when WSACleanup was called are reset and automatically deallocated as if closesocket were called; sockets that have been closed with closesocket but that still have pending data to be sent can be affected—the pending data can be lost if the Winsock.dll is unloaded from memory as the application exits. To insure that all pending data is sent, an application should use shutdown to close the connection, then wait until the close completes before calling closesocket and WSACleanup. All resources and internal state, such as queued un-posted messages, must be deallocated so as to be available to the next user.

There must be a call to WSACleanup for every successful call to WSAStartup made by a task. Only the final WSACleanup for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the Winsock.dll.

See Also

WSAStartup


WSAGetLastError

This function retrieves the error status for the last Windows Socket operation that failed.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int WSAGetLastError(void);

Return Values

The return value indicates the error value for this thread’s last Windows Sockets operation that failed.

Remarks

The WSAGetLastError function returns the last network error that occurred. When a particular Windows Sockets function indicates that an error has occurred, this function should be called to retrieve the appropriate error value. This error value can be different from the error value obtained from getsockopt SO_ERROR, which is socket-specific since WSAGetLastError is for all thread-specific sockets.

A successful function call, or a call to WSAGetLastError, does not reset the error value. To reset the error value, use the WSASetLastError function call with iError set to zero. A getsockopt SO_ERROR also resets the error value to zero.

See Also

GetLastError


WSAIoctl

This function controls the mode of a socket.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 2.0 and later

Syntax

int WSAIoctl(SOCKET s,DWORD dwIoContorlCode,LPVOID lpvInBuffer,DWORD cbInBuffer,LPVOID lpvOutBuffer,DWORD cbOutBuffer,LPDWORD lpcbBytesReturned,LPWSAOVERLAPPED lpOverlapped,LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE);

Parameters

s
[in] Descriptor that identifies a socket.
dwIoControlCode
[in] Specifies the control code of operation to perform.
lpvInBuffer
[in] Long void pointer to the input buffer.
cbInBuffer
[in] Number that indicates the size of the input buffer.
lpvOutBuffer
[out] Long void pointer to the output buffer.
cbOutBuffer
[in] Number that indicates the size of the output buffer.
lpcbBytesReturned
[out] For secure sockets, long pointer to the number of bytes returned in the output buffer.
lpOverlapped
[in] Unsupported; set to NULL.
lpCompletionRoutine
[in] Unsupported; set to NULL.

Return Values

Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem.

It is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket opcodes while providing a convenient way to partition the opcode identifier space in as much as the dwIoControlCode parameter is now a 32-bit entity. The dwIoControlCode parameter is designed to allow for protocol and vendor independence when adding new control codes while retaining backward compatibility with the Windows Sockets 1.1 and Unix control codes. The dwIoControlCode parameter has the following form:

3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1
1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
I | O | V | T | Vendor/Address Family | Code

I is set if the input buffer is valid for the code, as with IOC_IN.

O is set if the output buffer is valid for the code, as with IOC_OUT. Codes with both input and output parameters set both I and O.

V is set if there are no parameters for the code, as with IOC_VOID.

T is a two-bit quantity that defines the type of ioctl. The following values are defined:

0 – The ioctl is a standard Unix ioctl code, as with FIONREAD and FIONBIO.

1 – Not currently supported in Windows CE.

2 – The ioctl applies only to a specific address family.

3 – The ioctl applies only to a specific vendor's provider. This type allows companies to be assigned a vendor number that appears in the Vendor/Address family field. Then, the vendor can define new ioctls specific to that vendor without having to register the ioctl with a clearinghouse, thereby providing vendor flexibility and privacy.

Vendor/Address family – An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the address family to which the code applies (if T == 2). If this is a Unix ioctl code (T == 0) then this field has the same value as the code on Unix.

Code – The 16-bit quantity that contains the specific ioctl code for the operation.

The following Unix ioctl codes (commands) are supported:

FIONBIO
Enable or disable nonblocking mode on socket s. lpvInBuffer points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.
FIONREAD
Determine the amount of data that can be read atomically from socket s. lpvOutBuffer points at an unsigned long in which WSAIoctl stores the result. If s is stream oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of data that can be read in a single receive operation; this is normally the same as the total amount of data queued on the socket (since data stream is byte-oriented, this is not guaranteed). If s is message oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.
SIOCATMARK
Determine whether or not all out-of-band data has been read. This applies only to a socket of stream-style (for example, type SOCK_STREAM) that has been configured for inline reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next receive operation performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (Note that receive operations will never mix out-of-band and normal data in the same call.) lpvOutBuffer points at a BOOL in which WSAIoctl stores the result.

In addition to the ioctlsocket control codes (FIONBIO, SIOCATMARK, FIONREAD), the dwIoControlCode parameter may also assume the following SSL-specific control flags:

SO_SSL_GET_CAPABILITIES
Retrieves a set of flags describing the WinSock security provider’s capabilities. The output buffer must be a pointer to a DWORD bit field. At present, only the SSL_CAP_CLIENT flag is defined.
SO_SSL_GET_FLAGS
Retrieves s-channel specific flags associated with a particular socket. The output buffer must be a pointer to a DWORD bit field. See SO_SSL_SET_FLAGS for details on valid flags.
SO_SSL_SET_FLAGS
Sets the sockets’ current s-channel-specific flag values. The input buffer must be a pointer to a DWORD bit field. Currently, only the SSL_FLAG_DEFER_HANDSHAKE flag is defined to allow the application to send and receive plain text data before switching to cipher text. It is required for setting up communication through proxy servers.

Normally the WinSock security provider performs the secure handshake in the WinSock connect API. However, if this flag is set, the handshake is deferred until the application issues the SO_SSL_PERFORM_HANDSHAKE control code. After the handshaking, this flag is reset.

SO_SSL_GET_PROTOCOLS
Retrieves a list of protocols that the provider currently supports on this socket. The output buffer must be a pointer to a SSLPROTOCOLS structure as described below:

typedef struct _SSLPROTOCOL {
DWORD dwProtocol;
DWORD dwVersion;
DWORD dwFlags;
} SSLPROTOCOL, *LPSSLPROTOCOL;

typedef struct _SSLPROTOCOLS {
DWORD dwCount;
SSLPROTOCOL ProtocolList[1];
} SSLPROTOCOLS, FAR *LPSSLPROTOCOLS;

Valid protocols include SSL_PROTOCOL_SSL2, SSL_PROTOCOL_SSL3, and SSL_PROTOCOL_PCT1.

SO_SSL_SET_PROTOCOLS
Specifies a list of protocols the provider is to support on this socket. The input buffer must be a pointer to SSLPROTOCOLS structure described above.
SO_SSL_SET_VALIDATE_CERT_HOOK
Sets the pointer to the socket’s certificate validation hook. It is used to specify the callback function invoked by the WinSock security provider when a set of credentials is received from the remote party. The input buffer must be a pointer to the SSLVALIDEATECERTHOOK structure, described below:

typedef struct {
SSLVALIDATECERTFUNC HookFunc;
LPVOID pvArg;
} SSLVALIDATEPROTOCOLCERTHOOK, *PSSLVALIDATECERTHOOK;

where HookFunc is a pointer to the certificate validation callback function (see “Certificate Validation Callback” below). pvArg is a pointer to application specific data and may be used by the application for any purpose.

SO_SSL_PERFORM_HANDSHAKE
Initiates the secure handshake sequence on a connected socket where the SSL_FLAG_DEFER_HANDSHAKE flag has been set prior to the connection. Data buffers are not required, but the SSL_FLAG_DEFER_HANDSHAKE flag will be reset.

Certificate Validation Callback

The WinSock security provider invokes the certificate validation callback when the remote party receives a certificate for server authentication. All the client applications must implement the callback function to ensure that the certificate should meet the following minimum requirements:

  • The certificate has not expired;
  • The identity contained within the certificate matches that of the remote party.

The certificate validation callback function is of the following type:

typedef int (CALLBACK *SSLVALIDATECERTFUNC){
DWORD dwType, // in
LPVOID pvArg, // in
DWORD dwChainLen, // in
LPBLOB pCertChain, // in
DWORD dwFlags // in
};

The parameters are defined in the following table.

dwType
Specifies the type of data pointed to be pCertChain. This must be SSL_CERT_X59 to specify that pCertChain be a pointer to an X509 style certificate.
PvArg
An application-defined context passed into the SSLVALIDATECERTHOOK structure.
DwChainLen
The number of certificates pointed to by pCertChain. In Windows CE this will always be one.
PCertChain
Pointer to the remote party’s certificate.
DwFlags
To be designed to indicate that the certificate issuer list has been checked with the list of known certificate authorities and that the certificate is either trusted or not. This is required since not all the certificate chain is passed to the application.

The application-defined callback function will typically return one of the following error values:

Value
Description
SSL_ERR_OKAY | The remote party’s certificate is acceptable.
SSL_ERR_BAD_DATA | The certificate is improperly formatted.
SSL_ERR_BAD_SIG | The signature check fails.
SSL_ERR_CERT_EXPIRED | The certificate has expired.
SSL_ERR_CERT_REVOKED | The certificate has been revoked by its issuer.
SSL_ERR_CERT_UNKNOWN | The issuer of the certificate is not recognized or some unspecified issue arose in the processing of the certificate, rendering it unacceptable.

If the output buffer is not large enough to return all the data, WSAIoctl returns SOCKET_ERROR. The value for WSAGetLastError is WSAEFAULT and lpcbReturned contains the number of bytes required to successfully complete the operation.


WSASetLastError

This function sets the error value that can be retrieved through the WSAGetLastError function.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 2.0 and later

Syntax

void WSASetLastError ( int iError );

Parameters

iError
[in] Integer that specifies the error value to be returned by a subsequent WSAGetLastError call.

Return Values

None.

Remarks

The WSASetLastError function allows an application to set the error value to be returned by a subsequent WSAGetLastError call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error value as set by this routine.

The error value set by WSASetLastError is different from the error value reset by calling the function getsockopt with SO_ERROR.


WSAStartup

This function initializes a WSADATA structure.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

int WSAStartup(WORD wVersionRequested, LPWSADATA lpWSAData );

Parameters

wVersionRequested
[in] Specifies the highest version of Windows Sockets support that the caller can use. The high order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.
lpWSAData
[out] Long pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.

Return Values

Zero indicates success. To get a specific error value, call WSAGetLastError. The following table shows possible error values.

Value
Meaning
WSASYSNOTREADY | The underlying network subsystem is not ready for network communication.
WSAVERNOTSUPPORTED | The version of Windows Sockets support requested is not provided by this particular Windows Sockets implementation.
WSAEINPROGRESS | A blocking Windows Sockets 1.1 operation is in progress.
WSAEPROCLIM | The limit on the number of tasks supported by the Windows Sockets implementation has been reached.
WSAEFAULT | The lpWSAData is not a valid pointer.

An application cannot call WSAGetLastError to determine the error value as is normally done in Windows Sockets is WSAStartup fails. The Winsock.dll will not have been loaded in the case of a failure so the client data area where the "last error" information is stored could not be established.

Remarks

The WSAStartup function must be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets required and to retrieve details of the specific Windows Sockets implementation. The application or DLL can only issue further Windows Sockets functions after a successfully calling WSAStartup.

To support future Windows Sockets implementations and applications that can have functionality differences from current version of Windows Sockets, a negotiation takes place in WSAStartup. The caller of WSAStartup and the Winsock.dll indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to WSAStartup, the Winsock.dll examines the version requested by the application. If this version is equal to or higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in wHighVersion the highest version it supports and in wVersion the minimum of its high version and wVersionRequested. The Winsock.dll then assumes that the application will use wVersion. If the wVersion field of the WSADATA structure is unacceptable to the caller, it should call WSACleanup and either search for another Winsock.dll or fail to initialize.

It is legal and possible for an application written to this version of the specification to successfully negotiate a higher version number than the version of this specification. In such a case, the application is only guaranteed access to higher-version functionality that fits within the syntax defined in this version, such as new Ioctl codes and new behavior of existing functions. New functions, for example, may be inaccessible. To be guaranteed full access to new syntax of a future version, the application must fully conform to that future version, such as compiling against a new header file, linking to a new library, or other special cases.

This negotiation allows both a Winsock.dll and a Windows Sockets application to support a range of Windows Sockets versions. An application can use Winsock.dll if there is any overlap in the version ranges. The following chart gives examples of how WSAStartup works in conjunction with different application and Winsock.dll versions:

App versions
DLL versions
wVersion
requested
wVersion
wHigh
version
End result
1.1 | 1.1 | 1.1 | 1.1 | 1.1 | use 1.1
1.0 1.1 | 1.0 | 1.1 | 1.0 | 1.0 | use 1.0
1.0 | 1.0 1.1 | 1.0 | 1.0 | 1.1 | use 1.0
1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | use 1.1
1.1 | 1.0 | 1.1 | 1.0 | 1.0 | Application fails
1.0 1.1 1.0 --- --- WSAVERNOT
SUPPORTED
1.0 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | use 1.1
1.1 2.0 | 1.1 | 2.0 | 1.1 | 1.1 | use 1.1

The following code example demonstrates how an application that supports only version 1.1 of Windows Sockets makes a WSAStartup call:

WORD wVersionRequested;
WSADATA wsaData;
int err;

wVersionRequested = MAKEWORD( 1, 1 );

err = WSAStartup( wVersionRequested, &wsaData );
if ( err != 0 ) {
 /* Tell the user that we could not find a usable */
 /* WinSock DLL.   */
 return;
}

/* Confirm that the WinSock DLL supports 1.1.*/
/* Note that if the DLL supports versions greater */
/* than 1.1 in addition to 1.1, it will still return */
/* 1.1 in wVersion since that is the version we */
/* requested.   */

if ( LOBYTE( wsaData.wVersion ) != 1 ||
 HIBYTE( wsaData.wVersion ) != 1 ) {
 /* Tell the user that we could not find a usable */
 /* WinSock DLL.   */
 WSACleanup( );
 return;
}

/* The WinSock DLL is acceptable. Proceed. */

Once an application or DLL has made a successful WSAStartup call, it can proceed to make other Windows Sockets calls as needed. When it has finished using the services of the Winsock.dll, the application or DLL must call WSACleanup to allow the Winsock.dll to free any resources for the application.

Details of the actual Windows Sockets implementation are described in the WSADATA structure.

An application or DLL can call WSAStartup more than once if it needs to obtain the WSAData structure information more than once. On each such call the application can specify any version number supported by the DLL.

An application must call one WSACleanup call for every successful WSAStartup call to allow third-party DLLs to make use of a Winsock.dllon behalf of an application. This means, for example, that if an application calls WSAStartup three times, it must call WSACleanup three times. The first two calls to WSACleanup do nothing except decrement an internal counter; the final WSACleanup call for the task does all necessary resource deallocation for the task.

See Also

WSACleanup , WSADATA


COMMPROP

This structure is used by the GetCommProperties function to return specific communication support driver data.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _COMMPROP {
WORD wPacketLength;
WORD wPacketVersion;
DWORD dwServiceMask;
DWORD dwReserved1;
DWORD dwMaxTxQueue;
DWORD dwMaxRxQueue;
DWORD dwMaxBaud;
DWORD dwProvSubType;
DWORD dwProvCapabilities;
DWORD dwSettableParams;
DWORD dwSettableBaud;
WORD wSettableData;
WORD wSettableStopParity;
WORD dwCurrentTxQueue;
DWORD dwCurrentRxQueue;
DWORD dwProvSpec1;
DWORD dwProvSpec2;
WCHAR wcProvChar[1];
} COMMPROP;

Members

wPacketLength
Specifies the size, in bytes, of the entire data packet, regardless of the amount of data requested.
wPacketVersion
Specifies the version of the structure.
dwServiceMask
Specifies a bitmask indicating which services are implemented by this provider. The SP_SERIALCOMM value is always specified for communications providers, including modem providers.
dwReserved1
Reserved; do not use.
dwMaxTxQueue
Specifies the maximum size, in bytes, of the driver’s internal output buffer. A value of zero indicates that no maximum value is imposed by the serial provider.
dwMaxRxQueue
Specifies the maximum size, in bytes, of the driver’s internal input buffer. A value of zero indicates that no maximum value is imposed by the serial provider.
dwMaxBaud
Specifies the maximum acceptable baud rate, in bits per second (bps). It is one of the following values:
Value
Description
BAUD_075 | 75 bps
BAUD_110 | 110 bps
BAUD_134_5 | 134.5 bps
BAUD_150 | 150 bps
BAUD_300 | 300 bps
BAUD_600 | 600 bps
BAUD_1200 | 1200 bps
BAUD_1800 | 1800 bps
BAUD_2400 | 2400 bps
BAUD_4800 | 4800 bps
BAUD_7200 | 7200 bps
BAUD_9600 | 9600 bps
BAUD_14400 | 14400 bps
BAUD_19200 | 19200 bps
BAUD_38400 | 38400 bps
BAUD_56K | 56K bps
BAUD_57600 | 57600 bps
BAUD_115200 | 115200 bps
BAUD_128K | 128K bps
BAUD_USER | Programmable baud rates available

dwProvSubType
Specifies the specific communications provider type. It is one of the following values:
Value
Description
PST_FAX | FAX device
PST_LAT | LAT protocol
PST_MODEM | Modem device
PST_NETWORK_BRIDGE | Unspecified network bridge
PST_PARALLELPORT | Parallel port
PST_RS232 | RS-232 serial port
PST_RS422 | RS-422 port
PST_RS423 | RS-423 port
PST_RS449 | RS-449 port
PST_SCANNER | Scanner device
PST_TCPIP_TELNET | TCP/IP Telnet® protocol
PST_UNSPECIFIED | Unspecified
PST_X25 | X.25 standards

dwProvCapabilities
Indicates the capabilities offered by the provider. It is one of the following values:
Value
Description
PCF_16BITMODE | Special 16-bit mode is supported.
PCF_DTRDSR | DTR (Data Terminal Ready) and DSR (Data Set Ready) are supported.
PCF_INTTIMEOUTS | Interval time-outs are supported.
PCF_PARITY_CHECK | Parity checking is supported.
PCF_RLSD | RLSD (Receive Line Signal Detect) is supported.
PCF_RTSCTS | RTS (Request to Send) and CTS (Clear to Send) are supported.
PCF_SETXCHAR | XON and XOFF are supported.
PCF_SPECIALCHARS | Special character support is provided.
PCF_TOTALTIMEOUTS | Total, elapsed, time-outs are supported.
PCF_XONXOFF | XON and XOFF flow control are supported.

dwSettableParams
Indicates the communication parameter that can be changed. It is one of the following values:
Value
Description
SP_BAUD | Baud rate
SP_DATABITS | Data bits
SP_HANDSHAKING | Handshaking (flow control)
SP_PARITY | Parity
SP_PARITY_CHECK | Parity checking
SP_RLSD | Receive Line Signal Detect
SP_STOPBITS | Stop bits

dwSettableBaud
Indicates the baud rates that can be used. For values, see the dwMaxBaud member.
wSettableData
Indicates the number of data bits that can be set. It is one of the following values:
Value
Description
DATABITS_5 | 5 data bits
DATABITS_6 | 6 data bits
DATABITS_7 | 7 data bits
DATABITS_8 | 8 data bits
DATABITS_16 | 16 data bits
DATABITS_16X | Special wide path through serial hardware lines

wSettableStopParity
Indicates the stop bit and parity settings that can be selected. It is one of the following values:
Value
Description
PARITY_EVEN | Even parity
PARITY_MARK | Mark parity
PARITY_NONE | No parity
PARITY_ODD | Odd parity
PARITY_SPACE | Space parity
STOPBITS_10 | 1 stop bit
STOPBITS_15 | 1.5 stop bits
STOPBITS_20 | 2 stop bits

dwCurrentTxQueue
Specifies the size, in bytes, of the driver’s internal output buffer. A value of zero indicates that the value is unavailable.
dwCurrentRxQueue
Specifies the size, in bytes, of the driver’s internal input buffer. A value of zero indicates that the value is unavailable.
dwProvSpec1
Specifies provider-specific data. Applications should ignore this member unless specific data about the data format required by the provider is available.

Set this member to COMMPROP_INITIALIZED before calling the GetCommProperties function to indicate that the wPacketLength member is already valid.

dwProvSpec2
Specifies provider-specific data. Applications should ignore this member unless specific data about the data format required by the provider is available.
wcProvChar
Specifies provider-specific data. Applications should ignore this member unless specific data about the data format required by the provider is available.

Remarks

The contents of the dwProvSpec1, dwProvSpec2, and wcProvChar members depend on the provider subtype; this is specified by the dwProvSubType member.

If the provider subtype is PST_MODEM, these members are used as follows:

Value
Description
dwProvSpec1 | Not used
dwProvSpec2 | Not used
wcProvChar | Contains a MODEMDEVCAPS structure

See Also

GetCommProperties


COMMTIMEOUTS

This structure is used in the SetCommTimeouts and GetCommTimeouts functions to set and query the time-out parameters for a communication device. The parameters determine the behavior of the ReadFile and WriteFile function operations on the device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _COMMTIMEOUTS {
DWORD ReadIntervalTimeout;
DWORD ReadTotalTimeoutMultiplier;
DWORD ReadTotalTimeoutConstant;
DWORD WriteTotalTimeoutMultiplier;
DWORD WriteTotalTimeoutConstant;
} COMMTIMEOUTS,*LPCOMMTIMEOUTS;

Members

ReadIntervalTimeout
Specifies the maximum acceptable time, in milliseconds, to elapse between the arrival of two characters on the communication line. During a ReadFile operation, the time period begins when the first character is received. If the interval between the arrival of any two characters exceeds this amount, the ReadFile operation is completed and any buffered data is returned. A value of zero indicates that interval time-outs are not used.
ReadTotalTimeoutMultiplier
Specifies the multiplier, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is multiplied by the requested number of bytes to be read.
ReadTotalTimeoutConstant
Specifies the constant, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is added to the product of the ReadTotalTimeoutMultiplier member and the requested number of bytes.

A value of zero for both the ReadTotalTimeoutMultiplier and ReadTotalTimeoutConstant members indicates that total time-outs are not used for read operations.

WriteTotalTimeoutMultiplier
Specifies the multiplier, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is multiplied by the number of bytes to be written.
WriteTotalTimeoutConstant
Specifies the constant, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is added to the product of the WriteTotalTimeoutMultiplier member and the number of bytes to be written.

A value of zero for both the WriteTotalTimeoutMultiplier and WriteTotalTimeoutConstant members indicates that total time-outs are not used for write operations.

Remarks

If an application sets ReadIntervalTimeout and ReadTotalTimeoutMultiplier to MAXDWORD and sets ReadTotalTimeoutConstant to a value greater than zero and less than MAXDWORD, one of the following occurs when the ReadFile function is called:

  • If there are any characters in the input buffer, ReadFile returns immediately with the characters in the buffer.
  • If there are no characters in the input buffer, ReadFile waits until a character arrives and then returns immediately.
  • If no characters arrive within the time specified by ReadTotalTimeoutConstant, ReadFile times out.

See Also

GetCommTimeouts, ReadFile, SetCommTimeouts, WriteFile


COMSTAT

This structure contains communication device data. This structure is filled by the ClearCommError function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _COMSTAT {
DWORD fCtsHold : 1;
DWORD fDsrHold : 1;
DWORD fRlsdHold : 1;
DWORD fXoffHold : 1;
DWORD fXoffSent : 1;
DWORD fEof : 1;
DWORD fTxim : 1;
DWORD fReserved : 25;
DWORD cbInQue;
DWORD cbOutQue;
} COMSTAT, *LPCOMSTAT;

Members

fCtsHold
Specifies if the transmission is waiting to receive the CTS (Clear to Send) signal. If this member is TRUE, the transmission is waiting.
fDsrHold
Specifies if the transmission is waiting to receive the DSR (Data Set Ready) signal. If this member is TRUE, the transmission is waiting.
fRlsdHold
Specifies if the transmission is waiting to receive the RLSD (Receive Line Signal Detect) signal. If this member is TRUE, the transmission is waiting.
fXoffHold
Specifies if the transmission is waiting because the XOFF character was received. If this member is TRUE, the transmission is waiting.
fXoffSent
Specifies if the transmission is waiting because the XOFF character was transmitted. If this member is TRUE, the transmission is waiting. Transmission halts when the XOFF character is transmitted to a system that takes the next character as XON, regardless of the actual character.
fEof
Specifies if the End of File (EOF) character has been received. If this member is TRUE, the EOF character has been received.
fTxim
If this member is TRUE, there is a character queued for transmission that has come to the communication device by way of the TransmitCommChar function. The communication device transmits such a character ahead of other characters in the device’s output buffer.
fReserved
Reserved; do not use.
cbInQue
Specifies the number of bytes received by the serial provider, but not yet read by a ReadFile operation.
cbOutQue
Specifies the number of bytes of user data remaining to be transmitted for all write operations. This value will be zero for a nonoverlapped write.

See Also

ClearCommError, ReadFile, TransmitCommChar


CONNECTDLGSTRUCT

This structure is used in the WNetConnectionDialog1 function to specify the browsing dialog box parameters.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct {
DWORD cbStructure;
HWND hwndOwner;
LPNETRESOURCE lpConnRes;
DWORD dwFlags;
DWORD dwDevNum;
} CONNECTDLGSTRUCT, *LPCONNECTDLGSTRUCT;

Members

cbStructure
Size of this structure, in bytes.
hwndOwner
Handle of the owning window.
lpConnRes
Long pointer to a null-terminated string that specifies the path of a network resource to connect to. If the lpRemoteName member of the NETRESOURCE structure is specified, this member is entered into the path field of the dialog box. All other members must be set to NULL except dwType which specifies the type of resources of interest, and must be one of RESOURCETYPE_DISK.
dwFlags
Specifies variations in the dialog display. This member must be set to zero or the following value:
Value
Description
CONNDLG_RO_PATH Instead of enabling the user to type in a path, have a read-only path already inserted. This flag should be set only if lpRemoteName is not NULL, an empty string, and CONNDLG_USE_MRU is not set.

dwDevNum
If the call is successful, this member returns the number of the devices connected to. The value is 1 for A:, 2 for B:, 3 for C:, and so on. If the user made a deviceless connection, the value is 0xFFFFFFFF.

Return Values

WN_SUCCESS indicates that the call is successful and displays the dialog. Typically, this function returns an error only if the dialog box could not be displayed because errors that occur after are reported directly to the user. If the call is successful, dwDevNum contains the number of devices connected to. If the user cancels the dialog box, the function returns 0xFFFFFFFF.

The WN_BAD_VALUE means that CONNDLG_RO_PATH is set and lpRemoteName does not point to a remote name.


DCB

This structure defines the control setting for a serial communications device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _DCB {
DWORD DCBlength;
DWORD BaudRate;
DWORD fBinary:1;
DWORD fParity:1;
DWORD fOutxCtsFlow:1;
DWORD fOutxDsrFlow:1;
DWORD fDtrControl:2;
DWORD fDsrSensitivity:1;
DWORD fTXContinueOnXoff:1;
DWORD fOutX: 1;
DWORD fInX: 1;
DWORD fErrorChar:1;
DWORD fNull:1;
DWORD fRtsControl:2;
DWORD fAbortOnError:1;
DWORD fDummy2:17;
WORD wReserved;
WORD XonLim;
WORD XoffLim;
BYTE ByteSize;
BYTE Parity;
BYTE StopBits;
char XonChar;
char XoffChar;
char ErrorChar;
char EofChar;
char EvtChar;
WORD wReserved1;
} DCB;

Members

DCBlength
Specifies the DCB structure length, in bytes.
BaudRate
Specifies the baud rate at which the communication device operates. It is an actual baud rate value, or one of the following baud rate indexes:
CBR_110 | CBR_19200
CBR_300 | CBR_38400
CBR_600 | CBR_56000
CBR_1200 | CBR_57600
CBR_2400 | CBR_115200
CBR_4800 | CBR_128000
CBR_9600 | CBR_256000
CBR_14400

fBinary
Specifies if binary mode is enabled. The Win32 API does not support nonbinary mode transfers, so this member must be TRUE. Using FALSE will not work.
fParity
Specifies if parity checking is enabled. If this member is TRUE, parity checking is performed and errors are reported.
fOutxCtsFlow
Specifies if the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is turned off, output is suspended until CTS is sent again.
fOutxDsrFlow
Specifies if the DSR (data-set-ready) signal is monitored for output flow control. If this member is TRUE and DSR is turned off, output is suspended until DSR is sent again.
fDtrControl
Specifies the DTR (data-terminal-ready) flow control. This member can be one of the following values:
Value
Description
DTR_CONTROL_DISABLE | Disables the DTR line when the device is opened and leaves it disabled.
DTR_CONTROL_ENABLE | Enables the DTR line when the device is opened and leaves it on.
DTR_CONTROL_HANDSHAKE | Enables DTR handshaking. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.

fDsrSensitivity
Specifies if the communications driver is sensitive to the state of the DSR signal. If this member is TRUE, the driver ignores any bytes received, unless the DSR modem input line is high.
fTXContinueOnXoff
Specifies if transmission stops when the input buffer is full and the driver has transmitted the XoffChar character. If this member is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.
fOutX
Specifies if XON/XOFF flow control is used during transmission. If this member is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.
fInX
Specifies if XON/XOFF flow control is used during reception. If this member is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.
fErrorChar
Specifies if bytes received with parity errors are replaced with the character specified by the ErrorChar member. If this member is TRUE and the fParity member is TRUE, replacement occurs.
fNull
Specifies if null bytes are discarded. If this member is TRUE, null bytes are discarded when received.
fRtsControl
Specifies the RTS (request-to-send) flow control. If this value is zero, the default is RTS_CONTROL_HANDSHAKE. This member can be one of the following values:
Value
Description
RTS_CONTROL_DISABLE | Disables the RTS line when the device is opened and leaves it disabled.
RTS_CONTROL_ENABLE | Enables the RTS line when the device is opened and leaves it on.
RTS_CONTROL_HANDSHAKE | Enables RTS handshaking. The driver raises the RTS line when the “type-ahead” (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.
RTS_CONTROL_TOGGLE | Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low.

fAbortOnError
Specifies if read and write operations are terminated if an error occurs. If this member is TRUE, the driver terminates all read and write operations with an error status if an error occurs. The driver will not accept any further communications operations until the application has acknowledged the error by calling the ClearCommError function.
fDummy2
Reserved; do not use.
wReserved
Not used; set to zero.
XonLim
Specifies the minimum number of bytes accepted in the input buffer before the XON character is sent.
XoffLim
Specifies the maximum number of bytes accepted in the input buffer before the XOFF character is sent. The maximum number of bytes accepted is calculated by subtracting this value from the size, in bytes, of the input buffer.
ByteSize
Specifies the number of bits in the bytes transmitted and received.
Parity
Specifies the parity scheme to be used. It is one of the following values:
Value
Description
EVENPARITY | Even
MARKPARITY | Mark
NOPARITY | No parity
ODDPARITY | Odd
SPACEPARITY | Space

StopBits
Specifies the number of stop bits to be used. It is one of the following values:
Value
Description
ONESTOPBIT | 1 stop bit
ONE5STOPBITS | 1.5 stop bits
TWOSTOPBITS | 2 stop bits

XonChar
Specifies the value of the XON character for both transmission and reception.
XoffChar
Specifies the value of the XOFF character for both transmission and reception.
ErrorChar
Specifies the value of the character used to replace bytes received with a parity error.
EofChar
Specifies the value of the character used to signal the end of data.
EvtChar
Specifies the value of the character used to signal an event.
wReserved1
Reserved; do not use.

Remarks

For device driver developers: the COM_Open function in the sample serial port MDD driver does not support the fErrorChar, fNull, and fAbortOnChar members of the DCB structure. You are expected to add support for this functionality in your PDD layer, if appropriate for your serial port hardware.

The sample serial port MDD driver is found in Public\Common\Oak\Drivers\Serial.

See Also

ClearCommError, EscapeCommFunction, GetCommState, SetCommState


DISCDLGSTRUCT

This structure is used in the WNetDisconnectDialog1 function to describe the required behavior for the disconnect attempt.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _wcesdk_win32_DISCDLGSTRUCT_str{
DWORD cbStructure;
HWND hwndOwner;
LPTSTR lpLocalName;
LPTSTR lpRemoteName;
DWORD dwFlags;
} DISCDLGSTRUCT, *LPDISCDLGSTRUCT;

Members

cbStructure
Size, in bytes, of the DISCDLGSTRUCT structure. This structure is filled in by the caller to indicate the size of the structure passed in.
hwndOwner
Handle to the owning window.
lpRemoteName
Long pointer to the network resource to disconnect. This member can be set to NULL if lpLocalName is specified. When this occurs, the connection to the resource redirected from lpLocalName is disconnected.
lpLocalName
Long pointer to the local name that is redirected to the network resource, such as "myShare.”
dwFlags
Must be set to the following flag:
Value
Description
DISC_NO_FORCE If this value is not set, a forced disconnect will occur—typically because the user has open files. The user will be informed if there are open files to the connection and offered the option to disconnect.


IAS_QUERY

This structure contains data for an Data Access Service (IAS) object obtained from querying a remote device.

At a Glance

Header file: | Af_irda.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct IAS_QUERY {
u_char irdaDeviceID[4];
char irdaClassName[61];
char irdaAttribName[61];
u_short irdaAttribType;
union
{
int irdaAttribInt;
struct
{
int Len;
u_char OctetSeq[1];
u_char Reserved[3];
} irdaAttribOctetSeq;
struct
{
int Len;
u_char CharSet;
u_char UsrStr[1];
u_char Reserved[2];
} irda AttribUsrStr;
} irdaAttribute;
} _IAS_QUERY, *PIAS_QUERY;

Members

irdaDeviceID
Device identifier of the remote device to query.
irdaClassName
Null-terminated string that is the class name for an IAS object. Maximum of 60 characters.
irdaAttribName
Null-terminated string that is the attribute name for an IAS object. Maximum of 60 characters.
irdaAttribType
Attribute type. It is one of the following values:
Value
Description
IAS_ATTRIB_INT | Identifies an integer attribute value.
IAS_ATTRIB_OCTETSEQ | Identifies a binary, or octet, attribute value.
IAS_ATTRIB_STR | Identifies a string attribute value.

irdaAttribInt
32-bit signed integer attribute value.
Len (IAS_ATTRIB_OCTETSEQ)
Length of OctetSeq in octets, or bytes. It is a value from 0 through 1024.
OctetSeq (IAS_ATTRIB_OCTETSEQ)
Binary value to associate with irdaAttribName.
Reserved
Used to DWORD-align the structure.
Len (IAS_ATTRIB_STR)
Length of UsrStr, in octets. It is a value from 0 through 255.
CharSet (IAS_ATTRIB_STR)
Selected character set. It is one of the following values:
LmCharSetASCII | LmCharSetISO_8859_6
LmCharSetISO_8859_1 | LmCharSetISO_8859_7
LmCharSetISO_8859_2 | LmCharSetISO_8859_8
LmCharSetISO_8859_3 | LmCharSetISO_8859_9
LmCharSetISO_8859_4 | LmCharSetUNICODE
LmCharSetISO_8859_5

UsrStr (IAS_ATTRIB_STR)
User string to associate with irdaAttribName.
Reserved
Used to DWORD-align the structure.

Remarks

If either the octet sequence specified in OctetSeq, or the user string specified in UsrStr is associated with irdaAttribName, it is necessary to allocate additional buffer space.

The remote device is queried for the attributes of an IAS object with the specified irdaClassName and irdaAttribName. If an attribute of the specified object is not found on the remote device, then the irdaAttribType is set to IAS_ATTRIB_NO_ATTRIB to indicate that no attribute was found.

The Windows CE irdaClassName and irdaAttribName members have different maximum lengths than their Windows counterparts. The irdaAttribType, Len, and irdaAttribInt members also have different types.

The Windows CE IAS_SET structure does not contain the required buffer space for either the octet sequence attributes or user string sequence attributes. To ensure that the buffer is large enough to query all remote objects, the maximum required buffer is sizeof(IAS_SET) +1024, which is the maximum attribute value length for an octet sequence.


IAS_SET

This structure contains data for creating an Data Access Service (IAS) object.

At a Glance

Header file: | Af_irda.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _IAS_SET {
char irdaClassName[61];
char irdaAttribName[61];
u_short irdaAttribType;
union
{
int irdaAttribInt;
struct
{
int Len;
u_char OctetSeq[1];
u_char Reserved[3];
} irdaAttribOctetSeq;
struct
{
int Len;
u_char CharSet;
u_char UsrStr[1];
u_char Reserved[2];
} irda AttribUsrStr;
} irdaAttribute;
} _IAS_SET, *PIAS_SET;

Members

irdaClassName
Null-terminated string that is the class name for an IAS object. Maximum of 60 characters.
irdaAttribName
Null-terminated string that is the attribute name for an IAS object. Maximum of 60 characters.
irdaAttribType
Attribute type. It is one of the following values:
Value
Description
IAS_ATTRIB_INT | Identifies an integer attribute value.
IAS_ATTRIB_OCTETSEQ | Identifies a binary, or octet, attribute value.
IAS_ATTRIB_STR | Identifies a string attribute value.

irdaAttribInt
32-bit signed integer attribute value.
Len (IAS_ATTRIB_OCTETSEQ)
Length of OctetSeq in octets, or bytes. It is a value from 0 through 1024.
OctetSeq (IAS_ATTRIB_OCTETSEQ)
A binary value to associate with irdaAttribName.
Len (IAS_ATTRIB_STR)
Length of UsrStr, in octets. It is a value from 0 through 255.
CharSet (IAS_ATTRIB_STR)
Selected character set. It is one of the following values:
LmCharSetASCII | LmCharSetISO_8859_5
LmCharSetISO_8859_1 | LmCharSetISO_8859_6
LmCharSetISO_8859_2 | LmCharSetISO_8859_7
LmCharSetISO_8859_3 | LmCharSetISO_8859_8
LmCharSetISO_8859_4 | LmCharSetISO_8859_9

UsrStr (IAS_ATTRIB_STR)
User string to associate with irdaAttribName.
Reserved
Used to DWORD-align the structure.

Remarks

If either the octet sequence specified in OctetSeq or the user string specified in UsrStr is associated with irdaAttribName, it is necessary to allocate additional buffer space.

The Windows CE irdaClassName and irdaAttribName members have different maximum lengths than their Windows counterparts. The irdaAttribType, Len, and irdaAttribInt members also have different types.

The IAS_SET structure does not contain the required buffer space for either the octet sequence attributes or user string sequence attributes. To ensure that the buffer is large enough to query all remote objects, the maximum required buffer is sizeof(IAS_SET) + 1024, which is the maximum attribute value length for an octet sequence.


IN_ADDR

This structure is the IP address component of the SOCKADDR_IN structure. It is in big-endian network byte order.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct in_addr {
union {
struct{
unsigned char s_b1,
s_b2,
s_b3,
s_b4;
} S_un_b;
struct {
unsigned short s_w1,
s_w2;
} S_un_w;
unsigned long S_addr;
} S_un;
} IN_ADDR;

See Also

SOCKADDR_IN


LINECALLINFO

This structure contains call data. This data remains fixed during the call and is obtained with the lineGetCallInfo function. If a part of the structure does change, then a LINE_CALLINFO message is sent to the application indicating which data item has changed. Dynamically changing call data, such as call progress status, is available in the LINECALLSTATUS structure, returned with the lineGetCallStatus function.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linecallinfo_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;

HLINE hLine;
DWORD dwLineDeviceID;
DWORD dwAddressID;

DWORD dwBearerMode;
DWORD dwRate;
DWORD dwMediaMode;

DWORD dwAppSpecific;
DWORD dwCallID;
DWORD dwRelatedCallID;
DWORD dwCallParamFlags;
DWORD dwCallStates;

DWORD dwMonitorDigitModes;
DWORD dwMonitorMediaModes;
LINEDIALPARAMS DialParams;

DWORD dwOrigin;
DWORD dwReason;
DWORD dwCompletionID;
DWORD dwNumOwners;
DWORD dwNumMonitors;

DWORD dwCountryCode;
DWORD dwTrunk;

DWORD dwCallerIDFlags;
DWORD dwCallerIDSize;
DWORD dwCallerIDOffset;
DWORD dwCallerIDNameSize;
DWORD dwCallerIDNameOffset;

DWORD dwCalledIDFlags;
DWORD dwCalledIDSize;
DWORD dwCalledIDOffset;
DWORD dwCalledIDNameSize;
DWORD dwCalledIDNameOffset;

DWORD dwConnectedIDFlags;
DWORD dwConnectedIDSize;
DWORD dwConnectedIDOffset;
DWORD dwConnectedIDNameSize;
DWORD dwConnectedIDNameOffset;

DWORD dwRedirectionIDFlags;
DWORD dwRedirectionIDSize;
DWORD dwRedirectionIDOffset;
DWORD dwRedirectionIDNameSize;
DWORD dwRedirectionIDNameOffset;

DWORD dwRedirectingIDFlags;
DWORD dwRedirectingIDSize;
DWORD dwRedirectingIDOffset;
DWORD dwRedirectingIDNameSize;
DWORD dwRedirectingIDNameOffset;

DWORD dwAppNameSize;
DWORD dwAppNameOffset;
DWORD dwDisplayableAddressSize;
DWORD dwDisplayableAddressOffset;

DWORD dwCalledPartySize;
DWORD dwCalledPartyOffset;

DWORD dwCommentSize;
DWORD dwCommentOffset;

DWORD dwDisplaySize;
DWORD dwDisplayOffset;

DWORD dwUserUserInfoSize;
DWORD dwUserUserInfoOffset;

DWORD dwHighLevelCompSize;
DWORD dwHighLevelCompOffset;

DWORD dwLowLevelCompSize;
DWORD dwLowLevelCompOffset;

DWORD dwChargingInfoSize;
DWORD dwChargingInfoOffset;

DWORD dwTerminalModesSize;
DWORD dwTerminalModesOffset;

DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset;

} LINECALLINFO, FAR *LPLINECALLINFO;

Members

dwTotalSize
Specifies the total size, in bytes, allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure needed to contain all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
hLine
Handle for the line device with which this call is associated.
dwLineDeviceID
Specifies the device identifier of the line device with which this call is associated.
dwAddressID
Specifies the address identifier of the address on the line on which this call exists.
dwBearerMode
Specifies the current bearer mode of the call. It uses the following LINEBEARERMODE_ constants:
Value
Description
LINEBEARERMODE_VOICE | A regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH | Corresponds to the G.711 codec speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE | The multiuse mode, defined by ISDN.
LINEBEARERMODE_DATA | The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA | The alternate transfer of speech or unrestricted data on the same call; ISDN.
LINEBEARERMODE_NONCALLSIGNALING | A non-call-associated signaling connection from the application to the service provider or switch; treated as a media stream by TAPI.
LINEBEARERMODE_PASSTHROUGH | When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 communication functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

dwRate
Specifies the rate of the call data stream, in bits per second (bps).
dwMediaMode
Specifies the media mode of the data stream currently on the call. This is the media mode determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This member is not directly affected by the LINE_MONITORMEDIA messages. It uses the following LINEMEDIAMODE_ constants:
Value
Description
LINEMEDIAMODE_UNKNOWN | A media stream exists, but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an incoming call’s media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE | Speech is detected on the call and the call is treated as an interactive call with a humans at each end.
LINEMEDIAMODE_AUTOMATEDVOICE | Speech is detected on the call and is handled locally by an application.
LINEMEDIAMODE_DATAMODEM | A data modem session is detected on the call.
LINEMEDIAMODE_G3FAX | A group 3 fax is being sent or received on the call.
LINEMEDIAMODE_G4FAX | A group 4 fax is being sent or received on the call.
LINEMEDIAMODE_TDD | A TDD (Telecommunications device for the deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA | Digital data being sent or received on the call.
LINEMEDIAMODE_TELETEX | A teletext session on the call. Teletext is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX | A videotext session on the call. Videotext is one of the telematic services.
LINEMEDIAMODE_TELEX | A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED | A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI | An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW | The media mode of the call is VoiceView.

dwAppSpecific
Uninterpreted by the API implementation and service provider. It can be set by any owner application of this call with the lineSetAppSpecific function.
dwCallID
In some telephony environments, the switch, or service provider can assign a unique identifier to each call. This enables the call to be tracked across transfers, forwards, or other events. The domain of these call identifiers and their scope is service provider-defined. The dwCallID member makes this unique identifier available to the applications.
dwRelatedCallID
Telephony environments that use the call identifier often may find it necessary to relate one call to another. The dwRelatedCallID member can be used by the service provider for this purpose.
dwCallParamFlags
Specifies a collection of call-related parameters when the call is outgoing. These are the same call parameters specified in lineMakeCall, of type LINECALLPARAMFLAGS_. It is one of the following values:
Value
Description
LINECALLPARAMFLAGS_SECURE | The call is currently secure. This flag is also updated if the call is later secured with the lineSecureCall function.
LINECALLPARAMFLAGS_IDLE | The call started out using an idle call.
LINECALLPARAMFLAGS_BLOCKID | The originator identity was concealed (block caller IDpresentation to the remote party).
LINECALLPARAMFLAGS_ORIGOFFHOOK | The originator’s phone was automatically disconnected.
LINECALLPARAMFLAGS_DESTOFFHOOK | The called party’s phone was automatically disconnected.

dwCallStates
Specifies the call states of type LINECALLSTATE_ for which the application can be notified on this call. The dwCallStates member is constant in LINECALLINFO and does not change depending on the call state. It is one of the following values:
Value
Description
LINECALLSTATE_IDLE | The call is idle—no call exists.
LINECALLSTATE_OFFERING | The call is offered to the station signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; the alert is handled by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED | The call was offered and accepted. This indicates to monitoring applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE | The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING | Destination address data, a phone number, is being sent to the switch on the call. The lineGenerateDigits function does not place the line into the dialing state.
LINECALLSTATE_RINGBACK | The call is receiving a ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY | The call is receiving a busy signal. A busy signal indicates that the call cannot be completed—either a circuit (trunk) or the remote party station are in use.
LINECALLSTATE_SPECIALINFO | Special data is sent by the network. Special data is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED | The call has been established, the connection is made. Data is able to flow on the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING | Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD | The call is on hold by the switch.
LINECALLSTATE_CONFERENCED | The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF | The call is currently on hold while being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSF | The call is currently on hold waiting transfer to another number.
LINECALLSTATE_DISCONNECTED | The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN | The call state is not known. This may be due to limitations of the call progress detection implementation.

dwMonitorDigitModes
Specifies the various digit modes of type LINEDIGITMODE_ for which monitoring is currently enabled. It is one of the following values:
Value
Description
LINEDIGITMODE_PULSE | Uses pulse or rotary for digit signaling.
LINEDIGITMODE_DTMF | Uses DTMF tones for digit signaling.
LINEDIGITMODE_DTMFEND | Uses DTMF tones for digit detection, and also detects the down edges.

dwMonitorMediaModes
Specifies the various media modes for which monitoring is currently enabled, of type LINEMEDIAMODE_. It is one of the following values:
Value
Description
LINEMEDIAMODE_INTERACTIVEVOICE | The presence of speech on the call and the call is treated as an interactive call with a human on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE | The presence of speech on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM | A data modem session on the call.
LINEMEDIAMODE_G3FAX | A group 3 fax is being sent or received on the call.
LINEMEDIAMODE_G4FAX | A group 4 fax is being sent or received on the call.
LINEMEDIAMODE_TDD | A TDD (Telecommunications device for the deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA | Digital data is being sent or received on the call.
LINEMEDIAMODE_TELETEX | A teletext session on the call. Teletext is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX | A videotext session on the call. Videotext is one of the telematic services.
LINEMEDIAMODE_TELEX | A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED | A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI | An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW | The media mode of the call is VoiceView.

DialParams
The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either lineMakeCall or lineSetCallParams, their values are the same as the defaults used in the LINEDEVCAPS structure.
dwOrigin
Identifies where the call originated from. It uses the following LINECALLORIGIN_ constants:
Value
Description
LINECALLORIGIN_OUTBOUND | The call is outgoing.
LINECALLORIGIN_INTERNAL | The call is incoming and originated internally.
LINECALLORIGIN_EXTERNAL | The call is incoming and originated externally.
LINECALLORIGIN_UNKNOWN | The call is an incoming call and its origin is currently unknown, but may be identified later.
LINECALLORIGIN_UNAVAIL | The call is an incoming call. Its origin is not available and will never be identified.
LINECALLORIGIN_CONFERENCE | The call handle is for a conference call, that is, the application’s connection to the conference bridge in the switch.

dwReason
Specifies the reason why the call occurred. It uses the following LINECALLREASON_ constants:
Value
Description
LINECALLREASON_DIRECT | The call is a direct call.
LINECALLREASON_FWDBUSY | The call was forwarded from another extension that was busy at the time of the call.
LINECALLREASON_FWDNOANSWER | The call was forwarded from another extension that did not answer the call after some number of rings.
LINECALLREASON_FWDUNCOND | The call was forwarded unconditionally from another number.
LINECALLREASON_PICKUP | The call was picked up from another extension.
LINECALLREASON_UNPARK | The call was retrieved as a parked call.
LINECALLREASON_REDIRECT | The call was redirected to this station.
LINECALLREASON_CALLCOMPLETION | The call was the result of a call completion request.
LINECALLREASON_TRANSFER | The call has been transferred from another number. Party identifier data may identify the caller and where the call was transferred from.
LINECALLREASON_REMINDER | The call is a reminder that the user has a call parked or on hold for a potentially long time.
LINECALLREASON_UNKNOWN | The reason for the call is currently unknown, but may be identified later.
LINECALLREASON_UNAVAIL | The reason for the call is unavailable and cannot be identified later.

dwCompletionID
Specifies the completion identifier for the incoming call if it is the result of a completion request that terminates. This identifier is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.
dwNumOwners
Specifies the number of application modules with different call handles with owner privilege for the call.
dwNumMonitors
Specifies the number of application modules with different call handles with monitor privilege for the call.
dwCountryCode
Specifies the country code of the destination party. Zero if unknown.
dwTrunk
Specifies the number of the trunk over which the call is routed. This member is used for both incoming and outgoing calls. The dwTrunk member should be set to 0xFFFFFFFF if it is unknown.
dwCallerIDFlags
Determines the validity and content of the caller party identifier data. The caller is the originator of the call. It uses the following LINECALLPARTYID_* constants:
Value
Description
LINECALLPARTYID_BLOCKED | Caller identifier data for the call has been blocked by the caller, but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA | Caller identifier data for the call is not available because it is not propagated completely by the network.
LINECALLPARTYID_NAME | The caller identifier data for the call is the caller’s name taken from a table maintained inside the switch. It is provided in the caller identifier name field.
LINECALLPARTYID_ADDRESS | The caller identifier data for the call is the caller’s number and is provided in the caller identifier field.
LINECALLPARTYID_PARTIAL | Caller identifier data for the call is valid, but is limited to partial number data.
LINECALLPARTYID_UNKNOWN | Caller identifier data is currently unknown, but it may be identified later.
LINECALLPARTYID_UNAVAIL | Caller identifier data is unavailable and cannot be identified later.

dwCallerIDSize
dwCallerIDOffset
Specify the size, in bytes, of the field that contains the caller identifier number data, and the offset, in bytes, from the beginning of this data structure.
dwCallerIDNameSize
dwCallerIDNameOffset
Specify the size, in bytes, of the field that contains the caller party identifier name data, and the offset, in bytes, from the beginning of this data structure.
dwCalledIDFlags
Determines the validity and content of the called-party identifier data. The called party corresponds to the originally addressed party. It uses the following LINECALLPARTYID_ constants:
Value
Description
LINECALLPARTYID_BLOCKED | Called identifier data for the call has been blocked by the caller, but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA | Caller identifier data for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME | The called identifier data for the call is the caller’s name (from a table maintained inside the switch). It is provided in the called identifier name field.
LINECALLPARTYID_ADDRESS | The called identifier data for the call is the caller’s number and is provided in the called identifier field.
LINECALLPARTYID_PARTIAL | Called identifier data for the call is valid, but is limited to partial number data.
LINECALLPARTYID_UNKNOWN | Called identifier data is currently unknown, but it may be identified later.
LINECALLPARTYID_UNAVAIL | Called identifier data is unavailable and cannot be identified later.

dwCalledIDSize
dwCalledIDOffset
Specify the size, in bytes, of the field that contains the called-party identifier number data, and the offset, in bytes, from the beginning of this data structure.
dwCalledIDNameSize
dwCalledIDNameOffset
Specify the size, in bytes, of the field that contains the called-party identifier name data, and the offset, in bytes, from the beginning of this data structure.
dwConnectedIDFlags
Determines the validity and content of the connected party identifier data. The connected party is the party that was actually connected to. This may be different from the called-party identifier if the call was diverted. It uses the following LINECALLPARTYID_ constants:
Value
Description
LINECALLPARTYID_BLOCKED | Connected party identifier data for the call has been blocked by the caller, but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA | Connected identifier data for the call is not available as it is not propagated all the way by the network.
LINECALLPARTYID_NAME | The connected party identifier data for the call is the caller’s name (from a table maintained inside the switch). It is provided in the connected identifier name field.
LINECALLPARTYID_ADDRESS | The connected party identifier data for the call is the caller’s number and is provided in the connected identifier field.
LINECALLPARTYID_PARTIAL | Connected party identifier data for the call is valid, but is limited to partial number data.
LINECALLPARTYID_UNKNOWN | Connected party identifier data is currently unknown, but it may be identified later.
LINECALLPARTYID_UNAVAIL | Connected party identifier data is unavailable and cannot be identified later.

dwConnectedIDSize
dwConnectedIDOffset
Specify the size, in bytes, of the field that contains the connected party identifier number data, and the offset, in bytes, from the beginning of this data structure.
dwConnectedIDNameSize
dwConnectedIDNameOffset
Specify the size, in bytes, of the field that contains the connected party identifier name data, and the offset, in bytes, from the beginning of this data structure.
dwRedirectionIDFlags
Determines the validity and content of the redirection party identifier data. The redirection party identifies to the calling user the number toward which diversion was invoked. It uses the following LINECALLPARTYID_ constants:
Value
Description
LINECALLPARTYID_BLOCKED | Redirection party identifier data for the call has been blocked by the caller, but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA | Redirection identifier data for the call is not available because it is not propagated all the along the network.
LINECALLPARTYID_NAME | The redirection party identifier data for the call is the caller’s name (from a table maintained inside the switch). It is provided in the redirection identifier name field.
LINECALLPARTYID_ADDRESS | The redirection party identifier data for the call is the caller’s number and is provided in the redirection identifier field.
LINECALLPARTYID_PARTIAL | Redirection party identifier data for the call is valid, but is limited to partial number data.
LINECALLPARTYID_UNKNOWN | Redirection identifier data is currently unknown, but it may be identified later.
LINECALLPARTYID_UNAVAIL | Redirection identifier data is unavailable and cannot be identified later.

dwRedirectionIDSize
dwRedirectionIDOffset
Specify the size, in bytes, of the field that contains the redirection party identifier number data, and the offset, in bytes, from the beginning of this data structure.
dwRedirectionIDNameSize
dwRedirectionIDNameOffset
Specify the size, in bytes, of the field that contains the redirection party identifier name data, and the offset, in bytes, from the beginning of this data structure.
dwRedirectingIDFlags
Determines the validity and content of the redirecting party identifier data. The party that received the call identifies the new destination number or whatever data is detected to the call originator. It uses the following LINECALLPARTYID_* constants:
Value
Description
LINECALLPARTYID_BLOCKED | Redirecting party identifier data for the call has been blocked by the caller, but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA | Redirecting identifier data for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME | The redirecting party identifier data for the call is the caller’s name (from a table maintained inside the switch). It is provided in the redirecting identifier name field.
LINECALLPARTYID_ADDRESS | The redirecting party identifier data for the call is the caller’s number and is provided in the redirecting identifier field.
LINECALLPARTYID_PARTIAL | Redirecting party identifier data for the call is valid, but is limited to partial number data.
LINECALLPARTYID_UNKNOWN | Redirecting identifier data is currently unknown, but it may be identified later.
LINECALLPARTYID_UNAVAIL | Redirecting identifier data is unavailable and cannot be identified later.

dwRedirectingIDSize
dwRedirectingIDOffset
Specify the size, in bytes, of the field that contains the redirecting party identifier number data, and the offset, in bytes, from the beginning of this data structure.
dwRedirectingIDNameSize
dwRedirectingIDNameOffset
Specify the size, in bytes, of the field that contains the redirecting party identifier name data, and the offset, in bytes, from the beginning of this data structure.
dwAppNameSize
dwAppNameOffset
Specify the size, in bytes, and the offset, in bytes, from the beginning of this data structure of the field that holds the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify in lineInitializeEx. If the application specifies no such name, then the application’s module file name is used instead.
dwDisplayableAddressSize
dwDisplayableAddressOffset
Specify the displayable string is used for logging purposes. The data is obtained from LINECALLPARAMS for functions that initiate calls. The lineTranslateAddress function returns appropriate data to be placed in this member in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
Specify the size, in bytes, of the field that holds a user-friendly description of the called party, and the offset, in bytes, from the beginning of this data structure. This data can be specified with lineMakeCall and can be optionally specified in the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.
dwCommentSize
dwCommentOffset
Specify the size, in bytes, of the field that holds a comment about the call provided by the application that originated the call using lineMakeCall, and the offset, in bytes, from the beginning of this data structure. This data can be optionally specified in the lpCallParams parameter whenever a new call is established.
dwDisplaySize
dwDisplayOffset
Specify the size, in bytes, of the field that holds raw display data, and the offset, in bytes, from the beginning of this data structure. Depending on the telephony environment, a service provider may extract functional data from this member pair for formatting and presentation most appropriate for this telephony configuration.
dwUserUserInfoSize
dwUserUserInfoOffset
Specify the size, in bytes, of the field that holds user-user data, and the offset, in bytes, from the beginning of this data structure The protocol discriminator field for the user-user data, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset, and is accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
Specify the size, in bytes, of the field that holds high-level compatibility data, and the offset, in bytes, from the beginning of this data structure. The format of this data is specified by other standards (ISDN Q.931).
dwLowLevelCompSize
dwLowLevelCompOffset
Specify the size, in bytes, of the field that holds low-level compatibility data, and the offset, in bytes, from the beginning of this data structure. The format of this data is specified by other standards (ISDN Q.931).
dwChargingInfoSize
dwChargingInfoOffset
Specify the size, in bytes, of the field that holds charging data, and the offset, in bytes, from the beginning of this data structure. The format of this data is specified by other standards (ISDN Q.931).
dwTerminalModesSize
dwTerminalModesOffset
Specify the size, in bytes, of the variably sized device field that contains an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. The set of LINETERMMODE_ constants is indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this call’s media stream. The following values are predefined:
Value
Description
LINETERMMODE_LAMPS | Lamp events sent from the line to the terminal.
LINETERMMODE_BUTTONS | Button-press events sent from the terminal to the line.
LINETERMMODE_DISPLAY | Display data sent from the line to the terminal.
LINETERMMODE_RINGER | Ringer-control data sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH | Hookswitch event sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE | The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call’s media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE | The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call’s media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT | The bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both the unidirectional channels of a call’s media stream cannot be controlled independently.

dwDevSpecificSize
dwDevSpecificOffset
Specify the size, in bytes, of the field that holds device-specific data., and the offset, in bytes, from the beginning of this data structure.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The LINECALLINFO data structure contains relatively fixed data about a call. This structure is returned with lineGetCallInfo. When data items in this data structure have changed, a LINE_CALLINFO message is sent to the application. A parameter to this message is the data item or field that changed.

The members dwCallTreatment through dwReceivingFlowspecOffset are available only to applications that open the line device with an API version of 2.0 or later.

Note The preferred format for specification of the contents of the dwCallID member and the other five similar members (dwCallerIDFlag, dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, and dwCallerIDNameOffset) is the TAPI canonical number format. For example, a ICLID of “4258828080” received from the switch should be converted to “+1 (425) 8828080” before being placed in the LINECALLINFO structure. This standardized format facilitates searching of databases and callback functions implemented in applications. ¤


LINECALLPARAMS

This structure describes parameters supplied when making calls using the lineMakeCall function. The LINECALLPARAMS structure is also used as a parameter in other operations.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linecallparams_tag {
DWORD dwTotalSize;

DWORD dwBearerMode;
DWORD dwMinRate;
DWORD dwMaxRate;
DWORD dwMediaMode;

DWORD dwCallParamFlags;
DWORD dwAddressMode;
DWORD dwAddressID;

LINEDIALPARAMS DialParams;

DWORD dwOrigAddressSize;
DWORD dwOrigAddressOffset;

DWORD dwDisplayableAddressSize;
DWORD dwDisplayableAddressOffset;

DWORD dwCalledPartySize;
DWORD dwCalledPartyOffset;

DWORD dwCommentSize;
DWORD dwCommentOffset;

DWORD dwUserUserInfoSize;
DWORD dwUserUserInfoOffset;

DWORD dwHighLevelCompSize;
DWORD dwHighLevelCompOffset;

DWORD dwLowLevelCompSize;
DWORD dwLowLevelCompOffset;

DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset;
DWORD dwPredictiveAutoTransferStates;
DWORD dwTargetAddressSize;
DWORD dwTargetAddressOffset;
DWORD dwSendingFlowspecSize;
DWORD dwSendingFlowspecOffset;
DWORD dwReceivingFlowspecSize;
DWORD dwReceivingFlowspecOffset;
DWORD dwDeviceClassSize;
DWORD dwDeviceClassOffset;
DWORD dwDeviceConfigSize;
DWORD dwDeviceConfigOffset;
DWORD dwCallDataSize;
DWORD dwCallDataOffset;
DWORD dwNoAnswerTimeout;
DWORD dwCallingPartyIDSize;
DWORD dwCallingPartyIDOffset;
} LINECALLPARAMS, FAR *LPLINECALLPARAMS;

Members

dwTotalSize
Specifies the total size, in bytes, allocated to this data structure. This size should be big enough to hold all the fixed and variably sized portions of this data structure.
dwBearerMode
Specifies the bearer mode for the call. If dwBearerMode is set to any value except LINEBEARERMODE_PASSTHROUGH, the call will attempt to complete if or not that bearer mode is supported on the line being accessed. This member uses the following LINEBEARERMODE_ constants:
Value
Description
LINEBEARERMODE_VOICE | This is a regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH | Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE | The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA | The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA | The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING | Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a “media stream” by the Telephony API).
LINEBEARERMODE_PASSTHROUGH | When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

If dwBearerMode is zero, the default value is LINEBEARERMODE_VOICE.

DwMinRate
dwMaxRate
Unsupported; set to zero.
dwMediaMode
Specifies the expected media mode of the call. This member uses the following LINEMEDIAMODE_ constants:
Value
Description
LINEMEDIAMODE_UNKNOWN | A media stream exists, but its mode is not known. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an incoming call’s media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE | The presence of speech on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE | The presence of speech on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM | A datamodem session on the call.
LINEMEDIAMODE_G3FAX | A group 3 fax is being sent or received on the call.
LINEMEDIAMODE_G4FAX | A group 4 fax is being sent or received on the call.
LINEMEDIAMODE_TDD | A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA | Digital data is being sent or received on the call.
LINEMEDIAMODE_TELETEX | A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX | A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX | A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED | A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI | An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW | The media mode of the call is VoiceView.

If dwMediaMode is zero, the default value is LINEMEDIAMODE_INTERACTIVEVOICE.

dwCallParamFlags
Specifies a collection of Boolean call-setup parameters. This member uses the following LINECALLPARAMFLAGS_ constants:
Value
Description
LINECALLPARAMFLAGS_SECURE | The call should be set up as secure.
LINECALLPARAMFLAGS_IDLE | The call should get an idle call appearance.
LINECALLPARAMFLAGS_BLOCKID | The originator identity should be concealed (block caller identifier).
LINECALLPARAMFLAGS_ORIGOFFHOOK | The originator’s phone should be automatically taken offhook.
LINECALLPARAMFLAGS_DESTOFFHOOK | The called party’s phone should be automatically taken offhook.

dwAddressMode
Specifies the mode by which the originating address is specified. The dwAddressMode member cannot be LINEADDRESSMODE_ADDRESSID for the lineOpen function call. This member uses the following LINEADDRESSMODE_ constants:
Value
Description
LINEADDRESSMODE_ADDRESSID | The address is specified with a small integer in the range zero to dwNumAddresses minus one, where dwNumAddresses is the value in the line’s LINEDEVCAPS structure. The selected address is specified in the dwAddressID member.
LINEADDRESSMODE_DIALABLEADDR | The address is specified with its dialable address. The address is contained in the dwOrigAddressSize and dwOrigAddressOffset field. If dwAddressMode is zero, the default value is LINEADDRESSMODE_ADDRESSID.

dwAddressID
Specifies the address identifier of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID.
DialParams
Unsupported; set to zero.
DwOrigAddressSize
dwOrigAddressOffset
Specify the size, in bytes, of the field holding the originating address, and the offset, in bytes, from the beginning of this data structure. The format of this address is dependent on the dwAddressMode member.
dwDisplayableAddressSize
dwDisplayableAddressOffset
Specify the displayable string is used for logging purposes. The content of these members is recorded in the dwDisplayableAddressOffset and dwDisplayableAddressSize members of the call’s LINECALLINFO message. The lineTranslateAddress function returns appropriate data to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
Specify the size, in bytes, of the field that holds called-party data, and the offset, in bytes, from the beginning of this data structure. This data can be specified by the application that makes the call and is made available in the call’s data structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.
dwCommentSize
dwCommentOffset
Specify the size, in bytes, of the field that holds comments about the call, and the offset, in bytes, from the beginning of this data structure. This data can be specified by the application that makes the call and is made available in the call’s data structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.
dwUserUserInfoSize
dwUserUserInfoOffset
Specify the size, in bytes, of the field that holds user-user data, and the offset, in bytes, from the beginning of this data structure. The protocol discriminator field for the user-user data, if required, should appear as the first byte of the data pointed to by dwUserUserInfoOffset, and must be accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
Specify the size, in bytes, of the field that holds high-level compatibility data, and the offset, in bytes, from the beginning of this data structure.
dwLowLevelCompSize
dwLowLevelCompOffset
Specify the size, in bytes, of the field that holds low-level compatibility data, and the offset, in bytes, from the beginning of this data structure.
dwDevSpecificSize
dwDevSpecificOffset
Specify the size, in bytes, of the field that holds device-specific data, and the offset, in bytes, from the beginning of this data structure.
dwPredictiveAutoTransferStates
The LINECALLSTATE_ values, entry into which cause the call to be blind-transferred to the specified target address. Set to zero if automatic transfer is not desired.
dwTargetAddressSize
dwTargetAddressOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of a string specifying the target dialable address (not dwAddressID); used in the case of certain automatic actions. In the case of predictive dialing, specifies the address to which the call should be automatically transferred. Set to zero if automatic transfer is not desired. In the case of a No Hold Conference, specifies the address that should be added to the call. In the case of a One Step Transfer, specifies the address to dial on the consultation call.
dwSendingFlowspecSize
dwSendingFlowspecOffset
The total size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset
The total size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwDeviceClassSize
dwDeviceClassOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of a NULL-terminated ASCII string (the size includes the NULL) that indicates the device class of the device whose configuration is specified in DeviceConfig. Valid device class strings are the same as those specified for the lineGetID function.
dwDeviceConfigSize
dwDeviceConfigOffset
The number of bytes and offset from the beginning of LINECALLPARAMS of the opaque configuration data structure pointed to by dwDevConfigOffset. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is zero, the default device configuration is used. This enables the application to set the device configuration before the call is initiated.
dwCallDataSize
dwCallDataOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of the application-settable call data to be initially attached to the call.
dwNoAnswerTimeout
The number of seconds, after the completion of dialing, that the call should wait in the PROCEEDING or RINGBACK state, before abandoned by the service provider with a LINECALLSTATE_DISCONNECTED and LINEDISCONNECTMODE_NOANSWER. A value of 0 indicates that the application does not desire automatic call abandonment.
dwCallingPartyIDSize
dwCallingPartyIDOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of a NULL-terminated ASCII string (the size includes the NULL) that specifies the identity of the party placing the call. If the content of the identifier is acceptable and a path is available, the service provider passes the identifier along to the called party to indicate the identity of the calling party.

Remarks

Device-specific extensions should use the dwDevSpecificSize and dwDevSpecificOffset members of this structure.

This structure is used as a parameter to lineMakeCall when setting up a call. Its fields enable the application to specify the quality of service requested from the network as well as a variety of ISDN call-setup parameters. If no LINECALLPARAMS structure is supplied to lineMakeCall, a default POTS voice-grade call is requested with the default values listed above.

Note The members dwOrigAddressSize through dwDevSpecificOffset are ignored when an lpCallParams parameter is specified with the lineOpen function.

For Windows CE versions 1.0 through 2.12, the following members are not supported:

dwUUISendUserUserInfoSize | dwDeviceClassSize
dwMinRate | dwDeviceClassOffset
dwMaxRate | dwDeviceConfigSize
dwPredictiveAutoTransferStates | dwDeviceConfigOffset
dwTargetAddressSize | dwCallDataSize
dwTargetAddressOffset | dwCallDataOffset
dwSendingFlowspecSize | dwNoAnswerTimeout
dwSendingFlowspecOffset | dwCallingPartyIDSize
dwReceivingFlowspecSize | dwCallingPartyIDOffset
dwReceivingFlowspecOffset |


LINEDEVCAPS

This structure describes the capabilities of a line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linedevcaps_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;

DWORD dwProviderInfoSize;
DWORD dwProviderInfoOffset;

DWORD dwSwitchInfoSize;
DWORD dwSwitchInfoOffset;

DWORD dwPermanentLineID;
DWORD dwLineNameSize;
DWORD dwLineNameOffset;
DWORD dwStringFormat;
DWORD dwAddressModes;
DWORD dwNumAddresses;
DWORD dwBearerModes;
DWORD dwMaxRate;
DWORD dwMediaModes;

DWORD dwGenerateToneModes;
DWORD dwGenerateToneMaxNumFreq;
DWORD dwGenerateDigitModes;
DWORD dwMonitorToneMaxNumFreq;
DWORD dwMonitorToneMaxNumEntries;
DWORD dwMonitorDigitModes;
DWORD dwGatherDigitsMinTimeout;
DWORD dwGatherDigitsMaxTimeout;

DWORD dwMedCtlDigitMaxListSize;
DWORD dwMedCtlMediaMaxListSize;
DWORD dwMedCtlToneMaxListSize;
DWORD dwMedCtlCallStateMaxListSize;

DWORD dwDevCapFlags;
DWORD dwMaxNumActiveCalls;
DWORD dwAnswerMode;
DWORD dwRingModes;
DWORD dwLineStates;

DWORD dwUUIAcceptSize;
DWORD dwUUIAnswerSize;
DWORD dwUUIMakeCallSize;
DWORD dwUUIDropSize;
DWORD dwUUISendUserUserInfoSize;
DWORD dwUUICallInfoSize;

LINEDIALPARAMS MinDialParams;
LINEDIALPARAMS MaxDialParams;
LINEDIALPARAMS DefaultDialParams;

DWORD dwNumTerminals;
DWORD dwTerminalCapsSize;
DWORD dwTerminalCapsOffset;
DWORD dwTerminalTextEntrySize;
DWORD dwTerminalTextSize;
DWORD dwTerminalTextOffset;

DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset

DWORD dwLineFeatures;

DWORD dwSettableDevStatus;
DWORD dwDeviceClassesSize;
DWORD dwDeviceClassesOffset;
} LINEDEVCAPS, *LPLINEDEVCAPS;

Members

dwTotalSize
Specifies the total size, in bytes, allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure that is needed to hold all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
dwProviderInfoSize
dwProviderInfoOffset
Specify the size, in bytes, of the field that contains service provider data, and the offset, in bytes, from the beginning of this data structure. The dwProviderInfoSize/Offset member is intended to provide data about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This data can be useful when a user needs to call customer service with problems regarding the provider.
dwSwitchInfoSize
dwSwitchInfoOffset
Specify the size, in bytes, of the variably sized device field that contains switch data, and the offset, in bytes, from the beginning of this data structure. The dwSwitchInfoSize/Offset member is intended to provide data about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This data can be useful when a user needs to call customer service with problems regarding the switch.
dwPermanentLineID
Unsupported; set to zero.
dwLineNameSize
dwLineNameOffset
Specify the size, in bytes, of the variably sized device field that contains a user configurable name for this line device, and the offset, in bytes, from the beginning of this data structure. This name can be configured by the user when configuring the line device’s service provider, and is provided for the user’s convenience.
dwStringFormat
Specifies the string format used with this line device. This member uses the following STRINGFORMAT_ constants:
Value
Description
STRINGFORMAT_ASCII | The ASCII string format using one byte per character.
STRINGFORMAT_DBCS | The DBCS string format using one or two bytes per character.
STRINGFORMAT_UNICODE | The Unicode string format using two bytes per character.

dwAddressModes
Specifies the mode by which the originating address is specified. This member uses the LINEADDRESSMODE_ constants.
dwNumAddresses
Specifies the number of addresses associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value indicated by dwNumAddresses.
dwBearerModes
Flag array that indicates the different bearer modes that the address is able to support. This member uses the following LINEBEARERMODE_ constants:
Value
Description
LINEBEARERMODE_VOICE | A regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH | Corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE | The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA | The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA | The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING | Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a “media stream” by the Telephony API).
LINEBEARERMODE_PASSTHROUGH | When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 communications functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

dwMaxRate
Contains the maximum data rate in bits per second for data exchange over the call.
dwMediaModes
Flag array that indicates the different media modes the address is able to support. This member uses the following LINEMEDIAMODE_ constants:
Value
Description
LINEMEDIAMODE_UNKNOWN | A media stream exists, but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an incoming call’s media mode may be unknown until after the call has been answered and the media stream filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE | The presence of speech on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE | The presence of speech on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM | A data modem session on the call.
LINEMEDIAMODE_G3FAX | A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_G4FAX | A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_TDD | A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA | Digital data being transmitted over the call.
LINEMEDIAMODE_TELETEX | A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX | A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX | A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED | A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI | An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW | The media mode of the call is VoiceView.

dwGenerateToneModes;
dwGenerateToneMaxNumFreq;
dwGenerateDigitModes;
dwMonitorToneMaxNumFreq;
dwMonitorToneMaxNumEntries;
dwMonitorDigitModes;
dwGatherDigitsMinTimeout;
dwGatherDigitsMaxTimeout;
Unsupported; set to zero.
dwMedCtlDigitMaxListSize
Unsupported; set to zero.
dwMedCtlMediaMaxListSize
Contains the maximum number of entries that can be specified in the media list.
dwMedCtlToneMaxListSize
Unsupported; set to zero.
dwMedCtlCallStateMaxListSize
Contains the maximum number of entries that can be specified in the call state list.
dwDevCapFlags
Specifies various Boolean device capabilities. This member uses the following LINEDEVCAPFLAGS_ constants:
Value
Description
LINEDEVCAPFLAGS_CROSSADDRCONF | Specifies if calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_HIGHLEVCOMP | Specifies if high-level compatibility data elements are supported on this line.
LINEDEVCAPFLAGS_LOWLEVCOMP | Specifies if low-level compatibility data elements are supported on this line.
LINEDEVCAPFLAGS_MEDIACONTROL | Specifies if media control operations are available for calls at this line.
LINEDEVCAPFLAGS_MULTIPLEADDR | Specifies if lineMakeCall is able to deal with multiple addresses at once (such as for inverse multiplexing).
LINEDEVCAPFLAGS_CLOSEDROP | Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external device(s). A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive. For example, if an analog line has the computer and phone set both connect directly to them in a party-line configuration, the offhook phone automatically keeps the call active even after the computer powers down.
Applications should check this flag to determine if to warn the user (with an OK/Cancel dialog box) that active calls will be lost.
LINEDEVCAPFLAGS_DIALBILLING
LINEDEVCAPFLAGS_DIALQUIET
LINEDEVCAPFLAGS_DIALDIALTONE 		These flags indicate if the “$”, “@”, or “W” dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The “?” (prompt user to continue dialing) is never supported by a line device. These flags enable an application to determine “up front” which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters, or passing the “raw” string from lineTranslateAddress directly to the provider as part of lineMakeCall and letting the function generate an error to tell it which unsupported modifier occurs first in the string.

dwMaxNumActiveCalls
Provides the maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls may be lower if higher bandwidth calls have been established on the line.
dwAnswerMode
Specifies the effect on the active call when answering another offering call on a line device. This member uses the following LINEANSWERMODE_ constants:
Value
Description
LINEANSWERMODE_NONE | Answering another call on the same line has no effect on the existing active call(s) on the line.
LINEANSWERMODE_DROP | The currently active call is automatically dropped.
LINEANSWERMODE_HOLD | The currently active call is automatically placed on hold.

dwRingModes
Contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.
dwLineStates
Specifies the different line status components for which the application may be notified in a LINE_LINEDEVSTATE message on this line. This member uses the following LINEDEVSTATE_ constants:
Value
Description
LINEDEVSTATE_OTHER | Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING | The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED | The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED | This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON | The “message waiting” indicator is turned on.
LINEDEVSTATE_MSGWAITOFF | The “message waiting” indicator is turned off.
LINEDEVSTATE_NUMCOMPLETIONS | The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_INSERVICE | The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE | The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE | Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN | The line has been opened.
LINEDEVSTATE_CLOSE | The line has been closed.
LINEDEVSTATE_NUMCALLS | The number of calls on the line device has changed.
LINEDEVSTATE_TERMINALS | The terminal settings have changed.
LINEDEVSTATE_ROAMMODE | The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY | The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL | The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC | The line’s device-specific data has changed.
LINEDEVSTATE_REINIT | Items have changed in the configuration of line devices. To become aware of these changes (such as for the appearance of new line devices), the application should reinitialize its use of TAPI. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK | The locked status of the line device has changed.
LINEDEVSTATE_CAPSCHANGE | Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated data.
LINEDEVSTATE_CONFIGCHANGE | Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, may use lineGetDevConfig to read the updated data. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
LINEDEVSTATE_TRANSLATECHANGE | Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated data.
LINEDEVSTATE_COMPLCANCEL | Indicates that the call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
LINEDEVSTATE_REMOVED | Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.

dwUUIAcceptSize
Specifies the maximum size of user-user data that can be sent during a call accept.
dwUUIAnswerSize
Specifies the maximum size of user-user data that can be sent during a call answer.
dwUUIMakeCallSize
Specifies the maximum size of user-user data that can be sent during a make call.
dwUUIDropSize
Specifies the maximum size of user-user data that can be sent during a call drop.
dwUUISendUserUserInfoSize
Unsupported; set to zero.
dwUUICallInfoSize
Specifies the maximum size of user-user data that can be received in the LINECALLINFO structure.
MinDialParams
MaxDialParams
Unsupported; set to zero
DefaultDialParams
Unsupported; set to zero.
dwNumTerminals
dwTerminalCapsSize
dwTerminalCapsOffset
dwTerminalTextEntrySize
dwTerminalTextSize
dwTerminalTextOffset
Unsupported; set to zero.
dwDevSpecificSize
dwDevSpecificOffset
Specify the size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwLineFeatures
Specifies the features available for this line using the LINEFEATURE_ constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This member enables an application to discover which line features can be (and which can never be) supported by the device.
dwSettableDevStatus
The LINEDEVSTATUS_ values that can be modified using the lineSetLineDevStatus function.
dwDeviceClassesSize
dwDeviceClassesOffset
Length in bytes and offset from the beginning of LINEDEVCAPS of a string consisting of the device class identifiers supported on one or more addresses on this line for use with lineGetID, separated by NULL characters; the last identifier in the list is followed by two NULL characters.

Remarks

Device-specific extensions should use the dwDevSpecificSize and dwDevSpecificOffset members of this structure.

Older applications are compiled without new members in the LINEDEVCAPS structure, and using a SIZEOF LINEDEVCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetDevCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member less than the size of the fixed portion of the structure as defined in the specified dwAPIVersion, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetDevCaps, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New applications must be cognizant of the API version negotiated, and not examine the contents of members in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

If the LINEBEARERMODE_DATA bit is set in the dwBearerModes member, the dwMaxRate member indicates the maximum rate of digital transmission on the bearer channel. The dwMaxRate member of the LINEDEVCAPS structure can contain valid values even if the dwBearerModes member of the LINEDEVCAPS structure is not set to LINEBEARERMODE_DATA.

If LINEBEARERMODE_DATA is not set in dwBearerModes, but the LINEBEARERMODE_VOICE value is set and the LINEMEDIAMODE_DATAMODEM value is set in the dwMediaModes member, the dwMaxRate member indicates the maximum SYNCHRONOUS (DCE) bit rate on the phone line for the attached modem or functional equivalent. For example, if the modem’s fastest modulation speed is V.32bis at 14,400bps, dwMaxRate equals 14400. This is not the fastest DTE port rate (which would most likely be 38400, 57600, or 115200), but the fastest bit rate the modem supports on the phone line.

The application must be careful to check to see that LINEBEARERMODE_DATA is not set, to avoid misinterpreting the dwMaxRate member. It is likely to be 64000 or higher if LINEBEARERMODE_DATA is set.

It should also be noted that if the modem has not been specifically identified (for example, it is a “generic” modem), the figure indicated is a “best guess” based on examination of the modem.


LINEDEVSTATUS

This structure describes the current status of a line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linedevstatus_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;

DWORD dwNumOpens;
DWORD dwOpenMediaModes;
DWORD dwNumActiveCalls;
DWORD dwNumOnHoldCalls;
DWORD dwNumOnHoldPendCalls;
DWORD dwLineFeatures;
DWORD dwNumCallCompletions;
DWORD dwRingMode;
DWORD dwSignalLevel;
DWORD dwBatteryLevel;
DWORD dwRoamMode;

DWORD dwDevStatusFlags;

DWORD dwTerminalModesSize;
DWORD dwTerminalModesOffset;

DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset;

} LINEDEVSTATUS, FAR *LPLINEDEVSTATUS;

Members

dwTotalSize
Specifies the total size in bytes allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure that is needed to hold all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
dwNumOpens
Specifies the number of active opens on the line device.
dwOpenMediaModes
Specifies a bit array that indicates for which media modes the line device is currently open.
dwNumActiveCalls
Specifies the number of calls on the line in call states other idle, onhold, onholdpendingtransfer, and onholdpendingconference.
dwNumOnHoldCalls
Specifies the number of calls on the line in the onhold state.
dwNumOnHoldPendCalls
Specifies the number of calls on the line in the onholdpendingtransfer or onholdpendingconference state.
dwLineFeatures
Specifies the line-related API functions that are currently available on this line. It uses the following LINEFEATURE_* constants:
Value
Description
LINEFEATURE_DEVSPECIFIC | Device-specific operations can be used on the line.
LINEFEATURE_DEVSPECIFICFEAT | Device-specific features can be used on the line.
LINEFEATURE_FORWARD | Forwarding of all addresses can be used on the line.
LINEFEATURE_MAKECALL | An outgoing call can be placed on this line using an unspecified address.
LINEFEATURE_SETMEDIACONTROL | Media control can be set on this line.
LINEFEATURE_SETTERMINAL | Terminal modes for this line can be set.

dwNumCallCompletions
Specifies the number of outstanding call completion requests on the line.
dwRingMode
Specifies the current ring mode on the line device.
dwSignalLevel
Specifies the current signal level of the connection on the line. This is a value in the range 0x00000000 (weakest signal) to 0x0000FFFF (strongest signal).
dwBatteryLevel
Specifies the current battery level of the line device hardware. This is a value in the range 0x00000000 (battery empty) to 0x0000FFFF (battery full).
dwRoamMode
Specifies the current roam mode of the line device. It uses the following LINEROAMMODE_ constants:
Value
Description
LINEROAMMODE_UNKNOWN | The roam mode is currently unknown, but may be identified later.
LINEROAMMODE_UNAVAIL | The roam mode is unavailable and cannot be known.
LINEROAMMODE_HOME | The line is connected to the home network node.
LINEROAMMODE_ROAMA | The line is connected to the Roam-A carrier and calls are charged accordingly.
LINEROAMMODE_ROAMB | The line is connected to the Roam-B carrier and calls are charged accordingly.

dwDevStatusFlags
Specifies the size, in bytes, of this data structure that contains useful data, of type LINEDEVSTATUSFLAGS_.
Value
Description
LINEDEVSTATUSFLAGS_CONNECTED | Specifies if the line is connected to TAPI. If TRUE, the line is connected and API is able to operate on the line device. If FALSE, the line is disconnected and the application is unable to control the line device using TAPI.
LINEDEVSTATUSFLAGS_LOCKED | This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit may be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone, so that the application can present an appropriate alert to the user.
LINEDEVSTATUSFLAGS_MSGWAIT | This member indicates if the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.
LINEDEVSTATUSFLAGS_INSERVICE | This member indicates if the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.

dwTerminalModesSize
dwTerminalModesOffset
Specify the size, in bytes, of the variably sized device field that contains an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. This array is indexed by terminal identifiers, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set using the lineSetTerminal function for this line. It uses the following LINETERMMODE_ constants:
Value
Description
LINETERMMODE_LAMPS | Lamp events sent from the line to the terminal.
LINETERMMODE_BUTTONS | Button-press events sent from the terminal to the line.
LINETERMMODE_DISPLAY | Display data sent from the line to the terminal.
LINETERMMODE_RINGER | Ringer-control data sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH | Hookswitch events sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE | The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call’s media stream can be controlled independently.
LINETERMMODE_MEDIAFROMTERM | The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call’s media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT | The bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call’s media stream cannot be controlled independently.

dwDevSpecificSize
dwDevSpecificOffset
Specify the size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The members dwAvailableMediaModes through dwAppInfoOffset are available only to applications that open the line device with an API version of 2.0 or later.


LINELOCATIONENTRY

The LINELOCATIONENTRY structure describes a location used to provide an address translation context.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linelocationentry_tag {
DWORD dwPermanentLocationID;
DWORD dwLocationNameSize;
DWORD dwLocationNameOffset;
DWORD dwCountryCode;
DWORD dwCityCodeSize;
DWORD dwCityCodeOffset;
DWORD dwPreferredCardID;
DWORD dwLocalAccessCodeSize;
DWORD dwLocalAccessCodeOffset;
DWORD dwLongDistanceAccessCodeSize;
DWORD dwLongDistanceAccessCodeOffset;
DWORD dwTollPrefixListSize;
DWORD dwTollPrefixListOffset;
DWORD dwCountryID;
DWORD dwOptions;
DWORD dwCancelCallWaitingSize;
DWORD dwCancelCallWaitingOffset;
} LINELOCATIONENTRY, FAR *LPLINELOCATIONENTRY;

Members

dwPermanentLocationID
The permanent identifier that identifies the location.
dwLocationNameSize
dwLocationNameOffset
Contains a null-terminated ASCII string (size includes the NULL) that describes the location in a user-friendly manner.
dwCountryCode
The country code of the location.
dwPreferredCardID
The preferred calling card when dialing from this location.
dwCityCodeSize
dwCityCodeOffset
Contains a null-terminated ASCII string specifying the city/area code associated with the location (the size includes the NULL). This data, along with the country code, can be used by applications to “default” entry fields for the user when entering phone numbers, to encourage the entry of proper canonical numbers.
dwLocalAccessCodeSize
dwLocalAccessCodeOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the access code to be dialed before calls to addresses in the local calling area.
dwLongDistanceAccessCodeSize
dwLongDistanceAccessCodeOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the access code to be dialed before calls to addresses outside the local calling area.
dwTollPrefixListSize
dwTollPrefixListOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the toll prefix list for the location. The string contains only prefixes consisting of the digits "0" through "9", separated from each other by a single “,” (comma) character.
dwCountryID
The country identifier of the country selected for the location.
dwOptions
Indicates options in effect for this location, with values taken from the LINELOCATIONOPTION_ set of constants.
dwCancelCallWaitingSize
dwCancelCallWaitingOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a null-terminated ASCII string containing the dial digits and modifier characters that should be prefixed to the dialable string (after the pulse/tone character) when an application sets the LINETRANSLATEOPTION_CANCELCALLWAITING bit in the dwTranslateOptions parameter of lineTranslateAddress. If no prefix is defined, this may be indicated by dwCancelCallWaitingSize being set to zero, or by it being set to 1 and dwCancelCallWaitingOffset pointing to an empty string (single NULL byte).

Remarks

No extensions.

Older applications are compiled without knowledge of these new fields, and using a SIZEOF LINELOCATIONENTRY smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINELOCATIONENTRY structures in the format they previously expected, or they are not able to index through the array properly. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. The lineGetTranslateCaps function should use the LINELOCATIONENTRY members and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.


LINETRANSLATECAPS

This structure describes the address translation capabilities.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linetranslatecaps_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;

DWORD dwNumLocations;
DWORD dwLocationListSize;
DWORD dwLocationListOffset;

DWORD dwCurrentLocationID;
DWORD dwNumCards;
DWORD dwCardListSize;
DWORD dwCardListOffset;

DWORD dwCurrentPreferredCardID;
} LINETRANSLATECAPS, FAR *LPLINETRANSLATECAPS;

Members

dwTotalSize
Specifies the total size, in bytes, allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure that is needed to hold all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
dwNumLocations
Specifies the number of entries in the LocationList. It includes all locations defined, including zero (default).
dwLocationListSize
dwLocationListOffset
List of locations known to the address translation. The list consists of a sequence of LINELOCATIONENTRY structures. The dwLocationListOffset member points to the first byte of the first LINELOCATIONENTRY structure, and the dwLocationListSize member indicates the total number of bytes in the entire list.
dwCurrentLocationID
Specifies the dwPermanentLocationID member from the LINELOCATIONENTRY structure for the CurrentLocation.
dwNumCards
dwCardListSize
dwCardListOffset
Unsupported; set to zero.
dwCurrentPreferredCardID
Specifies the dwPreferredCardID member from the LINELOCATIONENTRY structure for the CurrentLocation.

Remarks

No extensions.


LINETRANSLATEOUTPUT

This structure describes the result of an address translation.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct linetranslateoutput_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;

DWORD dwDialableStringSize;
DWORD dwDialableStringOffset;
DWORD dwDisplayableStringSize;
DWORD dwDisplayableStringOffset;

DWORD dwCurrentCountry;
DWORD dwDestCountry;
DWORD dwTranslateResults;
} LINETRANSLATEOUTPUT, *LPLINETRANSLATEOUTPUT;

Members

dwTotalSize
Specifies the total size, in bytes, allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure that is needed to hold all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
dwDialableStringSize
dwDialableStringOffset
Contain the translated output that can be passed to the lineMakeCall or other function requiring a dialable string. The output is always a NULL-terminated ASCII string (NULL is accounted for in Size). Ancillary fields such as name and subaddress are included in this output string if they were in the input string. This string may contain private data such as calling card numbers. It should not be displayed to the user, to prevent inadvertent visibility to unauthorized persons.
dwDisplayableStringSize
dwDisplayableStringOffset
Contain the translated output that can be displayed to the user for confirmation. It is identical to DialableString, except that calling card digits are replaced with the “friendly name” of the card enclosed within bracket characters (for example, “[AT&T Card]”), and ancillary fields such as name and subaddress are removed. It should normally be safe to display this string in call-status dialog boxes without exposing private data to unauthorized persons. This data is also appropriate to include in call logs.
dwCurrentCountry
Contains the country code configured in CurrentLocation. This value may be used to control the display by the application of certain user interface elements, for local call progress tone detection, and for other purposes.
dwDestCountry
Contains the destination country code of the translated address. This value may be passed to the dwCountryCode parameter of lineMakeCall and other dialing functions (so that the call progress tones of the destination country such as a busy signal are properly detected). This field is set to zero if the destination address passed to lineTranslateAddress is not in canonical format.
dwTranslateResults
Indicates the data derived from the translation process, which may assist the application in presenting user-interface elements. This field uses the following LINETRANSLATERESULT_ constants:

LINETRANSLATERESULT_CANONICAL

Indicates that the input string was in valid canonical format.

Value
Description
LINETRANSLATERESULT_INTERNATIONAL | If this bit is on, the call is being treated as an international call (country code specified in the destination address is different from the country code specified for CurrentLocation).
LINETRANSLATERESULT_LONGDISTANCE | If this bit is on, the call is being treated as a long distance call (country code specified in the destination address is the same, but area code is different from those specified for CurrentLocation).
LINETRANSLATERESULT_LOCAL | If this bit is on, the call is being treated as a local call (country code and area code specified in the destination address are the same as those specified for CurrentLocation).
LINETRANSLATERESULT_INTOLLLIST | If this bit is on, the local call is being dialed as long distance because the country has toll calling and the prefix appears in the TollPrefixList of CurrentLocation.
LINETRANSLATERESULT_NOTINTOLLLIST | If this bit is on, the country supports toll calling, but the prefix does not appear in the TollPrefixList, so the call is dialed as a local call. If both INTOLLIST and NOTINTOLLIST are off, the current country does not support toll prefixes, and user interface elements related to toll prefixes should not be presented to the user; if either such bit is on, the country does support toll lists, and the related user interface elements should be enabled.
LINETRANSLATERESULT_DIALBILLING | Indicates that the returned address contains a “$”.
LINETRANSLATERESULT_DIALQUIET | Indicates that the returned address contains a “@”.
LINETRANSLATERESULT_DIALDIALTONE | Indicates that the returned address contains a “W”.
LINETRANSLATERESULT_DIALPROMPT | Indicates that the returned address contains a “?”.

Remarks

No extensions.


LINGER

This structure is used by an application to set the linger socket option and specify the length of time to wait for unsent data before a socket is closed.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct linger {
u_short l_onoff;
u_short l_linger;
};

Members

l_onoff
Integer that indicates if the linger option is turned on
l_linger
Integer that specifies the time, in seconds, to wait for unsent data before a socket is closed.

Remarks

To enable SO_LINGER, the application should set l_onoff to a nonzero value, set l_linger to zero or the desired timeout (in seconds), and call setsockopt. To enable SO_DONTLINGER (that is, disable SO_LINGER) l_onoff should be set to zero and setsockopt should be called. Note that enabling SO_LINGER with a nonzero timeout on a nonblocking socket is not recommended.

Enabling SO_LINGER also disables SO_DONTLINGER, and vice versa. Note that if SO_DONTLINGER is DISABLED (that is, SO_LINGER is ENABLED) then no timeout value is specified. In this case, the time-out used is implementation dependent. If a previous time-out has been established for a socket (by enabling SO_LINGER), then this time-out value should be reinstated by the service provider.

See Also

closesocket


NETRESOURCE

This structure that holds the network resource data. It is returned during enumeration of resources on the network and during enumeration of currently connected resources.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _NETRESOURCE {
DWORD dwScope;
DWORD dwType;
DWORD dwDisplayType;
DWORD dwUsage;
LPTSTR lpLocalName;
LPTSTR lpRemoteName;
LPTSTR lpComment;
LPTSTR lpProvider;
} NETRESOURCE;

Members

dwScope
Specifies the scope of the enumeration. Currently, this member can be one of the following values:
Value
Description
RESOURCE_CONNECTED | Currently connected resources (the dwUsage member is undefined).
RESOURCE_GLOBALNET | Resources on the network.
RESOURCE_REMEMBERED | Remembered (persistent) connections (dwUsage is undefined).

dwType
Specifies a bitmask that gives the resource type. Currently, this member can be one of the following values:
Value
Description
RESOURCETYPE_ANY | All resources
RESOURCETYPE_DISK | Disk resources
RESOURCETYPE_PRINT | Print resources

dwDisplayType
Specifies how the network object should be displayed in a network browsing user interface. Currently, this member can be the following values:
Value
Description
RESOURCEDISPLAYTYPE_DOMAIN | The object should be displayed as a domain.
RESOURCEDISPLAYTYPE_GENERIC | The method used to display the object does not matter.
RESOURCEDISPLAYTYPE_SERVER | The object should be displayed as a server.
RESOURCEDISPLAYTYPE_SHARE | The object should be displayed as a share.

dwUsage
Specifies a bitmask that gives the resource usage. This member is defined only if dwScope is RESOURCE_GLOBALNET. Currently, this member can be one of the following values:
Value
Description
RESOURCEUSAGE_CONNECTABLE | This is a connectable resource; the name pointed to by the lpRemoteName member can be passed to the WNetAddConnection function to make a network connection.
RESOURCEUSAGE_CONTAINER | This is a container resource; the name pointed to by the lpRemoteName member can be passed to the WNetOpenEnum function to enumerate the resources in the container.

lpLocalName
Long pointer to the local name of a network resource if the dwScope member is RESOURCE_CONNECTED or RESOURCE_REMEMBERED. This member is NULL if the connection does not have a local name.
lpRemoteName
Long pointer to a remote network name if the entry is a network resource.

If the entry is a current or persistent connection, lpRemoteName points to the network name associated with the name pointed to by the lpLocalName member.

lpComment
Long pointer to a provider-supplied comment.
lpProvider
Long pointer to the name of the provider owning this resource. This member can be NULL if the provider name is unknown.

Remarks

Windows CE does not support paths with the prefix of “drive letters.” The lpLocalName member can contain any string of up to 99 characters long. If the local name is “*”, the default name is constructed based on the remote name: “<share> on <server>.”


RASCONN

This structure provides data about a remote access connection. The RasEnumConnections function returns an array of RASCONN structures.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RASCONN {
DWORD dwSize;
HRASCONN hrasconn;
TCHAR szEntryName[RAS_MaxEntryName + 1];
} RASCONN ;

Members

dwSize
Specifies the size, in bytes, of the RASCONN structure.
hrasconn
Handle to the remote access connection. This handle is used in other remote access API calls.
szEntryName
Null-terminated string that specifies the phone-book entry used to establish the remote access connection. If the connection was established using an empty entry name, this string consists of a “.” followed by the connection phone number.

See Also

RasEnumConnections, RasGetConnectStatus


RASCONNSTATE

This enumeration type contains values that specify the states that may occur during a RAS connection operation. If you use the RasDial function to establish a RAS connection, you can specify a window to receive notification messages that report the current connection state. You can also use the RasGetConnectStatus function to get the connection state for a specified connection.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

typedef enum _RASCONNSTATE {
RASCS_OpenPort = 0,
RASCS_PortOpened,
RASCS_ConnectDevice,
RASCS_DeviceConnected,
RASCS_AllDevicesConnected,
RASCS_Authenticate,
RASCS_AuthNotify,
RASCS_AuthRetry,
RASCS_AuthCallback,
RASCS_AuthChangePassword,
RASCS_AuthProject,
RASCS_AuthLinkSpeed,
RASCS_AuthAck,
RASCS_ReAuthenticate,
RASCS_Authenticated,
RASCS_PrepareForCallback,
RASCS_WaitForModemReset,
RASCS_WaitForCallback,
RASCS_Projected,
RASCS_Interactive = RASCS_PAUSED,
RASCS_RetryAuthentication,
RASCS_CallbackSetByCaller,
RASCS_PasswordExpired,

RASCS_Connected = RASCS_DONE,
RASCS_Disconnected
} RASCONNSTATE ;

Enumerator Values

The enumerator values are listed here in the general order in which the connection states occur. However, you should not write code that depends on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

RASCS_OpenPort
The communication port is about to be opened.
RASCS_PortOpened
The communication port has been opened successfully.
RASCS_ConnectDevice
A device is about to be connected. RasGetConnectStatus can be called to determine the name and type of the device being connected.
RASCS_DeviceConnected
A device has connected successfully. RasGetConnectStatus can be called to determine the name and type of the device being connected.

For a simple modem connection, RASCS_ConnectDevice and RASCS_DeviceConnected will be called only once. For a dial-up X.25 PAD connection, the pair will be called first for the modem, then for the PAD. If a preconnect switch is configured, the pair will be called for the switch before any other devices connect. Likewise, the pair will be called for a postconnect switch after any other devices connect.

Windows CE: Note that Windows CE does not currently support multistage connections such as the X.25 PAD connection described earlier.

RASCS_AllDevicesConnected
All devices in the device chain have successfully connected. At this point, the physical link is established.
RASCS_Authenticate
The authentication process is starting. Remote access does not enable the remote client to generate any traffic on the LAN until authentication has been successfully completed.

Remote access authentication on a Windows NT or Windows 95 server consists of:

  • Validating the user name/ password on the specified domain.
  • Projecting the client onto the LAN. This means that the remote access server does what is necessary to send and receive data on the LAN on behalf of the client. For example, the remote access server might need to add a NetBIOS name that corresponds to the client’s computer name.
  • Call-back processing in which the client hangs up and the server calls back. (The user needs special permissions on the remote access server for this.)
  • Calculating the link speed. This is necessary to correctly set transport time-outs to match the relatively slow speed of the remote link.
RASCS_AuthNotify
An authentication event has occurred. If dwError is zero, this event will be immediately followed by one of the more specific authentication states following. If dwError is nonzero, authentication has failed, and the error value indicates why.
RASCS_AuthRetry
The client has requested another validation attempt with a new user name/password/domain.
RASCS_AuthCallback
The remote access server has requested a callback number. This occurs only if the user has “Set By Caller” callback privilege on the server.
RASCS_AuthChangePassword
The client has requested to change the password on the account.
RASCS_AuthProject
The projection phase is starting.
RASCS_AuthLinkSpeed
The link-speed calculation phase is starting.
RASCS_AuthAck
An authentication request is being acknowledged.
RASCS_ReAuthenticate
Reauthentication (after callback) is starting.
RASCS_Authenticated
The client has successfully completed authentication.
RASCS_PrepareForCallback
The line is about to disconnect in preparation for callback.
RASCS_WaitForModemReset
The client is delaying in order to give the modem time to reset itself in preparation for callback.
RASCS_WaitForCallback
The client is waiting for an incoming call from the remote access server.
RASCS_Projected
This state occurs after the RASCS_AuthProject state. It indicates that projection result data is available. You can access the projection result data by calling RasGetProjectionInfo.
RASCS_Interactive
This state corresponds to the terminal state supported by RASPHONE.EXE.
RASCS_RetryAuthentication
This state corresponds to the retry authentication state supported by RASPHONE.EXE
RASCS_CallbackSetByCaller
This state corresponds to the callback state supported by RASPHONE.EXE.
RASCS_PasswordExpired
This state corresponds to the change password state supported by RASPHONE.EXE.
RASCS_Connected
Successful connection.
RASCS_Disconnected
Disconnection or failed connection.

Remarks

The connection process states are divided into three classes: running states, paused states, and terminal states.

An application can easily determine the class of a specific state by performing Boolean bit operations with the RASCS_PAUSED and RASCS_DONE bitmasks. Here are some examples:

fDoneState = (state & RASCS_DONE);
fPausedState = (state & RASCS_PAUSED);
fRunState = !(fDoneState || fPausedState);

See Also

RasDial, RasGetConnectStatus, RASCONNSTATUS


RASCONNSTATUS

This structure describes the current status of a remote access connection. It is returned by the RasGetConnectStatus function.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RASCONNSTATUS {
DWORD dwSize;
RASCONNSTATE rasconnstate;
DWORD dwError;
TCHAR szDeviceType[RAS_MaxDeviceType + 1];
TCHAR szDeviceName[RAS_MaxDeviceName + 1];
} RASCONNSTATUS;

Members

dwSize
Specifies the structure size, in bytes.
rasconnstate
Specifies a RASCONNSTATE enumerator value that indicates the current state of the RasDial connection process; that is, the piece of the RasDial process that is currently executing.

Two state values are especially significant:
Value
Description
RASCS_Connected | Indicates that the connection has been successfully established.
RASCS_Disconnected | Indicates that the connection has failed.

dwError
If nonzero, specifies the reason for failure. The value is one of the error values from the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or ERROR_INVALID_HANDLE.
szDeviceType
Null-terminated string that specifies the type of the current device, if available. For example, common device types supported by RAS are “modem,” “pad,” “switch,” “isdn,” or “NULL.”
szDeviceName
Null-terminated string that specifies the name of the current device, if available. This would be the name of the modem—for example, “Hayes Smartmodem 2400”; the name of the PAD, for example, “US Sprint”; or the name of a switch device, for example “Racal-Guardata.”

See Also

RasGetConnectStatus, RasDial, RASCONNSTATE


RASDIALPARAMS

This structure contains parameters used by the RasDial function to establish a remote access connection.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RASDIALPARAMS {
DWORD dwSize;
TCHAR szEntryName[RAS_MaxEntryName + 1];
TCHAR szPhoneNumber[RAS_MaxPhoneNumber + 1];
TCHAR szCallbackNumber[RAS_MaxCallbackNumber + 1];
TCHAR szUserName[UNLEN + 1];
TCHAR szPassword[PWLEN + 1];
TCHAR szDomain[DNLEN + 1] ;
} RASDIALPARAMS;

Members

dwSize
Specifies the structure size, in bytes.
szEntryName
Null-terminated string that contains the phone-book entry to use to establish the connection. An empty string (““) specifies a simple modem connection on the first available modem port, in which case a nonempty szPhoneNumber must be provided.
szPhoneNumber
This parameter is ignored and should be set to NULL.
szCallbackNumber
This parameter is ignored and should be set to NULL.
szUserName
Null-terminated string that contains the user’s user name. This string is used to authenticate the user’s access to the remote access server.
szPassword
Null-terminated string that contains the user’s password. This string is used to authenticate the user’s access to the remote access server.
szDomain
Null-terminated string that contains the domain on which authentication is to occur. An empty string (““) specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phone book for the entry.

Remarks

The szCallbackNumber and szPhoneNumber members are ignored and should always be set to NULL.

The szUserName and szPassword strings are used to authenticate the user’s access to the remote access server.

See Also

RasDial


RASENTRY

This structure describes a phone-book entry. The RasSetEntryProperties and RasGetEntryProperties functions use this structure to set and retrieve the properties of a phone-book entry.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

typedef_struct_RASENTRY{
DWORD dwSize;
DWORD dwfOptions;
DWORD dwCountryID;
DWORD dwCountryCode;
TCHAR szAreaCode[ RAS_MaxAreaCode + 1 ];
TCHAR szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
DWORD dwAlternatesOffset;
RASIPADDR ipaddr;
RASIPADDR ipaddrDns;
RASIPADDR ipaddrDnsAlt;
RASIPADDR ipaddrWins;
RASIPADDR ipaddrWinsAlt;
DWORD dwFrameSize;
DWORD dwfNetProtocols;
DWORD dwFramingProtocol;
TCHAR szScript[ MAX_PATH ];
TCHAR szAutoDialDll[ MAX_PATH ];
TCHAR szAutoDialFunc[ MAX_PATH ];
TCHAR szDeviceType[ RAS_MaxDeviceType + 1 ];
TCHAR szDeviceName[ RAS_MaxDeviceName + 1 ];
TCHAR szX25PadType[ RAS_MaxPadType + 1 ];
TCHAR szX25Address[ RAS_MaxX25Address + 1 ];
TCHAR szX25Facilities[ RAS_MaxFacilities + 1 ];
TCHAR szX25UserData[ RAS_MaxUserData + 1 ];
DWORD dwChannels;
DWORD dwReserved1;
DWORD dwReserved2;
}RASENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASENTRY structure. Before calling RasSetEntryProperties or RasGetEntryProperties, set dwSize to sizeof(RASENTRY) to identify the version of the structure.
dwfOptions
Specifies connection options. It can be one or more of the following values:
Value
Description
RASEO_UseCountryAndAreaCodes | If this flag is set, the dwCountryID, dwCountryCode, and szAreaCode members are used to construct the phone number. If this flag is not set, these members are ignored.
This flag corresponds to the Use Country and Area Codes check box in the Phone dialog box.
RASEO_SpecificIpAddr | If this flag is set, RAS tries to use the IP address specified by ipaddr as the IP address for the dial-up connection. If this flag is not set, the value of the ipaddr member is ignored.
Setting the RASEO_SpecificIpAddr flag corresponds to selecting the Specify an IP Address setting in the TCP/IP settings dialog box. Clearing the RASEO_SpecificIpAddr flag corresponds to selecting the Server Assigned IP Address setting in the TCP/IP settings dialog box.
Currently, an IP address set in the phone-book entry properties or retrieved from a server overrides the IP address set in the network control panel.
RASEO_SpecificNameServers | If this flag is set, RAS uses the ipaddrDns, ipaddrDnsAlt, ipaddrWins, and ipaddrWinsAlt members to specify the name server addresses for the dial-up connection. If this flag is not set, RAS ignores these members.
Setting the RASEO_SpecificNameServers flag corresponds to selecting the Specify Name Server Addresses setting in the TCP/IP Settings dialog box. Clearing the RASEO_SpecificNameServers flag corresponds to selecting the Server Assigned Name Server Addresses setting in the TCP/IP Settings dialog box.
RASEO_IpHeaderCompression | If this flag is set, RAS negotiates to use IP header compression on PPP connections.
If this flag is not set, IP header compression is not negotiated.
This flag corresponds to the Use IP Header Compression check box in the TCP/IP settings dialog box. It is generally advisable to set this flag because IP header compression significantly improves performance. The flag should be cleared only when connecting to a server that does not correctly negotiate IP header compression.
RASEO_RemoteDefaultGateway | If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified.
This flag corresponds to the Use Default Gateway on Remote Network check box in the TCP/IP settings dialog box.
RASEO_DisableLcpExtensions | If this flag is set, RAS disables the PPP LCP extensions defined in RFC 1570. This may be necessary to connect to certain older PPP implementations, but interferes with features such as server callback. Do not set this flag unless specifically required.
RASEO_TerminalBeforeDial | If this flag is set, RAS displays a terminal window for user input before dialing the connection.
RASEO_TerminalAfterDial | If this flag is set, RAS displays a terminal window for user input after dialing the connection.
Do not set this flag if a dial-up networking script is to be associated with the connection, because scripting has its own terminal implementation.
RASEO_ModemLights | This flag is currently ignored.
RASEO_SwCompression | If this flag is set, software compression is negotiated on the link. Setting this flag causes the PPP driver to attempt to negotiate CCP with the server. This flag should be set by default, but clearing it can reduce the negotiation period if the server does not support a compatible compression protocol.
RASEO_RequireEncryptedPw | If this flag is set, only secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol to authenticate the client. The CHAP and SPAP authentication protocols are also supported. Clear this flag for increased interoperability, and set it for increased security.
This flag corresponds to the Require Encrypted Password check box in the Security dialog box. See also RASEO_RequireMsEncryptedPw.
RASEO_RequireMsEncryptedPw | If this flag is set, only Microsoft’s secure password scheme (MS-CHAP) can be used to authenticate the client with the server. This prevents the PPP driver from using the PPP plain-text authentication protocol, or MD5-CHAP. The flag should be cleared for maximum interoperability and should be set for maximum security. This flag takes precedence over RASEO_RequireEncryptedPw.
This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also RASEO_RequireDataEncryption.
RASEO_RequireDataEncryption | If this flag is set, data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set.
This flag corresponds to the Require Data Encryption check box in the Security dialog box.
RASEO_NetworkLogon | If this flag is set, RAS logs on to the network after the point-to-point connection is established.
RASEO_UseLogonCredentials | If this flag is set, RAS uses the user name, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set.
Note that this setting is ignored by the RasDial function, where specifying empty strings for the szUserName and szPassword members of the RASDIALPARAMS structure gives the same result.
RASEO_PromoteAlternates | This flag has an effect when alternate phone numbers are defined by the dwAlternateOffset member. If this flag is set, an alternate phone number that connects successfully becomes the primary phone number, and the current primary phone number is moved to the alternate list.
RASEO_DialAsLocalCall | Windows CE 2.10 and later: If this flag is set, RAS constructs the phone number as a local call, including the area code if it is different from the area code at the current location. This flag corresponds to the "force local" option in various dialog boxes.

dwCountryID
Specifies the TAPI country identifierThis member is currently ignored on Windows CE.
dwCountryCode
Specifies the country code portion of the phone number This member is ignored unless dwfOptions specifies the RASEO_UseCountryAndAreaCodes flag.
szAreaCode
Null-terminated string that contains the area code. If the dialing location does not have an area code, specify an empty string (““). Do not include parentheses or other delimiters in the area code string. (For example, “206” is a valid area code; “(206)” is not. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.
szLocalPhoneNumber
Null-terminated string that contains a telephone number. The way RAS uses this string depends on if the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag. If the flag is set, RAS combines szLocalPhoneNumber with the country and area codes specified by the dwCountryID, dwCountryCode, and szAreaCode members. If the flag is not set or if the RASEO_DialAsLocalCall flag is set, RAS uses the szLocalPhoneNumber string as the entire phone number.
ipaddr
Specifies the IP address to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificIpAddr flag.
ipaddrDns
Specifies the IP address of the DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrDnsAlt
Specifies the IP address of a secondary or backup DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrWins
Specifies the IP address of the WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrWinsAlt
Specifies the IP address of a secondary WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
dwFrameSize
Specifies the network protocol frame size. The value should be either 1006 or 1500. This member is ignored unless dwFramingProtocol specifies the RASFP_Slip flag.
dwfNetProtocols
Specifies the network protocols to negotiate. The following flag is supported.
Value
Description
RASNP_Ip Negotiate the TCP/IP protocol.

dwFramingProtocol
Specifies the framing protocol used by the server. PPP is the emerging standard. SLIP is used mainly in UNIX environments. This member can be one of the following flags.
Value
Description
RASFP_Ppp | Point-to-Point Protocol (PPP)
RASFP_Slip | Serial Line Internet Protocol (SLIP)

To use Compressed SLIP, set the RASFP_Slip flag and set the RASEO_IpHeaderCompression flag in the dwfOptions member.

szDeviceType
szDeviceType
Null-terminated string that indicates the RAS device type referenced by szDeviceName. This member is one of the following string constants:
Value
Description
RASDT_Modem | A modem accessed through a COM port.
RASDT_Direct | A direct serial connection.

szDeviceName
Null-terminated string that contains the name of a TAPI device to use with this phone-book entry, e.g. “XYZ Corp 28800 External”. To enumerate all available RAS-capable devices, use the RasEnumDevices function.
dwReserved1
Reserved; set to zero.
dwReserved2
Reserved; set to zero.

Remarks

The RasEnumDevices function, which enumerates RAS-capable devices in Windows 95 and Windows NT, is not supported in Windows CE. The number of TAPI devices can be obtained by calling the lineInitialize function.

The lineGetDevCaps function can be used to access the LINEDEVCAPS structure. The dwLineNameSize member of this structure indicates the length of the name in bytes. The dwLineNameOffset member indicates the number of bytes that the name is offset from the beginning of the structure.

On Windows CE, the dwCountryID member is ignored, and the dwCountryCode member must be set to the correct country code for the phone number of the entry.

For Windows CE versions 2.10 and later, the dwfOptions member supports the RASEO_DialAsLocalCall flag. If this flag is set, RAS constructs the phone number as a local call, including the area code if it is different from the area code at the current location. This flag corresponds to the “force local” option in various dialog boxes.

See Also

RasSetEntryProperties


RASENTRYNAME

This structure contains an entry name from a remote access phonebook. The RasEnumEntries function returns an array of these structures.

At a Glance

Header file: | Ras.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RASENTRYNAME {
DWORD dwSize;
TCHAR szEntryName[RAS_MaxEntryName + 1];
}RASENTRYNAME;

Members

dwSize
Specifies the structure size, in bytes.
szEntryName
Null-terminated string that contains the name of a remote access phone-book entry.

See Also

RasEnumEntries


REMOTE_NAME_INFO

This structure contains path and name data about a network resource. The structure contains a member that points to a Universal Naming Convention (UNC) name string for the resource, and two members that point to additional network connection data strings.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _REMOTE_NAME_INFO {
LPTSTR lpUniversalName;
LPTSTR lpConnectionName;
LPTSTR lpRemainingPath;
} REMOTE_NAME_INFO;

Members

lpUniversalName
Long pointer to a zero-terminated UNC name string.
lpConnectionName
Long pointer to a zero-terminated string that is the name of a network connection.
lpRemainingPath
Long pointer to a zero-terminated UNC name string.

Remarks

The REMOTE_NAME_INFO data structure contains a pointer to a Universal Naming Convention (UNC) name string. UNC names look like this:

\\servername\sharename\path\file

You can pass the REMOTE_NAME_INFO structure’s lpConnectionName member to the WNetAddConnection2 function as the lpRemoteName member of the NETRESOURCE structure pointed to by lpNetResource. This lets you create a local connection to a network resource. You can then append the string pointed to by the lpRemainingPath member to the local device string “\network\localname”, and pass the resulting string to Win32 functions that use a file-based path.

For example in the case of the UNC path \\servername\sharename\path\file, the lpConnectionName member woud be set to \\servername\sharename\ and the lpRemainingPath member would be set to path\file.


SecBuffer

This structure describes a buffer that is allocated by a transport application to pass to a security package.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecBuffer {
ULONG cbBuffer;
ULONG BufferType;
PVOID pvBuffer;
} SecBuffer, *PSecBuffer;

Members

cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pvBuffer member.
BufferType
Set of bit flags that indicate the type of buffer. It is one of the following flags:
Flag
Description
SECBUFFER_EMPTY | This is a placeholder in the buffer array. The caller can supply several such entries in the array, and the security package can return data in them.
SECBUFFER_DATA | Used for common data. The security package can read this data, and write it, for example, to encrypt some or all of it.
SECBUFFER_TOKEN | This buffer is used to indicate the security token portion of the message. This is "read-only" for input parameters, or "read/write" for output parameters.
SECBUFFER_PKG_PARAMS | These are transport-to-package–specific parameters. For example, the Netware redirector may supply the server object identifier, while DCE RPC can supply an association UUID, and so on.
SECBUFFER_MISSING | The security package uses this value to indicate the number of missing bytes in a particular message. The pvBuffer member is ignored in this type.
SECBUFFER_EXTRA | The security package uses this value to indicate the number of extra, or unprocessed bytes in a message.
SECBUFFER_STREAM_TRAILER | Indicates a protocol-specific trailer for a particular record. Not usually of interest to callers.
SECBUFFER_STREAM_HEADER | Indicates a protocol-specific header for a particular record. Not usually of interest to callers.

In addition, BufferType can combine the following flag with any of the flags in the preceding table.
Flag
Description
SECBUFFER_READONLY The buffer is read-only. This flag is intended for sending header data to the security package for checksumming or the like. The package can read this buffer, but cannot modify it.

pvBuffer
Void pointer to a buffer.

See Also

SecBufferDesc


SecBufferDesc

This structure describes an array of SecBuffer structures to pass from a transport application to a security package.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecBufferDesc {
ULONG ulVersion;
ULONG cBuffers;
PSecBuffer pBuffers;
} SecBufferDesc, * PSecBufferDesc;

Members

ulVersion
Specifies the version number of this structure. This member must be SECBUFFER_VERSION.
cBuffers
Indicates the number of SecBuffer structures in the pBuffers array.
pBuffers
Pointer to an array of SecBuffer structures.

See Also

SecBuffer


SecPkgContext_Authority

This structure contains the name of the authenticating authority, if one is available. It can be a Certification Authority, or the name of a server or domain that authenticated the connection. The QueryContextAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgContext_Authority {
SEC_CHAR SEC_FAR*sAuthorityName;
} SecPkgContext_Authority, * PSecPkgContext_Authority;

Members

sAuthorityName
Pointer to a null-terminated string that contains the name of the authenticating authority, if available.

See Also

QueryContextAttributes


SecPkgContext_DceInfo

This structure contains authorization data used by distributed computing environment (DCE) services. The QueryContextAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgContex_DceInfo {
ULONG AuthzSvc;
PVOID SEC_FAR *pPac;
} SecPkgContext_DceInfo, SEC_FAR* PSecPkgContext_DceInfo;

Members

AuthzSvc
Specifies the authorization service used. DCE use only.
pPac
Pointer to package-specific authorization data.

See Also

QueryContextAttributes


SecPkgContext_KeyInfo

This structure contains data about the keys used in a security context. It does not return the actual key values, merely data about them. The QueryContextAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgContext_KeyInfo {
SEC_CHAR SEC_FAR *sSignatureAlgorithmName;
SEC_CHAR SEC_FAR *sEncryptAlgorithmName;
ULONG KeySize;
ULONG SignatureAlgorithm;
ULONG EncryptAlgorithm;
} SecPkgContext_KeyInfo, SEC_FAR * PSecPkgContext_KeyInfo;

Members

sSignatureAlgorithmName
Pointer to a null-terminated string that contains the name, if available, of the algorithm used for generating signatures, such as “MD5”, “SHA-2”, and so on.
sEncryptAlgorithmName
Pointer to a null-terminated string that contains the name, if available, of the algorithm used for encrypting messages. Reserved for future use.
KeySize
Specifies the size, in bits, of the key used for encrypting messages. Reserved for future use.
SignatureAlgorithm
Specifies the CryptoAPI algorithm identifier (ALG_ID, documented in the Platform SDK) in use for the signature, if available.
EncryptAlgorithm
Specifies the CryptoAPI algorithm identifier (ALG_ID) in use for encrypting messages. Reserved for future use.

See Also

QueryContextAttributes


SecPkgContext_Lifespan

This structure indicates the life span of a security context. The QueryContextAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgContext_Lifespan {
TimeStamp tsStart;
TimeStamp tsExpiry;
} SecPkgContext_Lifespan, SEC_FAR * PSecPkgContext_Lifespan;

Members

tsStart
Time at which the context was established.
tsExpiry
Time at which the context will expire.

Remarks

The security provider should always return these values in local time.

See Also

QueryContextAttributes


SecPkgContext_Names

This structure indicates the name of the user associated with a security context. The QueryContextAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgContext_Names {
SEC_CHAR SEC_FAR *sUserName;
} SecPkgContext_Names, SEC_FAR * pSecPkgContext_Names;

Members

sUserName
Pointer to a null-terminated string that contains the name of the user represented by the context. If the security package indicates that it understands Win32 names (by setting the SECPKG_FLAG_ACCEPT_WIN32_NAME flag), you can use this name in other Win32 calls.

See Also

QueryContextAttributes


SecPkgContext_Sizes

This structure indicates the sizes of important structures used in the message support functions. The QueryContextAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgContext_Sizes {
ULONG cbMaxToken;
ULONG cbMaxSignature;
ULONG cbBlockSize;
ULONG cbSecurityTrailer;
} SecPkgContext_Sizes, SEC_FAR * PSecPkgContext_Sizes;

Members

cbMaxToken
Specifies the maximum size of the security token used in the authentication exchanges.
cbMaxSignature
Specifies the maximum size of the signature created by the MakeSignature function. This member should be zero if integrity services are not requested or available.
cbBlockSize
Specifies the preferred integral size of the messages—for example, 8 indicates that messages should be of size 0 mod 8 for optimal performance. Messages other than this block size can be padded.
cbSecurityTrailer
Specifies the size of the security trailer to be appended to messages. This member should be zero if the relevant services are not requested or available.

See Also

MakeSignature, QueryContextAttributes


SecPkgContext_StreamSizes

The SecPkgContext_StreamSizes structure indicates the sizes of the various stream components, for use with the message support functions. The QueryContextAttributes function uses this structure.

Syntax

typedef struct _SecPkgContext_StreamSizes{
unsigned long cbHeader;
unsigned long cbTrailer;
unsigned long cbMaximumMessage;
unsigned long cBuffers;
unsigned long cbBlockSize;
}SecPkgContext_StreamSizes, * PSecPkgContext_StreamSizes;

Members

cbHeader
Specifies the size, in bytes, of the header portion. If zero, no header is used.
cbTrailer
Specifies the size, in bytes, of the trailer portion. If zero, no trailer is used.
cbMaximumMessage
Specifies the size, in bytes, of the largest message that can be encapsulated.
cBuffers
Specifies the number of buffers to pass.
cbBlockSize
Specifies the preferred integral size of the messages—for example, 8 indicates that messages should be of size 0 mod 8 for optimal performance. Messages other than this block size can be padded.

See Also

QueryContextAttributes


SecPkgCredentials_Names

This structure indicates the name of the user associated with a context. The QueryCredentialsAttributes function uses this structure.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgCredentials_Names {
SEC_CHAR SEC_FAR *sUserName;
} SecPkgCredentials_Names, SEC_FAR * PSecPkgCredentials_Names;

Members

sUserName
Pointer to a null-terminated string that contains the name of the user represented by the credential. If the security package sets the SECPKG_FLAG_ACCEPT_WIN32_NAME flag to indicate that it can process Win32 names, you can use this name in other Win32 calls.

See Also

QueryCredentialsAttributes


SecPkgInfo

This structure provides general data about a security package, such as its name and its capabilities.

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SecPkgInfo {
ULONG fCapabilities;
USHORT wVersion;
USHORT wRPCID;
ULONG cbMaxToken;
SEC_CHAR SEC_FAR*Name;
SEC_CHAR SEC_FAR *Comment;
} SecPkgInfo, SEC_FAR * PSecPkgInfo;

Members

fCapabilities
Set of bit flags that describe the capabilities of the security package. It can be a combination of the following flags:
Flag
Description
SECPKG_FLAG_INTEGRITY | Verify that all messages exchanged have not been tampered with or exchanged out of sequence.
SECPKG_FLAG_PRIVACY | All messages are tamper proof and are not passed in cleartext. Reserved for future use.
SECPKG_FLAG_TOKEN_ONLY | The package is interested only in the security-token portion of messages, and will ignore any other buffers. This is a performance-related issue.
SECPKG_FLAG_DATAGRAM | Supports datagram-style authentication.
SECPKG_FLAG_CONNECTION | Supports connection-oriented style authentication.
SECPKG_FLAG_MULTI_REQUIRED | Multiple legs are required for authentication.
SECPKG_FLAG_CLIENT_ONLY | Server authentication support is not provided.
SECPKG_FLAG_EXTENDED_ERROR | Supports extended error handling.
SECPKG_FLAG_IMPERSONATION | Supports Win32 impersonation in server contexts.
SECPKG_FLAG_ACCEPT_WIN32_NAME | Understands Win32 principal and target names.
SECPKG_FLAG_STREAM | Supports stream semantics.

wVersion
Specifies the version of the package protocol. Must be 1.
wRPCID
Specifies a DCE RPC identifier, if appropriate. If the package does not implement one of the DCE registered security systems, the reserved value SECPKG_ID_NONE is used.
cbMaxToken
Specifies the maximum size, in bytes, of the token.
Name
Pointer to a null-terminated string that contains the name of the security package.
Comment
Pointer to a null-terminated string. This can be any additional string passed back by the package.

See Also

EnumerateSecurityPackages , QuerySecurityPackageInfo


SecurityFunctionTable

This structure is a dispatch table that contains pointers to the functions defined in the Security Service Provider Interface .

At a Glance

Header file: | Sspi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _SECURITY_FUNCTION_TABLE {
unsigned long dwVersion;
ENUMERATE_SECURITY_PACKAGES_FN EnumerateSecurityPackages;
void SEC_FAR *Reserved1;
ACQUIRE_CREDENTIALS_HANDLE_FN AcquireCredentialsHandle;
FREE_CREDENTIALS_HANDLE_FN FreeCredentialHandle;
void SEC_FAR *Reserved2;
INITIALIZE_SECURITY_CONTEXT_FN InitializeSecurityContextA;
ACCEPT_SECURITY_CONTEXT_FN AcceptSecurityContext;
COMPLETE_AUTH_TOKEN_FN CompleteAuthToken;
DELETE_SECURITY_CONTEXT_FN DeleteSecurityContext;
APPLY_CONTROL_TOKEN_FN ApplyControlToken;
QUERY_CONTEXT_ATTRIBUTES_FN QueryContextAttributesA;
IMPERSONATE_SECURITY_CONTEXT_FN ImpersonateSecurityContext;
REVERT_SECURITY_CONTEXT_FN RevertSecurityContext;
MAKE_SIGNATURE_FN MakeSignature;
VERIFY_SIGNATURE_FN VerifySignature;
FREE_CONTEXT_BUFFER_FN FreeContextBuffer;
QUERY_SECURITY_PACKAGE_INFO_FN QuerySecurityPackageInfoA;
void SEC_FAR *Reserved3;
void SEC_FAR *Reserved4;
} SecurityFunctionTable, * PSecurityFunctionTable;
#define SECURITY_SUPPORT_PROVIDER_INTERFACE_VERSION

See Also

InitSecurityInterface


SOCKADDR

This structure is the generic address structure for all address families used in Windows socket communication.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct sockaddr {
unsigned short sa_family;
char sa_data[14];
};

Remarks

The actual structure is interpreted differently in the context of different address families. The only requirements are that the first u_short is the address family and the total size of the memory buffer in bytes is namelen.

The structure below is used with TCP/IP. Other protocols use similar structures.

struct sockaddr_in {
 short sin_family;
 u_short sin_port;
 struct in_addr sin_addr;
 char sin_zero[8];
};

See Also

SOCKADDR_IN


SOCKADDR_IN

In the Internet address family, this structure is used by Windows Sockets to specify a local or remote endpoint address to which to connect a socket. This is the form of the SOCKADDR structure specific to the Internet address family and can be cast to SOCKADDR.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct sockaddr_in{
short sin_family;
unsigned short sin_port;
IN_ADDR sin_addr;
char sin_zero[8];
};

Members

sin_family
Address family; must be AF_INET.
sin_port
Internet Protocol (IP) port.
sin_addr
IP address in network byte order.
sin_zero
Padding to make structure the same size as SOCKADDR.

Remarks

The IP address component of this structure is of type IN_ADDR. The IN_ADDR structure is defined in Windows Sockets header file Winsock.h as follows:

typedef struct in_addr {
 union {
 struct{
 unsigned char s_b1,
 s_b2,
 s_b3,
 s_b4;
 } S_un_b;
 struct {
 unsigned short s_w1,
 s_w2;
 } S_un_w;
 unsigned long S_addr;
 } S_un;
} IN_ADDR;

See Also

IN_ADDR


sockaddr_irda

This structure specifies an IrSocket address.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct sockaddr_irda {
u_short irdaAddressFamily;
u_char irdaDeviceID[4];
char irdaServiceName[25];
};

Members

irdaAddressFamily
Value for the address format member is AF_IRDA from the AF_IRDA.H header file.
irdaDeviceID
Device identifier returned by the SO_IRLMP_ENUMDEVICES option used in a getsockopt function call.
irdaServiceName
Null-terminated string of 25 characters that contains the service name of the application associated with this socket address. If the name is 25 characters or the string is not null-terminated, the connection fails. If the service name is of the form “LSAP-SELXXX” where XXX is a decimal integer in the range 1-127, the address indicates a specific LSAP-SELXXX rather than a service name.


UNIVERSAL_NAME_INFO

This structure contains a pointer to a Universal Naming Convention (UNC) name string.

At a Glance

Header file: | Winnetwk.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _UNIVERSAL_NAME_INFO {
LPTSTR lpUniversalName;
} UNIVERSAL_NAME_INFO;

Members

lpUniversalName
Long pointer to a zero-terminated UNC name string.

Remarks

A universal form of a path identifies a network resource in an unambiguous, computer-independent manner. The path can then be passed to processes on other computers, enabling those processes to obtain access to the network resource.

Universal Naming Convention (UNC) names look like this:

\\servername\sharename\path\file


VARSTRING

This structure is used for returning variably sized strings. It is used both by the line device class and the phone device class.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct varstring_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;
DWORD dwStringFormat;
DWORD dwStringSize;
DWORD dwStringOffset;
} VARSTRING, FAR *LPVARSTRING;

Members

dwTotalSize
Specifies the total size, in bytes, allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure that is needed to hold all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
dwStringFormat
Specifies the format of the string. This member uses the following STRINGFORMAT_ constants:
Value
Description
STRINGFORMAT_ASCII | ASCII string format using one byte per character. The actual string is a NULL-terminated ASCII string with the terminating NULL accounted for in the string size.
STRINGFORMAT_DBCS | DBCS string format using one or two bytes per character.
STRINGFORMAT_UNICODE | Unicode string format using two bytes per character.
STRINGFORMAT_BINARY | An array of unsigned characters that could be used for numeric values.

dwStringSize
dwStringOffset
Specify the size, in bytes, of the variably sized device field that contains the string data, and the offset, in bytes, from the beginning of this data structure.

Remarks

No extensibility.

If a string cannot be returned in a variable structure, the dwStringSize and dwStringOffset members are set in one of these ways:

  • dwStringSize and dwStringOffset members are both set to zero.
  • dwStringOffset is nonzero and dwStringSize is zero.
  • dwStringOffset is nonzero, dwStringSize is 1, and the byte at the given offset is zero.

See Also

lineConfigDialogEdit, lineGetDevConfig, lineGetID, lineSetDevConfig, LINECALLPARAMS


WSADATA

This structure is used to store Windows Sockets initialization data returned by a call to WSAStartup. It contains data about the Winsock.dll implementation.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct WSAData {
WORD wVersion;
WORD wHighVersion;
char szDescription[WSADESCRIPTION_LEN+1];
char szSystemStatus[WSASYSSTATUS_LEN+1];
unsigned short iMaxSockets;
unsigned short iMaxUdpDg;
char * lpVendorInfo;
};

Members

wVersion
Version of the Windows Sockets specification that the Windows Sockets DLL expects the caller to use. The high-order word specifies the minor version (revision) number; and the low-order word specifies the major version number.
wHighVersion
Highest version of the Windows Sockets specification that this DLL can support, usually the same as wVersion.
szDescription
Null-terminated string into which the Windows Sockets DLL copies a description of the Windows Sockets implementation, including vendor identification. The text—up to 256 characters in length—can contain any characters, but vendors are cautioned against including control and formatting characters. Typically, an application uses this description in a status message.
szSystemStatus
Null-terminated string into which the Windows Sockets DLL copies relevant status or configuration data. The Windows Sockets DLL should use this member only if the data might be useful to the user or support staff; it should not be considered as an extension of the szDescription member.
iMaxSockets
Maximum number of sockets which a single process can potentially open. A Windows Sockets implementation can provide a global pool of sockets for allocation to any process; alternatively it can allocate per-process resources for sockets. The number can well reflect the way in which the Windows Sockets DLL or the networking software was configured. Application writers can use this number as a crude indication of whether the Windows Sockets implementation is usable by the application. For example, an X Windows server might check iMaxSockets when first started: if it is less than 8, the application would display an error message instructing the user to reconfigure the networking software. (This is a situation in which the szSystemStatus text might be used.) Obviously there is no guarantee that a particular application can actually allocate iMaxSockets sockets, since there can be other Windows Sockets applications in use.
iMaxUdpDg
Size, in bytes, of the largest User Datagram Protocol (UDP) datagram that can be sent or received by a Windows Sockets application. If the implementation imposes no limit, iMaxUdpDg is zero. In many implementations of Berkeley sockets, there is an implicit limit of 8192 bytes on UDP datagrams, which are fragmented if necessary. A Windows Sockets implementation can impose a limit based, for instance, on the allocation of fragment reassembly buffers. The minimum value of iMaxUdpDg for a compliant Windows Sockets implementation is 512. Note that regardless of the value of iMaxUdpDg, it is inadvisable to attempt to send a broadcast datagram which is larger than the Maximum Transmission Unit (MTU) for the network.

The Windows Sockets API does not provide a mechanism to discover the MTU, but it must be no less than 512 bytes.

lpVendorInfo
Long pointer to a vendor-specific data structure. The definition of this structure (if supplied) is beyond the scope of the Windows Sockets specification.

Remarks

WSAStartup assigns the following values to the members of the WSADATA structure:

WSADATA member
Assigned value
wVersion | wVersionRequested parameter value
wHighVersion | wVersionRequested parameter value
szDescription | NULL string
szSystemStatus | NULL string
iMaxSockets | 20
iMaxUdpDg | 0
lpVendorInfo | NULL

See Also

WSAStartup


LINE_ADDRESSSTATE

This message is sent when the status of an address changes on a line that is currently open by the application. The application can invoke lineGetAddressStatus to determine the current status of the address.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_ADDRESSSTATE dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idAddress; dwParam2 = (DWORD) AddressState;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Specifies a handle to the line device.
dwCallbackInstance
Specifies the callback instance supplied when opening the line.
dwParam1
Specifies the address identifier of the address that changed status.
dwParam2
Specifies the address state that changed. It can be a combination of the following values:
Value
Description
LINEADDRESSSTATE_OTHER | Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC | The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO | The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE | The address has changed from idle or from being used by many bridged stations to being used by just one station.
LINEADDRESSSTATE_INUSEMANY | The monitored or bridged address has changed from being used by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS | The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD | The forwarding status of the address has changed, including the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address’s current forwarding status.
LINEADDRESSSTATE_TERMINALS | The terminal settings for the address have changed.

dwParam3
Unused.

Return Values

None.

Remarks

The LINE_ADDRESSSTATE message is sent to any application that has opened the line device and that has enabled this message. The sending of this message for the various status items can be controlled and queried using lineGetStatusMessages and lineSetStatusMessages. By default, address status reporting is disabled.


LINE_CALLINFO

This message is sent when the call information about the specified call has changed. The application can invoke lineGetCallInfo to determine the current call information.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_CALLINFO dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) CallInfoState; dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Specifies a handle to the call.
dwCallbackInstance
Specifies the callback instance supplied when opening the call’s line.
dwParam1
Specifies the call information item that has changed. It can be a combination of the following values:
Value
Description
LINECALLINFOSTATE_OTHER | Information items other than those listed below have changed. The application should check the current call information to determine which items have changed.
LINECALLINFOSTATE_DEVSPECIFIC | The device-specific field of the call-information record has changed.
LINECALLINFOSTATE_BEARERMODE | The bearer mode field of the call-information record has changed.
LINECALLINFOSTATE_RATE | The rate field of the call-information record has changed.
LINECALLINFOSTATE_MEDIAMODE | The media mode field of the call-information record has changed.
LINECALLINFOSTATE_APPSPECIFIC | The application-specific field of the call-information record has changed.
LINECALLINFOSTATE_CALLID | The call identifier field of the call-information record has changed.
LINECALLINFOSTATE_RELATEDCALLID | The related call identifier field of the call-information record has changed.
LINECALLINFOSTATE_ORIGIN | The origin field of the call-information record has changed.
LINECALLINFOSTATE_REASON | The reason field of the call-information record has changed.
LINECALLINFOSTATE_COMPLETIONID | The completion identifier field of the call-information record has changed.
LINECALLINFOSTATE_NUMOWNERINCR | The number of owner fields in the call-information record was increased.
LINECALLINFOSTATE_NUMOWNERDECR | The number of owner fields in the call-information record was decreased.
LINECALLINFOSTATE_NUMMONITORS | The number of monitors fields in the call-information record has changed.
LINECALLINFOSTATE_TRUNK | The trunk field of the call information record has changed.
LINECALLINFOSTATE_CALLERID | One of the caller ID-related fields of the call information record has changed.
LINECALLINFOSTATE_CALLEDID | One of the caller ID-related fields of the call information record has changed.
LINECALLINFOSTATE_CONNECTEDID | One of the connected identifier-related fields of the call information record has changed.
LINECALLINFOSTATE_REDIRECTIONID | One of the redirection identifier-related fields of the call information record has changed.
LINECALLINFOSTATE_REDIRECTINGID | One of the redirecting identifier-related fields of the call information record has changed.
LINECALLINFOSTATE_DISPLAY | The display field of the call information record has changed.
LINECALLINFOSTATE_USERUSERINFO | The user-user information of the call information record has changed.
LINECALLINFOSTATE_HIGHLEVELCOMP | The high-level compatibility field of the call information record has changed.
LINECALLINFOSTATE_LOWLEVELCOMP | The low-level compatibility field of the call information record has changed.
LINECALLINFOSTATE_CHARGINGINFO | The charging information of the call information record has changed.
LINECALLINFOSTATE_TERMINAL | The terminal mode information of the call information record has changed.
LINECALLINFOSTATE_DIALPARAMS | The dial parameters of the call information record has changed.
LINECALLINFOSTATE_MONITORMODES | One or more of the digit, tone, or media monitoring fields in the call information record has changed.

dwParam2
Unused.
dwParam3
Unused.

Return Values

None.

Remarks

A LINE_CALLINFO message with a NumOwnersIncr, NumOwnersDecr, and/or NumMonitorsChanged indication is sent to applications that already have a handle for the call. This can be the result of another application changing ownership or monitorship to a call with lineOpen, lineClose, and lineShutdown.

These LINE_CALLINFO messages are not sent when a notification of a new call is provided in a LINE_CALLSTATE message, because the call information already reflects the correct number of owners and monitors at the time the LINE_CALLSTATE messages are sent. LINE_CALLINFO messages are also suppressed in the case where a call is offered by TAPI to monitors through the LINECALLSTATE_UNKNOWN mechanism.

Note The application that causes a change in the number of owners or monitors (for example, by invoking lineDeallocateCall or lineSetCallPrivilege) does not itself receive a message indicating that the change has been done.

No LINE_CALLINFO messages are sent for a call after the call has entered the idle state. Specifically, changes in the number of owners and monitors are not reported as applications deallocate their handles for the idle call.


LINE_CALLSTATE

This message is sent when the status of the specified call has changed. Several such messages will typically be received during the lifetime of a call. Applications are notified of new incoming calls with this message; the new call will be in the offering state. The application can use lineGetCallStatus to retrieve more detailed information about the current status of the call.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_CALLSTATE dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) CallState; dwParam2 = (DWORD) CallStateDetail;
dwParam3 = (DWORD) CallPrivilege;

Parameters

dwDevice
Specifies a handle to the call.
dwCallbackInstance
Specifies the callback instance supplied when opening the call’s line.
dwParam1
Specifies the new call state. It is only one of the following LINECALLSTATE_ values:
Value
Description
LINECALLSTATE_IDLE | The call is idle—no call actually exists.
LINECALLSTATE_OFFERING | The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user. Alerting is done by the switch instructing the line to ring; it does not affect any call states.
LINECALLSTATE_ACCEPTED | The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also indicates that alerting to both parties has started.
LINECALLSTATE_DIALTONE | The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING | Destination address information (a phone number) is being sent to the switch over the call. Note that lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK | The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY | The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party’s station are in use.
LINECALLSTATE_SPECIALINFO | Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED | The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING | Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD | The call is on hold by the switch.
LINECALLSTATE_CONFERENCED | The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF | The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENTRANSFER | The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED | The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN | The state of the call is not known. This may be due to limitations of the call-progress detection implementation.

dwParam2
Specifies call-state-dependent information.

If dwParam1 is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode. This parameter uses the following LINEBUSYMODE_ constants:
Value
Description
LINEBUSYMODE_STATION | The busy signal indicates that the called party’s station is busy. This is usually signaled by means of a “normal” busy tone.
LINEBUSYMODE_TRUNK | The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a “long” busy tone.
LINEBUSYMODE_UNKNOWN | The busy signal’s specific mode is currently unknown, but may become known later.
LINEBUSYMODE_UNAVAIL | The busy signal’s specific mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses the following LINECONNECTEDMODE_ constants:
Value
Description
LINECONNECTEDMODE_ACTIVE | Indicates that the call is connected at the current station (the current station is a participant in the call).
LINECONNECTEDMODE_INACTIVE | Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.

If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses the following LINEDIALTONEMODE_ constants:
Value
Description
LINEDIALTONEMODE_NORMAL | This is a “normal” dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL | This is a special dial tone indicating that a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL | This is an internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL | This is an external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN | The dial tone mode is currently unknown, but may become known later.
LINEDIALTONEMODE_UNAVAIL | The dial tone mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses the following LINEOFFERINGMODE_ constants:
Value
Description
LINEOFFERINGMODE_ACTIVE | Indicates that the call is alerting at the current station (is accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so.
LINEOFFERINGMODE_INACTIVE | Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light).

If dwParam1 is LINECALLSTATE_SPECIALINFO, dwParam2 contains the details about the special information mode. This parameter uses the following LINESPECIALINFO_ constants:
Value
Description
LINESPECIALINFO_NOCIRCUIT | This special information tone precedes a “no circuit” or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG | This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER | This special information tone precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN | Specifics about the special information tone are currently unknown but may become known later.
LINESPECIALINFO_UNAVAIL | Specifics about the special information tone are unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:
Value
Description
LINEDISCONNECTMODE_NORMAL | This is a “normal” disconnect request by the remote party, the call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN | The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT | The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP | The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED | The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY | The remote user’s station is busy.
LINEDISCONNECTMODE_NOANSWER | The remote user’s station does not answer.
LINEDISCONNECTMODE_NODIALTONE | A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a “W” in the dialable string).
LINEDISCONNECTMODE_BADADDRESS | The destination address in invalid.
LINEDISCONNECTMODE_UNREACHABLE | The remote user could not be reached.
LINEDISCONNECTMODE_CONGESTION | The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE | The remote user’s station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL | The reason for the disconnect is unavailable and cannot become known later.

Note In circumstances where a delayed response is appropriate, use LINEDISCONNECTMODE_TEMPFAILURE. Where a blacklisted response is appropriate, use LINEDISCONNECT_BLOCKED.

If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the hConfCall parameter of the parent call of the conference of which the subject hCall is a member. If the call specified in dwParam2 was not previously considered by the application to be a parent conference call (hConfCall), the application must do so as a result of this message. If the application does not have a handle to the parent call of the conference (because it has previously called lineDeallocateCall on that handle) dwParam2 is set to NULL.

dwParam3
If zero, this parameter specifies that there has been no change in the application’s privilege for the call.

If nonzero, it specifies the application’s privilege to the call. This occurs in the following situations: (1) The first time that the application is given a handle to this call; (2) When the application is the target of a call handoff (even if the application already was an owner of the call). This parameter uses the following LINECALLPRIVILEGE_ constants:
Value
Description
LINECALLPRIVILEGE_MONITOR | The application has monitor privilege.
LINECALLPRIVILEGE_OWNER | The application has owner privilege.

Return Values

None.

Remarks

This message is sent to any application that has a handle for the call. The LINE_CALLSTATE message also notifies applications that monitor calls on a line about the existence and state of outbound calls established by other applications or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which is not offering. By examining the call state, the application can determine whether the call is an inbound call that needs to be answered or not.

A LINE_CALLSTATE message with an unknown call state can be sent to a monitoring application as the result of a successful lineMakeCall function that has been requested by another application. At the same time that the requesting application is sent a LINE_REPLY (success) for the requested operation, any monitoring applications on the line are sent the LINE_CALLSTATE (unknown) message. A LINE_CALLSTATE message indicating the “real” call state of the newly generated call is sent (using information provided by the service provider) to the requesting and monitoring applications shortly thereafter.

A LINE_CALLSTATE (unknown) message is sent to monitoring applications only if lineCompleteTransfer causes calls to be resolved into a three-way conference.

For backward compatibility, older applications are not expecting any particular value in dwParam2 of a LINECALLSTATE_CONFERENCED message. TAPI therefore passes the parent call hConfCall in dwParam2 regardless of the API version of the application receiving the message. In the case of a conference call initiated by the service provider, the older application is not aware that the parent call has become a conference call unless it happens to spontaneously examine other information (for example, call lineGetConfRelatedCalls)

This message cannot be disabled.


LINE_CLOSE

This message is sent when the specified line device has been forcibly closed. The line device handle or any call handles for calls on the line are no longer valid once this message has been sent.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_CLOSE dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;

Parameters

dwDevice
Specifies a handle to the line device that was closed. This handle is no longer valid.
dwCallbackInstance
Specifies the callback instance supplied when opening the line.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Return Values

None.

Remarks

The LINE_CLOSE message is only sent to any application after an open line has been forcibly closed. This can be done to prevent a single application from monopolizing a line device for too long. Whether or not the line can be reopened immediately after a forced close is device-specific.

A line device can also be forcibly closed after the user has modified the configuration of that line or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application’s current view of the device (such as a change in device capabilities), then a service provider can forcibly close the line device.


LINE_CREATE

This message is sent to inform the application of the creation of a new line device.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_CREATE dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0; dwParam1 = (DWORD) idDevice;
dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;

Parameters

dwDevice
Unused.
dwCallbackInstance
Unused.
dwParam1
Specifies the dwDeviceID of the newly created device.
dwParam2
Unused.
dwParam3
Unused.

Return Values

None.

Remarks

Older applications (that negotiated TAPI version 1.3) are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REINIT, which requires them to shut down their use of the API and call lineInitialize again to obtain the new number of devices. Unlike previous versions of TAPI, however, this version does not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created (complete shutdown is still required when a service provider is removed from the system).

Applications supporting TAPI version 1.4 or later are sent a LINE_CREATE message. This informs them of the existence of the new device and its new device identifier. The application can then choose whether or not to attempt working with the new device at its leisure. This message is sent to all applications supporting this or subsequent versions of the API that have called lineInitialize or lineInitalizeEx, including those that do not have any line devices open at the time.


LINE_DEVSPECIFIC

This message is sent to notify the application about device-specific events occurring a line, address or call. The meaning of the message and the interpretation of the parameters is device specific.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_DEVSPECIFIC dwDevice = (DWORD) hLineOrCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

dwDevice
Specifies a handle to either a line device or call. This is device specific.
dwCallbackInstance
Specifies the callback instance supplied when opening the line.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

None.

Remarks

The LINE_DEVSPECIFIC message is used by a service provider in conjunction with the lineDevSpecific function. Its meaning is device specific.


LINE_LINEDEVSTATE

This message is sent when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_LINEDEVSTATE dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceState;
dwParam2 = (DWORD) DeviceStateDetail1;
dwParam3 = (DWORD) DeviceStateDetail2;

Parameters

dwDevice
Specifies a handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT.
dwCallbackInstance
Specifies the callback instance supplied when opening the line. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.
dwParam1
Specifies the line device status item that has changed. It can be a combination of the following LINEDEVSTATE_ constants:
Value
Description
LINEDEVSTATE_OTHER | Device status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING | The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED | The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED | This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON | The “message waiting” indicator is turned on.
LINEDEVSTATE_MSGWAITOFF | The “message waiting” indicator is turned off.
LINEDEVSTATE_NUMCOMPLETIONS | The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_INSERVICE | The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE | The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE | Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN | The line has been opened by another application.
LINEDEVSTATE_CLOSE | The line has been closed by another application.
LINEDEVSTATE_NUMCALLS | The number of calls on the line device has changed.
LINEDEVSTATE_TERMINALS | The terminal settings have changed.
LINEDEVSTATE_ROAMMODE | The roaming state of the line device has changed.
LINEDEVSTATE_BATTERY | The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL | The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC | The line’s device-specific information has changed.
LINEDEVSTATE_REINIT | Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices), the application should reinitialize its use of TAPI. The dwDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK | The locked status of the line device has changed. (For more information, refer to the description of the LINEDEVSTATUSFLAGS_LOCKED bit of the LINEDEVSTATUSFLAGS_ constants.)
LINEDEVSTATE_CAPSCHANGE | Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure.
LINEDEVSTATE_CONFIGCHANGE | Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, can use lineGetDevConfig to read the updated information.
LINEDEVSTATE_TRANSLATECHANGE | Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure.
LINEDEVSTATE_COMPLCANCEL | Indicates that the call completion identified by the completion identifier contained in parameter dwParam2 of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid.
LINEDEVSTATE_REMOVED | Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.

dwParam2
Specifies the interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a “real” REINIT message that requires the application to call lineShutdown at its earliest convenience.

dwParam3
Specifies the interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device identifier, if dwParam2 is LINE_CREATE).

Return Values

None.

Remarks

The sending of the LINE_LINEDEVSTATE message can be controlled with lineSetStatusMessages. An application can indicate status item changes about which it wants to be notified. By default, all status reporting is disabled except for LINEDEVSTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the line, including those that called lineOpen with the dwPrivileges parameter set to LINECALLPRIVILEGE_NONE, LINECALLPRIVILEGE_OWNER, LINECALLPRIVILEGE_MONITOR, or permitted combinations of these.

The dwParam1 parameter does not support the following constants:

  • LINEDEVSTATE_MESAGEWAITON
  • LINEDEVSTATE_MESSAGEWAITOFF
  • LINEDEVSTATE_INSERVICE
  • LINEDEVSTATE_OUTOFSERVICE
  • LINEDEVSTATE_MAINTENANCE
  • LINEDEVSTATE_TERMINALS
  • LINEDEVSTATE_ROAMMODE
  • LINEDEVSTATE_BATTERY
  • LINEDEVSTATE_SIGNAL
  • LINEDEVSTATE_LOCK
  • LINEDEVSTATE_COMPLCANCEL

‹See Also

›


LINE_REMOVE

This message is sent to inform an application of the removal, or deletion from the system, of a line device. Generally, this is not used for “temporary” removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_REMOVE dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0; dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;

Parameters

dwDevice
Reserved; set to zero.
dwCallbackInstance
Reserved; set to zero.
dwParam1
Specifies the identifier of the line device that was removed.
dwParam2
Reserved; set to zero.
dwParam3
Reserved; set to zero.

Return Values

None.

Remarks

Applications supporting TAPI version 2.0 or later are sent a LINE_REMOVE message. This informs them that the device has been removed from the system. The LINE_REMOVE message is preceded by a LINE_CLOSE message on each line handle, if the application had the line open. This message is sent to all applications supporting TAPI version 2.0 or later that have called lineInitializeEx, including those that do not have any line devices open at the time.

Older applications are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REMOVED, followed by a LINE_CLOSE message. Unlike the LINE_REMOVE message, however, these older applications can receive these messages only if they have the line open when it is removed. If they do not have the line open, their only indication that the device was removed would be receiving a LINEERR_NODEVICE error when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device identifier results in a LINEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, and when TAPI is reinitialized, the removed device no longer occupies a device identifier.

Implementation Note It is TAPI that returns this LINEERR_NODEVICE; after a LINE_REMOVE message is received from a service provider; no further calls are made to that service provider using that line device identifier.


LINE_REPLY

This message is sent to report the results of function calls that completed asynchronously.

At a Glance

Header file: | Tapi.h
Windows CE versions: | 1.0 and later

Syntax

LINE_REPLY dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idRequest; dwParam2 = (DWORD) Status;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Not used.
dwCallbackInstance
Returns the application’s callback instance.
dwParam1
Specifies the request identifier for which this is the reply.
dwParam2
Specifies the success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.
dwParam3
Unused.

Return Values

None.

Remarks

Functions that operate asynchronously return a positive request identifier value to the application. This request identifier is returned with the reply message to identify the request that was completed. The other parameter for the LINE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.

In some cases, an application may fail to receive the LINE_REPLY message corresponding to a call to an asynchronous function. This occurs if the corresponding call handle is deallocated before the message has been received.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

The LINE_REQUEST message is sent to the highest priority application that has registered for the corresponding request mode. This message indicates the arrival of an Assisted Telephony request of the specified request mode. If dwParam1 is LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL, the application can invoke lineGetRequest using the corresponding request mode to receive the request. If dwParam1 is LINEREQUESTMODE_DROP, the message contains all of the information the request recipient needs to perform the request.


IAdviseSink : IUnknown

This interface enables containers and other objects to receive notifications of data, view, and compound-document changes occurring in objects of interest. Container applications, for example, require such notifications to keep cached presentations of their linked and embedded objects up-to-date. Calls to IAdviseSink methods are asynchronous, so the call is sent and then the next instruction is executed without waiting for the call’s return.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The IAdviseSink interface enables containers and other objects to receive notifications of data changes, view changes, and compound-document changes occurring in objects of interest. Container applications, for example, require such notifications to keep cached presentations of their linked and embedded objects up-to-date. Calls to IAdviseSink methods are asynchronous, so the call is sent and then the next instruction is executed without waiting for the call’s return.

For an advisory connection to exist, the object that is to receive notifications must implement IAdviseSink, and the objects in which it is interested must implement IOleObject::Advise and IDataObject::DAdvise. In-process objects and handlers may also implement IViewObject::SetAdvise. Objects implementing IOleObject must support all reasonable advisory methods. IViewObject (and its advisory methods) is implemented in the default handler.

As shown in the following table, an object that has implemented an advise sink registers its interest in receiving certain types of notifications by calling the appropriate method:

Call This Method
To Register for These Notifications
IOleObject::Advise | When a document is saved, closed, or renamed.
IDataObject::DAdvise | When a document’s data changes.
IViewObject::SetAdvise | When a document’s presentation changes.

When an event occurs that applies to a registered notification type, the object application calls the appropriate IAdviseSink method. For example, when an embedded object closes, it calls the IAdviseSink::OnClose method to notify its container. These notifications are asynchronous, occurring after the events that trigger them.

When to Implement

Objects, such as container applications and compound documents, implement IAdviseSink to receive notification of changes in data, presentation, name, or state of their linked and embedded objects. Implementers register for one or more types of notification, depending on their needs.

Notifications of changes to an embedded object originate in the server and flow to the container by way of the object handler. If the object is a linked object, the OLE link object intercepts the notifications from the object handler and notifies the container directly. All containers, the object handler, and the OLE link object register for OLE notifications. The typical container also registers for view notifications. Data notifications are usually sent to the OLE link object and object handler.

When to Use

Servers call the methods of IAdviseSink to notify objects with which they have an advisory connection of changes in an object’s data, view, name, or state.

Note OLE does not permit synchronous calls in the implementation of asynchronous methods, so you cannot make synchronous calls within any of the the IAdviseSink interface’s methods. For example, an implementation of IAdviseSink::OnDataChange cannot contain a call to IDataObject::GetData.

Method
Description
IAdviseSink::OnClose | Advises the sink that data has changed.
IAdviseSink::OnDataChange | Advises the sink that an object view has changed.
IAdviseSink::OnRename | Advises the sink that an object name has changed.
IAdviseSink::OnSave | Advises the sink that an object has been saved to disk.
IAdviseSink::OnViewChange | Advises the sink that an object has been closed.


IAdviseSink::OnClose

This method advises the sink that data has changed.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

void OnClose();

Return Values

None.

Remarks

OnClose notification indicates that an object is making the transition from the running to the loaded state, so its container can take appropriate measures to ensure orderly shutdown. For example, an object handler must release its pointer to the object.

If the object that is closing is the last open object supported by its OLE server application, the application can also shut down.

In the case of a link object, the notification that the object is closing should always be interpreted to mean that the connection to the link source has broken.


IAdviseSink::OnDataChange

This method advises the sink that an object view has changed.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

void OnDataChange( FORMATETC * pFormatetc, STGMEDIUM * pStgmed );

Parameters

pFormatetc
[in] Pointer to the FORMATETC structure, which describes the format, target device, rendering, and storage information of the calling data object.
pStgmed
[in] Pointer to the STGMEDIUM structure, which defines the storage medium (global memory, disk file, storage object, stream object, GDI object, or undefined) and ownership of that medium for the calling data object.

Return Values

None.

Remarks

Object handlers and containers of link objects implement IAdviseSink::OnDataChange to take appropriate steps when notified that data in the object has changed. They also must call IDataObject::DAdvise to set up advisory connections with the objects in whose data they are interested. (See IDataObject::DAdvise for more information on how to specify an advisory connection for data objects.)

Containers that take advantage of OLE’s caching support do not need to register for data-change notifications, because the information necessary to update the container’s presentation of the object, including any changes in its data, are maintained in the object’s cache.

Notes to Implementers

If you implement IAdviseSink::OnDataChange for a container, remember that this method is asynchronous and that making synchronous calls within asynchronous methods is not valid. Therefore, you cannot call IDataObject::GetData to obtain the data you need to update your object. Instead, you either post an internal message, or invalidate the rectangle for the changed data by calling InvalidateRect and waiting for a WM_PAINT message, at which point you are free to get the data and update the object.

The data itself, which is valid only for the duration of the call, is passed using the storage medium pointed to by pStgmed. Since the caller owns the medium, the advise sink should not free it. Also, if pStgmed points to an IStorage or IStream interface, the sink must not increment the reference count.


IAdviseSink::OnRename

This method advises the sink that an object name has changed.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

void OnRename( IMoniker * pmk );

Parameters

pmk
[in] Pointer to the IMoniker interface on the new full moniker of the object.

Return Values

None.

Remarks

OLE link objects normally implement IAdviseSink::OnRename to receive notification of a change in the name of a link source or its container. The object serving as the link source calls OnRename and passes its new full moniker to the object handler, which forwards the notification to the link object. In response, the link object must update its moniker. The link object, in turn, forwards the notification to its own container.


IAdviseSink::OnSave

This method advises the sink that an object has been saved to disk.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

void OnSave();

Return Values

None.

Remarks

Object handlers and link objects normally implement IAdviseSink::OnSave to receive notifications of when an object is saved to disk, either to its original storage (through a Save operation) or to new storage (through a Save As operation). Object Handlers and link objects register to be notified when an object is saved for the purpose of updating their caches, but then only if the advise flag passed during registration specifies ADVFCACHE_ONSAVE. Object handlers and link objects forward these notifications to their containers.


IAdviseSink::OnViewChange

This method advises the sink that an object has been closed.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

void OnViewChange( DWORD dwAspect, LONG lindex );

Parameters

dwAspect
[in] Specifies the aspect, or view, of the object. Contains a value taken from the enumeration, DVASPECT.
lindex
[in] Portion of the view that has changed. Currently only 1 is valid.

Return Values

None.

Remarks

Containers register to be notified when an object’s view changes by calling IViewObject::SetAdvise. Once registered, the object will call the sink’s IAdviseSink::OnViewChange method when appropriate. OnViewChange can be called when the object is in either the loaded or running state.

Even though DVASPECT values are individual flag bits, dwAspect may represent only one value. That is, dwAspect cannot contain the result of an OR operation combining two or more DVASPECT values.

The lindex member represents the part of the aspect that is of interest. The value of lindex depends on the value of dwAspect. If dwAspect is either DVASPECT_THUMBNAIL or DVASPECT_ICON, lindex is ignored. If dwAspect is DVASPECT_CONTENT, lindex must be 1, which indicates that the entire view is of interest and is the only value that is currently valid.


ICeFileFilter : IUnknown

This interface is implemented by a file converter DLL. Windows CE Services uses OLE to create an instance of an ICeFileFilter object.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Methods
Description
ICeFileFilter::FilterOptions | Displays a dialog box that lets the user select from the options supported by a file filter.
ICeFileFilter::FormatMessage | Formats a message string.
ICeFileFilter::NextConvertFile | Called by Windows CE Services when the user selects a conversion type from the Windows CE Services conversion selection dialog box.


ICeFileFilter::FilterOptions

This method displays a dialog box that lets the user select from the options supported by a file filter.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilter::FilterOptions(HWND hwndParent);

Parameters

hwndParent
Handle to the parent window for the filtering options dialog box.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A file filter that includes user selectable conversion options should implement an ICeFileFilter::FilterOptions method. Windows CE Services calls the filter’s ICeFileFilter::FilterOptions method when the user selects a supported conversion type from the conversion selection dialog box and presses the Options button, which is not supported for Windows CE version 1.0. FilterOptions should display a dialog box that lets the user select from the conversion options supported by the file filter.

A file filter only needs to support the ICeFileFilter::FilterOptions method if the HasOptions named value exists in the \HKEY_CLASSES_ROOT\CLSID\<CLSID>\PegasusFilter key. For more information about file filter registry entries and extension keys, see Transferring Files.


ICeFileFilter::FormatMessage

This method formats a message string.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHOD(FormatMessage) (THIS_ DWORD dwFlags,
DWORD dwMessageId, DWORD dwLanguageId, LPTSTR lpBuffer,
DWORD nSize, va_list *Arguments, DWORD *pcb ) PURE;

Parameters

dwFlags
Contains a set of bit flags that specify aspects of the formatting process and how to interpret the lpSource parameter. The low-order byte of dwFlags specifies how FormatMessage handles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

It can be a combination of the following bit flags:
Value
Description
FORMAT_MESSAGE_ALLOCATE_BUFFER | Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of bytes (ANSI version) or characters (Unicode version) to allocate for an output message buffer. FormatMessage allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed.
FORMAT_MESSAGE_IGNORE_INSERTS | Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for retrieving a message for later formatting. If this flag is set, the Arguments parameter is ignored.
FORMAT_MESSAGE_FROM_STRING | Specifies that lpSource is a pointer to a null-terminated message definition. The message definition can contain insert sequences, just as the message text in a message table resource can. This flag cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM.
FORMAT_MESSAGE_FROM_HMODULE | Specifies that lpSource is a module handle containing the message table resources to search. If this lpSource handle is NULL, the current process’s application image file is searched. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.
FORMAT_MESSAGE_FROM_SYSTEM | Specifies that FormatMessage should search the system message table resources for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, FormatMessage searches the system message table if the message is not found in the module specified by lpSource. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.
If this flag is specified, an application can pass the result of the CeGetLastError function to retrieve the message text for a system-defined error.
FORMAT_MESSAGE_ARGUMENT_ARRAY | Specifies that the Arguments parameter is not a va_list structure, but instead is pointer to an array of 32-bit values that represent the arguments.

The low-order byte of dwFlags can specify the maximum width of a formatted output line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations to set and retrieve this maximum width value.

FormatMessage interprets the value of the low-order byte as follows:
Value
Description
0 | There are no output line width restrictions. FormatMessage stores line breaks that are in the message definition text in the output buffer.
A nonzero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK | The nonzero value is the maximum number of characters in an output line. FormatMessage ignores regular line breaks in the message definition text. FormatMessage never splits a string delimited by white space across a line break. FormatMessage stores hard-coded line breaks in the message definition text in the output buffer. Hard-coded line breaks are coded with the %n escape sequence.
FORMAT_MESSAGE_MAX_WIDTH_MASK | FormatMessage ignores regular line breaks in the message definition text. FormatMessage stores hard-coded line breaks in the message definition text in the output buffer. FormatMessage generates no new line breaks.

dwMessageId
Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
dwLanguageId
Specifies the 32-bit language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
lpBuffer
Long pointer to a buffer for the formatted and null-terminated message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, FormatMessage allocates a buffer using the LocalAlloc function, and places the address of the buffer at the address specified in lpBuffer.
nSize
If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the maximum number of bytes (ANSI version) or characters (Unicode version) that can be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of bytes or characters to allocate for an output buffer.
Arguments
Pointer to an array of 32-bit values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the Arguments array, %2 indicates the second argument, and so on.

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string.

By default, the Arguments parameter is of type va_list *, which is a language- and implementation-specific data type for describing a variable number of arguments. If you do not have a pointer of type va_list *, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 32-bit values; those values are used as input for the message and are formatted as the insert values. Each insert must have a corresponding element in the array.

pcb
Pointer to a DWORD that receives the length of the string returned by FormatMessage. If FormatMessage succeeds, pcb holds the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | FormatMessage was successful. The variable pointed to by the pcb parameter should be non-zero.
E_FAIL | FormatMessage failed.

Remarks

The FormatMessage method requires a message definition as input. The message definition can come from a buffer passed into FormatMessage, from a message table resource in an already-loaded module, or the caller can prompt FormatMessage to search the system’s message table resources. FormatMessage finds the message definition in a message table resource based on a message identifier and a language identifier. FormatMessage copies the formatted message text to an output buffer, processing any embedded insert sequences if requested. FormatMessage also allows the filter to define message codes specific to the filter. For more information, see Transferring Files.


ICeFileFilter::NextConvertFile

This method is called by Windows CE Services when the user selects a conversion type from the Windows CE Services conversion selection dialog box.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilter::NextConvertFile(
int nConversion, PFF_CONVERTINFO *pci, PFF_SOURCEFILE *psf,
PFF_DESTINATIONFILE *pdf, volatile BOOL *pbCancel,
PR_ERROR *perr );

Parameters

nConversion
Counter for converting a single source file into multiple destination files. This parameter is zero the first time NextConvertFile is called and is incremented for each successive call. A simple filter should return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) if this parameter is not zero.
pci
Pointer to a CFF_CONVERTINFO structure that contains a pointer to an ICeFileFilterSite object. A file filter uses this interface to create an IStream or IStorage object to read the contents of the source file or to write to the destination file. The type of interface object to create is determined by the nHowToOpen parameter in the ICeFileFilterSite::OpenSourceFile and ICeFileFilterSite::OpenDestinationFile methods. Any files opened in this way should be closed using the corresponding ICeFileFilterSite::CloseSourceFile or ICeFileFilterSite::CloseDestinationFile method.
psf
Pointer to a CFF_SOURCEFILE structure that contains information about the source file.
pdf
Pointer to a CFF_DESTINATIONFILE structure that contains information about the destination file.
pbCancel
Pointer to a Boolean that is set to TRUE if the user cancels the file conversion before it is completed, or set to FALSE otherwise. Because this variable is updated asynchronously by another thread, its contents can change at any time. A file filter must check this variable regularly during the conversion process, and return ERROR_CANCELLED, after cleaning up, if it is ever set to TRUE.
perr
Pointer to a filter-defined error value that can be passed by the Windows CE Services application to the ICeFileFilter::FormatMessage method. This error value is ignored unless the return value from NextConvertFile is E_FAIL.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The subconversion was successful; proceed to the next subconversion.
HRESULT_FROM_WIN32 (ERROR_CANCELLED) | The user canceled the conversion.
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS) | The conversion, or last subconversion, was successful. End calls to ICeFileFilter::NextConvertFile.
E_FAIL | The perr parameter contained an error value that should be passed to ICeFileFilter::FormatMessage.

Remarks

The Explorer window for the mobile device calls the ICeFileFilter::NextConvertFile method repeatedly, incrementing the nConversion parameter, until the return value is ERROR_NO_MORE_ITEMS. A simple filter should return NOERROR the first time this method is called, and thereafter return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS). Alternatively, a file filter can return E_FAIL and specify a filter-defined error value in the variable pointed to by perr.

As a file conversion progresses, a file filter should periodically call ICeFileFilterSite::ReportProgress to report its progress. Windows CE Services uses the progress information to update a progress bar that shows the user how much of the conversion is complete.

If any important data is intentionally discarded by a file filter during the conversion process, the filter should call ICeFileFilterSite::ReportLoss to report the loss. When calling this ReportLoss, the filter specifies a message that explains the data loss, and Windows CE Services formats and displays the message in a message box when the file conversion has completed. For more information, see Transferring Files.

See Also

ICeFileFilterSite::ReportLoss, ICeFileFilterSite::ReportProgress


ICeFileFilterOptions : IUnknown

This interface is optionally implemented by a version 2.0 file converter dynamic-link library (DLL).

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Methods
Description
ICEFileFilterOptions:SetFilterOptions Sets the filter options using a pointer to the CFF_CONVERTOPTIONS structure


ICeFileFilterOptions::SetFilterOptions

This method sets the filter options using a pointer to the CFF_CONVERTOPTIONS structure.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ICeFileFilterOptions::SetFilterOptions(
CFF_CONVERTOPTIONS *pco );

Parameters

pco
Pointer to the CFF_CONVERTOPTIONS structure.

Return Values

An appropriate HRESULT value is returned.

Remarks

Initialize the CFF_CONVERTIOPTIONS parameter by setting the cbSize member and the appropriate members before calling the ICeFileFilterOptions::SetFilterOptions method.


ICeFileFilterSite : IUnknown

This interface is implemented by the Explorer Window for the mobile device. A pointer to this interface will be passed to some file filter methods.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Methods
Description
ICeFileFilterSite::OpenSourceFile | Called by a file filter to open a source file.
ICeFileFilterSite::OpenDestinationFile | Called by a file filter to open a destination file.
ICeFileFilterSite::CloseSourceFile | Called by a file filter to close a source file.
ICeFileFilterSite::CloseDestinationFile | Called by a file filter to close a destination file.
ICeFileFilterSite::ReportProgress | Called by a file filter to report the progress of a file conversion.
ICeFileFilterSite::ReportLoss | Called by a file filter to report any information that it intentionally discarded during a file conversion. The file filter specifies a message that explains the data loss, and Windows CE Services formats and displays the message in a message box when the file conversion is complete. The file filter can specify either the identifier of a message table resource, or the address of a buffer that contains the message string.


ICeFileFilterSite::CloseDestinationFile

This method is called by a file filter to close a destination file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilterSite::CloseDestinationFile(
BOOL bKeepFile, LPUNKNOWN pObj );

Parameters

bKeepFile
Boolean value that indicates whether to keep or delete the destination file. A file filter should set this parameter to TRUE to keep the destination file, or FALSE to delete it.
pObj
Pointer to an IUnknown object returned from the ICeFileFilterSite::OpenDestinationFile method.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.


ICEFileFilterSite::CloseSourceFile

This method is called by a file filter to close a source file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilterSite::CloseSourceFile(
LPUNKNOWN pObj );

Parameters

pObj
Pointer to the IUnknown object returned from the ICeFileFilterSite::OpenSourceFile method.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.


ICeFileFilterSite::OpenDestinationFile

This method is called by a file filter to open a destination file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilterSite::OpenDestinationFile(
int nHowToOpenFile, LPCSTR pszFullpath, LPVOID *ppObj );

Parameters

nHowToOpenFile
Specifies how the source file is to be opened. It is one of the following values:
Value
Description
PF_OPENFLAT | Open as a flat file.
PF_OPENCOMPOUND | Open as an OLE compound file. Note that Windows CE does not support compound files.

pszFullpath
Pointer to the null-terminated string that contains the name of the file to open to override the default destination file name. If this parameter is NULL, the default destination file name is used.
ppObj
Pointer to an LPVOID variable that receives an IStream pointer if nHowToOpenFile is PF_OPENFLAT, or an IStorage pointer if nHowToOpenFile is PF_OPENCOMPOUND. This object must be released using the ICeFileFilterSite::CloseDestinationFile method before returning to H/PC Explorer.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.

Remarks

The default destination file name and path are specified in the CFF_DESTINATIONFILE structure is passed in to the call to ICeFileFilter::NextConvertFile. The default path is temporary and is managed by Windows CE Services. For example, if the user drags a bitmap file named Tmp.bmp from the desktop computer to the mobile device, the default destination file name is Tmp.2bp.

The following code example shows how the destination file can be modified when the file filter’s ICeFileFilter::NextConvertFile method calls the ICeFileFilterSite::OpenDestinationFile method.

// Filter and copy Tmp.bmp on desktop computer to Tmp1.2bp on Windows CE-based device
CFF_DESTINATIONFILE *pdf;
IStream *pstmDst; // Open the destination file as a stream
TCHAR szBuf[80];

lstrcpy(szBuf, pdf->szPath); // Use default path …
lstrcat(szBuf, TEXT("TMP1.2bp") ); // … but Modify the file name

hres = cffs->OpenDestinationFile(PF_OPENFLAT, szBuf, (LPVOID*)&pstmDst);

In this example, note that the path to the directory containing the temporary destination was preserved. The reason is that, after the file filter conversion is complete—that is, NextConvertFile has returned ERROR_NO_MORE_ITEMS—Windows CE Services looks in szPath and copies all files, regardless of file or extension name, to the target folder, as directed by the user.

The temporary destination file path must be located on the desktop computer, but the path can be modified as desired.

Note that OpenDestinationFile can be called only once within a specified call to ICeFileFilter::NextConvertFile.

See Also

ICeFileFilterSite::CloseDestinationFile


ICeFileFilterSite::OpenSourceFile

This method is called by a file filter to open a source file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilterSite::OpenSourceFile(
int nHowToOpenFile, LPVOID *ppObj );

Parameters

nHowToOpenFile
Specifies how the source file is to be opened. It is one of the following values:
Value
Description
PF_OPENFLAT | Open as a flat file.
PF_OPENCOMPOUND | Open as an OLE compound file. Note that Windows CE does not support compound files.

ppObj
Pointer to an LPVOID variable that receives an IStream pointer if nHowToOpenFile is PF_OPENFLAT, or an IStorage pointer if nHowToOpenFile is PF_OPENCOMPOUND. This object must be released using the ICeFileFilterSite::CloseSourceFile method before returning to H/PC Explorer.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.

Remarks

The ICeFileFilterSite::OpenSourceFile method opens the file specifed by the CFF_SOURCEFILE structure. Windows CE Explorer passes a pointer to this structure in the call to the file filter’s ICeFileFilter::NextConvertFile method.

See Also

ICeFileFilter::NextConvertFile


ICeFileFilterSite::ReportLoss

This method is called by a file filter to report any information that it intentionally discarded during a file conversion. The file filter specifies a message that explains the data loss, and Windows CE Services formats and displays the message in a message box when the file conversion is complete. The file filter can specify either the identifier of a message table resource, or the address of a buffer that contains the message string.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilterSite::ReportLoss( DWORD dw,
LPCTSTR psz, va_list * Arguments );

Parameters

dw
Specifies a 32-bit message identifier. ReportLoss uses ICeFileFilter::FormatMessage to format the message. If the format fails—for example, the message identifier could not be recognized—then the system function FormatMessage is used.
psz
Pointer to the null-terminated message string to display. This parameter should be NULL if the dw parameter is used.
Arguments
Pointer to an array of 32-bit values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the Arguments array, %2 indicates the second argument, and so on.

Return Values

None.

Remarks

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string. By default, the Arguments parameter is of type va_list*, which is a language- and implementation-specific data type for describing a variable number of arguments.

If the Win32 error value—passed in the dw parameter of the ICeFileFilterSite::ReportLoss method—to be formatted with FormatMessage is not NULL, then the Windows CE Explorer first calls the file filter’s ICeFileFilter::FormatMessage method—that is, in the current module—to request a description of the error. If the file filter’s FormatMessage fails, then the Windows CE Explorer attempts to identify the error using the system FormatMessage call.

If dw is NULL, then the strings passed in the psz and Arguments parameters are reported in a message by Windows CE Services when the file conversion is complete. Note that only one of the parameters dw or psz should not be NULL. That is, either a message identifier or a message string may be passed in the call to ReportLoss.


ICeFileFilterSite::ReportProgress

This method is called by a file filter to report the progress of a file conversion.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

STDMETHODIMP ICeFileFilterSite::ReportProgress( UINT nPercent );

Parameters

nPercent
Specifies the completed percentage of the operation. For example, if the file filter has converted 25 percent of a file, this parameter should be set to 25.

Return Values

None.

Remarks

Windows CE Services displays a progress bar that indicates the progress of a file conversion, and uses the percentage provided by the filter to set the current position of the progress bar. The filter should periodically call ReportProgress as the conversion progresses.

Consider that updating the progress bar takes a certain amount of time. Therefore, you may want to limit the frequency at which the application calls the ReportProgress method, since calling this method too often can add substantially the actual file copy and conversion time.


IClassFactory : IUnknown

Because this interface contains two methods intended to deal with an entire class of objects, it is implemented on the class object for a specific class of objects, identified by a class identifier (CLSID).

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Method
Description
IClassFactory::CreateInstance | Creates an uninitialized object of a specified class identifier (CLSID).
IClassFactory::LockServer | Locks an object application open in memory. This allows new objects to be created more quickly.

When to Implement

You must implement this interface for every class that you register in the system registry and to which you assign a CLSID, so objects of that class can be created.

When to Use

After calling the CoGetClassObject function to get an IClassFactory interface pointer to the class object, call the CreateInstance method of this interface to create a new uninitialized object.

It is not, however, always necessary to go through this process to create an object. To create a single uninitialized object, you can, instead, just call CoCreateInstance. OLE also provides numerous helper functions (with names of the form OleCreate Xxx) to create compound document objects.

Call the LockServer method to keep the object server in memory and enhance performance only if you intend to create more than one object of the specified class.


IClassFactory::CreateInstance

This method creates an uninitialized object of a specified class identifier (CLSID).

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CreateInstance( IUnknown *pUnkOuter, REFIID iid,
void ** ppvObj );

Parameters

pUnkOuter
[in] If the object is being created as part of an aggregate, pointer to the controlling IUnknown interface of the aggregate. Otherwise, pUnkOuter must be NULL.
riid
[in] Reference to the identifier of the interface to be used to communicate with the newly created object. If pUnkOuter is NULL, this parameter is frequently the IID of the initializing interface; if pUnkOuter is non-NULL, riid must be IID_IUnknown (defined in the header as the IID for IUnknown).
ppvObject
[out] Pointer to a pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObject contains the requested interface pointer. If the object does not support the interface specified in riid, the implementation must set *ppvObject to NULL.

Return Values

This method supports the standard return values E_UNEXPECTED, E_OUTOFMEMORY, and E_INVALIDARG, as well as the values described in the following table.

Value
Description
S_OK | The specified object was created.
CLASS_E_NOAGGREGATION | The pUnkOuter parameter was non-NULL and the object does not support aggregation.
E_NOINTERFACE | The object that ppvObject points to does not support the interface identified by riid.

Remarks

The IClassFactory interface is always on a class object. The CreateInstance method creates an uninitialized object of the class identified with the specified CLSID. When an object is created in this way, the CLSID must be registered in the system registry with CoRegisterClassObject.

The pUnkOuter parameter indicates whether the object is being created as part of an aggregate. Object definitions are not required to support aggregation—they must be specifically designed and implemented to support it.

The riid parameter specifies the interface identifier (IID) of the interface through which you will communicate with the new object. If pUnkOuter is non-NULL (that indicates aggregation), the value of the riid parameter must be IID_IUnknown. If the object is not part of an aggregate, riid often specifies the interface though which the object will be initialized.

For OLE embeddings, the initialization interface is IPersistStorage, but in other situations, other interfaces are used. To initialize the object, there must be a subsequent call to an appropriate method in the initializing interface. Common initialization functions include IPersistStorage::InitNew (for new, blank embeddable components), IPersistStorage::Load (for reloaded embeddable components),

In general, if an application supports only one class of objects, and the class object is registered for single use, only one object can be created. The application must not create other objects, and a request to do so should return an error from IClassFactory::CreateInstance. The same is true for applications that support multiple classes, each with a class object registered for single use; a CreateInstance for one class followed by a CreateInstance for any of the classes should return an error.


IClassFactory::LockServer

This method locks an object application open in memory. This allows new objects to be created more quickly.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESUTL LockServer( BOOL fLock );

Parameters

fLock
[in] Boolean value that is set to TRUE to increment the lock count, or to FALSE to decrements the lock count.

Return Values

This method supports the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, as well as S_OK, which indicates that the specified object was either locked ( fLock = TRUE) or unlocked from memory ( fLock = FALSE).

Remarks

IClassFactory::LockServer controls whether an object’s server is kept in memory. Keeping the application alive in memory allows instances to be created more quickly.

Notes to Callers

Most clients do not need to call this function. It is provided only for those clients that require special performance in creating multiple instances of their objects.

Notes to Implementers

If the lock count is zero, there are no more objects in use, and the application is not under user control, the server can be closed.

The process that locks the object application is responsible for unlocking it. Once the class object is released, there is no mechanism that guarantees the caller connection to the same class later (as in the case where a class object is registered as single-use). It is important to count all calls, not just the last one, to IClassFactory::LockServer, because calls must be balanced before attempting to release the pointer to the IClassFactory interface on the class object or an error results. For every call to LockServer with fLock set to TRUE, there must be a call to LockServer with fLock set to FALSE. When the lock count and the class object reference count are both zero, the class object can be freed.


ICreateErrorInfo : IUnknown

This interface returns error information.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The ICreateErrorInfo interface returns error information.

Implemented by
Used by
Header filename
Import library name
Oleaut32.dll
(32-bit systems)

Oledisp.dll
(16-bit systems)

 Applications that return rich error information. Oleauto.h

Dispatch.h

 Oleaut32.lib

Oledisp.lib

Method
Description
ICreateErrorInfo::SetDescription | Sets a textual description of the error.
ICreateErrorInfo::SetGUID | Sets the globally unique identifier (GUID) of the interface that defined the error.
ICreateErrorInfo::SetHelpContext | Sets the Help context identifier for the error.
ICreateErrorInfo::SetHelpFile | Sets the path of the Help file that describes the error.
ICreateErrorInfo::SetSource | Sets the language-dependent programmatic identifier for the class or application that raised the error.


ICreateErrorInfo::SetDescription

This method sets a textual description of the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetDescription( LPCOLESTR *szDescription );

Parameters

szDescription
Brief, null-terminated string that describes the error.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

Remarks

The text should be supplied in the language specified by the locale identifier (LCID) that was passed to the method raising the error.

Example

hr = CreateErrorInfo(&pcerrinfo);
if (m_excepinfo.bstrDescription)
 pcerrinfo->SetDescription(m_excepinfo.bstrDescription);


ICreateErrorInfo::SetGUID

This method sets the globally unique identifier (GUID) of the interface that defined the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetGUID( REFGUID rguid );

Parameters

rguid
GUID of the interface that defined the error, or GUID_NULL if the error was defined by the operating system.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

Remarks

ICreateErrorInfo::SetGUID sets the GUID of the interface that defined the error. If the error was defined by the system, set ICreateErrorInfo::SetGUID to GUID_NULL.

This GUID does not necessarily represent the source of the error; however, the source is the class or application that raised the error. Using the GUID, applications can handle errors in an interface, independent of the class that implements the interface.

Example

hr = CreateErrorInfo(&pcerrinfo);
pcerrinfo->SetGUID(IID_IHello);


ICreateErrorInfo::SetHelpContext

This method sets the Help context identifier for the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpContext( DWORD dwHelpContext );

Parameters

dwHelpContext
Specifies the Help context identifier for the error.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

Remarks

ICreateErrorInfo::SetHelpContext sets the Help context identifier for the error. To establish the Help file to which it applies, use ICreateErrorInfo::SetHelpFile.

Example

hr = CreateErrorInfo(&pcerrinfo);
pcerrinfo->SetHelpContext(dwhelpcontext);


ICreateErrorInfo::SetHelpFile

This method sets the path of the Help file that describes the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpFile( LPCOLESTR szHelpFile );

Parameters

szHelpFile
Null-terminated string that contains the fully qualified path of the Help file that describes the error.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

Remarks

ICreateErrorInfo::SetHelpFile sets the fully qualified path of the Help file that describes the current error. Use ICreateErrorInfo::SetHelpContext to set the Help context identifier for the error in the Help file.

Example

hr = CreateErrorInfo(&pcerrinfo);
pcerrinfo->SetHelpFile(“C:\myapp\myapp.hlp”);


ICreateErrorInfo::SetSource

This method sets the language-dependent programmatic identifier for the class or application that raised the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetSource( LPCOLESTR szSource );

Parameters

szSource
Null-terminated string that contains the programmatic identifier in the form progname.objectname.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

Remarks

ICreateErrorInfo::SetSource should be used to identify the class or application that is the source of the error. The language for the returned programmatic identifierdepends on the locale identifier (LCID) that was passed to the method at the time of invocation.

Example

hr = CreateErrorInfo(&pcerrinfo);
if (m_excepinfo.bstrSource)
 pcerrinfo->SetSource(m_excepinfo.bstrSource);


ICreateTypeInfo : IUnknown

This interface provides the tools for creating and administering the type information defined through the type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Method
Description
ICreateTypeInfo::AddFuncDesc | Adds a function description as a type description.
ICreateTypeInfo::AddImplType | Specifies an inherited interface.
ICreateTypeInfo::AddRefTypeInfo | Adds a type description to those referenced by the type description being created.
ICreateTypeInfo::AddVarDesc | Adds a data member description as a type description.
ICreateTypeInfo::DefineFuncAsDllEntry | Associates a dynamic-link library (DLL) entry point with a function that has a specified index.
ICreateTypeInfo::LayOut | Assigns virtual function table (VTBL) offsets for virtual functions and instance offsets for per-instance data members.
ICreateTypeInfo::SetAlignment | Specifies data alignment for types of TKIND_RECORD.
ICreateTypeInfo::SetDocString | Sets the documentation string displayed by type browsers.
ICreateTypeInfo::SetFuncAndParamNames | Sets the function name and names of its parameters.
ICreateTypeInfo::SetFuncDocString | Sets the documentation string for a function.
ICreateTypeInfo::SetFuncHelpContext | Sets the Help context identifier for a function.
ICreateTypeInfo::SetGuid | Sets the globally unique identifier (GUID) for the type library.
ICreateTypeInfo::SetHelpContext | Sets the Help context identifier of the type description.
ICreateTypeInfo::SetImplTypeFlags | Sets the attributes for an implemented or inherited interface of a type.
ICreateTypeInfo::SetMops | Sets the opcode string for a type description.
ICreateTypeInfo::SetTypeDescAlias | Sets the type description for which this type description is an alias, if TYPEKIND=TKIND_ALIAS.
ICreateTypeInfo::SetTypeFlags | Sets type flags of the type description that is being created.
ICreateTypeInfo::SetVarDocString | Sets the documentation string for a variable.
ICreateTypeInfo::SetVarHelpContext | Sets the Help context identifier for a variable.
ICreateTypeInfo::SetVarName | Sets the name of a variable.
ICreateTypeInfo::SetVersion | Sets version numbers for the type description.


ICreateTypeInfo::AddFuncDesc

This method adds a function description as a type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT AddFuncDesc( unsigned int index, FUNCDESC FAR* pFuncDesc );

Parameters

index
Index of the new FUNCDESC in the type information.
pFuncDesc
Pointer to a FUNCDESC structure that describes the function. The bstrIDLInfo member in the FUNCDESC should be set to NULL for future compatibility.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The index specifies the order of the functions within the type information. The first function has an index of zero. If an index is specified that exceeds one less than the number of functions in the type information, an error is returned. Calling this function does not pass ownership of the FUNCDESC structure to ICreateTypeInfo. Therefore, the caller must still de-allocate the FUNCDESC structure.

The passed-in virtual function table (VTBL) member (oVft) of the FUNCDESC is ignored. This attribute is set when ICreateTypeInfo::LayOut is called.

The function AddFuncDesc uses the passed-in member identifier members within each FUNCDESC for classes with TYPEKIND = TKIND_DISPATCH or TKIND_INTERFACE. If the member identifiers are set to MEMBERID_NIL, AddFuncDesc assigns member identifiers to the functions. Otherwise, the member identifier members within each FUNCDESC are ignored.

Any HREFTYPE members in the FUNCDESC structure must have been produced by the same instance of ITypeInfo for which AddFuncDesc is called.

The get and put accessor functions for the same property must have the same dispatch identifier (DISPID).


ICreateTypeInfo::AddImplType

This method specifies an inherited interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT AddImplType( unsigned int index, HREFTYPE hRefType);

Parameters

index
Index of the implementation class to be added. Specifies the order of the type relative to the other type.
hRefType
Handle to the referenced type description obtained from the AddRefType description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

To specify an inherited interface, use index = 0. For a dispinterface with Syntax 2, call ICreateTypeInfo::AddImplType twice, once with nindex = 0 for the inherited IDispatch and once with nindex = 1 for the interface that is being wrapped. For a dual interface, call ICreateTypeInfo::AddImplType with nindex = 1 for the TKIND_INTERFACE type information component of the dual interface.


ICreateTypeInfo::AddRefTypeInfo

This method adds a type description to those referenced by the type description being created.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT AddRefTypeInfo( ITypeInfo FAR* pTInfo,
HREFTYPE FAR* phRefType );

Parameters

pTInfo
Pointer to the type description to be referenced.
phRefType
On return, pointer to the handle that this type description associates with the referenced type information.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The second parameter returns a pointer to the handle to the added type information. If AddRefTypeInfo has been called previously for the same type information, the index that was returned by the previous call is returned in phRefType. If the referenced type description is in the type library being created, its type information can be obtained by calling IUnknown::QueryInterface(IID_ITypeInfo, ...) on the ICreateTypeInfo interface of that type description.


ICreateTypeInfo::AddVarDesc

This method adds a data member description as a type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT AddVarDesc( unsigned int index, VARDESC FAR* pVarDesc);

Parameters

index
Index of the variable or data member to be added to the type description.
pVarDesc
Pointer to the variable or data member description to be added.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The index specifies the order of the variables. The first variable has an index of zero. ICreateTypeInfo::AddVarDesc returns an error if the specified index is greater than the number of variables currently in the type information. Calling this function does not pass ownership of the VARDESC structure to ICreateTypeInfo. The instance member (oInst) of the VARDESC structure is ignored. This attribute is set only when ICreateTypeInfo::LayOut is called. Also, the member identifier members within the VARDESC structures are ignored unless the TYPEKIND of the class is TKIND_DISPATCH.

Any HREFTYPE members in the VARDESC structure must have been produced by the same instance of ITypeInfo for which AddVarDesc is called.

AddVarDesc ignores the contents of the idldesc member of the ELEMDESC.


ICreateTypeInfo::DefineFuncAsDllEntry

This method associates a dynamic-link library (DLL) entry point with a function that has a specified index.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DefineFuncAsDllEntry( unsigned int index,
OLECHAR FAR* szDllName, OLECHAR FAR* szProcName );

Parameters

index
Index of the function.
szDllName
NULL-terminated string that contains the name of the DLL that contains the entry point.
szProcName
NULL-terminated string that contains the name of the entry point or an ordinal (if the high-order word is zero).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

If the high-order word of szProcName is zero, then the low-order word must contain the ordinal of the entry point; otherwise, szProcName points to the null-terminated name of the entry point.


ICreateTypeInfo::LayOut

This method assigns virtual function table (VTBL) offsets for virtual functions and instance offsets for per-instance data members.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT LayOut();

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_UNDEFINEDTYPE | Bound to unrecognized type.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.
TYPE_E_WRONGTYPEKIND | Type mismatch.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.
TYPE_E_AMBIGUOUSNAME | More than one item exists with this name.
TYPE_E_SIZETOOBIG | The type information is too long.
TYPE_E_TYPEMISMATCH | Type mismatch.

Remarks

LayOut also assigns member identifier numbers to the functions and variables, unless the TYPEKIND of the class is TKIND_DISPATCH. Call LayOut after all members of the type information are defined, and before the type library is saved.

Other members of the ICreateTypeInfo interface should not be called after calling LayOut.

Different implementations of ICreateTypeInfo or other interfaces that create type information are free to assign any member identifier numbers, provided that all members (including inherited members), have unique identifiers. For examples, see the ICreateTypeInfo2 interface later in this chapter.


ICreateTypeInfo::SetAlignment

This method specifies data alignment for types of TKIND_RECORD.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetAlignment( unsigned short cbAlignment );

Parameter

cbAlignment
Alignment method for the type. A value of 0 indicates alignment on the 64K boundary; 1 indicates no special alignment. For other values, n indicates alignment on byte n.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.

Remarks

The alignment is the minimum of the natural alignment (for example, byte data on byte boundaries, word data on word boundaries, and so on), and the alignment denoted by cbAlignment.


ICreateTypeInfo::SetDocString

This method sets the documentation string displayed by type browsers.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetDocString( OLECHAR FAR* pStrDoc );

Parameters

pStrDoc
Pointer to the documentation string.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.

Remarks

The documentation string is a brief description of the type description being created.


ICreateTypeInfo::SetFuncAndParamNames

This method sets the function name and names of its parameters.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetFuncAndParamNames( unsigned int index,
OLECHAR FAR* FAR* rgszNames, unsigned int cNames);

Parameters

index
Index of the function whose function name and parameter names are to be set.
rgszNames
Array of pointers to names. The first element is the function name. Subsequent elements are names of parameters.
cNames
Number of elements in the rgszNames array.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.

Remarks

The function SetFuncAndParamNames needs to be used once for each property. The last parameter for put and putref accessor functions is unnamed.


ICreateTypeInfo::SetFuncDocString

This method sets the documentation string for a function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetFuncDocString(unsigned int index,
OLECHAR FAR* szDocString);

Parameters

index
Index of the function.
szDocString
NULL-terminated documentation string.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.

Remarks

The documentation string is a brief description of the function intended for use by tools such as type browsers. SetFuncDocString only needs to be used once for each property, because all property accessor functions are identified by one name.


ICreateTypeInfo::SetFuncHelpContext

This method sets the Help context identifier for a function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetFuncHelpContext( unsigned int index,
unsigned long dwHelpContext);

Parameters

index
Index of the function.
dwHelpContext
Specifies the Help context identifier for the Help topic.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.
E_INVALIDARG | One or more of the parameters is invalid.

Remarks

SetFuncHelpContext only needs to be set once for each property, because all property accessor functions are identified by one name.


ICreateTypeInfo::SetGuid

This method sets the globally unique identifier (GUID) for the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetGuid( REFGUID guid );

Parameters

guid
GUID to be associated with the type description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.

Remarks

For an interface, this is an interface identifier (IID); for a coclass, it is a class identifier (CLSID).


ICreateTypeInfo::SetHelpContext

This method sets the Help context identifier of the type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpContext( unsigned long dwHelpContext );

Parameters

dwHelpContext
Specifies the handle to the Help context.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.


ICreateTypeInfo::SetImplTypeFlags

This method sets the attributes for an implemented or inherited interface of a type.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetImplTypeFlags( unsigned int index, int implTypeFlags);

Parameters

index
Index of the interface for which to set type flags.
implTypeFlags
IMPLTYPE flags to be set.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.

Remarks

SetImplTypeFlags sets the IMPLTYPE flags for the indexed interface.


ICreateTypeInfo::SetMops

This method sets the opcode string for a type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetMops( unsigned int index, BSTR bstrMops );

Parameters

index
Index of the member for which to set the opcode string. If index is –1, sets the opcode string for the type description.
bstrMops
Marshaling opcode string.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.


ICreateTypeInfo::SetTypeDescAlias

This method sets the type description for which this type description is an alias, if TYPEKIND=TKIND_ALIAS.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetTypeDescAlias( TYPEDESC FAR* pTDescAlias);

Parameters

pTDescAlias
Pointer to a type description that describes the type for which this is an alias.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

To set the type for an alias, call SetTypeDescAlias for a type description whose TYPEKIND is TKIND_ALIAS.


ICreateTypeInfo::SetTypeFlags

This method sets type flags of the type description that is being created.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetTypeFlags( unsigned int uTypeFlags );

Parameters

uTypeFlags
Settings for the type flags.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

Use SetTypeFlags to set the flags for the type description.


ICreateTypeInfo::SetVarDocString

This method sets the documentation string for a variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVarDocString( unsigned int index,
OLECHAR FAR* szDocString);

Parameters

index
Index of the variable being documented.
szDocString
NULL-terminated documentation string to be set.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_ELEMENTNOTFOUND | The element was not found.


ICreateTypeInfo::SetVarHelpContext

This method sets the Help context identifier for a variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVarHelpContext( unsigned int index,
unsigned long dwHelpContext );

Parameters

index
Index of the variable described by the type description.
dwHelpContext
Specifies the handle to the Help context identifier for the Help topic on the variable.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.


ICreateTypeInfo::SetVarName

This method sets the name of a variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVarName( unsigned int index, OLECHAR FAR* szName);

Parameters

index
Index of the variable whose name is being set.
szName
NULL-terminated string that contains the name for the variable.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_ELEMENTNOTFOUND | The element cannot be found.


ICreateTypeInfo::SetVersion

This method sets version numbers for the type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVersion( unsigned short wMajorVerNum,
unsigned short wMinorVerNum);

Parameters

wMajorVerNum
Major version number for the type.
wMinorVerNum
Minor version number for the type.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_ACCESSDENIED | Cannot write to the destination.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


ICreateTypeInfo2 : ICreateTypeInfo

This interface derives from ICreateTypeInfo and adds methods for deleting items that have been added through ICreateTypeInfo.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The ICreateTypeInfo2 interface derives from ICreateTypeInfo, and adds methods for deleting items that have been added through ICreateTypeInfo.

The ICreateTypeInfo::LayOut method provides a way for the creator of the type information to check for any errors. A call to QueryInterface() can be made to the ICreateTypeInfo instance at any time for its ITypeInfo interface. Calling any of the methods in the ITypeInfo interface that require layout information lays out the type information automatically.

Example

interface ICreateTypeInfo2 : ICreateTypeInfo
Method
Description
ICreateTypeInfo2::DeleteFuncDesc | Deletes a function description specified by the index number.
ICreateTypeInfo2::SetName | Sets the name of the typeinfo.
ICreateTypeInfo2::DeleteFuncDescByMemId | Deletes the function description specified by member identifier.
ICreateTypeInfo2::DeleteVarDesc | Deletes the specified VARDESC structure.
ICreateTypeInfo2::DeleteVarDescByMemId | Deletes the specified VARDESC structure.
ICreateTypeInfo2::DeleteImplType | Deletes the IMPLTYPE flags for the indexed interface.
ICreateTypeInfo2::SetCustData | Sets a value for custom data.
ICreateTypeInfo2::SetHelpStringContext | Sets the context number for the specified Help string.
ICreateTypeInfo2::SetFuncCustData | Sets a value for a specified custom function.
ICreateTypeInfo2::SetFuncHelpStringContext | Sets a Help context value for a specified custom function.
ICreateTypeInfo2::SetVarCustData | Sets a custom data variable.
ICreateTypeInfo2::SetParamCustData | Sets the specified parameter for the custom data.
ICreateTypeInfo2::SetImplTypeCustData | Sets the implementation type for custom data.
ICreateTypeInfo2::SetVarHelpStringContext | Sets a Help context value for a specified variable.


ICreateTypeInfo2::DeleteFuncDesc

This method deletes a function description specified by the index number.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteFuncDesc( unsigned int index );

Parameters

index
Index of the function whose description is to be deleted. The index should be in the range of 0 to 1 less than the number of functions in this type.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::DeleteFuncDescByMemId

This method deletes the function description specified by member identifier.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteFuncDescByMemId( MEMBERID memid,
INVOKEKIND invKind );

Parameters

memid
Member identifier of the FUNCDESC to delete.
invKind
Type of the invocation.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::DeleteImplType

This method deletes the IMPLTYPE flags for the indexed interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteImplType( unsigned int index );

Parameters

index
Index of the interface for which to delete the type flags.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::DeleteVarDesc

This method deletes the specified VARDESC structure.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteVarDesc( unsigned int index );

Parameters

index
Index number of the VARDESC structure.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function cannot read from the file.
TYPE_E_INVDATAREAD | The function cannot read from the file.
TYPE_E_UNSUPFORMAT | The type library has an old format.
TYPE_E_INVALIDSTATE | The type library cannot be opened.

Example

ptypeinfo->DeleteVarDesc(index);


ICreateTypeInfo2::DeleteVarDescByMemId

This method deletes the specified VARDESC structure.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteVarDescByMemId( MEMBERID memid );

Parameters

memid
Member identifier of the VARDESC to be deleted.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function cannot read from the file.
TYPE_E_INVDATAREAD | The function cannot read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library cannot be opened.


ICreateTypeInfo2::SetCustData

This method sets a value for custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetCustData( REFGUID guid, VARIANT *pVarVal);

Parameters

guid
Globbaly unique identifier (GUID) that can be used to identify the data.
pVarVal
Pointer to the data to store (any variant except an object).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::SetFuncCustData

This method sets a value for a specified custom function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetFuncCustData( unsigned int index, REFGUID guid, VARIANT *pVarVal );

Parameters

index
Index of the function for which to set the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to the data to store (any variant except an object).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::SetFuncHelpStringContext

This method sets a Help context value for a specified custom function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetFuncHelpStringContext( unsigned int index,
DWORD dwHelpStringContext );

Parameters

index
Index of the function for which to set the custom data.
dwHelpStringContext
Specifies the Help string context for a localized string

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::SetHelpStringContext

This method sets the context number for the specified Help string.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpStringContext( DWORD *dwHelpStringContext );

Parameters

dwHelpStringContext
Specifies the Help string context number.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | Argument is invalid.


ICreateTypeInfo2::SetImplTypeCustData

This method sets the implementation type for custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetImplTypeCustData( unsigned int index, REFGUID guid,
VARIANT *pVarVal );

Parameters

index
Index of the variable for which to set the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to the value of the variable.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::SetName

This method sets the name of the typeinfo.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetName( OLECHAR FAR* szName );

Parameters

szName
NULL-terminated string that contains the name to be assigned to the typeinfo.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the typeinfo is not valid for this operation.


ICreateTypeInfo2::SetParamCustData

This method sets the specified parameter for the custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetParamCustData( unsigned int indexFunc,
unsigned int indexParam, REFGUID guid, VARIANT *pVarVal);

Parameters

indexFunc
Index of the function for which to set the custom data.
indexParam
Index of the parameter of the function for which to set the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pvarVal
Pointer to the data to store (any legal variant except an object).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::SetVarCustData

This method sets a custom data variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVarCustData( unsigned int index, REFGUID guid,
VARIANT *pVarVal);

Parameters

index
Index of the variable for which to set the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to the data to store (any legal variant except an object).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeInfo2::SetVarHelpStringContext

This method sets a Help context value for a specified variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVarHelpStringContext( unsigned int index,
DWORD dwHelpStringContext );

Parameters

index
Index of the variable.
dwHelpStringContext
Specifies the Help string context for a localized string

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeLib : IUnknown

This interface provides the methods for creating and managing the component or file that contains type information. Type libraries are created from type descriptions using the MkTypLib utility or the Microsoft Interface Definition Language (MIDL) compiler. These type libraries are accessed through the ITypeLib interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Method
Desciption
ICreateTypeLib::CreateTypeInfo | Creates a new type description instance within the type library.
ICreateTypeLib::SaveAllChanges | Not supported in Windows CE. Calls to this method return E_NOT_IMPL.
ICreateTypeLib::SetDocString | Not supported in Windows CE.
ICreateTypeLib::SetGuid | Sets the universally unique identifier (UUID) associated with the type library. Also known as the globally unique identifier (GUID).
ICreateTypeLib::SetHelpContext | Sets the Help context identifier for retrieving general Help information for the type library.
ICreateTypeLib::SetHelpFileName | Sets the name of the Help file.
ICreateTypeLib::SetLibFlags | Sets library flags, such as LIBFLAG_FRESTRICTED.
ICreateTypeLib::SetLcid | Sets the binary Microsoft national language identifier associated with the library.
ICreateTypeLib::SetName | Sets the name of the type library.
ICreateTypeLib::SetVersion | Sets the major and minor version numbers of the type library.


ICreateTypeLib::CreateTypeInfo

This method creates a new type description instance within the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CreateTypeInfo( OLECHAR FAR* szName, TYPEKIND tkind,
ICreateTypeInfo FAR* FAR* ppCTInfo );

Parameters

szName
Null-terminated string that contains the name of the new type.
tkind
TYPEKIND of the type description to be created.
ppCTInfo
On return, pointer to the type description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.
TYPE_E_NAMECONFLICT | The provided name is not unique.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

Use the function CreateTypeInfo to create a new type description instance within the library. An error is returned if the specified name already appears in the library. To get the type information of the type description that is being created, call IUnknown::QueryInterface(IID_ITypeInfo, ...) on the returned ICreateTypeInfo. This type information can be used by other type descriptions that reference it by using ICreateTypeInfo::AddRefTypeInfo .


ICreateTypeLib::SetGuid

This method sets the globally unique identifier (GUID) associated with the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetGuid( REFGUID guid );

Parameters

guid
GUID to be assigned to the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


ICreateTypeLib::SetHelpContext

This method sets the Help context identifier for retrieving general Help information for the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpContext( unsigned long dwHelpContext );

Parameters

dwHelpContext
Specifies the Help context identifier to be assigned to the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.

Remarks

Calling SetHelpContext with a Help context of zero is equivalent to not calling it at all, because zero indicates a null Help context.


ICreateTypeLib::SetHelpFileName

This method sets the name of the Help file.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpFileName( OLECHAR FAR* szHelpFileName );

Parameters

szHelpFileName
Null-terminated string that contains the name of the Help file for the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.

Remarks

Each type library can reference a single Help file.

The GetDocumentation method of the created ITypeLib returns a fully qualified path for the Help file, which is formed by appending the name passed into szHelpFileName to the registered Help directory for the type library. The Help directory is registered under:

\TYPELIB\<guid of library>\<Major.Minor version >\HELPDIR


ICreateTypeLib::SetLcid

This method sets the binary Microsoft national language identifier associated with the library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetLcid( LCID lcid );

Parameters

lcid
Represents the locale identifier for the type library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


ICreateTypeLib::SetLibFlags

This method sets library flags, such as LIBFLAG_FRESTRICTED.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetLibFlags( unsigned int uLibFlags );

Parameters

uLibFlags
Flags to set for the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


ICreateTypeLib::SetName

This method sets the name of the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetName( OLECHAR FAR* szName);

Parameters

szName
Null-terminated string that contains the name to be assigned to the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


ICreateTypeLib::SetVersion

This method sets the major and minor version numbers of the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetVersion( unsigned short wMajorVerNum,
unsigned short wMinorVerNum );

Parameters

wMajorVerNum
Major version number for the library.
wMinorVerNum
Minor version number for the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


ICreateTypeLib2 : ICreateTypeLib

ICreateTypeLib2 inherits from ICreateTypeLib, and has four member functions. The ICreateTypeInfo instance returned from ICreateTypeLib can be accessed through a QueryInterface() call to ICreateTypeInfo2.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The ICreateTypeInfo2 interface derives from ICreateTypeInfo, and adds methods for deleting items that have been added through ICreateTypeInfo.

The ICreateTypeInfo::LayOut method provides a way for the creator of the type information to check for any errors. A call to QueryInterface can be made to the ICreateTypeInfo instance at any time for its ITypeInfo interface. Calling any of the methods in the ITypeInfo interface that require layout information lays out the type information automatically.

Example

interface ICreateTypeInfo2 : ICreateTypeInfo
Method
Description
ICreateTypeLib2::DeleteTypeInfo | Deletes a specified type information from the type library.
ICreateTypeLib2::SetName | Sets the name of the type library.
ICreateTypeLib2::SetCustData | Sets a value to custom data.
ICreateTypeLib2::SetHelpStringContext | Sets the Help string context number.
ICreateTypeLib2::SetHelpStringDll | Sets the dynamic-link library (DLL) name to be used for Help string lookup for localization purposes.


ICreateTypeLib2::DeleteTypeInfo

This method deletes a specified type information from the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteTypeInfo( OLECHAR FAR* szName );

Parameters

szName
Null-terminated string that contains the name of the type information to remove.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeLib2::SetCustData

This method sets a value to custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetCustData( REFGUID guid, VARIANT *pVarVal);

Parameters

guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to the data to store (any variant except an object).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeLib2::SetHelpStringContext

This method sets the Help string context number.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpStringContext( DWORD *dwHelpStringContext );

Parameters

dwHelpStringContext
Specifies the Help string context number.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeLib2::SetHelpStringDll

This method sets the dynamic-link library (DLL) name to be used for Help string lookup for localization purposes.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHelpStringDll( LPOLESTR szFileName );

Parameters

szFileName
Null-terminated string that contains the DLL file name.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ICreateTypeLib2::SetName

This method sets the name of the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetName( OLECHAR FAR* szName );

Parameters

szName
Null-terminated string that contains the name to be assigned to the library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVALIDSTATE | The state of the type library is not valid for this operation.


IDccMan : IUnknown

This interface is implemented by the Windows CE connection manager. It allows an application some control of the connection manager and the ability to register for connection notifications. An application creates this interface by calling the COM CoCreateInstance function, using the CLSID_DccMan globally unique identifier (GUID), and receiving a pointer to an IDccMan interface.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Methods
Description
IDccMan::Advise | Registers an IDccManSink object so that it can receive connection notifications from the Windows CE connection manager.
IDccMan::ShowCommSettings | Displays the dialog box for setting the communications port.
IDccMan::Unadvise | Unregisters the client.

Remarks

The IDccManSink::OnLog* methods should return a value of NOERROR.

An IDccMan interface method typically return a value of NOERROR if the method succeeds. If a method fails, it uses the HRESULT_FROM_WIN32 macro to return an HRESULT Win32 error value. The application can display the error by using the Win32 FormatMessage function to create the error string. For more information about message tables, see the Win32 Programmer's Reference.

For more information, see Receiving Connection Notification.


IDccMan::Advise

This method registers an IDccManSink object so that it can receive connection notifications from the Windows CE connection manager.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

HRESULT STDMETHODIMP IDccMan::Advise( IDccManSink * pDccSink,
DWORD pdwContext );

Parameters

pDccSink
Pointer to an IDccManSink object that receives connection notifications.
pdwContext
Pointer to a DWORD that receives a context value used by the IDccMan object to identify the IDccManSink object that was passed in. The value pointed to by pdwContext should be passed in the call to IDccMan::Unadvise.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

For more information, see Receiving Connection Notification.

See Also

IDccMan::Unadvise


IDccMan::ShowCommSettings

This method displays the dialog box for setting the communications port.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

HRESULT STDMETHODIMP IDccMan::ShowCommSettings(void);

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

For more information, see Receiving Connection Notification.


IDccMan::Unadvise

This method is called by a client application when it wishes to stop receiving connection notifications.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

HRESULT STDMETHODIMP IDccMan::Unadvise( DWORD dwContext );

Parameters

dwContext
DWORD value that was returned in the call to IDccMan::Unadvise.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

For more information, see Receiving Connection Notification.

See Also

IDccMan::Advise


IDccManSink : IUnknown

This interface is implemented by a client application that needs to be notified by the Windows CE connection manager about the connection and disconnection events it handles.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Methods
Description
IDccManSink::OnLogActive | Indicates that a connection is established between the client application and the connection manager.
IDccManSink::OnLogAnswered | Indicates that the Windows CE connection manager has detected the communications interface.
IDccManSink::OnLogDisconnection | Indicates that the connection manager has terminated the connection between the desktop computer and the Windows CE–based-device.
IDccManSink::OnLogError | Indicates that the connection manager failed to start communications between the desktop computer and the Windows CE–based device.
IDccManSink::OnLogInactive | Indicates a disconnection, or disconnected state, between the desktop computer and the Windows CE–based device.
IDccManSink::OnLogIpAddr | Indicates that an Internet Protocol (IP) address has been established for communication between the desktop computer and the Windows CE–based device.
IDccManSink::OnLogListen | Indicates that a connection is waiting to be established between the desktop computer and the Windows CE–based device.
IDccManSink::OnLogTerminated | Indicates that the Windows CE connection manager has been shut down.

Remarks

For more information, see Receiving Connection Notification.


IDccManSink::OnLogActive

This method indicates that a connection is established between the client application and the connection manager.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogActive( void );

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogActive method is implemented by a client application and is called when a socket connection is established between the client application and the connection manager.

When this notification occurs, the Windows CE connection manager starts any applications that are registered with the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services\AutoStartOnConnect.

During this notification is a good time for the client application to initialize the remote application programming interface (RAPI) by calling the RAPI function CeRapiInit. A call to CeRapiInit does not return until a connection is established between the desktop computer and the Windows CE–based device.

For more information, see Receiving Connection Notification, and Invoking Functions from a Desktop Computer.

See Also

CeRapiInit


IDccManSink::OnLogAnswered

This method indicates that the Windows CE connection manager has detected the communications interface.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogAnswered( void );

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogAnswered method is implemented by a client application and is called when the Windows CE connection manager has detected the presence of the communications interface.

This method is called only for a client application running under Windows 95; it is not called if the client is running under Windows NT.

For more information, see Receiving Connection Notification.


IDccManSink::OnLogDisconnection

This method indicates that the connection manager has terminated the connection between the desktop computer and the Windows CE–based device.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogDisconnection( void);

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogDisconnection method is implemented by a client application and is called when the Windows CE connection manager terminates the connection between the desktop computer and the Windows CE–based device.

When this notification is made, the Windows CE connection manager starts any applications that are registered with the registry key \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services\AutoStartOnDisconnect.

For more information, see Receiving Connection Notification.


IDccManSink::OnLogError

This method indicates that the connection manager failed to start communications between the desktop computer and the Windows CE–based device.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogError( void );

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogError method is implemented by a client application and is called if the Windows CE connection manager failed to start the Remote Access Service (RAS) communications between the desktop computer and the Windows CE–based device.

OnLogError may also be called whenever a general Windows CE connection manager-related error occurs. For example, OnLogError is called if the communications port—selected in the Communications settings of the Windows CE connection manager Communications Properties—is already in use or is not available.

For more information, see Receiving Connection Notification.


IDccManSink::OnLogInactive

This method indicates a disconnection, or disconnected state, between the desktop computer and the Windows CE–based device.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogInactive( void );

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogInactive method is implemented by a client application and is called to indicate that the Windows CE connection manager has initiated a disconnection between the desktop computer and the Windows CE–based device.

This method is called only for a client application running under Windows 95; it is not called if the client is running under Windows NT.

For more information, see Receiving Connection Notification.


IDccManSink::OnLogIpAddr

This method indicates that an Internet Protocol (IP) address has been established for communication between the desktop computer and the Windows CE–based device.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogIpAddr( );

Parameters

dwIpAddr
Specifies the IP address of the Windows CE device.

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogIpAddr method is implemented by a client application and is called when the Windows CE connection manager has determined what IP address is used to connect to the Windows CE–based device. At this point, the connection is completely established.

For more information, see Receiving Connection Notification.


IDccManSink::OnLogListen

This method indicates that a connection is waiting to be established between the desktop computer and the Windows CE–based device.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IDccManSink::OnLogListen( void );

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogListen method is implemented by a client application and is called when the connection manager is waiting for a connection to be established between the desktop computer and the Windows CE–based device.

The current communications port used to establish the communication between the desktop computer and the Windows CE–based device can be viewed or modified by the user with the IDccMan::ShowCommSettings method.

For more information, see Receiving Connection Notification.

See Also

IDccMan::ShowCommSettings, IDccManSink


IDccManSink::OnLogTerminated

This method indicates that the Windows CE connection manager has been shut down.

At a Glance

Header file: | Dccole.h
Windows CE versions: | 1.0 and later

Syntax

HRESULT STDMETHODIMP IDccManSink::OnLogTerminated(void);

Return Values

This method should always return NOERROR.

Remarks

The IDccManSink::OnLogTerminated method is implemented by a client application and is called when the Windows CE connection manager has been shut down.

For more information, see Receiving Connection Notification.


IDispatch : IUnknown

This interface exposes objects, methods, and properties to Automation programming tools and other applications.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Method
Description
IDispatch::GetIDsOfNames | Maps a single member name and an optional set of parameter names to a corresponding set of integer dispatch identifiers (DISPIDs), which can then be used on subsequent calls to IDispatch::Invoke.
IDispatch::GetTypeInfo | Retrieves the type information for an object.
IDispatch::GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides, either 0 or 1.
IDispatch::Invoke | Provides access to properties and methods exposed by an object.


IDispatch::GetIDsOfNames

This method maps a single member name and an optional set of parameter names to a corresponding set of integer dispatch identifiers (DISPIDs), which can then be used on subsequent calls to IDispatch::Invoke.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetIDsOfNames( REFIID riid,
OLECHAR FAR* FAR* rgszNames, unsigned int cNames, LCID lcid,
DISPID FAR* rgDispId );

Parameters

riid
Reserved for future use; set to IID_NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgDispId
Caller-allocated array, each element of which contains an identifier that corresponds to one of the names passed in the rgszNames array. The first element represents the member name. The subsequent elements represent each of the member’s parameters.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned array of DISPIDs contains DISPID_UNKNOWN for each entry that corresponds to an unknown name.
DISP_E_UNKNOWNLCID | The locale identifier (LCID) was not recognized.

Remarks

An IDispatch implementation can associate any positive integer identifier value with a given name. Zero is reserved for the default, or Value property; –1 is reserved to indicate an unknown name; and other negative values are defined for other purposes. For example, if GetIDsOfNames is called, and the implementation does not recognize one or more of the names, it returns DISP_E_UNKNOWNNAME, and the rgDispId array contains DISPID_UNKNOWN for the entries that correspond to the unknown names.

The member and parameter DISPIDs must remain constant for the lifetime of the object. This allows a client to obtain the DISPIDs once, and cache them for later use.

When GetIDsOfNames is called with more than one name, the first name (rgszNames[0]) corresponds to the member name, and subsequent names correspond to the names of the member’s parameters.

The same name may map to different DISPIDs, depending on context. For example, a name may have a DISPID when it is used as a member name with a particular interface, a different identifier as a member of a different interface, and different mapping for each time it appears as a parameter.

The IDispatch interface binds to names at run time. To bind at compile time instead, an IDispatch client can map names to DISPIDs by using the ITypeLib, ITypeLib2, ITypeType, ITypeType2, and ITypeComp the type information interfaces. This allows a client to bind to members at compile time and avoid calling GetIDsOfNames at run time.

The implementation of GetIDsOfNames is case insensitive. Users that need case-sensitive name mapping should use type information interfaces to map names to DISPIDs, rather than call GetIDsOfNames.

Example

The following code from the Lines sample file Lines.cpp implements the GetIDsOfNames member function for the CLine class. The ActiveX or OLE object uses the standard implementation, DispGetIDsOfNames.

STDMETHODIMP
CLine::GetIDsOfNames(
        REFIID riid,
        OLECHAR FAR* FAR* rgszNames,
        UINT cNames,
        LCID lcid,
        DISPID FAR* rgDispId)
{
        return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

The following code might appear in an ActiveX client that calls GetIDsOfNames to get the DISPID of the CLine Color property.

HRESULT hresult;
IDispatch FAR* pdisp = (IDispatch FAR*)NULL;
DISPID dispid;
OLECHAR FAR* szMember = “color”;

// Code that sets a pointer to the dispatch (pdisp) is omitted.

hresult = pdisp->GetIDsOfNames(
    IID_NULL,
    &szMember,
    1, LOCALE_SYSTEM_DEFAULT,
    &dispid);


IDispatch::GetTypeInfo

This method retrieves the type information for an object.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeInfo( unsigned int iTInfo, LCID lcid,
ITypeInfo FAR* FAR* ppTInfo );

Parameters

iTInfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale identifier for the type information. An object may be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
ppTInfo
Receives a pointer to the requested type information object.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success; the type information element exists.
DISP_E_BADINDEX | Failure; iTInfo parameter was not 0.
TYPE_E_ELEMENTNOTFOUND | Failure; iTInfo parameter was not 0.

Example

The following code from the sample file Lines.cpp loads information from the type library and implements the member function GetTypeInfo:

// These lines are from CLines::Create load type information for the
// Lines collection from the type library.
    hr = LoadTypeInfo(&pLines->m_ptinfo, IID_ILines);
    if (FAILED(hr))
        goto error;

// Additional code omitted for brevity.

// This function implements GetTypeInfo for the CLines collection.
STDMETHODIMP
CLines::GetTypeInfo(
        UINT iTInfo,
        LCID lcid,
        ITypeInfo FAR* FAR* ppTInfo)
{
    *ppTInfo = NULL;

    if(iTInfo != 0)
        return ResultFromScode(DISP_E_BADINDEX);

    m_ptinfo->AddRef();
    *ppTInfo = m_ptinfo;

    return NOERROR;
}


IDispatch::GetTypeInfoCount

This method retrieves the number of type information interfaces that an object provides, either 0 or 1.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeInfoCount( unsigned int FAR* pctinfo );

Parameters

pctinfo
Pointer to a location that receives the number of type information interfaces provided by the object. If the object provides type information, this number is 1; otherwise the number is 0.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_NOTIMPL | Failure.

Remarks

The function may return zero, which indicates that the object does not provide any type information. In this case, the object may still be programmable through IDispatch, but does not provide type information for browsers, compilers, or other programming tools that access type information. This can be useful for hiding an object from browsers or for preventing early binding on an object.

Example

This code from the Lines sample file Lines.cpp implements the GetTypeInfoCount member function for the CLines class (ActiveX or OLE object).

STDMETHODIMP
CLines::GetTypeInfoCount(UINT FAR* pctinfo)
{
    *pctinfo = 1;
    return NOERROR;
}


IDispatch::Invoke

This method provides access to properties and methods exposed by an object.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Invoke( DISPID dispIdMember, REFIID riid, LCID lcid,
WORD wFlags, DISPPARAMS FAR* pDispParams,
VARIANT FAR* pVarResult, EXCEPINFO FAR* pExcepInfo,
unsigned int FAR* puArgErr);

Parameters

dispIdMember
Identifies the member. Use GetIDsOfNames or the object’s documentation to obtain the dispatch identifier.
riid
Reserved for future use; set to IID_NULL.
lcid
The locale context in which to interpret parameters. The lcid is used by the GetIDsOfNames function, and is also passed to Invoke to allow the object to interpret its parameters specific to a locale.

Applications that do not support multiple national languages can ignore this parameter.

wFlags
Flags describing the context of the Invoke call. It is one of the following values:
Value
Description
DISPATCH_METHOD | The member is invoked as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag may be set.
DISPATCH_PROPERTYGET | The member is retrieved as a property or data member.
DISPATCH_PROPERTYPUT | The member is changed as a property or data member.
DISPATCH_PROPERTYPUTREF | The member is changed by a reference assignment, rather than a value assignment. This flag is valid only when the property accepts a reference to an object.

pDispParams
Pointer to a structure that contains an array of parameters, an array of parameter DISPIDs for named parameters, and counts for the number of elements in the arrays. See the Remarks section that follows for a description of the DISPPARAMS structure.
pVarResult
Pointer to the location where the result is to be stored, or NULL if the caller expects no result. This parameter is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.
pExcepInfo
Pointer to a structure that contains exception information. This structure should be filled in if DISP_E_EXCEPTION is returned. Can be NULL.
puArgErr
The index within rgvarg of the first parameter that has an error. Arguments are stored in pDispParams->rgvarg in reverse order, so the first parameter is the one with the highest index in the array. This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND. For details, see “Returning Errors” in the following Remarks section.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADPARAMCOUNT | The number of elements provided to DISPPARAMS is different from the number of parameters accepted by the method or property.
DISP_E_BADVARTYPE | One of the parameters in rgvarg is not a valid variant type.
DISP_E_EXCEPTION | The application needs to raise an exception. In this case, the structure passed in pExcepInfo should be filled in.
DISP_E_MEMBERNOTFOUND | The requested member does not exist, or the call to Invoke tried to set the value of a read-only property.
DISP_E_NONAMEDARGS | This implementation of IDispatch does not support named parameters.
DISP_E_OVERFLOW | One of the parameters in rgvarg could not be coerced to the specified type.
DISP_E_PARAMNOTFOUND | One of the parameter DISPIDs does not correspond to a parameter on the method. In this case, puArgErr should be set to the first parameter that contains the error.
DISP_E_TYPEMISMATCH | One or more of the parameters could not be coerced. The index within rgvarg of the first parameter with the incorrect type is returned in the puArgErr parameter.
DISP_E_UNKNOWNINTERFACE | The interface identifier passed in riid is not IID_NULL.
DISP_E_UNKNOWNLCID | The member being invoked interprets string parameters according to the LCID, and the LCID is not recognized. If the LCID is not needed to interpret parameters, this error should not be returned.
DISP_E_PARAMNOTOPTIONAL | A required parameter was omitted.

In 16-bit versions, you can define your own errors using the MAKE_SCODE value macro.

Remarks

Generally, you should not implement Invoke directly. Instead, use the dispatch interface create functions CreateStdDispatch and DispInvoke.

If some application-specific processing needs to be performed before calling a member, the code should perform the necessary actions, and then call ITypeInfo::Invoke to invoke the member. ITypeInfo::Invoke acts exactly like IDispatch::Invoke. The standard implementations of IDispatch::Invoke created by CreateStdDispatch and DispInvoke defer to ITypeInfo::Invoke.

In an ActiveX client, IDispatch::Invoke should be used to get and set the values of properties, or to call a method of an ActiveX object. The dispIdMember parameter identifies the member to invoke. The DISPIDs that identify members are defined by the implementor of the object and can be determined by using the object’s documentation, the IDispatch::GetIDsOfNames function, or the ITypeInfo interface.

The information that follows addresses developers of ActiveX clients and others who use code to expose ActiveX objects. It describes the behavior that users of exposed objects should expect.

Calling a Method With No Arguments

The simplest use of Invoke is to call a method that does not have any parameters. You only need to pass the DISPID of the method, a LCID, the DISPATCH_METHOD flag, and an empty DISPPARAMS structure. For example:

HRESULT hresult;
IUnknown FAR* punk;
IDispatch FAR* pdisp = (IDispatch FAR*)NULL;
OLECHAR FAR* szMember = “Simple”;
DISPID dispid;
DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};

hresult = CoCreateInstance(CLSID_CMyObject, NULL, CLSCTX_SERVER,
                IID_Unknown, (void FAR* FAR*)&punk);

hresult = punk->QueryInterface(IID_IDispatch,
                (void FAR* FAR*)&pdisp);

hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
                LOCALE_USER_DEFAULT, &dispid);

hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_METHOD,
        &dispparamsNoArgs, NULL, NULL, NULL);

The example invokes a method named Simple on an object of the class CMyObject. First, it calls CoCreateInstance, which instantiates the object and returns a pointer to the object’s IUnknown interface (punk). Next, it calls QueryInterface, receiving a pointer to the object’s IDispatch interface (pdisp). It then uses pdisp to call the object’s GetIDsOfNames function, passing the string Simple in szMember to get the DISPID for the Simple method. With the DISPID for Simple in dispid, it calls Invoke to invoke the method, specifying DISPATCH_METHOD for the wFlags parameter and using the system default locale.

To further simplify the code, the example declares a DISPPARAMS structure named dispparamsNoArgs that is appropriate to an Invoke call with no parameters.

Because the Simple method does not take any parameters and does not return a result, the puArgErr and pVarResult parameters are NULL. In addition, the example passes NULL for pExcepInfo, that indicates that it is not prepared to handle exceptions and will handle only HRESULT errors.

Most methods, however, take one or more parameters. To invoke these methods, the DISPPARAMS structure should be filled in, as described in “Passing Parameters” later in this chapter.

Automation defines special DISPIDs for invoking an object’s Value property (the default), and the members _NewEnum, and Evaluate.

Getting and Setting Properties

Properties are accessed in the same way as methods, except you specify DISPATCH_PROPERTYGET or DISPATCH_PROPERTYPUT instead of DISPATCH_METHOD. Some languages can not distinguish between retrieving a property and calling a method. In this case, you should set the flags DISPATCH_PROPERTYGET and DISPATCH_METHOD.

The following code example gets the value of a property named On. You can assume that the object has been created, and that its interfaces have been queried, as in the previous example.

VARIANT FAR *pVarResult;
// Code omitted for brevity.
szMember = “On”;
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
                LOCALE_USER_DEFAULT, &dispid);

hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_PROPERTYGET,
        &dispparamsNoArgs, pVarResult, NULL, NULL);

As in the previous example, the code calls GetIDsOfNames for the DISPID of the On property, and then passes the identifier to Invoke. Then, Invoke returns the property’s value in pVarResult. In general, the return value does not set VT_BYREF. However, this bit may be set and a pointer returned to the return value, if the lifetime of the return value is the same as that of the object.

To change the property’s value, the call looks like this:

VARIANT FAR *pVarResult;
DISPPARAMS dispparams;
DISPID mydispid = DISP_PROPERTYPUT

// Code omitted for brevity.

szMember = “On”;
dispparams.rgvarg[0].vt = VT_BOOL;
dispparams.rgvarg[0].bool = FALSE;
dispparams.rgdispidNamedArgs = &mydispid;
dispparams.cArgs = 1;
dispparams.cNamedArgs = 1;
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
                LOCALE_USER_DEFAULT, &dispid);

hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_PROPERTYPUT,
        &dispparams, NULL, NULL, NULL);

The new value for the property (the Boolean value FALSE) is passed as an parameter when the On property’s Put function is invoked. The DISPID for the parameter is DISPID_PROPERTYPUT. This DISPID is defined by Automation to designate the parameter that contains the new value for a property’s Put function. The remaining details of the DISPPARAMS structure are described in the next section, “Passing Parameters.”

The DISPATCH_PROPERTYPUT flag in the previous example indicates that a property is being set by value. In Visual Basic, the following statement assigns the Value property (the default) of YourObj to the Prop property:

MyObj.Prop = YourObj

This statement should be flagged as a DISPATCH_PROPERTYPUT. Similarly, statements like the following assign the Value property of one object to the Value property of another object.

Worksheet.Cell(1,1) = Worksheet.Cell(6,6)
MyDoc.Text1 = YourDoc.Text1

These statements result in a PROPERTY_PUT operation on Worksheet.Cell(1,1) and MyDoc.Text1.

Use the DISPATCH_PROPERTYPUTREF flag to indicate a property or data member that should be set by reference. For example, the following Visual Basic statement assigns the pointer YourObj to the property Prop, and should be flagged as DISPATCH_PROPERTYPUTREF.

Set MyObj.Prop = YourObj

The Set statement causes a reference assignment, rather than a value assignment.

The parameter on the right side is always passed by name, and should not be accessed positionally.

Passing Parameters

Arguments to the method or property being invoked are passed in the DISPPARAMS structure. This structure consists of a pointer to an array of parameters represented as variants, a pointer to an array of DISPIDs for named parameters, and the number of parameters in each array.

typedef struct FARSTRUCT tagDISPPARAMS{
    VARIANTARG FAR* rgvarg;            // Array of parameters.
    DISPID FAR* rgdispidNamedArgs;     // Dispatch IDs of named parameters.
    unsigned int cArgs;                // Number of parameters.
    unsigned int cNamedArgs;         // Number of named parameters.
} DISPPARAMS;

The parameters are passed in the array rgvarg[ ], with the number of parameters passed in cArgs. The parameters in the array should be placed from last to first, so rgvarg[0] has the last parameter and rgvarg[cArgs –1] has the first parameter. The method or property may change the values of elements within the array rgvarg, but only if it has set the VT_BYREF flag. Otherwise, consider the elements as read-only.

A dispatch invocation can have named parameters as well as positional parameters. If cNamedArgs is 0, all the elements of rgvarg[ ] represent positional parameters. If cNamedArgs is not 0, each element of rgdispidNamedArgs[ ] contains the DISPID of a named parameter, and the value of the parameter is in the matching element of rgvarg[ ]. The DISPIDs of the named parameters are always contiguous in rgdispidNamedArgs, and their values are in the first cNamedArgs elements of rgvarg. Named parameters cannot be accessed positionally, and positional parameters cannot be named.

The DISPID of an parameter is its zero-based position in the parameter list. For example, the following method takes three parameters.

BOOL _export CDECL
CCredit::CheckCredit(BSTR bstrCustomerID,    // DISPID = 0.
                     BSTR bstrLenderID,        // DISPID = 1.
                     CURRENCY cLoanAmt)        // DISPID = 2.
{
// Code omitted.
}

If you include the DISPID with each named parameter, you can pass the named parameters to Invoke in any order. For example, if a method is to be invoked with two positional parameters, followed by three named parameters (A, B, and C), using the following hypothetical syntax, then cArgs would be 5, and cNamedArgs would be 3.

object.method(“arg1”, “arg2”, A := “argA”, B := “argB”, C := “argC”)

The first positional parameter would be in rgvarg[4]. The second positional parameter would be in rgvarg[3]. The ordering of named parameters is not important to the IDispatch implementation, but these parameters are generally passed in reverse order. The parameter A would be in rgvarg[2], with the DISPID of A in rgdispidNamedArgs[2]. The parameter B would be in rgvarg[1], with the corresponding DISPID in rgdispidNamedArgs[1]. The parameter C would be in rgvarg[0], with the DISPID corresponding to C in rgdispidNamedArgs[0].

You can also use Invoke on members with optional parameters, but all optional parameters must be of type VARIANT. As with required parameters, the contents of the parameter vector depend on whether the parameters are positional or named. The invoked member must ensure that the parameters are valid. Invoke merely passes the DISPPARAMS structure it receives.

Omitting named parameters is straightforward. You would pass the parameters in rgvarg and their DISPIDs in rgdispidNamedArgs. To omit the parameter named B (in the preceding example) you would set rgvarg[0] to the value of C, with its DISPID in rgdispidNamedArgs[0]; and rgvarg[1] to the value of A, with its DISPID in rgdispidNamedArgs[1]. The subsequent positional parameters would occupy elements 2 and 3 of the arrays. In this case, cArgs is 4 and cNamedArgs is 2.

If the parameters are positional (unnamed), you would set cArgs to the total number of possible parameters, cNamedArgs to 0, and pass VT_ERROR as the type of the omitted parameters, with the status code DISP_E_PARAMNOTFOUND as the value. For example, the following code invokes ShowMe (,1).

VARIANT FAR *pVarResult;
EXCEPINFO FAR *pExcepInfo;
unsigned int FAR *puArgErr;
DISPPARAMS dispparams;

// Code omitted for brevity.

szMember = “ShowMe”;
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
                                LOCALE_USER_DEFAULT, &dispid) ;
dispparams.rgvarg[0].vt = VT_I2;
dispparams.rgvarg[0].ival = 1;
dispparams.rgvarg[1].vt = VT_ERROR;
dispparams.rgvarg[1].scode = DISP_E_PARAMNOTFOUND;
dispparams.cArgs = 2;
dispparams.cNamedArgs = 0;

hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_METHOD,
        &dispparams, pVarResult, pExcepInfo, puArgErr);

The example takes two positional parameters, but omits the first. Therefore, rgvarg[0] contains 1, the value of the last parameter in the parameter list, and rgvarg[1] contains VT_ERROR and the error return value, that indicates the omitted first parameter.

The calling code is responsible for releasing all strings and objects referred to by rgvarg[ ] or placed in *pVarResult. As with other parameters that are passed by value, if the invoked member must maintain access to a string after returning, you should copy the string. Similarly, if the member needs access to a passed-object pointer after returning, it must call the AddRef function on the object. A common example occurs when an object property is changed to refer to a new object, using the DISPATCH_PROPERTYPUTREF flag.

For those implementing IDispatch::Invoke, Automation provides the DispGetParam function to retrieve parameters from the parameter vector and coerce them to the proper type. For details, see “DispGetParam” later in this chapter.

Indexed Properties

When you invoke indexed properties of any dimension, you must pass the indexes as additional parameters. To set an indexed property, place the new value in the first element of the rgvarg[ ] vector, and the indexes in the subsequent elements. To get an indexed property, pass the indexes in the first n elements of rgvarg, and the number of indexes in cArg. Invoke returns the value of the property in pVarResult.

Automation stores array data in column-major order, which is the same ordering scheme used by Visual Basic and FORTRAN, but different from C, C++, and Pascal. If you are programming in C, C++, or Pascal, you must pass the indexes in the reverse order. The following code example shows how to fill the DISPPARAMS structure in C++.

dispparams.rgvarg[0].vt = VT_I2;
dispparams.rgvarg[0].iVal = 99;
dispparams.rgvarg[1].vt = VT_I2;
dispparams.rgvarg[1].iVal = 2;
dispparams.rgvarg[2].vt = VT_I2;
dispparams.rgvarg[2].iVal = 1;
dispparams.rgdispidNamedArgs = DISPID_PROPERTYPUT;
dispparams.cArgs = 3;
dispparams.cNamedArgs = 1;

The example changes the value of Prop[1,2] to 99. The new property value is passed in rgvarg[0]. The right-most index is passed in rgvarg[1], and the next index in rgvarg[2]. The cArgs member specifies the number of elements of rgvarg[ ] that contain data, and cNamedArgs is 1, that indicates the new value for the property.

Property collections are an extension of this feature.

Raising Exceptions During Invoke

When you implement IDispatch::Invoke, errors can be communicated either through the normal return value or by raising an exception. An exception is a special situation that is normally handled by jumping to the nearest routine enclosing the exception handler.

To raise an exception, IDispatch::Invoke returns DISP_E_EXCEPTION and fills the structure passed through pExcepInfo with information about the cause of the exception or error. You can use the information to understand the cause of the exception and proceed as necessary.

The exception information structure includes an error code number that identifies the kind of exception (a string that describes the error in a human-readable way). It also includes a Help file and a Help context number that can be passed to Windows Help for details about the error. At a minimum, the error code number must be filled with a valid number.

If you consider IDispatch another way to call C++ methods in an interface, EXCEPINFO models the raising of an exception or longjmp() call by such a method.

Returning Errors

Invoke returns DISP_E_MEMBERNOTFOUND if one of the following conditions occurs:

  • A member or parameter with the specified DISPID and matching cArgs cannot be found, and the parameter is not optional.
  • The member is a void function, and the caller did not set pVarResult to NULL.
  • The member is a read-only property, and the caller set wFlags to DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF.

If Invoke finds the member, but uncovers errors in the parameter list, it returns one of several other errors. DISP_E_BAD_PARAMCOUNT means that the DISPPARAMS structure contains an incorrect number of parameters for the property or method. DISP_E_NONAMEDARGS means that Invoke received named parameters, but they are not supported by the member.

DISP_E_PARAMNOTFOUND means that the correct number of parameters was passed, but the DISPID for one or more parameters was incorrect. If Invoke cannot convert one of the parameters to the desired type, it returns DISP_E_TYPEMISMATCH. In these two cases, if it can identify which parameter is incorrect, Invoke sets *puArgErr to the index within rgvarg of the parameter with the error. For example, if an Automation method expects a reference to a double-precision number as an parameter, but receives a reference to an integer, the parameter is coerced. However, if the method receives a date, IDispatch::Invoke returns DISP_E_TYPEMISMATCH and sets *puArgErr to the index of the integer in the parameter array.

Automation provides functions to perform standard conversions of VARIANT, and these functions should be used for consistent operation. DISP_E_TYPEMISMATCH is returned only when these functions fail.

Example

This code from the Lines sample file Lines.cpp implements the Invoke member function for the CLines class.

STDMETHODIMP
CLines::Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD wFlags,
    DISPPARAMS FAR* pDispParams,
    VARIANT FAR* pVarResult,
    EXCEPINFO FAR* pExcepInfo,
    UINT FAR* puArgErr)
{
    return DispInvoke(
        this, m_ptinfo,
        dispidMember, wFlags, pDispParams,
        pVarResult, pExcepInfo, puArgErr);
}

The next code example calls the CLines::Invoke member function to get the value of the Color property:

HRESULT hr;
EXCEPINFO excepinfo;
UINT nArgErr;
VARIANT vRet;
DISPPARAMS FAR* pdisp;
OLECHAR FAR* szMember;
DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};

// Initialization code omitted for brevity.
szMember = “Color”;
hr = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1, LOCALE_USER_DEFAULT,
    &dispid);

// Get Color property.
hr = pdisp->Invoke(dispid, IID_NULL, LOCALE_SYSTEM_DEFAULT,
    DISPATCH_PROPERTYGET, &dispparams, &vRet, &excepinfo, &nArgErr);


IEnumReplItem

This interface enables enumeration of a collection of items.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Method
Description
IEnumReplItem::Clone | Creates a copy of the current state of enumeration.
IEnumReplItem::GetFolderHandle | Gets a handle to the folder (HREPLFD) that is currently being enumerated.
IEnumReplItem::Next | Attempts to advance to the next item in the enumeration sequence.
IEnumReplItem::Reset | Resets the enumeration sequence to the beginning.
IEnumReplItem::Skip | Attempts to skip over the next item in the enumeration sequence.


IEnumReplItem::Clone

This method creates a copy of the current state of enumeration.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Clone( IEnumReplItem FAR * FAR * ppEnum, );

Parameters

ppEnum
Pointer to the place to return the cloned enumerator. The type of ppEnum is the same as the enumerator name. For example, if the enumerator name is IEnumFORMATETC, ppEnum is of type IEnumFORMATETC.

Return Values

One of the values described in the following table is returned.

Value
Description
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | Value of ppEnum is invalid.
E_UNEXPECTED | An unexpected error occurred.


IEnumReplItem::GetFolderHandle

This method gets a handle to the folder (HREPLFLD) that is currently being enumerated.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

hHREPLFLD GetFolderHandle ( );

Return Values

Returns the handle to the folder (HREPLFLD) that is being enumerated.


IEnumReplItem::Next

This method attempts to advance to the next item in the enumeration sequence.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Next( unsigned long celt, HREPLITEM *phItem,
unsigned long FAR *pCeltFetched, );

Parameters

celt
Specifies the number of elements to return. If the number of elements requested is more than remains in the sequence, only the remaining elements are returned. The number of elements returned is passed through the pCeltFetched parameter, unless it is NULL.
phItem
Pointer to the handle to the structure in which to return the elements.
pCeltFetched
Pointer to the number of elements actually returned in *phItem. The pCeltFetched parameter cannot be NULL if celt is greater than one. Likewise, if pCeltFetched is NULL, celt must be one.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Returned the requested number of elements; phItem is set if non-NULL. All requested entries are valid.
S_FALSE | Returned fewer elements than requested in celt. In this case, unused slots in the enumeration are not set to NULL and *phItem holds the number of valid entries, even if zero is returned.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | The value of celt is invalid.
E_UNEXPECTED | An unexpected error occurred.


IEnumReplItem::Reset

This method resets the enumeration sequence to the beginning.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Reset();

Return Values

One of the values in the following table is returned.

Value
Description
S_OK | The enumeration sequence was reset to the beginning
S_FALSE | The enumeration sequence was not reset to the beginning.


IEnumReplItem::Skip

This method attempts to skip over the next item in the enumeration sequence.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Skip( unsigned long celt, );

Parameters

celt
Specifies the number of elements to be skipped.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to celt.
S_FALSE | The number of elements skipped is fewer than celt.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | The value of celt is invalid.
E_UNEXPECTED | An unexpected error occurred.


IEnumSTATDATA : IUnknown

This interface is used to enumerate through an array of STATDATA structures, which contain advisory connection information for a data object. IEnumSTATDATA has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The IEnumSTATDATA interface is used to enumerate through an array of STATDATA structures, which contain advisory connection information for a data object. IEnumSTATDATA has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone.

When to Implement

IEnumSTATDATA is implemented to enumerate advisory connections. Most applications will not implement this directly, but will use the OLE-provided implementation. Pointers to this implementation are available in two ways:

  • In a data object, call CreateDataAdviseHolder to get a pointer to the OLE data advise holder object, and then, to implement IDataObject::EnumDAdvise, call IDataAdviseHolder::EnumAdvise, which creates the enumeration object and supplies a pointer to the implementation of IEnumSTATDATA.
  • In a compound document object, call CreateOLEAdviseHolder to get a pointer to the OLE advise holder object, and then, to implement IOleObject::EnumAdvise, call IOleAdviseHolder::EnumAdvise, which creates the enumeration object and supplies a pointer to the implementation of IEnumSTATDATA.

When to Use

Containers usually call methods that return a pointer to IEnumSTATDATA so the container can use its methods to enumerate the existing advisory connections, and use this information to instruct an object to release each of its advisory connections prior to closing down. The IDataObject::EnumDAdvise and IOleAdviseHolder::EnumAdvise methods both supply a pointer to IEnumSTATDATA.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG celt,
  STATDATA * rgelt,
  ULONG * pceltFetched
);

HRESULT Skip(
  ULONG celt
);

HRESULT Reset(void)

HRESULT Clone(
  IEnumSTATDATA ** ppenum
);
Method
Description
IEnumSTATDATA::Next | Retrieves a specified number of items in the enumeration sequence.
IEnumSTATDATA::Skip | Skips over a specified number of items in the enumeration sequence.
IEnumSTATDATA::Reset | Resets the enumeration sequence to the beginning.
IEnumSTATDATA::Clone | Creates a copy of the current state of enumeration.


IEnumSTATDATA::Clone

This method creates a copy of the current state of enumeration.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Clone( Ienum<ELT_T> ** ppenum);

Parameters

ppenum
[out] Address of IEnum<ELT_T>* pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


IEnumSTATDATA::Next

This method retrieves a specified number of items in the enumeration sequence.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Next( ULONG celt, ELT_T[ ] rgelt, ULONG * pceltFetched);

Parameters

celt
[in] Number of elements being requested.
rgelt
[out] Array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
pceltFetched
[in/out] Pointer to the number of elements actually supplied in rgelt. Caller can pass in NULL if celt is one.

Return Values

S_OK indicatesthat the number of elements supplied is celt. S_FALSE indicates otherwise.


IEnumSTATDATA::Reset

This method resets the enumeration sequence to the beginning.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Reset( void );

Return Values

S_OK indicates success.

Remarks

A call to this method, resetting the sequence, does not guarantee that the same set of objects will be enumerated after the reset, because it depends on the collection being enumerated. A static collection is reset to the beginning, but it can be too expensive for some collections, such as files in a directory, to guarantee this condition.


IEnumSTATDATA::Skip

This method skips over a specified number of items in the enumeration sequence.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESUTL Skip( ULONG celt );

Parameters

celt
[in] Number of elements to be skipped.

Return Values

S_OK indicates that the number of elements skipped is celt. S_FALSE indicates otherwise.


IEnumSTATSTG : IUnknown

This interface is used to enumerate through an array of STATSTG structures that contains statistical information about an open storage, stream, or byte array object. This interface has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

The IEnumSTATSTG interface is used to enumerate through an array of STATSTG structures, which contain statistical information about an open storage, stream, or byte array object. IEnumSTATSTG has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone.

When to Implement

IEnumSTATSTG is implemented to enumerate the elements of a storage object. If you are using the compound file implementation of the storage object, a pointer to which is available through a call to StgCreateDocfile, IEnumSTATSTG is implemented on that object, and a pointer is returned through a call to IStorage::EnumElements. If you are doing a custom implementation of a storage object, you need to implement IEnumSTATSTG to fill in a caller-allocated array of STATSTG structures, each of which contains information about the nested elements in the storage object.

When to Use

Containers call methods that return a pointer to IEnumSTATSTG so the container can manage its storage object and the elements within it. Calls to the IStorage::EnumElements method supply a pointer to IEnumSTATDATA. The caller allocates an array of STATSTG structures and the IEnumSTATSTG methods fill in each structure with the statistics about one of the nested elements in the storage object.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG celt,
  STATSTG * rgelt,
  ULONG * pceltFetched
);

HRESULT Skip(
  ULONG celt
);

HRESULT Reset(void)

HRESULT Clone(
  IEnumSTATSTG ** ppenum
);
Method
Description
IEnumSTATSTG::Next | Retrieves a specified number of items in the enumeration sequence.
IEnumSTATSTG::Skip | Skips over a specified number of items in the enumeration sequence.
IEnumSTATSTG::Reset | Resets the enumeration sequence to the beginning.
IEnumSTATSTG::Clone | Creates a copy of the current state of enumeration.


IEnumSTATSTG::Clone

This method creates a copy of the current state of enumeration.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Clone( Ienum<ELT_T> ** ppenum );

Parameters

ppenum
[out] Address of IEnum<ELT_T>* pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


IEnumSTATSTG::Next

This method retrieves a specified number of items in the enumeration sequence.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Next( ULONG celt, ELT_T[ ] rgelt, ULONG * pceltFetched);

Parameters

celt
[in] Number of elements being requested.
rgelt
[out] Array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
pceltFetched
[in/out] Pointer to the number of elements actually supplied in rgelt. Caller can pass in NULL if celt is one.

Return Values

S_OK indicatesthat the number of elements supplied is celt. S_FALSE indicates otherwise.


IEnumSTATSTG::Reset

This method resets the enumeration sequence to the beginning.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Reset( void );

Return Values

S_OK indicates success.

Remarks

A call to this method, resetting the sequence, does not guarantee that the same set of objects will be enumerated after the reset, because it depends on the collection being enumerated. A static collection is reset to the beginning, but it can be too expensive for some collections, such as files in a directory, to guarantee this condition.


IEnumSTATSTG::Skip

This method skips over a specified number of items in the enumeration sequence.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESUTL Skip( ULONG celt );

Parameters

celt
[in] Number of elements to be skipped.

Return Values

S_OK indicatesthat the number of elements skipped is celt. S_FALSE indicates otherwise.


IEnumVARIANT : IUnknown

This interface provides a method for enumerating a collection of variants, including heterogeneous collections of objects and intrinsic types. Callers of this interface do not need to know the specific type or types of the elements in the collection.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The IEnumVARIANT interface provides a method for enumerating a collection of variants, including heterogeneous collections of objects and intrinsic types. Callers of this interface do not need to know the specific type (or types) of the elements in the collection.

Implemented by
Used by
Header file name
Applications that expose collections of objects Applications that access collections of objects Oleauto.h (32-bit systems)

Dispatch.h (16-bit systems)

The following is the definition that results from expanding the parameterized type IEnumVARIANT:

interface IEnumVARIANT : IUnknown {
   virtual HRESULT Next(unsigned long celt,
               VARIANT FAR* rgvar,
               unsigned long FAR* pceltFetched) = 0;
   virtual HRESULT Skip(unsigned long celt) = 0;
   virtual HRESULT Reset() = 0;
   virtual HRESULT Clone(IEnumVARIANT FAR* FAR* ppenum) = 0;
   };

To see how to implement a collection of objects using IEnumVARIANT, refer to the file Enumvar.cpp in the Lines sample code.

Method
Description
IEnumVARIANT::Clone | Creates a copy of the current state of enumeration.
IEnumVARIANT::Next | Attempts to get the next celt items in the enumeration sequence, and return them through the array pointed to by rgVar.
IEnumVARIANT::Reset | Resets the enumeration sequence to the beginning.
IEnumVARIANT::Skip | Attempts to skip over the next celt elements in the enumeration sequence.


IEnumVARIANT::Clone

This method creates a copy of the current state of enumeration.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Clone( IEnumVARIANT FAR* FAR* ppEnum );

Parameters

ppEnum
On return, pointer to the location of the clone enumerator.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Insufficient memory to complete the operation.

Remarks

Using this function, a particular point in the enumeration sequence can be recorded, and then returned to at a later time. The returned enumerator is of the same actual interface as the one that is being cloned.

There is no guarantee that exactly the same set of variants will be enumerated the second time as was enumerated the first. Although an exact duplicate is desirable, the outcome depends on the collection being enumerated. You may find that it is impractical for some collections to maintain this condition (for example, an enumeration of the files in a directory).

Example

The following code implements IEnumVariant::Clone for collections in the Lines sample file Enumvar.cpp.

STDMETHODIMP
CEnumVariant::Clone(IEnumVARIANT FAR* FAR* ppEnum)
{
    CEnumVariant FAR* penum = NULL;
    HRESULT hr;

    *ppenum = NULL;

    hr = CEnumVariant::Create(m_psa, m_cElements, &penum);
    if (FAILED(hr))
        goto error;
    penum->AddRef();
    penum->m_lCurrent = m_lCurrent;

    *ppenum = penum;
    return NOERROR;

error:
    if (penum)
        penum->Release();
    return hr;
}


IEnumVARIANT::Next

This method attempts to get the next celt items in the enumeration sequence, and return them through the array pointed to by rgVar.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Next( unsigned long celt, VARIANT FAR* rgVar,
unsigned long FAR* pCeltFetched );

Parameters

celt
Number of elements to be returned.
rgVar
Array of at least size celt in which the elements are to be returned.
pCeltFetched
Pointer to the number of elements returned in rgVar, or NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements returned is celt.
S_FALSE | The number of elements returned is less than celt.

Remarks

If fewer than the requested number of elements remain in the sequence, Next returns only the remaining elements. The actual number of elements returned is passed through *pCeltFetched, unless it is NULL.

Example

The following code implements IEnumVariant::Next for collections in the Lines sample file Enumvar.cpp.

STDMETHODIMP
CEnumVariant::Next(ULONG cElements, VARIANT FAR* pvar, ULONG FAR* pcElementFetched)
{
    HRESULT hr;
    ULONG l;
    long l1;
    ULONG l2;

    if (pcElementFetched != NULL)
        *pcElementFetched = 0;

    for (l=0; l<cElements; l++)
        VariantInit(&pvar[l]);

    // Retrieve the next cElements elements.
    for (l1=m_lCurrent, l2=0; l1<(long)(m_lLBound+m_cElements) &&
        l2<cElements; l1++, l2++)
    {
        hr = SafeArrayGetElement(m_psa, &l1, &pvar[l2]);
        if (FAILED(hr))
            goto error;
    }
    // Set count of elements retrieved.
    if (pcElementFetched != NULL)
        *pcElementFetched = l2;
    m_lCurrent = l1;

    return  (l2 < cElements) ? ResultFromScode(S_FALSE) : NOERROR;

error:
    for (l=0; l<cElements; l++)
        VariantClear(&pvar[l]);
    return hr;
}


IEnumVARIANT::Reset

This method resets the enumeration sequence to the beginning.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Reset()

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
S_FALSE | Failure.

Remarks

There is no guarantee that exactly the same set of variants will be enumerated the second time as was enumerated the first time. Although an exact duplicate is desirable, the outcome depends on the collection being enumerated. You may find that it is impractical for some collections to maintain this condition (for example, an enumeration of the files in a directory).

Example

The following code implements IEnumVariant::Reset for collections in the Lines sample file Enumvar.cpp:

STDMETHODIMP
CEnumVariant::Reset()
{
    m_lCurrent = m_lLBound;
    return NOERROR;
}


IEnumVARIANT::Skip

This method attempts to skip over the next celt elements in the enumeration sequence.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Skip( unsigned long celt );

Parameters

celt
Number of elements to skip.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The specified number of elements was skipped.
S_FALSE | The end of the sequence was reached before skipping the requested number of elements.

Example

The following code implements IEnumVariant::Skip for collections in the Lines sample file Enumvar.cpp.

STDMETHODIMP
CEnumVariant::Skip(ULONG cElements)
{
    m_lCurrent += cElements;
    if (m_lCurrent > (long)(m_lLBound+m_cElements))
    {
        m_lCurrent =  m_lLBound+m_cElements;
        return ResultFromScode(S_FALSE);
    }
    else return NOERROR;
}


IErrorInfo : IUnknown

This interface provides detailed contextual error information.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The IErrorInfo interface provides detailed contextual error information.

Implemented by
Used by
Header filename
Import library name
Oleaut32.dll
(32-bit systems)

Ole2disp.dll
(16-bit systems)

 Applications that receive rich information. Oleauto.h

Dispatch.h

 Oleaut32.lib

Oledisp.lib

Method
Description
IErrorInfo::GetDescription | Returns a textual description of the error.
IErrorInfo::GetGUID | Returns the globally unique identifier (GUID) of the interface that defined the error.
IErrorInfo::GetHelpContext | Returns the Help context identifier for the error.
IErrorInfo::GetHelpFile | Returns the path of the Help file that describes the error.
IErrorInfo::GetSource | Returns the language-dependent programmatic identifier for the class or application that raised the error.


IErrorInfo::GetDescription

This method returns a textual description of the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDescription( BSTR *pBstrDescription );

Parameters

pBstrDescription
Pointer to a Unicode string that describes the error.

Return Values

S_OK indicates success.

Comments

The text is returned in the language specified by the locale identifier (LCID) that was passed to IDispatch::Invoke for the method that encountered the error.


IErrorInfo::GetGUID

This method returns the globally unique identifier (GUID) of the interface that defined the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetGUID( GUID *pGUID );

Parameters

pGUID
Pointer to a GUID, or GUID_NULL, if the error was defined by the operating system.

Return Values

S_OK indicates success.

Remarks

IErrorInfo::GetGUID returns the GUID of the interface that defined the error. If the error was defined by the system, IErrorInfo::GetGUID returns GUID_NULL.

This GUID does not necessarily represent the source of the error. The source is the class or application that raised the error. Using the GUID, an application can handle errors in an interface, independent of the class that implements the interface.


IErrorInfo::GetHelpContext

This method returns the Help context identifier for the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetHelpContext( DWORD *pdwHelpContext );

Parameters

pdwHelpContext
Pointer to the Help context identifier for the error.

Return Values

S_OK indicates success.

Remarks

IErrorInfo::GetHelpContext returns the Help context identifier for the error. To find the Help file to which it applies, use IErrorInfo::GetHelpFile.


IErrorInfo::GetHelpFile

This method returns the path of the Help file that describes the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetHelpFile( BSTR *pBstrHelpFile );

Parameters

pBstrHelpFile
Pointer to a Unicode string that contains the fully qualified path of the Help file.

Return Values

S_OK indicates success.

Comments

IErrorInfo::GetHelpFile returns the fully qualified path of the Help file that describes the current error. IErrorInfo::GetHelpContext should be used to find the Help context identifier for the error in the Help file.


IErrorInfo::GetSource

This method returns the language-dependent programmatic identifier for the class or application that raised the error.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetSource( BSTR *pBstrSource );

Parameters

pBstrSource
Pointer to a string that contains a programmatic identifier, in the form progname.objectname.

Return Values

S_OK indicates success.

Remarks

Use IErrorInfo::GetSource to determine the class or application that is the source of the error. The language for the returned programmatic identifier depends on the locale identifier (LCID) that was passed into the method at the time of invocation.


IIMCallback

An input method (IM) is given a pointer to this interface by the input panel through the IInputMethod interface. The IM calls the methods in IMCallback to send keystrokes to the current application and to change the icon that displays on the Input Panel button.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Method
Description
IIMCallback::SetImInfo | Called by the input method (IM) to change the bitmaps shown on the Input Panel button representing the current input panel, to change the visible state of the input panel, or to notify the input panel when the IM has changed the size, placement, or docked status of the input panel window.
IIMCallback::SendVirtualKey | Called by the input method (IM) to simulate a keystroke or a virtual key. The key event is sent to the window that currently has the focus; that is, the window that would have received keyboard input if a key had been pressed on an external keyboard.
IIMCallback::SendCharEvents | Sends Unicode characters from the input method (IM) to the window with the focus, while also determining which WM_KEYDOWN and WM_KEYUP messages the window should receive.
IIMCallback::SendString | Called by the input method (IM) to send an entire string to the window that currently has the focus; that is, the window that would have received keyboard input if a key had been pressed on an external keyboard.


IIMCallback::SendCharEvents

This method sends a series of WM_KEYUP or WM_KEYDOWN messages from the input method (IM) to the window with the focus.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT SendCharEvents( UINT uVK, UINT uKeyFlags, UINT uChars,
UINT *puShift, UINT *puChars );

Parameters

uVK
Virtual key code sent in the first WM_KEYUP or WM_KEYDOWN message generated as a result of this method.
uKeyFlags
Unsigned integer that contains flags describing the state of the first key sent by this method. These flags are translated into the lKeyData parameter of the first message. See Keybd.h for the legally defined values. If the KeyStateDownFlag bit is set, this method generates a WM_KEYDOWN message; otherwise, it generates a WM_KEYUP message.
uChars
Number of characters in puChars.
puShift
Pointer to a buffer containing the corresponding KEY_STATE_FLAGS for the characters in puChars. See Keybd.h for the legally defined values. These flags should be identical to the flags in uKeyFlags.
puChars
Pointer to a buffer containing the all characters but the first one sent by this method.

Return Values

An appropriate HRESULT value is returned.

Remarks

This method allows the IM to determine its own keyboard layout, because it can associate any virtual key with any character and key state.

Another way to send characters to the active window is by means of the IIMCallback::SendString and IIMCallback::SendVirtualKey methods.

Unlike IInputMethod::SendVirtualKey, SendCharEvents does not affect the global key state.

See Also

IIMCallback::SendString, IIMCallback::SendVirtualKey, WM_CHAR, WM_KEYDOWN, WM_KEYUP


IIMCallback::SetImInfo

This method is called by the input method (IM) to change the bitmaps shown on the Input Panel button, to change the visible state of the input panel, or to notify the input panel when the IM has changed the size, placement, or docked status of the input panel window.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT SetImInfo( IMINFO *pimi );

Parameters

pimi
Pointer to an IMINFO structure containing the new IM settings, including the size, placement, and state of the input panel window. The IMINFO structure also contains indexes to the bitmaps for the Input Panel button.

Return Values

An appropriate HRESULT value is returned.

Remarks

IMs use this method to alter part of the input panel state. For example, an IM may include a user interface element that allows the user to toggle the input panel between a docked and floating state. However, the input panel uses all values passed in the IMINFO structure. Therefore, the IM must create and initialize an IMINFO structure that is identical to the current IMINFO structure .The IM should toggle the SIPF_DOCKED flag in the fdwFlags member, and use the altered IMINFO structure in this method. Much of the information in the IMINFO structure is also contained in the SIPINFO structure. An IM receives this information upon initialization, with the IInputMethod::ReceiveSipInfo method.

Applications written for Windows CE for the Palm-size PC can access the SIPINFO structure using the SHSipInfo function.

For Windows CE versions 2.12 and later, an IM can set the rcSipRect member of the IMINFO structure to set the new position of the SIP window. If rcSipRect is zeroed-out, then rcSipRect is ignored and no position is altered.

See Also

IInputMethod::ReceiveSipInfo, IMINFO, SIPINFO


IIMCallback::SendString

This method is called by the input method (IM) to send an entire string to the window that currently has the focus; that is, the window that would have received keyboard input if a key had been pressed on an external keyboard.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT SendString( LPTSTR ptszStr, DWORD dwSize );

Parameters

ptszStr
Pointer to a string buffer containing the string to send.
dwSize
Specifies the number of characters in the buffer. This number should not include the terminating null character, which is not sent.

Return Values

An appropriate HRESULT value is returned.

Remarks

An IM uses this method after an entire word or sentence has been entered. For example, a character recognizer IM could call this method after the user enters a full word. The input panel sends each character in the buffer as a WM_CHAR message to the current application. You can also use IIMCallback::SendCharEvents and IIMCallback::SendVirtualKey to send characters to the current application.

See Also

IIMCallback::SendCharEvents, IIMCallback:: SendVirtualKey


IIMCallback::SendVirtualKey

This method is called by the input method (IM) to simulate a keystroke or a virtual key. The key event is sent to the window that currently has the focus; that is, the window that would have received keyboard input if a key had been pressed on an external keyboard.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT SendVirtualKey( BYTE bVk, DWORD dwFlags );

Parameters

bVk
Byte containing the virtual key code of the key to simulate.
dwFlags
Specifies the state of the key. It is any combination of the following values:
Value
Description
KEYEVENTF_KEYUP | If this flag is set, a call to SendVirtualKey generates a WM_KEYUP message. If this flag is not set, a call to SendVirtualKey generates a WM_KEYDOWN message.
KEYEVENTF_SILENT | If this flag is set, the key the user pressed to activate SendVirtualKey does not make a keyboard click sound, even if clicks are enabled on the device.

Return Values

An appropriate HRESULT value is returned.

Remarks

This function modifies the global key state for the virtual key sent in bVk. For example, an IM can use this method to send SHIFT, CTRL, and ALT key up and down events. These events are retrieved when an application calls the GetKeyState function. This method should send virtual key events that do not have associated characters; that is, it should not send VK_* messages that cause a WM_CHAR message to be sent in the TranslateMessage function. If a character-producing virtual key is sent by this method, the key is modified by the global key state. For example, an application can use this method to send a VK_5 message to the current application. If the SHIFT global key is currently down, the application receives the “%” character message, depending on the computer’s keyboard driver. You can also send character messages and strings using the IIMCallback::SendCharEvents and IIMCallback::SendString methods. Call the SendCharEvents and SendString methods instead of the keybd_event function while programming an IM.

See Also

IIMCallback::SendCharEvents, IIMCallback::SendString, keybd_event


IInputMethod

This interface is implemented by the input method (IM) component. The input panel calls the methods of this interface to notify the IM of state changes and to request action and information from the IM. Because an IM is a COM interface, it is up to the developer to implement the following methods.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Method
Description
IInputMethod::Select | Implemented to create the windows and image list for the input method (IM).
IInputMethod::Deselect | Implemented to select the input method (IM) out of the input panel window and to destroy the IM windows.
IInputMethod::Showing | Implemented to perform any initialization before the input panel window is displayed.
IInputMethod::Hiding | Implemented to perform any saving routines before the input panel is hidden.
IInputMethod::GetInfo | Implemented to return information about the current input method (IM) to the operating system.
IInputMethod::ReceiveSipInfo | Implemented to receive information about the size, placement, and docked status of the input panel.
IInputMethod::RegisterCallback | Implemented to receive a pointer to an IIMCallback interface. An input method (IM) uses the IIMCallback interface to send keystrokes to applications and to change the icons on the Input Panel button.
IInputMethod::GetImData | Implemented to send data from the current input method (IM) to the current application.
IInputMethod::SetImData | Implemented to respond to an application’s request to set input method (IM)-specific data within the IM.
IInputMethod::UserOptionsDlg | Implemented when the user requests that an input method (IM)-specific options dialog box be presented.

Remarks

An IM receives method calls in the following sequence before it is required to render the input panel window space or to respond to user actions:

  1. Select
  2. GetInfo
  3. ReceiveSipInfo
  4. RegisterCallback


IInputMethod::Deselect

This method is implemented to select the input method (IM) out of the input panel window and to destroy the IM windows.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT Deselect( void );

Return Values

An appropriate HRESULT value is returned.

Remarks

This method is called before IUnknown::Release is called on the IInputMethod pointer. Deselect provides an IM a place to perform cleanup activities, such as destroying windows and pointers. This method, along with the Release call, is the only notification that an IM receives that it is to be unloaded.

See Also

IUnknown::Release


IInputMethod::GetImData

This method is implemented to send data from the current input method (IM) to the current application.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT GetImData( DWORD dwSize, void* pvImData );

Parameters

dwsize
Specifies the size of the buffer pointed to by pvImData.
pvImData
Void pointer to a block of data in the application. The application is requesting that the IM fill the block with information. The size and format of the data are defined by the IM.

Return Values

An appropriate HRESULT value is returned.

Remarks

On Windows CE for the Palm-size PC, the input panel calls this method when an application has asked for IM-specific information in the SHSipInfo function. The application does this by providing a non-NULL pointer for the pvImData member of the SIPINFO structure and setting the uiAction parameter to GETSIPINFO. The IM can then pass information directly to the application. Use this method and IInputMethod::SetImData to send data to and from an application.

See Also

IInputMethod::SetImData, SIPINFO


IInputMethod::GetInfo

This method is implemented to return information about the current input method (IM) to the operating system.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT GetInfo( IMINFO *pimi, );

Parameters

pimi
Pointer to an IMINFO structure. GetInfo passes most of its information to the operating system through this structure.

Return Values

An appropriate HRESULT value is returned.

Remarks

The system calls this method for information about the IM. This includes flags indicating special properties of the IM, which are stored in a IMINFO structure. This structure contains the handles of the two image lists containing the masked bitmaps that are displayed on the Input Panel button, the indexes into the specified image lists, and a rectangle indicating the preferred size and placement of the IM.

On Windows CE for the Palm-size PC, the SHSipInfo function operates similar to this method; however, SHSipInfo is called by an application, and it returns information regarding the input panel.

See Also

IMINFO


IInputMethod::Hiding

This method is implemented to perform any saving routines before the input panel is hidden.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT Hiding( void );

Return Values

An appropriate HRESULT value is returned.

Remarks

This method is called by the system when the user toggles the visible state of the input panel off. Programmatically, this occurs when the SIPF_ON flag is toggled off in the SIPINFO structure. Hiding the input panel allows the user to see more of the current application. The input panel is hidden upon return from this call. Use this method to save any data the input method (IM) needs to display when the input panel becomes visible again. The data is used to reinitialize the input panel and IM in the IInputMethod::Showing method.

See Also

IInputMethod::Showing, SIPINFO


IInputMethod::ReceiveSipInfo

This method is implemented for the IM to receive information about the size, placement, and docked status of the input panel.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT ReceiveSipInfo( SIPINFO *psi );

Parameters

psi
Pointer to a SIPINFO structure. Because this method only provides information regarding the size, placement and docked status of the input panel, only the rcSipRect member and the SIPF_DOCKED flag, if set, of the fdwFlags member are valid in this SIPINFO structure.

Return Values

An appropriate HRESULT value is returned.

Remarks

The input panel calls this method to provide the IM with the current size, placement, and docked status of the input panel. This method is called whenever the user, an application, or the IM changes the input panel state. The IM should respond to these new values by changing its own state. However, it could also ignore these values. For example, a developer can implement an IM that is larger or smaller than the standard size for an IM. These values have either been selected by the user, or have been recommended as expected input panel values for that platform.

The input panel also calls this method during the initialization of the IM, along with Select, GetInfo, and RegisterCallback.

See Also

IInputMethod::GetInfo, IInputMethod::RegisterCallback, IInputMethod::Select, SIPINFO


IInputMethod::RegisterCallback

This method is implemented to receive a pointer to an IIMCallback interface. An input method (IM) uses the IIMCallback interface to send keystrokes to applications and to change the icons on the Input Panel button.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT RegisterCallback( IIMCallback* pIMCallback );

Parameters

pIMCallback
Pointer to an IIMCallback interface implemented in the input panel. The IM can call methods on this interface to send information back to the input panel.

Return Values

An appropriate HRESULT value is returned.

Remarks

The IIMCallback interface to the input panel is exposed only through this method. The input panel calls this method during the initialization of the IM, along with Select, GetInfo, and ReceiveSipInfo.

See Also

IIMCallback, IInputMethod::GetInfo, IInputMethod::ReceiveSipInfo, IInputMethod::Select


IInputMethod::SetImData

This method is implemented to respond to an application’s request to set input method (IM)-specific data within the IM.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT SetImData( DWORD dwSize, void* pvImData );

Parameters

dwsize
Specifies the size of the buffer pointed to by pvImData.
pvImData
Void pointer to a data buffer in the application. The application is providing information for the IM. The size and format of the data are defined by the IM.

Return Values

An appropriate HRESULT value is returned.

Remarks

Use this method and IInputMethod::GetImData to send data to and from an application.

On Windows CE for the Palm-size PC, the input panel calls SetImInfo when an application has asked to alter IM-specific information in the SHSipInfo function. This is done by the application providing a non-null pointer for the pvImData member of the SIPINFO structure, and setting the uiAction parameter to SETSIPINFO. The application can then pass information directly to the IM.

See Also

IInputMethod::GetImData, SIPINFO


IInputMethod::Select

This method is implemented to create the windows and image list for the input method (IM).

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT Select( HWND hwndSip, );

Parameters

hwndSip
Handle to the input panel window. The IM usually creates a child window of this input panel window in order to access the input panel window’s WndProc function. The IM is responsible for drawing the entire client area of the input panel window.

Return Values

An appropriate HRESULT value is returned.

Remarks

An IM receives this call when it has been selected by the input panel. The IM should perform any necessary initializations. The input panel calls this function during the initialization of the IM, along with GetInfo, ReceiveSipInfo, and RegisterCallback.

See Also

IInputMethod::GetInfo, IInputMethod::ReceiveSipInfo, IInputMethod::RegisterCallBack


IInputMethod::Showing

This method is implemented to perform any initialization before the input panel window is displayed.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT Showing( void );

Return Values

An appropriate HRESULT value is returned.

Remarks

This method is called by the input panel when the user toggles the visible status of the input panel on. Programmatically, this occurs when the SIPF_ON flag is toggled in the SIPINFO structure. Use this method to initialize any parameters, structures, and functions that relate to displaying the IM. The IM can also use any data that was stored with a previous call to IInputMethod::Hiding to initialize the window. After this method is complete and the input panel window is shown, the window and its children, such as those created by the IM, receive WM_PAINT messages.

See Also

IInputMethod::Hiding, SIPINFO, WM_PAINT


IInputMethod::UserOptionsDlg

This method is implemented when the user requests that an input method (IM)-specific options dialog box be presented.

At a Glance

Header file: | Sip.h
Windows CE Versions: | 2.01 and later

Syntax

HRESULT UserOptionsDlg( [in] HWND hwndParent );

Parameters

hwndParent
Handle to the window that should be the parent of the dialog box window created by the IM.

Return Values

An appropriate HRESULT value is returned.

Remarks

Through this method, the user can directly configure settings within the IM. This method differs significantly in context from the other methods in the IInputMethod interface for the following reasons:

  • It is called by the input panel control panel dialog box after instantiating a new instance of the IM; it is not called on the input panel thread.
  • It is called without other initialization methods, such as RegisterCallback or Select, being called first.
  • The current IM instance is unloaded immediately after calling UserOptionsDlg.

The User Options dialog box sets registry or other persistent configuration information for the IM. This information is used by the IM when it is selected into the input panel.

See Also

IInputMethod::RegisterCallback, IInputMethod::Select


ILockBytes : IUnknown

This interface is implemented on a byte array object that is backed by some physical storage, such as a disk file, global memory, or a database. It is used by a Component Object Model (COM) compound file storage object to give its root storage access to the physical device, while isolating the root storage from the details of accessing the physical storage.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

When to Implement

Most applications will not implement the ILockBytes interface because COM provides implementations for one of the most common situations:

File-based implementation—If you call StgCreateDocfile function to create a compound file storage object, it contains an implementation of ILockBytes that is associated with a byte array stored in a physical disk file. The compound file storage object calls the ILockBytes methods—you do not call them directly in this implementation.

There are situations in which it would be useful for an application to provide its own ILockBytes implementation. For example, a database application could implement ILockBytes to create a byte array object backed by the storage of its relational tables. However, it is strongly recommended that you use the COM-provided implementations. For a discussion of the advantages of using the COM implementations rather than creating your own, see the StgCreateDocfileOnILockBytes API function, which creates a compound file storage object on top of a caller-provided byte array object.

When to Use

The ILockBytes methods are called by the COM implementations of IStorage and IStream on the compound file object. Unless you are implementing IStorage and IStream, you would not need to call ILockBytes methods directly. If you write your own ILockBytes implementation, you can use the StgCreateDocfileOnILockBytes function to create a compound file storage object backed by your implementation of ILockBytes.

Method
Description
ILockBytes::Flush | Ensures that any internal buffers maintained by the byte array object are written out to the backing storage.
ILockBytes::LockRegion | Restricts access to a specified range of bytes in the array.
ILockBytes::ReadAt | Reads a specified number of bytes starting at a specified offset from the beginning of the array.
ILockBytes::SetSize | Changes the size of the byte array.
ILockBytes::Stat | Retrieves a STATSTG structure for this byte array object.
ILockBytes::UnlockRegion | Removes the access restriction on a range of bytes previously restricted with ILockBytes::LocRegion.
ILockBytes::WriteAt | Writes a specified number of bytes to a specified location in the array.


ILockBytes::Flush

This method ensures that any internal buffers maintained by the byte array object are written out to the backing storage.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Flush( void );

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The flush operation was successful.
STG_E_ACCESSDENIED | The caller does not have permission to access the byte array.
STG_E_MEDIUMFULL | The flush operation is not completed because there is no space left on the storage device.
E_FAIL | General failure writing data.
STG_E_TOOMANYFILESOPEN | Under certain circumstances, Flush does a dump-and-close to flush, which can lead to a return value of STG_E_TOOMANYFILESOPEN if no file handles are available.
STG_E_INVALIDHANDLE | An underlying file has been prematurely closed, or the correct floppy disk has been replaced by an invalid one.

Remarks

ILockBytes::Flush flushes internal buffers to the underlying storage device.

The COM-provided implementation of compound files calls this method during a transacted commit operation to provide a two-phase commit process that protects against loss of data.


ILockBytes::LockRegion

This method restricts access to a specified range of bytes in the array.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT LockRegion( ULARGE_INTEGER libOffset,
ULARGE_INTEGER cb, DWORD dwLockType );

Parameters

libOffset
[in] Specifies the byte offset for the beginning of the range.
cb
[in] Specifies, in bytes, the length of the range to be restricted.
dwLockType
[in] Specifies the type of restrictions being requested on accessing the range. This parameter uses one of the values from the LOCKTYPE enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The specified range of bytes was locked.
STG_E_INVALIDFUNCTION | Locking is not supported at all or the specific type of lock requested is not supported.
STG_E_ACCESSDENIED | Access denied because the caller has insufficient permission, or another caller has the file open and locked.
STG_E_LOCKVIOLATION | Access denied because another caller has the file open and locked.
STG_E_INVALIDHANDLE | An underlying file has been prematurely closed, or the correct floppy disk has been replaced by an invalid one.

Remarks

ILockBytes::LockRegion restricts access to the specified range of bytes. Once a region is locked, attempts by others to gain access to the restricted range must fail with the STG_E_ACCESSDENIED error.

The byte range can extend past the current end of the byte array. Locking beyond the end of an array is useful as a method of communication between different instances of the byte array object without changing data that is actually part of the byte array. For example, an implementation of ILockBytes for compound files could rely on locking past the current end of the array as a means of access control, using specific locked regions to indicate permissions currently granted.

The dwLockType parameter specifies one of three types of locking, using values from the LOCKTYPE enumeration. The types are as follows: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requestor to obtain a lock on the given range. This third type of locking is usually an alias for one of the other two lock types, and permits an Implementer to add other behavior as well. A given byte array might support either of the first two types, or both.

To determine the lock types supported by a particular ILockBytes implementation, you can examine the grfLocksSupported member of the STATSTG structure returned by a call to ILockBytes::Stat.

Any region locked with ILockBytes::LockRegion must later be explicitly unlocked by calling ILockBytes::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

Notes to Callers

Since the type of locking supported is optional and can vary in different implementations of ILockBytes, you must provide code to deal with the STG_E_INVALIDFUNCTION error.

Notes to Implementers

Support for this method depends on how the storage object built on top of the ILockBytes implementation is used. If you know that only one storage object at any given time can be opened on the storage device that underlies the byte array, then your ILockBytes implementation does not need to support locking. However, if multiple simultaneous openings of a storage object are possible, then region locking is needed to coordinate them.

A LockRegion implementation can choose to support all, some, or none of the lock types. For unsupported lock types, the implementation should return STG_E_INVALIDFUNCTION.


ILockBytes::ReadAt

This method reads a specified number of bytes starting at a specified offset from the beginning of the array.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ReadAt( ULARGE_INTEGER ulOffset, void * pv,
ULONG cb, ULONG * pcbRead );

Parameters

ulOffset
[in] Specifies the starting point from the beginning of the byte array for reading data.
pv
[in] Pointer to the buffer into which the byte array is read.
cb
[in] Specifies the number of bytes of data to attempt to read from the byte array.
pcbRead
[out] Pointer to a location where this method writes the actual number of bytes read from the byte array. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes read.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Indicates that the specified number of bytes were read, or the maximum number of bytes were read up to the end of the byte array.
E_FAIL | Data could not be read from the byte array.
E_PENDING | Asynchronous Storage only: Part or all of the data to be read is currently unavailable.
STG_E_ACCESSDENIED | The caller does not have permission to access the byte array.
STG_E_READFAULT | The number of bytes to be read does not equal the number of bytes that were acutally read.

Remarks

ILockBytes::ReadAt reads bytes from the byte array object. It reports the number of bytes that were actually read. This value may be less than the number of bytes requested if an error occurs or if the end of the byte array is reached during the read.

It is not an error to read less than the specified number of bytes if the operation encounters the end of the byte array. Note that this is the same end-of-file behavior as found in MS-DOS FAT file system files.


ILockBytes::SetSize

This method changes the size of the byte array.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetSize( ULARGE_INTEGER cb );

Parameters

cb
[in] Specifies the new size of the byte array as a number of bytes.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The size of the byte array was successfully changed.
STG_E_ACCESSDENIED | The caller does not have permission to access the byte array.
STG_E_MEDIUMFULL | The byte array size is not changed because there is no space left on the storage device.

Remarks

ILockBytes::SetSize changes the size of the byte array. If the cb parameter is larger than the current byte array, the byte array is extended to the indicated size by filling the intervening space with bytes of undefined value, as does ILockBytes::WriteAt, if the seek pointer is past the current end-of-stream.

If the cb parameter is smaller than the current byte array, the byte array is truncated to the indicated size.

Notes to Callers

Callers cannot rely on STG_E_MEDIUMFULL being returned at the appropriate time because of cache buffering in the operating system or network. However, callers must be able to deal with this return code because some ILockBytes implementations might support it.


ILockBytes::Stat

This method retrieves a STATSTG structure for this byte array object.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Stat( STATSTG * pstatstg, DWORD grfStatFlag);

Parameters

pstatstg
[out] Pointer to a STATSTG structure in which this method places information about this byte array object. The pointer is NULL if an error occurs.
grfStatFlag
[in] Specifies whether this method should supply the pwcsName member of the STATSTG structure through values taken from the STATFLAG enumeration. If the STATFLAG_NONAME is specified, the pwcsName member of STATSTG is not supplied, thus saving a memory allocation operation. The other possible value, STATFLAG_DEFAULT, indicates that all STATSTG members be supplied.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The STATSTG structure was successfully returned at the specified location.
E_OUTOFMEMORY | The STATSTG structure was not returned due to a lack of memory for the name member in the structure.
STG_E_ACCESSDENIED | The STATSTG structure was not returned because the caller did not have access to the byte array.
STG_E_INSUFFICIENTMEMORY | The STATSTG structure was not returned, due to a lack of memory.
STG_E_INVALIDFLAG | The value for the grfStateFlag parameter is not valid.
STG_E_INVALIDPOINTER | The value for the pStatStg parameter is not valid.

Remarks

ILockBytes::Stat should supply information about the byte array object in a STATSTG structure.


ILockBytes::UnlockRegion

This method removes the access restriction on a range of bytes previously restricted with ILockBytes::LocRegion.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT UnlockRegion( ULARGE_INTEGER libOffset,
ULARGE_INTEGER cb, DWORD dwLockType );

Parameters

libOffset
[in] Specifies the byte offset for the beginning of the range.
cb
[in] Specifies, in bytes, the length of the range that is restricted.
dwLockType
[in] Specifies the type of access restrictions previously placed on the range. This parameter uses a value from the LOCKTYPE enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The byte range was unlocked.
STG_E_INVALIDFUNCTION | Locking is not supported at all or the specific type of lock requested is not supported.
STG_E_LOCKVIOLATION | The requested unlock cannot be granted.

Remarks

ILockBytes::UnlockRegion unlocks a region previously locked with a call to ILockBytes::LockRegion. Each region locked must be explicitly unlocked, using the same values for the libOffset, cb, and dwLockType parameters as in the matching calls to ILockBytes::LockRegion. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.


ILockBytes::WriteAt

This method writes a specified number of bytes to a specified location in the array.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT WriteAt( ULARGE_INTEGER ulOffset, void const *pv,
ULONG cb, ULONG * pcbWritten );

Parameters

ulOffset
[in] Specifies the starting point from the beginning of the byte array for the data to be written.
pv
[in] Pointer to the buffer that contains the data to be written.
cb
[in] Specifies the number of bytes of data to attempt to write into the byte array.
pcbRead
[out] Pointer to a location where this method specifies the actual number of bytes written to the byte array. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes written.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Indicates that the specified number of bytes were written.
E_FAIL | A general failure occurred during the write.
E_PENDING | Asynchronous Storage only: Part or all of the data to be written is currently unavailable.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for writing this byte array.
STG_E_WRITEFAULT | The number of bytes to be written does not equal the number of bytes that were acutally written.
STG_E_MEDIUMFULL | The write operation was not completed because there is no space left on the storage device. The actual number of bytes written is still returned in pcbWritten.

Remarks

ILockBytes::WriteAt writes the specified data at the specified location in the byte array. The number of bytes actually written must always be returned in pcbWritten, even if an error is returned. If the byte count is zero bytes, the write operation has no effect.

If ulOffset is past the end of the byte array and cb is greater than zero, ILockBytes::WriteAt increases the size of the byte array. The fill bytes written to the byte array are not initialized to any particular value.


IMoniker : IUnknown

This interface contains methods that allow you to use a moniker object, which contains information that uniquely identifies a Component Object Model (COM) object. An object that has a pointer to the moniker object’s IMoniker interface can locate, activate, and access the identified object without having any other specific information on where the object is actually located in a distributed system.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The IMoniker interface contains methods that allow you to use a moniker object, which contains information that uniquely identifies a COM object. An object that has a pointer to the moniker object’s IMoniker interface can locate, activate, and get access to the identified object without having any other specific information on where the object is actually located in a distributed system.

Like a path to a file in a file system, a moniker contains information that allows a COM object to be located and activated. Monikers can identify any type of COM object, from a document object stored in a file to a selection within an embedded object. COM provides a set of moniker classes that allow you to create moniker objects identifying the objects most commonly found in the system. For example, there might be an object representing a range of cells in a spreadsheet which is itself embedded in a text document stored in a file. In a distributed system, this object’s moniker would identify the location of the object’s system, the file’s physical location on that system, the storage of the embedded object within that file, and, finally, the location of the range of cells within the embedded object.

A moniker object supports the IMoniker interface and uniquely identifies a single object in the system. Once an object providing a moniker has created the moniker object, this information cannot be changed within that object. If the moniker provider changes the information, it can only do so by creating a new moniker object, which would then uniquely identify the object in question.

Monikers have two important capabilities:

  • Monikers can be saved to a persistent storage. When a moniker is loaded back into memory, it still identifies the same object.
  • Monikers support an operation called “binding,” which is the process of locating the object named by the moniker, activating it (loading it into memory) if it is not already active, and returning a pointer to a requested interface on that object.

Monikers are used as the basis for linking in COM. A linked object contains a moniker that identifies its source. When the user activates the linked object to edit it, the moniker is bound; this loads the link source into memory.

When to Implement

Implement IMoniker only if you are writing a new moniker class. This is necessary only if you need to identify objects that cannot be identified using one of the COM-supplied moniker classes described below.

The COM-supplied moniker classes are sufficient for most situations. Before considering writing your own moniker class, you should make sure that your requirements cannot be satisfied by these classes.

When to Use

Two kinds of objects call the methods of IMoniker:

  • A component that contains one or more objects to be identified with a moniker and must provide the moniker to other objects
  • A client object that must bind to the object identified by the moniker

The component providing a moniker makes it accessible to other objects. It is important to understand the differences between the various system-supplied moniker classes to know which are appropriate for a given object. COM also provides functions for creating monikers using the COM-supplied moniker classes.

File monikers
Based on a path in the file system. File monikers can be used to identify objects that are saved as files. The associated creation function is CreateFileMoniker.
Item monikers
Based on a string that identifies an object in a container. Item monikers can be used to identify objects smaller than a file, such as embedded objects in a compound document and pseudo-objects (like a range of cells in a spreadsheet). The associated creation function is CreateItemMoniker.
Generic composite monikers
Consists of two or more monikers of arbitrary type that have been composed together. Generic composite monikers allow monikers of different classes to be used in combination. The associated creation function is CreateGenericComposite.
Anti-monikers
The inverse of file, item, or pointer monikers. Anti-monikers are used primarily for constructing relative monikers, which are analogous to relative path (such as “..\backup\report.old”), and which specify a location of an object relative to the location of another object). The associated creation function is CreateAntiMoniker.
Pointer monikers
A non-persistent moniker that wraps an interface pointer to an object loaded in memory. Whereas most monikers identify objects that can be saved to persistent storage, pointer monikers identify objects that cannot. The associated creation function is CreatePointerMoniker.

A moniker provider must also implement other interfaces to allow the monikers it hands out to be bound. COM objects that commonly provide monikers are link sources. These include server applications that support linking and container applications that support linking to their embedded objects.

Binding to an object means that a client uses a moniker to locate the object, activate it when necessary, and get a pointer to one of the active object’s interfaces. The client of the moniker does not need to be aware of the class of the moniker—it must just get a pointer to the correct moniker’s IMoniker interface. Monikers are used most often in this way by container applications that allow their documents to contain linked objects. However, link containers rarely call IMoniker methods directly. Instead, they generally manipulate linked objects through the default handler’s implementation of the IOleLink interface, which calls the appropriate IMoniker methods as needed.

Class monikers
These represent an object class. Class monikers bind to the class object of the class for which they are created. The associated creation function is CreateClassComposite.
Method
Description
IMoniker::BindToObject | Binds to the object named by the moniker.
IMoniker::BindToStorage | Binds to the object’s storage.
IMoniker::CommonPrefixWith | Finds the prefix that the moniker has in common with another moniker.
IMoniker::ComposeWith | Composes with another moniker.
IMoniker::Enum | Enumerates component monikers.
IMoniker::GetDisplayName | Returns the display name.
IMoniker::GetTimeOfLastChange | Returns the time the object was last changed.
IMoniker::Hash | Returns a hash value.
IMoniker::Inverse | Returns the inverse of the moniker.
IMoniker::IsEqual | Compares one moniker with another moniker.
IMoniker::IsRunning | Checks whether object is running.
IMoniker::IsSystemMoniker | Checks whether moniker is one of the system-supplied types.
IMoniker::ParseDisplayName | Converts a display name into a moniker.
IMoniker::Reduce | Reduces the moniker to the simplest form.
IMoniker::RelativePathTo | Constructs a relative moniker between the specified moniker and another.


IMoniker::BindToObject

This method binds to the object named by the moniker.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT BindToObject( IBindCtx * pbc, IMoniker * pmkToLeft,
REFIID riidResult, void ** ppvResult );

Parameters

pbc
[in] Pointer to the IBindCtx interface on the bind context object, which is used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
pmkToLeft
[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
riidResult
[in] Reference to the identifier of the interface the client wishes to use to communicate with the object that the moniker identifies.
ppvResult
[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvResult contains the requested interface pointer to the object the moniker identifies. When successful, the implementation must call IUnknown::AddRef on the moniker. It is the caller’s responsibility to release the object with a call to IUnknown::Release. If an error occurs, *ppvResult should be NULL.

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the values described in the following table.

S_OK
The binding operation was successful.
MK_E_NOOBJECT
The object identified by this moniker, or some object identified by the composite moniker of which this moniker is a part, could not be found.
MK_E_EXCEEDEDDEADLINE
The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.
MK_E_CONNECTMANUALLY
The binding operation requires assistance from the end user. The most common reasons for returning this value are that a password is needed or that a floppy needs to be mounted. When this value is returned, retrieve the moniker that caused the error with a call to IBindCtx::GetObjectParam with the key “ConnectManually”. You can then call IMoniker::GetDisplayName to get the display name, display a dialog box that communicates the desired information, such as instructions to mount a floppy or a request for a password, and then retry the binding operation.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED
An intermediate object was found but it did not support an interface required to complete the binding operation. For example, an item moniker returns this value if its container does not support the IOleItemContainer interface.
STG_E_ACCESSDENIED
Unable to access the storage object.
IOleItemContainer::GetObject errors
If the moniker used to bind to an object contains an item moniker, errors associated with this method can be returned.

Remarks

IMoniker::BindToObject implements the primary function of a moniker, which is to locate the object identified by the moniker and return a pointer to one of its interfaces.

Notes to Callers

If you are using a moniker as a persistent connection between two objects, you activate the connection by calling IMoniker::BindToObject.

You typically call IMoniker::BindToObject during the following process:

  1. Create a bind context object with a call to the CreateBindCtx function.
  2. Call IMoniker::BindToObject using the moniker, retrieving a pointer to a desired interface on the identified object.
  3. Release the bind context.
  4. Through the acquired interface pointer, perform the desired operations on the object.
  5. When finished with the object, release the object’s interface pointer.

The following code fragment illustrates these steps:

// pMnk is an IMoniker * that points to a previously acquired moniker
// ICellRange is a custom interface designed for an object that is a
//            range of spreadsheet cells
ICellRange *pCellRange;
IBindCtx *pbc;

CreateBindCtx( 0, &pbc );
pMnk->BindToObject( pbc, NULL, IID_ICellRange, &pCellRange );
pbc->Release();
// pCellRange now points to the object; safe to use pCellRange
pCellRange->Release();

You can also use the BindMoniker function when you only intend one binding operation and don’t need to retain the bind context object. This helper function encapsulates the creation of the bind context, calling IMoniker::BindToObject, and releasing the bind context.

COM containers that support links to objects use monikers to locate and get access to the linked object, but typically do not call IMoniker::BindToObject directly. Instead, when a user activates a link in a container, the link container usually calls IOleObject::DoVerb, using the link handler’s implementation, which calls IMoniker::BindToObject on the moniker stored in the linked object (if it cannot handle the verb).

Notes to Implementers

What your implementation does depends on whether you expect your moniker to have a prefix, that is, whether you expect the pmkToLeft parameter to be NULL or not. For example, an item moniker, which identifies an object within a container, expects that pmkToLeft identifies the container. An item moniker consequently uses pmkToLeft to request services from that container. If you expect your moniker to have a prefix, you should use the pmkToLeft parameter (for instance, calling IMoniker::BindToObject on it) to request services from the object it identifies.

If you expect your moniker to have no prefix, your IMoniker::BindToObject implementation should first check the Running Object Table (ROT) to see if the object is already running. To acquire a pointer to the ROT, your implementation should call IBindCtx::GetRunningObjectTable on the pbc parameter. You can then call the IRunningObjectTable::GetObject method to see if the current moniker has been registered in the ROT. If so, you can immediately call IUnknown::QueryInterface to get a pointer to the interface requested by the caller.


IMoniker::BindToStorage

This method binds to the object’s storage.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT BindToStorage( IBindCtx *pbc, IMoniker * pmkToLeft,
REFIID riid, void ** ppvObj );

Parameters

pbc
[in] Pointer to the IBindCtx interface on the bind context object to be used during this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.
pmkToLeft
[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
riid
[in] Reference to the identifier of the storage interface requested, whose pointer will be returned in ppvObj. Storage interfaces commonly requested include IStorage, IStream, and ILockBytes.
ppvObj
[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObj contains the requested interface pointer to the storage of the object identified by the moniker. If ppvObj is non-NULL, the implementation must call IUnknown::AddRef on the storage; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, *ppvObj must be set to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the values described in the following table.

S_OK
The binding operation was successful.
MK_E_NOSTORAGE
The object identified by this moniker does not have its own storage.
MK_E_EXCEEDEDDEADLINE
The operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.
MK_E_CONNECTMANUALLY
The operation was unable to connect to the storage, possibly because a network device could not be connected to. For more information, see IMoniker::BindToObject.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED
An intermediate object was found but it did not support an interface required for an operation. For example, an item moniker returns this value if its container does not support the IOleItemContainer interface.
STG_E_ACCESSDENIED
Unable to access the storage object.
IOleItemContainer::GetObject errors
Binding to a moniker that contains an item moniker can return any of the errors associated with this function.

Remarks

There is an important difference between the IMoniker::BindToObject and IMoniker::BindToStorage methods. If, for example, you have a moniker that identifies a spreadsheet object, calling IMoniker::BindToObject provides access to the spreadsheet object itself, while calling IMoniker::BindToStorage provides access to the storage object in which the spreadsheet resides.

Notes to Callers

Although none of the COM moniker classes call this method in their binding operations, it might be appropriate to call it in the implementation of a new moniker class. You could call this method in an implementation of IMoniker::BindToObject that requires information from the object identified by the pmkToLeft parameter and can get it from the persistent storage of the object without activation. For example, if your monikers are used to identify objects that can be activated without activating their containers, you may find this method useful.

A client that can read the storage of the object its moniker identifies could also call this method.

Notes to Implementers

Your implementation should locate the persistent storage for the object identified by the current moniker and return the desired interface pointer. Some types of monikers represent pseudo-objects, which are objects that do not have their own persistent storage. Such objects comprise some portion of the internal state of its container; as, for example, a range of cells in a spreadsheet. If your moniker class identifies this type of object, your implementation of IMoniker::BindToStorage should return the error MK_E_NOSTORAGE.

If the bind context’s BIND_OPTS structure specifies the BINDFLAGS_JUSTTESTEXISTENCE flag, your implementation has the option of returning NULL in ppvObj (although it can also ignore the flag and perform the complete binding operation).


IMoniker::CommonPrefixWith

This method finds the prefix that the moniker has in common with another moniker.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CommonPrefixWith( IMoniker * pmkOther,
IMoniker ** ppmkPrefix );

Parameters

pmkOther
[in] Pointer to the IMoniker interface on another moniker to be compared with this one to determine whether there is a common prefix.
ppmkPrefix
[out] Address of IMoniker* pointer variable that receives the interface pointer to the moniker that is the common prefix of this moniker and pmkOther. When successful, the implementation must call IUnknown::AddRef on the resulting moniker; it is the caller’s responsibility to call IUnknown::Release. If an error occurs or if there is no common prefix, the implementation should set *ppmkPrefix to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the values described in the following table.

Value
Description
S_OK | A common prefix exists that is neither this moniker nor pmkOther.
MK_S_NOPREFIX | No common prefix exists.
MK_S_HIM | The entire pmkOther moniker is a prefix of this moniker.
MK_S_US | The two monikers are identical.
MK_S_ME | This moniker is a prefix of the pmkOther moniker.
MK_E_NOTBINDABLE | This method was called on a relative moniker. It is not meaningful to take the common prefix on a relative moniker.

Remarks

IMoniker::CommonPrefixWith creates a new moniker that consists of the common prefixes of the moniker on this moniker object and another moniker. If, for example, one moniker represents the path “c:\projects\secret\art\pict1.bmp” and another moniker represents the path “c:\projects\secret\docs\chap1.txt,” the common prefix of these two monikers would be a moniker representing the path “c:\projects\secret.”

Notes to Callers

The IMoniker::CommonPrefixWith method is primarily called in the implementation of the IMoniker::RelativePathTo method. Clients using a moniker to locate an object rarely need to call this method.

Call this method only if pmkOther and this moniker are both absolute monikers. An absolute moniker is either a file moniker or a generic composite whose leftmost component is a file moniker that represents an absolute path. Do not call this method on relative monikers, because it would not produce meaningful results.

Notes to Implementers

Your implementation should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the common prefix of the two monikers. Otherwise, it should pass both monikers in a call to the MonikerCommonPrefixWith function, which correctly handles the generic case.


IMoniker::ComposeWith

This method composes with another moniker.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ComposeWith( IMoniker * pmkRight, BOOL fOnlyIfNotGeneric,
IMoniker ** ppmkComposite,);

Parameters

pmkRight
[in] Pointer to the IMoniker interface on the moniker to compose onto the end of this moniker.
fOnlyIfNotGeneric
[in] Boolean that is set to TRUE if the caller requires a non-generic composition, so the operation should proceed only if pmkRight is a moniker class that this moniker can compose with in some way other than forming a generic composite. If FALSE, the method can create a generic composite if necessary.
ppmkComposite
[out] Address of IMoniker* pointer variable that receives the interface pointer to the resulting composite moniker pointer. When successful, the implementation must call IUnknown::AddRef on the resulting moniker; it is the caller’s responsibility to call IUnknown::Release. If an error occurs or if the monikers compose to nothing (e.g., composing an anti-moniker with an item moniker or a file moniker), *ppmkComposite should be set to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | The monikers were successfully combined.
MK_E_NEEDGENERIC | Indicates that fOnlyIfNotGeneric was TRUE, but the monikers could not be composed together without creating a generic composite moniker.

Remarks

Joining two monikers together is called composition. Sometimes two monikers of the same class can be combined in what is called non-generic composition. For example, a file moniker representing an incomplete path and another file moniker representing a relative path can be combined to form a single file moniker representing the complete path. Non-generic composition for a given moniker class can be handled only in the implementation of IMoniker::ComposeWith for that moniker class.

Composition of monikers is an associative operation. That is, if A, B, and C are monikers, then, where Comp() represents the composition operation:

Comp( Comp( A, B ), C )
    is always equal to
Comp( A, Comp( B, C ) )

Notes to Callers

To combine two monikers, call IMoniker::ComposeWith to give the first moniker a chance to perform a non-generic composition.

An object that provides item monkers to identify its objects would call IMoniker::ComposeWith to provide a moniker that completely identifies the location of the object. This would apply, for example, to a server that supports linking to portions of a document, or a container that supports linking to embedded objects within its documents. In such a situation, you would do the following:

  1. Create an item moniker identifying an object.
  2. Get a moniker that identifies the object’s container.
  3. Call IMoniker::ComposeWith on the moniker identifying the container, passing the item moniker as the pmkRight parameter.

Most callers of IMoniker::ComposeWith should set the fOnlyIfNotGeneric parameter to FALSE.

Notes to Implementers

You can use either non-generic or generic composition to compose the current moniker with the moniker that pmkRight points to. If the class of the moniker indicated by pmkRight is the same as that of the current moniker, it is possible to use the contents of pmkRight to perform a more intelligent non-generic composition.

In writing a new moniker class, you must decide if there are any kinds of monikers, whether of your own class or another class, to which you want to give special treatment. If so, implement IMoniker::ComposeWith to check whether pmkRight is a moniker of the type that should have this treatment. To do this, you can call the moniker’s GetClassID method (derived from the IPersist Interface), or, if you have defined a moniker object that supports a custom interface, you can call IUnknown::QueryInterface on the moniker for that interface. An example of special treatment would be the non-generic composition of an absolute file moniker with a relative file moniker. The most common case of a special moniker is the inverse for your moniker class (whatever you return from your implementation of IMoniker::Inverse).

If pmkRight completely negates the receiver so the resulting composite is empty, you should pass back NULL in ppmkComposite and return the status code S_OK.

If the pmkRight parameter is not of a class to which you give special treatment, examine fOnlyIfNotGeneric to determine what to do next. If fOnlyIfNotGeneric is TRUE, pass back NULL through ppmkComposite and return the status code MK_E_NEEDGENERIC. If fOnlyIfNotGeneric is FALSE, call the CreateGenericComposite function to perform the composition generically.


IMoniker::Enum

This method enumerates component monikers.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Enum( IEnumMoniker ** ppenumMoniker );

Parameters

fForward
[in] Boolean value that is set to TRUE to enumerate the monikers from left to right, or to FALSE to enumerate from right to left.
ppenumMoniker
[out] Address of IEnumMoniker* pointer variable that receives the interface pointer to the enumerator object for the moniker. When successful, the implementation must call IUnknown::AddRef on the enumerator object. It is the caller’s responsibility to call IUnknown::Release. If an error occurs or if the moniker has no enumerable components, the implementation sets *ppenumMoniker to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as S_OK, which indicates success. S_OK is returned even if the moniker does not provide an enumerator (if ppenumMoniker equals NULL).

Remarks

IMoniker::Enum must supply an IEnumMoniker pointer to an enumerator that can enumerate the components of a moniker. For example, the implementation of the IMoniker::Enum method for a generic composite moniker creates an enumerator that can determine the individual monikers that make up the composite, while the IMoniker::Enum method for a file moniker creates an enumerator that returns monikers representing each of the components in the path.

Notes to Callers

Call this method to examine the components that make up a composite moniker.

Notes to Implementers

If the new moniker class has no discernible internal structure, your implementation of this method can simply return S_OK and set ppenumMoniker to NULL.


IMoniker::GetDisplayName

This method returns the display name.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDisplayName( IBindCtx *pbc, IMoniker *pmkToLeft,
LPOlESTR * ppszDisplayName );

Parameters

pbc
[in] Pointer to the IBindCtx interface on the bind context to be used in this operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.
pmkToLeft
[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
ppszDisplayName
[out] Address of LPOLESTR pointer variable that receives a pointer to the display name string. When successful, this string is a zero-terminated wide character string (two bytes per character) that contains the display name of the moniker. The implementation must use IMalloc::Alloc to allocate the string returned in ppszDisplayName, and the caller is responsible for calling IMalloc::Free to free it. Both the caller and the implementation of this method use the COM task allocator returned by CoGetMalloc. If an error occurs, the implementation must set *ppszDisplayName should be set to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the values described in the following table.

Value
Description
S_OK | The display name was successfully supplied.
MK_E_EXCEEDEDDEADLINE | The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.
E_NOTIMPL | There is no display name.

Remarks

IMoniker::GetDisplayName provides a string that is a displayable representation of the moniker. A display name is not a complete representation of a moniker’s internal state; it is simply a form that can be read by users. As a result, it is possible (though rare) for two different monikers to have the same display name. While there is no guarantee that the display name of a moniker can be parsed back into that moniker when calling the MkParseDisplayName function with it, failure to do so is rare.

As examples, the file moniker implementation of this method supplies the path the moniker represents, and an item moniker’s display name is the string identifying the item that is contained in the moniker.

Notes to Callers

It is possible that retrieving a moniker’s display name may be an expensive operation. For efficiency, you may want to cache the results of the first successful call to IMoniker::GetDisplayName, rather than making repeated calls.

Notes to Implementers

If you are writing a moniker class in which the display name does not change, simply cache the display name and supply the cached name when requested. If the display name can change over time, getting the current display name might mean that the moniker has to access the object’s storage or bind to the object, either of which can be expensive operations. If this is the case, your implementation of IMoniker::GetDisplayName should return MK_E_EXCEEDEDDEADLINE if the name cannot be retrieved by the time specified in the bind context’s BIND_OPTS structure.

A moniker that is intended to be part of a generic composite moniker should include any preceding delimiter (such as ‘\’) as part of its display name. For example, the display name returned by an item moniker includes the delimiter specified when it was created with the CreateItemMoniker function. The display name for a file moniker does not include a delimiter because file monikers are always expected to be the leftmost component of a composite.


IMoniker::GetTimeOfLastChange

This method returns the time the object was last changed.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTimeOfLastChange( IBindCtx *pbc, IMoniker *pmkToLeft,
FILETIME *pFileTime );

Parameters

pbc
[in] Pointer to the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.
pmkToLeft
[in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
pFileTime
[out] Pointer to the FILETIME structure receiving the time of last change. A value of {0xFFFFFFFF,0x7FFFFFFF} indicates an error (for example, exceeded time limit, information not available).

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | The method successfully returned a time.
MK_E_EXCEEDEDDEADLINE | The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.
MK_E_CONNECTMANUALLY | The operation was unable to connect to the storage for this object, possibly because a network device could not be connected to. For more information, see IMoniker::BindToObject.
MK_E_UNAVAILABLE | The time of the change is unavailable, and will not be available no matter what deadline is used.

Remarks

Notes to Callers

If you’re caching information returned by the object identified by the moniker, you may want to ensure that your information is up-to-date. To do so, you would call IMoniker::GetTimeOfLastChange and compare the time returned with the time you last retrieved information from the object.

For the monikers stored within linked objects, IMoniker::GetTimeOfLastChange is primarily called by the default handler’s implementation of IOleObject::IsUpToDate. Container applications call IOleObject::IsUpToDate to determine if a linked object (or an embedded object that contains linked objects) is up-to-date without actually binding to the object. This enables an application to determine quickly which linked objects require updating when the end user opens a document. The application can then bind only those linked objects that need updating (after prompting the end user to determine whether they should be updated), instead of binding every linked object in the document.

Notes to Implementers

It is important to perform this operation quickly because, for linked objects, this method is called when a user first opens a compound document. Consequently, your IMoniker::GetTimeOfLastChange implementation should not bind to any objects. In addition, your implementation should check the deadline parameter in the bind context and return MK_E_EXCEEDEDDEADLINE if the operation cannot be completed by the specified time.

There are a number of strategies you can use in your implementations:

  • For many types of monikers, the pmkToLeft parameter identifies the container of the object identified by this moniker. If this is true of your moniker class, you can simply call IMoniker::GetTimeOfLastChange on the pmkToLeft parameter, since an object cannot have changed at a date later than its container.
  • You can get a pointer to the Running Object Table (ROT) by calling IBindCtx::GetRunningObjectTable on the pbc parameter, and then calling IRunningObjectTable::GetTimeOfLastChange, since the ROT generally records the time of last change.
  • You can get the storage associated with this moniker (or the pmkToLeft moniker) and return the storage’s last modification time with a call to IStorage::Stat.


IMoniker::Hash

This method returns a hash value.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Hash( DWORD * pdwHash );

Parameter

pdwHash
[out] Pointer to the hash value.

Return Value

S_OK indicates that a 32-bit integer hash value was successfully received.

Remarks

Notes to Callers

You can use the value returned by this method to maintain a hash table of monikers. The hash value determines a hash bucket in the table. To search such a table for a specified moniker, calculate its hash value and then compare it to the monikers in that hash bucket using IMoniker::IsEqual.

Notes to Implementers

The hash value must be constant for the lifetime of the moniker. Two monikers that compare as equal using IMoniker::IsEqual must hash to the same value.

Marshaling and then unmarshaling a moniker should have no effect on its hash value. Consequently, your implementation of IMoniker::Hash should rely only on the internal state of the moniker, not on its memory address.


IMoniker::Inverse

This method returns the inverse of the moniker.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Inverse( IMoniker ** ppmk );

Parameters

ppmk
[out] Address of IMoniker* pointer variable that receives the interface pointer to a moniker that is the inverse of this moniker. When successful, the implementation must call IUnknown::AddRef on the new inverse moniker. It is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation should set *ppmk to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the values described in the following table.

Value
Description
S_OK | The inverse moniker has been returned successfully.
MK_E_NOINVERSE | The moniker class does not have an inverse.

Remarks

The inverse of a moniker is analogous to the “..” directory in MS-DOS file systems; the “..” directory acts as the inverse to any other directory name, because appending “..” to a directory name results in an empty path. In the same way, the inverse of a moniker typically is also the inverse of all monikers in the same class. However, it is not necessarily the inverse of a moniker of a different class.

The inverse of a composite moniker is a composite consisting of the inverses of the components of the original moniker, arranged in reverse order. For example, if the inverse of A is Inv( A ) and the composite of A, B, and C is Comp( A, B, C ), then

Inv( Comp( A, B, C ) )
    is equal to
Comp( Inv( C ), Inv( B ), Inv( A ) ).

Not all monikers have inverses. Most monikers that are themselves inverses, such as anti-monikers, do not have inverses. Monikers that have no inverse cannot have relative monikers formed from inside the objects they identify to other objects outside.

Notes to Callers

An object that is using a moniker to locate another object usually does not know the class of the moniker it is using. To get the inverse of a moniker, you should always call IMoniker::Inverse rather than the CreateAntiMoniker function, because you cannot be certain that the moniker you’re using considers an anti-moniker to be its inverse.

The IMoniker::Inverse method is also called by the implementation of the IMoniker::RelativePathTo method, to assist in constructing a relative moniker.

Notes to Implementers

If your monikers have no internal structure, you can call the CreateAntiMoniker function in to get an anti-moniker in your implementation of IMoniker::Inverse. In your implementation of IMoniker::ComposeWith, you need to check for the inverse you supply in the implementation of IMoniker::Inverse.


IMoniker::IsEqual

This method compares one moniker with another moniker.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsEqual( IMoniker *pmkOtherMoniker );

Parameters

pmkOtherMoniker
[in] Pointer to the IMoniker interface on the moniker to be used for comparison with this one (the one from which this method is called).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The two monikers are identical.
S_FALSE | The two monikers are not identical.

Remarks

Previous implementations of the Running Object Table (ROT) called this method. The current implementation of the ROT uses the IROTData interface instead.

Notes to Callers

Call this method to determine if two monikers are identical or not. Note that the reduced form of a moniker is considered different from the unreduced form. You should call the IMoniker::Reduce method before calling IMoniker::IsEqual, because a reduced moniker is in its most specific form. IMoniker::IsEqual may return S_FALSE on two monikers before they are reduced, and S_OK after they are reduced.

Notes to Implementers

Your implementation should not reduce the current moniker before performing the comparison. It is the caller’s responsibility to call IMoniker::Reduce in order to compare reduced monikers.

Note that two monikers that compare as equal must hash to the same value using IMoniker::Hash.


IMoniker::IsRunning

This method checks whether object is running.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsRunning( IBindCtx * pbc, IMoniker * pmkToLeft,
IMoniker * pmkNewlyRunning );

Parameters

pbc
[in] Pointer to theIBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.
pmkToLeft
[in] Pointer to theIMoniker interface on the moniker to the left of this moniker if this moniker is part of a composite. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.
pmkNewlyRunning
[in] Pointer to theIMoniker interface on the moniker most recently added to the Running Object Table (ROT). This can be NULL. If non-NULL, the implementation can return the results of calling IMoniker::IsEqual on the pmkNewlyRunning parameter, passing the current moniker. This parameter is intended to enable IMoniker::IsRunning implementations that are more efficient than just searching the ROT, but the implementation can choose to ignore pmkNewlyRunning without causing any harm.

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | The moniker is running.
S_FALSE | The moniker is not running.

Remarks

Notes to Callers

If speed is important when you’re requesting services from the object identified by the moniker, you may want those services only if the object is already running (because loading an object into the running state may be time-consuming). In such a situation, you’d call IMoniker::IsRunning to determine if the object is running.

For the monikers stored within linked objects, IMoniker::IsRunning is primarily called by the default handler’s implementation of IOleLink::BindIfRunning.

Notes to Implementers

To get a pointer to the Running Object Table (ROT), your implementation should call IBindCtx::GetRunningObjectTable on the pbc parameter. Your implementation can then call IRunningObjectTable::IsRunning to determine whether the object identified by the moniker is running. Note that the object identified by the moniker must have registered itself with the ROT when it first began running.


IMoniker::IsSystemMoniker

This method checks whether moniker is one of the system-supplied types.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsSystemMoniker( DWORD * pdwMksys );

Parameters

pdwMksys
[out] Pointer to an integer that is one of the values from the MKSYS enumeration, and refers to one of the COM moniker classes. This parameter cannot be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The moniker is a system moniker.
S_FALSE | The moniker is not a system moniker.

Remarks

Notes to Callers

New values of the MKSYS enumeration may be defined in the future; therefore you should explicitly test for each value you are interested in.

Notes to Implementers

Your implementation of this method must return MKSYS_NONE. You cannot use this function to identify your own monikers (for example, in your implementation of IMoniker::ComposeWith). Instead, you should use your moniker’s implementation of IPersist::GetClassID or use IUnknown::QueryInterface to test for your own private interface.


IMoniker::ParseDisplayName

This method converts a display name into a moniker.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ParseDisplayName( IBindCtx * pbc, IMoniker * pmkToLeft,
LPOLESTR * pszDisplayName, ULONG * pchEaten, IMoniker ** ppmkOut );

Parameters

pbc
[in] Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.
pmkToLeft
[in] Pointer to the IMoniker interface on the moniker that has been built out of the display name up to this point.
pszDisplayName
[in] Pointer to a null-terminated string that contains the remaining display name to be parsed. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.
pchEaten
[out] Pointer to the number of characters in pszDisplayName that were consumed in this step.
ppmkOut
[out] Address of IMoniker* pointer variable that receives the interface pointer to the moniker that was built from pszDisplayName. When successful, the implementation must call IUnknown::AddRef on the new moniker; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation sets *ppmkOut to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | The parsing operation was completed successfully.
MK_E_SYNTAX | An error in the syntax of the input components (pmkToLeft, this moniker, and pszDisplayName). For example, a file moniker returns this error if pmkToLeft is non-NULL, and an item moniker returns it if pmkToLeft is NULL.
IMoniker::BindToObject errors | Parsing display names may cause binding. Thus, any error associated with this function may be returned.

Remarks

Notes to Callers

Moniker clients do not typically call IMoniker::ParseDisplayName directly. Instead, they call the MkParseDisplayName function when they want to convert a display name into a moniker (for example, in implementing the Links dialog box for a container application, or for implementing a macro language that supports references to objects outside the document). That function first parses the initial portion of the display name itself.

It then calls IMoniker::ParseDisplayName on the moniker it has just created, passing the remainder of the display name and getting a new moniker in return; this step is repeated until the entire display name has been parsed.

Notes to Implementers

Your implementation may be able to perform this parsing by itself if your moniker class is designed to designate only certain kinds of objects. Otherwise, you must get an IParseDisplayName interface pointer for the object identified by the moniker-so-far (i.e., the composition of pmkToLeft and this moniker) and then return the results of calling IParseDisplayName::ParseDisplayName.

There are different strategies for getting an IParseDisplayName pointer:

  • You can try to get the object’s CLSID (by calling IPersist::GetClassID on the object), and then call the CoGetClassObject function, requesting the IParseDisplayName interface on the class factory associated with that CLSID.
  • You can try to bind to the object itself to get an IParseDisplayName pointer.
  • You can try binding to the object identified by pmkToLeft to get an IOleItemContainer pointer, and then call IOleItemContainer::GetObject to get an IParseDisplayName pointer for the item.

Any objects that are bound should be registered with the bind context (see IBindCtx::RegisterObjectBound) to ensure that they remain running for the duration of the parsing operation.


IMoniker::Reduce

This method reduces the moniker to the simplest form.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Reduce( IBindCtx * pbc, DWORD dwReduceHowFar,
IMoniker **ppmkReduced );

Parameters

pbc
[in] Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment. For more information, see IBindCtx.
dwReduceHowFar
[in] Specifies how far this moniker should be reduced. This parameter must be one of the values from the MKRREDUCE enumeration.
ppmkToLeft
[in/out] On entry, address of IMoniker* pointer variable that contains the interface pointer to moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.

On return, *ppmkToLeft is usually set to NULL, that indicates no change in the original moniker to the left. In rare situations, *ppmkToLeft indicates a moniker, that indicates that the previous moniker to the left should be disregarded and the moniker returned through *ppmkToLeft is the replacement. In such a situation, the implementation must call IUnknown::Release on the old moniker to the left of this moniker and must call IUnknown::AddRef on the new returned moniker; the caller must release it later. If an error occurs, the implementation can either leave the interface pointer unchanged or set it to NULL.

ppmkReduced
[out] Address of IMoniker* pointer variable that receives the interface pointer to the reduced form of this moniker, which can be NULL if an error occurs or if this moniker is reduced to nothing. If this moniker cannot be reduced, *ppmkReduced is simply set to this moniker and the return value is MK_S_REDUCED_TO_SELF. If *ppmkReduced is non-NULL, the implementation must call IUnknown::AddRef on the the new moniker; it is the caller’s responsibility to call IUnknown::Release. (This is true even if *ppmkReduced is set to this moniker.)

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the values described in the following table.

Value
Description
S_OK | This moniker was reduced.
MK_S_REDUCED_TO_SELF | This moniker could not be reduced any further, so ppmkReduced indicates this moniker.
MK_E_EXCEEDEDDEADLINE | The operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.

Remarks

IMoniker::Reduce is intended for the following uses:

  • It enables the construction of user-defined macros or aliases as new kinds of moniker classes. When reduced, the moniker to which the macro evaluates is returned.
  • It enables the construction of a kind of moniker that tracks data as it moves about. When reduced, the moniker of the data in its current location is returned.
  • On file systems that support an identifier-based method of accessing files which is independent of file names; a file moniker could be reduced to a moniker which contains one of these identifiers.

The intent of the MKRREDUCE flags passed in the dwReduceHowFar parameter is to provide the ability to programmatically reduce a moniker to a form whose display name is recognizable to the user. For example, paths in the file system, bookmarks in word-processing documents, and range names in spreadsheets are all recognizable to users. In contrast, a macro or an alias encapsulated in a moniker are not recognizable to users.

Notes to Callers

The scenarios described above are not currently implemented by the system-supplied moniker classes.

You should call IMoniker::Reduce before comparing two monikers using the IMoniker::IsEqual method, because a reduced moniker is in its most specific form. IMoniker::IsEqual may return S_FALSE on two monikers before they are reduced and return S_OK after they are reduced.

Notes to Implementers

If the current moniker can be reduced, your implementation must not reduce the moniker in-place. Instead, it must return a new moniker that represents the reduced state of the current one. This way, the caller still has the option of using the non-reduced moniker (for example, enumerating its components). Your implementation should reduce the moniker at least as far as is requested.


IMoniker::RelativePathTo

This method constructs a relative moniker between the specified moniker and another.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT RelativePathTo( IMoniker *pmkOther, IMoniker **ppmkRelPath );

Parameters

pmkOther
[in] Pointer to the IMoniker interface on the moniker to which a relative path should be taken.
ppmkRelPath
[out] Address of IMoniker* pointer variable that receives the interface pointer to the relative moniker. When successful, the implementation must call IUnknown::AddRef on the new moniker; it is the caller’s responsibility to call IUnknown::Release. If an error occurs, the implementation sets *ppmkRelPath to NULL.

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | A meaningful relative path has been returned.
MK_S_HIM | No common prefix is shared by the two monikers and the moniker returned in ppmkRelPath is pmkOther.
MK_E_NOTBINDABLE | This moniker is a relative moniker, such as an item moniker. This moniker must be composed with the moniker of its container before a relative path can be determined.

Remarks

A relative moniker is analogous to a relative path (such as “..\backup”). For example, suppose you have one moniker that represents the path “c:\projects\secret\art\pict1.bmp” and another moniker that represents the path “c:\projects\secret\docs\chap1.txt.” Calling IMoniker::RelativePathTo on the first moniker, passing the second one as the pmkOther parameter, would create a relative moniker representing the path “..\docs\chap1.txt.”

Notes to Callers

Moniker clients typically do not need to call IMoniker::RelativePathTo. This method is primarily called by the default handler for linked objects. Linked objects contain both an absolute and a relative moniker to identify the link source (this enables link tracking if the user moves a directory tree that contains both the container and source files). The default handler calls this method to create a relative moniker from the container document to the link source (that is, it calls IMoniker::RelativePathTo on the moniker identifying the container document, passing the moniker identifying the link source as the pmkOther parameter).

If you do call IMoniker::RelativePathTo, call it only on absolute monikers; for example, a file moniker or a composite moniker whose leftmost component is a file moniker, where the file moniker represents an absolute path. Do not call this method on relative monikers.

Notes to Implementers

Your implementation of IMoniker::RelativePathTo should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the relative path. Otherwise, it should pass both monikers in a call to the MonikerRelativePathTo function, which correctly handles the generic case.

The first step in determining a relative path is determining the common prefix of this moniker and pmkOther. The next step is to break this moniker and pmkOther into two parts each, say (P, myTail) and (P, otherTail) respectively, where P is the common prefix. The correct relative path is then the inverse of myTail composed with otherTail:

Comp( Inv( myTail ), otherTail )

Where Comp() represents the composition operation and Inv() represents the inverse operation.

Note that for certain types of monikers, you cannot use your IMoniker::Inverse method to construct the inverse of myTail. For example, a file moniker returns an anti-moniker as an inverse, while its IMoniker::RelativePathTo method must use one or more file monikers that each represent the path “..” to construct the inverse of myTail.


IOleAdviseHolder : IUnknown

This interface manages advisory connections and compound document notifications in an object server.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

The IOleAdviseHolder interface contains methods that manage advisory connections and compound document notifications in an object server. Its methods are intended to be used to implement the advisory methods of IOleObject. IOleAdviseHolder is implemented on an advise holder object. Its methods establish and delete advisory connections from the object managed by the server to the object’s container, which must contain an advise sink (support the IAdviseSink interface). The advise holder object must also keep track of which advise sinks are interested in which notifications and pass along the notifications as appropriate.

When to Implement

It is unlikely that you would choose to implement this interface. OLE provides an implementation of the OLE advise holder as a convenience to programmers. Few applications will require notification capabilities beyond those which the default advise holder provides. In general, a single server application that requires different notification capabilities would simply implement the advisory functionality in its IOleObject advisory methods. It would be necessary to implement IOleAdviseHolder only in the case where there may be a need for a custom advise holder object, whose methods are to be used to implement the IOleObject methods in a set of servers.

When to Use

Call the methods of IOleAdviseHolder to implement the advisory methods of IOleObject. Applications instantiate an OLE advise holder by calling the OLE function CreateOleAdviseHolder.

Containers and other objects that need to receive compound document notifications must implement the IAdviseSink interface to receive those notifications, and call the IOleAdviseHolder interface methods to establish an advisory connection and inform the object of what specific notifications it wishes to receive.

Method
Description
IOleAdviseHolder::Advise | Establishes an advisory connection between an OLE object and the calling object’s advise sink. Through that sink, the calling object can receive notification when the OLE object is renamed, saved, or closed.
IOleAdviseHolder::EnumAdvise | Creates an enumerator that can be used to enumerate the advisory connections currently established for an object and supplies a pointer to its IEnumSTATDATA interface.
IOleAdviseHolder::SendOnClose | Sends IAdviseSink::OnRename notifications to all advisory sinks currently registered with the advise holder.
IOleAdviseHolder::SendOnRename | Sends IAdviseSink::OnSave notifications to all advisory sinks currently registered with the advise holder.
IOleAdviseHolder::SendOnSave | Sends notifications to all advisory sinks currently registered with the advise holder.
IOleAdviseHolder::Unadvise | Deletes a previously established advisory connection.


IOleAdviseHolder::Advise

This method establishes an advisory connection between an OLE object and the calling object’s advise sink. Through that sink, the calling object can receive notification when the OLE object is renamed, saved, or closed.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Advise( IAdviseSink * pAdvise, DWORD * pdwConnection );

Parameters

pAdvise
[in] Pointer to the IAdviseSink interface on the advisory sink that should be informed of changes.
pdwConnection
[out] Pointer to a token that can be passed to the IOleAdviseHolder::Unadvise method to delete the advisory connection. The calling object is responsible for calling both IUnknown::AddRef and IUnknown::Release on this pointer.

Return Values

This method supports the standard return value E_INVALIDARG, as well as S_OK, which indicates that the advisory connections set up successfully.

Remarks

Containers, object handlers, and link objects all create advise sinks to receive notification of changes in compound-document objects of interest, such as embedded or linked objects. OLE objects of interest to these objects must implement the IOleObject interface, which includes several advisory methods, including IOleObject::Advise. A call to this method must set up an advisory connection with any advise sink that calls it, and maintain each connection until it is closed. It must be able to handle more than one advisory connection at a time.

IOleAdviseHolder::Advise is intended to be used to simplify the implementation of IOleObject::Advise. You can get a pointer to the OLE implementation of IOleAdviseHolder by calling CreateOleAdviseHolder, and then, to implement IOleObject::Advise, just delegate the call to IOleAdviseHolder::Advise. Other IOleAdviseHolder methods are intended to implement other IOleObject advisory methods.

If the attempt to establish an advisory connection is successful, the object receiving the call returns a nonzero value through pdwConnection. If the attempt fails, the object returns a zero. To delete an advisory connection, the object with the advise sink passes this nonzero token back to the object by calling IOleAdviseHolder::Unadvise.


IOleAdviseHolder::EnumAdvise

Thsi method creates an enumerator that can be used to enumerate the advisory connections currently established for an object and supplies a pointer to its IEnumSTATDATA interface.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT EnumAdvise( IENumSTATDATA * ppEnumAdvise, );

Parameters

ppenumAdvise
[out] Address of IEnumSTATDATA* pointer variable that receives the interface pointer to the new enumerator. A NULL value for *ppenumAdvise indicates that there are presently no advisory connections on the object, or that an error occurred. The advise holder is responsible for incrementing the reference count on the IEnumSTATDATA pointer this method supplies. It is the caller’s responsibility to call IUnknown::Release when it is done with the pointer.

Return Values

This method supports the standard return value E_FAIL, as well as the values described in the following table.

Value
Description
S_OK | Enumerator created successfully.
E_NOTIMPL | EnumAdvise is not implemented.

Remarks

IOleAdviseHolder::EnumAdvise creates an enumerator that can be used to enumerate an object’s established advisory connections. The method supplies a pointer to the IEnumSTATDATA interface on this enumerator. Advisory connection information for each connection is stored in the STATDATA structure, and the enumerator must be able to enumerate these structures, defined as follows:

typedef struct tagSTATDATA {
    FORMATETC         Formatetc;
    DWORD             grfAdvf;
    IAdviseSink *     pAdvise;
    DWORD             dwConnection;
    }STATDATA;

For this method, the only relevant structure members are pAdvise and dwConnection. Other members contain data advisory information. When you call the enumeration methods, and while an enumeration is in progress, the effect of registering or revoking advisory connections on what is to be enumerated is undefined.


IOleAdviseHolder::SendOnClose

This method sends notification that the object is closed to all advisory sinks currently registered with the advise holder.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SendOnClose()

Return Value

S_OK indicates that advise sinks were notified of the close operation through a call to the IAdviseSink::OnClose method.

Remarks

IOleAdviseHolder::SendOnClose must call IAdviseSink::OnClose on all advise sinks that have a valid advisory connection with the object, whenever the object goes from the running state to the loaded state. This occurs through a call to IOleObject::Close, so you can call IOleAdviseHolder::SendOnClose when you determine that a Close operation has been successful.


IOleAdviseHolder::SendOnRename

This method sends IAdviseSink::OnRename notifications to all advisory sinks currently registered with the advise holder.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SendOnRename( IMoniker * pmk, );

Parameters

pmk
[in] Pointer to the new full moniker of the object.

Return Value

S_OK indicatesthat advise sinks were sent IAdviseSink::OnRename notifications.

Remarks

IOleAdviseHolder::SendOnRename calls IAdviseSink::OnRename to advise the calling object, which must have already established an advisory connection, that the object has a new moniker. If you are using the OLE advise holder (having obtained a pointer through a call to CreateOleAdviseHolder), you can call IOleAdviseHolder::SendOnRename in the implementation of IOleObject::SetMoniker, when you have determined that the operation is successful.


IOleAdviseHolder::SendOnSave

This method sends IAdviseSink::OnSave notifications to all advisory sinks currently registered with the advise holder.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SendOnSave()

Return Values

S_OK indicates that advise sinks were sent IAdviseSink::OnSave notifications.

Remarks

IOleAdviseHolder::SendOnSave calls IAdviseSink::OnSave to advise the calling object (client), which must have already established an advisory connection, that the object has been saved. If you are using the OLE advise holder (having obtained a pointer through a call to CreateOleAdviseHolder), you can call IOleAdviseHolder::SendOnSave whenever you save the object the advise holder is associated with.

To take the object from the running state to the loaded state, the client calls IOleObject::Close. Within that implementation, if the user wants to save the object to persistent storage, the object calls IOleClientSite::SaveObject, followed by the call to IOleAdviseHolder::SendOnSave.


IOleAdviseHolder::Unadvise

This method deletes a previously established advisory connection.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Unadvise( DWORD dwConnection );

Parameters

dwConnection
[in] Contains a nonzero DWORD previously returned by IOleAdviseHolder::Advise in pdwConnection.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Advisory connection deleted successfully.
OLE_E_NOCONNECTION | The dwConnection parameter does not represent a valid advisory connection.

Remarks

IOleAdviseHolder::Unadvise is intended to be used to implement IOleObject::Unadvise to delete an advisory connection. In general, you would use the OLE advise holder having obtained a pointer through a call to CreateOleAdviseHolder.

Usually, containers call this method at shutdown or when an object is deleted. In certain cases, containers could call this method on objects that are running but not currently visible, as a way of reducing the overhead of maintaining multiple advisory connections.


IOleClientSite : IUnknown

This interface is the primary means by which an embedded object obtains information about the location and extent of its display site, moniker, user interface, and other resources provided by its container. An object server calls IOleClientSite to request services from the container. A container must provide one instance of IOleClientSite for every compound document object it contains.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Method
Description
IOleClientSite::GetContainer | Requests a pointer to an object’s container.
IOleClientSite::GetMoniker | Requests an object’s moniker.
IoleClientSite::OnShowWindow | Notifies a container when an object becomes visible or invisible.
IOleClientSite::RequestNewObjectLayout | Prompts a container to resize the display site.
IOleClientSite::SaveObject | Saves an embedded object.
IOleClientSite::ShowObject | Prompts a container to display an object.


IOleClientSite::GetContainer

This method requests a pointer to an object’s container.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESEUT GetContainer( LPOLECONTAINTER FAR * ppContainer);

Parameters

ppContainer
[out] Address of IOleContainer* pointer variable that receives the interface pointer to the container object. If an error occurs, the implementation must set *ppContainer to NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The pointer to the container’s IOleContainer interface was successfully returned.
OLE_E_NOT_SUPPORTED | Client site is in OLE 1 container.
E_NOINTERFACE | The container does not implement the IOleContainer interface.

Remarks

If a container supports links to its embedded objects, implementing IOleClientSite::GetContainer enables link clients to enumerate the container’s objects and recursively traverse a containment hierarchy. This method is optional but recommended for all containers that expect to support links to their embedded objects.

Link clients can traverse a hierarchy of compound-document objects by recursively calling IOleClientSite::GetContainer to get a pointer to the link source’s container; followed by IOleContainer::QueryInterface to get a pointer to the container’s IOleObject interface and, finally, IOleObject::GetClientSite to get the container’s client site in its container.

Simple containers that do not support links to their embedded objects probably do not need to implement this method. Instead, they can return E_NOINTERFACE and set ppContainer to NULL.


IOleClientSite::GetMoniker

This method requests an object’s moniker.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetMoniker( DWORD dwAssign, DWORD dwWhichMoniker,
IMoniker ** ppmk );

Parameters

dwAssign
[in] Determines how the moniker is assigned to the object. Depending on the value of dwAssign, IOleObject::GetMoniker does one of the following:
  • Obtains a moniker only if one has already been assigned,
  • Forces assignment of a moniker, if necessary, in order to satisfy the call, or
  • Obtains a temporary moniker.

Values for dwAssign are specified in the enumeration OLEGETMONIKER.

You cannot pass OLEGETMONIKER_UNASSIGN when calling IOleObject::GetMoniker. This value is valid only when calling IOleClientSite::GetMoniker.

dwWhichMoniker
[in] Specifies the form of the moniker being requested. Valid values are taken from the enumeration OLEWHICHMK.
ppmk
[out] Address of IMoniker* pointer variable that receives the interface pointer to the object’s moniker. If an error occurs, *ppmk must be set to NULL. Each time an object receives a call to GetMoniker, it must increase the reference count on *ppmk. It is the caller’s responsibility to call Release when it is done with *ppmk.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | Requested moniker returned successfully.
E_NOTIMPL | This container cannot assign monikers to objects. This is the case with OLE 1 containers.

Remarks

The IOleObject::GetMoniker method returns an object’s moniker. Like IOleObject::SetMoniker, this method is important only in the context of managing links to embedded objects and even in that case is optional. A potential link client that requires an object’s moniker to bind to the object can call this method to obtain that moniker. The default implementation of IOleObject::GetMoniker calls the IOleClientSite::GetMoniker, returning E_UNEXPECTED if the object is not running or does not have a valid pointer to a client site.


IOleClientSite::OnShowWindow

This method notifies container when an object becomes visible or invisible.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT OnShowWindow( BOOL fShow );

Parameters

fShow
[in] Boolean value that is set to TRUE if an object’s window is open, or set to FALSE if it is closed.

Return Values

S_OK indicatesthat shading or hatching has been successfully added or removed.

Remarks

An embedded object calls IOleClientSite::OnShowWindow to keep its container informed when the object is open in a window. This window may or may not be currently visible to the end user. The container uses this information to shade the object’s client site when the object is displayed in a window, and to remove the shading when the object is not. A shaded object, having received this notification, knows that it already has an open window and therefore can respond to being double-clicked by bringing this window quickly to the top, instead of launching its application in order to obtain a new one.


IOleClientSite::RequestNewObjectLayout

This method prompts a container to resize the display site.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT RequestNewObjectlayout();

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Request for new layout succeeded.
E_NOTIMPL | Client site does not support requests for new layout.

Remarks

Currently, there is no standard mechanism by which a container can negotiate how much room an object would like. When such a negotiation is defined, responding to this method will be optional for containers.


IOleClientSite::SaveObject

This method saves an embedded object.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SaveObject( void );

Return Values

This method supports the standard return value E_FAIL, as well as S_OK, which indicates that the object was saved.

Remarks

An embedded object calls IOleClientSite::SaveObject to ask its container to save it to persistent storage when an end user chooses the File Update or Exit commands. The call is synchronous, meaning that by the time it returns, the save operation will be completed.

Calls to IOleClientSite::SaveObject occur in most implementations of IOleObject::Close. Usually, when a container tells an object to close, the container passes a flag specifying whether the object should save itself before closing, prompt the user for instructions, or close without saving itself. If an object is instructed to save itself, either by its container or an end user, it calls IOleClientSite::SaveObject to ask the container application to save the object’s contents before the object closes itself. If a container instructs an object not to save itself, the object should not call SaveObject.


IOleClientSite::ShowObject

This method prompts a container to display an object.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ShowObject();

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Container has tried to make the object visible.
OLE_E_NOT_SUPPORTED | Client site is in an OLE 1 container.

Remarks

After a link client binds to a link source, it commonly calls IOleObject::DoVerb on the link source, usually requesting the source to perform some action requiring that it display itself to the user. As part of its implementation of DoVerb, the link source can call IOleClientSite::ShowObject, which forces the client to show the link source as best it can. If the link source’s container is itself an embedded object, it will recursively invoke IOleClientSite::ShowObject on its own container.

Having called the ShowObject method, a link source has no guarantee of being appropriately displayed because its container may not be able to do so at the time of the call. The ShowObject method does not guarantee visibility, only that the container will do the best it can.


IOleObject : IUnknown

This interface is the principal means by which an embedded object provides basic functionality to and communicates with its container.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

When to Implement

An object application must implement this interface, along with at least IDataObject and IPersistStorage, for each type of embedded object that it supports. Although this interface contains 21 methods, only three are nontrivial to implement and must be fully implemented: DoVerb, SetHostNames, and Close. Six of the methods provide optional functionality, which, if not desired, can be implemented to return E_NOTIMPL: SetExtent, InitFromData, GetClipboardData, SetColorScheme, SetMoniker, and GetMoniker. The latter two methods are useful mainly for enabling links to embedded objects.

When to Use

Call the methods of this interface to enable a container to communicate with an embedded object. A container must call DoVerb to activate an embedded object, SetHostNames to communicate the names of the container application and container document, and Close to move an object from a running to a loaded state. Calls to all other methods are optional.

Method
Description
IOleObject::Advise | Establishes an advisory connection between an OLE object and the calling object’s advise sink, through which the calling object receives notification when the compound document object is renamed, save, or closed.
IOleObject::Close | Changes an embedded object from the running to the loaded state. It also disconnects a linked object from its link source.
IOleObject::DoVerb | Requests an object to perform an action in response to an end-user’s action. The possible actions are enumerated for the object in IOleObject::EnumVerbs.
IOleObject::EnumAdvise | Retrieves a pointer to an enumerator that can be used to enumerate the advisory connections registered for an object, so a container knows what to release prior to closing down.
IOleObject::EnumVerbs | Exposes a pull-down menu listing the verbs available for an object in ascending order by verb number.
IOleObject::GetClientSite | Obtains a pointer to an embedded object’s client site.
IOleObject::GetClipboardData | Retrieves a data object that contains the current contents of the embedded object on which this method is called. Using the pointer to this data object, it is possible to create a new embedded object with the same data as the original.
IOleObject::GetExtent | Retrieves a running object’s current display size.
IOleObject::GetMiscStatus | Returns a value that indicates the status of an object at creation and loading.
IOleObject::GetMoniker | Retrieves an embedded object’s moniker, which the caller can use to link to the object.
IOleObject::GetUserClassID | Returns the object class identifier (CLSID) corresponding to the string identifying the object to an end-user.
IOleObject::GetUserType | Retrieves the user type name of an object for display in user interface elements such as menus, list boxes, and dialog boxes.
IOleObject::InitFromData | Initializes a newly created object with data from a specified data object, which can reside either in the same container or on the clipboard.
IOleObject::IsUpToDate | Checks recursively whether or not an object is current.
IOleObject::SetClientSite | Informs an embedded object of its display location, called a “client site,” within its container.
IOleObject::SetColorScheme | Specifies the color palette that the object application should use when it edits the specified object.
IOleObject::SetExtent | Informs an object of how much display space its container has assigned it.
IOleObject::SetHostNames | Provides an object with the name of its container application and the compound document in which it is embedded.
IOleObject::SetMoniker | Notifies an object of its container’s moniker, the object’s own moniker relative to the container, or the object’s full moniker.
IOleObject::Unadvise | Deletes a previously established advisory connection.
IOleObject::Update | Updates an object handler’s or link object’s data to view caches.


IOleObject::Advise

This method establishes an advisory connection between an OLE object and the calling object’s advise sink, through which the calling object receives notification when the compound document object is renamed, save, or closed.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Advise( IAdviseSink * pAdvSink, DWORD * pdwConnection);

Parameters

pAdvSink
[in] Pointer to the IAdviseSink interface on the advisory sink that should be informed of changes.
pdwConnection
[out] Pointer to a token that can be passed to the IOleAdviseHolder::Unadvise method to delete the advisory connection. The calling object is responsible for calling both IUnknown::AddRef and IUnknown::Release on this pointer.

Return Values

This method supports the standard return value E_INVALIDARG, as well as S_OK, which indicates that advisory connections set up successfully.

Remarks

Containers, object handlers, and link objects all create advise sinks to receive notification of changes in compound-document objects of interest, such as embedded or linked objects. OLE objects of interest to these objects must implement the IOleObject interface, which includes several advisory methods, including IOleObject::Advise. A call to this method must set up an advisory connection with any advise sink that calls it, and maintain each connection until it is closed. It must be able to handle more than one advisory connection at a time.

IOleAdviseHolder::Advise is intended to be used to simplify the implementation of IOleObject::Advise. You can get a pointer to the OLE implementation of IOleAdviseHolder by calling CreateOleAdviseHolder, and then, to implement IOleObject::Advise, just delegate the call to IOleAdviseHolder::Advise. Other IOleAdviseHolder methods are intended to implement other IOleObject advisory methods.

If the attempt to establish an advisory connection is successful, the object receiving the call returns a nonzero value through pdwConnection. If the attempt fails, the object returns a zero. To delete an advisory connection, the object with the advise sink passes this nonzero token back to the object by calling IOleAdviseHolder::Unadvise.


IOleObject::Close

This method changes an embedded object from the running to the loaded state. It also disconnects a linked object from its link source.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Close( DWORD dwSaveOption );

Parameters

dwSaveOption
[in] Specifies whether the object is to be saved as part of the transition to the loaded state. Valid values are taken from the enumeration OLECLOSE.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The object closed successfully.
OLE_E_PROMPTSAVECANCELLED | The user was prompted to save but chose the Cancel button from the prompt message box.

Remarks

The OLE 2 user model recommends that object applications do not prompt users before saving linked or embedded objects, including those activated in place. This policy represents a change from the OLE 1 user model, in which object applications always prompt the user to decide whether to save changes.

Notes to Callers

A container application calls IOleObject::Close when it wants to move the object from a running to a loaded state. Following such a call, the object still appears in its container but is not open for editing. Calling IOleObject::Close on an object that is loaded but not running has no effect. Closing a linked object simply means disconnecting it.

Notes to Implementers

Upon receiving a call to IOleObject::Close, a running object should do the following:

  • If the object has been changed since it was last opened for editing, it should request to be saved, or not, according to instructions specified in dwSaveOption. If the option is to save the object, then it should call its container’s IOleClientSite::SaveObject interface.
  • If the object has IDataObject::DAdvise connections with ADVF_DATAONSTOP flags, then it should send an OnDataChange notification.
  • If the object currently owns the Clipboard, it should empty it by calling OleFlushClipboard.
  • If the object is currently visible, notify its container by calling IOleClientSite::OnShowWindow with the fshow parameter set to FALSE.
  • Send IAdvise::OnClose notifications to appropriate advise sinks.
  • Finally, forcibly cut off all remoting clients by calling CoDisconnectObject.

If the object application is a local server (an EXE rather than a DLL), closing the object should also shut down the object application unless the latter is supporting other running objects or has another reason to remain in the running state. Such reasons might include the presence of IClassFactory::LockServer locks, end-user control of the application, or the existence of other open documents requiring access to the application.

Calling IOleObject::Close on a linked object disconnects it from, but does not shut down, its source application. A source application that is visible to the user when the object is closed remains visible and running after the disconnection and does not send an OnClose notification to the link container.


IOleObject::DoVerb

This method requests an object to perform an action in response to an end-user’s action. The possible actions are enumerated for the object in IOleObject::EnumVerbs.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DoVerb( LONG iVerb, LPMSG lpmsg,
IOleClientSite * pActiveSite, LONG lindex, HWND hwndParent,
LPCRECT lprcPosRect);

Parameters

iVerb
[in] Number assigned to the verb in the OLEVERB structure returned by IOleObject::EnumVerbs.
lpmsg
[in] Long pointer to the MSG structure describing the event that invoked the verb. The caller should pass the MSG structure unmodified, without attempting to interpret or alter the values of any of the members of lpmsg.
pActiveSite
[in] Pointer to the IOleClientSite interface on the object’s active client site, where the event occurred that invoked the verb.
lindex
[in] Reserved for future use; set to zero.
hwndParent
[in] Handle to the document window that contains the object. This and lprcPosRect together make it possible to open a temporary window for an object, where hwndParent is the parent window in which the object’s window is to be displayed, and lprcPosRect defines the area available for displaying the object window within that parent. A temporary window is useful, for example, to a multimedia object that opens itself for playback but not for editing.
lprcPosRect
[in] Long pointer to the RECT structure that contains the coordinates, in pixels, that define an object’s bounding rectangle in hwndParent. This and hwndParent together enable opening multimedia objects for playback but not for editing.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Object successfully invoked specified verb.
OLE_E_NOT_INPLACEACTIVE | The iVerb parameter is set to OLEIVERB_UIACTIVATE or OLEIVERB_INPLACEACTIVATE and object is not already visible.
OLE_E_CANT_BINDTOSOURCE | The object handler or link object cannot connect to the link source.
DV_E_LINDEX | Invalid lindex.
OLEOBJ_S_CANNOT_DOVERB_NOW | The verb is valid, but in the object’s current state it cannot carry out the corresponding action.
OLEOBJ_S_INVALIDHWND | DoVerb was successful but hwndParent is invalid.
OLEOBJ_E_NOVERBS | The object does not support any verbs.
OLEOBJ_S_INVALIDVERB | Object does not recognize a positive verb number. Verb is treated as OLEIVERB_PRIMARY.
MK_E_CONNECT | Link source is across a network that is not connected to a drive on this machine.
OLE_E_CLASSDIFF | Class for source of link has undergone a conversion.
E_NOTIMPL | Object does not support in-place activation or does not recognize a negative verb number.

Remarks

A “verb” is an action that an OLE object takes in response to a message from its container. An object’s container, or a client linked to the object, normally calls IOleObject::DoVerb in response to some end-user action, such as double-clicking on the object. The various actions that are available for a given object are enumerated in an OLEVERB structure, which the container obtains by calling IOleObject::EnumVerbs. IOleObject::DoVerb matches the value of iVerb against the iVerb member of the structure to determine which verb to invoke.

Through IOleObject::EnumVerbs, an object, rather than its container, determines which verbs (actions) it supports. OLE 2 defines seven verbs that are available, but not necessarily useful, to all objects. In addition, each object can define additional verbs that are unique to it. The following list describes the verbs defined by OLE:

OLEIVERB_PRIMARY (0L)
Specifies the action that occurs when an end user double-clicks the object in its container. The object, not the container, determines this action. If the object supports in-place activation, the primary verb usually activates the object in place.
OLEIVERB_SHOW (–1)
Instructs an object to show itself for editing or viewing. Called to display newly inserted objects for initial editing and to show link sources. Usually an alias for some other object-defined verb.
OLEIVERB_OPEN (–2)
Instructs an object, including one that otherwise supports in-place activation, to open itself for editing in a window separate from that of its container. If the object does not support in-place activation, this verb has the same semantics as OLEIVERB_SHOW.
OLEIVERB_HIDE (–3)
Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place.
OLEIVERB_UIACTIVATE (–4)
Activates an object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in the title bar of the container window. If the object does not support in-place activation, it should return E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (–5)
Activates an object in place without displaying tools, such as menus and toolbars, that end users need to change the behavior or appearance of the object. Single-clicking such an object causes it to negotiate the display of its user-interface tools with its container. If the container refuses, the object remains active but without its tools displayed.
OLEIVERB_DISCARDUNDOSTATE (–6)
Used to tell objects to discard any undo state that they may be maintaining without deactivating the object.

Note to Callers

Containers call IOleObject::DoVerb as part of initializing a newly created object. Before making the call, containers should first call IOleObject::SetClientSite to inform the object of its display location and IOleObject::SetHostNames to alert the object that it is an embedded object and to trigger appropriate changes to the user interface of the object application in preparation for opening an editing window.

Like the OleActivate function in OLE 1, IOleObject::DoVerb automatically runs the OLE server application. If an error occurs during verb execution, the object application is shut down.

If an end user invokes a verb by some means other than selecting a command from a menu (say, by double-clicking or, more rarely, single-clicking an object), the object’s container should pass a pointer (lpmsg) to a Windows MSG structure that contains the appropriate message. For example, if the end user invokes a verb by double-clicking the object, the container should pass a MSG structure that contains WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUTTONDBLCLK. If the container passes no message, lpmsg should be set to NULL. The object should ignore the hwnd member of the passed MSG structure, but can use all the other MSG members.

If the object’s embedding container calls IOleObject::DoVerb, the client-site pointer (pClientSite) passed to DoVerb is the same as that of the embedding site. If the embedded object is a link source, the pointer passed to DoVerb is that of the linking client’s client site.

When IOleObject::DoVerb is invoked on an OLE link, it may return OLE_E_CLASSDIFF or MK_CONNECTMANUALLY. The link object returns the former error when the link source has been subjected to some sort of conversion while the link was passive. The link object returns the latter error when the link source is located on a network drive that is not currently connected to the caller’s computer.

Container applications that do not support general in-place activation can still use the hwndParent and lprcPosRect parameters to support in-place playback of multimedia files. Containers must pass valid hwndParent and lprcPosRect parameters to IOleObject::DoVerb.

Some code samples pass a lindex value of –1 instead of zero. The value –1 works but should be avoided in favor of zero. The lindex parameter is a reserved parameter, and for reasons of consistency Microsoft recommends assigning a zero value to all reserved parameters.

Notes to Implementers

In addition to the above verbs, an object can define in its OLEVERB structure additional verbs that are specific to itself. Positive numbers designate these object-specific verbs. An object should treat any unknown positive verb number as if it were the primary verb and return OLE_S_INVALIDVERB to the calling function. The object should ignore verbs with negative numbers that it does not recognize and return E_NOTIMPL.

If the verb being executed places the object in the running state, you should register the object in the Running Object Table (ROT) even if its server application doesn’t support linking. Registration is important because the object at some point may serve as the source of a link in a container that supports links to embeddings. Registering the object with the ROT enables the link client to get a pointer to the object directly, instead of having to go through the object’s container. To perform the registration, call IOleClientSite::GetMoniker to get the full moniker of the object, call the GetRunningObjectTable function to get a pointer to the ROT, and then call IRunningObjectTable::Register.

Note When the object leaves the running state, remember to revoke the object’s registration with the ROT by calling IOleObject::Close. If the object’s container document is renamed while the object is running, you should revoke the object’s registration and re-register it with the ROT, using its new name. The container should inform the object of its new moniker either by calling IOleObject::SetMoniker or by responding to the object’s calling IOleClientSite::GetMoniker.

When showing a window as a result of DoVerb, it is very important for the object to explicitly call SetForegroundWindow on its editing window. This ensures that the object’s window will be visible to the user even if another process originally obscured it. For more information about SetForegroundWindow and SetActiveWindow, see the Platform SDK.


IOleObject::EnumAdvise

This method retrieves a pointer to an enumerator that can be used to enumerate the advisory connections registered for an object, so a container knows what to release prior to closing down.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IEnumSTATDATA( IEnumSTATDATA ** ppenumAdvise);

Parameters

ppenumAdvise
[out] Address of IEnumSTATDATA* pointer variable that receives the interface pointer to the new enumerator. A NULL value for *ppenumAdvise indicates that there are presently no advisory connections on the object, or that an error occurred. The advise holder is responsible for incrementing the reference count on the IEnumSTATDATA pointer this method supplies. It is the caller’s responsibility to call IUnknown::Release when it is done with the pointer.

Return Values

This method supports the standard return value E_FAIL, as well as the values described in the following table.

Value
Description
S_OK | Enumerator created successfully.
E_NOTIMPL | EnumAdvise is not implemented.

Remarks

IOleAdviseHolder::EnumAdvise creates an enumerator that can be used to enumerate an object’s established advisory connections. The method supplies a pointer to the IEnumSTATDATA interface on this enumerator. Advisory connection information for each connection is stored in the STATDATA structure, and the enumerator must be able to enumerate these structures, defined as follows:

typedef struct tagSTATDATA {
    FORMATETC         Formatetc;
    DWORD             grfAdvf;
    IAdviseSink *     pAdvise;
    DWORD             dwConnection;
    }STATDATA;

For this method, the only relevant structure members are pAdvise and dwConnection. Other members contain data advisory information. When you call the enumeration methods, and while an enumeration is in progress, the effect of registering or revoking advisory connections on what is to be enumerated is undefined.


IOleObject::EnumVerbs

This method exposes a pull-down menu listing the verbs available for an object in ascending order by verb number.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT EnumVerbs( IEnumOleVerb ** ppEnumOleVerb);

Parameters

ppEnumOleVerb
[out] Address of IEnumOleVerb* pointer variable that receives the interface pointer to the new enumerator object. Each time an object receives a call to EnumVerbs, it must increase the reference count on *ppEnumOleVerb. It is the caller’s responsibility to call Release when it is done with *ppEnumOleVerb. If an error occurs, *ppEnumOleVerb must be set to NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Verb(s) enumerated successfully.
OLE_S_USEREG | Delegate to the default handler to use the entries in the registry to provide the enumeration.
OLEOBJ_E_NOVERBS | Object does not support any verbs.

Remarks

Notes to Callers

Containers call this method to expose a pull-down menu of the verbs available for their embedded objects. You may want your container to call IOleObject::EnumVerbs each and every time such a menu is selected in order to enable such objects as media clips, whose verbs may change while they are running, to update their menus. The default verb for a media clip, for example, changes from “Play” before it is activated to “Stop” once it is running.

Notes to Implementers

The default handler’s implementation of IOleObject::EnumVerbs uses the registry to enumerate an object’s verbs. If an object application is to use the default handler’s implementation, it should return OLE_S_USEREG.

The enumeration returned is of type IEnumOLEVERB:

typedef Enum < OLEVERB > IEnumOLEVERB;

where OLEVERB is defined as:

typedef struct tagOLEVERB
{
    LONG    iVerb;
    LPOLESTR   lpszVerbName;
    DWORD   fuFlags;
    DWORD   grfAttribs;
} OLEVERB;

The following list describes the members of the OLEVERB structure:

iVerb
Verb number being enumerated. If the object supports OLEIVERB_OPEN, OLEIVERB_SHOW and/or OLEIVERB_HIDE (or another predefined verb), these will be the first verbs enumerated, since they have the lowest verb numbers.
lpszVerbName
Long pointer to the null-terminated string that contains the name of the verb.

In Windows, this value, along with optional embedded ampersand characters to indicate accelerator keys, can be passed to the AppendMenu function.

On the Macintosh, the following metacharacters may be passed along with this value:

  • ! marks the menu item with the subsequent character
  • < sets the character style of the item
  • ( disables the item.

The metacharacters / and ^ are not permitted.

fuFlags
In Windows, a group of flags taken from the flag constants beginning with MF_ defined in AppendMenu. Containers should use these flags in building an object’s verb menu. All flags defined in AppendMenu are supported except for MF_BITMAP, MF_OWNERDRAW, and MF_POPUP.
grfAttribs
In Windows, a group of flag bits taken from the enumeration OLEVERBATTRIB. The flag OLEVERBATTRIB_NEVERDIRTIES indicates that executing this verb will not cause the object to become dirty and is therefore in need of saving to persistent storage.

OLEVERBATTRIB_ONCONTAINERMENU indicates that this verb should be placed on the container’s menu of object verbs when the object is selected. OLEIVERB_HIDE, OLEIVERB_SHOW, and OLEIVERB_OPEN never have this value set.

For more information on the Windows AppendMenu function, see the Microsoft Win32 SDK.


IOleObject::GetClientSite

This method obtains a pointer to an embedded object’s client site.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetClientSite( IOleClientSite ** ppClientSite);

Parameters

ppClientSite
[out] Address of IOleClientSite* pointer variable that receives the interface pointer to the object’s client site. If an object does not yet know its client site, or if an error has occurred, *ppClientSite must be set to NULL. Each time an object receives a call to GetClientSite, it must increase the reference count on *ppClientSite. It is the caller’s responsibility to call Release when it is done with *ppClientSite.

Return Values

S_OK indicates that the client site pointer returned successfully.

Remarks

Link clients most commonly call the IOleObject::GetClientSite method in conjunction with the IOleClientSite::GetContainer method to traverse a hierarchy of nested objects. A link client calls IOleObject::GetClientSite to get a pointer to the link source’s client site. The client then calls IOleClientSite::GetContainer to get a pointer to the link source’s container. Finally, the client calls IOleContainer::QueryInterface to get IOleObject and IOleObject::GetClientSite to get the container’s client site within its container. By repeating this sequence of calls, the caller can eventually retrieve a pointer to the master container in which all the other objects are nested.

Notes to Callers

The returned client-site pointer will be NULL if an embedded object has not yet been informed of its client site. This will be the case with a newly loaded or created object when a container has passed a NULL client-site pointer to one of the object-creation helper functions but has not yet called IOleObject::SetClientSite as part of initializing the object.


IOleObject::GetClipboardData

This method retrieves a data object that contains the current contents of the embedded object on which this method is called. Using the pointer to this data object, it is possible to create a new embedded object with the same data as the original.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetClipboardData( DWORD dwReserved,
IDataObject ** ppDataObject );

Parameters

dwReserved
[in] Reserved for future use; set to zero.
ppDataObject
[out] Address of IDataObject* pointer variable that receives the interface pointer to the data object. If an error occurs, *ppDataObject must be set to NULL. Each time an object receives a call to GetClipboardData, it must increase the reference count on *ppDataObject. It is the caller’s responsibility to call Release when it is done with *ppDataObject.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The data transfer object is successfully returned.
E_NOTIMPL | GetClipboardData is not supported.
OLE_E_NOTRUNNING | The object is not running.

Remarks

You can use the GetClipboardData method to convert a linked object to an embedded object, in which case the container application would call IOleObject::GetClipboardData and then pass the data received to OleCreateFromData. This method returns a pointer to a data object that is identical to what would have been passed to the Clipboard by a standard copy operation.

Notes to Callers

If you want a stable snapshot of the current contents of an embedded object, call IOleObject::GetClipboardData. Should the data change, you will need to call the function again for an updated snapshot. If you want the caller to be informed of changes that occur to the data, call IDataObject::QueryInterface, then call IDataObject::DAdvise.

Notes to Implementers

If you implement this function, you must return an IDataObject pointer for an object whose data will not change.


IOleObject::GetExtent

This method retrieves a running object’s current display size.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetExtent( DWORD dwDrawAspect, SIZEL * psizel );

Parameters

dwDrawAspect
[in] Specifies the aspect of the object whose limit is to be retrieved; the value is obtained from the enumeration DVASPECT. The most common value for this method is DVASPECT_CONTENT, which specifies a full rendering of the object within its container.
psizel
[out] Pointer to where the object’s size is to be returned.

Return Values

This method supports the standard return value E_INVALIDARG, as well as S_OK, which indicates the extent information successfully returned.

Remarks

A container calls IOleObject::GetExtent on a running object to retrieve its current display size. If the container can accommodate that size, it will normally do so because the object, after all, knows what size it should be better than the container does. A container normally makes this call as part of initializing an object.

The display size returned by IOleObject::GetExtent may differ from the size last set by IOleObject::SetExtent because the latter method dictates the object’s display space at the time the method is called but does not necessarily change the object’s native size, as determined by its application.

Note This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. IViewObject2::GetExtent must do the same thing.

If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the DVASPECT_CONTENT aspect.

Notes to Implementers

Implementation consists of filling the sizel structure with an object’s height and width.


IOleObject::GetMiscStatus

This method returns a value that indicates the status of an object at creation and loading.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetMiscStatus( DWORD dwAspect, DWORD * pdwStatus);

Parameters

dwAspect
[in] Specifies the aspect of an object about which status information is being requested. The value is obtained from the enumeration DVASPECT (see “FORMATETC Data Structure”).
pdwStatus
[out] Pointer to where the status information is returned; cannot be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Status information returned successfully.
OLE_S_USEREG | Delegate the retrieval of miscellaneous status information to the default handler’s implementation of this method.
CO_E_CLASSNOTREG | There is no CLSID registered for the object.
CO_E_READREGDB | Error accessing the registry.

Remarks

A container normally calls IOleObject::GetMiscStatus when it creates or loads an object in order to determine how to display the object and what types of behaviors it supports.

Objects store status information in the registry. If the object is not running, the default handler’s implementation of IOleObject::GetMiscStatus retrieves this information from the registry. If the object is running, the default handler invokes IOleObject::GetMiscStatus on the object itself.

The default value of MiscStatus is used if a subkey corresponding to the specified DVASPECT is not found. To set an OLE control, specify DVASPECT==1. This will cause the following to occur in the Registry:

HKEY_CLASSES_ROOT\CLSID\ . . .\MiscStatus = 1

Notes to Implementers

Implementation normally consists of delegating the call to the default handler.


IOleObject::GetMoniker

This method retrieves an embedded object’s moniker, which the caller can use to link to the object.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetMoinker( DWORD dwAsign, DWORD dwWhichMoinker,
IMoniker ** ppmk);

Parameters

dwAssign
[in] Determines how the moniker is assigned to the object. Depending on the value of dwAssign, IOleObject::GetMoniker does one of the following:
  • Obtains a moniker only if one has already been assigned.
  • Forces assignment of a moniker, if necessary, in order to satisfy the call.
  • Obtains a temporary moniker.

Values for dwAssign are specified in the enumeration OLEGETMONIKER.

dwWhichMoniker
[in] Specifies the form of the moniker being requested. Valid values are taken from the enumeration OLEWHICHMK.
ppmk
[out] Address of IMoniker* pointer variable that receives the interface pointer to the object’s moniker. If an error occurs, *ppmk must be set to NULL. Each time an object receives a call to GetMoniker, it must increase the reference count on *ppmk. It is the caller’s responsibility to call Release when it is done with *ppmk.

Remarks

You cannot pass OLEGETMONIKER_UNASSIGN when calling IOleObject::GetMoniker. This value is valid only when calling IOleClientSite::GetMoniker.

The IOleObject::GetMoniker method returns an object’s moniker. Like IOleObject::SetMoniker, this method is important only in the context of managing links to embedded objects and even in that case is optional. A potential link client that requires an object’s moniker to bind to the object can call this method to obtain that moniker. The default implementation of IOleObject::GetMoniker calls the IOleClientSite::GetMoniker, returning E_UNEXPECTED if the object is not running or does not have a valid pointer to a client site.


IOleObject::GetUserClassID

This method returns the object class identifier (CLSID) corresponding to the string identifying the object to an end-user.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetUserClassID( CLSID * pClsid );

Parameter

pClsid
[out] Pointer to the class identifier (CLSID) to be returned. An object’s CLSID is the binary equivalent of the user-type name returned by IOleObject::GetUserType.

Return Values

This method supports the standard return value E_FAIL, as well as S_OK, which indicates that the CLSID returned successfully.

Remarks

GetUserClassID returns the CLSID associated with the object in the registration database. Usually, this value is identical to the CLSID stored with the object, which is returned by IPersist::GetClassID. For linked objects, this is the CLSID of the last bound link source. If the object is running in an application different from the one in which it was created and for the purpose of being edited is emulating a class that the container application recognizes, the CLSID returned will be that of the class being emulated rather than that of the object’s own class.


IOleObject::GetUserType

This method retrieves the user type name of an object for display in user interface elements such as menus, list boxes, and dialog boxes.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetUserType( DWORD dwFormOfType,
LPOLESTR * pszUserType );

Parameters

dwFormOfType
[in] Specifies the form of the user-type name to be presented to users. Valid values are obtained from the USERCLASSTYPE enumeration.
pszUserType
[out] Address of LPOLESTR pointer variable that receives a pointer to the user type string. The caller must free *pszUserType using the current IMalloc instance. If an error occurs, the implementation must set *pszUserType to NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The object’s user-type name is successfully returned.
OLE_S_USEREG | Delegate to the default handler’s implementation using the registry to provide the requested information.

Remarks

Containers call IOleObject::GetUserType in order to represent embedded objects in list boxes, menus, and dialog boxes by their normal, user-recognizable names. Examples include “Word Document,” “Excel Chart,” and “Paintbrush Object.” The information returned by IOleObject::GetUserType is the user-readable equivalent of the binary class identifier returned by IOleObject::GetUserClassID.

Notes to Callers

The default handler’s implementation of IOleObject::GetUserType uses the object’s class identifier (the pClsid parameter returned by IOleObject::GetUserClassID) and the dwFormOfType parameter together as a key into the registry. If an entry is found that matches the key exactly, then the user type specified by that entry is returned. If only the CLSID part of the key matches, then the lowest-numbered entry available (usually the full name) is used. If the CLSID is not found, or there are no user types registered for the class, the user type currently found in the object’s storage is used.

You should not cache the string returned from GetUserType. Instead, call this method each and every time the string is needed. This guarantees correct results when the embedded object is being converted from one type into another without the caller’s knowledge. Calling this method is inexpensive because the default handler implements it using the registry.

Notes to Implementers

You can use the implementation provided by the default handler by returning OLE_S_USEREG as your application’s implementation of this method. If the user type name is an empty string, the message “Unknown Object” is returned.


IOleObject::InitFromData

This method initializes a newly created object with data from a specified data object, which can reside either in the same container or on the clipboard.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT InitFromData( IDataObject * pDataObject, BOOL fCreation,
DWORD dwReserved );

Parameters

pDataObject
[in] Pointer to the IDataObject interface on the data object from which the initialization data is to be obtained. This parameter can be NULL, which indicates that the caller wants to know if it is worthwhile trying to send data; that is, whether the container is capable of initializing an object from data passed to it. The data object to be passed can be based on either the current selection within the container document or on data transferred to the container from an external source.
fCreation
[in] Boolean value that is set to TRUE if the container is inserting a new object inside itself and initializing that object with data from the current selection, or to FALSE if a more general programmatic data transfer, most likely from a source other than the current selection.
dwReserved
[in] Reserved for future use; set to zero.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | If pDataObject is not NULL, the object successfully attempted to initialize itself from the provided data; if pDataObject is NULL, the object is able to attempt a successful initialization.
S_FALSE | If pDataObject is not NULL, the object made no attempt to initialize itself; if pDataObject is NULL, the object cannot attempt to initialize itself from the data provided.
E_NOTIMPL | The object does not support InitFromData.
OLE_E_NOTRUNNING | The object is not running and therefore cannot perform the operation.

Remarks

This method enables a container document to insert within itself a new object whose content is based on a current data selection within the container. For example, a spreadsheet document may want to create a graph object based on data in a selected range of cells.

Using this method, a container can also replace the contents of an embedded object with data transferred from another source. This provides a convenient way of updating an embedded object.

Notes to Callers

Following initialization, the container should call IOleObject::GetMiscStatus to check the value of the OLEMISC_INSERTNOTREPLACE bit. If the bit is on, the new object inserts itself following the selected data. If the bit is off, the new object replaces the selected data.

Notes to Implementers

A container specifies whether to base a new object on the current selection by passing either TRUE or FALSE to the fCreation parameter.

If fCreation is TRUE, the container is attempting to create a new instance of an object, initializing it with the selected data specified by the data object.

If fCreation is FALSE, the caller is attempting to replace the object’s current contents with that pointed to by pDataObject. The usual constraints that apply to an object during a paste operation should be applied here. For example, if the type of the data provided is unacceptable, the object should fail to initialize and return S_FALSE.

If the object returns S_FALSE, it cannot initialize itself from the provided data.


IOleObject::IsUpToDate

This method checks recursively whether or not an object is current.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsUpToDate();

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Object is up to date.
S_FALSE | Object is not up to date.
OLE_E_UNAVAILABLE | Status of object cannot be determined in a timely manner.

Remarks

The IsUpToDate method provides a way for containers to check recursively whether or not all objects are up to date. That is, when the container calls this method on the first object, the object in turn calls it for all its own objects, and they in turn for all of theirs, until all objects have been checked.

Notes to Implementers

Because of the recursive nature of IOleObject:IsUpToDate, determining whether an object is out-of-date, particularly one that contains one or more other objects, can be as time-consuming as simply updating the object in the first place. If you would rather avoid lengthy queries of this type, make sure that IOleObject::IsUpToDate returns OLE_E_UNAVAILABLE. In cases where the object to be queried is small and contains no objects itself, thereby making an efficient query possible, this method can return either S_OK or S_FALSE.


IOleObject::SetClientSite

This method informs an embedded object of its display location, called a “client site,” within its container.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetClientSite( IOleClientSite * pClientSite );

Parameters

pClientSite
[in] Pointer to the IOleClientSite interface on the container application’s client-site.

Return Values

This method supports the standard return value E_UNEXPECTED, as well as S_OK, which indicates that the client site successfully set.

Remarks

Within a compound document, each embedded object has its own client site —the place where it is displayed and through which it receives information about its storage, user interface, and other resources. IOleObject::SetClientSite is the only method enabling an embedded object to obtain a pointer to its client site.

Notes to Callers

A container can notify an object of its client site either at the time the object is created or, subsequently, when the object is initialized.

When creating or loading an object, a container may pass a client-site pointer (along with other parameters) to OleCreate, a helper function. This helper function loads an object handler for the new object and calls IOleObject::SetClientSite on the container’s behalf before returning a pointer to the new object.

Passing a client-site pointer informs the object handler that the client site is ready to process requests. If the client site is unlikely to be ready immediately after the handler is loaded, you may want your container to pass a NULL client-site pointer to the helper function. The NULL pointer says that that no client site is available and thereby defers notifying the object handler of the client site until the object is initialized. In response, the helper function returns a pointer to the object, but upon receiving that pointer the container must call SetClientSite as part of initializing the new object.

Notes to Implementers

Implementation consists simply of incrementing the reference count on, and storing, the pointer to the client site.


IOleObject::SetColorScheme

This method specifies the color palette that the object application should use when it edits the specified object.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetColorScheme( LOGPALETTE * pLogpal );

Parameters

pLogpal
[in] Pointer to a LOGPALETTE structure that specifies the recommended palette.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Color palette received successfully.
E_NOTIMPL | Object does not support setting palettes.
OLE_E_PALETTE | Invalid LOGPALETTE structure pointed to by lpLogPal.
OLE_E_NOTRUNNING | Object must be running to perform this operation.

Remarks

The IOleObject::SetColorScheme method sends the container application’s recommended color palette to the object application, which is not obliged to use it.

Notes to Implementers

Upon receiving the palette, the object application should:

  1. Allocate and fill in its own LOGPALETTE structure with the colors specified in the container application’s LOGPALETTE structure.
  2. Call CreatePalette to create a palette from the resulting LOGPALETTE structure. This palette can be used to render objects and color menus as the user edits objects in the document.

The first palette entry in the LOGPALETTE structure specifies the foreground color recommended by the container. The second palette entry specifies the recommended background color. The first half of the remaining palette entries are fill colors and the second half are colors for the lines and text.

Container applications typically specify an even number of palette entries. If a container specifies an odd number of entries, the object application should assume that the first half of the total entries plus one designate fill colors, while the remainder designate line and text colors. For example, if there are five entries, the first three should be interpreted as fill colors and the last two as line and text colors.


IOleObject::SetExtent

This method informs an object of how much display space its container has assigned it.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetExtent( DWORD dwDrawAspect, SIZEL * psizel );

Parameters

dwDrawAspect
[in] Describes which form, or “aspect,” of an object is to be displayed. The object’s container obtains this value from the enumeration DVASPECT (refer to the FORMATETC enumeration). The most common aspect is DVASPECT_CONTENT, which specifies a full rendering of the object within its container. An object can also be rendered as an icon, a thumbnail version for display in a browsing tool, or a print version, which displays the object as it would be rendered using the File Print command.
psizel
[in] Pointer to the size limit for the object.

Return Values

This method supports the standard return value E_FAIL, as well as the values described in the following table.

Value
Description
S_OK | The object has resized successfully.
OLE_E_NOTRUNNING | The object is not running.

Remarks

A container calls IOleObject::SetExtent when it needs to dictate to an embedded object the size at which it will be displayed. Often, this call occurs in response to an end user resizing the object window. Upon receiving the call, the object, if possible, should recompose itself gracefully to fit the new window.

Whenever possible, a container seeks to display an object at its finest resolution, sometimes called the object’s native size. All objects, however, have a default display size specified by their applications, and in the absence of other constraints, this is the size they will use to display themselves. Since an object knows its optimum display size better than does its container, the latter normally requests that size from a running object by calling IOleObject::GetExtent. Only in cases where the container cannot accommodate the value returned by the object does it override the object’s preference by calling IOleObject::SetExtent.

Notes to Callers

You can call SetExtent on an object only when the object is running. If a container resizes an object while an object is not running, the container should keep track of the object’s new size but defer calling IOleObject::SetExtent until a user activates the object. If the OLEMISC_RECOMPOSEONRESIZE bit is set on an object, its container should force the object to run before calling OleObject::SetExtent.

As noted above, a container may want to delegate responsibility for setting the size of an object’s display site to the object itself, by calling IOleObject::GetExtent.

Notes to Implementers

You may want to implement this method so that your object rescales itself to match as closely as possible the maximum space available to it in its container.

If an object’s size is fixed, that is, if it cannot be set by its container, OleObject::SetExtent should return E_FAIL. This is always the case with linked objects, whose sizes are set by their link sources, not by their containers.


IOleObject::SetHostNames

This method provides an object with the name of its container application and the compound document in which it is embedded.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetHostNames( LPCOLESTR szContainerApp,
LPCOLESTR szContainerObj );

Parameters

szContainerApp
[in] NULL-terminated string that contains the name of the container application in which the object is running.
szContainerObj
[in] NULL-terminated string that contains the name of the compound document that contains the object. If you do not wish to display the name of the compound document, you can set this parameter to NULL.

Return Values

S_OK indicates that the window title information set successfully.

Remarks

When a container initializes an embedded object, it calls this function to inform the object of the names of both the container application and container document. When the object is opened for editing, it displays these names in the title bar of its window.

Notes to Callers

Call SetHostNames only for embedded objects, because for linked objects, the link source supplies its own separate editing window and title bar information.

Notes to Implementers

An object’s application of SetHostNames should include whatever modifications to its user interface may be appropriate to an object’s embedded state. Such modifications typically will include adding and removing menu commands and altering the text displayed in the title bar of the editing window.

The complete window title for an embedded object in an SDI container application or an MDI application with a maximized child window should appear as follows:

<object application name> – <object short type> in <container document>

Otherwise, the title should be:

<object application name> – <container document>

The “object short type” refers to a form of an object’s name short enough to be displayed in full in a list box.

Since these identifying strings are not stored as part of the persistent state of the object, IOleObject::SetHostNames must be called each time the object loads or runs.


IOleObject::SetMoniker

This method notifies an object of its container’s moniker, the object’s own moniker relative to the container, or the object’s full moniker.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESUTL SetMoniker( DWORD dwWhichMoinker, IMoniker * pmk );

Parameters

dwWhichMoniker
[in] Specifies which moniker is passed in pmk. Values are from the enumeration OLEWHICHMK.
pmk
[in] Pointer to where to return the moniker.

Return Values

This method supports the standard return value E_FAIL, as well as S_OK, which indicates that the moniker successfully set.

Remarks

A container that supports links to embedded objects must be able to inform an embedded object when its moniker has changed. Otherwise, subsequent attempts by link clients to bind to the object will fail. The IOleObject::SetMoniker method provides one way for a container to communicate this information.

The container can pass either its own moniker, an object’s moniker relative to the container, or an object’s full moniker. In practice, if a container passes anything other than an object’s full moniker, each object calls the container back to request assignment of the full moniker, which the object requires to register itself in the running object table.

The moniker of an object relative to its container is stored by the object handler as part of the object’s persistent state. The moniker of the object’s container, however, must not be persistently stored inside the object because the container can be renamed at any time.

Notes to Callers

A container calls IOleObject::SetMoniker when the container has been renamed, and the container’s embedded objects currently or can potentially serve as link sources. Containers call SetMoniker mainly in the context of linking because an embedded object is already aware of its moniker. Even in the context of linking, calling this method is optional because objects can call IOleClientSite::GetMoniker to force assignment of a new moniker.

Note to Implementers

Upon receiving a call to SetMoniker, an object should register its full moniker in the running object table and send OnRename notification to all advise sinks that exist for the object.


IOleObject::Unadvise

This method deletes a previously established advisory connection.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Unadvise( DWORD dwConnection );

Parameter

dwConnection
[in] Contains a nonzero DWORD previously returned by IOleAdviseHolder::Advise in pdwConnection.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Advisory connection deleted successfully.
OLE_E_NOCONNECTION | The dwConnection parameter does not represent a valid advisory connection.

Remarks

IOleAdviseHolder::Unadvise is intended to be used to implement IOleObject::Unadvise to delete an advisory connection. In general, you would use the OLE advise holder having obtained a pointer through a call to CreateOleAdviseHolder.

Usually, containers call this method at shutdown or when an object is deleted. In certain cases, containers could call this method on objects that are running but not currently visible, as a way of reducing the overhead of maintaining multiple advisory connections.


IOleObject::Update

This method updates an object handler’s or link object’s data to view caches.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Update();

Return Values

This method supports the standard return value E_FAIL, as well as the values described in the following table.

Value
Description
S_OK | All caches are up to date.
OLE_E_CANT_BINDTOSOURCE | Cannot run object to get updated data. The object is for some reason unavailable to the caller.
CACHE_E_NOCACHE_UPDATED | No caches were updated.
CACHE_S_SOMECACHES_
NOTUPDATED 		Some caches were not updated.

Remarks

The Update method provides a way for containers to keep data updated in their linked and embedded objects. A link object can become out-of-date if the link source has been updated. An embedded object that contains links to other objects can also become out of date. An embedded object that does not contain links cannot become out of date because its data is not linked to another source.

Notes to Implementers

When a container calls a link object’s IOleObject::Update method, the link object finds the link source and gets a new presentation from it. This process may also involve running one or more object applications, which could be time-consuming.

When a container calls an embedded object’s IOleObject::Update method, it is requesting the object to update all link objects it may contain. In response, the object handler recursively calls IOleObject::Update for each of its own linked objects, running each one as needed.


IPegasusFileFilter : IUnknown

This interface is implemented by a file converter DLL. The H/PC Explorer uses OLE to create an instance of an IPegasusFileFilter object.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Methods
Description
IPegasusFileFilter::FilterOptions | Displays a dialog box that lets the user select among the file filtering options supported by a file filter.
IPegasusFileFilter::FormatMessage | Formats a message string.
IPegasusFileFilter::NextConvertFile | Called by the H/PC Explorer when the user selects a conversion type from the H/PC Explorer conversion selection dialog box.


IPegasusFileFilter::FilterOptions

This method displays a dialog box that lets the user select among the file filtering options supported by a file filter.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.01 and later

Syntax

STDMETHODIMP IPegasusFileFilter::FilterOptions( HWND hwndParent);

Parameters

hwndParent
Handle to the parent window for the filtering options dialog box.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A file filter that includes user selectable conversion options should implement an IPegasusFileFilter::FilterOptions method. H/PC Explorer calls the filter’s IPegasusFileFilter::FilterOptions method when the user selects a supported conversion type from the conversion selection dialog box and presses the Options button, which is not supported for Windows CE version 1.0. FilterOptions should display a dialog box that lets the user select among the conversion options supported by the file filter.

Note that a file filter only needs to support the IPegasusFileFilter::FilterOptions method if the HasOptions named value exists in the HKEY_CLASSES_ROOT\CLSID\<CLSID>\PegasusFilter key. For more information about file filter registry entries and extension keys, see Transferring Files.


IPegasusFileFilter::FormatMessage

This method formats a message string.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHOD(FormatMessage) (THIS_ DWORD dwFlags,
DWORD dwMessageId, DWORD dwLanguageId, LPTSTR lpBuffer,
DWORD nSize, va_list *Arguments, DWORD *pcb ) PURE;

Parameters

dwFlags
Contains a set of bit flags that specify aspects of the formatting process and how to interpret the lpSource parameter. The low-order byte of dwFlags specifies how FormatMessage handles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

It can be a combination of the following flags:
Value
Description
FORMAT_MESSAGE_ALLOCATE_BUFFER | Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of bytes (ANSI version) or characters (Unicode version) to allocate for an output message buffer. FormatMessage allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed.
FORMAT_MESSAGE_IGNORE_INSERTS | Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for retrieving a message for later formatting. If this flag is set, the Arguments parameter is ignored.
FORMAT_MESSAGE_FROM_STRING | Specifies that lpSource is a pointer to a null-terminated message definition. The message definition can contain insert sequences, just as the message text in a message table resource can. This flag cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM.
FORMAT_MESSAGE_FROM_HMODULE | Specifies that lpSource is a module handle containing the message table resources to search. If this lpSource handle is NULL, the current process’s application image file is searched. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.
FORMAT_MESSAGE_FROM_SYSTEM | Specifies that FormatMessage should search the system message table resources for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, FormatMessage searches the system message table if the message is not found in the module specified by lpSource. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.
If this flag is specified, an application can pass the result of the GetLastError function to retrieve the message text for a system-defined error.
FORMAT_MESSAGE_ARGUMENT_ARRAY | Specifies that the Arguments parameter is not a va_list structure, but instead is pointer to an array of 32-bit values that represent the arguments.

The low-order byte of dwFlags can specify the maximum width of a formatted output line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations to set and retrieve this maximum width value.

FormatMessage interprets the value of the low-order byte as follows:
Value
Description
0 | There are no output line width restrictions. FormatMessage stores line breaks that are in the message definition text in the output buffer.
A nonzero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK
The nonzero value is the maximum number of characters in an output line. FormatMessage ignores regular line breaks in the message definition text. FormatMessage never splits a string delimited by white space across a line break. FormatMessage stores hard-coded line breaks in the message definition text in the output buffer. Hard-coded line breaks are coded with the %n escape sequence.
FORMAT_MESSAGE_MAX_WIDTH_MASK | FormatMessage ignores regular line breaks in the message definition text. FormatMessage stores hard-coded line breaks in the message definition text in the output buffer. FormatMessage generates no new line breaks.

dwMessageId
Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
dwLanguageId
Specifies the 32-bit language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
lpBuffer
Long pointer to a buffer for the formatted and null-terminated message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, FormatMessage allocates a buffer using the LocalAlloc function, and places the address of the buffer at the address specified in lpBuffer.
nSize
If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the maximum number of bytes (ANSI version) or characters (Unicode version) that can be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of bytes or characters to allocate for an output buffer.
Arguments
Pointer to an array of 32-bit values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the Arguments array, %2 indicates the second argument, and so on.

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string.

By default, the Arguments parameter is of type va_list *, which is a language- and implementation-specific data type for describing a variable number of arguments. If you do not have a pointer of type va_list *, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 32-bit values; those values are used as input for the message and are formatted as the insert values. Each insert must have a corresponding element in the array.

pcb
Pointer to a DWORD that receives the length of the string returned by FormatMessage. If FormatMessage succeeds, pcb holds the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | FormatMessage was successful. The variable pointed to by the pcb parameter should be non-zero.
E_FAIL | FormatMessage failed.

Remarks

The FormatMessage method requires a message definition as input. The message definition can come from a buffer passed into FormatMessage, from a message table resource in an already-loaded module, or the caller can prompt FormatMessage to search the system’s message table resources. FormatMessage finds the message definition in a message table resource based on a message identifier and a language identifier. FormatMessage copies the formatted message text to an output buffer, processing any embedded insert sequences if requested. FormatMessage also allows the filter to define message codes specific to the filter. For more information, see Transferring Files.


IPegasusFileFilter::NextConvertFile

This method is called by the H/PC Explorer when the user selects a conversion type from the H/PC Explorer conversion selection dialog box.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilter::NextConvertFile(
int nConversion, PFF_CONVERTINFO *pci, PFF_SOURCEFILE *psf,
PFF_DESTINATIONFILE *pdf, volatile BOOL *pbCancel,
PR_ERROR *perr );

Parameters

nConversion
Counter for converting a single source file into multiple destination files. This parameter is zero the first time NextConvertFile is called and is incremented for each successive call. A simple filter should return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) if this parameter is not zero.
pci
Pointer to a PFF_CONVERTINFO structure that contains a pointer to an IPegasusFileFilterSite object. A file filter uses this interface to create an IStream or IStorage object to read the contents of the source file or to write to the destination file. The type of interface object to create is determined by the nHowToOpen parameter in the IPegasusFileFilterSite::OpenSourceFile and IPegasusFileFilterSite::OpenDestinationFile methods. Any files opened in this way should be closed using the corresponding IPegasusFileFilterSite::CloseSourceFile or IPegasusFileFilterSite::CloseDestinationFile method.
psf
Pointer to a PFF_SOURCEFILE structure that contains information about the source file.
pdf
Pointer to a PFF_DESTINATIONFILE structure that contains information about the destination file.
pbCancel
Pointer to a Boolean value that is set to TRUE if the user cancels the file conversion before it is completed, or to FALSE otherwise. Because this variable is updated asynchronously by another thread, its contents can change at any time. A file filter must check this variable regularly during the conversion process, and return ERROR_CANCELLED (after cleaning up) if it is ever set to TRUE.
perr
Pointer to a filter-defined error value that can be passed by the H/PC Explorer application to the IPegasusFileFilter::FormatMessage method. This error value is ignored unless the return value from NextConvertFile is E_FAIL.

Return Values

One of the values described in the following table is returned.

NOERROR
The subconversion was successful; proceed to the next subconversion.
HRESULT_FROM_WIN32 (ERROR_CANCELLED)
The user canceled the conversion.
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)
The conversion, or last subconversion, was successful. End calls to IPegasusFileFilter::NextConvertFile.
E_FAIL
The perr parameter contained an error value that should be passed to IPegasusFileFilter::FormatMessage.

Remarks

H/PC Explorer calls the IPegasusFileFilter::NextConvertFile method repeatedly, incrementing the nConversion parameter, until the return value is ERROR_NO_MORE_ITEMS. A simple filter should return NOERROR the first time this method is called, and thereafter return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS). Alternatively, a file filter can return E_FAIL and specify a filter-defined error code in the variable pointed to by perr.

As a file conversion progresses, a file filter should periodically call IPegasusFileFilterSite::ReportProgress to report its progress. H/PC Explorer uses the progress information to update a progress bar that shows the user how much of the conversion is complete.

If any important data is intentionally discarded by a file filter during the conversion process, the filter should call IPegasusFileFilterSite::ReportLoss to report the loss. When calling this ReportLoss, the filter specifies a message that explains the data loss, and H/PC Explorer formats and displays the message in a message box when the file conversion has completed. For more information, see Transferring Files.

See Also

IPegasusFileFilterSite::ReportLoss, IPegasusFileFilterSite::ReportProgress


IPegasusFileFilterSite : IUnknown

This interface is implemented by the H/PC Explorer. A pointer to this interface is passed to some file filter methods.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Methods
Description
IPegasusFileFilterSite::OpenSourceFile | Called by a file filter to open a source file.
IPegasusFileFilterSite::OpenDestinationFile | Called by a file filter to open a destination file.
IPegasusFileFilterSite::CloseSourceFile | Called by a file filter to close a source file.
IPegasusFileFilterSite::CloseDestinationFile | Called by a file filter to close a destination file.
IPegasusFileFilterSite::ReportProgress | Called by a file filter to report the progress of a file conversion.
IPegasusFileFilterSite::ReportLoss | Called by a file filter to report any information that it intentionally discarded during a file conversion. The file filter specifies a message that explains the data loss, and H/PC Explorer formats and displays the message in a message box when the file conversion is complete. The file filter can specify either the identifier of a message table resource, or the address of a buffer that contains the message string.


IPegasusFileFilterSite::CloseDestinationFile

This method is called by a file filter to close a destination file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilterSite::CloseDestinationFile(
BOOL bKeepFile, LPUNKNOWN pObj );

Parameters

bKeepFile
Boolean value that indicates whether to keep or delete the destination file. A file filter should set this parameter to TRUE to keep the destination file, or FALSE to delete it.
pObj
Pointer to an IUnknown object returned from the IPegasusFileFilterSite::OpenDestinationFile method.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.


IPegasusFileFilterSite::CloseSourceFile

This method is called by a file filter to close a source file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilterSite::CloseSourceFile(
LPUNKNOWN pObj );

Parameters

pObj
Pointer to the IUnknown object returned from the IPegasusFileFilterSite::OpenSourceFile method.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.


IPegasusFileFilterSite::OpenDestinationFile

This method is called by a file filter to open a destination file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilterSite::OpenDestinationFile(
int nHowToOpenFile, LPCSTR pszFullpath, LPVOID *ppObj );

Parameters

nHowToOpenFile
Specifies how the source file is to be opened. It is one of the following values:
PF_OPENFLAT
Open as a flat file.
PF_OPENCOMPOUND
Open as an OLE compound file. Note that Windows CE does not support compound files.
pszFullpath
Pointer to the null-terminated string that contains the name of the file to open to override the default destination file name. If this parameter is NULL, the default destination file name will be used.
ppObj
Pointer to an LPVOID variable that receives an IStream pointer if nHowToOpenFile is PF_OPENFLAT, or an IStorage pointer if nHowToOpenFile is PF_OPENCOMPOUND. This object must be released using the IPegasusFileFilterSite::CloseDestinationFile method before returning to H/PC Explorer.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.

Remarks

The default destination file name and path are specified in the PFF_DESTINATIONFILE structure that is passed in to the call to IPegasusFileFilter::NextConvertFile. The default path is temporary and is managed by H/PC Explorer. For example, if the user drags a bitmap file named Tmp.bmp from the desktop computer to the H/PC, the default destination file name is Tmp.2bp.

The following code example shows how the destination file can be modified when the file filter’s IPegasusFileFilter::NextConvertFile method calls the IPegasusFileFilterSite::OpenDestinationFile method.

// Filter and copy Tmp.bmp on desktop computer to Tmp1.2bp on Windows CE–based device
PFF_DESTINATIONFILE *pdf;
IStream *pstmDst;         // Open the destination file as a stream
TCHAR szBuf[80];

lstrcpy(szBuf, pdf->szPath);        // Use default path …
lstrcat(szBuf, TEXT("TMP1.2bp") );  // … but modify the file name

hres = pffs->OpenDestinationFile(PF_OPENFLAT, szBuf, (LPVOID*)&pstmDst);

In this example, note that the path to the directory containing the temporary destination was preserved. The reason is that, after the file filter conversion is complete—that is, NextConvertFile has returned ERROR_NO_MORE_ITEMS—H/PC Explorer looks in szPath and copies all files, regardless of file or extension name, to the target folder, as directed by the user.

The temporary destination file path must be located on the desktop computer, but the path can be modified as desired.

Note that OpenDestinationFile can be called only once within a specified call to IPegasusFileFilter::NextConvertFile.

See Also

IPegasusFileFilterSite::CloseDestinationFile


IPegasusFileFilterSite::OpenSourceFile

This method is called by a file filter to open a source file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilterSite::OpenSourceFile(
int nHowToOpenFile, LPVOID *ppObj );

Parameters

nHowToOpenFile
Specifies how the source file is to be opened. It is one of the following values:
Value
Description
PF_OPENFLAT | Open as a flat file.
PF_OPENCOMPOUND | Open as an OLE compound file. Note that Windows CE does not support compound files.

ppObj
Pointer to an LPVOID variable that receives an IStream pointer if nHowToOpenFile is PF_OPENFLAT, or an IStorage pointer if nHowToOpenFile is PF_OPENCOMPOUND. This object must be released using the IPegasusFileFilterSite::CloseSourceFile method before returning to H/PC Explorer.

Return Values

NOERROR indicates success. An HRESULT_FROM_WIN32 error value indicates failure.

Remarks

The IPegasusFileFilterSite::OpenSourceFile method opens the file specifed by the PFF_SOURCEFILE structure. H/PC Explorer passes a pointer to this structure in the call to the file filter’s IPegasusFileFilter::NextConvertFile method.

See Also

IPegasusFileFilter::NextConvertFile


IPegasusFileFilterSite::ReportLoss

This method is called by a file filter to report any information that it intentionally discarded during a file conversion. The file filter specifies a message that explains the data loss, and H/PC Explorer formats and displays the message in a message box when the file conversion is complete. The file filter can specify either the identifier of a message table resource, or the address of a buffer that contains the message string.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilterSite::ReportLoss( DWORD dw,
LPCTSTR psz, va_list * Arguments );

Parameters

dw
Specifies a 32-bit message identifier. ReportLoss uses IPegasusFileFilter::FormatMessage to format the message. If the format fails—for example, the message identifier could not be recognized—then the system function FormatMessage is used.
psz
Pointer to the null-terminated message string to display. This parameter should be NULL if the dw parameter is used.
Arguments
Pointer to an array of 32-bit values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the Arguments array, %2 indicates the second argument, and so on.

Return Values

None.

Remarks

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string. By default, the Arguments parameter is of type va_list*, which is a language- and implementation-specific data type for describing a variable number of arguments.

If the Win32 error value—passed in the dw parameter of the IPegasusFileFilterSite::ReportLoss method—to be formatted with FormatMessage is not NULL, then the H/PC Explorer first calls the file filter’s IPegasusFileFilter::FormatMessage method—that is, in the current module—to request a description of the error. If the file filter’s FormatMessage fails, then the H/PC Explorer attempts to identify the error using the system FormatMessage call.

If dw is NULL, then the strings passed in the psz and Arguments parameters are reported in a message by the H/PC Explorer when the file conversion is complete. Note that only one of the parameters dw or psz should not be NULL. That is, either a message identifier or a message string may be passed in the call to ReportLoss.


IPegasusFileFilterSite::ReportProgress

This method is called by a file filter to report the progress of a file conversion.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

STDMETHODIMP IPegasusFileFilterSite::ReportProgress(UINT nPercent);

Parameters

nPercent
Specifies the completed percentage of the operation. For example, if the file filter has converted 25 percent of a file, this parameter should be set to 25.

Return Values

None.

Remarks

H/PC Explorer displays a progress bar that indicates the progress of a file conversion, and uses the percentage provided by the filter to set the current position of the progress bar. The filter should periodically call ReportProgress as the conversion progresses.

Consider that updating the progress bar takes a certain amount of time. Therefore, you may want to limit the frequency at which the application calls the ReportProgress method, since calling this method too often can add substantially to the actual file copy and conversion time.


Ipersist : IUnknown

This interface defines the single method GetClassID, which is designed to supply the class identifier (CLSID) of an object that can be stored persistently in the system. A call to this method can allow the object to specify which object handler to use in the client process, as it is used in the OLE default implementation of marshaling.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

The IPersist interface defines the single method GetClassID, which is designed to supply the CLSID of an object that can be stored persistently in the system. A call to this method can allow the object to specify which object handler to use in the client process, as it is used in the OLE default implementation of marshaling.

IPersist is the base interface for another interface, IPersistStorage. This interface, therefore, includes the GetClassID method, and is implemented on objects that can be serialized to a storage. The methods of this interface allow the state of the object to be saved for later instantiations, and load the object using the saved state. Typically, the persistence interfaces are implemented by an embedded or linked object, and are called by the container application or the default object handler

When to Implement

You must implement the single method of IPersist in implementing the other persistence interface, IPersistStorage. Typically, for example, you would implement IPersistStorage on an embedded object, although its uses are not limited to this object. You could implement IPersist in a situation where all that is required is to obtain the CLSID of a persistent object, as it is used in marshaling.

When to Use

The single method of IPersist is rarely called directly in application code. It is called by the default object handler to get the CLSID of an embedded object, or an object to be marshaled. A container application, for example, would probably not call the GetClassID method directly unless it provided object handlers for specific classes of objects.

Method
Description
IPersist::GetClassID Retrieves the class identifier (CLSID) of an object. The CLSID is a unique value that identifies the code that can manipulate the persistent data.


IPersist::GetClassID

This method retrieves the class identifier (CLSID) of an object. The CLSID is a unique value that identifies the code that can manipulate the persistent data.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetClassID( CLSID * pClassID );

Parameters

pClassID
[out] Pointer to the location of the CLSID on return. The CLSID is a globally unique identifier (GUID) that uniquely represents an object class that defines the code that can manipulate the object’s data.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The CLSID was successfully retrieved.
E_FAIL | The CLSID could not be retrieved.

Remarks

The GetClassID method retrieves the class identifier (CLSID) for an object, used in later operations to load object-specific code into the caller’s context.

Notes to Callers

A container application might call this method to retrieve the original CLSID of an object that it is treating as a different class. Such a call would be necessary if a user performed an editing operation that required the object to be saved. If the container were to save it using the treat-as CLSID, the original application would no longer be able to edit the object. Typically, in this case, the container calls the OleSave helper function, which performs all the necessary steps. For this reason, most container applications have no need to call this method directly.

The exception would be a container that provides an object handler for certain objects. In particular, a container application should not get an object’s CLSID and then use it to retrieve class specific information from the registry. Instead, the container should use IOleObject and IDataObject interfaces to retrieve such class-specific information directly from the object.

Notes to Implementers

Typically, implementations of this method simply supply a constant CLSID for an object. If, however, the object’s TreatAs registry key has been set by an application that supports emulation (and so is treating the object as one of a different class), a call to IPersist::GetClassID must supply the CLSID specified in the TreatAs key. For more information on emulation, refer to CoTreatAsClass.

When an object is in the running state, the default handler calls an implementation of IPersist::GetClassID that delegates the call to the implementation in the object. When the object is not running, the default handler instead calls the ReadClassStg function to read the CLSID that is saved in the object’s storage.


IPersistStorage : IUnknown

This interface defines methods that enable a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container’s storage.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

The IPersistStorage interface defines methods that enable a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container’s storage.

The IPersistStorage contract inherits its definition from IPersist, so all implementations must also include the GetClassID method of IPersist.

When to Implement

Any object that can be embedded in a container must implement the IPersistStorage interface. This interface is one of the primary interfaces for a compound document object. Embeddable objects must also implement the IOleObject and IDataObject interfaces.

The OLE default handler for embedded objects provides an implementation of the IPersistStorage interface that is used when the object is in the loaded state. Similarly, the OLE default link handler provides an IPersistStorage implementation that manages storage for a linked object. These default handlers both interact with the OLE default cache implementation, which has its own IPersistStorage implementation.

If you are providing a custom embedding or link handler for your objects, the handler must include an implementation of IPersistStorage. You can delegate calls to the default handler so you can take advantage of the default cache implementation.

When to Use

When an OLE container creates a new object, loads an existing object from storage, or inserts a new object in a clipboard or a drag-and-drop operation, the container uses the IPersistStorage interface to initialize the object and put it in the loaded or running state. When an object is loaded or running, an OLE container calls other IPersistStorage methods to instruct the object to perform various save operations or to release its storage.

Typically, applications use helper functions such as OleCreate, rather than calling the IPersistStorage::Load or IPersistStorage::InitNew methods directly. Similarly, applications typically call the OleSave helper function rather than calling IPersistStorage::Save directly.

Method
Description
IPersistStorage::HandsOffStorage | Instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOff mode, in which the object cannot do anything and only the close operation works.
IPersistStorage::InitNew | Initializes a new object, providing a pointer to the storage to be used for the object.
IPersistStorage::IsDirty | Indicates whether the object has changed since it was last saved to its current storage.
IPersistStorage::Load | Loads an object from its existing storage.
IPersistStorage::Save | Saves an object and any nested objects that it contains into the specified storage. The object is placed in NoScribble mode and must not write to the specified storage until it receives a call to its IPersistStorage::SaveCompleted method.
IPersistStorage::SaveCompleted | Notifies the object that it can revert from NoScribble or HandsOff mode, in which it must not write to its storage object, to Normal mode, in which it can.


IPersistStorage::HandsOffStorage

This method instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOff mode, in which the object cannot do anything and only the close operation works.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT HandsOfStorage(void);

Return Values

S_OK indicates that the object has successfully entered HandsOff mode.

Remarks

This method causes an object to release any storage objects that it is holding and to enter the HandsOff mode until a subsequent IPersistStorage::SaveCompleted call. In HandsOff mode, the object cannot do anything and the only operation that works is a close operation.

A container application typically calls this method during a full save or low-memory full save operation to force the object to release all pointers to its current storage. In these scenarios, the HandsOffStorage call comes after a call to either OleSave or IPersistStorage::Save, putting the object in HandsOffAfterSave mode. Calling this method is necessary so the container application can delete the current file as part of a full save, or so it can call the IRootStorage::SwitchToFile method as part of a low-memory save.

A container application also calls this method when an object is in Normal mode to put the object in HandsOffFromNormal mode.

While the component object is in either HandsOffAfterSave or HandsOffFromNormal mode, most operations on the object will fail. Thus, the container should restore the object to Normal mode as soon as possible. The container application does this by calling the IPersistStorage::SaveCompleted method, which passes a storage pointer back to the component object for the new storage object.

Notes to Implementers

This method must release all pointers to the current storage object, including pointers to any nested streams and storages. If the object contains nested objects, the container application must recursively call this method for any nested objects that are loaded or running.


IPersistStorage::InitNew

This method initializes a new object, providing a pointer to the storage to be used for the object.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT InitNew( IStorage *pStg );

Parameters

pStg
[in] IStorage pointer to the new storage object to be initialized. The container creates a nested storage object in its storage object (see IStorage::CreateStorage). Then, the container calls the WriteClassStg function to initialize the new storage object with the object class identifier (CLSID).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The new storage object was successfully initialized.
CO_E_ALREADYINITIALIZED | The object has already been initialized by a previous call to either the IPersistStorage::Load method or the IPersistStorage::InitNew method.
E_OUTOFMEMORY | The storage object was not initialized due to a lack of memory.
E_FAIL | The storage object was not initialized for some reason other than a lack of memory.

Remarks

A container application can call this method when it needs to initialize a new object, for example, with an InsertObject command.

An object that supports the IPersistStorage interface must have access to a valid storage object at all times while it is running. This includes the time just after the object has been created but before it has been made persistent. The object’s container must provide the object with a valid IStorage pointer to the storage during this time through the call to IPersistStorage::InitNew. Depending on the container’s state, a temporary file might have to be created for this purpose.

If the object wants to retain the IStorage instance, it must call IUnknown::AddRef to increment its reference count.

After the call to IPersistStorage::InitNew, the object is in either the loaded or running state. For example, if the object class has an in-process server, the object will be in the running state. However, if the object uses the default handler, the container’s call to InitNew only invokes the handler’s implementation which does not run the object. Later if the container runs the object, the handler calls the IPersistStorage::InitNew method for the object.

Notes to Callers

Rather than calling IPersistStorage::InitNew directly, you typically call the OleCreate helper function which does the following:

  1. Calls the CoCreateInstance function to create an instance of the object class
  2. Queries the new instance for the IPersistStorage interface
  3. Calls the IPersistStorage::InitNew method to initialize the object

The container application should cache the IPersistStorage pointer to the object for use in later operations on the object.

Notes to Implementers

An implementation of IPersistStorage::InitNew should initialize the object to its default state, taking the following steps:

  1. Pre-open and cache the pointers to any streams or storages that the object will need to save itself to this storage.
  2. Call IPersistStorage::AddRef and cache the storage pointer that is passed in.
  3. Call the WriteFmtUserTypeStg function to write the native clipboard format and user type string for the object to the storage object.
  4. Set the dirty flag for the object.

The first two steps are particularly important for ensuring that the object can save itself in low memory situations. Pre-opening and holding onto pointers to the stream and storage interfaces guarantee that a save operation to this storage will not fail due to insufficient memory.

Your implementation of this method should return the CO_E_ALREADYINITIALIZED error code if it receives a call to either the IPersistStorage::InitNew method or the IPersistStorage::Load method after it is already initialized.


IPersistStorage::IsDirty

This method indicates whether the object has changed since it was last saved to its current storage.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsDirty( void );

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The object has changed since it was last saved.
S_FALSE | The object has not changed since the last save.

Remarks

This method checks whether an object has changed since it was last saved so you can save it before closing it. The dirty flag for an object is conditionally cleared in the IPersistStorage::Save method.

For example, you could optimize a File:Save operation by calling the IPersistStorage::IsDirty method for each object and then calling the IPersistStorage::Save method only for those objects that are dirty.

Notes to Callers

You should treat any error return codes as an indication that the object has changed. In other words, unless this method explicitly returns S_FALSE, you must assume that the object needs to be saved.

Notes to Implementers

A container with one or more contained objects must maintain an internal dirty flag that is set whenever any of its contained objects are dirty.


IPersistStorage::Load

This method loads an object from its existing storage.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Load( IStorage *pStg );

Parameters

pStg
[in] IStorage pointer to the existing storage from which the object is to be loaded.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The object was successfully loaded.
CO_E_ALREADYINITIALIZED | The object has already been initialized by a previous call to the IPersistStorage::Load method or the IPersistStorage::InitNew method.
E_OUTOFMEMORY | The object was not loaded due to lack of memory.
E_FAIL | The object was not loaded due to some reason besides a lack of memory.

Remarks

This method initializes an object from an existing storage. The object is placed in the loaded state if this method is called by the container application. If called by the default handler, this method places the object in the running state.

Either the default handler or the object itself can hold onto the IStorage pointer while the object is loaded or running.

Notes to Callers

The container should cache the IPersistStorage pointer for use in later operations on the object.

Notes to Implementers

Your implementation should perform the following steps to load an object:

  1. Open the object’s streams in the storage object, and read the necessary data into the object’s internal data structures.
  2. Clear the object’s dirty flag.
  3. Call the IPersistStorage::AddRef method and cache the passed in storage pointer.
  4. Keep open and cache the pointers to any streams or storages that the object will need to save itself to this storage.
  5. Perform any other default initialization required for the object.

Steps 3 and 4 are particularly important for ensuring that the object can save itself in low memory situations. Holding onto pointers to the storage and stream interfaces guarantees that a save operation to this storage will not fail due to insufficient memory.

Your implementation of this method should return the CO_E_ALREADYINITIALIZED error code if it receives a call to either the IPersistStorage::InitNew method or the IPersistStorage::Load method after it is already initialized.


IPersistStorage::Save

This method saves an object and any nested objects that it contains into the specified storage. The object is placed in NoScribble mode and must not write to the specified storage until it receives a call to its IPersistStorage::SaveCompleted method.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Save( IStorage * pStgSave, BOOL fSameAsLoad );

Parameters

pStgSave
[in] IStorage pointer to the storage into which the object is to be saved.
fSameAsLoad
[in] Boolean value that indicates whether the specified storage is the current one, which was passed to the object by one of the following calls:
  • IPersistStorage::InitNew when it was created.
  • IPersistStorage::Load when it was loaded.
  • IPersistStorage::SaveCompleted when it was saved to a storage different from its current storage.

This parameter is set to FALSE when performing a Save As or Save A Copy To operation or when performing a full save. In the latter case, this method saves to a temporary file, deletes the original file, and renames the temporary file.

This parameter is set to TRUE to perform a full save in a low-memory situation or to perform a fast incremental save in which only the dirty components are saved.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The object was successfully saved.
STG_E_MEDIUMFULL | The object was not saved because of a lack of space on the disk.
E_FAIL | The object could not be saved due to errors other than a lack of disk space.

Remarks

This method saves an object, and any nested objects it contains, into the specified storage. It also places the object into NoScribble mode. Thus, the object cannot write to its storage until a subsequent call to the IPersistStorage::SaveCompleted method returns the object to Normal mode.

If the storage object is the same as the one it was loaded or created from, the save operation may be able to write incremental changes to the storage object. Otherwise, a full save must be done.

This method recursively calls the IPersistStorage::Save method, the OleSave function, or the IStorage::CopyTo method to save its nested objects.

This method does not call the IStorage::Commit method. Nor does it write the CLSID to the storage object. Both of these tasks are the responsibilities of the caller.

Notes to Callers

Rather than calling IPersistStorage::Save directly, you typically call the OleSave helper function which performs the following steps:

  1. Call the WriteClassStg function to write the class identifier for the object to the storage.
  2. Call the IPersistStorage::Save method.
  3. If needed, call the IStorage::Commit method on the storage object.

Then, a container application performs any other operations necessary to complete the save and calls the SaveCompleted method for each object.

If an embedded object passes the IPersistStorage::Save method to its nested objects, it must receive a call to its IPersistStorage::SaveCompleted method before calling this method for its nested objects.


IPersistStorage::SaveCompleted

This method notifies the object that it can revert from NoScribble or HandsOff mode, in which it must not write to its storage object, to Normal mode, in which it can.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SaveCompleted( IStorage * pStgNew );

Parameters

pStgNew
[in] IStorage pointer to the new storage object, if different from the storage object prior to saving. This pointer can be NULL if the current storage object does not change during the save operation. If the object is in HandsOff mode, this parameter must be non-NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The object was successfully returned to Normal mode.
E_OUTOFMEMORY | The object remained in HandsOff mode or NoScribble mode due to a lack of memory. Typically, this error occurs when the object is not able to open the necessary streams and storage objects in pStgNew.
E_INVALIDARG | The pStgNew parameter is not valid. Typically, this error occurs if pStgNew is NULL when the object is in HandsOff mode.
E_UNEXPECTED | The object is in Normal mode, and there was no previous call to IPersistStorage::Save or IPersistStorage::HandsOffStorage.

Remarks

This method notifies an object that it can revert to Normal mode and can once again write to its storage object. The object exits NoScribble mode or HandsOff mode.

If the object is reverting from HandsOff mode, the pStgNew parameter must be non-NULL. In HandsOffFromNormal mode, this parameter is the new storage object that replaces the one that was revoked by the IPersistStorage::HandsOffStorage method. The data in the storage object is a copy of the data from the revoked storage object. In HandsOffAfterSave mode, the data is the same as the data that was most recently saved. It is not the same as the data in the revoked storage object.

If the object is reverting from NoScribble mode, the pStgNew parameter can be NULL or non-NULL. If NULL, the object once again has access to its storage object. If it is not NULL, the component object should simulate receiving a call to its IPersistStorage::HandsOffStorage method. If the component object cannot simulate this call, its container must be prepared to actually call the IPersistStorage::HandsOffStorage method.

The IPersistStorage::SaveCompleted method must recursively call any nested objects that are loaded or running.

If this method returns an error code, the object is not returned to Normal mode. Thus, the container object can attempt different save strategies.


IRAPIStream

This interface extends the IStream interface with two methods that allow the setting of timeouts.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Method
Description
IRAPIStream::SetRapiStat | Sets the value of the timeout value for the IStream::Read method.
IRAPIStream::GetRapiStat | Gets the current value of the timeout timeout for the IStream::Read method.

Remarks

The SetRapiStat and GetRapiStat methods are modeled after the IStream::Stat method.


IRAPIStream::GetRapiStat

This method gets the current value of the timeout for the IStream::Read method.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

GetRapiStat( RAPISTREAMFLAG Flag, DWORD *pdwValue );

Parameters

Flag
Used to set properties for the timeout. Currently, the only supported value is STREAM_TIMEOUT_READ.
pdwValue
Pointer to the value of the timeout.

Return Value

Returns S_OK if timeout value is retrieved successfully, or returns Error_Invalid_Parameter otherwise.


IRAPIStream::SetRapiStat

This method sets the timeout value for the IStream::Read method.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

SetRapiStat( RAPISTREAMFLAG Flag, DWORD dwValue);

Parameters

Flag
Used to set properties for the timeout. Currently, the only supported value is STREAM_TIMEOUT_READ.
dwvalue
Specifies the value of the timeout.

Return Value

Returns S_OK if timeout value is set successfully, or returns Error_Invalid_Parameter otherwise.

Remarks

STREAM_TIMEOUT_READ allows setting timeouts on the IStream::Read method.


IReplNotify : IUnknown

An ActiveSync service manager implements this interface, which can be used by an ActiveSync service provider to notify the ActiveSync service manager of certain events taking place in the ActiveSync service provider’s store.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Methods
Description
IReplNotify::GetWindow | Obtains a handle to the window that must be used as a parent for any modal dialog or message box that an ActiveSync service provider wants to display.
IReplNotify::OnItemCompleted | Used internally by the ActiveSync service manager. An ActiveSync service provider should not call this explicitly.
IReplNotify::OnItemNotify | Notifies the ActiveSync service manager that an item has been created, deleted, or modified.
IReplNotify::QueryDevice | Used to ask for information about a device.
IReplNotify::SetStatusText | Sets the text to be displayed on the Explorer Window status control.
IUnknown::AddRef | Increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a specified object.
IUnknown::QueryInterface | Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.
IUnknown::Release | Decrements the reference count for the calling interface on a object. If the reference count on the object falls to 0, the object is freed from memory.

Remarks

The IReplNotify : IUnknown interface is implemented and exposed by the ActiveSync service manager. If the store is capable of detecting changes and deletions to the objects as they occur, an ActiveSync service provider should use the interface to notify the ActiveSync service manager of these changes and deletions. This is more efficient than enumerating the changes and comparing time stamps.


IReplNotify::GetWindow

This method obtains a handle to the window that must be used as a parent for any modal dialog or message box that an ActiveSync service provider wants to display.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetWindow( UINT uFlags );

Parameters

uFlags
Reserved; set to zero.

Return Values

An appropriate HRESULT value is returned.

See Also

IReplNotify


IReplNotify::OnItemCompleted

This method is used internally by the ActiveSync service manager. An ActiveSync service provider should never call this method explicitly.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT OnObjectCompleted( PREPLSETUP pSetup );

Parameters

pSetup
Pointer to a REPLSETUP structure.

Return Values

An appropriate HRESULT value is returned.

See Also

IReplNotify


IReplNotify::OnItemNotify

This method notifies the ActiveSync service manager that an object has been created, deleted, or modified.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT OnItemNotify( UINT uCode, LPSTR lpszProgId,
LPSTR lpszObjType, HREPLITEM hItem, ULONG ulFlags );

Parameters

uCode
Code that describes what happened. It is one of the following values:
Value
Description
RNC_CREATED | Object was created.
RNC_MODIFIED | Object was modified.
RNC_DELETED | Object was deleted.
RNC_SHUTDOWN | The store has been shut down. Windows CE Services should unload the module immediately.

lpszProgId
Long pointer to the null-terminated string that contains the programmatic identifier of the store.
lpszObjType
Long pointer to the null-terminated string that contains the name of the object type.
hItem
Handle to the concerned item.
ulFlags
Reserved.

Return Values

An appropriate HRESULT value is returned.

Remarks

If the store is capable of detecting changes and deletions as they occur, an ActiveSync service provider should call the IReplNotify::OnItemNotify method immediately after any changes or deletions are detected.

See Also

IReplNotify


IReplNotify::QueryDevice

This method is used to ask for information about a device.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

void QueryDevice( UINT uCode, LPVOID *ppvData );

Parameters

uCode
[in] It is one of the following values:
Value
Description
QDC_SEL_DEVICE | Requests information for the selected device. In this case, *ppvData points to the DEVINFO structure containing the information for the device.
QDC_CON_DEVICE | Requests information for the connected device. In this case, *ppvData points to the DEVINFO structure containing the information for the device.
QDC_SEL_DEVICE_KEY | Gets a registry key that can be used to store selected device-specific settings. In this case, *ppvData points to HKEY. The caller must close the registry key when its usage is over.
QDC_CON_DEVICE_KEY | Gets a registry key that can be used to store connected device-specific settings. In this case, *ppvData points to HKEY. The caller must close the registry key when its usage is over.

ppvData
[out] Depending on uCode, this parameter is a pointer to a void pointer to either a DEVINFO structure or HKEY.

Return Values

An appropriate HRESULT value is returned.


IReplNotify::SetStatusText

This method sets the text to be displayed on the Explorer Window status control.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetStatusText ( LPSTR lpszText );

Parameters

lpszText
Long pointer to a null-terminated status text string.

Return Values

An appropriate HRESULT value is returned.

Remarks

Status messages should be advisory only. Use modal dialog boxes or message boxes for information that requires user intervention.

See Also

IReplNotify


IReplObjHandler : IUnknown

This interface implements all required methods related to the serialization and deserialization of an object.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Methods
Description
IReplObjHandler::DeleteObj | Informs the ActiveSync service provider that an object should be deleted.
IReplObjHandler::GetPacket | ActiveSync service provider implements this method to deserialize an object into one or more packets. These packets are sent between the Windows CE–based device and the desktop computer by the ActiveSync service provider.
IReplObjHandler::Reset | Resets the ActiveSync service provider so all the resources that the ActiveSync service provider used during the serialization or deserialization are freed.
IReplObjHandler::SetPacket | ActiveSync service provider implements this method to serialize one or more packets into an object. These packets are guaranteed to be in the same order as when they are sent.
IReplObjHandler::Setup | Sets up the ActiveSync service provider so it is ready to serialize or deserialize an object.
IUnknown::AddRef | Increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a specified object.
IUnknown::QueryInterface | Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.
IUnknown::Release | Decrements the reference count for the calling interface on a object. If the reference count on the object falls to 0, the object is freed from memory.

Remarks

The IReplObjHandler : IUnknown interface encapsulates all functions needed to serialize or deserialize the objects. Any object can be deserialized into one or more data packets of any size. An ActiveSync service provider determines the number of packets and their sizes. These packets are exchanged between the Windows CE–based device and the desktop computer. The receiver of these packets is guaranteed to receive them in the exact same order as they are sent and the receiver can then serialize these packets back into an object.


IReplObjHandler::DeleteObj

This method informs the ActiveSync service provider that an object should be deleted.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DeleteObj( PREPLSETUP pSetup );

Parameters

pSetup
Pointer to a REPLSETUP structure.

Return Values

NOERROR indicates success.

Remarks

The IReplObjHandler::DeleteObj method is called whenever the ActiveSync service manager determines that an object needs to be deleted. Note that Setup and Reset are not called before and after this method. The ActiveSync service provider should delete the object specified in the specified REPLSETUP structure.

See Also

IReplObjHandler


IReplObjHandler::GetPacket

This method is implemented by the ActiveSync service provider implements to deserialize an object into one or more packets. These packets are sent between the Windows CE–based device and the desktop computer by the ActiveSync service provider.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetPacket( LPBYTE *lppbData, DWORD *pcbData,
DWORD cbRecommend );

Parameters

lppbData
Long pointer to a pointer of the outgoing packet.
pcbData
Pointer to a DWORD for the packet size.
cbRecommend
Recommended maximum size of the packet.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The operation successfully created one packet.
RERR_BAD_OBJECT | The operation failed to create one object. If the receiver does receive some of the earlier packets, they should be discarded.
RWRN_LAST_PACKET | A packet was successfully created, and it is the last one for the object.

Remarks

During a deserialization of an object, the ActiveSync service manager calls the IReplObjHandler::GetPacket method continuously until RWRN_LAST_OBJECT or an error value is returned. The ActiveSync service provider determines how many packets are to be sent and the sizes of each packet. For efficiency, a packet size is recommended to be less than 8,000 bytes in size.

Allocation and deallocation of memory for the packet is the responsibility of the ActiveSync service provider. An ActiveSync service provider sets lppbData to that pointer and sets pcbData with the packet size. Typically, an ActiveSync service provider allocates a piece of memory of a known size in IReplObjHandler::Setup and frees it in IReplObjHandler::Reset.

See Also

IReplObjHandler::SetPacket


IReplObjHandler::Reset

This method prompts the ActiveSync service provider to reset or free any resources used during the serialization or deserialization of an object.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Reset( PREPLSETUP pSetup );

Parameters

pSetup
Pointer to a REPLSETUP structure.

Return Values

NOERROR indicates success.

Remarks

The IReplObjHandler::Reset method is called once per object.

See Also

IReplObjHandler::Setup


IReplObjHandler::SetPacket

This method is implemented by the ActiveSync service provider to serialize one or more packets into an object. These packets are guaranteed to be in the same order as when they are sent.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetPacket( LPBYTE lpbData, DWORD cbData );

Parameters

lpbData
Long pointer to the incoming packet.
cbData
Stores the packet size.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The packet was successfully used to deserialize the object.
RERR_SKIP_ALL | Failed to apply the packet toward the object; skip all remaining packets for the object.

Remarks

The IReplObjHandler::SetPacket method is called continuously until the last packet is received. These packets are guaranteed to be received in the same number and order as they are created by IReplObjHandler::GetPacket.

See Also

IReplObjHandler::GetPacket


IReplObjHandler::Setup

This method sets up the ActiveSync service provider so it is ready to serialize or deserialize an object.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Setup( PREPLSETUP pSetup );

Parameters

pSetup
Pointer to a REPLSETUP structure, which contains information about the object to be serialized or deserialized.

Return Values

An appropriate HRESULT value is returned.

Remarks

The IReplObjHandler::Setup method is called once per object. Necessary data is stored in the passed REPLSETUP structure.

See Also

REPLSETUP


IReplStore : IUnknown

This interface implements all required functions related to the store.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

IReplStore Methods
Description
IReplStore::ActivateDialog | Activates an ActiveSync service provider-specific dialog box.
IReplStore::BytesToObject | Converts an array of bytes to a HREPLOBJ, which can be either a HREPLITEM or HREPLFLD, when loading.
IReplStore::CompareItem | Compares the specified handles using entry identifiers, such as file names or record numbers.
IReplStore::CompareStoreIDs | Compares two store identifiers to determine if they are equal.
IReplStore::CopyObject | Copies one HREPLOBJ, which can be either a HREPLITEM or HREPLFLD, over to another.
IReplStore::FindFirstItem | Returns a new HREPLITEM of the first object in the specified folder, if there’s any.
IReplStore::FindItemClose | Completes the Find operation in the specified folder.
IReplStore::FindNextItem | Returns a new HREPLITEM of the next object in the specified folder, if there’s any.
IReplStore::FreeObject | Frees the specified HREPLOBJ handle.
IReplStore::GetConflictInfo | Gets information about two conflicting objects.
IReplStore::GetFolderInfo | Returns a HREPLFLD for folder, specified the object type name. Also returns a pointer to the IReplObjHandler of the specified object type.
IReplStore::GetObjTypeUIData | Sends user interface (UI)-related data about an object type to the ActiveSync service manager.
IReplStore::GetStoreInfo | Gets information about the current store instance.
IReplStore::Initialize | Initializes the ActiveSync service provider.
IReplStore::IsFolderChanged | Determines if any object in a specified folder has been changed since the method was last called.
IReplStore::IsItemChanged | Determines if the item has changed.
IReplStore::IsItemReplicated | Determines if the item should be replicated using ActiveSync service provider-defined rules.
IReplStore::IsValidObject | Determines if the specified handles are valid.
IReplStore::ObjectToBytes | Converts the HREPLOBJ, which can be either a HREPLITEM or HREPLFLD, to an array of bytes when saving.
IReplStore::RemoveDuplicates | Finds and removes duplicated objects from the store.
IReplStore::ReportStatus | ActiveSync service manager is reporting to the store about the status of the synchronization.
IReplStore::UpdateItem | Updates the object’s time stamp, change number, and other information that is stored in the specified handle.

Remarks

The IReplStore : IUnknown interface encapsulates all functions needed to access the objects in the store. A handle of type HREPLITEM identifies each object in the store.


IReplStore::ActivateDialog

This method activates an ActiveSync service provider-specific dialog box.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ActivateDialog( UINT uDlg, HWND hwndParent,
HREPLFLD hFolder, IEnumReplItem * penum );

Parameters

uDlg
Identifies the dialog box to be activated.
hwndParent
Handle to the window that should be used as parent for the dialog box.
hFolder
Handle to a folder.
penum
Pointer to a enumerator of HREPLITEM for objects stored in the folder.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | User selected OK to save the changes made.
RERR_CANCEL | User selected CANCEL to ignore the changes made.
RERR_SHUT_DOWN | User selected OK to save the changes made. The ActiveSync service manager must be closed now because of these changes.
RERR_UNLOAD | User selected OK to save the changes made. Replication modules must be unloaded so the change can take effect.
E_NOTIMPL | The requested dialog box is not implemented.

Remarks

The IReplStore::ActivateDialog method is used to activate dialog boxes options for each object type. ReplDialogs contains the list of dialog boxes that can be activated. An ActiveSync service provider can return E_NOTIMPL if it does not implement a particular dialog box. An enumerator of the HREPLITEM contained in the specified folder is passed in. The ActiveSync service provider should use this enumerator to enumerate all items in the folder.

See Also

IReplStore


IReplStore::BytesToObject

This method converts an array of bytes to an HREPLOBJ, which can be HREPLITEM or HREPLFLD, when loading.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HREPLOBJ BytesToObject( LPBYTE lpb, UINT cb );

Parameters

lpb
Long pointer to a buffer where the array of bytes should be stored. This parameter can be NULL.
cb
Size of the buffer.

Remarks

The IReplStore::BytesToObject method is used to convert a series of bytes into an item or folder handle. BytesToObject returns the new handle.

See Also

IReplStore::ObjectToBytes


IReplStore::CompareItem

This method compares the specified handles using entry identifiers, such as file names or record numbers.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

int CompareItem( HREPLITEM hItem1, HREPLITEM hItem2 );

Parameters

hItem1
Handle to the first object. The ActiveSync service manager guarantees this handle is one of those returned by FindFirstItem or FindNextItem.
hItem2
Handle to the second object. The ActiveSync service manager guarantees this handle is one of those returned by FindFirstItem or FindNextItem.

Return Values

One of the values described in the following table is returned.

Value
Description
0 | These two handles represent the same object.
1 | The first object is bigger than the second object.
–1 | The first object is smaller than the second object.

See Also

HREPLITEM, IReplStore::IsItemChanged


IReplStore::CompareStoreIDs

This method compares two store identifiers to determine if they are equal.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CompareStoreIDs( LPBYTE lpbID1, UINT cbID1,
LPBYTE lpbID2, UINT cbID2 );

Parameters

lpbID1
Long pointer to the first store identifier.
cbID1
Size of the first store identifier.
lpbID2
Long pointer to the second store identifier.
cbID2
Size of the second store identifier.

Return Values

One of the values described in the following table is returned.

Value
Description
0 | These store identifiers represent the same store.
1 | The first store is bigger than the second store.
-1 | The first store is smaller than the second store.

Remarks

Replication calls the IReplStore::CompareStoreIDs method whenever it needs to know if the current store is different from the one it last replicated with. The store identifiers passed are always obtained from the STOREINFO structure set by the IReplStore::GetStoreInfo method.

See Also

IReplStore::GetStoreInfo, STOREINFO


IReplStore::CopyObject

This method copies one HREPLOBJ, which can be either a HREPLITEM or HREPLFLD, over to another.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CopyObject( HREPLOBJ hObjSrc, HREPLOBJ hObjDst );

Parameters

hObjSrc
Handle to the source.
hObjDst
Handle to the destination.

Return Values

One of the values described in the following table is returned.

Value
Description
TRUE | The operation was successful.
FALSE | The operation failed. A possible reason is that the two handles are of different types or of different sizes.

Remarks

The IReplStore::CopyObject method is used to copy the contents of a specified handle to another. Any resource allocated in the source must be freed before they are overwritten, and any resource in the destination should be reset so it is not freed after the assignment to the source. CopyObject is always called when the ActiveSync service manager detects that an object has been modified since the last replication and its contents must therefore be updated from the modified handle returned by the ActiveSync service provider from FindNextItem or FindNextItem.

See Also

IReplStore


IReplStore::FindFirstItem

This method returns a new handle to the first object in a specified folder, if there is any.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT FindFirstItem( HREPLFLD hFolder, HREPLITEM *phItem,
BOOL * pfExist );

Parameters

hFolder
Handler to a folder.
phItem
[out] Pointer to a handle to the first object in the folder.
pfExist
[out] Pointer to a Boolean value that is set to TRUE if there is an object in the folder.

Return Values

One of the values described in the following table is returned.

Value
Description
E_FAIL | There are problems with the enumeration. Replication should ignore the folder.
NOERROR | A new HREPLITEM was created for the first object in the folder and its pointer has been returned.

Remarks

The IReplStore::FindFirstItem method works together with FindNextItem and FindItemClose to enumerate all items in a specified folder. FindFirstItem and FindNextItem are the only methods in IReplStore that can create HREPLITEM for the items. All HREPLITEM structures passed by the ActiveSync service manager are guaranteed to be originally created from these two methods. It is possible that, before FindItemClose is called, a different thread calls methods like DeleteObject that write to the store. Therefore, it is important for the ActiveSync service provider to have some sort of thread synchronization between this method and the methods that write to the store. A typical ActiveSync service provider would use critical section to make sure that, during the time between calls to FindFirstItem and FindItemClose, no write to the store is permitted.

See Also

HREPLITEM, IReplStore::FindItemClose , IReplStore::FindNextItem


IReplStore::FindItemClose

This method completes the folder enumeration.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT FindItemClose( HREPLFLD hFolder );

Parameters

hFolder
Handle for the folder being enumerated.

Return Values

NOERROR indicates success.

Remarks

The IReplStore::FindItemClose method works with FindFirstItem and FindNextItem to enumerate all items in a specified folder. An ActiveSync service provider can do whatever it needs to complete the enumeration, for example, free memory and delete temporary objects.

See Also

HREPLITEM, IReplStore::FindFirstItem, IReplStore::FindNextItem


IReplStore::FindNextItem

This method returns a new item handle to the next object in a specified folder, if there is any.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT FindNextItem( HREPLFLD hFolder, HREPLITEM *phItem,
BOOL * pfExist );

Parameters

hFolder
Handle to a folder.
phItem
[out] Pointer to a handle to the next object in the folder.
pfExist
[out] Pointer to a Boolean value that is set to TRUE if there is an object in the folder.

Return Values

One of the values described in the following table is returned.

Value
Description
E_FAIL | There are problems with the enumeration. Replication should ignore the folder.
NOERROR | A new HREPLITEM was created for the next object in the folder and its pointer has been returned.

Remarks

The IReplStore::FindNextItem method works with FindFirstItem and FindItemClose to enumerate all items in a specified folder. FindNextItem and FindFirstItem are the only methods in IReplStore that can create HREPLITEM structures for the objects. All HREPLITEM structures passed by the ActiveSync service manager are guaranteed to be originally created from these two methods.

See Also

HREPLITEM, IReplStore::FindFirstItem, IReplStore::FindItemClose


IReplStore::FreeObject

This method frees the specified HREPLOBJ handle.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

void FreeObject( HREPLOBJ hObject );

Parameters

hObject
Handle to an object whose contents need to be freed.

Return Values

None.

Remarks

The IReplStore::FreeObject method is used to free any memory pointers or delete any temporary objects that might have been created during the life of the handle and must be freed when the handle dies. This handle could either be an HREPLITEM or HREPLFLD structure.

See Also

IReplStore


IReplStore::GetConflictInfo

This method gets information about two conflicting objects.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetConflictInfo( PCONFINFO pConfInfo );

Parameters

pConfInfo
Pointer to the CONFINFO structure.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | Information was retrieved successfully.
RERR_IGNORE | This conflict should be ignored. The objects are identical.

See Also

IReplStore


IReplStore::GetFolderInfo

This method creates a new HREPLFLD of a folder for the specified object type name and returns a pointer to the IReplObjHandler interface that is used to serialize and deserialize all items in this folder.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetFolderInfo( LPSTR lpszName, HREPLFLD * phFolder,
IUnknown **ppObjHandler );

Parameters

lpszName
Long pointer to the null-terminated string that contains the name of the object type as taken from the registry.
phFolder
[out] Pointer to the handle to the folder.
ppObjHandler
[out] Pointer to a pointer to the IReplObjHandler interface.

Return Values

NOERROR indicates success.

Remarks

The IReplStore::GetFolderInfo method is the only method in IReplStore that creates or modifies a HREPLFLD structure for the folder. The ActiveSync service manager calls this method to get a folder handle for the specified object type. Object types are configured into the registry, where object type name and other relevant information about an object type are stored. Note that the handle pointed to by phFolder may or may not be NULL when called. If phFolder points to a handle that has a NULL value, the ActiveSync service provider should create a new handle for the specified folder. If phFolder points to a pointer that has a value, the ActiveSync service provider should modify the data indicated by this handle.

See Also

IReplStore


IReplStore::GetObjTypeUIData

This method sends user interface (UI)-related data about an object type to the ActiveSync service manager.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetObjTypeUIData( HREPLFLD hFolder, POBJUIDATA pData );

Parameters

hFolder
[in] Handle to a folder that contains the items.
pData
[out] Pointer to an OBJUIDATA structure.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | User selected OK to save the changes made.
E_OUTOFMEMORY | The operation was unable to load required UI resources.

See Also

IReplStore


IReplStore::GetStoreInfo

This method gets information about the current store instance.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetStoreInfo( PSTOREINFO pInfo );

Parameters

pInfo
Pointer to the STOREINFO structure.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The STOREINFO structure was successfully returned.
E_INVALIDARG | The value of cbStruct is not expected.
E_POINTER | The store is not initialized or there is a problem getting the required store identifier or lpbStored is NULL.
E_OUTOFMEMORY | The value of cbMaxStoreId is too small. The size of the identifier is set in cbStoreId upon return.

Remarks

The ActiveSync service manager calls the IReplStore::GetStoreInfo method with lpbStoreId set to NULL for the first time. The ActiveSync service provider should then set cbStoreId to the size of the store identifier. Replication then calls GetStoreInfo again with an allocated buffer and the size stored in cbMaxStoreId.

See Also

STOREINFO


IReplStore::Initialize

This method initializes the IReplStore ActiveSync service provider.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Initialize( IReplNotify * pReplNotify UINT uFlags );

Parameters

pReplStatus
Pointer to the IReplNotify interface. Set this parameter to 0.
uFlags
Flags passed to the store by the ActiveSync service manager. It is one of the following values:
Value
Description
ISF_SELECTED_DEVICE | Set if the store is initialized for the selected device; otherwise, it is initialized for the connected device.
ISF_REMOTE_CONNECTED | Set if the store is initialized during the remote connection; all user interface (UI) should be suppressed.

Return Values

NOERROR indicates success.

See Also

IReplStore


IReplStore::IsFolderChanged

This method determines if any object in a specified folder has been changed since the method was last called.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsFolderChanged( HREPLFLD hFolder, BOOL * pfChanged );

Parameters

hFolder
Handle to a folder.
pfChanged
Pointer to a Boolean value that is set to TRUE if folder is changed.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The operation completed successfully. The pfChanged parameter is set to TRUE if the folder is changed, or FALSE otherwise.
RERR_SHUT_DOWN | There was a serious error, and the ActiveSync service provider should shut down immediately.
RERR_UNLOAD | There was a less serious error, and replication modules must be unloaded
RERR_STORE_REPLACED | The complete store was replaced.

Remarks

If the ActiveSync service provider wants real-time synchronization to be simulated; see GetStoreInfo. The ActiveSync service manager calls the IReplStore::IsFolderChanged method once the timer is up to see if it needs to scan the store further to pick up any changes. This is used to reduce the number of scans replication has to make to the store. An ActiveSync service provider should return TRUE if it does not need to implement this method.

See Also

IReplStore::GetStoreInfo, STOREINFO


IReplStore::IsItemChanged

This method determines if the object has changed.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

BOOL IsItemChanged( HREPLFLD hFolder, HREPLITEM hItem,
HREPLITEM hItemComp );

Parameters

hFolder
Handle to the folder or container that stores the object.
hItem
Handle to the object.
hItemComp
Handle to the object used for comparison.

Return Values

One of the values described in the following table is returned.

Value
Description
FALSE | The object has not been changed.
TRUE | The object has changed.

Remarks

If hItemComp is not NULL, the ActiveSync service provider should check the data (time stamp, change number) in hItem with hItemComp. If hItemComp is NULL, the ActiveSync service provider should get the data by opening the object and comparing it with the data in hItem.

See Also

HREPLITEM, IReplStore::CompareItem


IReplStore::IsItemReplicated

This method determines if an item should be replicated using ActiveSync service provider-defined rules.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

BOOL IsItemReplicated( HREPLIFLD hFolder, HREPLITEM hItem );

Parameters

hFolder
Handle to the folder or container that stores the object.
hItem
Handle to the object. This parameter can be NULL, in which case, IsItemReplicated should determine if the specified folder should be replicated.

Return Values

One of the values described in the following table is returned.

Value
Description
FALSE | The object should not be replicated.
TRUE | The object should be replicated.

Remarks

If the ActiveSync service provider requires that some objects on the desktop computer should not be replicated, it can use the IReplStore::IsItemReplicated method to tell the ActiveSync service manager to ignore these objects. The ActiveSync service provider can design its own rules and store it using the handle to the folder. If all objects should be replicated, the ActiveSync service provider can return TRUE in all calls.

See Also

IReplStore


IReplStore::ObjectToBytes

This method converts the HREPLOBJ, which can be either a HREPLITEM or HREPLFLD, to an array of bytes when saving.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

UINT ObjectToBytes( HREPLOBJ hObject, LPBYTE lpb );

Parameters

hObject
Handle to an object.
lpb
Long pointer to a buffer where the array of bytes should be stored. This parameter can be NULL.

Return Values

Number of bytes in the array.

Remarks

The IReplStore::ObjectToBytes method is used to save the data represented by a handle to a disk. The ActiveSync service manager calls ObjectToBytes first with lpb set to NULL. The ActiveSync service provider should then return the size required, followed by the ActiveSync service manager calling ObjectToBytes with a lpb parameter pointing to a buffer large enough for the array.

See Also

IReplStore::BytesToObject


IReplStore::IsValidObject

This method determines if the specified handles are valid.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsValidObject( HREPLFLD hFolder, HREPLITEM hItem,
UINT uFlags );

Parameters

hFolder
Handle to a folder. This parameter can be NULL.
hItem
Handle to an item. This parameter can be NULL.
uFlags
Reserved; set to zero.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The specified handles are all valid.
RERR_CORRUPT | The data in the specified handle is corrupted.
RERR_OBJECT_DELETED | The object identified by the handle is no longer in the store.

Remarks

The IReplStore::IsValidObject method is used to determine if the specified handles are valid. The ActiveSync service provider should check both hFolder and hItem to determine if either of them is not NULL.

See Also

IReplStore


IReplStore::RemoveDuplicates

This method finds and removes duplicated objects from the store.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT RemoveDuplicates( LPSTR lpszObjType, UINT uFlags );

Parameters

lpszObjType
Long pointer to the null-terminated string that contains the name of the object type for which this operation is intended. This parameter is NULL if all object types should be checked.
uFlags
Reserved; set to zero.

Return Values

Value
Description
NOERROR | The operation completed successfully and there is no need to restart replication to pick up the deletions.
RERR_RESTART | The operation completed successfully and replication should be restarted to pick up the deletions.
E_NOTIMPL | The ActiveSync service provider does not support this operation.

Remarks

Occasionally, the ActiveSync service manager might need to prompt an ActiveSync service provider to scan all objects in the store to check for duplicates and give the user a chance to remove them. The ActiveSync service provider should return E_NOTIMPL if it chooses not to implement this functionality. Otherwise, the ActiveSync service provider should perform the check and remove and return NOERROR or RERR_RESTART if successful. In this case, replication does not call the IReplStore::RemoveDuplicates method again until necessary. It should return all other error values if, for some reason, operation cannot be performed at that time. In this case, replication calls RemoveDuplicates again at the end of the next synchronization.

See Also

IReplStore


IReplStore::ReportStatus

This method is called by the ActiveSync service manager to get information on the synchronization status.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ReportStatus( HREPLFLD hFolder, HREPLITEM hItem,
UINT uStatus, UINT uParam );

Parameters

hFolder
Handle to the folder this status applies to. This parameter is NULL if status applies to all folders.
hItem
Handle to the object this status applies to. This parameter is NULL if status applies to all objects.
uStatus
Status code. It is one of the following values:
Value
Description
RSC_BEGIN_SYNC | Synchronization is about to start; uReserved is a combination of the following bit flags:
Flag
Description
BSF_AUTO_SYNC | Synchronization is started as a result of changes while “autosync on change” is turned on.
BSF_REMOTE_SYNC | Consistent with RSC_REMOTE_SYNC, set if synchronization is done remotely.
RSC_END_SYNC | Synchronization has ended.
RSC_BEGIN_CHECK | The ActiveSync service manager is about to call FindFirstItem and FindNextItem.
RSC_END_CHECK | The ActiveSync service manager has completed all enumeration calls and FindItemClose has been called.
RSC_DATE_CHANGED | The user has changed the system date. This code is called on every existing object in the store to give the ActiveSync service provider a chance to reset the date-dependent synchronization options. For example, if an ActiveSync service provider wants to synchronize files that are modified in the last two weeks, it can respond to this code to reset the enable bit for each item. When IsItemReplicated is called later, it re-evaluates the items based on the new date.
RSC_RELEASE | The ActiveSync service manager is about to release the IReplStore object. This is called before the final IReplStore::Release call.
RSC_REMOTE_SYNC | If uParam is TRUE, the ActiveSync service manager is about to start remote synchronization. The ActiveSync service provider should not show any UI that requires user interaction from now on until this status code is used again with uParam equal to FALSE.
RSC_INTERRUPT | ActiveSync service manager is about to interrupt the current operation.
The following values of uParam are defined only for RSC_INTERRUPT:
Value | Description
PSA_RESET_INTERRUPT | This flag is set if the interrupt state is being cleared; that is, normal operation is resuming.
PSA_SYS_SHUTDOWN | User has shut down the Windows operating system.
RSC_BEGIN_SYNC_OBJ | Synchronization is about to start on an object type. uReserved is a combination of bit flags; see RSC_BEGIN_SYNC.
RSC_END_SYNC_OBJ | Synchronization is about to end on an object type.
RSC_OBJ_TYPE_ENABLED | Synchronization of the specified object is enabled; hFolder is a pointer to a string (object type name).
RSC_OBJ_TYPE_DISABLED | Synchronization of the specified object is disabled; hFolder is a pointer to a string (object type name).
RSC_BEGIN_BATCH_WRITE | A series of SetPackets is called on a number of objects. This is the time for ActiveSync service provider to start a transaction.
RSC_END_BATCH_WRITE | RSC_BEGIN_BATCH_WRITE has ended. This is the time for the ActiveSync service provider to commit the transaction.
RSC_CONNECTION_CHG | The connection status has changed. uParam is TRUE if a connection has been established; otherwise, it is FALSE.
RSC_WRITE_OBJ_FAILED | There was a failure while writing to an object on the device. uParam is the HRESULT code.
RSC_DELETE_OBJ_FAILED | There was a failture while deleting an object on the device. uParam is the HRESULT code.

uParam
Additional information about the status, based on uStatus code.

Return Values

One of the values in the following table is returned.

Value
Description
NOERROR | The process indicated by uStatus is successful.
E_FAIL | The process indicated by uStatus has failed or encountered problems.

Remarks

The ActiveSync service provider can return NOERROR for all cases if it is not interested.

This is an application programming interface (API) exported by the Store.dll for the synchronization engine.

See Also

IReplStore


IReplStore::UpdateItem

This method updates the object’s time stamp, change number, and other information that is stored in the specified handle.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

void UpdateItem( HREPLFLD hFolder, HREPLITEM hItemDst,
HREPLITEM hItemSrc );

Parameters

hFolder
Handle to a folder that stores the item.
hItemDst
Handle to the destination item.
hItemSrc
Handle to the source item; can be NULL.

Return Values

None.

Remarks

The ActiveSync service manager calls the IReplStore::UpdateItem method to update the relevant information, such as time stamp or change number, in the specified handle. If a source handle is specified, the ActiveSync service provider should copy the information over; otherwise, the ActiveSync service provider should open the object, then get the object’s information and store it in the destination handle.

See Also

IReplStore


IRootStorage : IUnknown

This interface contains a single method that switches a storage object to a different underlying file and saves the storage object to that file.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

The IRootStorage interface contains a single method that switches a storage object to a different underlying file and saves the storage object to that file. The save operation occurs even with low memory conditions and uncommitted changes to the storage object. A subsequent call to IStorage::Commit is guaranteed to not consume any additional memory.

When to Implement

Storage objects that are based on a file should implement IRootStorage in addition to the IStorage interface. For storage objects that are not file-based, this interface is not necessary.

OLE provides an implementation of a storage object, including the IRootStorage interface, as part of its compound file implementation.

When to Use

The primary use for the IRootStorage interface is to save a storage object to a file during low memory conditions. Typically, the container application calls the IRootStorage interface to switch to a new file.

If you have an IStorage pointer to a compound file object, you can call IStorage::QueryInterface with IID_IRootStorage to obtain a pointer to the IRootStorage interface.

Method
Description
IRootStorage::SwitchToFile Copies the file underlying this root storage object, then associates this storage with the copied file.


IRootStorage::SwitchToFile

This method copies the current file associated with the storage object to a new file, which is then used for the storage object and any uncommitted changes.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SwitchTofFile( LPOLESTR pszFile, );

Parameters

pszFile
Pointer to the null-terminated string that contains the name for the new file. It cannot be the name of an existing file. If NULL, this method creates a temporary file with a unique name, and you can call IStorage::Stat to retrieve the name of the temporary file.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The file was successfully copied.
STG_E_MEDIUMFULL | The file was not copied because of insufficient space on the storage device.
STG_E_ACCESSDENIED | The file was not copied because the caller does not have permission to access storage device.
STG_E_INVALIDPOINTER | The file was not copied because the pszFile pointer is invalid.
STG_E_FILEALREADYEXISTS | The file was not copied because the new filename (pszFile) points to an existing file.

Remarks

The IRootStorage::SwitchToFile method copies the file associated with the storage object. A COM container calls SwitchToFile to perform a full save on a file in a low-memory situation. Typically, this is done only after a normal full save operation—save to temporary file, delete original file, and rename temporary file—has failed with an E_OUTOFMEMORY error.

It is illegal to call SwitchToFile if the storage object or anything contained within it has been marshalled to another process. As a consequence, before calling SwitchToFile, the container must call the IPersistStorage::HandsOffStorage method for any element within the storage object that is loaded or running. The HandsOffStorage method forces the element to release its storage pointers and enter the hands-off storage mode. The container must also release all pointers to streams or storages that are contained in this root storage. After the full save operation is completed, the container returns the contained elements to normal storage mode.

When storing storage objects on NTFS systems in native structured storage format, the files are automatically converted for all non-NTFS partitions, for example FAT partitions. The IRootStorage::SwitchToFile method is not supported for NTFS native structured storage files.

Notes to Implementers

If you are implementing your own storage objects, the IRootStorage methods (including QueryInterface, AddRef, and Release) must not consume additional memory or file handles.


IStorage : IUnknown

This interface provides methods for creating and managing the root storage, child storage, and stream objects. These methods can create, open, enumerate, move, copy, rename, or delete the elements in the storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

The IStorage interface supports the creation and management of structured storage objects. Structured storage allows hierarchical storage of information within a single file, and is often referred to as “a file system within a file”. Elements of a structured storage object are storages and streams. Storages are analogous to directories, and streams are analogous to files. Within a structured storage there will be a primary storage object that may contain substorages, possibly nested, and streams. Storages provide the structure of the object, and streams contain the data, which is manipulated through the IStream interface.

The IStorage interface provides methods for creating and managing the root storage object, child storage objects, and stream objects. These methods can create, open, enumerate, move, copy, rename, or delete the elements in the storage object.

An application must release its IStorage pointers when it is done with the storage object to deallocate memory used. There are also methods for changing the date and time of an element.

There are a number of different modes in which a storage object and its elements can be opened, determined by setting values from the STGM enumeration. One aspect of this is how changes are committed. You can set direct mode, in which in which changes to an object are immediately written to it, or transacted mode, in which changes are written to a buffer until explicitly committed. The IStorage interface provides methods for committing changes and reverting to the last-committed version. Other storage modes set, for example, a stream can be opened in read only mode or read/write mode. For more information, refer to the STGM enumeration.

Other methods provide a means to gain access to information about a storage object and its elements through the STATSTG structure.

When to Implement

Generally, you would not implement this interface unless you were defining a new storage scheme for your system. COM provides a compound file implementation of the IStorage interface that supports transacted access. COM provides a set of helper APIs to facilitate using the compound file implementation of storage objects. Refer to IStorage - Compound File Implementation.

When to Use

Call the methods of IStorage to manage substorages or streams within the current storage. This management includes creating, opening, or destroying sub-storages or streams, as well as managing aspects such as time stamps and names. You can also commit changes or revert to previous version for storages opened in transacted mode. The methods of IStorage do not include means to read and write data—this is reserved for IStream, which manages the actual data. While the IStorage and IStream interfaces are used to manipulate the storage object and its elements, the IPersistStorage interface contains methods that are called to serialize the storage object and its elements to a disk file.

Method
Description
IStorage::Commit | Reflects changes for a transacted storage object in the parent level.
IStorage::CopyTo | Copies the entire contents of this open storage object into another storage object.
IStorage::CreateStorage | Creates and opens a new storage object nested within this storage object.
IStorage::CreateStream | Creates and opens a stream object with the specified name contained in this storage object. All elements within a storage object, both streams and other storage objects, are kept in the same name space.
IStorage::DestroyElement | Removes the specified storage or stream object from this storage object.
IStorage::EnumElements | Retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.
IStorage::MoveElementTo | Copies or moves a substorage or stream object from this storage object to another storage object.
IStorage::OpenStorage | Opens an existing storage object with the specified name according to the specified access mode.
IStorage::OpenStream | Opens an existing stream object within this storage object according to the specified access mode.
IStorage::RenameElement | Renames the specified storage or stream object in this storage object.
IStorage::Revert | Discards all changes that have been made to the storage object since the last commit operation.
IStorage::SetClass | Assigns the specified class idenitifier (CLSID) to this storage object.
IStorage::SetElementTimes | Sets the modification, access, and creation times of the indicated storage element, if supported by the underlying file system.
IStorage::SetStateBits | Stores up to 32 bits of state information in this storage object.
IStorage::Stat | Returns the STATSTG structure for this open storage object.


IStorage::Commit

This method ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage; for a root storage, reflects the changes in the actual device, for example, a file on disk. For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk. For non-root storage objects in direct mode, this method has no effect.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Commit( DWORD grfCommitFlags );

Parameter

grfCommitFlags
[in] Controls how the changes are committed to the storage object. For a definition of these values, see the STGC enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Changes to the storage object were successfully committed to the parent level. If STGC_CONSOLIDATE was specified, the storage was successfully consolidated, or the storage was already too compact to consolidate further.
STG_S_MULTIPLEOPENS | The commit operation succeeded, but the storage could not be consolidated because it had been opened multiple times using the STGM_NOSNAPSHOT flag.
STG_S_CANNOTCONSOLIDATE | The commit operation succeeded, but the storage could not be consolidated due to an incorrect storage mode. For compound files, the storage may have been opened using the STGM_NOSCRATCH flag, or the storage may not be the outermost transacted level.
STG_S_CONSOLIDATIONFAILED | The commit operation succeeded, but the storage could not be consolidated due to an internal error (for example, a memory allocation failure).
E_PENDING | Asynchronous storage only: Part or all of the data to be committed is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
STG_E_INVALIDFLAG | The value for the grfCommitFlags parameter is not valid.
STG_E_INVALIDPARAMETER | One of the parameters was not valid.
STG_E_NOTCURRENT | Another open instance of the storage object has committed changes. As a result, the current commit operation may overwrite previous changes.
STG_E_MEDIUMFULL | No space left on device to commit.
STG_E_TOOMANYOPENFILES | The commit operation could not be completed because there are too many open files.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStorage::Commit makes permanent changes to a storage object that is in transacted mode, in which changes are accumulated in a buffer, and not reflected in the storage object until there is a call to this method. The alternative is to open an object in direct mode, in which changes are immediately reflected in the storage object and so does not require a commit operation. Calling this method on a storage opened in direct mode has no effect, unless it is a root storage, in which case it ensures that changes in memory buffers are written to the underlying storage device.

The commit operation publishes the current changes in this storage object and its children to the next level up in the storage hierarchy. To undo current changes before committing them, call IStorage::Revert to roll back to the last-committed version.

Calling IStorage::Commit has no effect on currently-opened nested elements of this storage object. They are still valid and can be used. However, the IStorage::Commit method does not automatically commit changes to these nested elements. The commit operation publishes only known changes to the next higher level of the storage hierarchy. Thus, transactions to nested levels must be committed to this storage object before they can be committed to higher levels.

In commit operations, you need to take steps to ensure that data is protected during the commit process:

  • When committing changes to root storage objects, the caller must check the return value to determine whether the operation has been completed successfully, and if not, that the old committed contents of the IStorage are still intact and can be restored.
  • If this storage object was opened with some of its items excluded, then the caller is responsible for rewriting them before calling commit. Write mode is required on the storage opening for the commit to succeed.
  • Unless prohibiting multiple simultaneous writers on the same storage object, an application calling this method should specify at least STGC_ONLYIFCURRENT in the grfCommitFlags parameter to prevent the changes made by one writer from inadvertently overwriting the changes made by another.

If the STGC_CONSOLIDATE flag is not supported by a storage implementation, then calling IStorage::Commit with STGC_CONSOLIDATE specified in the grfCommitFlags parameter returns the value STG_E_INVALIDFLAG.


IStorage::CopyTo

This method copies the entire contents of an open storage object to another storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CopyTo( DWORD ciidExclude, IID const * rgiidExclude,
SNB snbExclude, IStorage * pstgDest );

Parameters

ciidExclude
[in] Number of elements in the array pointed to by rgiidExclude. If rgiidExclude is NULL, then ciidExclude is ignored.
rgiidExclude
[in] Array of interface identifiers that either the caller knows about and does not want to be copied or that the storage object does not support but whose state the caller will later explicitly copy. The array can include IStorage, that indicates that only stream objects are to be copied, and IStream, that indicates that only storage objects are to be copied. An array length of zero indicates that only the state exposed by the IStorage object is to be copied; all other interfaces on the object are to be ignored. Passing NULL indicates that all interfaces on the object are to be copied.
snbExclude
[in] String name block (refer to SNB) that specifies a block of storage or stream objects that are not to be copied to the destination. These elements are not created at the destination. If IID_IStorage is in the rgiidExclude array, this parameter is ignored. This parameter may be NULL.
pstgDest
[in] Pointer to the open storage object into which this storage object is to be copied. The destination storage object can be a different implementation of the IStorage interface from the source storage object. Thus, IStorage::CopyTo can only use publicly available methods of the destination storage object. If pstgDest is open in transacted mode, it can be reverted by calling its IStorage::Revert method.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The storage object was successfully copied.
E_PENDING | Asynchronous Storage only: Part or all of the data to be copied is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The destination storage object is a child of the source storage object.
STG_E_INSUFFICIENTMEMORY | The copy was not completed due to a lack of memory.
STG_E_INVALIDPOINTER | The pointer specified for the storage object was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_TOOMANYOPENFILES | The copy was not completed because there are too many open files.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_MEDIUMFULL | The copy was not completed because the storage medium is full.

Remarks

This method merges elements contained in the source storage object with those already present in the destination. The layout of the destination storage object may differ from the source storage object.

The copy process is recursive, invoking IStorage::CopyTo and IStream::CopyTo on the elements nested inside the source.

When copying a stream on top of an existing stream with the same name, the existing stream is first removed and then replaced with the source stream. When copying a storage on top of an existing storage with the same name, the existing storage is not removed. As a result,, after the copy operation, the destination IStorage contains older elements, unless they were replaced by newer ones with the same names.

A storage object may expose interfaces other than IStorage, including IRootStorage, IPropertyStorage, or IPropertySetStorage. The rgiidExclude parameter provides a way to exclude any or all of these additional interfaces from the copy operation.

A caller with a newer or more efficient copy of an existing substorage or stream object may want to exclude the current versions of these objects from the copy operation. The snbExclude and rgiidExclude parameters provide two different ways of excluding a storage objects existing storages or streams.

Note to Callers

The most common way to use this method is to copy everything possible from the source to the destination, as in most Full Save and SaveAs operations. The following code example illustrates this call:

pstg->CopyTo(0, NULL, NULL, pstgDest)


IStorage::CreateStorage

This method creates and opens a new storage object nested within this storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CreateStorage( const WCHAR * pwcsName, DWORD grfMode,
DWORD reserved1, DWORD reserved2, IStorage ** ppstg );

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the newly created storage object. This name can be used later to reopen the storage object.
grfMode
[in] Specifies the access mode to use when opening the newly created storage object. See the STGM enumeration values for descriptions of the possible values.
reserved1
[in] Reserved for future use; set to zero.
reserved2
[in] Reserved for future use; set to zero.
ppstg
[out] When successful, pointer to the location of the IStorage pointer to the newly-created storage object. This parameter is set to NULL if an error occurs.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The storage object was created successfully.
E_PENDING | Asynchronous Storage only: Part or all of the necessary data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | Insufficient permissions to create storage object.
STG_E_FILEALREADYEXISTS | The name specified for the storage object already exists in the storage object and the grfmode flag includes the flag STGM_FAILIFTHERE.
STG_E_INSUFFICIENTMEMORY | The storage object was not created due to a lack of memory.
STG_E_INVALIDFLAG | The value specified for the grfMode flag is not a valid STGM enumeration value.
STG_E_INVALIDFUNCTION | The specified combination of grfMode flags is not supported.
STG_E_INVALIDNAME | Invalid value for pwcsName.
STG_E_INVALIDPOINTER | The pointer specified for the storage object was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The storage object was not created because there are too many open files.
STG_S_CONVERTED | The existing stream with the specified name was replaced with a new storage object that contains a single stream called CONTENTS. The new storage object will be added.

Remarks

If a storage with the name specified in the pwcsName parameter already exists within the parent storage object, and the grfMode parameter includes the STGM_CREATE flag, the existing storage is replaced by the new one. If the grfMode parameter includes the STGM_CONVERT flag, the existing element is converted to a stream object named CONTENTS and the new storage object is created that contains the CONTENTS stream object. The destruction of the old element and the creation of the new storage object are both subject to the transaction mode on the parent storage object.

If a storage object with the same name already exists and grfMode is set to STGM_FAILIFTHERE, this method fails with the return value STG_E_FILEALREADYEXISTS.


IStorage::CreateStream

This method creates and opens a stream object with the specified name contained in this storage object. All elements within a storage object, both streams and other storage objects, are kept in the same name space.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CreateStream( const WCHAR * pwcsName, DWORD grfmode,
DWORD reserved1, DWORD * reserved2, IStream * ppstm,);

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the newly created stream. This name can be used later to open or reopen the stream.
grfMode
[in] Specifies the access mode to use when opening the newly created stream. See the STGM enumeration values for descriptions of the possible values.
reserved1
[in] Reserved for future use; set to zero.
reserved2
[in] Reserved for future use; set to zero.
ppstm
[out] On return, pointer to the location of the new IStream interface pointer. This is only valid if the operation is successful. When an error occurs, this parameter is set to NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The new stream was successfully created.
E_PENDING | Asynchronous Storage only: Part or all of the necessary data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | Insufficient permissions to create stream.
STG_E_FILEALREADYEXISTS | The name specified for the stream already exists in the storage object and the grfmode flag includes the flag STGM_FAILIFTHERE.
STG_E_INSUFFICIENTMEMORY | The stream was not created due to a lack of memory.
STG_E_INVALIDFLAG | The value specified for the grfMode flag is not a valid STGM enumeration value.
STG_E_INVALIDFUNCTION | The specified combination of grfMode flags is not supported. For example, if this method is called without the STGM_SHARE_EXCLUSIVE flag.
STG_E_INVALIDNAME | Invalid value for pwcsName.
STG_E_INVALIDPOINTER | The pointer specified for the stream object was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The stream was not created because there are too many open files.

Remarks

If a stream with the name specified in the pwcsName parameter already exists and the grfMode parameter includes the STGM_CREATE flag, the existing stream is replaced by a newly created one. Both the destruction of the old stream and the creation of the new stream object are subject to the transaction mode on the parent storage object.

If the stream already exists and grfMode is set to STGM_FAILIFTHERE, this method fails with the return value STG_E_FILEALREADYEXISTS.


IStorage::DestroyElement

This method removes the specified storage or stream object from this storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DestroyElement( WCHAR * pwcsName );

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the storage or stream to be removed.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The element was successfully removed.
E_PENDING | Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for removing the element.
STG_E_FILENOTFOUND | The element with the specified name does not exist.
STG_E_INSUFFICIENTMEMORY | The element was not removed due to a lack of memory.
STG_E_INVALIDNAME | Invalid value for pwcsName.
STG_E_INVALIDPOINTER | The pointer specified for the element was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The element was not removed because there are too many open files.

Remarks

The DestroyElement method deletes a substorage or stream from the current storage object. After a successful call to DestroyElement, any open instance of the destroyed element from the parent storage becomes invalid.

If a storage object is opened in transacted mode, destruction of an element requires that the call to DestroyElement be followed by a call to IStorage::Commit.


IStorage::EnumElements

This method retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT EnumElement( DWORD reserved1, void * reserved2,
DWORD reserved3, IEnumSTATSTG ** ppenum );

Parameters

reserved1
[in] Reserved for future use; set to zero.
reserved2
[in] Reserved for future use; set to NULL.
reserved3
[in] Reserved for future use; set to zero.
ppenum
[out] Address of IEnumSTATSTG* pointer variable that receives the interface pointer to the new enumerator object.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The enumerator object was successfully returned.
E_PENDING | Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_INSUFFICIENTMEMORY | The enumerator object could not be created due to lack of memory.
STG_E_INVALIDPARAMETER | One of the parameters was not valid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

The enumerator object returned by this method implements the IEnumSTATSTG interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods. IEnumSTATSTG enumerates the data stored in an array of STATSTG structures.

The storage object must be open in read mode to allow the enumeration of its elements.

The order in which the elements are enumerated and whether the enumerator is a snapshot or always reflects the current state of the storage object, and depends on the IStorage implementation.


IStorage::MoveElementTo

This method copies or moves a substorage or stream object from this storage object to another storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT MoveElementTo( const WCHAR * pwcsName,
IStorage * pstgDest, LPWSTR pwcsNewName, DWORD grfFlags );

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the element in this storage object to be moved or copied.
pstgDest
[in] IStorage pointer to the destination storage object.
pwcsNewName
[in] Pointer to a wide character string that contains the new name for the element in its new storage object.
grfFlags
[in] Specifies whether the operation should be a move (STGMOVE_MOVE) or a copy (STGMOVE_COPY). See the STGMOVE enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The storage object was successfully copied or moved.
E_PENDING | Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The destination storage object is a child of the source storage object.
STG_E_FILENOTFOUND | The element with the specified name does not exist.
STG_E_FILEALREADYEXISTS | The specified file already exists.
STG_E_INSUFFICIENTMEMORY | The copy or move was not completed due to a lack of memory.
STG_E_INVALIDFLAG | The value for the grfFlags parameter is not valid.
STG_E_INVALIDNAME | Invalid value for pwcsName.
STG_E_INVALIDPOINTER | The pointer specified for the storage object was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The copy or move was not completed because there are too many open files.

Remarks

The IStorage::MoveElementTo method is typically the same as invoking the IStorage::CopyTo method on the indicated element and then removing the source element. In this case, the MoveElementTo method uses only the publicly available functions of the destination storage object to carry out the move.

If the source and destination storage objects have special knowledge about each other’s implementation (they could, for example, be different instances of the same implementation), this method can be implemented more efficiently.

Before calling this method, the element to be moved must be closed, and the destination storage must be open.


IStorage::OpenStorage

This method opens an existing storage object with the specified name according to the specified access mode.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT OpenStorage( const WCHAR * pwcsName,
IStorage * pstgPriority, DWORD grfMode, SNB snbExclude,
DWORD reserved, IStorage ** ppstg );

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the storage object to open. It is ignored if pstgPriority is non-NULL.
pstgPriority
[in] If the pstgPriority parameter is not NULL, it is an IStorage pointer to a previous opening of an element of the storage object, usually one that was opened in priority mode. The storage object should be closed and re-opened according to grfMode. When the IStorage::OpenStorage method returns, pstgPriority is no longer valid. Use the value supplied in the ppstg parameter. If the pstgPriority parameter is NULL, it is ignored.
grfMode
[in] Specifies the access mode to use when opening the storage object. See the STGM enumeration values for descriptions of the possible values. Whatever other modes you may choose, you must at least specify STGM_SHARE_EXCLUSIVE when calling this method.
snbExclude
[in] Set to NULL. A non-NULL value will return STG_E_INVALIDPARAMETER.
reserved
[in] Reserved for future use; set to zero.
ppstg
[out] When the operation is successful, pointer to the location of an IStorage pointer to the opened storage object. This parameter is set to NULL if an error occurs.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The storage object was opened successfully.
E_PENDING | Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | Insufficient permissions to open storage object.
STG_E_FILENOTFOUND | The storage object with the specified name does not exist.
STG_E_INSUFFICIENTMEMORY | The storage object was not opened due to a lack of memory.
STG_E_INVALIDFLAG | The value specified for the grfMode flag is not a valid STGM enumeration value.
STG_E_INVALIDFUNCTION | The specified combination of grfMode flags is not supported.
STG_E_INVALIDNAME | Invalid value for pwcsName.
STG_E_INVALIDPOINTER | The pointer specified for the storage object was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The storage object was not created because there are too many open files.
STG_S_CONVERTED | The existing stream with the specified name was replaced with a new storage object that contains a single stream called CONTENTS. In direct mode, the new storage is immediately written to disk. In transacted mode, the new storage is written to a temporary storage in memory and later written to disk when it is committed.

Remarks

Storage objects can be opened with STGM_DELETEONRELEASE, in which case the object is destroyed when it receives its final release. This is useful for creating temporary storage objects.


IStorage::OpenStream

This method opens an existing stream object within this storage object according to the specified access mode.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT OpenStream( const WCHAR * pwcsName, void * reserved1,
DWORD grfMode, DWORD reserved2, IStream ** ppstm );

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the stream to open.
reserved1
[in] Reserved for future use; set to NULL.
grfMode
[in] Specifies the access mode to be assigned to the open stream. See the STGM enumeration values for descriptions of the possible values. Whatever other modes you may choose, you must at least specify STGM_SHARE_EXCLUSIVE when calling this method.
reserved2
[in] Reserved for future use; set to zero.
ppstm
[out] Address of IStream* pointer variable that receives the interface pointer to the newly-opened stream object. If an error occurs, *ppstm must be set to NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The stream was successfully opened.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | Insufficient permissions to open stream.
STG_E_FILENOTFOUND | The stream with specified name does not exist.
STG_E_INSUFFICIENTMEMORY | The stream was not opened due to a lack of memory.
STG_E_INVALIDFLAG | The value specified for the grfMode flag is not a valid STGM enumeration value.
STG_E_INVALIDFUNCTION | The specified combination of grfMode flags is not supported. For example, if this method is called without the STGM_SHARE_EXCLUSIVE flag.
STG_E_INVALIDNAME | Invalid value for pwcsName.
STG_E_INVALIDPOINTER | The pointer specified for the stream object was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The stream was not opened because there are too many open files.

Remarks

IStorage::OpenStream opens an existing stream object within this storage object in the access mode specified in grfMode. There are restrictions on the permissions that can be given in grfMode. For example, the permissions on this storage object restrict the permissions on its streams. In general, access restrictions on streams should be stricter than those on their parent storages. Compound-file streams must be opened with STGM_SHARE_EXCLUSIVE.


IStorage::RenameElement

This method renames the specified substorage or stream object in this storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT RenameElement( const WCHAR * pwcsOldName,
const WCHAR * pwcsNewName);

Parameters

pwcsOldName
[in] Pointer to a wide character string that contains the name of the substorage or stream to be changed.
pwcsNewName
[in] Pointer to a wide character string that contains the new name for the specified substorage or stream.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The element was successfully renamed.
E_PENDING | Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for renaming the element.
STG_E_FILENOTFOUND | The element with the specified old name does not exist.
STG_E_FILEALREADYEXISTS | The element specified by the new name already exists.
STG_E_INSUFFICIENTMEMORY | The element was not renamed due to a lack of memory.
STG_E_INVALIDNAME | Invalid value for one of the names.
STG_E_INVALIDPOINTER | The pointer specified for the element was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_TOOMANYOPENFILES | The element was not renamed because there are too many open files.

Remarks

IStorage::RenameElement renames the specified substorage or stream in this storage object. An element in a storage object cannot be renamed while it is open. The rename operation is subject to committing the changes if the storage is open in transacted mode.

The IStorage::RenameElement method is not guaranteed to work in low memory with storage objects open in transacted mode. It may work in direct mode.


IStorage::Revert

This method discards all changes that have been made to the storage object since the last commit operation.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Revert( void );

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The revert operation was successful.
E_PENDING | Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_INSUFFICIENTMEMORY | The revert operation could not be completed due to a lack of memory.
STG_E_TOOMANYOPENFILES | The revert operation could not be completed because there are too many open files.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

For storage objects opened in transacted mode, the IStorage::Revert method discards any uncommitted changes to this storage object or changes that have been committed to this storage object from nested elements.

After this method returns, any existing elements (substorages or streams) that were opened from the reverted storage object are invalid and can no longer be used. Specifying these reverted elements in any call except IStorage::Release returns the error STG_E_REVERTED

This method has no effect on storage objects opened in direct mode.


IStorage::SetClass

This method assigns the specified class identifier (CLSID) to this storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetClass( REFCLSID clsid );

Parameters

clsid
[in] Class identifier (CLSID) that is to be associated with the storage object.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The CLSID was successfully assigned.
E_PENDING | Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for assigning a class identifier to the storage object.
STG_E_MEDIUMFULL | Not enough space was left on device to complete the operation.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

When first created, a storage object has an associated CLSID of CLSID_NULL. Call this method to assign a CLSID to the storage object.

Call the IStorage::Stat method to retrieve the current CLSID of a storage object.


IStorage::SetElementTimes

This method sets the modification, access, and creation times of the specified storage element, if supported by the underlying file system.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetElementTimes( const WCHAR * pwcsName,
FILETIME const * pctime, FILETIME const * patime,
FILETIME const * pmtime );

Parameters

pwcsName
[in] Pointer to a wide character string that contains the name of the storage object element whose times are to be modified. If NULL, the time is set on the root storage rather than one of its elements.
pctime
[in] Either the new creation time for the element or NULL if the creation time is not to be modified.
patime
[in] Either the new access time for the element or NULL if the access time is not to be modified.
pmtime
[in] Either the new modification time for the element or NULL if the modification time is not to be modified.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The time values were successfully set.
E_PENDING | Asynchronous Storage only: Part or all of the element’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for changing the element.
STG_E_FILENOTFOUND | The element with the specified name does not exist.
STG_E_INSUFFICIENTMEMORY | The element was not changed due to a lack of memory.
STG_E_INVALIDNAME | Invalid value for the element name.
STG_E_INVALIDPOINTER | The pointer specified for the element was invalid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.
STG_E_TOOMANYOPENFILES | The element was not changed because there are too many open files.
STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method sets time statistics for the specified storage element within this storage object.

Not all file systems support all of the time values. This method sets those times that are supported and ignores the rest. Each of the time value parameters can be NULL; that indicates that no modification should occur.

Call the IStorage::Stat method to retrieve these time values.


IStorage::SetStateBits

This method stores up to 32 bits of state information in this storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetStateBits( DWORD grfStateBits, DWORD grfMask );

Parameters

grfStateBits
[in] Specifies the new values of the bits to set. No legal values are defined for these bits; they are all reserved for future use and must not be used by applications.
grfMask
[in] Binary mask that indicates which bits in grfStateBits are significant in this call.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The state information was successfully set.
E_PENDING | Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for changing this storage object.
STG_E_INVALIDFLAG | The value for the grfStateBits or grfMask parameters are not valid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.

Remarks

This interface is reserved for future use. The values for the state bits are not currently defined.


IStorage::Stat

This method retrieves the STATSTG structure for this open storage object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Stat( STATSTG * pstatstg, DWORD grfStatFlag);

Parameters

pstatstg
[out] On return, pointer to a STATSTG structure where this method places information about the open storage object. This parameter is NULL if an error occurs.
grfStatFlag
[in] Specifies that some of the members in the STATSTG structure are not returned, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The STATSTG structure was successfully returned at the specified location.
E_PENDING | Asynchronous Storage only: Part or all of the storage’s data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for accessing statistics for this storage object.
STG_E_INSUFFICIENTMEMORY | The STATSTG structure was not returned due to a lack of memory.
STG_E_INVALIDFLAG | The value for the grfStateFlag parameter is not valid.
STG_E_INVALIDPARAMETER | One of the parameters was invalid.

Remarks

IStorage::Stat retrieves the STATSTG structure for the current storage. This structure contains statistical information about the storage. IStorage::EnumElements creates an enumerator object with the IEnumSTATSTG interface, though which you can enumerate the substorages and streams of a storage through the STATSTG structure of each.


IStream : IUnknown

This interface supports reading and writing data to stream objects. Stream objects contain the data in a structured storage object, where storages provide the structure. Simple data can be written directly to a stream, but most frequently, streams are elements nested within a storage object. They are similar to standard files.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

The IStream interface supports reading and writing data to stream objects. Stream objects contain the data in a structured storage object, where storages provide the structure. Simple data can be written directly to a stream, but most frequently, streams are elements nested within a storage object. They are similar to standard files.

The IStream interface defines methods similar to the MS-DOS FAT file functions. For example, each stream object has its own access rights and a seek pointer. The main difference between a stream object and a DOS file is that streams are not opened using a file handle, but through an IStream interface pointer.

The methods in this interface present your object’s data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams open in transacted mode and methods for restricting access to a range of bytes in the stream.

Streams can remain open for long periods of time without consuming file system resources. The IStream::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.

Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous IMoniker::BindToStorage operation and for receiving asynchronous notifications.The table below compares the behavior of asynchronous ISequentialStream::Read and IStream::Seek calls returned in IBindStatusCallback::OnDataAvailable in these two download models:

IStream method call
Behavior in data-pull model
Behavior in data-push model
Read is called to read partial data, that is, not all the available data. | Returns S_OK. The client must continue to read all available data before returning from IBindStatusCallback::OnDataAvailable or else the bind operation is blocked, that is, read until S_FALSE or E_PENDING is returned. | Returns S_OK. Even if the client returns from IBindStatusCallback::OnDataAvailable at this point the bind operation continues and IBindStatusCallback::OnDataAvailable will be called again repeatedly until the binding finishes.
Read is called to read all the available data | Returns E_PENDING if the bind operation has not completed, and IBindStatusCallback::OnDataAvailable will be called again when more data is available. | Same as data-pull model.
Read is called to read all the available data and the bind operation is over (end-of-file) | Returns S_FALSE. There will be a subsequent call to IBindStatusCallback::OnDataAvailable with the grfBSC flag set to BSCF_LASTDATANOTIFICATION. | Same as data-pull model.
Seek is called | Seek doesn’t work in data-pull model | Seek doesn’t work in data-push model.

When to Implement

Implement IStream on a container or object application when you require functionality not provided by the COM compound file implementation. The specification of IStream defines more functionality that the COM implementation supports. In addition, if you are creating a stream object that is larger than the heap in your machine’s memory and you are using a global memory handle, the compound file implementation calls GlobalRealloc internally whenever it needs more memory, which can be extremely inefficient. In this case, the preferred solution is to implement an IStream that uses memory allocated by VirtualAlloc instead of GlobalAlloc. This can reserve a large chunk of virtual address space and then commit memory within that address space as required. No data copying occurs and memory is committed only as it is needed. For more information, refer to IStream - Compound File Implementation.

Note Most containers do not implement ISequentialStream as a separate interface, and you are not required to provide it separately even if you provide an IStream implementation. For example, the compound file implementation of structured storage does not succeed on a QueryInterface for ISequentialStream but it includes the Read and Write methods through the IStream interface pointer. The same is true for the NTFS Native Structured Storage implementation.

When to Use

Call the methods of the IStream interface from a container or application to read and write the data for an object. Since stream objects can be marshaled to other processes, applications can share the data in storage objects without having to use global memory.

Method
Description
IStream::Clone | Creates a new stream object with its own seek pointer that references the same bytes as the original stream.
IStream::Commit | Ensures that any changes made to a stream object opened in transacted mode are reflected in the parent storage object. If the stream object is opened in direct mode, this method has no effect other than flushing all memory buffers to the next level storage object. The OLE compound file implementation of streams does not support opening streams in transacted mode.
IStream::CopyTo | Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.
IStream::LockRegion | Restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
IStream::Read | Reads a specified number of bytes from the stream object into memory, starting at the current seek pointer.
IStream::Revert | Discards all changes that have been made to a transacted stream since the last IStream::Commit call. This method has no effect on streams open in direct mode and streams using the OLE compound file implementation of IStream::Revert.
IStream::Seek | Changes the seek pointer to a new location relative to the current seek pointer or the beginning or end of the stream.
IStream::SetSize | Resizes of the stream object.
IStream::Stat | Retrieves the STATSTG structure for this stream object.
IStream::UnlockRegion | Removes the access restriction on a range of bytes previously restricted with IStream::LockRegion.
IStream::Write | Writes a specified number of bytes into the stream object starting at the current seek pointer.


IStream::Clone

This method creates a new stream object with its own seek pointer that references the same bytes as the original stream.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Clone( IStream ** ppstm );

Parameters

ppstm
[out] When successful, pointer to the location of an IStream pointer to the new stream object. If an error occurs, this parameter is NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The stream was successfully cloned.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_INSUFFICIENT_MEMORY | The stream was not cloned due to a lack of memory.
STG_E_INVALIDPOINTER | The ppStm pointer is not valid.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method creates a new stream object for accessing the same bytes but using a separate seek pointer. The new stream object sees the same data as the source stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.

The initial setting of the seek pointer in the cloned stream instance is the same as the current setting of the seek pointer in the original stream at the time of the clone operation.


IStream::Commit

This method ensures that any changes made to a stream object opened in transacted mode are reflected in the parent storage. If the stream object is opened in direct mode, IStream::Commit has no effect other than flushing all memory buffers to the next level storage object. The OLE compound file implementation of streams does not support opening streams in transacted mode.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Commit( DWORD grfCommitFlags );

Parameters

grfCommitFlags
[in] Controls how the changes for the stream object are committed. For a definition of these values, see the STGC enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Changes to the stream object were successfully committed to the parent level.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_MEDIUMFULL | The commit operation failed due to lack of space on the storage device.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may still revert at a later time rolling back the changes to this stream object. The compound file implementation does not support opening streams in transacted mode, so this method has very little effect other than to flush memory buffers.

If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.

The IStream::Commit method is useful on a direct mode stream when the implementation of the IStream interface is a wrapper for underlying file system APIs. In this case, IStream::Commit would be connected to the file system’s flush call.


IStream::CopyTo

This method copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CopyTo( IStream * pstm, ULARGE_INTEGER cb,
ULARGE_INTEGER * pcbRead, ULARGE_INTEGER * pcbWritten );

Parameters

pstm
[in] Pointer to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
cb
[in] Specifies the number of bytes to copy from the source stream.
pcbRead
[out] Pointer to the location where this method writes the actual number of bytes read from the source. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes read.
pcbWritten
[out] Pointer to the location where this method writes the actual number of bytes written to the destination. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes written.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The stream object was successfully copied.
E_PENDING | Asynchronous Storage only: Part or all of the data to be copied is currently unavailable.
STG_E_INVALIDPOINTER | The value of one of the pointer parameters is not valid.
STG_E_MEDIUMFULL | The stream is not copied because there is no space left on the storage device.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

This method copies the specified bytes from one stream to another. The seek pointer in each stream instance is adjusted for the number of bytes read or written.

The destination stream can be a clone of the source stream created by calling the IStream::Clone method.

If IStream::CopyTo returns an error, you cannot assume that the seek pointers are valid for either the source or destination. Additionally, the values of pcbRead and pcbWritten are not meaningful even though they are returned.

If IStream::CopyTo returns successfully, the actual number of bytes read and written are the same.

To copy the remainder of the source from the current seek pointer, specify the maximum large integer value for the cb parameter. If the seek pointer is the beginning of the stream, this technique copies the entire stream.


IStream::LockRegion

This method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT LockRegion( LARGE_INTEGER libOffset,
LARGE_INTEGER cb, DWORD dwLockType );

Parameters

libOffset
[in] Integer that specifies the byte offset for the beginning of the range.
cb
[in] Integer that specifies the length of the range, in bytes, to be restricted.
dwLockType
[in] Specifies the restrictions being requested on accessing the range.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The specified range of bytes was locked.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_INVALIDFUNCTION | Locking is not supported at all or the specific type of lock requested is not supported.
STG_E_LOCKVIOLATION | Requested lock is supported, but cannot be granted because of an existing lock.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

The byte range can extend past the current end of the stream. Locking beyond the end of a stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.

Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requestor to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the LOCKTYPE enumeration.

Any region locked with IStream::LockRegion must later be explicitly unlocked by calling IStream::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

Notes to Callers

Since the type of locking supported is optional and can vary in different implementations of IStream, you must provide code to deal with the STG_E_INVALIDFUNCTION error.

This method has no effect in the compound file implementation, because the implementation does not support range locking.

Notes to Implementers

Support for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.


IStream::Read

This method reads a specified number of bytes from the stream object into memory, starting at the current seek pointer.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Read( void * pv, ULONG cb, ULONG *pcbRead );


IStream::Revert

This method discards all changes that have been made to a transacted stream since the last IStream::Commit call. This method has no effect on streams open in direct mode and streams using the OLE compound file implementation of IStream::Revert.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Revert( void );

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The stream was successfully reverted to its previous version.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.

Remarks

This method discards changes made to a transacted stream since the last commit operation.


IStream::Seek

This method changes the seek pointer to a new location relative to the current seek pointer or the beginning or end of the stream.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Seek( ULARGE_INTEGER dlibMove, DWORD dwOrigin,
ULARGE_INTEGER plibNewPosition );

Parameters

dlibMove
[in] Displacement to be added to the location indicated by dwOrigin. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than signed.
dwOrigin
[in] Specifies the origin for the displacement specified in dlibMove. The origin can be the beginning of the file, the current seek pointer, or the end of the file.
plibNewPosition
[out] Pointer to the location where this method writes the value of the new seek pointer from the beginning of the stream. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the new seek pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The seek pointer has been successfully adjusted.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_INVALIDPOINTER | The value of the plibNewPosition parameter is not valid.
STG_E_INVALIDFUNCTION | The value of the dwOrigin parameter is not valid.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::Seek changes the seek pointer so subsequent reads and writes can take place at a different location in the stream object. It is an error to seek before the beginning of the stream. It is not, however, an error to seek past the end of the stream. Seeking past the end of the stream is useful for subsequent writes, as the stream will at that time be extended to the seek position immediately before the write is done.

You can also use this method to obtain the current value of the seek pointer by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so the seek pointer is not changed. The current seek pointer is returned in the plibNewPosition parameter.


IStream::SetSize

This method resizes the stream object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetSize( ULARGE_INTEGER libNewSize );

Parameters

libNewSize
[in] Specifies the new size of the stream as a number of bytes.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The size of the stream object was successfully changed.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_MEDIUMFULL | The stream size is not changed because there is no space left on the storage device.
STG_E_INVALIDFUNCTION | The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD of libNewSize must be 0. If it is nonzero, this parameter is not valid.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::SetSize changes the size of the stream object. Call this method to preallocate space for the stream. If the libNewSize parameters larger than the current stream size, the stream is extended to the indicated size by filling the intervening space with bytes of undefined value.

If the libNewSize parameter is smaller than the current stream, then the stream is truncated to the indicated size.

The seek pointer is not affected by the change in stream size.

Calling IStream::SetSize can be an effective way of trying to obtain a large chunk of contiguous space.


IStream::Stat

This method retrieves the STATSTG structure for this stream object.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Stat( STATSTG * pstatstg, DWORD grfStartFlag );

Parameters

pstatstg
[out] Pointer to a STATSTG structure where this method places information about this stream object. This pointer is NULL if an error occurs.
grfStatFlag
[in] Specifies that this method does not return some of the members in the STATSTG structure, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration.

Return Value

One of the values described in the following table is returned.

Value
Description
S_OK | The STATSTG structure was successfully returned at the specified location.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_ACCESSDENIED | The caller does not have sufficient permissions for accessing statistics for this storage object.
STG_E_INSUFFICIENTMEMORY | The STATSTG structure was not returned due to a lack of memory.
STG_E_INVALIDFLAG | The value for the grfStateFlag parameter is not valid.
STG_E_INVALIDPOINTER | The pStatStg pointer is not valid.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::Stat retrieves a pointer to the STATSTG structure that contains information about this open stream. When this stream is within a structured storage and IStorage::EnumElements is called, it creates an enumerator object with the IEnumSTATSTG interface on it, which can be called to enumerate the storages and streams through the STATSTG structures associated with each of them.


IStream::UnlockRegion

This method removes the access restriction on a range of bytes previously restricted with IStream::LockRegion.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT UnlockRegion( ULARGE_INTEGER libOffset, ULARGE_INTEGER cb, DWORD dwLockType);

Parameters

libOffset
[in] Specifies the byte offset for the beginning of the range.
cb
[in] Specifies, in bytes, the length of the range to be restricted.
dwLockType
[in] Specifies the access restrictions previously placed on the range.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The byte range was unlocked.
E_PENDING | Asynchronous Storage only: Part or all of the stream’s data is currently unavailable.
STG_E_INVALIDFUNCTION | Locking is not supported at all or the specific type of lock requested is not supported.
STG_E_LOCKVIOLATION | The requested unlock cannot be granted.
STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.

Remarks

IStream::UnlockRegion unlocks a region previously locked with the IStream::LockRegion method. Locked regions must later be explicitly unlocked by calling IStream::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.


IStream::Write

This method writes a specified number of bytes into the stream object starting at the current seek pointer.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Write( void const * pv, ULONG cb, ULONG * pcbWritten);


ISupportErrorInfo : IUnknown

This interface ensures that error information can be propagated up the call chain correctly. Automation objects that use the error handling interfaces must implement ISupportErrorInfo.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The ISupportErrorInfo interface ensures that error information can be propagated up the call chain correctly. Automation objects that use the error handling interfaces must implement ISupportErrorInfo.

Implemented by
Used by
Header filename
Applications that return error information. Applications that retrieve error information. Oleauto.h
(32-bit systems)

Dispatch.h
(16-bit systems)

Method
Description
ISupportErrorInfo::InterfaceSupportsErrorInfo Indicates whether or not an interface supports the IErrorInfo interface.


ISupportErrorInfo::InterfaceSupportsErrorInfo

This method indicates whether or not an interface supports the IErrorInfo interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT InterfaceSupportsErrorInfo(REFIID riid);

Parameters

riid
Pointer to an interface identifier (IID).

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Interface supports IErrorInfo.
S_FALSE | Interface does not support IErrorInfo.

Remarks

Objects that support the IErrorInfo interface must also implement this interface.

Programs that receive an error return value should call QueryInterface to get a pointer to the ISupportErrorInfo interface, and then call InterfaceSupportsErrorInfo with the riid of the interface that returned the return value. If InterfaceSupportsErrorInfo returns S_FALSE, then the error object does not represent an error returned from the caller, but from somewhere else. In this case, the error object can be considered incorrect and should be discarded.

If ISupportErrorInfo returns S_OK, use the GetErrorInfo function to get a pointer to the error object.

Example

The following code example implements the ISupportErrorInfo for the Lines sample. The IErrorInfo implementation also supports the AddRef, Release, and QueryInterface members inherited from the IUnknown interface.

CSupportErrorInfo::CSupportErrorInfo(IUnknown FAR* punkObject, REFIID riid)
{
   m_punkObject = punkObject;
   m_iid = riid;
}

STDMETHODIMP
CSupportErrorInfo::QueryInterface(REFIID iid, void FAR* FAR* ppv)
{
   return m_punkObject->QueryInterface(iid, ppv);
}

STDMETHODIMP_(ULONG)
CSupportErrorInfo::AddRef(void)
{
   return m_punkObject->AddRef();
}

STDMETHODIMP_(ULONG)
CSupportErrorInfo::Release(void)
{
   return m_punkObject->Release();
}

STDMETHODIMP
CSupportErrorInfo::InterfaceSupportsErrorInfo(REFIID riid)
{
   return (riid == m_iid) ? NOERROR : ResultFromScode(S_FALSE);
}


ITypeComp : IUnknown

This interface provides a fast way to access information that compilers need when binding to and instantiating structures and interfaces.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The ITypeComp interface provides a fast way to access information that compilers need when binding to and instantiating structures and interfaces. Binding is the process of mapping names to types and type members.

Implemented by
Used by
Header file name
Oleaut32.dll (32-bit systems)

Typelib.dll (16-bit systems)

 Tools that need to access the descriptions of objects contained in type libraries. Oleauto.h

Dispatch.h

Method
Description
ITypeComp::Bind | Maps a name to a member of a type, or binds global variables and functions contained in a type library.
ITypeComp::BindType | Binds to the type descriptions contained within a type library.


ITypeComp::Bind

This method maps a name to a member of a type, or binds global variables and functions contained in a type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Bind(OLECHAR FAR* szName, unsigned long lHashVal, unsigned short wFlags, ITypeInfo FAR*FAR* ppTInfo,
DESCKIND FAR* pDescKind, BINDPTR FAR* pBindPtr );

Parameters

szName
NULL-terminated string that contains the name to be bound.
lHashVal
Hash value for the name computed by LHashValOfNameSys.
wFlags
Flags word that contains one or more of the Invoke flags defined in the INVOKEKIND enumeration. Specifies whether the name was referenced as a method or a property. When binding to a variable, specify the flag INVOKE_PROPERTYGET. Specify zero to bind to any type of member.
ppTInfo
If a FUNCDESC or VARDESC was returned, then ppTInfois a pointer to a pointer to the type description that contains the item to which it is bound.
pDescKind
Pointer to a DESCKIND enumerator that indicates whether the name bound to is a VARDESC, FUNCDESC, or TYPECOMP. If there was no match, points to DESCKIND_NONE.
pBindPtr
On return, contains a pointer to the bound-to VARDESC, FUNCDESC, or ITypeComp interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_AMBIGUOUSNAME | More than one instance of this name occurs in the type library.

Remarks

Use Bind for binding to the variables and methods of a type, or for binding to the global variables and methods in a type library. The returned DESCKIND pointer pDescKind indicates whether the name was bound to a VARDESC, a FUNCDESC, or to an ITypeComp instance. The returned pBindPtr points to the VARDESC, FUNCDESC, or ITypeComp.

If a data member or method is bound to, then ppTInfo points to the type description that contains the method or data member.

If Bind binds the name to a nested binding context, it returns a pointer to an ITypeComp instance in pBindPtr and a NULL type description pointer in ppTInfo. For example, if the name of a type description is passed for a module (TKIND_MODULE), enumeration (TKIND_ENUM), or coclass (TKIND_COCLASS), Bind returns the ITypeComp instance of the type description for the module, enumeration, or coclass. This feature supports languages such as Visual Basic that allow references to members of a type description to be qualified by the name of the type description. For example, a function in a module can be referenced by modulename.functionname.

The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be bound to directly from ITypeComp, without specifying the name of the module. The ITypeComp of a coclass defers to the ITypeComp of its default interface.

As with other methods of ITypeComp, ITypeInfo, and ITypeLib, the calling code is responsible for releasing the returned object instances or structures. If a VARDESC or FUNCDESC is returned, the caller is responsible for deleting it with the returned type description and releasing the type description instance itself. Otherwise, if an ITypeComp instance is returned, the caller must release it.

Special rules apply if you call a type library’s Bind method, passing it the name of a member of an Application object class (a class that has the TYPEFLAG_FAPPOBJECT flag set). In this case, Bind returns DESCKIND_IMPLICITAPPOBJ in pDescKind, a VARDESC that describes the Application object in pBindPtr, and the ITypeInfo of the Application object class in ppTInfo. To bind to the object, ITypeInfo::GetTypeComp must make a call to get the ITypeComp of the Application object class, and then reinvoke its Bind method with the name initially passed to the type library’s ITypeComp.

The caller should use the returned ITypeInfo pointer (ppTInfo) to get the address of the member.

The wflags parameter is the same as the wflags parameter in IDispatch::Invoke.


ITypeComp::BindType

This method binds to the type descriptions contained within a type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT BindType( OLECHAR FAR* szName, unsigned long lHashVal,
ITypeInfo FAR* FAR* ppTInfo, ITypeComp FAR* FAR* ppTComp );

Parameters

szName
NULL-terminated string that contains the name to be bound.
lHashVal
Hash value for the name computed by LHashValOfName.
ppTInfo
On return, contains a pointer to a pointer to an ITypeInfo of the type to which the name was bound.
ppTComp
Passes a valid pointer, such as the address of an ITypeComp* variable.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_AMBIGUOUSNAME | More than one instance of this name occurs in the type library.

Remarks

Use the function BindType for binding a type name to the ITypeInfo that describes the type. This function is invoked on the ITypeComp that is returned by ITypeLib::GetTypeComp to bind to types defined within that library. It can also be used in the future for binding to nested types.

Example

TypeComp * ptcomp;
    ptemp -> BindType(szName, lhashval, &ptinfo, &ptemp)


ITypeInfo : IUnknown

This interface is typically used for reading information about objects.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

This section describes ITypeInfo, an interface typically used for reading information about objects. For example, an object browser tool can use ITypeInfo to extract information about the characteristics and capabilities of objects from type libraries.

Implemented by
Used by
Header file name
Oleaut32.dll (32-bit systems)

Typelib.dll (16-bit systems)

 Tools that need to access the descriptions of objects contained in type libraries. Oleauto.h

Dispatch.h

Type information interfaces are intended to describe the parts of the application that can be called by outside clients, rather than those that might be used internally to build an application.

The ITypeInfo interface provides access to the following:

  • The set of function descriptions associated with the type. For interfaces, this contains the set of member functions in the interface.
  • The set of data member descriptions associated with the type. For structures, this contains the set of members of the type.
  • The general attributes of the type, such as whether it describes a structure, an interface, and so on.

The type description of an IDispatch interface can be used to implement the interface.

An instance of ITypeInfo provides various information about the type of an object, and is used in different ways. A compiler can use an ITypeInfo to compile references to members of the type. A type interface browser can use it to find information about each member of the type. An IDispatch implementor can use it to provide automatic delegation of IDispatch calls to an interface.

Type Descriptions

The information associated with an object described by ITypeInfo can include a set of functions, a set of data members, and various type attributes. It is essentially the same as the information described by a C++ class declaration, which can be used to define both interfaces and structures, as well as any combination of functions and data members. In addition to interfaces and structure definitions, the ITypeInfo interface is used to describe other types, including enumerations and aliases. Because the interface to a C file or library is simply a set of functions and variable declarations, ITypeInfo can also be used to describe them.

Type information comprises individual type descriptions. Each type description must have one of the following forms:

Category
ODL keyword
Description
alias | typedef | An alias for another type.
enumeration | enum | An enumeration.
structure | struct | A structure.
union | union | A single data item that can have one of a specified group of types.
module | module | Data and functions not accessed through virtual function table (VTBL) entries.
IDispatch interface | dispinterface | IDispatch properties and methods accessed through IDispatch::Invoke.
OLE interface | interface | OLE member functions accessed through VTBL entries.
dual interface | dual | Supports either VTBL or IDispatch.
component object class | coclass | A component object class. Specifies an implementation of one or more OLE interfaces and one or more IDispatch interfaces.

Note All bit flags that are not used specifically should be set to zero for future compatibility.

Alias

An alias has TypeKind = TKIND_ALIAS. An alias is an empty set of functions, an empty set of data members, and a type description (located in the TYPEATTR), which gives the actual type definition (typedef) of the alias.

Enumeration (Statement)

An enumeration (enum) has TypeKind = TKIND_ENUM. An enumeration is an empty set of functions and a set of constant data members.

Structure (Statement)

A structure (struct) description has TypeKind = TKIND_RECORD. A structure is an empty set of functions and a set of per-instance data members.

Union (Statement)

A union description has TypeKind = TKIND_UNION. A union is an empty set of functions and a set of per-instance data members, each of which has an instance offset of zero.

Module (Statement)

A module has TypeKind = TKIND_MODULE. A module is a set of static functions and a set of static data members.

OLE-Compatible Interface

An interface definition has TypeKind = TKIND_INTERFACE. An interface is a set of pure virtual functions and an empty set of data members. If a type description contains any virtual functions, then the pointer to the VTBL is the first 4 bytes of the instance.

The type information fully describes the member functions in the VTBL, including parameter names and types and function return types. It may inherit from no more than one other interface.

With interfaces and dispinterfaces, all members should have different names, except the accessor functions of properties. For property functions having the same name, the documentation string and Help context should be set for only one of the functions (because they define the same property conceptually).

IDispatch Interface

These include objects (TypeKind = TKIND_DISPATCH) that support the IDispatch interface with a specification of the dispatch data members (such as properties) and methods supported through the object’s Invoke implementation. All members of the dispinterface should have different IDs, except for the accessor functions of properties.

Dual Interface

Dual interfaces have two different type descriptions for the same interface. The TKIND_INTERFACE type description describes the interface as a standard OLE Component Object Model (COM) interface. The TKIND_DISPATCH type description describes the interface as a standard dispatch interface. The lcid and retval parameters, and the HRESULT return types are removed, and the return type of the member is specified to be the same type as the retval parameter.

By default, the TYPEKIND enumeration for a dual interface is TKIND_INTERFACE. Tools that bind to interfaces should check the type flags for TYPEFLAG_FDUAL. If this flag is set, the TKIND_DISPATCH type description is available through a call to ITypeInfo::GetRefTypeOfImplType with an index of –1, followed by a call to ITypeInfo::GetRefTypeInfo.

Component Object Classes

These coclass objects (TypeKind = TKIND_COCLASS) support a set of implemented interfaces, which can be of either TKIND_INTERFACE or TKIND_DISPATCH.

Method
Description
ITypeInfo::AddressOfMember | Retrieves the addresses of static functions or variables, such as those defined in a dynamic-link library (DLL).
ITypeInfo::CreateInstance | Creates a new instance of a type that describes a component object class (coclass).
ITypeInfo::GetContainingTypeLib | Retrieves both the type library that contains a specific type description and the index of the type description within the type library.
ITypeInfo::GetDllEntry | Retrieves a description or specification of an entry point for a function in a dynamic-link library (DLL).
ITypeInfo::GetDocumentation | Retrieves the documentation string, name of the complete Help file name and path, and the context identifier for the Help topic for a specified type description.
ITypeInfo::GetFuncDesc | Retrieves the FUNCDESC structure that contains information about a specified function.
ITypeInfo::GetIDsOfNames | Maps between the names and identifiers of members and parameters.
ITypeInfo::GetImplTypeFlags | Retrieves the IMPLTYPE flags for an interface.
ITypeInfo::GetMops | Retrieves marshaling information.
ITypeInfo::GetNames | Retrieves the variable with the specified member identifier, or the name of the function and parameter names corresponding to the specified function identifier.
ITypeInfo::GetRefTypeInfo | Retrieves the type descriptions referenced by a specified type description.
ITypeInfo::GetRefTypeOfImplType | Retrieves the type description of implemented interface types for a component object class (coclass) or an inherited interface.
ITypeInfo::GetTypeAttr | Retrieves a TYPEATTR structure that contains the type description attributes.
ITypeInfo::GetTypeComp | Retrieves the ITypeComp interface for the type description, which enables a client compiler to bind to the type description’s members.
ITypeInfo::GetVarDesc | Retrieves a VARDESC structure that describes the specified variable.
ITypeInfo::Invoke | Invokes a method or accesses a property of an object that implements the interface indicated by the type description.
ITypeInfo::ReleaseFuncDesc | Releases a FUNCDESC previously returned by GetFuncDesc.
ITypeInfo::ReleaseTypeAttr | Releases a TYPEATTR previously returned by GetTypeAttr.
ITypeInfo::ReleaseVarDesc | Releases a VARDESC previously returned by GetVarDesc.


ITypeInfo::AddressOfMember

This method retrieves the addresses of static functions or variables, such as those defined in a dynamic-link library (DLL).

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT AddressOfMember( MEMBERID memid,
INVOKEKIND invKind, VOID FAR* FAR* ppv );

Parameters

memid
Member identifier of the static member whose address is to be retrieved. The member identifier is defined by the DISPID.
invKind
Specifies whether the member is a property, and if so, what kind.
ppv
On return, pointer to a pointer to the static member.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_WRONGTYPEKIND | Type mismatch.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND | The element was not found.
TYPE_E_DLLFUNCTIONNOTFOUND | The function could not be found in the DLL.
TYPE_E_CANTLOADLIBRARY | The type library or DLL could not be loaded.

Remarks

The addresses are valid until the caller releases its reference to the type description. The invKind parameter can be ignored unless the address of a property function is being requested.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member identifier.


ITypeInfo::CreateInstance

This method creates a new instance of a type that describes a component object class (coclass).

At a Glance

Header file: | Oaidl.h
Windows CE Versions: | 2.0 and later

Syntax

HRESULT CreateInstance( IUnknown FAR* pUnkOuter, REFIID riid,
VOID FAR* FAR* ppvObj );

Parameters

pUnkOuter
Pointer to the controlling IUnknown. If NULL, then a stand-alone instance is created. If valid, then an aggregate object is created.
riid
Reference to an identifier for the interface that the caller will use to communicate with the resulting object.
ppvObj
On return, pointer to a pointer to an instance of the created object.

Return Value

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
TYPE_E_WRONGTYPEKIND | Type mismatch.
E_INVALIDARG | One or more of the parameters is invalid.
E_NOINTERFACE | OLE could not find an implementation of one or more required interfaces.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
Other return codes | Additional errors may be returned from CoCreateInstance.

Remarks

For types that describe a component object class (coclass), CreateInstance creates a new instance of the class. Usually, CreateInstance calls CoCreateInstance with the type description’s GUID.


ITypeInfo::GetContainingTypeLib

This method retrieves both the type library that contains a specific type description and the index of the type description within the type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetContainingTypeLib( ITypeLib FAR* FAR* ppTLib,
unsigned int FAR* pIndex );

Parameters

ppTLib
On return, pointer to the containing type library.
pIndex
On return, pointer to the index of the type description within the that contains type library.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_NOINTERFACE | OLE could not find an implementation of one or more required interfaces.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.


ITypeInfo::GetDllEntry

This method retrieves a description or specification of an entry point for a function in a dynamic-link library (DLL).

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDllEntry( MEMBERID memid, INVOKEKIND invKind,
BSTR FAR* pBstrDllName, BSTR FAR* pBstrName,
unsigned short FAR* pwOrdinal);

Parameters

memid
Identifier of the member function whose DLL entry description is to be returned.
invKind
Specifies the kind of member identified by memid. This is important for properties, because one memid can identify up to three separate functions.
pBstrDllName
If not NULL, the function sets pBstrDllName to a Unicode string that contains the name of the DLL.
pBstrName
If not NULL, the function sets lpbstrName to a Unicode string that contains the name of the entry point. If the entry point is specified by an ordinal, *lpbstrName is set to NULL.
pwOrdinal
If not NULL, and if the function is defined by an ordinal, then pwOrdinal is set to point to the ordinal.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
E_NOINTERFACE | OLE could not find an implementation of one or more required interfaces.
TYPE_E_ELEMENTNOTFOUND | The element was not found.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The caller passes in a member identifier, which represents the member function whose entry description is desired. If the function has a DLL entry point, the name of the DLL that contains the function, as well as its name or ordinal identifier, are placed in the passed-in pointers allocated by the caller. If there is no DLL entry point for the function, an error is returned.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member identifier.

The caller should use SysFreeString to free the BSTRs referenced by pBstrName and pBstrDllName.


ITypeInfo::GetDocumentation

This method retrieves the documentation string, name of the complete Help file name and path, and the context identifier for the Help topic for a specified type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDocumentation( MEMBERID memid,
BSTR FAR* pBstrName, BSTR FAR* pBstrDocString,
unsigned long FAR* pdwHelpContext, BSTR FAR* pBstrHelpFile );

Parameters

index
Index of the type description whose documentation is to be returned. If index is –1, then the documentation for the library itself is returned.
pBstrName
Returns a BSTR that contains the name of the specified item. If the caller does not need the item name, then pBstrName can be NULL.
pBstrDocString
Returns a BSTR that contains the documentation string for the specified item. If the caller does not need the documentation string, then pBstrDocString can be NULL.
pdwHelpContext
Returns the Help context identifier associated with the specified item. If the caller does not need the Help context identifier, then pdwHelpContext can be NULL.
pBstrHelpFile
Returns a BSTR that contains the fully qualified name of the Help file. If the caller does not need the Help file name, then pBstrHelpFile can be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND | The element was not found.

Remarks

The function GetDocumentation provides access to the documentation for the member specified by the memid parameter. If the passed-in memid is MEMBERID_NIL, then the documentation for the type description is returned.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member identifier.

The caller should free the BSTR parameters pBstrName, pBstrDocString, and pBstrHelpFile.

Example

for (i = 0; i < utypeinfoCount; i++)
{
    CHECKRESULT(ptlib->GetDocumentation(i, &bstrName, NULL, NULL, NULL));
.
.
.
    SysFreeString(bstrName);
}


ITypeInfo::GetFuncDesc

This method retrieves the FUNCDESC structure that contains information about a specified function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetFuncDesc( unsigned int index,
FUNCDESC FAR* FAR* ppFuncDesc );

Parameters

index
Index of the function whose description is to be returned. The index should be in the range of 0 to 1 less than the number of functions in this type.
ppFuncDesc
On return, pointer to a pointer to a FUNCDESC that describes the specified function.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

The function GetFuncDesc provides access to a FUNCDESC structure that describes the function with the specified index. The FUNCDESC should be freed with ITypeInfo::ReleaseFuncDesc. The number of functions in the type is one of the attributes contained in the TYPEATTR structure.

Example

CHECKRESULT(ptypeinfo->GetFuncDesc(i, &pfuncdesc));
idMember = pfuncdesc->elemdescFunc.ID;
CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL, NULL));
ptypeinfo->ReleaseFuncDesc(pfuncdesc);


ITypeInfo::GetIDsOfNames

This method maps between names and identifiers of members and parameters.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetIDsOfNames( OLECHAR FAR* FAR* rgszNames,
unsigned int cNames, MEMBERID FAR* pMemId );

Parameters

rgszNames
Passed-in pointer to an array of names to be mapped.
cNames
Count of the names to be mapped.
pMemId
Caller-allocated array in which name mappings are placed.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
DISP_E_UNKNOWNNAME | One or more of the names could not be found.
DISP_E_UNKNOWNLCID | The locale identifier (LCID) could not be found in the OLE DLLs.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The function GetIDsOfNames maps the name of a member (rgszNames[0]) and its parameters (rgszNames[1] ...rgszNames[cNames –1]) to the identifier of the member (rgid[0]), and to the IDs of the specified parameters (rgid[1] ... rgid[cNames –1]). The IDs of parameters are 0 for the first parameter in the member function’s parameter list, 1 for the second, and so on.

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member identifier.


ITypeInfo::GetImplTypeFlags

This method retrieves the IMPLTYPE flags for an interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetImplTypeFlags( unsigned int index, int* pImplTypeFlags);

Parameters

index
Index of the implemented interface or base interface for which to get the flags.
pImplTypeFlags
On return, pointer to the IMPLTYPEFLAGS enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The flags are associated with the act of inheritance, and not with the inherited interface.


ITypeInfo::GetMops

This method retrieves marshaling information.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetMops( MEMBERID memid, BSTR FAR* pBstrMops);

Parameters

memid
Member identifier that indicates which marshaling information is needed.
pBstrMops
On return, pointer to the opcode string used in marshaling the members of the structure described by the referenced type description, or returns NULL if there is no information to return.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND | The element was not found.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

If the passed-in member identifier is MEMBERID_NIL, the function returns the opcode string for marshaling the members of the structure described by the type description. Otherwise, it returns the opcode string for marshaling the function specified by the index.

If the type description inherits from another type description, this function recurses on the base type description, if necessary, to find the item with the requested member identifier.


ITypeInfo::GetNames

This method retrieves the variable with the specified member identifier, or the name of the function and parameter names corresponding to the specified function identifier.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetNames( MEMBERID memid, BSTR FAR* rgBstrNames,
unsigned int cMaxNames, unsigned int FAR* pcNames);

Parameters

memid
Identifier of the member whose name (or names) is to be returned.
rgBstrNames
Pointer to the caller-allocated array. On return, each of these lpcName elements is filled in to point to a BSTR that contains the name (or names) associated with the member.
cMaxNames
Length of the passed-in rgBstrNames array.
pcNames
On return, pointer to the number that represents the number of names in rgBstrNames array.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.
TYPE_E_ELEMENTNOTFOUND | The element was not found.

Remarks

The caller must release the returned BSTR array.

If the member identifier identifies a property that is implemented with property functions, the property name is returned.

For property get functions, the names of the function and its parameters are always returned.

For property put and put reference functions, the right side of the assignment is unnamed. If cMaxNamesis less than is required to return all of the names of the parameters of a function, then only the names of the first cMaxNames –1 parameters are returned. The names of the parameters are returned in the array in the same order that they appear elsewhere in the interface (for example, the same order in the parameter array associated with the FUNCDESC enumeration).

If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member identifier.


ITypeInfo::GetRefTypeInfo

This method retrieves the type descriptions referenced by a specified type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetRefTypeInfo( HREFTYPE hRefType,
ITypeInfo FAR* FAR* ppTInfo );

Parameters

hRefType
Handle to the referenced type description to be returned.
ppTInfo
Pointer to a pointer to the referenced type description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.
TYPE_E_ELEMENTNOTFOUND | The element was not found.
TYPE_E_REGISTRYACCESS | There was an error accessing the system registration database.
TYPE_E_LIBNOTREGISTERED | The type library was not found in the system registration database.

Remarks

On return, the second parameter contains a pointer to a pointer to a type description that is referenced by this type description. A type description must have a reference to each type description that occurs as the type of any of its variables, function parameters, or function return types. For example, if the type of a data member is a record type, the type description for that data member contains the hRefTypeof a referenced type description. To get a pointer to the type description, the reference is passed to GetRefTypeInfo.


ITypeInfo::GetRefTypeOfImplType

This method retrieves the type description of implemented interface types for a component object class (coclass) or an inherited interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetRefTypeOfImplType(unsigned int index,
HREFTYPE FAR* pRefType );

Parameters

index
Index of the implemented type whose handle is returned. The valid range is 0 to the cImplTypes member in the TYPEATTR structure.
pRefType
On return, pointer to a handle for the implemented interface (if any). This handle can be passed to ITypeInfo::GetRefTypeInfo to get the type description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
TYPE_E_ELEMENTNOTFOUND | Passed index is outside the range 0 to 1 less than the number of function descriptions.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

If the TKIND_DISPATCH type description is for a dual interface, the TKIND_INTERFACE type description can be obtained by calling GetRefTypeOfImplType with an index of –1, and by passing the returned pRefType handle to GetRefTypeInfo to retrieve the type information.


ITypeInfo::GetTypeAttr

This method retrieves a TYPEATTR structure that contains the type description attributes.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeAttr( TYPEATTR FAR* FAR* ppTypeAttr );

Parameters

ppTypeAttr
On return, pointer to a pointer to a structure that contains the attributes of this type description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

To free the TYPEATTR structure, use ITypeInfo::ReleaseTypeAttr.

Example

CHECKRESULT(ptypeinfoCur->GetTypeAttr(&ptypeattrCur));
.
.
.
ptypeinfoCur->ReleaseTypeAttr(ptypeattrCur);


ITypeInfo::GetTypeComp

This method retrieves the ITypeComp interface for the type description, which enables a client compiler to bind to the type description’s members.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeComp( ITypeComp FAR* FAR* ppTComp );

Parameters

ppTComp
Pointer to a pointer to the ITypeComp instance for this ITypeLib. A client compiler uses the methods in the ITypeComp interface to bind to types in ITypeLib, as well as to the global functions, variables, and constants defined in ITypeLib.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The Bind function of the returned TypeComp binds to global functions, variables, constants, enumerated values, and coclass members. The Bind function also binds the names of the TYPEKIND enumerations of TKIND_MODULE, TKIND_ENUM, and TKIND_COCLASS. These names shadow any global names defined within the type information. The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be directly bound to from ITypeComp without specifying the name of the module.

ITypeComp::Bind and ITypeComp::BindType accept only unqualified names. ITypeLib::GetTypeComp returns a pointer to the ITypeComp interface, which is then used to bind to global elements in the library. The names of some types (TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS) share the name space with variables, functions, constants, and enumerators.

If a member requires qualification to differentiate it from other items in the name space, GetTypeComp can be called successively for each qualifier in order to bind to the desired member. This allows programming language compilers to access members of modules, enumerations, and coclasses, even though the member can’t be bound to with a qualified name.


ITypeInfo::GetVarDesc

This method retrieves a VARDESC structure that describes the specified variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetVarDesc( unsigned int index,
VARDESC FAR* FAR* ppVarDesc );

Parameters

index
Index of the variable whose description is to be returned. The index should be in the range of 0 to 1 less than the number of variables in this type.
ppVarDesc
On return, pointer to a pointer to a VARDESC that describes the specified variable.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

To free the VARDESC structure, use ReleaseVarDesc.

Example

CHECKRESULT(ptypeinfo->GetVarDesc(i, &pvardesc));
idMember = pvardesc->memid;
CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL,
        NULL));
ptypeinfo->ReleaseVarDesc(pvardesc);


ITypeInfo::Invoke

This method invokes a method or accesses a property of an object that implements the interface indicated by the type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Invoke( VOID FAR* pvInstance, MEMBERID memid,
unsigned short wFlags, DISPPARAMS FAR* pDispParams,
VARIANT FAR* pVarResult, EXCEPINFO FAR* pExcepInfo,
unsigned int FAR* puArgErr );

Parameters

pvInstance
Pointer to an instance of the interface described by this type description.
memid
Identifier of the interface member.
wFlags
Flags that describe the context of the invoke call. It is one of the following values:
Value
Description
DISPATCH_METHOD | The member is accessed as a method. If there is ambiguity, both this and the DISPATCH_PROPERTYGET flag can be set.
DISPATCH_PROPERTYGET | The member is retrieved as a property or data member.
DISPATCH_PROPERTYPUT | The member is changed as a property or data member.
DISPATCH_PROPERTYPUTREF | The member is changed by using a reference assignment, rather than a value assignment. This value is only valid when the property accepts a reference to an object.

pDispParams
Pointer to a structure that contains an array of parameters, an array of DISPIDs for named parameters, and counts of the number of elements in each array.
pVarResult
Should be NULL if the caller does not expect any result. Otherwise, it should be a pointer to the location at which the result is to be stored. If wFlags specifies DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF, pVarResultis ignored.
pExcepInfo
Points to an exception information structure, which is filled in only if DISP_E_EXCEPTION is returned. If pExcepInfois NULL on input, only an HRESULT error is returned.
puArgErr
If Invoke returns DISP_E_TYPEMISMATCH, puArgErr indicates the index (within rgvarg) of the parameter with incorrect type. If more than one parameter returns an error, puArgErr indicates only the first parameter with an error. Arguments in pDispParams->rgvarg appear in reverse order, so the first parameter is the one having the highest index in the array. Cannot be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | One or more of the parameters is invalid.
DISP_E_EXCEPTION | The member being invoked has returned an error HRESULT. If the member implements IErrorInfo, details are available in the error object. Otherwise, the pExcepInfo parameter contains details.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_REGISTRYACCESS | There was an error accessing the system registration database.
TYPE_E_LIBNOTREGISTERED | The type library was not found in the system registration database.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.
TYPE_E_ELEMENTNOTFOUND | The element was not found.
TYPE_E_BADMODULEKIND | The module does not support Invoke.
Other return codes | Any of the IDispatch::Invoke errors may also be returned.

Remarks

Use the function ITypeInfo::Invoke to access a member of an object or invoke a method that implements the interface described by this type description. For objects that support the IDispatch interface, you can use Invoke to implement IDispatch::Invoke.

ITypeInfo::Invoke takes a pointer to an instance of the class. Otherwise, its parameters are the same as IDispatch::Invoke, except that ITypeInfo::Invoke omits the refiid and lcid parameters. When called, ITypeInfo::Invoke performs the actions described by the IDispatch::Invoke parameters on the specified instance.

For VTBL interface members, ITypeInfo::Invoke passes the LCID of the type information into parameters tagged with the lcid attribute, and the returned value into the retval attribute.

If the type description inherits from another type description, this function recurses on the base type description to find the item with the requested member identifier.


ITypeInfo::ReleaseFuncDesc

This method releases a FUNCDESC previously returned by GetFuncDesc.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ReleaseFuncDesc( FUNCDESC FAR* pFuncDesc );

Parameter

pFuncDesc
Pointer to the FUNCDESC to be freed.

Remarks

The function ReleaseFuncDesc releases a FUNCDESC that was returned through ITypeInfo::GetFuncDesc.

Example

ptypeinfoCur->ReleaseFuncDesc(pfuncdesc);


ITypeInfo::ReleaseTypeAttr

This method releases a TYPEATTR previously returned by GetTypeAttr.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ReleaseTypeAttr( TYPEATTR FAR* pTypeAttr );

Parameter

pTypeAttr
Pointer to the TYPEATTR to be freed.

Remarks

The function ReleaseTypeAttr releases a TYPEATTR that was returned through ITypeInfo::GetTypeAttr.


ITypeInfo::ReleaseVarDesc

This method releases a VARDESC previously returned by GetVarDesc.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ReleaseVarDesc( VARDESC FAR* pVarDesc );

Parameter

pVarDesc
Pointer to the VARDESC to be freed.

Remarks

ReleaseVarDesc releases a VARDESC that was returned through ITypeInfo::GetVarDesc.

Example

VARDESC        FAR *pVarDesc;
CHECKRESULT(ptypeinfo->GetVarDesc(i, &pvardesc));
idMember = pvardesc->memid;
CHECKRESULT(ptypeinfo->GetDocumentation(idMember, &bstrName, NULL, NULL,     NULL));
ptypeinfo->ReleaseVarDesc(pvardesc);


ITypeInfo2 : IUnknown

This interface allows ITypeInfo to cast to an ITypeInfo2 in performance-sensitive cases. An ITypeInfo can be cast to an ITypeInfo2 instead of using the calls QueryInterface and Release. This casting procedure is not compatible with Windows 95 or Windows NT version 3.51.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Method
Description
ITypeInfo2::GetTypeKind | Returns the TYPEKIND enumeration quickly, without doing any allocations.
ITypeInfo2::GetTypeFlags | Returns the TYPEFLAGS quickly, without doing any allocations.
ITypeInfo2::GetFuncIndexOfMemId | Binds to a specific member based on a known dispatch identifier (DISPID).
ITypeInfo2::GetVarIndexOfMemId | Binds to a specific member based on a known dispatch identifier (DISPID).
ITypeInfo2::GetCustData | Gets the custom data.
ITypeInfo2::GetAllCustData | Gets all custom data items for the library.
ITypeInfo2::GetFuncCustData | Gets the custom data from the specified function.
ITypeInfo2::GetAllFuncCustData | Gets all of the custom data from the specified function.
ITypeInfo2::GetParamCustData | Gets the specified custom data parameter.
ITypeInfo2::GetAllParamCustData | Gets all of the custom data for the specified parameter.
ITypeInfo2::GetVarCustData | Gets the variable for the custom data.
ITypeInfo2::GetAllVarCustData | Gets all of the custom data for the specified variable.
ITypeInfo2::GetImplTypeCustData | Gets the implementation type of the custom data.
ITypeInfo2::GetAllImplTypeCustData | Gets all of the custom data for the specified implementation type.
ITypeInfo2::GetDocumentation2 | Retrieves the documentation string and other Help-related information.


ITypeInfo2::GetAllCustData

This method gets all custom data items for the library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAllCustData( CUSTDATA *pCustData );

Parameters

pCustData
Returns a pointer to CUSTDATA, which holds all custom data items.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Remarks

After the call, the caller needs to release memory used to hold the custom data item by calling ClearCustData.


ITypeInfo2::GetAllFuncCustData

This method gets all of the custom data from the specified function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAllFuncCustData( unsigned int index,
CUSTDATA *pCustData );

Parameters

index
Index of the function for which to get the custom data.
pCustData
Returns a pointer to CUSTDATA, which holds all custom data items.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Remarks

After the call, the caller needs to release memory used to hold the custom data item by calling ClearCustData.


ITypeInfo2::GetAllImplTypeCustData

This method gets all of the custom data for the specified implementation type.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAllImplTypeCustData( unsigned int index,
CUSTDATA *pCustData );

Parameters

index
Index of the implementation type for the custom data.
pCustData
Returns a pointer to CUSTDATA, which holds all custom data items.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetAllParamCustData

This method gets all of the custom data for the specified parameter.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAllParamCustData( unsigned int indexFunc,
unsigned int indexParam, CUSTDATA *pCustData );

Parameters

indexFunc
Index of the function for which to get the custom data.
IndexParam
Index of the parameter of this function for which to get the custom data.
pCustData
Returns a pointer to CUSTDATA, which holds all custom data items.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetAllVarCustData

This method gets all of the custom data for the specified variable.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAllVarCustData( unsigned int index, CUSTDATA *pCustData );

Parameters

index
Index of the variable for which to get the custom data.
pCustData
Returns a pointer to CUSTDATA, which holds all custom data items.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetCustData

This method gets the custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetCustData( REFGUID guid, VARIANT *pVarVal );

Parameters

guid
Globbaly unique identifier (GUID) used to identify the data.
pVarVal
Pointer to where to put the retrieved data.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetDocumentation2

This method retrieves the documentation string and other Help-related information.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDocumentation2( [in] MEMID memid, [in] LCID lcid,
[out] BSTR FAR* pbstrHelpString,
[out] unsigned long FAR* pdwHelpStringContext,
BSTR FAR* pbstrHelpStringDll );

Parameters

memid
Member identifier for the type description.
lcid
Locale identifier (LCID).
pbstrHelpString
Returns a pointer to a BSTR that contains the name of the specified item. If the caller does not need the item name, then pbstrHelpString can be NULL.
pdwHelpStringContext
Returns a pointer to the Help localization context. If the caller does not need the Help context, it can be NULL.
pbstrHelpStringDll
Returns a pointer to a BSTR that contains the fully qualified name of the file that contains the DLL used for Help file. If the caller does not need the file name, it can be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND | The element was not found.

Remarks

Gets information at the type information level (about the type information and its members). The caller should free the BSTR parameters.

This function will call _DLLGetDocumentation in the specified DLL to retrieve the desired Help string, if there is a Help string context for this item. If no Help string context exists or an error occurs, then it will defer to the GetDocumentation method and return the associated documentation string.


ITypeInfo2::GetFuncCustData

This method gets the custom data from the specified function.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetFuncCustData( unsigned int index, REFGUID guid,
VARIANT *pVarVal );

Parameters

index
Index of the function for which to get the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to where to put the data.


ITypeInfo2::GetFuncIndexOfMemId

This method binds to a specific member based on a known dispatch identifier (DISPID)

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetFuncIndexOfMemId(MEMBERID memid,
INVOKEKIND invKind, unsigned int *pFuncIndex );

Parameters

memid
Member identifier.
invKind
Invoke kind.
pFuncIndex
Returns a pointer to the index to the function.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Example

ITypeInfo2::GetFuncIndexOfMemId(
MEMID memid,
INVOKEKIND invKind,
UINT * pfuncIndex)


ITypeInfo2::GetImplTypeCustData

This method gets the implementation type of the custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetImplTypeCustData( unsigned int index, REFGUID guid,
VARIANT *pVarVal);

Parameters

index
Index of the implementation type for the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to where to put the retrieved data.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetParamCustData

This method gets the specified custom data parameter.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetParamCustData( unsigned int indexFunc,
unsigned int indexParam, REFGUID guid, VARIANT *pVarVal );

Parameters

indexFunc
Index of the function for which to get the custom data.
IndexParam
Index of the parameter of this function for which to get the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to where to put the retrieved data.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetTypeFlags

This method returns the TYPEFLAGS quickly, without doing any allocations.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeFlags( unsigned long *pTypeFlags );

Parameters

pTypeFlags
Pointer to a TYPEFLAG.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Example

HRESULT ITypeInfo2::GetTypeFlags(DWORD * pTypeFlags)


ITypeInfo2::GetTypeKind

This method returns the TYPEKIND enumeration quickly, without doing any allocations.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeKind( TYPEKIND *pTypeKind );

Parameters

pTypeKind
Pointer to a TYPEKIND enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Example

HRESULT ITypeInfo2::GetTypeKind(TYPEKIND * ptypekind)


ITypeInfo2::GetVarCustData

This method gets the variable for the custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetVarCustData( unsigned int index, REFGUID guid,
VARIANT *pVarVal );

Parameters

index
Index of the variable for which to get the custom data.
guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to where to put the retrieved data.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeInfo2::GetVarIndexOfMemId

This method binds to a specific member based on a known dispatch identifier (DISPID).

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetVarIndexOfMemId( MEMBERID memid,
unsigned int *pVarIndex);

Parameters

memid
Member identifier.
pVarIndex
Returns a pointer to the index.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Example

ITypeInfo2::GetVarIndexOfMemId(MEMID memid, UINT * pvarIndex)


ITypeLib : IUnknown

This interface provides methods for accessing a library of type descriptions.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The data that describes a set of objects is stored in a type library. A type library can be a stand-alone binary file (.tlb), a resource in a dynamic link library or executable file (.dll or .exe), or part of a compound document file.

Implemented by
Used by
Header file name
Oleaut32.dll (32-bit systems)

Typelib.dll (16-bit systems)

 Tools that need to access the descriptions of objects contained in type libraries. Oleauto.h

Dispatch.h

The system registry contains a list of all the installed type libraries.

The ITypeLib interface provides methods for accessing a library of type descriptions. This interface supports the following:

  • Generalized containment for type information. ITypeLib allows iteration over the type descriptions contained in the library.
  • Global functions and data. A type library can contain descriptions of a set of modules, each of which is the equivalent of a C or C++ source file that exports data and functions. The type library supports compiling references to the exported data and functions.
  • General information, including a user-readable name for the library and help for the library as a whole.
Method
Description
ITypeLib::FindName | Finds occurrences of a type description in a type library. This may be used to verify that a name exists in a type library.
ITypeLib::GetDocumentation | Retrieves the library’s documentation string, the complete Help file name and path, and the context identifier for the library Help topic.
ITypeLib::GetLibAttr | Retrieves the structure that contains the library’s attributes.
ITypeLib::GetTypeComp | Retrieves a pointer to the ITypeComp for a type library. This enables a client compiler to bind to the library’s types, variables, constants, and global functions.
ITypeLib::GetTypeInfo | Retrieves the specified type description in the library.
ITypeLib::GetTypeInfoCount | Retrieves the number of type descriptions in the library.
ITypeLib::GetTypeInfoOfGuid | Retrieves the type description that corresponds to the specified globally unique identifier (GUID).
ITypeLib::GetTypeInfoType | Retrieves the type of a type description.
ITypeLib::IsName | Indicates whether a passed-in string contains the name of a type or a member described in the library.
ITypeLib::ReleaseTLibAttr | Releases the TLIBATTR originally obtained from ITypeLib::GetLibAttr.


ITypeLib::FindName

This method finds occurrences of a type description in a type library. This may be used to verify that a name exists in a type library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT FindName( OLECHAR FAR* szNameBuf,
unsigned long lHashVal, ITypeInfo FAR* FAR* ppTInfo,
MEMBERID FAR* rgMemId, unsigned int FAR* pcFound );

Parameters

szNameBuf
Null-terminated string that contains the name to search for.
lHashVal
Hash value to speed up the search, computed by the LHashValOfNameSys function. If lHashVal = 0, a value is computed.
ppTInfo
On return, an array of pointers to the type descriptions that contain the name specified in szNameBuf. Cannot be NULL.
rgMemId
Array of the MEMBERIDs of the found items; rgMemId[i] is the MEMBERID that indexes into the type description specified by ppTInfo[i]. Cannot be NULL.
pcFound
On entry, indicates how many instances to look for. For example, *pcFound = 1 can be called to find the first occurrence. The search stops when one is found.

On exit, indicates the number of instances that were found. If the in and out values of *pcFound are identical, there may be more type descriptions that contain the name.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_CANTLOADLIBRARY | The library or .dll file could not be loaded.
TYPE_E_ELEMENTNOTFOUND | The element was not found.

Remarks

Passing *pcFound = n indicates that there is enough room in the ppTInfo and rgMemId arrays for n (ptinfo, memid) pairs. The function returns MEMBERID_NIL in rgMemId[i], if the name in szNameBuf is the name of the type information in ppTInfo[i].


ITypeLib::GetDocumentation

This method retrieves the library’s documentation string, the complete Help file name and path, and the context identifier for the library Help topic.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDocumentation( int index, BSTR FAR* pBstrName,
BSTR FAR* pBstrDocString, unsigned long FAR* pdwHelpContext,
BSTR FAR* pBstrHelpFile );

Parameters

index
Index of the type description whose documentation is to be returned. I If index is–1, then the documentation for the library itself is returned.
pBstrName
Returns a BSTR that contains the name of the specified item. If the caller does not need the item name, then pBstrName can be NULL.
pBstrDocString
Returns a BSTR that contains the documentation string for the specified item. If the caller does not need the documentation string, then pBstrDocString can be NULL.
pdwHelpContext
Returns a pointer to the Help context identifier associated with the specified item. If the caller does not need the Help context identifier, then pdwHelpContext can be NULL.
pBstrHelpFile
Returns a pointer to a BSTR that contains the fully qualified name of the Help file. If the caller does not need the Help file name, then pBstrHelpFile can be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND | The element was not found.

Remarks

The caller should free the BSTR parameters pBstrName, pBstrDocString, and pBstrHelpFile.

Example

for (i = 0; i < utypeinfoCount; i++)
{
    CHECKRESULT(ptlib->GetDocumentation(i, &bstrName, NULL, NULL, NULL));
.
.
.
    SysFreeString(bstrName);
}


ITypeLib::GetLibAttr

This method retrieves the structure that contains the library’s attributes.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetLibAttr( TLIBATTR FAR* FAR* ppTLibAttrr);

Parameters

ppTLibAttrr
Pointer to a structure that contains the library’s attributes.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an unsupported format.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

Use ITypeLib::ReleaseTLibAttr to free the memory occupied by the TLIBATTR structure.


ITypeLib::GetTypeComp

This method retrieves a pointer to the ITypeComp for a type library. This enables a client compiler to bind to the library’s types, variables, constants, and global functions.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetLibAttr( ITypeComp FAR* FAR* ppTComp );

Parameters

ppTComp
Pointer to a pointer to the ITypeComp instance for this ITypeLib. A client compiler uses the methods in the ITypeComp interface to bind to types in ITypeLib, as well as to the global functions, variables, and constants defined in ITypeLib.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_WRONGTYPEKIND | Type mismatch.

Remarks

The Bind function of the returned TypeComp binds to global functions, variables, constants, enumerated values, and coclass members. The Bind function also binds the names of the TYPEKIND enumerations of TKIND_MODULE, TKIND_ENUM, and TKIND_COCLASS. These names shadow any global names defined within the type information. The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be directly bound to from ITypeComp without specifying the name of the module.

ITypeComp::Bind and ITypeComp::BindType accept only unqualified names. ITypeLib::GetTypeComp returns a pointer to the ITypeComp interface, which is then used to bind to global elements in the library. The names of some types (TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS) share the name space with variables, functions, constants, and enumerators.

If a member requires qualification to differentiate it from other items in the name space, GetTypeComp can be called successively for each qualifier in order to bind to the desired member. This allows programming language compilers to access members of modules, enumerations, and coclasses, even though the member can’t be bound to with a qualified name.


ITypeLib::GetTypeInfo

This method retrieves the specified type description in the library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeInfo( unsigned int index, ITypeInfo FAR* FAR* ppTInfo );

Parameters

index
Index of the ITypeInfo interface to be returned.
ppTInfo
If successful, returns a pointer to the pointer to the ITypeInfo interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
TYPE_E_ELEMENTNOTFOUND | The index parameter is outside the range of 0 to GetTypeInfoCount –1.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_REGISTRYACCESS | There was an error accessing the system registration database.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

For dual interfaces, ITypeLib::GetTypeInfo returns only the TKIND_DISPATCH type information. To get the TKIND_INTERFACE type information, ITypeInfo::GetRefTypeOfImplType can be called on the TKIND_DISPATCH type information, passing an index of –1. Then, the returned type information handle can be passed to ITypeInfo::GetRefTypeInfo.

Example

The following code example gets the TKIND_INTERFACE type information for a dual interface.

ptlib->GetTypeInfo((unsigned int) dwIndex, &ptypeinfoDisp);
ptypeinfoDisp->GetRefTypeOfImplType(-1, &phreftype);
ptypeinfoDisp->GetRefTypeInfo(phreftype, &ptypeinfoInt);


ITypeLib::GetTypeInfoCount

This method retrieves the number of type descriptions in the library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeInfoCount()

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_NOTIMPL | Failure.

Remarks

Returns the number of type descriptions in the type library.


ITypeLib::GetTypeInfoOfGuid

This method retrieves the type description that corresponds to the specified globally unique identifier (GUID).

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeInfoOfGuid( REFGUID guid,
ITypeInfo FAR* FAR* ppTinfo );

Parameters

guid
GUID of the type description.
ppTinfo
Pointer to a pointer to the ITypeInfo interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
TYPE_E_ELEMENTNOTFOUND | No type description was found in the library with the specified GUID.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_REGISTRYACCESS | There was an error accessing the system registration database.
TYPE_E_INVALIDSTATE | The type library could not be opened.


ITypeLib::GetTypeInfoType

This method retrieves the type of a type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetTypeInfoType( unsigned int index, TYPEKIND FAR* pTKind );

Parameters

index
Index of the type description within the type library.
pTKind
Pointer to the TYPEKIND enumeration for the type description.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
TYPE_E_ELEMENTNOTFOUND | Index is outside the range of 0 to GetTypeInfoCount –1.


ITypeLib::IsName

This method indicates whether a passed-in string contains the name of a type or a member described in the library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT IsName( OLECHAR FAR* szNameBuf, unsigned long lHashVal, BOOL pfName );

Parameters

szNameBuf
Null-terminated string to test. If IsName is successful, szNameBuf is modified to match the case (capitalization) found in the type library.
lHashVal
Hash value of szNameBuf.
pfName
On return, pointer to a Boolean value that is set to TRUE if szNameBuf was found in the type library, or set to FALSE otherwise.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVDATAREAD | Invalid data.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.


ITypeLib::ReleaseTLibAttr

This method releases the TLIBATTR originally obtained from ITypeLib::GetLibAttr.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT ReleaseTLibAttr( TLIBATTR FAR* pTLibAttr );

Parameters

pTLibAttr
Pointer to the TLIBATTR to be freed.

Remarks

Releases the specified TLIBATTR. This TLIBATTR was previously obtained with a call to GetTypeLib::GetLibAttr.


ITypeLib2 : ITypeLib

This interface inherits from the ITypeLib interface. This allows ITypeLib to cast to an ITypeLib2 in performance-sensitive cases, rather than perform extra QueryInterface and Release calls. This casting procedure is not compatible with Windows 95 or Windows NT version 3.51.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

The ITypeLib2 interface inherits from the ITypeLib interface. This allows ITypeLib to cast to an ITypeLib2 in performance-sensitive cases, rather than perform extra QueryInterface and Release calls.

Example

DECLARE_INTERFACE_(ITypeLib2, ITypeLib)
{
BEGIN_INTERFACE
Method
Desription
ITypeLib2::GetCustData | Gets the custom data.
ITypeLib2::GetDocumentation2 | Retrieves the library’s documentation string, the complete Help file name and path, and the context identifier for the library help topic.
ITypeLib2::GetLibStatistics | Returns statistics about a type library that are required for efficient sizing of hash tables.
ITypeLib2::GetAllCustData | Gets all custom data items for the library.


ITypeLib2::GetAllCustData

This gets all custom data items for the library.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAllCustData( CUSTDATA *pCustData );

Parameters

pCustData
Returns a pointer to CUSTDATA, which holds all custom data items.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Remarks

After the call, the caller needs to release memory used to hold the custom data item by calling ClearCustData.


ITypeLib2::GetCustData

This method gets the custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetCustData( REFGUID guid, VARIANT *pVarVal);

Parameters

guid
Globally unique identifier (GUID) used to identify the data.
pVarVal
Pointer to where to put the retrieved data.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.


ITypeLib2::GetDocumentation2

This method retrieves the library’s documentation string, the complete Help file name and path, the localization context to use, and the context identifier for the library Help topic.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetDocumentation2( [in] int index, [in] LCID lcid,
[out] BSTR FAR* pbstrHelpString,
[out] unsigned long FAR* pdwHelpStringContext,
BSTR FAR* pbstrHelpStringDll );

Parameters

index
Index of the type description whose documentation is to be returned; if index is –1, then the documentation for the library is returned.
lcid
Locale identifier.
pbstrHelpString
Returns a pointer to a BSTR that contains the name of the specified item. If the caller does not need the item name, then pbstrHelpString can be NULL.
pdwHelpStringContext
Returns a pointer to the Help localization context. If the caller does not need the Help context, then it can be NULL.
pbstrHelpStringDll
Returns a pointer to a BSTR that contains the fully qualified name of the file that contains the DLL used for Help file. If the caller does not need the file name, then it can be NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
STG_E_INSUFFICIENTMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_ELEMENTNOTFOUND | The element was not found.

Remarks

Gets information at the type library level. The caller should free the BSTR parameters.

This function will call _DLLGetDocumentation in the specified DLL to retrieve the desired Help string, if there is a Help string context for this item. If no Help string context exists or an error occurs, then it will defer to the GetDocumentation method and return the associated documentation string.


ITypeLib2::GetLibStatistics

This method returns statistics about a type library that are required for efficient sizing of hash tables.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetLibStatistics( unsigned long* pcUniqueNames,
unsigned long* pcchUniqueNames);

Parameters

pcUniqueNames
Returns a pointer to a count of unique names. If the caller does not need this information, set to NULL.
pcchUniqueNames
Returns a pointer to a change in the count of unique names.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the parameters is invalid.

Example

ITypeLib2::GetLibStatistics(DWORD *pcUniqueNames, DWORD * pcchUniqueNames)


IUnknown

This interface enables clients to get pointers to other interfaces on a specified object through the IUnknown::QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other COM interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the Vtable for every interface.

At a Glance

Header file: | Unknown.h
Windows CE versions: | 1.0 and later

Methods
Description
IUnknown::QueryInterface | Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.
IUnknown::AddRef | Increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a specified object.
IUnknown::Release | Decrements the reference count for the calling interface on a object. If the reference count on the object falls to 0, the object is freed from memory.


IUnknown::AddRef

This method increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a specified object.

At a Glance

Header file: | Unknown.h
Windows CE versions: | 1.0 and later

Syntax

ULONG AddRef( void );

Return Value

Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because, in certain situations, the value may be unstable.

Remarks

Objects use a reference counting mechanism to ensure that the lifetime of the object includes the lifetime of references to it. You use IUnknown::AddRef to stabilize a copy of an interface pointer. It can also be called when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling IUnknown::Release.

Objects must be able to maintain (231) –1 outstanding pointer references. Therefore, the internal reference counter that IUnknown::AddRef maintains must be a 32-bit unsigned integer.

Notes to Callers

Call this function for every new copy of an interface pointer that you make. For example, if you are passing a copy of a pointer back from a function, you must call IUnknown::AddRef on that pointer. You must also call IUnknown::AddRef on a pointer before passing it as an in-out parameter to a function; the function will call IUnknown::Release before copying the out-value on top of it.

See Also

IUnknown::Release


IUnknown::QueryInterface

This method returns a pointer to a specified interface on an object to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

At a Glance

Header file: | Unknown.h
Windows CE versions: | 1.0 and later

Syntax

HRESULT QueryInterface( REFIID iid, void ** ppvObject );

Parameters

iid
[in] Identifier of the interface being requested.
ppvObject
[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObject contains the requested interface pointer to the object. If the object does not support the interface specified in iid, *ppvObject is set to NULL.

Return Value

S_OK indicates that the interface is supported. E_NOINTERFACE indicates that the interface is not supported.

Remarks

The QueryInterface method gives a client access to other interfaces on an object.

For any one object, a specific query for the IUnknown interface on any of the object's interfaces must always return the same pointer value. This allows a client to determine whether two pointers point to the same component by calling QueryInterface on both and comparing the results. It is specifically not the case that queries for interfaces (even the same interface through the same pointer) must return the same pointer value.

There are four requirements for implementations of QueryInterface (In these cases, "must succeed" means "must succeed barring catastrophic failure."):

  • The set of interfaces accessible on an object through IUnknown::QueryInterface must be static, not dynamic. This means that if a call to QueryInterface for a pointer to a specified interface succeeds the first time, it must succeed again, and if it fails the first time, it must fail on all subsequent queries.
  • It must be symmetric—if a client holds a pointer to an interface on an object, and queries for that interface, the call must succeed.
  • It must be reflexive—if a client holding a pointer to one interface queries successfully for another, a query through the obtained pointer for the first interface must succeed.
  • It must be transitive—if a client holding a pointer to one interface queries successfully for a second, and through that pointer queries successfully for a third interface, a query for the first interface through the pointer for the third interface must succeed.


IUnknown::Release

This method decrements the reference count for the calling interface on a object. If the reference count on the object falls to 0, the object is freed from memory.

At a Glance

Header file: | Unknown.h
Windows CE versions: | 1.0 and later

Syntax

ULONG Release( void );

Return Value

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

If IUnknown::AddRef has been called on this object's interface n times and this is the n+1th call to IUnknown::Release, the implementation of IUnknown::AddRef must cause the interface pointer to free itself. When the released pointer is the only existing reference to an object (whether the object supports single or multiple interfaces), the implementation must free the object.

Aggregation of objects restricts the ability to recover interface pointers.

Notes to Callers

Call this function when you no longer need to use an interface pointer. If you are writing a function that takes an in-out parameter, call IUnknown::Release on the pointer you are passing in before copying the out-value on top of it.

See Also

IUnknown::AddRef


IViewObject : IUnknown

This interface enables an object to display itself directly without passing a data object to the caller. In addition, this interface can create and manage a connection with an advise sink so the caller can be notified of changes in the view object.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

The IViewObject interface enables an object to display itself directly without passing a data object to the caller. In addition, this interface can create and manage a connection with an advise sink so the caller can be notified of changes in the view object.

The caller can request specific representations and specific target devices. For example, a caller can ask for either an object’s content or an iconic representation. Also, the caller can ask the object to compose a picture for a target device that is independent of the drawing device context. As a result, the picture can be composed for one target device and drawn on another device context. For example, to provide a print preview operation, you can compose the drawing for a printer target device but actually draw the representation on the display.

The IViewObject interface is similar to IDataObject; except that IViewObject places a representation of the data onto a device context while IDataObject places the representation onto a transfer medium.

Unlike most other interfaces, IViewObject cannot be marshaled to another process. This is because device contexts are only effective in the context of one process.

When to Implement

Object handlers and in-process servers that manage their own presentations implement IViewObject for use by compound document containers. OLE provides an IViewObject implementation for its default object handler’s cache.

When to Use

You call IViewObject from a container application if you need to draw a contained object on a specific device context. For example, if you want to print the object to a printer, you call the Draw method in the IViewObject interface.

Method
Description
IViewObject::Draw | Draws a representation of an object onto the specified device context.
IViewObject::Freeze | Freezes a certain aspect of the object’s presentation so that it does not change until the IViewObject::Unfreeze method is called.
IViewObject::GetAdvise | Retrieves the existing advisory connection on the object if there is one and returns the parameters used in the most recent call to the IViewObject::SetAdvise method.
IViewObject::GetColorSet | Returns the logical palette that the object uses for drawing in its IViewObject::Draw method with the corresponding parameters.
IViewObject::SetAdvise | Establishes a connection between the view object and an advise sink so that the advise sink can be notified about changes in the object’s view.
IViewObject::Unfreeze | Releases a previously frozen drawing.


IViewObject::Draw

This method draws a representation of an object onto the specified device context.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Draw( DWORD dwAspect, LONG lindex, void * pvAspet,
DVTARGETDEVICE * ptd, HDC hicTargetDev, HDC hdcDraw,
const LPRECTL lprcBounds, const LPRECTL lprcWBounds,
BOOL (*) (DWORD) pfnContinue, DWORD dwContinue );

Parameters

dwAspect
[in] Specifies the aspect to be drawn, that is, how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT. Windowless objects allow only DVASPECT_CONTENT, DVASPECT_OPAQUE, and DVASPECT_TRANSPARENT.
lindex
[in] Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the dwAspect parameter. For more information, see the DVASPECT enumeration.
pvAspect
[in] Pointer to additional information in a DVASPECTINFO structure that enables drawing optimizations depending on the aspect specified. Note that newer objects and containers that support optimized drawing interfaces support this parameter as well. Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter.
ptd
[in] Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, the view should be rendered for the default target device (typically the display). A value other than NULL is interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, the ptd parameter points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value or it may be displayed in print preview mode if hicTargetDev is NULL.
hicTargetDev
[in] Information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device’s capabilities. If ptd is NULL; the object should ignore the value in the hicTargetDev parameter.
hdcDraw
[in] Device context on which to draw. For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the client coordinates of the that contains window. For a windowless object, the device context should be in the same state as the one normally passed by a WM_PAINT message.
lprcBounds
[in] Long pointer to a RECTL structure that specifies the rectangle on hdcDraw and in which the object should be drawn. This parameter controls the positioning and stretching of the object. This parameter should be NULL to draw a windowless in-place active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code. If the container passes a non-NULL value to a windowless object, the object should render the requested aspect into the specified device context and rectangle. A container can request this from a windowless object to render a second, non-active view of the object or to print the object.
lprcWBounds
[in] If hdcDraw is a metafile device context, this parameter is a long pointer to a RECTL structure specifying the bounding rectangle in the underlying metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same coordinate space.

If hdcDraw is not a metafile device context; lprcWBounds will be NULL.

pfnContinue
[in] Pointer to a callback function that the view object should call periodically during a lengthy drawing operation to determine whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT.
dwContinue
[in] Specifies a value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to an application-defined structure needed inside the callback function.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the values described in the following table.

Value
Description
S_OK | The object was drawn successfully.
OLE_E_BLANK | No data to draw from.
DRAW_E_ABORT | Draw operation aborted.
VIEW_E_DRAW | Error in drawing.
DV_E_LINDEX | Invalid value for lindex; currently only -1 is supported.
DV_E_DVASPECT | Invalid value for dwAspect.
OLE_E_INVALIDRECT | Invalid rectangle.

Remarks

A container application issues a call to IViewObject::Draw to create a representation of a contained object. This method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter.

There is a relationship between the dwDrawAspect value and the lprcbounds value. The lprcbounds value specifies the rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT_ICON, and DVASPECT_SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. Some objects might scale to fit while some might scale to fit but preserve the aspect ratio. In addition, some might scale so the drawing appears at full width, but the bottom is cropped. The container can use IOleObject::SetExtent to suggest a size, but it has no control over the rendering size. In the case of DVASPECT_CONTENT, the Draw implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in the lprcBounds parameter.

To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, rectangular or not, are required to maintain an origin and a rectangular extent. This allows the container to still consider all its embedded objects as rectangles and to pass them appropriate rendering rectangles in IViewObjectEx::Draw.

An object’s extent depends on the drawing aspect. For non-rectangular objects, the extent should be the size of a rectangle covering the entire aspect. By convention, the origin of an object is the top-left corner of the rectangle of the DVASPECT_CONTENT aspect. In other words, the origin always coincides with the top-left corner of the rectangle maintained by the object’s site, even for a non-rectangular object.

Note to Callers

The value of hicTargetDevice is typically an information context for the target device. However, it may be a full device context instead.

Note to Implementers

If you are writing an object handler (such as the default handler) that implements IViewObject::Draw by playing a metafile, you have to treat SetPaletteEntries metafile records in a special way because of Windows’ behavior. The Windows function PlayMetaFile sets these palette entries to the foreground. You must override this default by setting them to the background palette. Use EnumMetaFile to do this. Enhanced metafiles are always recorded with the background palette so there is no need to do it manually.


IViewObject::Freeze

This method freezes a certain aspect of the object’s presentation so that it does not change until the IViewObject::Unfreeze method is called.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Freeze( DWORD dwAspect, LONG lindex, void * pvAspect,
DWORD * pdwFreeze);

Parameters

dwAspect
[in] Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT.
lindex
[in] Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. For more information, see the DVASPECT enumeration.
pvAspect
[in] Pointer to additional information about the view of the object specified in dwAspect. Because none of the current aspects support additional information, pvAspect must always be NULL.
pdwFreeze
[out] Pointer to where an identifying DWORD key is returned. This unique key is later used to cancel the freeze by calling IViewObject::Unfreeze. This key is an index that the default cache uses to keep track of which object is frozen.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The presentation was successfully frozen.
VIEW_S_ALREADYFROZEN | Presentation has already been frozen. The value of pdwFreeze is the identifying key of the already frozen object.
OLE_E_BLANK | Presentation not in cache.
DV_E_LINDEX | Invalid value for lindex; currently; only -1 is supported.
DV_E_DVASPECT | Invalid value for dwAspect.

Remarks

The IViewObject::Freeze method causes the view object to freeze its drawn representation until a subsequent call to IViewObject::Unfreeze releases it. After calling IViewObject::Freeze, successive calls to IViewObject::Draw with the same parameters produce the same picture until IViewObject::Unfreeze is called.

IViewObject::Freeze is not part of the persistent state of the object and does not continue across unloads and reloads of the object.

The most common use of this method is for banded printing.

While in a frozen state, view notifications are not sent. Pending view notifications are deferred to the subsequent call to IViewObject::Unfreeze.


IViewObject::GetAdvise

This method retrieves the existing advisory connection on the object if there is one and returns the parameters used in the most recent call to the IViewObject::SetAdvise method.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetAdvise( DWORD * pdwAspect, DWORD * padvf,
IAdviseSink ** ppAdvSink);

Parameters

pdwAspect
[out] Pointer to where the dwAspect parameter from the previous SetAdvise call is returned. If this pointer is NULL, the caller does not permit this value to be returned.
padvf
[out] Pointer to where the advf parameter from the previous SetAdvise call is returned. If this pointer is NULL, the caller does not permit this value to be returned.
ppAdvSink
[out] Address of IAdviseSink* pointer variable that receives the interface pointer to the advise sink. The connection to this advise sink must have been established with a previous SetAdvise call, which provides the pAdvSink parameter. If *ppvAdvSink is NULL, there is no established advisory connection.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well S_OK, which indicates that the existing advisory connection was retrieved.


IViewObject::GetColorSet

This method returns the logical palette that the object uses for drawing in its IViewObject::Draw method with the corresponding parameters.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT GetColorSet( DWORD dwAspect, LONG lindex,
void * pvAspect, DVTARGETDEVICE * ptd, HDC hicTagetDev,
LOGPALETTE ** ppColorSet );

Parameters

dwAspect
[in] Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT.
lindex
[in] Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. For more information, see the DVASPECT enumeration.
pvAspect
[in] Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects support additional information, pvAspect must always be NULL.
ptd
[in] Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, the view should be rendered for the default target device (typically the display). A value other than NULL is interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, ptd points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value or it may be displayed in print preview mode if hicTargetDev is NULL.
hicTargetDev
[in] Information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device’s capabilities. If ptd is NULL, the object should ignore the hicTargetDev parameter.
ppColorSet
[out] Address of LOGPALETTE pointer variable that receives a pointer to the LOGPALETTE structure. The LOGPALETTE structure contains the set of colors that would be used if IViewObject::Draw were called with the same parameters for dwAspect, lindex, pvAspect, ptd, and hicTargetDev. If *ppColorSet is NULL, the object does not use a palette.

Return Values

This method supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the values described in the following table.

Value
Description
S_OK | The set of colors was returned successfully.
S_FALSE | Set of colors is empty or the object will not give out the information.
OLE_E_BLANK | No presentation data for object.
DV_E_LINDEX | Invalid value for lindex; currently only -1 is supported.
DV_E_DVASPECT | Invalid value for dwAspect.

Remarks

The IViewObject::GetColorSet method recursively queries any nested objects and returns a color set that represents the union of all colors requested. The color set eventually percolates to the top-level container that owns the window frame. This container can call IViewObject::GetColorSet on each of its embedded objects to obtain all the colors needed to draw the embedded objects. The container can use the color sets obtained in conjunction with other colors it needs for itself to set the overall color palette.

The OLE-provided implementation of IViewObject::GetColorSet looks at the data it has on hand to draw the picture. If CF_DIB is the drawing format, the palette found in the bitmap is used. For a regular bitmap, no color information is returned. If the drawing format is a metafile, the object handler enumerates the metafile looking for a CreatePalette metafile record. If one is found, the handler uses it as the color set.

Note to Implementers

Object applications that rely on the default handler for drawing and that use metafiles for doing so should provide a SetPaletteEntries record when they generate their metafiles. If a SetPaletteEntries record is not found, the default object handler returns S_FALSE.


IViewObject::SetAdvise

This method establishes a connection between the view object and an advise sink so that the advise sink can be notified about changes in the object’s view.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetAdvise( DWORD dwAspect, DWORD advf,
IAdviseSink * pAdvSink );

Parameters

dwAspect
[in] Specifies the view for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT.
advf
[in] Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only the following ADVF values are relevant for this method:
Value
Description
ADVF_ONLYONCE | Causes the advisory connection to be destroyed after the first notification is sent.
ADVF_PRIMEFIRST | Causes an initial notification to be sent regardless of whether data has changed from its current state.

For more information about the following values, see the ADVF enumeration.

Note that the ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData.

pAdvSink
[out] Pointer to the IAdviseSink interface on the advisory sink that is to be informed of changes. A NULL value deletes any existing advisory connection.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the values described in the following table.

Value
Description
S_OK | The advisory connection was successfully established.
OLE_E_ADVISENOTSUPPORTED | Advisory notifications are not supported.
DV_E_DVASPECT | Invalid value for dwAspect.

Remarks

A container application that is requesting a draw operation on a view object can also register with the IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when an object’s underlying data changes, you must call IDataObject::DAdvise separately.

To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL.

If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange method.

At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new one is registered.


IViewObject::Unfreeze

This method releases a previously frozen drawing.

At a Glance

Header file: | Oleidl.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT Unfreeze( DWORD dwFreeze );

Parameters

dwFreeze
[in] Contains a key previously returned from IViewObject::Freeze that determines which view object to unfreeze.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The drawing was unfrozen successfully.
OLE_E_NOCONNECTION | Error in the unfreezing process or the object is currently not frozen.


AbnormalTermination

This function indicates whether the try block of a try-finally statement terminated normally. This function can be called only from within the finally block of a try-finally statement.

At a Glance

Header file: | Excpt.h
Windows CE versions: | 1.0 and later

Syntax

BOOL AbnormalTermination(void);

Return Values

Nonzero indicates that the try block of the try-finally statement terminated abnormally. Zero indicates that the try block of the try-finally statement terminated normally.

Remarks

The Excpt.h file has to be explicitly included in order to use this function.

The try block terminates normally only if execution leaves the block sequentially after executing the last statement in the block. Statements (such as return, goto, continue, or break) that cause execution to leave the try block result in abnormal termination of the block. This is the case even if such a statement is the last statement in the try block.

Abnormal termination of a try block causes the system to search backward through all stack frames to determine whether any termination handlers must be called. This can result in the execution of hundreds of instructions, so it is important to avoid abnormal termination of a try block due to a return, goto, continue, or break statement. Note that these statements do not generate an exception, even though the termination is abnormal.

To avoid abnormal termination of the try-finally block, execution should continue to the end of the block. You can also execute the leave statement. The leave statement allows for immediate termination of the try block without causing abnormal termination and its performance penalty. Check your compiler documentation to determine if the leave statement is supported.


AddPropSheetPageProc

This application-defined callback function is used by a property sheet extension to add a page to a property sheet.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK AddPropSheetPageProc(HPROPSHEETPAGE hpage, LPARAM lParam);

Parameters

hpage
[in] Handle to a property sheet page.
lparam
[in] Application-defined 32-bit value.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

ExtensionPropSheetPageProc


BstrFromVector

This function returns a BSTR, assigning each element of the vector to a character in the BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT BstrFromVector(SAFEARRAY FAR* psa, BSTR FAR* pbstr);

Parameters

psa
Pointer to the vector to be converted to a BSTR.
pbstr
On exit, pointer to a BSTR, each character of which is assigned to an element from the vector.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | The psa parameter is NULL.
DISP_E_TYPEMISMATCH | The psa parameter is not a vector (not an array of bytes).


CeClearUserNotification

This function deletes a registered user notification that was created by a previous call to the CeSetUserNotification function. CeClearUserNotification does not operate on notifications that have occurred.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeClearUserNotification(HANDLE hNotification);

Parameters

hNotification
[in] Handle to the user notification to delete.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When writing applications for Windows CE version 1.0, use the PegClearUserNotification function.

See Also

CeSetUserNotification, CeHandleAppNotifications


CeCheckPassword (RAPI)

This function compares a specified string to the system password.. CeCheckPassword is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeCheckPassword( LPWSTR lpszPassword );

Parameters

lpszPassword
Pointer to a wide character string to compare with the system password.

Return Values

TRUE indicates that lpszPassword matches the system password. FALSE indicates failure.

Upon a RAPI related failure, the return value is FALSE.


CeCloseHandle (RAPI)

This function closes an open object handle. CeCloseHandle is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CeCloseHandle( HANDLE hObject );

Parameters

hObject
Handle to an open object.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError.

Remarks

The CeCloseHandle function closes handles to the following objects:

Communications device | Mutex
Database | Process
Event | Socket
File | Thread

CeCloseHandle invalidates the specified object handle, decrements the object’s handle count, and performs object retention checks. After the last handle to an object is closed, the object is removed from the system.

Closing a thread handle does not terminate the associated thread. To remove a thread object, you must terminate the thread, then close all handles to the thread.

Use CeCloseHandle to close handles returned by calls to the CeCreateFile function. Use CeFindClose to close handles returned by calls to the CeFindFirstFile function.

See Also

CeCreateFile, CeDeleteFile, CeFindClose, CeFindFirstFile


CeCopyFile (RAPI)

This function copies an existing file to a new file. CeCopyFile is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeCopyFile(LPCWSTR lpExistingFileName,
LPCWSTR lpNewFileName, BOOL bFailIfExists);

Parameters

lpExistingFileName
[in] Long pointer to a null-terminated string that specifies the name of an existing file.
lpNewFileName
[in] Long pointer to a null-terminated string that specifies the name of the new file.
bFailIfExists
[in] Boolean value that specifies how this operation is to proceed if a file of the same name as that indicated by lpNewFileName already exists. If bFailIfExists is TRUE and the new file already exists, the function fails. If bFailIfExists is FALSE and the new file already exists, the function overwrites the existing file and succeeds.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE version 1.0 and 1.01, use the PegCopyFile function.

See Also

CopyFile


CeCreateDatabase

This function creates a new database. This functions is obsolete. Applications instead should call CeCreateDatabaseEx.

A remote application interface (RAPI) version of this function exists, and it is also named CeCreateDatabase.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeCreateDatabase(LPWSTR lpszName, DWORD dwDbaseType, WORD wNumSortOrder, SORTORDERSPEC * rgSortSpecs);

Parameters

lpszName
[in] Long pointer to a null-terminated string that specifies the name for the new database. The name can have up to 32 characters, including the terminating null character. If the name is too long, it is truncated and the database is created.
dwDbaseType
[in] Specifies the type identifier for the database. This is an application-defined value that can be used for any application-defined purpose. For example, an application can use the type identifier to distinguish address book data from to-do list data or use the identifier during a database enumeration sequence. See CeFindFirstDatabase for details. The type identifier is not meant to be a unique identifier for the database. The system does not use this value.
wNumSortOrder
[in] Number of sort orders active in the database, with four being the maximum number. This parameter can be zero if no sort orders are active. If this value is zero, then the database engine creates a default sort order where "rgSortSpecs[0].propid = 0", and "rgSortSpecs[0].dwFlags = CEDB_SORT_GENERICORDER." This is only a placeholder and does not influence the insertion order of the records.
rgSortSpecs
[in] Pointer to an array of actual sort order descriptions. The size of the array is specified by wNumSortOrder. This parameter can be NULL if wNumSortOrder is zero.

Return Values

The object identifier of the newly created database—not a handle to an open database—indicates success. NULL indicates failure. To get extended error information within a Windows CE program, call GetLastError. Possible values for GetLastError include the following:

ERROR_DISK_FULL
The object store does not contain enough space to create the new database.
ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_DUP_NAME
A database already exists with the specified name.

Remarks

Because sort orders increase the system resources needed to perform each insert and delete operation, keep the number of sort orders to a minimum. However, try not to specify too few sort orders. If you do, you can use the CeSetDatabaseInfoEx function to change the sort order later; however, this function is even more expensive in terms of system resources.

See Also

CeCreateDatabaseEx, CeDeleteDatabaseEx, CeOidGetInfoEx, CeOpenDatabaseEx, CeSetDatabaseInfoEx, SORTORDERSPEC


CeCreateDatabase (RAPI)

This function creates a new database. CeCreateDatabase (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeCreateDatabase(LPWSTR lpszName, DWORD dwDbaseType, WORD wNumSortOrder, SORTORDERSPEC * rgSortSpecs);

Parameters

lpszName
[in] Long pointer to a null-terminated string that specifies the name for the new database. The name can have up to 32 characters, including the terminating null character. If the name is too long, it is truncated and the databases is created.
dwDbaseType
[in] Specifies the type identifier for the database. This is an application-defined value that can be used for any application-defined purpose. For example, an application can use the type identifier to distinguish address book data from to-do list data or use the identifier during a database enumeration sequence. See CeFindFirstDatabase for details. The type identifier is not meant to be a unique identifier for the database. The system does not use this value.
wNumSortOrder
[in] Number of sort orders active in the database, with four being the maximum number. This parameter can be zero if no sort orders are active. If this value is zero then the database engine creates a default sort order where "rgSortSpecs[0].propid = 0", and "rgSortSpecs[0].dwFlags = CEDB_SORT_GENERICORDER". This is only a placeholder and does not influence the insertion order of the records.
rgSortSpecs
[in] Pointer to an array of actual sort order descriptions. The size of the array is specified by wNumSortOrder. This parameter can be NULL if wNumSortOrder is zero.

Return Values

The object identifier of the newly created database — not a handle to an open database — indicates success. NULL indicates failure. To get extended error information within a RAPI program, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_DISK_FULL
The object store does not contain enough space to create the new database.
ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_DUP_NAME
A database already exists with the specified name.

Remarks

Because sort orders increase the system resources needed to perform each insert and delete operation, keep the number of sort orders to a minimum. However, try not to specify too few sort orders. If you do, you can use the CeSetDatabaseInfo (RAPI) function to change the sort order later; however, this function is even more expensive in terms of system resources.

See Also

CeCreateDatabase (RAPI), CeDeleteDatabase (RAPI), CeOidGetInfo (RAPI), CeOpenDatabase (RAPI), CeSetDatabaseInfo (RAPI), SORTORDERSPEC


CeCreateDatabaseEx

This function creates a new database in the object store or in a mounted volume. A remote application interface (RAPI) version of this function exists, and it is also named CeCreateDatabaseEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

CEOID CeCreateDatabaseEx( PCEGUID pceguid,
CEDBASEINFO * lpCEDBInfo );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.
lpCEDBInfo
[in] Pointer to the CEDBASEINFO structure that determines the name, type, sort orders, and characteristics of the database.

Return Values

The object identifier of the newly created database indicates success. NULL indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

ERROR_DISK_FULL
The destination source does not contain enough space to create the new database.
ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_DUP_NAME
A database already exists with the specified name.

Remarks

Because sort orders increase the system resources needed to perform each insert and delete operation, you should keep the number of sort orders to a minimum. Use the CeSetDatabaseInfoEx function to change the sort order later; however, this function is even more expensive in terms of system resources.

Together, a CEGUID and CEOID uniquely identifies a record or database in a database volume, including the object store.

See Also

CEDBASEINFO, CeDeleteDatabaseEx, CeOidGetInfoEx, CeOpenDatabaseEx, CeSetDatabaseInfoEx, CREATE_SYSTEMGUID, SORTORDERSPEC


CeCreateDirectory (RAPI)

This function creates a new directory. CeCreateDirectory is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeCreateDirectory(LPCWSTR lpPathName, LPSECURITY_ATTRIBUTES lpSecurityAttributes);

Parameters

lpPathName
[in] Long pointer to a null-terminated string that specifies the path of the directory to be created.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the CeCreateDirectory function parses paths.

An application can transcend this limit and send in paths longer than MAX_PATH characters by prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with CeCreateDirectory. However, each component in the path cannot be more than MAX_PATH characters long. This also works with Universal Naming Convention (UNC) names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private” and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps.”

lpSecurityAttributes
Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegCreateDirectory function.

See Also

CreateDirectory


CeCreateFile (RAPI)

This function creates, opens, or truncates a file, pipe, communications resource, disk device, or console. It returns a handle that can be used to access the object. It can also open and return a handle to a directory.

CeCreateFile is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HANDLE CeCreateFile(LPCWSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile);

Parameters

lpFileName
[in] Long pointer to a null-terminated string that specifies the name of the object (file, pipe, mailslot, communications resource, disk device, console, or directory) to create or open.

If lpFileName is a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CeCreateFile function parses paths.

You can use paths longer than MAX_PATH characters by prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing. This lets you use paths that are nearly 32,000 Unicode characters long. However, each component in the path cannot be more than MAX_PATH characters long. You must use fully-qualified paths with this technique. This also works with Universal Naming Convention (UNC) names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private” and “\\?\UNC\tom_1\hotstuff\coolapps” is seen as “\\tom_1\hotstuff\coolapps.”

dwDesiredAccess
[in] Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. This parameter can be any combination of the following values.
Value
Description
0 | Specifies device query access to the object. An application can query device attributes without accessing the device.
GENERIC_READ | Specifies read access to the object. Data can be read from the file and the file pointer can be moved. Combine with GENERIC_WRITE for read-write access.
GENERIC_WRITE | Specifies write access to the object. Data can be written to the file and the file pointer can be moved. Combine with GENERIC_READ for read-write access.

dwShareMode
[in] Specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

To share the object, use a combination of one or more of the following values:
Value
Description
FILE_SHARE_READ | Subsequent open operations on the object will succeed only if read access is requested.
FILE_SHARE_WRITE | Subsequent open operations on the object will succeed only if write access is requested.

lpSecurityAttributes
Ignored; set to NULL.
dwCreationDisposition
[in] Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. This parameter must be one of the following values:
Value
Description
CREATE_NEW | Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS | Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
OPEN_EXISTING | Opens the file. The function fails if the file does not exist.
See the Remarks section for a discussion of why you should use the OPEN_EXISTING flag if you are using the CeCreateFile function for devices, including the console.
OPEN_ALWAYS | Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDisposition were CREATE_NEW.
TRUNCATE_EXISTING | Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.

dwFlagsAndAttributes
Specifies the file attributes and flags for the file.

Any combination of the following attributes is acceptable for the dwFlagsAndAttributes parameter, except all other file attributes override FILE_ATTRIBUTE_NORMAL.
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file should be archived. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_HIDDEN | The file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_READONLY | The file is read only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM | The file is part of or is used exclusively by the operating system.
FILE_ATTRIBUTE_TEMPORARY | This attribute flag is not supported; however, if you have an installed file system that supports FILE_ATTRIBUTE_TEMPORARY, you can set or receive this flag. For example, the network redirector shows this flag if you are talking to a computer running Windows NT. Also, if you have a flash card inserted, the attributes of \StorageCard include the temporary bit.

Any combination of the following flags is acceptable for the dwFlagsAndAttributes parameter.
Value
Description
FILE_FLAG_WRITE_THROUGH | Instructs the system to write through any intermediate cache and go directly to disk. The system can still cache write operations, but cannot lazily flush them.
FILE_FLAG_OVERLAPPED | This flag is not supported; however, multiple reads/writes pending on a device at a time are allowed.
FILE_FLAG_RANDOM_ACCESS | Indicates that the file is accessed randomly. The system can use this as a hint to optimize file caching.
FILE_FLAG_SEQUENTIAL_SCAN | Indicates that the file is to be accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur; however, correct operation is still guaranteed.
Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.

hTemplateFile
[in] Ignored; as a result, CeCreateFile does not copy the extended attributes to the new file.

Return Values

An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastError returns zero. INVALID_HANDLE_VALUE indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError.

Remarks

When writing applications for Windows CE version 1.0 and 1.01, use the PegCreateFile function.

See Also

CreateFile


CeCreateProcess (RAPI)

This function is used to run a new program. It creates a new process and its primary thread. The new process executes the specified executable file.

CeCreateProcess is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeCreateProcess(LPCWSTR lpApplicationName, LPCWSTR lpCommandLine, LPSECURITY_ATTRIBUTES lpProcessAttributes, LPSECURITY_ATTRIBUTES lpThreadAttributes, BOOL bInheritHandles, DWORD dwCreationFlags, LPVOID lpEnvironment, LPWSTR lpCurrentDirectory, LPSTARTUPINFO lpStartupInfo, LPPROCESS_INFORMATION lpProcessInformation);

Parameters

lpApplicationName
[in] Long pointer to a null-terminated string that specifies the module to execute.

The string can specify the full path and filename of the module to execute or it can specify a partial name. In the case of a partial name, the function uses the current drive and current directory to complete the specification.

lpCommandLine
[in] Long pointer to a null-terminated string that specifies the command line to execute.

The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.

If lpCommandLine is non-NULL, lpApplicationName specifies the module to execute, and lpCommandLine specifies the command line. C runtime processes can use the argc and argv arguments.

If lpApplicationName does not contain an extension, .EXE is assumed. If the filename ends in a period (.) with no extension, or the filename contains a path, .EXE is not appended.

If the filename does not contain a directory path, Windows CE versions 2.10 and later search for the executable file in the following sequence:

  • The windows (\windows) directory
  • The root (\) directory of the device
  • An OEM-dependent directory
  • The OEM-defined shell (\ceshell) directory—Embedded Toolkit users only

Windows CE versions 1.0 through 2.01 search for the executable file in the following sequence:

  • The root of the PC Card if it exists
  • The windows (\windows) directory
  • The root (\ ) directory of the device
lpProcessAttributes
[in] Not supported; set to NULL.
lpThreadAttributes
[in] Not supported; set to NULL.
bInheritHandles
[in] Not supported; set to FALSE.
dwCreationFlags
[in] Specifies additional flags that control the priority class and the creation of the process. For Windows CE versions 1.0 and later, specify either zero or the following flag:
Value
Description
CREATE_SUSPENDED The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.

For Windows CE versions 2.0 and later, you can specify one of the following flags in addition to CREATE_SUSPENDED:
Value
Description
DEBUG_PROCESS | If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. Child processes of the new process are also debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
If you create a process with this flag set, only the calling thread—the thread that called CreateProcess—can call the WaitForDebugEvent function.
DEBUG_ONLY_THIS_PROCESS | If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. No child processes of the new process are debugged. The system notifies the debugger of all debug events that occur in the process being debugged.

lpEnvironment
[in] Not supported; set to NULL.
lpCurrentDirectory
[in] Not supported; set to NULL.
lpStartupInfo
[in] Not supported; set to NULL.
lpProcessInformation
[out] Long pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegCreateProcess function.

See Also

CreateProcess


CeDeleteDatabase

This function removes a database from the object store. This function is obsolete. Applications should call CeDeleteDatabaseEx instead.

A remote application interface (RAPI) version of this function exists, and it also named CeDeleteDatabase.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeDeleteDatabase(CEOID oidDbase);

Parameters

oidDbase
[in] Object identifier of the database to be deleted.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information within a Windows CE–based program, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_SHARING_VIOLATION
Another thread has an open handle to the database.

Remarks

The CeDeleteDatabase function deletes a database, including all records in the database.

See Also

CeDeletDatabaseEx, CeCreateDatabaseEx, CeOidGetInfoEx


CeDeleteDatabase (RAPI)

This function removes a database from the object store. CeCreateDatabase (RAPI) is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeDeleteDatabase(CEOID oidDbase);

Parameters

oidDbase
[in] Object identifier of the database to be deleted.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information within a RAPI program, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_SHARING_VIOLATION
Another thread has an open handle to the database.

Remarks

The CeDeleteDatabase (RAPI) function deletes a database, including all records in the database.

See Also

CeCreateDatabase (RAPI), CeOidGetInfo (RAPI)


CeDeleteDatabaseEx

This function removes a database from the object store or a mounted database volume. A remote application interface (RAPI) version of this function exists, and it is also named CeDeleteDatabaseEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeDeleteDatabaseEx( PCEGUID pceguid, PCEOID oidDbase );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.
oidDbase
[in] Object identifier of the database to be deleted.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

Value
Description
ERROR_INVALID_PARAMETER | A parameter was invalid.
ERROR_SHARING_VIOLATION | The file is in use.

See Also

CREATE_SYSTEMGUID, CeCreateDataBaseEx


CeDeleteDatabaseEx (RAPI)

This function removes a database from the object store or a mounted database volume. CeCreateDatabaseEx (RAPI) is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeDeleteDatabaseEx( PCEGUID pceguid, PCEOID oidDbase );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.
oidDbase
[in] Object identifier of the database to be deleted.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call CeGetLastError. Possible values for CeGetLastError include the following:

Value
Description
ERROR_INVALID_PARAMETER | A parameter was invalid.
ERROR_SHARING_VIOLATION | The file is in use.

See Also

CREATE_SYSTEMGUID, CeCreateDataBaseEx


CeDeleteFile (RAPI)

This function deletes an existing file from the object store. CeDeleteFile is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeDeleteFile(LPCWSTR lpFileName);

Parameters

lpFileName
[in] Long pointer to a null-terminated string that specifies the file to be deleted.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

The CeDeleteFile function fails if an application attempts to delete a file that is open for normal I/O or as a memory-mapped file.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegDeleteFile function.

See Also

DeleteFile


CeDeleteRecord

This function deletes a record from a database. A remote application interface (RAPI) version of this function exists, and it is also named CeDeleteRecord.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeDeleteRecord(HANDLE hDatabase, CEOID oidRecord);

Parameters

hDatabase
[in] Handle to the database from which the record is to be deleted. The database must be open. Open a database by calling the CeOpenDatabase function.
oidRecord
[in] Object identifier of the record to be deleted; this is obtained from CeOpenDatabase.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information within a Windows CE program, call GetLastError. GetLastError and may return ERROR_INVALID_PARAMETER if the handle or object identifier is invalid.

Remarks

If the CEDB_AUTOINCREMENT flag was not specified when the database was opened, and the record being deleted is the current record, the next read operation that uses the database handle will fail. If the CEDB_AUTOINCREMENT flag was specified, the system automatically moves the current seek pointer forward by one.

See Also

CeOpenDatabaseEx


CeDeleteRecord (RAPI)

This function deletes a record from a database. CeDeleteRecord (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeDeleteRecord(HANDLE hDatabase, CEOID oidRecord);

Parameters

hDatabase
[in] Handle to the database from which the record is to be deleted. The database must be open. Open a database by calling the CeOpenDatabase (RAPI) function.
oidRecord
[in] Object identifier of the record to be deleted; this is obtained from CeOpenDatabase (RAPI).

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information within a RAPI program, call CeGetLastError. CeGetLastError may return ERROR_INVALID_PARAMETER if the handle or object identifier is invalid.

Remarks

If the CEDB_AUTOINCREMENT flag was not specified when the database was opened, and the record being deleted is the current record, the next read operation that uses the database handle will fail. If the CEDB_AUTOINCREMENT flag was specified, the system automatically moves the current seek pointer forward by one.

See Also

CeOpenDatabase (RAPI)


CeEnumDBVolumes

This function enumerates all mounted database volumes and returns the name for each. A remote application interface (RAPI) version of this function exists, and it is also called CeEnumDBVolumes.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeEnumDBVolumes( PCEGUID pceguid, LPWSTR lpBuf,
DWORD dwNumChars );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database that is queried for its name. To begin enumeration, set this parameter to CREATE_INVALIDGUID.
lpBuf
[out] Pointer to the allocated buffer that receives the database volume names.
dwNumChars
[in] Specifies the length, in characters, of the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
One of the parameters is invalid.
ERROR_NO_MORE_ITEMS
There are no more mounted volumes to enumerate.
ERROR_INSUFFICIENT_BUFFER
The specified buffer was not large enough.

Remarks

To enumerate all mounted volumes

  1. Supply the result of CREATE_INVALIDGUID as the first CEGUID. The system sets up the process of enumerating all database volumes.
  2. On the first successful completion, pceguid and lpBuf are set to the CEGUID and the database volume name of the first of the database volumes, respectively.

To continue enumeration

  1. Call CeEnumDBVolumes with the previously returned CEGUID. Continue until an error occurs.
  2. If the return value is ERROR_INSUFFICIENT_BUFFER, reallocate the buffer and use the pceguid that was returned from the failure to resume the enumeration. This prevents the necessity to completely restart the process.

See Also

CREATE_INVALIDGUID


CeEnumDBVolumes (RAPI)

This function enumerates all mounted database volumes and returns the name for each. CeEnumDBVolumes is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.12 and later

Syntax

BOOL CeEnumDBVolumes( PCEGUID pceguid, LPWSTR lpBuf,
DWORD dwNumChars );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database that is queried for its name. To begin enumeration, set this parameter to CREATE_INVALIDGUID.
lpBuf
[out] Pointer to the allocated buffer that receives the database volume names.
dwNumChars
[in] Specifies the length, in characters, of the buffer.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_INVALID_PARAMETER
One of the parameters is invalid.
ERROR_NO_MORE_ITEMS
There are no more mounted volumes to enumerate.
ERROR_INSUFFICIENT_BUFFER
The specified buffer was not large enough.

Remarks

To enumerate all mounted volumes

  1. Supply the result of CREATE_INVALIDGUID as the first CEGUID. The system sets up the process of enumerating all database volumes.
  2. On the first successful completion, pceguid and lpBuf are set to the CEGUID and the database volume name of the first of the database volumes, respectively.

To continue enumeration

  1. Call CeEnumDBVolumes (RAPI) with the previously returned CEGUID. Continue until an error occurs.
  2. If the return value is ERROR_INSUFFICIENT_BUFFER, reallocate the buffer and use the pceguid that was returned from the failure to resume the enumeration. This prevents the necessity to completely restart the process.

See Also

CREATE_INVALIDGUID


CeFindAllDatabases (RAPI)

This function retrieves information about all databases of a given type residing on the Windows CE device. The function copies information to an array of CEDB_FIND_DATA structures.

CeFindAllDatabases is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeFindAllDatabases(DWORD dwDbaseType, WORD wFlags, LPWORD cFindData, LPLPCEDB_FIND_DATA ppFindData);

Parameters

dwDbaseType
[in] Specifies the type identifier of the databases to seek.
wFlags
[in] Members of the CEDB_FIND_DATA structure that are to be retrieved. This parameter can be a combination of the following values:
Value
Description
FAD_OID | Retrieves the OidDb member.
FAD_FLAGS | Retrieves the DbInfo.dwFlags member.
FAD_NAME | Retrieves the DbInfo.szDbaseName member.
FAD_TYPE | Retrieves the DbInfo.dwDbaseType member.
FAD_NUM_RECORDS | Retrieves the DbInfo.dwNumRecords member.
FAD_NUM_SORT_ORDER | Retrieves the DbInfo.dwNumSortOrder member.
FAD_SORT_SPECS | Retrieves the DbInfo.rgSortSpecs member.

cFindData
[out] Pointer to a variable that receives a count of the items found.
ppFindData
[out] Pointer to the pointer to an array of CEDB_FIND_DATA structures that receives information about the found items. It is the application’s responsibility to free the memory used by the array. To free the memory the application must call CeRapiFreeBuffer.

Return Values

TRUE indicates success. FALSE indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegFindAllDatabases function.


CeFindAllFiles (RAPI)

This function retrieves information about all files and directories in the given directory of the Windows CE object store. The function copies information to an array of CE_FIND_DATA structures.

CeFindAllFiles is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeFindAllFiles(LPCWSTR szPath, DWORD dwFlags,
LPDWORD lpdwFoundCount, LPLPCE_FIND_DATA ppFindDataArray);

Parameters

szPath
[in] Null-terminated string contains the name of the path in which to search for files. Note that within the path string, two backslashes (\\) must be used to achieve a single backslash because the C language reserves a single backslash for escape characters. For example, a valid path would be “\\temp”, whereas a path set to “\temp” would expand to the tab character followed by “emp”.
dwFlags
[in] Combination of filter and retrieval flags. The filter flags specify what kinds of files to document, and the retrieval flags specify which members of the CE_FIND_DATA structure to retrieve.

The filter flags can be a combination of the following values:
Value
Description
FAF_ATTRIB_CHILDREN | Only retrieve information for directories which have child items.
FAF_ATTRIB_NO_HIDDEN | Do not retrieve information for files or directories which have the hidden attribute set.
FAF_FOLDERS_ONLY | Only retrieve information for directories.
FAF_NO_HIDDEN_SYS_ROMMODULES | Do not retrieve information for ROM files or directories.

The retrieval flags can be a combination of the following values:
Value
Description
FAF_ATTRIBUTES | Retrieve the file attributes and copy them to the dwFileAttributes member.
FAF_CREATION_TIME | Retrieve the file creation time and copy it to the ftCreationTime member.
FAF_LASTACCESS_TIME | Retrieve the time when the file was last accessed and copy it to the ftLastAccessTime member.
FAF_LASTWRITE_TIME | Retrieve the time when the file was last written to and copy it to the ftLastWriteTime member.
FAF_SIZE_HIGH | Retrieve the high-order DWORD value of the file size and copy it to the nFileSizeHigh member.
FAF_SIZE_LOW | Retrieve the low-order DWORD value of the file size and copy it to the nFileSizeLow member.
FAF_OID | Retrieve the object identifier of the file and copy it to the dwOID member.
FAF_NAME | Retrieve the file name and copy it to the cFileName member.

lpdwFoundCount
[out] Long pointer to a variable that receives a count of the items found.
ppFindDataArray
[out] Pointer to the pointer to an array of CE_FIND_DATA structures that receive information about the found items. It is the application’s responsibility to free the memory used by the array. To free the memory you must call CeRapiFreeBuffer.

Return Values

TRUE indicates success. FALSE indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegFindAllFiles function.


CeFindClose (RAPI)

This function closes the specified search handle. The CeFindFirstFile and CeFindNextFile functions use the search handle to locate files with names that match a specified name.

CeFindClose is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeFindClose( HANDLE hFindFile );

Parameters

hFindFile
[in] Search handle. This handle must have been previously opened by the CeFindFirstFile function.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

After the CeFindClose function is called, the handle specified by the hFindFile parameter cannot be used in subsequent calls to either the CeFindNextFile or CeFindClose function.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegFindClose function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

CeFindFirstFile, CeFindNextFile


CeFindFirstDatabase

This function opens an enumeration context that enables an application to enumerate all databases in the object store. This function is obsolete. Applications should call CeFindFirstDatabaseEx instead.

A remote application interface (RAPI) version of this function exists, and it is also named CeFindFirstDatabase.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CeFindFirstDatabase(DWORD dwDbaseType);

Parameters

dwDbaseType
[in] Specifies the type identifier of the databases to enumerate. If this parameter is zero, all databases are enumerated.

Return Values

A handle to an enumeration context indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information within a Windows CE program, call GetLastError. GetLastError may return ERROR_OUTOFMEMORY if no memory is available to allocate a database handle.

Remarks

This function returns only the handle to a enumeration context. To begin enumerating databases, an application must call the CeFindNextDatabaseEx function. When an application is done with the handle to the enumeration context, an application uses CloseHandle to release the resources associated with the enumeration context.

See Also

CeFindNextDatabaseEx, CloseHandle


CeFindFirstDatabase (RAPI)

This function opens an enumeration context to enable an application to enumerate all databases in the object store. CeFindFirstDatabase (RAPI) is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CeFindFirstDatabase(DWORD dwDbaseType);

Parameters

dwDbaseType
[in] Specifies the type identifier of the databases to enumerate. If this parameter is zero, all databases are enumerated.

Return Values

A handle to an enumeration context indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information within a RAPI program, call CeGetLastError. CeGetLastError may return ERROR_OUTOFMEMORY if no memory is available to allocate a database handle.

Remarks

This function only returns the handle to a enumeration context. To begin enumerating databases, an application must call the CeFindNextDatabase (RAPI) function.

Use the CeCloseHandle function to close a handle returned by the CeFindFirstDatabase (RAPI) function.

See Also

CeFindNextDatabase (RAPI), CeCloseHandle (RAPI)


CeFindFirstDatabaseEx

This function opens an enumeration context for all databases in a database volume. A remote application interface (RAPI) version of this function exists and it is also named CeFindFirstDatabaseEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE CeFindFirstDatabaseEx( PCEGUID pceguid,
DWORD dwDbaseType );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database volume. If pceguid is NULL or set to an invalid GUID, then all mounted database volumes are searched.
dwDbaseType
[in] Specifies the type identifier of the databases to enumerate. If this parameter is zero, all databases are enumerated in the volume. For Windows CE-based devices, a volume is the object store or a mounted database volume.

Return Values

A handle to an enumeration context indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError. GetLastError may return ERROR_OUTOFMEMORY if no memory is available to allocate a database handle.

To find all the databases of the desired type, specify the enumeration context handle in multiple calls to the CeFindNextDatabaseEx function.

Remarks

This function only returns the handle to a enumeration context. To begin enumerating databases, an application must call the CeFindNextDatabaseEx function. When an application is done with the handle to the enumeration context, an application uses CloseHandle to release the resources associated with the enumeration context.

See Also

CeFindNextDatabaseEx, CREATE_INVALIDGUID


CeFindFirstDatabaseEx (RAPI)

This function opens an enumeration context for all databases in a database volume. CeFindFirstDatabaseEx (RAPI) is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE CeFindFirstDatabaseEx( PCEGUID pceguid,
DWORD dwDbaseType );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database volume. If pceguid is NULL or set to an invalid GUID, then all mounted database volumes are searched.
dwDbaseType
[in] Specifies the type identifier of the databases to enumerate. If this parameter is zero, all databases are enumerated in the volume. For Windows CE-based devices, a volume is the object store or a mounted database volume.

Return Values

A handle to an enumeration context indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call CeGetLastError. CeGetLastError may return ERROR_OUTOFMEMORY if no memory is available to allocate a database handle.

To find all the databases of the desired type, specify the enumeration context handle in multiple calls to the CeFindNextDatabaseEx function.

Remarks

This function only returns the handle to a enumeration context. To begin enumerating databases, an application must call the CeFindNextDatabaseEx (RAPI) function. When an application is done with the handle to the enumeration context, an application uses CeCloseHandle to release the resources associated with the enumeration context.

See Also

CeFindNextDatabaseEx (RAPI), CREATE_INVALIDGUID


CeFindFirstFile (RAPI)

This function searches a directory for a file whose name matches the specified filename. CeFindFirstFile examines subdirectory names as well as filenames.

CeFindFirstFile is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HANDLE CeFindFirstFile(LPCWSTR lpFileName,
LPCE_FIND_DATA lpFindFileData);

Parameters

lpFileName
[in] Long pointer to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the FindFirstFile function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with FindFirstFile. However, each component in the path cannot be more than MAX_PATH characters long. This also works with Universal Naming Convention (UNC) names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private” and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps.”

lpFindFileData
[out] Long pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory.

Return Values

A search handle, used in a subsequent call to CeFindNextFile or CeFindClose, indicates success. INVALID_HANDLE_VALUE indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegFindFirstFile function.

See Also

FindFirstFile, CE_FIND_DATA, WIN32_FIND_DATA


CeFindNextDatabase

This function retrieves the next database in an enumeration context. This function is obsolete. Applications should call CeFindNextDatabaseEx instead.

A remote application interface (RAPI) version of this function exists and is also called CeFindNextDatabase.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeFindNextDatabase(HANDLE hEnum);

Parameters

hEnum
[in] Handle to an enumeration context; this handle is returned from CeFindFirstDatabase.

Return Values

The object identifier of the next database to be enumerated indicates success. Zero indicates that there are no more databases are left to enumerate, or that an error occurred. To get extended error information within a Windows CE program, call GetLastError. Possible values for GetLastError include the following:

ERROR_NO_MORE_ITEMS
The object store contains no more databases to enumerate.
ERROR_INVALID_PARAMETER
The hEnum parameter specified an invalid handle.

Remarks

To find all matching databases, CeFindNextDatabase is called in a loop until 0 is returned. If a database is deleted during an enumeration, CeFindNextDatabase fails and returns ERROR_KEY_DELETED. If this error occurs, you must restart the enumeration with a call to CeFindFirstDatabase.

See Also

CeFindFirstDatabase


CeFindNextDatabase (RAPI)

This function retrieves the next database in an enumeration context. CeFindNextDatabase (RAPI) is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeFindNextDatabase(HANDLE hEnum);

Parameters

hEnum
[in] Handle to an enumeration context; this handle is returned from CeFindFirstDatabase (RAPI).

Return Values

The object identifier of the next database to be enumerated indicates success. Zero indicates that there are no more databases are left to enumerate, or that an error occurred. To get extended error information within a RAPI program, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_NO_MORE_ITEMS
The object store contains no more databases to enumerate.
ERROR_INVALID_PARAMETER
The hEnum parameter specified an invalid handle.

Remarks

To find all matching databases, CeFindNextDatabase (RAPI)is called in a loop until 0 is returned. If a database is deleted during an enumeration, CeFindNextDatabase (RAPI) fails and returns ERROR_KEY_DELETED. If this error occurs, you must restart the enumeration with a call to CeFindFirstDatabase (RAPI).

See Also

CeFindFirstDatabase (RAPI)


CeFindNextDatabaseEx

This function retrieves the next database in an enumeration context. A remote application interface (RAPI) version of this function exists, and it is also named CeFindNextDatabaseEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

CEOID CeFindNextDatabaseEx( HANDLE hEnum,PCEGUID pceguid );

Parameters

hEnum
[in] Handle returned from CeFindFirstDatabaseEx.
pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.

Return Values

A valid CEOID indicates success. Zero indicates failure or a lack of additional databases. Call GetLastError to get the extended error information. Possible values for GetLastError include the following:

ERROR_NO_MORE_ITEMS
There are no more databases to enumerate.
ERROR_KEY_DELETED
A database was deleted during enumeration.

Remarks

To find all matching databases, CeFindNextDatabaseEx is called in a loop until 0 is returned. If a database is deleted during an enumeration, CeFindNextDatabaseEx fails and returns error ERROR_KEY_DELETED. If this error occurs, you must restart the enumeration with a call to CeFindFirstDatabaseEx. When enumeration is complete, the hEnum handle must be closed by calling the CloseHandle function.

See Also

CeFindFirstDatabaseEx, CREATE_SYSTEMGUID


CeFindNextDatabaseEx (RAPI)

This function retrieves the next database in an enumeration context. CeFindNextDatabaseEx (RAPI) is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.10 and later

Syntax

CEOID CeFindNextDatabaseEx( HANDLE hEnum,PCEGUID pceguid );

Parameters

hEnum
[in] Handle returned from CeFindFirstDatabaseEx.
pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.

Return Values

A valid CEOID indicates success. Zero indicates failure or a lack of additional databases. Call CeGetLastError to get the extended error information. Possible values for CeGetLastError include the following:

ERROR_NO_MORE_ITEMS
There are no more databases to enumerate.
ERROR_KEY_DELETED
A database was deleted during enumeration.

Remarks

To find all matching databases, CeFindNextDatabaseEx (RAPI) is called in a loop until 0 is returned. If a database is deleted during an enumeration, CeFindNextDatabaseEx (RAPI) fails and returns error ERROR_KEY_DELETED. If this error occurs, you must restart the enumeration with a call to CeFindFirstDatabaseEx (RAPI). When enumeration is complete, the hEnum handle must be closed by calling the CeCloseHandle function.

See Also

CeFindFirstDatabaseEx, CREATE_SYSTEMGUID


CeFindNextFile (RAPI)

This function continues a file search from a previous call to the CeFindFirstFile function. CeFindNextFile is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeFindNextFile( HANDLE hFindFile,
LPWIN32_FIND_DATA lpFindFileData );

Parameters

hFindFile
[in] Search handle returned by a previous call to the CeFindFirstFile function.
lpFindFileData
[out] Pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to CeFindNextFile to refer to the found file or directory.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError. If no matching files can be found, the CeGetLastError function returns ERROR_NO_MORE_FILES.

Remarks

The CeFindNextFile function searches for files by name only; it cannot be used for attribute-based searches.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegFindNextFile function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

CeFindClose (RAPI), CeFindFirstFile (RAPI), CeGetFileAttributes (RAPI), CeSetFileAttributes (RAPI), WIN32_FIND_DATA


CeFlushDBVol

This function flushes information from a database volume to permanent storage.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeFlushDBVol( PCEGUID pceguid );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted volume to be flushed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

In a mounted database volume, all write operations are cached. To explicitly force the data to be written out to permanent storage, the CeFlushDBVol function must be called. If a reset or power failure occurs before data is flushed from the cache, then the data that has not been flushed is lost. The database engine periodically flushes the database volume when enough data has been changed, but an application that must be assured that their data is saved should call CeFlushDBVol. A database volume is also flushed when it is unmounted.

See Also

CeUnmountDBVol, CeWriteRecordProps


CeFreeNotification

This function frees a CENOTIFICATION structure passed to an application.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeFreeNotification(PCENOTIFYREQUEST pRequest, PCENOTIFICATION pNotify);

Parameters

pRequest
[in] Pointer to the CENOTIFYREQUEST structure associated with the CENOTIFICATION structure to be freed.
pNotify
[in] Pointer to the CENOTIFICATION structure passed to the application from the database subsystem.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

A CENOTIFICATION structure that is received with a WM_DBNOTIFACTION message can only be freed by calling CeFreeNotification. Any attempt to free the structure in another manner can lead to unpredictable results.

See Also

WM_DBNOTIFICATION, CeOpenDatabaseEx


CeGetDesktopDeviceCaps (RAPI)

This function retrieves device-specific information about a specified device. CeGetDesktopDeviceCaps is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

INT CeGetDesktopDeviceCaps(INT nIndex);

Parameters

nIndex
[in] Specifies the item to return. It is one of the following values:
Value
Description
DRIVERVERSION | Returns the device driver version.
TECHNOLOGY | Returns the device technology. It is one of the values shown in the following table.
DT_PLOTTER | Vector plotter
DT_RASDISPLAY | Raster display
DT_RASPRINTER | Raster printer
DT_RASCAMERA | Raster camera
DT_CHARSTREAM | Character stream
DT_METAFILE | Metafile
DT_DISPFILE | Display file
If the hdc parameter identifies the device context of an enhanced metafile, the device technology is that of the referenced device. To determine whether it is an enhanced metafile device context, use the GetObjectType function.
HORZSIZE | Returns the width, in millimeters, of the physical screen.
VERTSIZE | Returns the height, in millimeters, of the physical screen.
HORZRES | Returns the width, in pixels, of the screen.
VERTRES | Return the height, in raster lines, of the screen.
BITSPIXEL | Returns the number of adjacent color bits for each pixel.
PLANES | Returns the number of color planes.
NUMBRUSHES | Returns the number of device-specific brushes.
NUMPENS | Returns the number of device-specific pens.
NUMMARKERS | Returns the number of device-specific markers.
NUMFONTS | Returns the number of device-specific fonts.
NUMCOLORS | Returns the number of entries in the device's color table, if the device has a color depth of no more than 8 bits per pixel. For devices with greater color depths, –1 is returned.
ASPECTX | Returns the relative width of a device pixel used for line drawing.
ASPECTY | Returns the relative height of a device pixel used for line drawing.
ASPECTXY | Returns the diagonal width of the device pixel used for line drawing.
PDEVICESIZE | Reserved.
CLIPCAPS | Returns the flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is 0.
PHYSICALWIDTH | For printing devices, returns the width of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical width value of 5100 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
PHYSICALHEIGHT | For printing devices, returns the height of the physical page, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical height value of 6600 device units. Note that the physical page is almost always greater than the printable area of the page, and never smaller.
PHYSICALOFFSETX | For printing devices, returns the distance from the left edge of the physical page to the left edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the leftmost 0.25" of paper, has a horizontal physical offset of 150 device units.
PHYSICALOFFSETY | For printing devices, returns the distance from the top edge of the physical page to the top edge of the printable area, in device units. For example, a printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the topmost 0.5" of paper, has a vertical physical offset of 300 device units.
RASTERCAPS | Returns the value that indicates the raster capabilities of the device, as shown in the following table.
RC_BANDING | Requires banding support.
RC_BITBLT | Capable of transferring bitmaps.
RC_BITMAP64 | Capable of supporting bitmaps larger than 64K.
RC_DI_BITMAP
RC_DIBTODEV
RC_FLOODFILL | Capable of performing flood fills.
RC_GDI20_OUTPUT | Capable of supporting features of 16-bit Windows 2.0.
RC_PALETTE | Specifies a palette-based device.
RC_SCALING | Capable of scaling.
RC_STRETCHBLT | Capable of performing the StretchBlt function.
RC_STRETCHDIB
CURVECAPS | Returns the value that indicates the curve capabilities of the device, as shown in the following table.
CC_NONE | Device does not support curves.
CC_CHORD | Device can draw chord arcs.
CC_CIRCLES | Device can draw circles.
CC_ELLIPSES | Device can draw ellipses.
CC_INTERIORS | Device can draw interiors.
CC_PIE | Device can draw pie wedges.
CC_ROUNDRECT | Device can draw rounded rectangles.
CC_STYLED | Device can draw styled borders.
CC_WIDE | Device can draw wide borders.
CC_WIDESTYLED | Device can draw borders that are wide and styled.
LINECAPS | Returns the value that indicates the line capabilities of the device, as shown in the following table:
LC_NONE | Device does not support lines.
LC_INTERIORS | Device can draw interiors.
LC_MARKER | Device can draw a marker.
LC_POLYLINE | Device can draw a polyline.
LC_POLYMARKER | Device can draw multiple markers.
LC_STYLED | Device can draw styled lines.
LC_WIDE | Device can draw wide lines.
LC_WIDESTYLED | Device can draw lines that are wide and styled.
POLYGONALCAPS | Returns the value that indicates the polygon capabilities of the device, as shown in the following table.
PC_NONE | Device does not support polygons.
PC_INTERIORS | Device can draw interiors.
PC_POLYGON | Device can draw alternate-fill polygons.
PC_RECTANGLE | Device can draw rectangles.
PC_SCANLINE | Device can draw a single scanline.
PC_STYLED | Device can draw styled borders.
PC_WIDE | Device can draw wide borders.
PC_WIDESTYLED | Device can draw borders that are wide and styled.
PC_WINDPOLYGON | Device can draw winding-fill polygons.
TEXTCAPS | Returns the value that indicates the text capabilities of the device, as shown in the following table.
TC_OP_CHARACTER | Device is capable of character output precision.
TC_OP_STROKE | Device is capable of stroke output precision.
TC_CP_STROKE | Device is capable of stroke clip precision.
TC_CR_90 | Device is capable of 90-degree character rotation.
TC_CR_ANY | Device is capable of any character rotation.
TC_SF_X_YINDEP | Device can scale independently in the x- and y-directions.
TC_SA_DOUBLE | Device is capable of doubled character for scaling.
TC_SA_INTEGER | Device uses integer multiples only for character scaling.
TC_SA_CONTIN | Device uses any multiples for exact character scaling.
TC_EA_DOUBLE | Device can draw double-weight characters.
TC_IA_ABLE | Device can italicize.
TC_UA_ABLE | Device can underline.
TC_SO_ABLE | Device can draw strikeouts.
TC_RA_ABLE | Device can draw raster fonts.
TC_VA_ABLE | Device can draw vector fonts.
TC_RESERVED | Reserved; must be zero.
TC_SCROLLBLT | Device cannot scroll using a bit-block transfer. Note that this meaning may be the opposite of what you expect.

Return Values

The return value specifies the value of the desired item.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegGetDesktopDeviceCaps function.

See Also

GetDeviceCaps


CeGetDeviceId

This function returns a device identifier for the currently connected device.

Syntax

DWORD CeGetDeviceId(void);

Return Values

Valid device identifier indicates success. Zero indicates no device or invalid device. The value -1 indicates a guest device.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeGetFileAttributes (RAPI)

This function returns attributes for a specified file or directory. CeGetFileAttributes is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeGetFileAttributes(LPCWSTR lpFileName);

Parameters

lpFileName
[in] Long pointer to a null-terminated string that specifies the name of a file or directory.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the CeGetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with CeGetFileAttributes. However, each component in the path cannot be more than MAX_PATH characters long. This also works with Universal Naming Convention (UNC) names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private” and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps.”

Return Values

The attributes of the specified file or directory, returned in a DWORD, indicates success. 0xFFFFFFFF indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

The attributes returned upon success can be one or more of the following values:

FILE_ATTRIBUTE_ARCHIVE
The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
The handle identifies a directory.
FILE_ATTRIBUTE_ENCRYPTED
The file or directory is encrypted. For a file, this means that all data streams are encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN
The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_INROM
This file is an operating system file stored in ROM. These files are read-only; they cannot be modified.
FILE_ATTRIBUTE_NORMAL
The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE
The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY
The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_REPARSE_POINT
The file has an associated reparse point.
FILE_ATTRIBUTE_ROMMODULE
This file is an operating system file stored in ROM and executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file, instead the LoadLibrary and CreateProcess functions must be used.
FILE_ATTRIBUTE_SPARSE_FILE

The file is a sparse file.

FILE_ATTRIBUTE_SYSTEM
The file or directory is part of, or is used exclusively by, the operating system.
FILE_ATTRIBUTE_TEMPORARY
The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegGetFileAttributes function.

See Also

GetFileAttributes


CeGetFileSize (RAPI)

This function retrieves the size, in bytes, of the specified file. CeGetFileSize is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeGetFileSize( HANDLE hFile, LPDWORD lpFileSizeHigh );

Parameters

hFile
[in] Open handle of the file whose size is being returned. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.
lpFileSizeHigh
[out] Pointer to the variable where the high-order word of the file size is returned. This parameter can be NULL if the application does not require the high-order word.

Return Values

The low-order DWORD of the file size indicates success. If lpFileSizeHigh is non-NULL, the function puts the high-order DWORD of the file size into the variable pointed to by that parameter. If lpFileSizeHigh is NULL, 0xFFFFFFFF indicates failure. To get extended error information, call CeGetLastError.

If lpFileSizeHigh is non-NULL, 0xFFFFFFFF indicates failure and CeGetLastError returns a value other than NO_ERROR.

Remarks

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetFileSize function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

GetFileSize


CeGetFileTime (RAPI)

This function retrieves the date and time that a file was created, last accessed, and last modified. CeGetFileTime is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeGetFileTime( HANDLE hFile, LPFILETIME lpCreationTime,
LPFILETIME lpLastAccessTime, LPFILETIME lpLastWriteTime );

Parameters

hFile
[in] Handle to the files for which to get dates and times. The file handle must have been created with GENERIC_READ access to the file.
lpCreationTime
[out] Pointer to a FILETIME structure to receive the date and time the file was created. This parameter can be NULL if the application does not require this information.
lpLastAccessTime
[out] Pointer to a FILETIME structure to receive the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.
lpLastWriteTime
[out] Pointer to a FILETIME structure to receive the date and time the file was last written to. This parameter can be NULL if the application does not require this information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError.

Remarks

The FAT and NTFS file systems support the file creation, last access, and last write time values.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetFileTime function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

The precision of the time for a file in a FAT file system is one second. The time precision for files in other file systems, such as those connected through a network or installed on a peripheral device, depends on the file system but may also be limited by the remote device.

See Also

FILETIME, CeGetFileSize, CeSetFileTime


CeGetLastError (RAPI)

This function returns the calling thread’s last-error code value. CeGetLastError is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeGetLastError( void );

Return Values

The calling thread’s last-error code value indicates success. Functions set this value by calling the SetLastError function. The Return Value section of each reference page notes the conditions under which the function sets the last-error code.

Remarks

You should call the CeGetLastError function immediately when a function’s return value indicates that such a call will return useful data. That is because some functions call SetLastError(0) when they succeed, wiping out the error code set by the most recently failed function.

Most functions in the Win32 API that set the thread’s last error code value set it when they fail; a few functions set it when they succeed. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or –1. Some functions call SetLastError under conditions of success; those cases are noted in each function’s reference page.

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no system error code has this bit set. If you are defining an error code for your application, set this bit to one. That indicates that the error code has been defined by an application, and ensures that your error code does not conflict with any error codes defined by the system.

To obtain an error string for system error codes, use the FormatMessage function. For a complete list of error codes, see Error Values or the SDK header file WINERROR.H.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetLastError function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

SetLastError


CeGetSelectedDeviceId

This function returns a device id for the currently selected device.

Syntax

DWORD CeGetSelectedDeviceId(void);

Return Values

Valid device identifier indicates success. Zero indicates no device or invalid device. The value -1 indicates a guest device.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeGetSpecialFolderPath (RAPI)

This function gets the path to a special shell folder. CeGetSpecialFolderPath is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeGetSpecialFolderPath( int nFolder, DWORD nBufferLength, LPWSTR lpBuffer);

Parameters

nFolder
[in] Value specifying the folder for which to retrieve the location. This parameter can be one of the following values:
Value
Description
CSIDL_DESKTOP | Windows desktop, which is a virtual folder at the root of the name space.
CSIDL_FAVORITES | File system directory that serves as a common repository for the user's favorite items.
CSIDL_FONTS | Virtual folder containing fonts.
CSIDL_PERSONAL | File system directory that serves as a common repository for documents.
CSIDL_PROGRAMS | File system directory that contains the user’s program groups which are also file system directories.
CSIDL_RECENT | File system directory containing the user’s most recently used documents.
CSIDL_STARTUP | File system directory that corresponds to the user’s Startup program group.

nBufferLength
[in] Size of lpBuffer in characters.
lpBuffer
[out] Long pointer to the buffer for the folder path.

Return Values

The length of the returned string indicates success. FALSE indicates a RAPI related failure. To extended error information, call CeRapiGetError.

Remarks

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetSpecialFolderPath function.


CeGetStoreInformation (RAPI)

This function fills in a STORE_INFORMATION structure with the size of the object store and the amount of free space currently in the object store.

CeGetStoreInformation is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeGetStoreInformation( LPSTORE_INFORMATION lpsi );

Parameters

lpsi
[out] Pointer to the STORE_INFORMATION structure to be filled in by this function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the CeGetLastError function.

Remarks

The system reserves that last 24K for high priority system operations. This function always reports 24K storage memory less then what is really available.

Upon a RAPI-related failure, the return value is FALSE.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetStoreInformation function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

STORE_INFORMATION


CeGetSystemInfo (RAPI)

This function returns information about the current system. CeGetSystemInfo is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

VOID CeGetSystemInfo( LPSYSTEM_INFO lpSystemInfo);

Parameters

lpSystemInfo
Pointer to a SYSTEM_INFO structure to be filled in by this function.

Return Values

None.

Remarks

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetSystemInfo function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

SYSTEM_INFO


CeGetTempPath (RAPI)

This function gets the path to the directory designated for temporary files. CeGetTempPath is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeGetTempPath( DWORD nBufferLength, LPWSTR lpBuffer );

Parameters

nBufferLength
[in] Size of lpBuffer in characters.
lpBuffer
[out] Long pointer to the buffer for the folder path.

Return Values

The return value is the length, in characters, of the string copied to lpBuffer, not including the terminating null character. If the return value is greater than nBufferLength, the return value is the size of the buffer required to hold the path.

If CeGetTempPath fails, the return value is 0. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

The CeGetTempPath function gets the temporary file path as follows:

  1. The path specified by the TMP environment variable.
  2. The path specified by the TEMP environment variable, if TMP is not defined.
  3. The current directory, if both TMP and TEMP are not defined.


CeGetUserNotificationPreferences

This function queries the user for notification settings by displaying a dialog box showing options that are valid for the current hardware platform.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Parameters

Syntax

BOOL CeGetUserNotificationPreferences(HWND hWndParent, PCE_USER_NOTIFICATION lpNotification);

hWndParent
[in] Handle to the parent window for the notification settings dialog box.
lpNotification
[in/out] Long pointer to a CE_USER_NOTIFICATION structure. When calling CeGetUserNotificationPreferences, this structure contains data used to initialize the notification settings dialog box. When the function returns, this structure contains the user's notification settings.

Return Values

TRUE indicates success. FALSE indicates failure or that the user did not change the settings.

Remarks

If the function returns TRUE, the settings returned in the CE_USER_NOTIFICATION structure should be saved and considered when calling CeSetUserNotification.

See Also

CeSetUserNotification, CE_USER_NOTIFICATION


CeGetVersionEx (RAPI)

This function obtains extended information about the version of the operating system that is currently running. CeGetVersionEx is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeGetVersionEx(LPCEOSVERSIONINFO lpVersionInformation);

Parameters

lpVersionInformation
[out] Long pointer to an OSVERSIONINFO data structure that the function fills with operating system version information.

Before calling the CeGetVersionEx function, set the dwOSVersionInfoSize member of the OSVERSIONINFO data structure to 'sizeof(OSVERSIONINFO)'.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

CeGetVersionEx fails if you specify an invalid value for the dwOSVersionInfoSize member of the OSVERSIONINFO.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegGetVersionEx function.

When writing applications for Windows CE Japanese 2.01 be aware that the Tool Bar will indicate that the version is 2.0.

See Also

GetVersionEx, OSVERSIONINFO


CeGetWindow (RAPI)

This function retrieves the handle to a window that has the specified relationship to the specified window. CeGetWindow is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HWND CeGetWindow( HWND hWnd, UINT uCmd);

Parameters

hWnd
Handle to a window. The window handle retrieved is relative to this window, based on the value of the uCmd parameter.
uCmd
Specifies the relationship between the specified window and the window whose handle is to be retrieved. This parameter can be one of the following values:
Value
Description
GW_CHILD | The retrieved handle identifies the child window at the top of the z-order, if the specified window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the specified window. It does not examine descendant windows.
GW_HWNDFIRST | The retrieved handle identifies the window of the same type that is highest in the z-order. If the specified window is a topmost window, the handle identifies the topmost window that is highest in the z-order. If the specified window is a child window, the handle identifies the sibling window that is highest in the z-order.
GW_HWNDLAST | The retrieved handle identifies the window of the same type that is lowest in the z-order. If the specified window is a topmost window, the handle identifies the topmost window that is lowest in the z-order. If the specified window is a child window, the handle identifies the sibling window that is lowest in the z-order.
GW_HWNDNEXT | The retrieved handle identifies the window below the specified window in the z-order. If the specified window is a topmost window, the handle identifies the topmost window below the specified window. If the specified window is a child window, the handle identifies the sibling window below the specified window.
GW_HWNDPREV | The retrieved handle identifies the window above the specified window in the z-order. If the specified window is a topmost window, the handle identifies the topmost window above the specified window. If the specified window is a child window, the handle identifies the sibling window above the specified window.
GW_OWNER | The retrieved handle identifies the specified window’s owner window, if any. This flag will not retrieve a parent window.

Return Values

A window handle indicates success. NULL indicates that no window exists with the specified relationship to the specified window. To get extended error information, call CeGetLastError.

Remarks

This function distinguishes between only top-level and child windows. Top-most windows are considered top-level windows.

In Windows CE version 1.0, the GW_OWNER flag value for the uCmd parameter is only supported for dialog boxes.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGetWindow function.


CeGlobalMemoryStatus (RAPI)

This function gets information on the physical and virtual memory of the system. CeGlobalMemoryStatus is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

void CeGlobalMemoryStatus( LPMEMORYSTATUS lpmst );

Parameters

lpBuffer
[out] Pointer to a MEMORYSTATUS structure. The GlobalMemoryStatus function stores information about current memory availability into this structure.

Return Values

None.

Remarks

You can use the GlobalMemoryStatus function to determine how much memory your application can allocate without severely impacting other applications.

The information returned by the GlobalMemoryStatus function is volatile. There is no guarantee that two sequential calls to this function will return the same information.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegGlobalMemoryStatus function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.


CeHandleAppNotifications

This function marks as “handled” all notifications previously registered by the given application that have occurred. CeHandleAppNotifications turns off the sound and LED and stops vibration (if they were on), and removes the taskbar annunciator.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeHandleAppNotifications(TCHAR *pwszAppName);

Parameters

pwszAppName
[in] Pointer to a null-terminated string that specifies the name of the application whose events are to be marked as “handled”. This must be the name that was passed in to CeSetUserNotification as the owner of the notification.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

CeGetUserNotificationPreferences, CeSetUserNotification


CeMountDBVol

This function issues a mount request for a database volume that contains both data and an integrity log. The function returns a CEGUID that is the globally unique identifier of a mounted database.

A remote application interface (RAPI) version of this function exists, and it is also called CeMountDBVol.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeMountDBVol( PCEGUID pceguid, LPWSTR lpszDBVol,
DWORD dwFlags );

Parameters

pceguid
[in] Pointer to a buffer that contains the CEGUID that contains the globally unique identifier of a mounted database.
lpszDBVol
[in] Pointer to the null-terminated string that contains the file name of the database volume to be mounted. The path is limited to MAX_PATH characters and includes the NULL character.
dwFlags
[in] Specifies how the database volume is opened. It is one of the following flags:
Value
Description
CREATE_NEW | Creates a new database volume. The function fails if the specified database volume already exists.
CREATE_ALWAYS | Creates a new database volume. The function overwrites the database volume if it exists.
OPEN_EXISTING | Opens the database volume. The function fails if the database volume does not exist.
OPEN_ALWAYS | Opens the database volume, if it exists. If the database volume does not exist, the function creates the database volume as if CREATE_NEW was specified.
TRUNCATE_EXISTING | Opens the database volume. Once opened, the database volume is truncated so that its size is zero bytes. The function fails if the database volume does not exist.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

ERROR_DISK_FULL
The mounted volume does not have space to create the new database.
ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_NOT_ENOUGH_MEMORY
There was not enough memory available to create volume.
If the database volume already exists before the function call and dwFlags is CREATE_ALWAYS or OPEN_ALWAYS, GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded.

Remarks

The CeMountDBVol function creates a database volume that contains both data and an integrity log. The function can accept any path including Uniform Naming Convention (UNC) names for files on a LAN.

A single database volume can be mounted more than once by a different application. Each time the volume is mounted, a reference count is incremented. A mounted database volume does not unmount until all applications that mounted the volume call CeUnmountDBVol. CeUnmountDBVol must be called to free up system resources.

All data written to a mounted database volume is cached until one of the following occurs:

  • It is explicitly flushed. See CeFlushDBVol.
  • It is flushed by the OS because of a low memory condition.
  • It is unmounted.

See Also

CeUnmountDBVol, CHECK_INVALIDGUID


CeMountDBVol (RAPI)

This function issues a mount request for a database volume that contains both data and an integrity log. The function returns a CEGUID that is the globally unique identifier of a mounted database.

CeMountDBVol is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.12 and later

Syntax

BOOL CeMountDBVol( PCEGUID pceguid, LPWSTR lpszDBVol,
DWORD dwFlags );

Parameters

pceguid
[in] Pointer to a buffer that contains the CEGUID that contains the globally unique identifier of a mounted database.
lpszDBVol
[in] Pointer to the null-terminated string that contains the file name of the database volume to be mounted. The path is limited to MAX_PATH characters and includes the NULL character.
dwFlags
[in] Specifies how the database volume is opened. It is one of the following flags:
Value
Description
CREATE_NEW | Creates a new database volume. The function fails if the specified database volume already exists.
CREATE_ALWAYS | Creates a new database volume. The function overwrites the database volume if it exists.
OPEN_EXISTING | Opens the database volume. The function fails if the database volume does not exist.
OPEN_ALWAYS | Opens the database volume, if it exists. If the database volume does not exist, the function creates the database volume as if CREATE_NEW was specified.
TRUNCATE_EXISTING | Opens the database volume. Once opened, the database volume is truncated so that its size is zero bytes. The function fails if the database volume does not exist.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_DISK_FULL
The mounted volume does not have space to create the new database.
ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_NOT_ENOUGH_MEMORY
There was not enough memory available to create volume.

If the database volume already exists before the function call and dwFlags is CREATE_ALWAYS or OPEN_ALWAYS, CeGetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded.

Remarks

The CeMountDBVol (RAPI) function creates a database volume that contains both data and an integrity log. The function can accept any path including Uniform Naming Convention (UNC) names for files on a LAN.

A single database volume can be mounted more than once by a different application. Each time the volume is mounted, a reference count is incremented. A mounted database volume does not unmount until all applications that mounted the volume call CeUnmountDBVol (RAPI). CeUnmountDBVol (RAPI) must be called to free up system resources.

All data written to a mounted database volume is cached until one of the following occurs:

  • It is explicitly flushed. See CeFlushDBVol.
  • It is flushed by the OS because of a low memory condition.
  • It is unmounted.

See Also

CeUnmountDBVol (RAPI), CHECK_INVALIDGUID


CeMoveFile (RAPI)

This function renames an existing file or a directory—including all its children. CeMoveFile is a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeMoveFile(LPCWSTR lpExistingFileName,
LPCWSTR lpNewFileName);

Parameters

lpExistingFileName
[in] Long pointer to a null-terminated string that names an existing file or directory.
lpNewFileName
[in] Long pointer to a null-terminated string that specifies the new name of a file or directory. The new name must not already exist. A new file may be on a different file system or drive. A new directory must be on the same drive.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegMoveFile function.

See Also

MoveFile


CeOidGetInfo

This function retrieves information about an object in the object store. This function is obsolete. Applications should call CeOidGetInfoEx instead.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeOidGetInfo(CEOID oid, CEOIDINFO *poidInfo) ;

Parameters

oid
[in] Identifier of the object for which information is to be retrieved.
poidInfo
[out] Pointer to a CEOIDINFO structure that contains information about the object.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. GetLastError may return ERROR_INVALID_HANDLE if the specified object identifier is invalid.

Remarks

Use the CeOidGetInfo function to retrieve information about any object in the object store database or file system.

See Also

CEOIDINFO, CeCreateDatabaseEx, CeOpenDatabaseEx


CeOidGetInfo (RAPI)

This function retrieves information about an object in the object store. CeOidGetInfo (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeOidGetInfo(CEOID oid, CEOIDINFO *poidInfo) ;

Parameters

oid
[in] Identifier of the object for which information is to be retrieved.
poidInfo
[out] Pointer to a CEOIDINFO structure that contains information about the object.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call CeGetLastError. CeGetLastError may return ERROR_INVALID_HANDLE if the specified object identifier is invalid.

Remarks

Use the CeOidGetInfo function to retrieve information about any object in the object store database or file system.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegOidGetInfo function.

See Also

CEOIDINFO, CeCreateDatabase (RAPI), CeOpenDatabase (RAPI)


CeOidGetInfoEx

This function retrieves information about an object in the object store or a mounted database volume. A remote application interface (RAPI) version of this function exists, and it is also called CeOidGetInfoEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeOidGetInfoEx( PCEGUID pceguid, CEOID oid,
CEOIDINFO * poidInfo );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.
oid
[in] Identifier of the object for which information is to be retrieved.
poidInfo
[out] Pointer to a CEOIDINFO structure that contains information about the object.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. GetLastError may return ERROR_INVALID_HANDLE if the specified object identifier is invalid.

Remarks

The difference between CeOidGetInfo and CeOidGetInfoEx is that CeOidGetInfo retrieves information about objects only in the object store databases, while CeOidGetInfoEx retrieves information about any object in mounted database volumes in addition to the object store databases.

See Also

CeCreateDatabaseEx, CEOIDINFO, CeOpenDatabaseEx, CREATE_SYSTEMGUID


CeOidGetInfoEx (RAPI)

This function retrieves information about an object in the object store or a mounted database volume. CeOidGetInfoEx (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeOidGetInfoEx( PCEGUID pceguid, CEOID oid,
CEOIDINFO * poidInfo );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.
oid
[in] Identifier of the object for which information is to be retrieved.
poidInfo
[out] Pointer to a CEOIDINFO structure that contains information about the object.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call CeGetLastError. CeGetLastError may return ERROR_INVALID_HANDLE if the specified object identifier is invalid.

Remarks

The difference between CeOidGetInfo (RAPI)and CeOidGetInfoEx (RAPI) is that CeOidGetInfo (RAPI) retrieves information about objects only in the object store databases, while CeOidGetInfoEx (RAPI) retrieves information about any object in mounted database volumes in addition to the object store databases.

See Also

CeCreateDatabaseEx (RAPI), CEOIDINFO, CeOpenDatabaseEx (RAPI), CREATE_SYSTEMGUID


CeOpenDatabase

This function opens an existing database. This function is obsolete. Applications should call CeOpenDatabaseEx instead.

A remote application interface (RAPI) version of this function exists, and it is also called CeOpenDatabase.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CeOpenDatabase(PCEOID poid, LPWSTR lpszName, CEPROPID propid, DWORD dwFlags, HWND hwndNotify);

Parameters

poid
[in] Pointer to the object identifier of the database to be opened. To open a database by name, set the value pointed to by poid to zero to receive the object identifer of the newly opened database when a database name is specified for lpszName.
lpszName
[in] Pointer to the null-terminated string that contains the name of the database to be opened. This parameter is ignored if the value pointed to by poid is nonzero.
propid
[in] Property identifier of the primary key for the sort order in which the database is to be traversed. All subsequent calls to CeSeekDatabase assume this sort order. This parameter can be zero if the sort order is not important.
dwFlags
[in] Specifies a bitmask of action flags. It is one of the following values:
Value
Description
CEDB_AUTOINCREMENT | Causes the current seek position to be automatically incremented with each call to the CeReadRecordProps function.
0 (ZERO) | Current seek position is not incremented with each call to CeReadRecordProps.

hwndNotify
[in] Handle to the window to which notification messages (DB_CEOID_*) will be posted if another thread modifies the specified database while you have it open. This parameter can be NULL if you do not need to receive notifications.

Return Values

The handle to the open database indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information within a Windows CE program, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_FILE_NOT_FOUND
No database exists with the specified name. This value applies only if the value pointed to by poid was set to NULL when the function was called.
ERROR_NOT_ENOUGH_MEMORY
No memory was available to allocate a database handle.

Remarks

Use the CloseHandle function to close the handle returned by the CeOpenDatabase function.

Unlike many other traditional databases, opening and closing a database does not imply any transactioning. In other words, the database is not committed at the closing—it is committed after each individual call.

An application that opens the same database more then once and requests to be notified about changes to the database will receive change notification for changes that its process has made on the database. The reason is that change notification process is not done on a process level, but on a per open database level.

See Also

CeCloseHandle, CeCreateDatabase, CeSeekDatabase


CeOpenDatabase (RAPI)

This function opens an existing database. CeOpenDatabase (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CeOpenDatabase(PCEOID poid, LPWSTR lpszName, CEPROPID propid, DWORD dwFlags, HWND hwndNotify);

Parameters

poid
[in] Pointer to the object identifier of the database to be opened. To open a database by name, set the value pointed to by poid to zero to receive the object identifer of the newly opened database when a database name is specified for lpszName.
lpszName
[in] Pointer to the null-terminated string that contains the name of the database to be opened. This parameter is ignored if the value pointed to by poid is nonzero.
propid
[in] Property identifier of the primary key for the sort order in which the database is to be traversed. All subsequent calls to CeSeekDatabase assume this sort order. This parameter can be zero if the sort order is not important.
dwFlags
[in] Specifies a bitmask of action flags. It is one of the following values:
Value
Description
CEDB_AUTOINCREMENT | Causes the current seek position to be automatically incremented with each call to the CeReadRecordProps function.
0 (ZERO) | Current seek position is not incremented with each call to CeReadRecordProps.

hwndNotify
[in] Handle to the window to which notification messages (DB_CEOID_*) will be posted if another thread modifies the specified database while you have it open. This parameter can be NULL if you do not need to receive notifications.

Return Values

The handle to the open database indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information within a RAPI program, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_FILE_NOT_FOUND
No database exists with the specified name. This value applies only if the value pointed to by poid was set to NULL when the function was called.
ERROR_NOT_ENOUGH_MEMORY
No memory was available to allocate a database handle.

Remarks

Use the CeCloseHandle function to close the handle returned by the CeOpenDatabase function.

Unlike many other traditional databases, opening and closing a database does not imply any transactioning. In other words, the database is not committed at the closing—it is committed after each individual call.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegOpenDatabase function.

See Also

CeCreateDatabase (RAPI), CeSeekDatabase (RAPI)


CeOpenDatabaseEx

This function opens an existing database on any database volume, including mounted databases. A remote application interface (RAPI) version of this function exists, and it is also called CeOpenDatabaseEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE CeOpenDatabaseEx( PCEGUID pceguid, PCEOID poid,
LPWSTR lpszName, CEPROPID propid, DWORD dwFlags,
CENOTIFYREQUEST *pRequest hwndNotify );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database. If pceguid equals CREATE_INVALIDGUID, then poid is ignored, and the object store and all mounted databases are searched for a database whose name matches lpszName. The search is completed when the first match is located.
poid
[in] Pointer to the object identifier of the database to be opened. To open a database by name, set the value pointed to by poid to zero, set lpszName to the database name, and set pceguid to the database volume.
lpszName
[in] Long pointer to the null-terminated string that contains the name of the database to be opened. This is used along with pceguid to specify the database if the value pointed to by poid is zero. If the value pointed to by poid is nonzero, lpszName is ignored.
propid
[in] Property identifier of the primary sort key for the database. All subsequent calls to CeSeekDatabase assume this sort order. This parameter can be zero if the sort order is not important.
dwFlags
[in] Specifies an action flag. It is one of the following flags:
Value
Description
CEDB_AUTOINCREMENT | Current seek position is automatically incremented with each call to CeReadRecordPropsEx.
0 | Current seek position is not incremented with each call to CeReadRecordPropsEx.

pRequest
[in] Pointer to a CENOTIFICATION structure that requests notifications be sent to an identified window. This parameter can be NULL if an application does not need to receive notifications.

Return Values

A handle to the open database indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_FILE_NOT_FOUND
No database exists with the specified name. This error code applies only if the value pointed to by poid was set to NULL, when the function was called.
ERROR_NOT_ENOUGH_MEMORY
No memory was available to allocate the database handle.

Remarks

An application must use the CloseHandle function to close the handle returned by the CeOpenDatabaseEx function.

Changes to Windows CE databases are committed after each individual call, not when opening and closing a database.

See Also

CeCreateDatabaseEx, CeReadRecordPropsEx, CeSeekDatabase, CREATE_INVALIDGUID


CeOpenDatabaseEx (RAPI)

This function opens an existing database on any database volume, including mounted databases. CeOpenDatabaseEx (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE CeOpenDatabaseEx( PCEGUID pceguid, PCEOID poid,
LPWSTR lpszName, CEPROPID propid, DWORD dwFlags,
CENOTIFYREQUEST *pRequest hwndNotify );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database. If pceguid equals CREATE_INVALIDGUID, then poid is ignored, and the object store and all mounted databases are searched for a database whose name matches lpszName. The search is completed when the first match is located.
poid
[in] Pointer to the object identifier of the database to be opened. To open a database by name, set the value pointed to by poid to zero, set lpszName to the database name, and set pceguid to the database volume.
lpszName
[in] Long pointer to the null-terminated string that contains the name of the database to be opened. This is used along with pceguid to specify the database if the value pointed to by poid is zero. If the value pointed to by poid is nonzero, lpszName is ignored.
propid
[in] Property identifier of the primary sort key for the database. All subsequent calls to CeSeekDatabase (RAPI) assume this sort order. This parameter can be zero if the sort order is not important.
dwFlags
[in] Specifies an action flag. It is one of the following flags:
Value
Description
CEDB_AUTOINCREMENT | Current seek position is automatically incremented with each call to CeReadRecordPropsEx (RAPI).
0 | Current seek position is not incremented with each call to CeReadRecordPropsEx (RAPI).

pRequest
[in] Pointer to a CENOTIFICATION structure that requests notifications be sent to an identified window. This parameter can be NULL if an application does not need to receive notifications.

Return Values

A handle to the open database indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_FILE_NOT_FOUND
No database exists with the specified name. This error code applies only if the value pointed to by poid was set to NULL, when the function was called.
ERROR_NOT_ENOUGH_MEMORY
No memory was available to allocate the database handle.

Remarks

An application must use the CeCloseHandle function to close the handle returned by the CeOpenDatabaseEx (RAPI) function.

Changes to Windows CE databases are committed after each individual call, not when opening and closing a database.

See Also

CeCreateDatabaseEx (RAPI), CeReadRecordPropsEx (RAPI), CeSeekDatabase (RAPI), CREATE_INVALIDGUID


CeRapiFreeBuffer

This function frees the memory on the desktop computer allocated by a call to CeFindAllDatabases, CeFindAllFiles, or CeReadRecordProps.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CeRapiFreeBuffer( LPVOID Buffer );

Parameters

Buffer
[in] Pointer to the buffer to be freed.

Return Values

S_OK indicates success. E_FAIL indicates failure.

Remarks

Any RAPI function that allocates memory on the desktop computer on the users’ behalf must be freed by calling the CeRapiFreeBuffer function.

For Windows CE versions 1.0 and 1.01, the name of this function is RapiFreeBuffer.


CeRapiGetError

This function reports remote API related failures. CeRapiGetError can be used to determine if a call failed due to a failure in the remote API.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CeRapiGetError(void);

Return Values

This function returns standard Win32 error values.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

When writing applications for Windows CE versions 1.0 and 1.01, use the GetRapiError function.


CeRapiInit

This function attempts to initialize the Windows CE remote application programming interface (RAPI).

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CeRapiInit(void);

Return Values

E_SUCCESS indicates success. CERAPI_E_ALREADYINITIALIZED indicates that RAPI was already initialized. E_FAIL indicates failure.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

The functions CeRapiInit or CeRapiInitEx must be called before any remote API calls can be performed. They initialize the underlying communications layers between the desktop PC and the target platform device.

A call to CeRapiInit does not return until the connection is made, an error occurs, or another thread calls CeRapiUninit. The CeRapiInitEx function does not block the calling thread. Instead, it uses an event to signal when initialization is complete.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegRapiInit function.

See Also

CeRapiInitEx, RAPIINIT


CeRapiInitEx

This function attempts to initialize the Windows CE remote application programming interface (RAPI) and initially returns an event handle.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CeRapiInitEx(RAPIINIT* pRapiInit);

Parameters

pRapiInit
[in] Pointer to a RAPIINIT structure. The cbSize member of this structure contains the size of the structure being passed in. Initially, a handle to an event is passed back in the heRapiInit member of this structure. When the connection is made or an error occurs, the event is set. The hrRapiInit member of this structure contains the value E_SUCCESS if the connection is successful, CERAPI_E_ALREADYINITIALIZED if the RAPI was already initialized, or E_FAIL if an error occurred.

Return Values

E_SUCCESS indicates success. CERAPI_E_ALREADYINITIALIZED indicates that RAPI was already initialized. E_FAIL indicates failure.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

The CeRapiInitEx or CeRapiInit functions must be called before any remote API calls can be performed. They initialize the underlying communications layers between the desktop PC and the target platform device.

Call CeRapiInitEx to avoid blocking a thread inside of a call to CeRapiInit. CeRapiInitEx returns immediately and continues initialization until the connection is made, until an error occurs, or until there is a call to CeRapiUninit. When CeRapiInitEx is complete it then sets the event specified in the heRapiInit member of the RAPIINIT structure.

After calling CeRapiInitEx, check the return value to see if an error occurred. If the call was initially successful, call the MsgWaitForMultipleObjects function to wait on the event handle passed back in the heRapiInit member of the RAPIINIT structure. When the event is set, check the hrRapiInit member of the structure to determine if the connection was successful.

To shut down or to abort the connection process, call the CeRapiUnInit function.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegRapiInitEx function.

See Also

CeRapiInit, RAPIINIT


CeRapiInvoke

This function can be used as a general-purpose mechanism to remotely execute a routine on the Windows CE device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CeRapiInvoke( LPCWSTR pDllPath,
LPCWSTR pFunctionName, DWORD cbInput, BYTE *pInput,
DWORD *pcbOutput, BYTE **ppOutput, IRAPIStream **ppIRAPIStream, DWORD dwReserved );

Parameters

pDllPath
[in] Pointer to a buffer containing the name of a DLL on the Windows CE device containing pFunctionName.
pFunctionName
[in] Pointer to a buffer containing the name of the function that RAPI should call on the Windows CE device.
cbInput
[in] Number of bytes in the input buffer *pInput.
pInput
[in] Pointer to a buffer containing the input data.
cbOutput
[out] Pointer to a variable that is set to the number of bytes in the output buffer ppOutput when the function returns.
ppOutput
[out] Pointer to a variable that is set to the location of the output buffer upon return.
ppIRAPIStream
[in] Pointer to a variable that is set to the address of the IRAPIStream interface.
dwReserved
Reserved.

Return Values

If RAPI services on the Windows CE device successfully locate and call the client function, then in Block Mode the return value is that which is returned on the Windows CE device by the called function. In Stream Mode the return value is S_OK. If the function was not called successfully, or an exception occurred during its execution, an error code is returned.

The CeGetLastError function can be used to get the error code, which takes the value set by pFunctionName, including the following values:

ERROR_FILE_NOT_FOUND
The LoadLibrary pDllPath call failed on the device.
ERROR_CALL_NOT_IMPLEMENTED
The GetProcAddress of pFunctionName call on the device failed.
ERROR_EXCEPTION_IN_SERVICE
An exception occurred during execution of pFunctionName.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

An application should allocate memory for the pInput parameter with the LocalAlloc function. The memory is freed by the system. The system allocates memory for the ppOutput parameter. When the application is completed with the buffer, it should free the memory with the LocalFree function.

The CeRapiInvoke function operates in either block mode or stream mode.

In block mode, the caller passes the data in a single buffer as an input parameter and receives the response in a single buffer as an output parameter. This is a synchronous call, thus all input or output data must be present in memory at the time of the call.

In stream mode, the CeRapiInvoke function returns a pointer to an IStream type interface that can be used to exchange arbitrary sized data in any order and direction. In this mode, the caller can still pass data in a single buffer as an input parameter, but from that point on all data should be exchanged by means of the stream. Thus the data can be read, written, and stored in chunks.

Streaming is significantly faster than block mode.

The ppIRAPIStream parameter specifies block mode or stream mode. Select block mode by supplying the value NULL. Select stream mode by supplying a valid pointer to a variable of type IRAPIStream; this IRAPIStream interface can be used for a direct transfer of data. If ppIRAPIStream is not NULL, the pFunctionName parameter on the Windows CE device will be passed a pointer to the IRAPIStream interface.

The IRAPIStream definition is based on Istream and has been expanded by two new methods to allow the setting of timeouts. These methods, IRAPIStream::SetRapiStat and IRAPIStream::GetRapiStat,are modeled after the IStream::Stat method.

See Also

IRapiStream


CeRapiUninit

This function uninitializes the Windows CE remote application programming interface (RAPI).

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

STDAPI CeRapiUninit(void);

Return Values

E_FAIL indicates that RAPI was not originally initialized.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

The CeRapiUnInit function should be called when the application has completed its use of the remote API services. It gracefully closes down the connection to the Windows CE device. If called when not in an initialized state, it will return E_FAIL.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegRapiUninit function.


CeReadFile (RAPI)

This function reads data from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read.

CeReadFile is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeReadFile( HANDLE hFile, LPVOID lpBuffer,
DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped );

Parameters

hFile
[in] Handle to the file to be read. The file handle must have been created with GENERIC_READ access to the file. This parameter cannot be a socket handle.
lpBuffer
[out] Pointer to the buffer that receives the data read from the file.
nNumberOfBytesToRead
[in] Number of bytes to be read from the file.
lpNumberOfBytesRead
[out] Pointer to the number of bytes read. CeReadFile sets this value to zero before doing any work or error checking.
lpOverlapped
[in] Unsupported; set to NULL.

Return Values

The CeReadFile function returns when one of the following is true: the number of bytes requested has been read or an error occurs.

Nonzero indicates success. If the return value is nonzero and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read operation. Zero indicates failure. To get extended error information, call CeGetLastError.

Remarks

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes.

The ReadFile function may fail and return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. Windows CE does not support asynchronous read operations on files.

See Also

ReadFile , CeCreateFile (RAPI), CeWriteFile (RAPI)


CeReadRecordProps

This function reads properties from the current record. This function is obsolete. Applications should call CeReadRecordsPropsEx instead.

A remote application interface (RAPI) version of this function exists, and it is also called CeReadRecordProps.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeReadRecordProps(HANDLE hDbase, DWORD dwFlags, LPWORD lpcPropID, CEPROPID * rgPropID, LPBYTE * lplpBuffer, LPDWORD lpcbBuffer);

Parameters

hDbase
[in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabase function.
dwFlags
[in] Specifies a bitmask of read flags. It is the following value:
Value
Description
CEDB_ALLOWREALLOC The LocalAlloc function was used to allocate the buffer specified by the lplpBuffer parameter, and the server can reallocate the buffer if it is not large enough to hold the requested properties.

lpcPropID
[in] Pointer to the number of property identifiers in the array specified by the rgPropID parameter. If rgPropID is NULL, this parameter receives the number of properties retrieved.
rgPropID
[in] Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is NULL, CeReadRecordProps retrieves all properties in the record.
lplpBuffer
[out] Pointer to a long pointer to a buffer that receives the requested properties. If the dwFlags parameter includes the CEDB_ALLOWREALLOC flag, the buffer may be reallocated if necessary. If the CEDB_ALLOWREALLOC flag is specified and this parameter is NULL, the server uses the LocalAlloc function to allocate a buffer of the appropriate size in the caller's address space and returns a pointer to the buffer. Note that if the CEDB_ALLOWREALLOC flag is specified, it is possible for the value of this pointer to change even on failure. For example, the old memory might be freed and the allocation might then fail, leaving the pointer set to NULL.
lpcbBuffer
[out] Pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBuffer parameter. When CeReadRecordProps returns, lpcbBuffer receives a value that indicates the actual size of the data copied to the buffer. If the buffer was too small to contain the data, this parameter can be used to calculate the amount of memory to allocate for the buffer if CEDB_ALLOWREALLOC was not specified.

Return Values

The object identifier of the record from which the function read indicates success. Zero indicates failure. To get extended error information within a Windows CE program, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_NO_DATA
None of the requested properties was found. The output buffer and the size are valid.
ERROR_INSUFFICIENT_BUFFER
The specified buffer was not large enough, and the reallocation failed—if the CEDB_ALLOWREALLOC flag was specified. The lpcbBuffer parameter contains the required buffer size.
ERROR_KEY_DELETED
The record that was about to be read was deleted by another thread. If the current record was reached as a result of an autoseek, this error is not returned, and the next record is returned.
ERROR_NO_MORE_ITEMS
The current seek pointer is at the end of the database.

Remarks

The CeReadRecordProps function reads the specified set of properties from the current record. If the database was opened with the autoseek flag—that is, if the dwFlags parameter of CeOpenDatabase was set to CEDB_AUTOINCREMENT—CeReadRecordProps increments the seek pointer by one so that the next call reads the next record in the current sort order. That is, if the database was opened with a sort order active, then CeReadRecordProps will return the records in sorted order. If the database was not opened with a sort order active, then the order in which records are returned is not predictable.

Read all needed properties from the record in a single call. The entire record is stored in a compressed format, and each time a property is read it must be decompressed. All the properties are returned in a single marshalled structure, which consists of an array of CEPROPVAL structures, one for each property requested—or one for each property found if the application set the rgPropID parameter to NULL when calling the function.

If a property was requested, such as strings or blobs that are packed in at the end of the array, the pointers in the CEPROPVAL structures point into this marshalled structure. This means that the only memory that must be freed is the original pointer to the buffer passed in to the call. Even if the function fails, it may have allocated memory on the caller’s behalf. Free the pointer returned by this function if the pointer is not NULL.

See Also

LocalAlloc, LocalFree, CeOpenDatabase, CeSeekDatabase, CEPROPVAL


CeReadRecordProps (RAPI)

This function reads properties from the current record. CeReadRecordProps is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeReadRecordProps(HANDLE hDbase, DWORD dwFlags, LPWORD lpcPropID, CEPROPID * rgPropID, LPBYTE * lplpBuffer, LPDWORD lpcbBuffer);

Parameters

hDbase
[in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabase (RAPI) function.
dwFlags
[in] Specifies a bitmask of read flags. It is the following value:
Value
Description
CEDB_ALLOWREALLOC The LocalAlloc function was used to allocate the buffer specified by the lplpBuffer parameter, and the server can reallocate the buffer if it is not large enough to hold the requested properties.

lpcPropID
[in] Pointer to the number of property identifiers in the array specified by the rgPropID parameter. If rgPropID is NULL, this parameter receives the number of properties retrieved.
rgPropID
[in] Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is NULL, CeReadRecordProps retrieves all properties in the record.
lplpBuffer
[out] Pointer to a long pointer to a buffer that receives the requested properties. If the dwFlags parameter includes the CEDB_ALLOWREALLOC flag, the buffer may be reallocated if necessary. If the CEDB_ALLOWREALLOC flag is specified and this parameter is NULL, the server uses the LocalAlloc function to allocate a buffer of the appropriate size in the caller's address space and returns a pointer to the buffer. Note that if the CEDB_ALLOWREALLOC flag is specified, it is possible for the value of this pointer to change even on failure. For example, the old memory might be freed and the allocation might then fail, leaving the pointer set to NULL.
lpcbBuffer
[out] Long pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBuffer parameter. When CeReadRecordProps (RAPI) returns, lpcbBuffer receives a value that indicates the actual size of the data copied to the buffer. If the buffer was too small to contain the data, this parameter can be used to calculate the amount of memory to allocate for the buffer if CEDB_ALLOWREALLOC was not specified.

Return Values

The object identifier of the record from which the function read indicates success. Zero indicates failure. To get extended error information within a RAPI program, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_NO_DATA
None of the requested properties was found. The output buffer and the size are valid.
ERROR_INSUFFICIENT_BUFFER
The specified buffer was not large enough, and the reallocation failed—if the CEDB_ALLOWREALLOC flag was specified. The lpcbBuffer parameter contains the required buffer size.
ERROR_KEY_DELETED
The record that was about to be read was deleted by another thread. If the current record was reached as a result of an autoseek, this error is not returned, and the next record is returned.
ERROR_NO_MORE_ITEMS
The current seek pointer is at the end of the database.

Remarks

The CeReadRecordProps(RAPI) function reads the specified set of properties from the current record. If the database was opened with the autoseek flag—that is, if the dwFlags parameter of CeOpenDatabase (RAPI) was set to CEDB_AUTOINCREMENT—CeReadRecordProps (RAPI) increments the seek pointer by one so that the next call reads the next record in the current sort order. That is, if the database was opened with a sort order active, then CeReadRecordProps (RAPI) will return the records in sorted order. If the database was not opened with a sort order active, then the order in which records are returned is not predictable.

Read all needed properties from the record in a single call. The entire record is stored in a compressed format, and each time a property is read it must be decompressed. All the properties are returned in a single marshalled structure, which consists of an array of CEPROPVAL structures, one for each property requested—or one for each property found if the application set the rgPropID parameter to NULL when calling the function.

If a property was requested, such as strings or blobs that are packed in at the end of the array, the pointers in the CEPROPVAL structures point into this marshalled structure. This means that the only memory that must be freed is the original pointer to the buffer passed in to the call. Even if the function fails, it may have allocated memory on the caller’s behalf. Free the pointer returned by this function if the pointer is not NULL.

See Also

CeOpenDatabase (RAPI), CeSeekDatabase (RAPI), CEPROPVAL


CeReadRecordPropsEx

This function reads properties from the current record. A remote application interface (RAPI) version of this function exists, and it is also called CeReadRecordPropsEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

CEOID CeReadRecordPropsEx ( HANDLE hDbase, DWORD dwFlags,
LPWORD lpcPropID, CEGPROPID * rgPropID, LPBYTE * lplpBuffer,
LPDWORD lpcbBuffer, HANDLE hHeap );

Parameters

hDbase
[in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabaseEx function.
dwFlags
[in] Specifies read flags. It is one of the following flags:
Value
Description
0 | There are no special instructions for handling the read process.
CEDB_ALLOWREALLOC | The LocalAlloc function was used to allocate the buffer specified by the lplpBuffer parameter. The server can reallocate the buffer if it is not large enough to hold the requested properties.

lpcPropID
[in] Pointer to the number of property identifiers in the array specified by the rgPropID parameter. If rgPropID is NULL, this parameter receives the number of properties retrieved.
rgPropID
[in] Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is NULL, CeReadRecordPropsEx retrieves all properties in the record.
lplpBuffer
[out] Pointer to the address of a pointer to a buffer that receives the requested properties. If the dwFlags parameter includes the CEDB_ALLOWREALLOC flag, the buffer may be reallocated if necessary, even if the function fails. If the CEDB_ALLOWREALLOC flag is specified and lplpBuffer is NULL, the server allocates a buffer of the appropriate size in the caller's address space and returns a pointer to the buffer.
lpcbBuffer
[out] Pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBuffer parameter. When CeReadRecordPropsEx returns, lpcbBuffer receives a value that indicates the actual size of the data copied to the buffer. If the buffer was too small to contain the data and CEDB_ALLOWREALLOC was not specified, this parameter can be used to calculate the amount of memory to allocate for the buffer.
hHeap
[in] For Windows CE versions 2.10 and later, handle to a application-created heap to be used when reallocating memory. This parameter is only meaningful if the CEDB_ALLOWREALLOC flag is set.

Return Values

The object identifier of the record from which the function read indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_NO_DATA
None of the requested properties were found. The output buffer and the size are valid.
ERROR_INSUFFICIENT_BUFFER
The specified buffer was not large enough, and the reallocation failed if the CEDB_ALLOWREALLOC flag was specified. The lpcbBuffer parameter contains the required buffer size.
ERROR_KEY_DELETED
The record that was about to be read was deleted by another thread. If the current record was reached as a result of an autoseek, this error is not returned, and the next record is returned.
ERROR_NO_MORE_ITEMS
The current seek pointer is at the end of the database.

Remarks

The CeReadRecordPropsEx function reads the specified set of properties from the current record. If the dwFlags parameter of CeOpenDatabaseEx was set to CEDB_AUTOINCREMENT, the function increments the seek pointer so that the next call reads the next record in the current sort order. If there was no active sort order when the database was opened, then the order in which records are returned is not predictable.

You should read all needed properties from the record in a single call. This is because the entire record is stored in a compressed format, and each time a property is read it must be decompressed. All the properties are returned in a single marshaled structure, which consists of an array of CEPROPVAL structures. There is one CEPROPVAL structure for each property requested or, if rgPropID is NULL, there is one for each property found.

If a property was requested, such as strings or Binary Large Objects (BLOBs) that are packed in at the end of the array, the pointers in the CEPROPVAL structures point into this marshaled structure. This means that the only memory that must be freed is the original pointer to the buffer passed in to the call. Even if the function fails, it may have allocated memory on the caller’s behalf. You must free the pointer returned by this function if the pointer is not NULL.

See Also

CeOpenDatabaseEx, CEPROPVAL, CeSeekDatabase


CeReadRecordPropsEx (RAPI)

This function reads properties from the current record. CeReadRecordPropsEx is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.10 and later

Syntax

CEOID CeReadRecordPropsEx ( HANDLE hDbase, DWORD dwFlags,
LPWORD lpcPropID, CEGPROPID * rgPropID, LPBYTE * lplpBuffer,
LPDWORD lpcbBuffer, HANDLE hHeap );

Parameters

hDbase
[in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabaseEx (RAPI) function.
dwFlags
[in] Specifies read flags. It is one of the following flags:
Value
Description
0 | There are no special instructions for handling the read process.
CEDB_ALLOWREALLOC | The LocalAlloc function was used to allocate the buffer specified by the lplpBuffer parameter. The server can reallocate the buffer if it is not large enough to hold the requested properties.

lpcPropID
[in] Pointer to the number of property identifiers in the array specified by the rgPropID parameter. If rgPropID is NULL, this parameter receives the number of properties retrieved.
rgPropID
[in] Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is NULL, CeReadRecordPropsEx (RAPI) retrieves all properties in the record.
lplpBuffer
[out] Pointer to the address of a pointer to a buffer that receives the requested properties. If the dwFlags parameter includes the CEDB_ALLOWREALLOC flag, the buffer may be reallocated if necessary, even if the function fails. If the CEDB_ALLOWREALLOC flag is specified and lplpBuffer is NULL, the server allocates a buffer of the appropriate size in the caller's address space and returns a pointer to the buffer.
lpcbBuffer
[out] Pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBuffer parameter. When CeReadRecordPropsEx (RAPI) returns, lpcbBuffer receives a value that indicates the actual size of the data copied to the buffer. If the buffer was too small to contain the data and CEDB_ALLOWREALLOC was not specified, this parameter can be used to calculate the amount of memory to allocate for the buffer.
hHeap
[in] For Windows CE versions 2.10 and later, handle to a application-created heap to be used when reallocating memory. This parameter is only meaningful if the CEDB_ALLOWREALLOC flag is set.

Return Values

The object identifier of the record from which the function read indicates success. Zero indicates failure. To get extended error information, call CeGetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_NO_DATA
None of the requested properties were found. The output buffer and the size are valid.
ERROR_INSUFFICIENT_BUFFER
The specified buffer was not large enough, and the reallocation failed if the CEDB_ALLOWREALLOC flag was specified. The lpcbBuffer parameter contains the required buffer size.
ERROR_KEY_DELETED
The record that was about to be read was deleted by another thread. If the current record was reached as a result of an autoseek, this error is not returned, and the next record is returned.
ERROR_NO_MORE_ITEMS
The current seek pointer is at the end of the database.

Remarks

The CeReadRecordPropsEx (RAPI) function reads the specified set of properties from the current record. If the dwFlags parameter of CeOpenDatabaseEx (RAPI) was set to CEDB_AUTOINCREMENT, the function increments the seek pointer so that the next call reads the next record in the current sort order. If there was no active sort order when the database was opened, then the order in which records are returned is not predictable.

You should read all needed properties from the record in a single call. This is because the entire record is stored in a compressed format, and each time a property is read it must be decompressed. All the properties are returned in a single marshaled structure, which consists of an array of CEPROPVAL structures. There is one CEPROPVAL structure for each property requested or, if rgPropID is NULL, there is one for each property found.

If a property was requested, such as strings or Binary Large Objects (BLOBs) that are packed in at the end of the array, the pointers in the CEPROPVAL structures point into this marshaled structure. This means that the only memory that must be freed is the original pointer to the buffer passed in to the call. Even if the function fails, it may have allocated memory on the caller’s behalf. You must free the pointer returned by this function if the pointer is not NULL.

See Also

CeOpenDatabaseEx (RAPI), CEPROPVAL, CeSeekDatabase (RAPI)


CeRegCloseKey (RAPI)

This function releases the handle of the specified key. CeRegCloseKey is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegCloseKey( HKEY hKey );

Parameters

hKey
[in] Handle to the open key to close.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The handle for a specified key should not be used after it has been closed, because it will no longer be valid. Key handles should not be left open any longer than necessary.

The CeRegCloseKey function always writes information to the registry before returning, eliminating the need to flush keys in the Windows CE registry.

See Also

CeRegCreateKeyEx (RAPI), CeRegDeleteKey (RAPI), CeRegOpenKeyEx (RAPI), CeRegSetValueEx (RAPI)


CeRegCreateKeyEx (RAPI)

This function creates the specified key. If the key already exists in the registry, the function opens it. CeRegCreateKeyEx is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegCreateKeyEx( HKEY hKey, LPCWSTR lpszSubKey,
DWORD Reserved, LPWSTR lpszClass, DWORD dwOptions,
REGSAM samDesired, LPSECURITY_ATTRIBUTES lpSecurityAttributes,
PHKEY phkResult, LPDWORD lpdwDisposition );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

Windows CE does not support the HKEY_CURRENT_CONFIG, HKEY_PERFORMANCE_DATA, or HKEY_DYN_DATA predefined reserved handle values.

The key opened or created by the CeRegCreateKeyEx function is a subkey of the key identified by the hKey parameter.

lpSubKey
[in] Pointer to a null-terminated string specifying the name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter. This subkey must not begin with the backslash character (‘\’). This parameter cannot be NULL. In Windows CE, the maximum length of a key name is 255 characters, not including the terminating NULL character. You can also only nest 16 levels of sub-keys in Windows CE.
Reserved
[in] Reserved; set to 0.
lpClass
[in] Pointer to a null-terminated string that specifies the class (object type) of this key. This parameter is ignored if the key already exists. In Windows CE, the maximum length of a class string is 255 characters, not including the terminating NULL character.
dwOptions
[in] Ignored; set to 0 to ensure compatibility with future versions of Windows CE.
samDesired
[in] Ignored; set to 0 to ensure compatibility with future versions of Windows CE.
lpSecurityAttributes
[in] Set to NULL. Windows CE automatically assigns the key a default security descriptor.
phkResult
[out] Pointer to a variable that receives a handle to the opened or created key. When you no longer need the returned handle, call the CeRegCloseKey function to close it.
lpdwDisposition
[out] Pointer to a variable that receives one of the following disposition values:
Value
Description
REG_CREATED_NEW_KEY | The key did not exist and was created.
REG_OPENED_EXISTING_KEY | The key existed and was simply opened without being changed.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key that the CeRegCreateKeyEx function creates has no values. An application can use the CeRegSetValueEx function to set key values.

The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access. To open the key, use the CeRegCreateKeyEx or CeRegOpenKeyEx function.

CeRegCreateKeyEx can create keys under the HKEY_LOCAL_MACHINE and HKEY_USERS registries.

An application can use CeRegCreateKeyEx to temporarily lock a portion of the registry. When the locking process creates a new key, it receives the disposition value REG_CREATED_NEW_KEY, indicating that it “owns” the lock. Another process attempting to create the same key receives the disposition value REG_OPENED_EXISTING_KEY, indicating that another process already owns the lock.

See Also

CeRegDeleteKey (RAPI)


CeRegDeleteKey (RAPI)

This function deletes a named subkey from the specified registry key. The subkey to be deleted cannot have any subkeys.

CeRegDeleteKey is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegDeleteKey( HKEY hKey, LPCWSTR lpszSubKey );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The key specified by the lpSubKey parameter must be a subkey of the key identified by hKey.

lpSubKey
[in] Pointer to a null-terminated string specifying the name of the key to delete. This parameter cannot be NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

If the function succeeds, CeRegDeleteKey removes the specified key from the registry. The entire key, including all of its values, is removed. An application cannot call CeRegDeleteKey for a key that an application currently has open.

To open the key, use the CeRegCreateKeyEx or CeRegOpenKeyEx function.

See Also

CeRegCloseKey (RAPI), CeRegCreateKeyEx (RAPI), CeRegOpenKeyEx (RAPI)


CeRegDeleteValue (RAPI)

This function removes a named value from the specified registry key. CeRegDeleteValue is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegDeleteValue( HKEY hKey, LPCWSTR lpszValueName );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpValueName
[in] Pointer to a null-terminated string that names the value to remove. If this parameter is NULL or points to an empty string, the default value of the key is removed. A default value is create by calling CeRegCreateValueEx with a NULL or empty string value name.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).

See Also

CeRegSetValueEx (RAPI)


CeRegEnumKeyEx (RAPI)

This function enumerates subkeys of the specified open registry key. CeRegEnumKeyEx retrieves information about one subkey each time it is called and it retrieves the class name of the subkey and the time it was last modified.

CeRegEnumKeyEx is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegEnumKeyEx(HKEY hKey, DWORD dwIndex,
LPWSTR lpName, LPDWORD lpcbName, LPDWORD lpReserved,
LPWSTR lpClass, LPDWORD lpcbClass, PFILETIME lpftLastWriteTime );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The enumerated keys are subkeys of the key identified by hKey.

dwIndex
[in] Specifies the index of the subkey to retrieve. This parameter should be zero for the first call to the CeRegEnumKeyEx function and then incremented for subsequent calls.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.

lpName
[out] Pointer to a buffer that receives the name of the subkey, including the terminating null character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.
lpcbName
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer specified by the lpName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.
lpReserved
[in] Reserved; set to NULL.
lpClass
[out] Pointer to a buffer that contains the class of the enumerated subkey when the function returns. This parameter can be NULL if the class is not required.
lpcbClass
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer specified by the lpClass parameter. The size should include the terminating null character. When the function returns, lpcbClass contains the number of characters stored in the buffer. The count returned does not include the terminating null character. This parameter can be NULL only if lpClass is NULL.
lpftLastWriteTime
[in] Ignored; set to NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

To enumerate subkeys, an application should initially call the CeRegEnumKeyEx function with the dwIndex parameter set to zero. An application should then increment the dwIndex parameter and call CeRegEnumKeyEx until there are no more subkeys (until the function returns ERROR_NO_MORE_ITEMS).

An application can also set dwIndex to the index of the last subkey on the first call to the function and decrement the index until the subkey with the index 0 is enumerated. To retrieve the index of the last subkey, use the CeRegQueryInfoKey function.

While an application is using the CeRegEnumKeyEx function, it should not make calls to any registration functions that might change the key being enumerated.

The key identified by hKey must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ includes KEY_ENUMERATE_SUB_KEYS). Use the CeRegCreateKeyEx or CeRegOpenKeyEx function to open the key.

See Also

CeRegCreateKeyEx (RAPI), CeRegDeleteKey (RAPI), CeRegOpenKeyEx (RAPI), CeRegQueryInfoKey (RAPI)


CeRegEnumValue (RAPI)

This function enumerates the values for the specified open registry key. CeRegEnumValue copies one indexed value name and data block for the key each time it is called.

CeRegEnumValue is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegEnumValue( HKEY hKey, DWORD dwIndex,
LPWSTR lpszValueName, LPDWORD lpcchValueName,
LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData,
LPDWORD lpcbData );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The enumerated values are associated with the key identified by hKey.

dwIndex
[in] Specifies the index of the value to retrieve. This parameter should be zero for the first call to the CeRegEnumValue function and then be incremented for subsequent calls.

Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.

lpValueName
[out] Pointer to a buffer that receives the name of the value, including the terminating null character.
lpcbValueName
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbValueName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.
lpReserved
[in] Reserved; set to NULL.
lpType
[out] Pointer to a variable that receives the type code for the value entry. The type code can be one of the following values:
Value
Description
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format. This is equivalent to REG_DWORD.
In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format.
In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.

The lpType parameter can be NULL if the type code is not required.

lpData
[out] Pointer to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required.
lpcbData
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if lpData is NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

To enumerate values, an application should initially call the CeRegEnumValue function with the dwIndex parameter set to zero. The application should then increment dwIndex and call the CeRegEnumValue function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0 is enumerated. To retrieve the index of the last value, use the CeRegQueryInfoKey function.

While using CeRegEnumValue, an application should not call any registration functions that might change the key being queried.

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the CeRegCreateKeyEx or CeRegOpenKeyEx function.

To determine the maximum size of the name and data buffers, use the CeRegQueryInfoKey function.

See Also

CeRegCreateKeyEx (RAPI), CeRegEnumKeyEx (RAPI), CeRegOpenKeyEx (RAPI), CeRegQueryInfoKey (RAPI)


CeRegOpenKeyEx (RAPI)

This function opens the specified key. CeRegOpenKeyEx is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegOpenKeyEx( HKEY hKey, LPCWSTR lpszSubKey,
DWORD ulOptions, REGSAM samDesired, PHKEY phkResult );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

Windows CE does not support the HKEY_CURRENT_CONFIG, HKEY_PERFORMANCE_DATA, or HKEY_DYN_DATA predefined reserved handle values.

lpSubKey
[in] Pointer to a null-terminated string containing the name of the subkey to open. If this parameter is NULL or a pointer to an empty string, the function will open a new handle to the key identified by the hKey parameter. In this case, the function will not close the handles previously opened.
ulOptions
[in] Reserved; set to 0.
samDesired
[in] Not supported; set to zero.
phkResult
[out] Pointer to a variable that receives a handle to the opened key. When you no longer need the returned handle, call the CeRegCloseKey function to close it.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

Unlike the CeRegCreateKeyEx function, the CeRegOpenKeyEx function does not create the specified key if the key does not exist in the registry.

See Also

CeRegCreateKeyEx (RAPI), CeRegDeleteKey (RAPI)


CeRegQueryInfoKey (RAPI)

This function retrieves information about a specified registry key. CeRegQueryInfoKey is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegQueryInfoKey ( HKEY hKey, LPWSTR lpClass,
LPDWORD lpcbClass, LPDWORD lpReserved, LPDWORD lpcSubKeys,
LPDWORD lpcbMaxSubKeyLen, LPDWORD lpcbMaxClassLen,
LPDWORD lpcValues, LPDWORD lpcbMaxValueNameLen,
LPDWORD lpcbMaxValueLen, LPDWORD lpcbSecurityDescriptor,
PFILETIME lpftLastWriteTime );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpClass
[out] Pointer to a buffer that receives the key’s class name. This parameter can be NULL.
lpcbClass
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpClass parameter. This size should include the terminating null character. When the function returns, this variable contains the length of the class string stored in the buffer. The count returned does not include the terminating null character. If the buffer is not big enough, the function returns ERROR_MORE_DATA, and the variable contains the size of the string, in characters, without counting the null character.

If lpClass is NULL, lpcbClass can be NULL.

If the lpClass parameter is a valid address, but this parameter is not, the function returns ERROR_INVALID_PARAMETER.

lpReserved
[in] Reserved; set to NULL.
lpcSubKeys
[out] Pointer to a variable that receives the number of subkeys contained by the specified key. This parameter can be NULL.
lpcbMaxSubKeyLen
[out] Pointer to a variable that receives the length, in characters, of the key’s subkey with the longest name. The count returned does not include the terminating null character. This parameter can be NULL.
lpcbMaxClassLen
[out] Pointer to a variable that receives the length, in characters, of the longest string specifying a subkey class. The count returned does not include the terminating null character. This parameter can be NULL.
lpcValues
[out] Pointer to a variable that receives the number of values associated with the key. This parameter can be NULL.
lpcbMaxValueNameLen
[out] Pointer to a variable that receives the length, in characters, of the key’s longest value name. The count returned does not include the terminating null character. This parameter can be NULL.
lpcbMaxValueLen
[out] Pointer to a variable that receives the length, in bytes, of the longest data component among the values of the key. This parameter can be NULL.
lpcbSecurityDescriptor
[in] Not used; set to NULL.
lpftLastWriteTime
[in] Ignored; set to NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

See Also

CeRegDeleteKey (RAPI), CeRegEnumKeyEx (RAPI), CeRegEnumValue (RAPI), CeRegQueryValueEx (RAPI)


CeRegQueryValueEx (RAPI)

This function retrieves the type and data for a specified value name associated with an open registry key. CeRegQueryValueEx is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegQueryValueEx( HKEY hKey, LPCWSTR lpValueName,
LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData,
LPDWORD lpcbData );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpValueName
[in] Pointer to a string containing the name of the value to query. If this parameter is NULL or an empty string, the function retrieves the type and data for the key’s unnamed value. A registry key does not automatically have an unnamed or default value. Unnamed values can be of any type.
lpReserved
[in] Reserved; set to NULL.
lpType
[out] Pointer to a variable that receives the type of data associated with the specified value. The value returned through this parameter will be one of the following:
Value
Description
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format. This is equivalent to REG_DWORD.
In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format.
In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”).
REG_LINK | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string.

The lpType parameter can be NULL if the type is not required.

lpData
[out] Pointer to a buffer that receives the value’s data. This parameter can be NULL if the data is not required.
lpcbData
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, this variable contains the size of the data copied to lpData.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then lpcbData will also include the size of the terminating null character.

The lpcbData parameter can be NULL only if lpData is NULL.

If the buffer specified by lpData parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbData.

If lpData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData. This lets an application determine the best way to allocate a buffer for the value’s data.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key identified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the CeRegCreateKeyEx or CeRegOpenKeyEx function.

Windows CE supports only the Unicode version of this function.

See Also

CeRegCreateKeyEx (RAPI), CeRegEnumKeyEx (RAPI), CeRegEnumValue (RAPI), CeRegOpenKeyEx (RAPI), CeRegQueryInfoKey (RAPI)


CeRegSetValueEx (RAPI)

This function stores data in the value field of an open registry key. It can also set additional value and type information for the specified key. CeRegSetValueEx is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

LONG CeRegSetValueEx( HKEY hKey, LPCWSTR lpValueName,
DWORD Reserved, DWORD dwType, const BYTE *lpData, DWORD cbData );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpValueName
[in] Pointer to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key. If this parameter is NULL or an empty string, the function sets the type and data for the key’s unnamed value. Registry keys do not have default values, but they can have one unnamed value, which can be of any type. The maximum length of a value name is 255, not including the terminating NULL character.
Reserved
[in] Reserved; must be zero.
dwType
[in] Specifies the type of information to be stored as the value’s data. This parameter can be one of the following values:
Value
Description
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format. This is equivalent to REG_DWORD.
In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format.
In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”).
REG_LINK | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string.
Do not use the REG_SZ type to store hard-coded paths to the system root directory or to the drive containing the system files. Instead, use the REG_EXPAND_SZ type with environment variables such as "%SystemRoot%". This ensures that the path will be up-to-date even if the user remaps the system drive to a different drive letter.

lpData
[in] Pointer to a buffer containing the data to be stored with the specified value name.
cbData
[in] Specifies the size, in bytes, of the information pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating null character. The maximum size of data allowed in Windows CE is 4 KB.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the CeRegCreateKeyEx or CeRegOpenKeyEx function.

Windows CE supports only the Unicode version of this function.

See Also

CeRegCreateKeyEx (RAPI), CeRegOpenKeyEx (RAPI), CeRegQueryValueEx (RAPI)


CeRemoveDirectory (RAPI)

This function deletes an existing empty directory. CeRemoveDirectory is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeRemoveDirectory(LPCWSTR lpPathName);

Parameters

lpPathName
[in] Long pointer to a null-terminated string that specifies the path of the directory to be removed. The path must specify an empty directory, and the calling process must have delete access to the directory.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

This function is a part of the remote application programming interface (RAPI), which invokes function calls on a Windows CE–based device. RAPI functions are supported only for applications that run on desktop platforms.

When writing applications for Windows CE versions 1.0 and 1.01, use the PegRemoveDirectory function.

See Also

RemoveDirectory


CeRunAppAtEvent

This function starts running an application when a specified event occurs.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeRunAppAtEvent(TCHAR *pwszAppName, LONG lWhichEvent);

Parameters

pwszAppName
[in] Pointer to a null-terminated string that specifies the name of the application to be started.
lWhichEvent
[in] Event at which the application is to be started. It is one of the following values:
Value
Description
NOTIFICATION_EVENT_NONE | No events—remove all event registrations for this application.
NOTIFICATION_EVENT_SYNC_END | When data synchronization finishes.
NOTIFICATION_EVENT_DEVICE_CHANGE | When a PC Card device is changed.
NOTIFICATION_EVENT_RS232_DETECTED | When an RS232 connection is made.
NOTIFICATION_EVENT_TIME_CHANGE | When the system time is changed.
NOTIFICATION_EVENT_RESTORE_END | When a full device data restore completes.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The application is started with a system-defined command line. If there was already an instance of the application running, the new instance must send a private message to the existing instance and then shut down. The command line, which corresponds to the registered event, can be one of the following string constants.

Constant
Value
APP_RUN_AFTER_SYNC | “AppRunAfterSync”
APP_RUN_AT_AC_POWER_ON | “AppRunAtAcPowerOn”
APP_RUN_AT_AC_POWER_OFF | “AppRunAtAcPowerOff”
APP_RUN_AT_NET_CONNECT | “AppRunAtNetConnect”
APP_RUN_AT_NET_DISCONNECT | “AppRunAtNetDisconnect”
APP_RUN_AT_DEVICE_CHANGE | “AppRunDeviceChange”
APP_RUN_AT_IR_DISCOVERY | “AppRunAtIrDiscovery”
APP_RUN_AT_RS232_DETECT | “AppRunAtRs232Detect”
APP_RUN_AFTER_RESTORE | “AppRunAfterRestore”

The string values in this table are processed as command line commands. In some cases, the part of the command line that follows the string is treated as a parameter.

Use the CeRunAppAtEvent function sparingly, because automatically starting an application can confuse the user and cause low-memory conditions on a machine with restricted memory. Ideally, the application should be small and non-intrusive.

The following constants are defined in the header file, but they are not supported:

NOTIFICATION_EVENT_IR_DISCOVERED
NOTIFICATION_EVENT_NET_CONNECT
NOTIFICATION_EVENT_NET_DISCONNECT
NOTIFICATION_EVENT_OFF_AC_POWER
NOTIFICATION_EVENT_ON_AC_POWER

See Also

CeRunAppAtTime


CeRunAppAtTime

This function prompts the system to start running a specified application at a specified time.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeRunAppAtTime(TCHAR *pwszAppName,
SYSTEMTIME *lpTime);

Parameters

pwszAppName
[in] Pointer to a null-terminated string that specifies the name of the application to be run.
lpTime
[in] Long pointer to a SYSTEMTIME structure that specifies the time when the given application is to be run.

If this parameter is NULL, the existing run request is deleted and no new request is entered. The deleted run request must have been initiated by a call to CeRunAppAtTime.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Calling the CeRunAppAtTime function replaces any previous run request for the specified application.

The system passes the APP_RUN_AT_TIME string to the application as the command line. If an instance of the application is already running, the new instance must send a private message to the existing instance and then shut down.

Use CeRunAppAtTime sparingly because automatically starting an application can confuse the user and cause low-memory conditions on a machine with restricted memory. Ideally, the application should be small and non-intrusive.

See Also

CeRunAppAtEvent


CeSeekDatabase

This function seeks the specified record in an open database. A remote application interface (RAPI) version of this function exists, and it is also called CeSeekDatabase.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeSeekDatabase(HANDLE hDatabase, DWORD dwSeekType, DWORD dwValue, LPDWORD lpdwIndex);

Parameters

hDatabase
[in] Handle to the open database in which to seek.
dwSeekType
[in] Specifies the type of seek operation to perform. It is one of the following values:
Value
Description
CEDB_SEEK_CEOID | Seek until finding an object that has the specified object identifier. The dwValue parameter specifies the object identifier. This type of seek operation is very efficient.
CEDB_SEEK_VALUESMALLER | Seek until finding the largest value that is smaller than the specified value. If none of the records has a smaller value, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_VALUEFIRSTEQUAL | Seek until finding the first value that is equal to the specified value. If the seek operation fails, the seek pointer is left pointing at the end of the database, and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_VALUENEXTEQUAL | Starting from the current seek position, seek exactly one position forward in the sorted order and check if the next record is equal in value to the specified value. If so, return the object identifier of this next record; otherwise, return zero and leave the seek pointer at the end of the database. This operation can be used in conjunction with the CEDB_SEEK_VALUEFIRSTEQUAL operation to enumerate all records with an equal value. The dwValue parameter specifies the value for which to seek.
CEDB_SEEK_VALUEGREATER | Seek until finding a value greater than or equal to the specified value. If all records are smaller, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_BEGINNING | Seek until finding the record at the specified position from the beginning of the database. The dwValue parameter specifies the number of records to seek.
CEDB_SEEK_CURRENT | Seek backward or forward from the current position of the seek pointer for the specified number of records. The dwValue parameter specifies the number of records from the current position. The function seeks forward if dwValue is a positive value, or backward if it is negative. A forward seek operation is efficient.
CEDB_SEEK_END | Seek backward for the specified number of records from the end of the database. The dwValue parameter specifies the number of records.

dwValue
[in] Specifies the value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType.
lpdwIndex
[out] Pointer to a variable that receives the index from the start of the database to the beginning of the record that was found.

Return Values

The object identifier of the record on which the seek ends indicates success. Zero indicates failure. To get extended error information within a CE program, call GetLastError. GetLastError may return ERROR_INVALID_PARAMETER if a parameter is invalid.

Remarks

The CeSeekDatabase function always uses the current sort order as specified in the call to the CeOpenDatabaseEx function. If the CEDB_AUTOINCREMENT flag was specified, an automatic seek of one from the current position is done with each read operation that occurs on the database. If a seeks fails then the record pointer points to the same record as before the seek operation.

Note that a seek can only be performed on a sorted property value. After creating a database (using CeCreateDatabaseEx) and opening the database (using CeOpenDatabaseEx), subsequent calls to CeSeekDatabase assume the sort order that was specified in the propid parameter of the call to CeOpenDatabaseEx.

To enter negative values for the CEDB_SEEK_CURRENT case, cast a signed long. This changes the effective range on the record indexes to 31 bits from 32.

Multiple sort orders cannot be specified for a single property.

When a CEPROPVAL structure is required to seek operation, the propid parameter must be set to the PROPID of the sort order specified in the CeOpenDatabaseEx call.

See Also

CeCreateDatabaseEx, CeOpenDatabaseEx, CEPROPVAL


CeSeekDatabase (RAPI)

This function seeks the specified record in an open database. CeSeekDatabase (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeSeekDatabase(HANDLE hDatabase, DWORD dwSeekType, DWORD dwValue, LPDWORD lpdwIndex);

Parameters

hDatabase
[in] Handle to the open database in which to seek.
dwSeekType
[in] Specifies the type of seek operation to perform. It is one of the following values:
Value
Description
CEDB_SEEK_CEOID | Seek until finding an object that has the specified object identifier. The dwValue parameter specifies the object identifier. This type of seek operation is very efficient.
CEDB_SEEK_VALUESMALLER | Seek until finding the largest value that is smaller than the specified value. If none of the records has a smaller value, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_VALUEFIRSTEQUAL | Seek until finding the first value that is equal to the specified value. If the seek operation fails, the seek pointer is left pointing at the end of the database, and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_VALUENEXTEQUAL | Starting from the current seek position, seek exactly one position forward in the sorted order and check if the next record is equal in value to the specified value. If so, return the object identifier of this next record; otherwise, return zero and leave the seek pointer at the end of the database. This operation can be used in conjunction with the CEDB_SEEK_VALUEFIRSTEQUAL operation to enumerate all records with an equal value. The dwValue parameter specifies the value for which to seek.
CEDB_SEEK_VALUEGREATER | Seek until finding a value greater than or equal to the specified value. If all records are smaller, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_BEGINNING | Seek until finding the record at the specified position from the beginning of the database. The dwValue parameter specifies the number of records to seek.
CEDB_SEEK_CURRENT | Seek backward or forward from the current position of the seek pointer for the specified number of records. The dwValue parameter specifies the number of records from the current position. The function seeks forward if dwValue is a positive value, or backward if it is negative. A forward seek operation is efficient.
CEDB_SEEK_END | Seek backward for the specified number of records from the end of the database. The dwValue parameter specifies the number of records.

dwValue
[in] Specifies the value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType.
lpdwIndex
[out] Pointer to a variable that receives the index from the start of the database to the beginning of the record that was found.

Return Values

The object identifier of the record on which the seek ends indicates success. Zero indicates failure. To get extended error information a RAPI program, call CeGetLastError. CeGetLastError may return ERROR_INVALID_PARAMETER if a parameter is invalid.

Remarks

The CeSeekDatabase (RAPI) function always uses the current sort order as specified in the call to the CeOpenDatabase (RAPI) function. If the CEDB_AUTOINCREMENT flag was specified, an automatic seek of one from the current position is done with each read operation that occurs on the database.

Note that a seek can only be performed on a sorted property value. After creating a database using CeCreateDatabaseEx (RAPI) and opening the database using CeOpenDatabaseEx (RAPI), subsequent calls to CeSeekDatabase (RAPI) assume the sort order that was specified in the propid parameter of the call to CeOpenDatabaseEx (RAPI).

To enter negative values for the CEDB_SEEK_CURRENT case, cast a signed long. This changes the effective range on the record indexes to 31 bits from 32.

Multiple sort orders cannot be specified for a single property.

When a CEPROPVAL structure is required to seek, the propid parameter must be set to PROPID of the sort order specified in the CeOpenDatabaseEx (RAPI) call.

See Also

CeCreateDatabase (RAPI), CeOpenDatabase (RAPI), CEPROPVAL


CeSetDatabaseInfo

This function sets various database parameters, including the name, type, and sort-order descriptions. This function is obsolete. Applications should call CeSetDataBaseInfoEx instead.

A remote application interface (RAPI) version of this function exists, and it is also called CeSetDatabaseInfo.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeSetDatabaseInfo(CEOID oidDbase, CEDBASEINFO * pNewInfo);

Parameters

oidDbase
[in] Object identifier of the database for which parameters are to be set.
pNewInfo
[in] Pointer to a CEDBASEINFO structure that contains new parameter information for the database. The wNumRecords member of the structure is not used.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information within a Windows CE program, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_DISK_FULL
The object store is full and any size changes required could not be accommodated. Changing sort orders can change the size of the stored records, though not by much.
ERROR_SHARING_VIOLATION
CeSetDatabaseInfo tried to remove a sort order that is being used by a currently open database.

Remarks

The CeSetDatabaseInfo function can be used to change the database parameters passed in while creating the database. Note that changing the sort order of the database can take several minutes. Before calling CeSetDatabaseInfo, an application should warn the user that this operation can be lengthy.

See Also

CeCreateDatabase, CEDBASEINFO, CeOidGetInfo


CeSetDatabaseInfo (RAPI)

This function sets various database parameters, including the name, type, and sort-order descriptions. CeSetDatabaseInfo (RAPI) is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CeSetDatabaseInfo(CEOID oidDbase, CEDBASEINFO * pNewInfo);

Parameters

oidDbase
[in] Object identifier of the database for which parameters are to be set.
pNewInfo
[in] Pointer to a CEDBASEINFO structure that contains new parameter information for the database. The wNumRecords member of the structure is not used.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information within a RAPI program, call CeGetLastError. Possible values for CeGetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_DISK_FULL
The object store is full and any size changes required could not be accommodated. Changing sort orders can change the size of the stored records, though not by much.
ERROR_SHARING_VIOLATION
CeSetDatabaseInfo tried to remove a sort order that is being used by a currently open database.

Remarks

The CeSetDatabaseInfo (RAPI) function can be used to change the database parameters passed in while creating the database. Note that changing the sort order of the database can take several minutes. Before calling CeSetDatabaseInfo (RAPI), an application should warn the user that this operation can be lengthy.

See Also

CeCreateDatabase (RAPI), CEDBASEINFO, CeOidGetInfo (RAPI)


CeSetDatabaseInfoEx

This function sets various database parameters, including the name, type, sort-order descriptions, and compression of the database.

A remote application interface (RAPI) version of this function exists, and it is also called CeSetDatabaseInfoEx.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeSetDatabaseInfoEx( PCEGUID pceguid, CEOID oidDbase,
CEDBASEINFO * pNewInfo );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database.
oidDbase
[in] Object identifier of the database for which parameters are to be set.
pNewInfo
[in] Pointer to a CEDBASEINFO structure that contains new parameter information for the database. The wNumRecords member of the structure is not used.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

ERROR_INVALID_PARAMETER
A parameter was invalid.
ERROR_DISK_FULL
The object store or mounted volume is full and any size changes required could not be accommodated. Changing sort orders can minimally change the size of the stored records.
ERROR_SHARING_VIOLATION
The CeSetDatabaseInfoEx function tried to remove a sort order that is being used by a currently open database.

Remarks

Use CeSetDatabaseInfoEx to change the database parameters passed in while creating the database. Changing the sort order or compression of a database is a very expensive operation, possibly taking a few minutes. Before calling this function, warn the user that this is a lengthy process.

See Also

CeCreateDatabaseEx, CEDBASEINFO, CeOidGetInfoEx, CREATE_SYSTEMGUID


CeSetEndOfFile (RAPI)

This function moves the end-of-file position for the specified file to the current position of the file pointer. CeSetEndOfFile is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeSetEndOfFile( HANDLE hFile );

Parameters

hFile
[in] Handle to the file to have its EOF position moved. The file handle must have been created with GENERIC_WRITE access to the file.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError.

Remarks

This function can be used to truncate or extend a file. If the file is extended, the contents of the file between the old EOF position and the new position are not defined.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegSetEndOfFile function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

CeCreateFile (RAPI)


CeSetFileAttributes (RAPI)

This function sets a file's attributes. CeSetFileAttributes is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeSetFileAttributes(LPCWSTR lpFileName,
DWORD dwFileAttributes);

Parameters

lpFileName
[in] Long pointer to a null-terminated string that specifies the name of the file whose attributes are to be set.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the CeSetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by prepending “\\?\” to the path. However, each component in the path cannot be more than MAX_PATH characters long. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with CeSetFileAttributes. However, each component in the path cannot be more than MAX_PATH characters long. This also works with Universal Naming Convention (UNC) names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private” and “\\?\UNC\wow\hotstuff\coolapps” is seen as “\\wow\hotstuff\coolapps.”

dwFileAttributes
[in] Specifies the file attributes to set for the file. This parameter can be a combination of the following values. However, all other values override FILE_ATTRIBUTE_NORMAL.
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_HIDDEN | The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE | The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY | The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM | The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY | The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.

Return Values

Nonzero indicates success. Zero indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError. To determine if a function failed because of non-RAPI errors, call CeGetLastError.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegSetFileAttributes function.

See Also

SetFileAttributes


CeSetFilePointer (RAPI)

This function moves the file pointer of an open file. CeSetFilePointer is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeSetFilePointer( HANDLE hFile, LONG lDistanceToMove,
PLONG lpDistanceToMoveHigh, DWORD dwMoveMethod );

Parameters

hFile
[in] Handle to the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.
lDistanceToMove
Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. If lpDistanceToMoveHigh is not NULL, lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value that specifies the distance to move. If lpDistanceToMoveHigh is NULL, lDistanceToMove is a 32-bit signed value. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer backward.
lpDistanceToMoveHigh
[in] Pointer to the high-order 32 bits of the signed 64-bit distance to move. If you do not need the high-order 32 bits, this pointer can be NULL. When non-NULL, this parameter also receives the high-order DWORD of the new value of the file pointer. For more information, see the Remarks section later in this topic.
dwMoveMethod
[in] Specifies the starting point for the file pointer move. This parameter can be one of the following values.
Value
Description
FILE_BEGIN | The starting point is zero or the beginning of the file.
FILE_CURRENT | The starting point is the current value of the file pointer.
FILE_END | The starting point is the current end-of-file position.

Return Values

The low-order DWORD of the new file pointer indicates success and that lpDistanceToMoveHigh is NULL. If lpDistanceToMoveHigh is not NULL, the function returns the low order DWORD of the new file pointer, and puts the high-order DWORD of the new file pointer into the LONG pointed to by that parameter.

If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call CeGetLastError.

If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF. However, because 0xFFFFFFFF is a valid value for the low-order DWORD of the new file pointer, you must check CeGetLastError to determine whether an error occurred. If an error occurred, CeGetLastError returns a value other than NO_ERROR. For a code example that illustrates this point, see the Remarks section later in this topic.

If the new file pointer would have been a negative value, the function fails, the file pointer is not moved, and the code returned by CeGetLastError is ERROR_NEGATIVE_SEEK.

Remarks

You cannot use the CeSetFilePointer function with a handle to a nonseeking such as communications device.

You can use the CeSetFilePointer function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero.

You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object. For more information about these objects, see Working with Processes and Threads.

It is not an error to set the file pointer to a position beyond the end of the file. The size of the file does not increase until you call the CeSetEndOfFile or CeWriteFile function. A write operation increases the size of the file to the file pointer position plus the size of the buffer written, leaving the intervening bytes uninitialized.

The parameter lpDistanceToMoveHigh is used to manipulate huge files. If it is set to NULL, then lDistanceToMove has a maximum value of 2^31–2, or 2 gigabytes less two. This is because all file pointer values are signed values. Therefore if there is even a small chance that the file will grow to that size, you should treat the file as a huge file and work with 64-bit file pointers.

If lpDistanceToMoveHigh is not NULL, then lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value. The lDistanceToMove parameter is treated as the low-order 32 bits of the value, and lpDistanceToMoveHigh as the upper 32 bits. Thus, lpDistanceToMoveHigh is a sign extension of lDistanceToMove.

To move the file pointer from 0 to 2 gigabytes, lpDistanceToMoveHigh can be either NULL or a sign extension of lDistanceToMove. To move the pointer more than 2 gigabytes, use lpDistanceToMoveHigh and lDistanceToMove as a single 64-bit quantity. For example, to move in the range from 2 gigabytes to 4 gigabytes, set the contents of lpDistanceToMoveHigh to zero, or to –1 for a negative sign extension of lDistanceToMove.

To work with 64-bit file pointers, you can declare a LONG, treat it as the upper half of the 64-bit file pointer, and pass its address in lpDistanceToMoveHigh. This means you have to treat two different variables as a logical unit, which is error-prone. The problems can be ameliorated by using the LARGE_INTEGER structure to create a 64-bit value and passing the two 32-bit values by means of the appropriate elements of the union.

It is conceptually simpler and better design to use a function to hide the interface to CeSetFilePointer. To do so, use something like this:

__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
 LARGE_INTEGER li;

 li.QuadPart = distance;

 li.LowPart = CeSetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod);

 if (li.LowPart == 0xFFFFFFFF && CeGetLastError() != NO_ERROR)
 {
 li.QuadPart = –1;
 }

 return li.QuadPart;
}

You can use CeSetFilePointer to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location zero. The file offset returned is the length of the file. However, this practice can have unintended side effects, such as failure to save the current file pointer so that the program can return to that location. It is simpler and safer to use CeGetFileSize instead.

See Also

SetFilePointer, CeReadFile


CeSetFileTime (RAPI)

This function sets the date and time that a file was created, last accessed, or last modified. CeSetFileTime is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeSetFileTime( HANDLE hFile, const FILETIME *lpCreationTime,
const FILETIME *lpLastAccessTime, const FILETIME *lpLastWriteTime );

Parameters

hFile
[in] Handle to the file for which to set the dates and times. The file handle must have been created with GENERIC_WRITE access to the file.
lpCreationTime
[in] Pointer to a FILETIME structure that contains the date and time the file was created. This parameter can be NULL if the application does not need to set this information.
lpLastAccessTime
[in] Pointer to a FILETIME structure that contains the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or (in the case of executable files) run. This parameter can be NULL if the application does not need to set this information.
lpLastWriteTime
[in] Pointer to a FILETIME structure that contains the date and time the file was last written to. This parameter can be NULL if the application does not want to set this information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError.

Remarks

Not all file systems support all file time parameters. The Windows CE object store stores only one file time and it can be set by any one of the three parameters.

When working with RAPI for Windows CE versions 1.0 and 1.01, use the PegSetFileTime function.

For more information about using RAPI functions, see Invoking Functions from a Desktop Computer.

See Also

FILETIME, CeGetFileSize, CeGetFileTime


CeSetUserNotification

This function creates a new user notification or modifies an existing one.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CeSetUserNotification(HANDLE hNotification,
TCHAR *pwszAppName, SYSTEMTIME *lpTime,
PCE_USER_NOTIFICATION lpUserNotification);

Parameters

hNotification
[in] Handle to the notification to overwrite, or zero to add a new notification.
pwszAppName
[in] Pointer to a null-terminated string that specifies the name of the application that owns this notification. The system uses the application’s primary icon as the taskbar annunciator for the notification. The user can start the application by selecting the annunciator.
lpTime
[in] Long pointer to the SYSTEMTIME structure that specifies the time when the notification should occur.
lpUserNotification
[in] Long pointer to the CE_USER_NOTIFICATION structure that describes the events that are to occur when the notification time is reached.

Return Values

The handle to the notification indicates success. Zero indicates failure.

Remarks

The notification occurs at the specified time, without starting the application. The application can specify the notification options, including whether to light the LED, generate a sound, or display a dialog box. However, an application typically uses the CeGetUserNotificationPreferences function to allow the user to set the notification options.

The user can start the owning application after the notification occurs. In this case, the system starts a new instance of the application using the APP_RUN_TO_HANDLE_NOTIFICATION string as the prefix of the command line and the notification handle (converted to a string) as the postfix. If another instance of the application is already running, the new instance must pass a private message to the old instance and then shut down.

To delete a notification, use the handle returned by CeSetUserNotification in a call to CeClearUserNotification. To overwrite a notification, use the returned handle in another call to CeSetUserNotification.

See Also

CeHandleAppNotifications


CeSetUserNotificationEx

This function creates a new user notification or modifies an existing one.

At a Glance

Header file: | Notify.h
Windows CE versions: | 2.12 and later

Syntax

HANDLE CeSetUserNotificationEx (HANDLE hNotification,
CE_NOTIFICATION_TRIGGER *pcnt,
CE_USER_NOTIFICATION *pceun);

Parameters

hNotification
[in] Handle to the notification to overwrite or 0 to add a new notification.
pcnt
[in] Pointer to a UserNotificationTrigger structure which defines what event activates a notification.
pceun
[in] Pointer to a UserNotificationType structure, which defines how the system should respond when a notification occurs. For example, the system could launch a dialog box or another application.

Return Values

Returns a handle to the notification event if successful. Returns NULL if unsuccessful.


CeSHCreateShortcut (RAPI)

This function creates a shortcut. CeSHCreateShortcut is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

DWORD CeSHCreateShortcut(LPWSTR lpszShortcut, LPWSTR lpszTarget);

Parameters

szShortcut
[in] Null-terminated string that contains the name of the shortcut to create. Passing a NULL value for this parameter will cause an exception
szTarget
[in] Null-terminated string that contains the target path of the shortcut. The size of the buffer is limited to 256 characters.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegSHCreateShortcut function.

See Also

SHCreateShortcut


CeSHGetShortcutTarget (RAPI)

This function retrieves the shortcut’s target path. CeSHGetShortcutTarget is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeSHGetShortcutTarget(LPWSTR lpszShortcut, LPWSTR lpszTarget, INT Arg3);

Parameters

szShortcut
[in] Null-terminated string that contains the name of the shortcut to create.
szTarget
[in] Null-terminated string that gets the target path of the shortcut. The buffer must be at least cbMax characters long.
cbMax
[in] Maximum number of characters that can be copied to the buffer.

Return Values

True indicates success. FALSE indicates failure.

Remarks

When writing applications for Windows CE versions 1.0 and 1.01, use the PegSHGetShortcutTarget function.

See Also

SHGetShortcutTarget


CeSvcClose

This function closes a handle previously returned by CeSvcOpen or CeSvcOpenEx.

Syntax

HRESULT CeSvcClose( HCESVC hSvc);

Parameters

hSvc
[in] Handle to a registry subkey, obtained by means of a call to CeSvcOpen or CeSvcOpenEx. Can be NULL.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcDeleteVal

This function removes a named value from the specified registry key.

Syntax

HRESULT CeSvcDeleteVal( HCESVC hSvc, LPCTSTR pszValName);

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcEnumProfiles

This function enumerates all subkeys underneath a given subkey.

Syntax

HRESULT CeSvcEnumProfiles( PHCESVC phSvc, DWORD plProfileIndex,
PDWORD plProfile );

Parameters

phSvc
[in] Pointer to a handle to a registry subkey.
lProfileIndex
[in] Index for subkey returned. Caller should initialize to 0 and increment for each additional subkey.
plProfile
[in] Pointer to a device identifier.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcGetBinary

This function reads a binary value from a registry subkey and copies the data into a buffer.

Syntax

HRESULT CeSvcGetBinary( HCESVC hSvc, LPCTSTR pszValName,
LPBYTE lpData, LPDWORD pcbVal );

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.
lpData
[in] Long pointer to the buffer for read data.
pcbVal
[in] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, this variable contains the size of the data copied to lpData.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcGetDword

This function reads a DWORD value from a registry key and copies the data into a buffer.

Syntax

HRESULT CeSvcGetDword( HCESVC hSvc, LPCTSTR pszValName,
LPDWORD pdwVal );

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.
pdwVal
[in] Pointer to the buffer for read data.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcGetString

This function reads a string value from a registry subkey and copies the data into a buffer.

Syntax

HRESULT CeSvcGetString( HCESVC hSvc, LPTSTR pszValName,
LPTSTR pszVal, DWORD cbVal );

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.
pszVal
[in] Address of buffer for read data.
cbVal
[in] Size of buffer.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcOpen

This function opens and returns a handle to the registry root for a specified logical position, as specified by the CEUTIL constants shown in the table below. This is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE.

Syntax

HRESULT CeSvcOpen( UINT uSvc, LPTSTR pszPath, BOOL fCreate,
PHCESVC phSvc );

Parameters

uSvc
[in] Logical subkey in registry as identified by CESVC_* keys.The following table maps registry locations to pre-defined constants. MACHINE_ROOT is used for HKEY_LOCAL_MACHINE\Software\Microsoft\Windows CE and LOCAL_ROOT is used for HKEY_CURRENT_USER\Software\Microsoft\Windows CE Service.
Registry Key
CEUTIL Constants
Description
MACHINE_ROOT | CESVC_ROOT_MACHINE | Windows CE Services root hierarchy under HKEY_LOCAL_MACHINE
MACHINE_ROOT\Filters | CESVC_FILTERS | The Filters registry root. New filters should register themselves here
MACHINE_ROOT\CustomMenus | CESVC_CUSTOM_MENUS | Custom menus reg root
MACHINE_ROOT\Services | CESVC_SERVICES_COMMON | Services reg root
MACHINE_ROOT\Services \Synchronization | CESVC_SYNC_COMMON | Synchronization registry root. New sync services should register here
LOCAL_ROOT | CESVC_ROOT_USER | Windows CE Services root hierarchy under HKEY_CURRENT_USER
LOCAL_ROOT\Partners | CESVC_DEVICES | Individual device subkeys are created under this key
LOCAL_ROOT\Partners\<device id> | CESVC_DEVICEX | Particular device root subkey
LOCAL_ROOT\Partners\<selected device id> | CESVC_DEVICE_SELECTED | Root subkey for the currently selected device
LOCAL_ROOT\Partners\<device id>\Services | CESVC_SERVICES_USER | Root Services subkey for a particular device
LOCAL_ROOT\Partners\<device id>\Services\Synchronization | CESVC_SYNC | Synchronization reg root for a particular device

pszPath
[in] Pointer to a null-terminated string that contains either a subpath to append to the logical subkey, or a DWORD device identifier (if uSvc is CESVC_DEVICEX).
fCreate
[in] Boolean that is set to TRUE to indicate that the subkey should be created if it does not exist.
phSvc
[out] Returns the logical handle to the registry subkey. This handle is equivalent to a HKEY and can be used by other CEUTIL APIs as well as Win32 registry manipulation routines.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

The first time a device is connected to the desktop and a partnership is created, the various synchronization and filter settings are copied from the MACHINE_ROOT to the partnership subkey under LOCAL_ROOT.


CeSvcOpenEx

This function, given a handle to an already open registry, opens a nested subkey underneath.

Syntax

HRESULT CeSvcOpenEx( HCESVC hSvcRoot, LPTSTR pszPath,
BOOL fCreate, PHCESVC phSvc );

Parameters

hSvcRoot
[in] Handle to a registry subkey, obtained by means of a call to CeSvcOpen.
pszPath
[in] Pointer to a null-terminated string that contains a subpath to append to the logical subkey.
fCreate
[in] Boolean that is set to TRUE to indicate that the subkey should be created if it does not exist.
phSvc
[out] Returns the logical handle to the registry subkey. This handle is equivalent to a HKEY and can be used by other CEUTIL APIs as well as Win32 registry manipulation routines.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcSetBinary

This function writes a binary value to a registry subkey.

Syntax

HRESULT CeSvcSetBinary( HCESVC hSvc, LPCTSTR pszValName,
LPBYTE lpData, DWORD cbVal );

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.
lpData
[in] Long pointer to the binary data to be written.
cbVal
[in] Size of binary data.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcSetDword

This function writes a DWORD value to a registry subkey.

Syntax

HRESULT CeSvcSetDword( HCESVC hSvc, LPCTSTR pszValName,
DWORD dwVal );

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.
dwVal
[in] Specifies the data to be written.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeSvcSetString

This function writes a string value to a registry subkey.

Syntax

HRESULT CeSvcSetString( HCESVC hSvc, LPCTSTR pszValName,
LPTSTR pszVal );

Parameters

hSvc
[in] Handle to a registry subkey.
pszValName
[in] Pointer to a null-terminated string that contains the name of the value.
pszVal
[in] Pointer to a null-terminated string that contains data to be written.

Return Values

HRESULT indicates success. A standard Win32 error code indicates failure.

Remarks

This function is part of CEUTIL, a utility DLL for dealing with desktop registry entries for Windows CE. CEUTIL functions are for use by desktop applications that need to communicate remotely with Windows CE–based devices. These functions are not available to applications running on Windows CE–based devices.


CeUnmountDBVol

This function unmounts a database volume. A remote application interface (RAPI) version of this function exists, and it is also called CeUnmountDBVol.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL CeUnmountDBVol ( PCEGUID pceguid );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database to be unmounted.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

All cached data is flushed to permanent storage. A single database volume can be mounted more then once by a different application. Each time the volume is mounted a reference count is incremented. A mounted database volume does not unmount until all applications that mounted the volume call CeUnmountDBVol.

See Also

CeMountDBVol


CeUnmountDBVol (RAPI)

This function unmounts a database volume. CeUnmountDBVol is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.12 and later

Syntax

BOOL CeUnmountDBVol ( PCEGUID pceguid );

Parameters

pceguid
[in] Pointer to the CEGUID that contains the globally unique identifier of a mounted database to be unmounted.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

All cached data is flushed to permanent storage. A single database volume can be mounted more then once by a different application. Each time the volume is mounted a reference count is incremented. A mounted database volume does not unmount until all applications that mounted the volume call CeUnmountDBVol (RAPI).

See Also

CeMountDBVol (RAPI)


CeWriteFile (RAPI)

This function writes data to a file. CeWriteFile starts writing data to the file at the position indicated by the file pointer. After the write operation has been completed, the file pointer is adjusted by the number of bytes actually written.

CeWriteFile is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 2.0 and later

Syntax

BOOL CeWriteFile( HANDLE hFile, LPCVOID lpBuffer,
DWORD nNumberOfBytesToWrite, LPDWORD lpNumberOfBytesWritten,
LPOVERLAPPED lpOverlapped );

Parameters

hFile
[in] Handle to the file to be written to. The file handle must have been created with GENERIC_WRITE access to the file.
lpBuffer
[in] Pointer to the buffer containing the data to be written to the file.
nNumberOfBytesToWrite
[in] Number of bytes to write to the file.

A value of zero specifies a null write operation. A null write operation does not write any bytes but does cause the time stamp to change. CeWriteFile does not truncate or extend the file. To truncate or extend a file, use the CeSetEndOfFile function.

Named pipe write operations across a network are limited to 65,535 bytes.

lpNumberOfBytesWritten
[out] Pointer to the number of bytes written by this function call. CeWriteFile sets this value to zero before doing any work or error checking.
lpOverlapped
[in] Unsupported; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError.

Remarks

If part of the file is locked by another process and the write operation overlaps the locked portion, this function fails.

Accessing the output buffer while a write operation is using the buffer may lead to corruption of the data written from that buffer. Applications must not read from, write to, reallocate, or free the output buffer that a write operation is using until the write operation completes.

See Also

WriteFile, CeCreateFile, CeReadFile, CeSetEndOfFile


CeWriteRecordProps

This function writes a set of properties to a single record, creating the record if necessary. A remote application interface (RAPI) version of this function exists, and it is also called CeWriteRecordProps.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeWriteRecordProps(HANDLE hDbase, CEOID oidRecord,
WORD cPropID, CEPROPVAL * rgPropVal);

Parameters

hDbase
[in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabase function.
oidRecord
[in] Object identifier of the record to which the specified properties are to be written. If this parameter is zero, a new record is created and filled in with the specified properties.
cPropID
[in] Number of properties in the array specified by the rgPropVal parameter. The cPropID parameter must not be zero.
rgPropVal
[in] Pointer to an array of CEPROPVAL structures that specify the property values to be written to the specified record.

Return Values

The object identifier of the record to which the properties were written indicates success. Zero indicates failure. To get extended error information when within a CE program call GetLastError. GetLastError may return one of the following values:

Value
Description
ERROR_DISK_FULL | There was not enough space in the object store to write the properties.
ERROR_INVALID_PARAMETER | A parameter was invalid.

Remarks

The CeWriteRecordProps function writes all the requested properties into the specified record. CeWriteRecordProps does not move the seek pointer.

To delete a property, set the CEDB_PROPDELETE flag in the appropriate property value. This allows multiple deletes and changes in a single call, which is much more efficient than multiple calls.

No memory is freed by the callee. Pointers in the CEPROPVAL structures can be anywhere in the caller’s address space—they can be marshalled in like the array returned by CeReadRecordProps, or they can be independently allocated.

For Windows CE versions 2.10 and later, on a mounted database volume, all write operations are cached. The database subsystem periodically requests a cache flush after a series of operations. If memory is low, the cache is flushed to permanent storage. Unlike a file system that can choose to flush only part of the cache, on a database, all blocks are flushed.


CeWriteRecordProps (RAPI)

This function writes a set of properties to a single record, creating the record if necessary. CeWriteRecordProps is a remote application interface, which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

CEOID CeWriteRecordProps(HANDLE hDbase, CEOID oidRecord,
WORD cPropID, CEPROPVAL * rgPropVal);

Parameters

hDbase
[in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabase function.
oidRecord
[in] Object identifier of the record to which the specified properties are to be written. If this parameter is zero, a new record is created and filled in with the specified properties.
cPropID
[in] Number of properties in the array specified by the rgPropVal parameter. The cPropID parameter must not be zero.
rgPropVal
[in] Pointer to an array of CEPROPVAL structures that specify the property values to be written to the specified record.

Return Values

The object identifier of the record to which the properties were written indicates success. Zero indicates failure. To get extended error information within a RAPI program, call CeGetLastError. CeGetLastError may return one of the following values:

Value
Description
ERROR_DISK_FULL | There was not enough space in the object store to write the properties.
ERROR_INVALID_PARAMETER | A parameter was invalid.

Remarks

The CeWriteRecordProps function writes all the requested properties into the specified record. CeWriteRecordProps does not move the seek pointer.

To delete a property, set the CEDB_PROPDELETE flag in the appropriate property value. This allows multiple deletes and changes in a single call, which is much more efficient than multiple calls.

No memory is freed by the callee. Pointers in the CEPROPVAL structures can be anywhere in the caller’s address space—they can be marshalled in like the array returned by CeReadRecordProps, or they can be independently allocated.

For Windows CE versions 2.10 and later, on a mounted database volume, all write operations are cached. The database subsystem periodically requests a cache flush after a series of operations. If memory is low, the cache is flushed to permanent storage. Unlike a file system that can choose to flush only part of the cache, on a database, all blocks are flushed.


CharLower

This function converts a character string or a single character to lowercase. If the operand is a character string, the function converts the characters in place.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPTSTR CharLower LPTSTR lpsz );

Parameters

lpsz
[in] Pointer to a null-terminated string or specifies a single character. If the high-order word of this parameter is zero, the low-order word must contain a single character to be converted.

Return Values

A pointer to the converted string indicates that the operand is a character string. Since the string is converted in place, the return value is equal to lpsz.

A 32-bit value whose high-order word is zero and low-order word contains the converted character indicates that the operand is a single character.

There is no indication of success or failure. Failure is rare. There is no extended error information for this function; do not call GetLastError.

Remarks

The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows CE does not have language drivers.

Windows CE supports only the Unicode version of this function.

See Also

CharLowerBuff, CharUpper, CharUpperBuff, HIWORD, LOWORD


CharLowerBuff

This function converts uppercase characters in a buffer to lowercase characters. The function converts the characters in place.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD CharLowerBuff(LPTSTR lpsz, DWORD cchLength);

Parameters

lpsz
[in] Pointer to a buffer that contains one or more characters to process.
cchLength
[in] Specifies the size, in characters, of the buffer pointed to by lpsz.

The function examines each character, and converts uppercase characters to lowercase characters. The function examines the number of bytes or characters indicated by cchLength, even if one or more characters are null characters.

Return Values

The number of characters processed indicates success. For example, if CharLowerBuff("Acme of Operating Systems", 10) succeeds, the return value is 10.

Remarks

The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows CE does not have language drivers.

Windows CE supports only the Unicode version of this function.

See Also

CharUpperBuff


CharNext

This function returns a pointer to the next character in a string.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPTSTR CharNext(LPCTSTR lpsz );

Parameters

lpsz
[in] Pointer to a character in a null-terminated string.

Return Values

A pointer to the next character in the string, or to the terminating null character if at the end of the string, indicates success.

If lpsz points to the terminating null character, the return value is equal to lpsz.

See Also

CharPrev


CharPrev

This function returns a pointer to the preceding character in a string.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

LPTSTR CharPrev (LPCTSTR lpszStart, LPCTSTR lpszCurrent );

Parameters

lpszStart
[in] Pointer to the beginning of the null-terminated string.
lpszCurrent
[in] Pointer to a character in a null-terminated string.

Return Values

A pointer to the preceding character in the string, or to the first character in the string if the lpszCurrent parameter equals the lpszStart parameter, indicates success.

See Also

CharNext


CharUpper

This function converts a character string or a single character to uppercase. If the operand is a character string, the function converts the characters in place.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPTSTR CharUpper( LPTSTR lpsz );

Parameters

lpsz
[in] Pointer to a null-terminated string or specifies a single character. If the high-order word of this parameter is zero, the low-order word must contain a single character to be converted.

Return Values

A pointer to the converted string indicates that the operand is a character string. Since the string is converted in place, the return value is equal to lpsz.

A 32-bit value whose high-order word is zero and low-order word contains the converted character indicates that the operand is a single character.

There is no indication of success or failure. Failure is rare. There is no extended error information for this function; do not call GetLastError.

Remarks

The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows CE does not have language drivers.

Windows CE supports only the Unicode version of this function.

See Also

CharLower, CharLowerBuff, CharUpperBuff, HIWORD, LOWORD


CharUpperBuff

This function converts lowercase characters in a buffer to uppercase characters. The function converts the characters in place.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD CharUpperBuff(LPTSTR lpsz, DWORD cchLength);

Parameters

lpsz
[in] Pointer to a buffer that contains one or more characters to process.
cchLength
[in] Specifies the size, in characters, of the buffer pointed to by lpsz.

The function examines each character, and converts lowercase characters to uppercase characters. The function examines the number of characters indicated by cchLength, even if one or more characters are null characters.

Return Values

The number of characters processed indicates success. For example, if CharUpperBuff("Zenith of API Sets", 10) succeeds, the return value is 10.

Remarks

The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows CE does not have language drivers.

Windows CE supports only the Unicode version of this function.

See Also

CharLowerBuff


CheckPassword

This function compares a specified string to the system password. A remote application interface (RAPI) version of this function exists, named CeCheckPassword.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL CheckPassword( LPWSTR lpszPassword );

Parameters

lpszPassword
Pointer to a wide character string to compare with the system password.

Return Values

TRUE indicates that lpszPassword matches the system password. FALSE indicates failure.


CloseHandle

This function closes an open object handle. A remote application interface (RAPI) version of this function exists, named CeCloseHandle.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CloseHandle( HANDLE hObject );

Parameters

hObject
Handle to an open object.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The CloseHandle function closes handles to the following objects:

Communications device | Mutex
Database | Process
Event | Socket
File | Thread

CloseHandle invalidates the specified object handle, decrements the object’s handle count, and performs object retention checks. After the last handle to an object is closed, the object is removed from the system.

Closing a thread handle does not terminate the associated thread. To remove a thread object, you must terminate the thread, then close all handles to the thread.

Use CloseHandle to close handles returned by calls to the CreateFile function. Use FindClose to close handles returned by calls to the FindFirstFile function.

See Also

CreateFile, DeleteFile, FindClose, FindFirstFile


CloseToolhelp32Snapshot

This function closes a handle to a snapshot.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI CloseToolhelp32Snapshot(HANDLE hSnapshot);

Parameters

hSnapshot
Handle to a snapshot returned from the CreateToolhelp32Snapshot function.

Remarks

Close a snapshot in order to free valuable resources for the system.

See Also

CreateToolhelp32Snapshot


CLSIDFromProgID

This function looks up a class identifier in the registry, given a programmatic identifier.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.10 and later

Syntax

HRESULT CLSIDFromProgID (LPCOLESTR lpszProgID, LPCLSID pclsid );

Parameters

lpszProgID
[in] Long pointer to the ProgID whose class identifier is requested.
pclsid
[out] Pointer to the retrieved class identifier on return.

Return Values

One of the values described in the following table is returned.
Value
Description
S_OK | The class identifier was retrieved successfully.
CO_E_CLASSSTRING | The registered class identifier for the ProgID is invalid.
REGDB_E_WRITEREGDB | An error occurred writing the class identifier to the registry. See the Remarks section.
REGDB_E_CLASSNOTREG | The class identifier for the ProgID cannot be found in the registry.

Remarks

Given a ProgID, CLSIDFromProgID looks up its associated class identifier in the registry.


CLSIDFromString

This function converts a string generated by the StringFromCLSID function back into the original class identifier.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CLSIDFromString(LPOLESTR lpsz, LPCLSID pclsid);

Parameters

lpsz
[in] Long pointer to the null-terminated string that represnts the class identifier.
pclsid
[out] Pointer to the class identifier on return.

Return Values

One of the values described in the following table is returned.

Value
Description
NOERROR | The class identifier was obtained successfully.
CO_E_CLASSTRING | The class string was improperly formatted.
REGDB_E_WRITEREGDB | The class identifier corresponding to the class string was not found in the registry.

The standard return value E_INVALIDARG is also supported.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoCreateInstance

This function creates on the local system a single uninitialized object of the class associated with a specified class identifier

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

STDAPI CoCreateInstance(REFCLSID rclsid, LPUNKNOWN pUnkOuter, DWORD dwClsContext, REFIID riid, LPVOID * ppv);

Parameters

rclsid
[in] Class identifier associated with the data and code that are used to create the object.
pUnkOuter
[in] If NULL, indicates that the object is not being created as part of an aggregate. If non-NULL, pointer to the aggregate object’s IUnknown interface (the controlling IUnknown).
dwClsContext
[in] Specifies the context in which the code that manages the newly created object will run. The only valid value for this parameter is CLSCTX_INPROC_SERVER, which is from the enumeration CLSCTX. Any other value results in a return value of E_NOTIMPL.
riid
[in] Reference to the identifier of the interface to be used to communicate with the object.
ppv
[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, ppv contains the requested interface pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | An instance of the specified object class was successfully created.
REGDB_E_CLASSNOTREG | A specified class is not registered in the registration database. Also can indicate that the type of server you requested in the CLSCTX enumeration is not registered or the values for the server types in the registry are corrupt.
CLASS_E_NOAGGREGATION | This class cannot be created as part of an aggregate.

Remarks

The CoCreateInstance helper function provides a convenient shortcut by connecting to the class object associated with the specified class identifier, creating an uninitialized instance, and releasing the class object. As such, it encapsulates the following functionality:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF);
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj)
pCF->Release();

It is convenient to use CoCreateInstance when you need to create only a single instance of an object on the local machine. When you are creating multiple instances, it is more efficient to obtain a pointer to the class object's IClassFactory interface and use its methods as needed. In the latter case, you should use the CoGetClassObject function.

In the CLSCTX enumeration, you can specify the type of server used to manage the object. The constants can be CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, or any combination of these values. The constant CLSCTX_ALL is defined as the combination of all three. For more information about the use of one or a combination of these constants, refer to CLSCTX.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoFreeLibrary

This function frees a library that, when loaded, was specified to be freed explicitly.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0

Syntax

void CoFreeLibrary(HINSTANCE hInst);

Parameter

hInst
[in] Handle to the library module to be freed, as returned by CoLoadLibrary.

Return Values

None.

Remarks

The CoFreeLibrary function should be called to free a library that is to be freed explicitly. This is established when the library is loaded with the bAutoFree parameter of CoLoadLibrary set to FALSE. It is illegal to free a library explicitly when the corresponding CoLoadLibrary call specifies that it be freed automatically (the bAutoFree parameter is set to TRUE).

For Windows CE versions 2.10 and later, this function is not supported. Applications should call CoFreeUnusedLibraries instead.

Passing into this function any invalid and, under some circumstances, NULL pointers results in unexpected termination of the application.


CoFreeUnusedLibraries

This function unloads any DLLs that are no longer in use and that, when loaded, were specified to be freed automatically.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

void CoFreeUnusedLibraries();

Return Values

None.

Remarks

Applications can call CoFreeUnusedLibraries periodically to free resources. It is most efficient to call it either at the top of a message loop or in some idle-time task. DLLs that are to be freed automatically have been loaded with the bAutoFree parameter of the CoLoadLibrary function set to TRUE. CoFreeUnusedLibraries internally calls DllCanUnloadNow for DLLs that implement and export that function.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoGetClassObject

This function provides a pointer to an interface on a class object associated with a specified class identifier. Call CoGetClassObject directly when you want to create multiple objects through a class object whose class identifier is already in the system registry. Most class objects implement the IClassFactory interface. You would then call IClassFactory::CreateInstance to create an uninitialized object. To create a single object on a local machine, use the CoCreateInstance function.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

STDAPI CoGetClassObject(REFCLSID rclsid, WORD dwClsContext, COSERVERINFO * pServerInfo, REFIID riid, LPVOID * ppv);

Parameters

rclsid
[in] Class identifier associated with the data and code that you will use to create the objects.
dwClsContext
[in] Specifies the context in which the executable code is to be run The only valid value for this parameter is CLSCTX_INPROC_SERVER, which is from the enumeration CLSCTX. Any other value results in a return value of E_NOTIMPL.
pServerInfo
[in] Set to NULL.
riid
[in] Reference to the identifier of the interface, which will be supplied in ppv on successful return. This interface will be used to communicate with the class object. Typically this value is IID_IClassFactory, although other values – such as IID_IClassFactory2 which supports a form of licensing – are allowed. All OLE-defined interface IIDs are defined in the OLE header files as IID_interfacename, where interfacename is the name of the interface.
ppv
[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, ppv contains the requested interface pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Location and connection to the specified class object was successful.
REGDB_E_CLASSNOTREG | Class identifier is not properly registered. Can also indicate that the value you specified in dwClsContext is not in the registry.
E_NOINTERFACE | Either the object pointed to by ppv does not support the interface identified by riid, or the QueryInterface operation on the class object returned E_NOINTERFACE.
REGDB_E_READREGDB | Error reading the registration database.
CO_E_DLLNOTFOUND | In-process DLL or handler DLL not found (depends on context).
CO_E_APPNOTFOUND | EXE not found (CLSCTX_LOCAL_SERVER only).
E_ACCESSDENIED | General access failure (returned from LoadLib or CreateProcess).
CO_E_ERRORINDLL | EXE has error in image.
CO_E_APPDIDNTREG | EXE was launched, but it did not register class object (may or may not have shut down).

Remarks

A class object in OLE is an intermediate object that supports an interface that permits operations common to a group of objects. The objects in this group are instances derived from the same object definition represented by a single class identifier. Usually, the interface implemented on a class object is IClassFactory, through which you can create object instances of a given definition (class).

A call to CoGetClassObject creates, initializes, and gives the caller access (through a pointer to an interface specified with the riid parameter) to the class object. The class object is the one associated with the class identifier that you specify in the rclsid parameter. The details of how the system locates the associated code and data within a given machine are transparent to the caller, as is the dynamic loading of any code that is not already loaded.

If the class context is CLSCTX_REMOTE_SERVER, indicating remote activation is required, the COSERVERINFO structure provided in the pServerInfo parameter allows you to specify the machine on which the server is located. For information on the algorithm used to locate a remote server when pServerInfo is NULL, refer to the CLSCTX enumeration.

There are two places to find a class identifier for a given class:

  • The registry holds an association between class identifiers and file suffixes, and between class identifiers and file signatures for determining the class of an object.
  • When an object is saved to persistent storage, its class identifier is stored with its data.

To create and initialize embedded or linked OLE document objects, it is not necessary to call CoGetClassObject directly. Instead, call one of the OleCreate or OleCreate Xxx helper functions. These functions encapsulate the entire object instantiation and initialization process, and call, among other functions, CoGetClassObject.

The riid parameter specifies the interface the client will use to communicate with the class object. In most cases, this interface is IClassFactory. This provides access to the IClassFactory::CreateInstance method, through which the caller can then create an uninitialized object of the kind specified in its implementation. All classes registered in the system with a class identifier must implement IClassFactory.

In rare cases, however, you may want to specify some other interface that defines operations common to a set of objects. For example, in the way OLE implements monikers, the interface on the class object is IParseDisplayName, used to transform the display name of an object into a moniker.

The dwClsContext parameter specifies the execution context, allowing one class identifier to be associated with different pieces of code in different execution contexts. The CLSCTX enumeration, defined in Compobj.h, specifies the available context flags. CoGetClassObject consults (as appropriate for the context indicated) both the registry and the class objects that are currently registered by calling the CoRegisterClassObject function.

To release a class object, use the class object's Release method. The function CoRevokeClassObject is to be used only to remove a class object's class identifier from the system registry.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoInitializeEx

This function initializes the Component Object Model (COM). Applications are required to use CoInitializeEx before they make any other COM library calls except for memory allocation functions.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CoInitializeEx(LPVOID pvReserved, DWORD dwCoInit);

Parameters

pvReserved
[in] Reserved; set to NULL.
dwCoInit
[in] Specifies the concurrency model and initialization options for the thread. Must be set to COINIT_MULTITHREADED.

Return Values

S_OK indicates that the COM library was initialized successfully. S_FALSE indicates that the COM library is already initialized. The standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED are also supported.

Remarks

The CoInitializeEx function initializes the Component Object Model (COM), including the OLE library, for use by the current thread. The dwCoInit parameter specifies the type of concurrency control required by objects created by this thread. Windows CE supports only the multi-threaded concurrency control. Thus, COINIT_MULTITHREADED is the only option permitted for the dwCoInit parameter.

Compound document applications must call CoInitializeEx before calling any other function in the OLE library.

Windows CE does not support the CoInitialize(NULL) or OleInitialize function. Use CoInitializeEx instead.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoLoadLibrary

This function is called internally by the CoGetClassObject, when the class context indicates a DLL, to load a specific DLL into the caller’s process. Applications should not call it directly.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

HINSTANCE CoLoadLibrary(LPOLESTR lpszLibName, BOOL bAutoFree);

Parameters

lpszLibName
[in] Long pointer to the null-terminated string that contains the name of the library to be loaded. The use of this name is the same as in the Win32 function LoadLibrary.
bAutoFree
[in] Boolean that is set to TRUE if this library is freed when it is no longer needed, through a call to either the CoFreeUnusedLibraries or CoUninitialize functions, or to FALSE if the library should be explicitly freed with the CoFreeLibrary function.

Return Values

The handle of the loaded library indicates success. NULL indicates that the library could not be loaded.

Remarks

The CoLoadLibrary function is called internally by the CoGetClassObject function when the class context (CLSCTX) indicates a DLL. CoLoadLibrary loads a DLL specified by the lpszLibName parameter into the process that called CoGetClassObject. Containers should not call CoLoadLibrary directly.

Internally, a reference count is kept on the loaded DLL, by using CoLoadLibrary to increment the count and the CoFreeLibrary function to decrement it.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CompareFileTime

This function compares two 64-bit file times.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LONG CompareFileTime( const FILETIME *lpFileTime1,
const FILETIME *lpFileTime2 );

Parameters

lpFileTime1
[in] Long pointer to a FILETIME structure that specifies the first 64-bit file time.
lpFileTime2
[in] Long pointer to a FILETIME structure that specifies the second 64-bit file time.

Return Values

–1 indicates that the first file time is less than the second file time. 0 indicates that the first file time is equal to the second file time. +1 indicates that the first file time is greater than the second file time.

See Also

GetFileTime, FILETIME


CompareString

This function compares two character strings, using the locale specified by the given identifier as the basis for the comparison.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int CompareString(LCID Locale, DWORD dwCmpFlags,
LPCTSTR lpString1, int cchCount1, LPCTSTR lpString2, int cchCount2);

Parameters

Locale
[in] Specifies the locale used for the comparison. This parameter can be one of the following predefined locale identifiers:
Value
Description
LOCALE_SYSTEM_DEFAULT | The system’s default locale.
LOCALE_USER_DEFAULT | The current user’s default locale.

This parameter can also be a locale identifier created by the MAKELCID macro.

dwCmpFlags
[in] A set of flags that indicate how the function compares the two strings. By default, these flags are not set. This parameter can specify zero to get the default behavior, or it can be any combination of the following values:
Value
Description
NORM_IGNORECASE | Ignore case.
NORM_IGNOREKANATYPE | Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana characters compare as equal.
NORM_IGNORENONSPACE | Ignore nonspacing characters.
NORM_IGNORESYMBOLS | Ignore symbols.
NORM_IGNOREWIDTH | Do not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT | Treat punctuation the same as symbols.

lpString1
[in] Pointer to the first string to be compared.
cchCount1
[in] Specifies the size, in characters, of the string pointed to by the lpString1 parameter. If this parameter is –1, the string is assumed to be null terminated and the length is calculated automatically.
lpString2
[in] Pointer to the second string to be compared.
cchCount2
[in] Specifies the size, in characters, of the string pointed to by the lpString2 parameter. If this parameter is –1, the string is assumed to be null terminated and the length is calculated automatically.

Return Values

If the function succeeds, the return value is one of the following values:

Value
Description
CSTR_LESS_THAN | The string pointed to by the lpString1 parameter is less in lexical value than the string pointed to by the lpString2 parameter.
CSTR_EQUAL | The string pointed to by lpString1 is equal in lexical value to the string pointed to by lpString2.
CSTR_GREATER_THAN | The string pointed to by lpString1 is greater in lexical value than the string pointed to by lpString2.

Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Notice that if the return value is CSTR_EQUAL, which is the value 2, the two strings are “equal” in the collation sense, though not necessarily identical.

To maintain the C run-time convention of comparing strings, the value 2 can be subtracted from a nonzero return value. The meaning of < 0, ==0 and > 0 is then consistent with the C run times.

If the two strings are of different lengths, they are compared up to the length of the shortest one. If they are equal to that point, then the return value will indicate that the longer string is greater. For more information about locale identifiers, see Locale Identifiers.

Strings are compared using what is called a “string sort” technique. In a string sort, the hyphen and apostrophe are treated just like any other nonalphanumeric symbols: they come before the alphanumeric symbols.

The following list of words is sorted using a string sort:

bill’s | t-ant
billet | t-aria
bills | tanya
can’t | sue’s
cannot | sued
cant | sues
co-op | we’re
con | went
coop | were

The LCMapString function defaults to using a word sort, but uses a string sort if their caller sets the SORT_STRINGSORT flag.

The CompareString function is optimized to run at the highest speed when dwCmpFlags is set to 0 or NORM_IGNORECASE, and cchCount1 and cchCount2 have the value –1.

See Also

GetSystemDefaultLCID, MAKELCID


ContinueDebugEvent

This function enables a debugger to continue a thread that previously reported a debugging event.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ContinueDebugEvent( DWORD dwProcessId, DWORD dwThreadId,
DWORD dwContinueStatus );

Parameters

dwProcessId
Specifies the handle to the process to continue.
dwThreadId
Specifies the handle to the thread to continue. The combination of process identifier and thread identifier must identify a thread that has previously reported a debugging event.
dwContinueStatus
Specifies how to continue the thread that reported the debugging event.

If the DBG_CONTINUE flag is specified for this parameter and the thread specified by the dwThreadId parameter previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function stops all exception processing and continues the thread. For any other debugging event, this flag simply continues the thread.

If the DBG_EXCEPTION_NOT_HANDLED flag is specified for this parameter and the thread specified by dwThreadId previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function continues exception processing. If this is a first-chance exception event, the search and dispatch logic of the structured exception handler is used; otherwise, the process is terminated. For any other debugging event, this flag simply continues the thread.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Only the thread that created dwProcessId with the CreateProcess function can call ContinueDebugEvent.

After the ContinueDebugEvent function succeeds, the specified thread continues. Depending on the debugging event previously reported by the thread, different actions occur. If the continued thread previously reported an EXIT_THREAD_DEBUG_EVENT debugging event, ContinueDebugEvent closes the handle the debugger has to the thread. If the continued thread previously reported an EXIT_PROCESS_DEBUG_EVENT debugging event, ContinueDebugEvent closes the handles the debugger has to the process and to the thread.

See Also

CreateProcess


ConvertDefaultLocale

This function converts a special default locale value to an actual locale identifier.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

LCID ConvertDefaultLocale(LCID Locale);

Parameters

Locale
[in] Default locale value that the function converts to a locale identifier (LCID). The following list shows the default locale values:
Value
Description
LOCALE_SYSTEM_DEFAULT | The system’s default locale.
LOCALE_USER_DEFAULT | The current user’s default locale.
LOCALE_NEUTRAL | The language-neutral default locale.
Any sublanguage-neutral locale | A locale identifier constructed by calling MAKELCID with a primary language identifier, such as LANG_ENGLISH, and the SUBLANG_NEUTRAL secondary language identifier.

Return Values

The appropriate LCID indicates success. The Locale parameter indicates failure. The function fails when Locale is not one of the default locale values listed above.

Remarks

A call to ConvertDefaultLocale(LOCALE_SYSTEM_DEFAULT) is equivalent to a call to GetSystemDefaultLCID. A call to ConvertDefaultLocale(LOCALE_USER_DEFAULT) is equivalent to a call to GetUserDefaultLCID.

For more information, see Locale Identifiers.

See Also

GetSystemDefaultLCID


CopyFile

This function copies an existing file to a new file. A remote application interface (RAPI) version of this function exists, named CeCopyFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CopyFile(LPCTSTR lpExistingFileName, LPCTSTR lpNewFileName, BOOL bFailIfExists);

Parameters

lpExistingFileName
[in] Long pointer to a null-terminated string that specifies the name of an existing file.
lpNewFileName
[in] Long pointer to a null-terminated string that specifies the name of the new file.
bFailIfExists
[in] Boolean that specifies how this operation is to proceed if a file of the same name as that specified by lpNewFileName already exists. If this parameter is TRUE and the new file already exists, the function fails. If this parameter is FALSE and the new file already exists, the function overwrites the existing file and succeeds.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Security attributes for the existing file are not copied to the new file.

File attributes for the existing file are copied to the new file. For example, if an existing file has the FILE_ATTRIBUTE_READONLY file attribute, a copy created through a call to CopyFile will also have the FILE_ATTRIBUTE_READONLY file attribute. For more information about file attributes, see CreateFile.

To store the maximum number of files on PC Card storage devices, limit file names to eight uppercase characters and file extensions to three uppercase characters. Also, do not allow non-OEM characters in file names. File names that do not conform to these limits require more than one physical directory entry on a PC Card.

See Also

CreateFile, MoveFile


CopyRect

This function copies the coordinates of one rectangle to another.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CopyRect(LPRECT lprcDst, const RECT *lprcSrc);

Parameters

lprcDst
Long pointer to the RECT structure that will receive the logical coordinates of the source rectangle.
lprcSrc
Long pointer to the RECT structure whose coordinates are to be copied.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

RECT, SetRect, SetRectEmpty


CoTaskMemAlloc

This function allocates a block of task memory.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

LPVOID CoTaskMemAlloc(ULONG cb);

Parameter

cb
[in] Size, in bytes, of the memory block to be allocated.

Return Values

A pointer to the allocated memory block indicates success. NULL indicates insufficient memory.

Remarks

The initial contents of the returned memory block are undefined – there is no guarantee that the block has been initialized. The allocated block may be larger than cb bytes because of the space required for alignment and for maintenance information.

If cb is zero, CoTaskMemAlloc allocates a zero-length item and returns a valid pointer to that item. If there is insufficient memory available, CoTaskMemAlloc returns NULL.

Applications should always check the return value from this method, even when requesting small amounts of memory, because there is no guarantee the memory will be allocated.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoTaskMemFree

This function frees a block of task memory previously allocated through a call to the CoTaskMemAlloc or CoTaskMemRealloc function.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

void CoTaskMemFree(void pv);

Parameter

pv
[in] Void pointer to the memory block to be freed.

Return Values

None.

Remarks

The CoTaskMemFree function, using the default OLE allocator, frees a block of memory previously allocated through a call to the CoTaskMemAlloc or CoTaskMemRealloc function.

The number of bytes freed equals the number of bytes that were originally allocated or reallocated. After the call, the memory block pointed to by pv is invalid and can no longer be used.

The pv parameter can be NULL, in which case this method has no effect.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoTaskMemRealloc

This function changes the size of a previously allocated block of task memory.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

LPVOID CoTaskMemRealloc(LPVOID pv, ULONG cb);

Parameters

pv
[in] Void pointer to the memory block to be reallocated. It can be a NULL pointer, as discussed in the Remarks.
cb
[in] Size, in bytes, of the memory block to be reallocated. It can be zero, as discussed in the following remarks.

Return Values

A pointer to the reallocated memory block indicates success. NULL indicates insufficient memory, or that cb is zero and pv is not NULL.

Remarks

The pv argument points to the beginning of the memory block. If pv is NULL, CoTaskMemRealloc allocates a new memory block in the same way as the CoTaskMemAlloc function. If pv is not NULL, it should be a pointer returned by a prior call to CoTaskMemAlloc.

The cb argument specifies the size (in bytes) of the new block. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a different memory location, the pointer returned by CoTaskMemRealloc is not guaranteed to be the pointer passed through the pv argument. If pv is not NULL and cb is zero, then the memory pointed to by pv is freed.

CoTaskMemRealloc returns a void pointer to the reallocated (and possibly moved) memory block. The return value is NULL if the size is zero and the buffer argument is not NULL, or if there is not enough memory available to expand the block to the given size. In the first case, the original block is freed; in the second, the original block is unchanged.

The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CoUninitialize

This function closes the OLE Component Object Model (COM) library, freeing any resources that it maintains.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

void CoUninitialize();

Return Values

None.

Remarks

CoUninitialize should be called on application shutdown, as the last call made to the COM library after the application hides its main windows and falls through its main message loop. If there are open conversations remaining, CoUninitialize starts a modal message loop and dispatches any pending messages from the containers or server for this COM application. By dispatching the messages, CoUninitialize ensures that the application does not quit before receiving all of its pending messages. Non-COM messages are discarded.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


CreateBindCtx

This function supplies a pointer to an implementation of IBindCtx, an object that stores information about a particular moniker-binding operation.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.10 and later

Syntax

WINOLEAPI CreateBindCtx ( DWORD reserved, LPBC FAR * ppbc);

Parameters

reserved
[in] Reserved for future use; set to zero.
ppbc
[out] Address of IBindCtx* pointer variable that receives the interface pointer to the new bind context object. When the function is successful, the caller is responsible for calling IUnknown::Release on the bind context. A NULL value for the bind context indicates that an error occurred.

Return Values

S_OK indicates that the bind context was allocated and initialized successfully. The standard return value E_OUTOFMEMORY is also supported.

Remarks

CreateBindCtx is most commonly used in the process of binding a moniker (locating and getting a pointer to an interface by identifying it through a moniker), as in the following steps:

  1. Get a pointer to a bind context by calling the CreateBindCtx function.
  2. Call the IMoniker::BindToObject method on the moniker, retrieving an interface pointer to the object to which the moniker refers.
  3. Release the bind context.
  4. Use the interface pointer.
  5. Release the interface pointer.

The following code example shows these steps.

// pMnk is an IMoniker * that points to a previously acquired moniker
IFoo *pFoo;
IBindCtx *pbc;

CreateBindCtx( 0, &pbc );
pMnk->BindToObject( pbc, NULL, IID_IFoo, &pFoo );
pbc->Release();
// pFoo now points to the object; safe to use pFoo
pFoo->Release();

Bind contexts are also used in other methods of the IMoniker interface besides IMoniker::BindToObject.

A bind context retains references to the objects that are bound during the binding operation, causing the bound objects to remain active (keeping the object's server running) until the bind context is released. Reusing a bind context when subsequent operations bind to the same object can improve performance. You should, however, release the bind context as soon as possible, because you could be keeping the objects activated unnecessarily.

A bind context contains a BIND_OPTS structure, which contains parameters that apply to all steps in a binding operation. When you create a bind context using CreateBindCtx, the fields of the BIND_OPTS structure are initialized to the following values:

cbStruct = sizeof(BIND_OPTS)
grfFlags = 0
grfMode = STGM_READWRITE
dwTickCountDeadline = 0.

You can call the IBindCtx::SetBindOptions method to modify these default values.


CreateDirectory

This function creates a new directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory.

A remote application interface (RAPI) version of this function exists, and it is named CeCreateDirectory.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CreateDirectory(LPCTSTR lpPathName, LPSECURITY_ATTRIBUTES lpSecurityAttributes);

Parameters

lpPathName
[in] Long pointer to a null-terminated string that specifies the path of the directory to be created.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the CreateDirectory function parses paths.

lpSecurityAttributes
[in] Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Some file systems, such as NTFS, support compression or encryption for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression and encryption attributes of its parent directory.

See Also

CreateFile, RemoveDirectory


CreateErrorInfo

This function creates an instance of a generic error object.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CreateErrorInfo(ICreateErrorInfo ** pperrinfo);

Parameters

pperrinfo
Pointer to a pointer to a system-implemented generic error object.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Could not create the error object.

Remarks

This function returns a pointer to a generic error object, which you can use with QueryInterface on ICreateErrorInfo to set its contents. You can then pass the resulting object to SetErrorInfo. The generic error object implements both ICreateErrorInfo and IErrorInfo.

Example

ICreateErrorInfo *perrinfo;
HRESULT hr;

hr = CreateErrorInfo(&pcerrinfo);

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


CreateEvent

This function creates a named or an unnamed event object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE CreateEvent( LPSECURITY_ATTRIBUTES lpEventAttributes,
BOOL bManualReset, BOOL bInitialState, LPTSTR lpname );

Parameters

lpEventAttributes
Ignored. Must be NULL.
bManualReset
Boolean that specifies whether a manual-reset or auto-reset event object is created. If TRUE, then you must use the ResetEvent function to manually reset the state to nonsignaled. If FALSE, the system automatically resets the state to nonsignaled after a single waiting thread has been released.
bInitialState
Boolean that specifies the initial state of the event object. If TRUE, the initial state is signaled; otherwise, it is nonsignaled.
lpName
Pointer to a null-terminated string that specifies the name of the event object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named event object, the bManualReset and bInitialState parameters are ignored because they have already been set by the creating process.

If lpName is NULL, the event object is created without a name.

If lpName matches the name of an existing semaphore, mutex, waitable timer, job, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same name space.

Return Values

A handle to the event object indicates success. If the named event object existed before the function call, the function returns a handle to the existing object and GetLastError returns ERROR_ALREADY_EXISTS. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The handle returned by CreateEvent has EVENT_ALL_ACCESS access to the new event object and can be used in any function that requires a handle to an event object.

Any thread of the calling process can specify the event-object handle in a call to one of the wait functions. The single-object wait functions return when the state of the specified object is signaled. The multiple-object wait functions can be instructed to return either when any one of the specified objects are signaled. When a wait function returns, the waiting thread is released to continue its execution.

The initial state of the event object is specified by the bInitialState parameter. Use the SetEvent function to set the state of an event object to signaled. Use the ResetEvent function to reset the state of an event object to nonsignaled.

When the state of a manual-reset event object is signaled, it remains signaled until it is explicitly reset to nonsignaled by the ResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object, can be released while the object’s state is signaled.

When the state of an auto-reset event object is signaled, it remains signaled until a single waiting thread is released; the system then automatically resets the state to nonsignaled. If no threads are waiting, the event object’s state remains signaled.

Multiple processes can have handles of the same event object, enabling use of the object for interprocess synchronization. The following object-sharing mechanism is available: a process can specify the name of an event object in a call to the CreateEvent function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The event object is destroyed when its last handle has been closed.

See Also

CloseHandle, ResetEvent, SetEvent, WaitForSingleObject


CreateFile

This function creates, opens, or truncates a file, communications resource, disk device, or console. It returns a handle that can be used to access the object. It can also open and return a handle to a directory.

A remote application interface (RAPI) version of this function exists, and it is named CeCreateFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE CreateFile(LPCTSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes, DWORD dwCreationDistribution, DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile);

Parameters

lpFileName
[in] Pointer to a null-terminated string that specifies the name of the object (file, communications resource, disk device, console, or directory) to create or open.

If *lpFileName is a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CreateFile function parses paths.

When lpFileName points to a communications resource to open, you must include a colon after the name. For example, specify “COM1:” to open that port.

dwDesiredAccess
[in] Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. This parameter can be any combination of the following values.
Value
Description
0 | Specifies device query access to the object. An application can query device attributes without accessing the device.
GENERIC_READ | Specifies read access to the object. Data can be read from the file and the file pointer can be moved. Combine with GENERIC_WRITE for read-write access.
GENERIC_WRITE | Specifies write access to the object. Data can be written to the file and the file pointer can be moved. Combine with GENERIC_READ for read-write access.

dwShareMode
[in] Specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

To share the object, use a combination of one or more of the following values:
Value
Description
FILE_SHARE_READ | Subsequent open operations on the object will succeed only if read access is requested.
FILE_SHARE_WRITE | Subsequent open operations on the object will succeed only if write access is requested.

lpSecurityAttributes
[in] Ignored; set to NULL.
dwCreationDisposition
[in] Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. This parameter must be one of the following values:
Value
Description
CREATE_NEW | Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS | Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
OPEN_EXISTING | Opens the file. The function fails if the file does not exist.
See the Remarks section for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFile function for devices, including the console.
OPEN_ALWAYS | Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDisposition were CREATE_NEW.
TRUNCATE_EXISTING | Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.

dwFlagsAndAttributes
[in] Specifies the file attributes and flags for the file.

Any combination of the following attributes is acceptable for the dwFlagsAndAttributes parameter, except all other file attributes override FILE_ATTRIBUTE_NORMAL.
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file should be archived. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_HIDDEN | The file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_READONLY | The file is read only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM | The file is part of or is used exclusively by the operating system.
FILE_ATTRIBUTE_TEMPORARY | Not supported.

Any combination of the following flags is acceptable for the dwFlagsAndAttributes parameter.
Value
Description
FILE_FLAG_WRITE_THROUGH | Instructs the system to write through any intermediate cache and go directly to disk. The system can still cache write operations, but cannot lazily flush them.
FILE_FLAG_OVERLAPPED | This flag is not supported; however, multiple reads/writes pending on a device at a time are allowed.
FILE_FLAG_RANDOM_ACCESS | Indicates that the file is accessed randomly. The system can use this as a hint to optimize file caching.
FILE_FLAG_SEQUENTIAL_SCAN | Indicates that the file is to be accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur; however, correct operation is still guaranteed.
Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.

hTemplateFile
[in] Ignored; as a result, CreateFile does not copy the extended attributes to the new file.

Return Values

An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastError returns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

Use the CloseHandle function to close an object handle returned by CreateFile.

As noted above, specifying zero for dwDesiredAccess allows an application to query device attributes without actually accessing the device. This type of querying is useful, for example, if an application wants to determine the size of a floppy disk drive and the formats it supports without having a floppy in the drive.

Files

When creating a new file, the CreateFile function performs the following actions:

  • Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.
  • Sets the file length to zero.

When opening an existing file, CreateFile performs the following actions:

  • Combines the file flags specified by dwFlagsAndAttributes with existing file attributes. CreateFile ignores the file attributes specified by dwFlagsAndAttributes.
  • Sets the file length according to the value of dwCreationDisposition.

To store the maximum number of files on PC Card storage devices, limit file names to eight uppercase characters and file extensions to three uppercase characters. Also, do not allow non-OEM characters in file names. File names that do not conform to these limits require more than one physical directory entry on a PC Card.

Communications Resources

The CreateFile function can create a handle to a communications resource. By setting the dwCreationDisposition parameter to OPEN_EXISTING, read, write, or read-write access can be specified.

Directories

An application cannot create a directory with CreateFile; it must call CreateDirectory to create a directory.

Some file systems, such as NTFS, support compression or encryption for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression and encryption attributes of its parent directory.

See Also

CloseHandle, CreateDirectory, ReadFile, VirtualAlloc


CreateFileForMapping

This function creates a file that can be used for memory mapping.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CreateFileForMapping( LPCTSTR lpFileName,
DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes,
DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile);

Parameters

lpFileName
Pointer to a null-terminated string that specifies the name of the file that is to be created and used as a file-mapping object. The maximum length is MAX_PATH characters.
dwDesiredAccess
Specifies the type of access. An application can obtain read-only access to files, or query device attributes. You can use the following flag constants to build a value for this parameter.
Value
Description
0 | Allows an application to query device attributes without actually accessing the device.
GENERIC_READ | Specifies read access to the file. Data can be read from the file and the file pointer can be moved.
GENERIC_WRITE | For Windows CE versions 2.10 and later, this flag specifies write access to the file.

dwShareMode
Specifies how this file can be shared. This parameter must be some combination of the following values:
Value
Description
0 | Prevents the file from being shared.
FILE_SHARE_READ | Other open operations can be performed on the file for read access. If CreateFile is opening the client end of a mailslot, this flag is specified.
FILE_SHARE_WRITE | Other open operations can be performed on the file for write access.

lpSecurityAttributes
Not used; set to NULL.
dwCreationDisposition
This parameter is one of the following values:
Value
Description
CREATE_NEW | Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS | Creates a new file. The function overwrites the file if it exists.
OPEN_EXISTING | Opens the file. The function fails if the file does not exist.
OPEN_ALWAYS | Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDistribution were CREATE_NEW.
TRUNCATE_EXISTING | Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.

dwFlagsAndAttributes
Specifies the file attributes and flags for the file.

Any combination of the following attributes is acceptable, except all other file attributes override FILE_ATTRIBUTE_NORMAL.
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED | The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_HIDDEN | The file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_READONLY | The file is read only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM | The file is part of or is used exclusively by the operating system.

Any combination of the following flags is acceptable:

Value
Description
FILE_FLAG_WRITE_THROUGH | Instructs the operating system to write through any intermediate cache and go directly to the file. The operating system can still cache write operations, but cannot lazily flush them.
FILE_FLAG_RANDOM_ACCESS | Indicates that the file is accessed randomly. Windows uses this flag to optimize file caching. Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.

hTemplateFile
Not used; ignored.

Return Values

An open handle to the specified file-mapping object indicates success. If the specified object exists before the function call and dwCreationDistribution is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file-mapping object does not exist before the call, GetLastError returns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateFileForMapping function is a special version of CreateFile that is designed for file-mapping objects. It performs a callback into the kernel's address space so that the specified file is created by the kernel. This ensures that the file is available to processes other than the creating process.

The handle returned from CreateFileForMapping is used as the hFile parameter in a subsequent call to CreateFileMapping, as shown in the following psuedo-code:

// psuedocode fragment to show call sequence, use of the handle
HANDLE hFile;
hFile = CreateFileForMapping(...);
CreateFileMapping(hFile, ...);

If your process exits without having called CreateFileMapping, the handle returned by CreateFileForMapping is automatically closed.

See Also

CreateFileMapping, MapViewOfFile, UnmapViewOfFile


CreateFileMapping

This function creates a named or unnamed file-mapping object for the specified file.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CreateFileMapping(HANDLE hFile,
LPSECURITY_ATTRIBUTES lpFileMappingAttributes, DWORD flProtect,
DWORD dwMaximumSizeHigh, DWORD dwMaximumSizeLow,
LPCTSTR lpName );

Parameters

hFile
Handle to the file from which to create a mapping object. The file must be opened with an access mode compatible with the protection flags specified by the flProtect parameter. It is recommended, though not required, that files you intend to map be opened for exclusive access.

If hFile is (HANDLE)0xFFFFFFFF, the calling process must also specify a mapping object size in the dwMaximumSizeHigh and dwMaximumSizeLow parameters. The function creates a file-mapping object of the specified size backed by physical memory rather than by a named file in the file system. The file-mapping object can be shared by name. In Windows CE, memory utilized for the mapping object is not part of the 32 MB virtual process space.

lpFileMappingAttributes
Ignored. Must be NULL.
flProtect
Specifies the protection desired for the file view, when the file is mapped. This parameter can be one of the following values:
Value
Description
PAGE_READONLY | Gives read-only access to the committed region of pages. An attempt to write to or execute the committed region results in an access violation. The file specified by the hFile parameter must have been created with GENERIC_READ access. You cannot specify PAGE_READONLY without a file handle.
PAGE_READWRITE | Gives read-write access to the committed region of pages. The file specified by hFile must have been created with GENERIC_READ and GENERIC_WRITE access.
PAGE_WRITECOPY | Not supported.

In addition, an application can specify certain section attributes by combining (using the bitwise OR operator) one or more of the following section attribute values with one of the preceding page protection values:
Value
Description
SEC_COMMIT | Allocates physical storage in memory or in the paging file on disk for all pages of a section. This is the default setting.
SEC_IMAGE | Not supported.
SEC_NOCACHE | Not supported.
SEC_RESERVE | Not supported.

dwMaximumSizeHigh
Specifies the high-order 32 bits of the maximum size of the file-mapping object.
dwMaximumSizeLow
Specifies the low-order 32 bits of the maximum size of the file-mapping object. If this parameter and dwMaximumSizeHig are zero, the maximum size of the file-mapping object is equal to the current size of the file identified by hFile.
lpName
Long pointer to a null-terminated string specifying the name of the mapping object. The name can contain any character except the backslash character (\).

If this parameter matches the name of an existing named mapping object, the function requests access to the mapping object with the protection specified by flProtect.

If this parameter is NULL, the mapping object is created without a name.

If lpName matches the name of an existing event, semaphore, mutex, waitable timer, or job, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same name space.

Return Values

A handle to the file-mapping object indicates success. If the object existed before the function call, the function returns a handle to the existing object — with its current size, not the specified size — and GetLastError returns ERROR_ALREADY_EXISTS. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If you call CreateFileMapping with a handle from CreateFileForMapping and it fails for any reason, the handle is closed.

This function will not work on a Windows CE–based platform that does not support Page-In.

After a file-mapping object has been created, the size of the file must not exceed the size of the file-mapping object; if it does, not all of the file’s contents will be available for sharing.

If an application specifies a size for the file-mapping object that is larger than the size of the actual named file on disk, the file on disk is grown to match the specified size of the file-mapping object. If the file cannot be grown, this results in a failure to create the file-mapping object. GetLastError will return ERROR_DISK_FULL.

The handle that CreateFileMapping returns has full access to the new file-mapping object. It can be used with any function that requires a handle to a file-mapping object. File-mapping objects can be shared through process creation.

File handles that have been used to create file-mapping objects must not be used in subsequent calls to file I/O functions, such as ReadFile and WriteFile. In general, if a file handle has been used in a successful call to the CreateFileMapping function, do not use that handle unless you first close the corresponding file-mapping object.

Creating a file-mapping object creates the potential for mapping a view of the file but does not map the view. The MapViewOfFile function maps a view of a file into the address space of a process.

With one important exception, file views derived from a single file-mapping object are coherent, or identical, at a given time. If multiple processes have handles of the same file-mapping object, they see a coherent view of the data when they map a view of the file.

The exception has to do with remote files. Although CreateFileMapping works with remote files, it does not keep them coherent. For example, if two computers both map a file as writeable, and both change the same page, each computer will only see its own writes to the page. When the data gets updated on the disk, it is not merged.

A mapped file and a file accessed by means of the input and output (I/O) functions (ReadFile and WriteFile) are not necessarily coherent.

To fully close a file mapping object, an application must unmap all mapped views of the file mapping object by calling UnmapViewOfFile, and close the file mapping object handle by calling CloseHandle. The order in which these functions are called does not matter. The call to UnmapViewOfFile is necessary because mapped views of a file mapping object maintain internal open handles to the object, and a file mapping object will not close until all open handles to it are closed.

Note To guard against an access violation, use structured exception handling to protect any code that writes to or reads from a memory mapped view.

Example

To implement a mapping-object creation function that fails if the object already exists, an application can use the following code.

hMap = CreateFileMapping(...);

if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS)
{
    CloseHandle(hMap);
    hMap = NULL;
}
return hMap;

See Also

CloseHandle, CreateFileForMapping, MapViewOfFile, ReadFile, UnmapViewOfFile, VirtualAlloc, WriteFile


CreateMutex

This function creates a named or unnamed mutex object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CreateMutex( LPSECURITY_ATTRIBUTES lpMutexAttributes,
BOOL bInitialOwner, LPCTSTR lpName );

Parameters

lpMutexAttributes
Ignored. Must be NULL.
bInitialOwner
Boolean that specifies the initial owner of the mutex object. If this value is TRUE and the caller created the mutex, the calling thread obtains ownership of the mutex object. Otherwise, the calling thread does not obtain ownership of the mutex. To determine if the caller created the mutex, see the Return Values section.
lpName
Long pointer to a null-terminated string specifying the name of the mutex object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named mutex object, the bInitialOwner parameter is ignored because it has already been set by the creating process.

If lpName is NULL, the mutex object is created without a name.

If lpName matches the name of an existing event, semaphore, waitable timer, job, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same name space.

Return Values

A handle to the mutex object indicates success. If the named mutex object existed before the function call, the function returns a handle to the existing object and GetLastError returns ERROR_ALREADY_EXISTS. Otherwise, the caller created the mutex. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The handle returned by CreateMutex has MUTEX_ALL_ACCESS access to the new mutex object and can be used in any function that requires a handle to a mutex object.

Any thread of the calling process can specify the mutex-object handle in a call to one of the wait functions. The single-object wait functions return when the state of the specified object is signaled. The multiple-object wait functions can be instructed to return either when any one or when all of the specified objects are signaled. When a wait function returns, the waiting thread is released to continue its execution.

The state of a mutex object is signaled when it is not owned by any thread. The creating thread can use the bInitialOwner flag to request immediate ownership of the mutex. Otherwise, a thread must use one of the wait functions to request ownership. When the mutex’s state is signaled, one waiting thread is granted ownership, the mutex’s state changes to nonsignaled, and the wait function returns. Only one thread can own a mutex at any given time. The owning thread uses the ReleaseMutex function to release its ownership.

The thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. Typically, you would not wait repeatedly for the same mutex, but this mechanism prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call ReleaseMutex once for each time that the mutex satisfied a wait.

Two or more processes can call CreateMutex to create the same named mutex. The first process actually creates the mutex, and subsequent processes open a handle to the existing mutex. This enables multiple processes to get handles of the same mutex, while relieving the user of the responsibility of ensuring that the creating process is started first. When using this technique, you should set the bInitialOwner flag to FALSE; otherwise, it can be difficult to be certain which process has initial ownership.

Multiple processes can have handles of the same mutex object, enabling use of the object for interprocess synchronization. The following object-sharing mechanism is available: A process can specify the name of a mutex object in a call to the CreateMutex function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The mutex object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, ReleaseMutex


CreateOleAdviseHolder

This function instantiates an advise holder object for managing compound document notifications. It passes out a pointer to the object’s OLE implementation of the IOleAdviseHolder interface.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI CreateOleAdviseHolder(
IOleAdviseHolder FAR * FAR * ppOAHolder);

Parameter

ppOAHolder
[out] Pointer to IOleAdviseHolder* pointer variable that receives the interface pointer to the new advise holder object.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK
The new OLE advise holder returned successfully.

Remarks

The function CreateOleAdviseHolder creates an instance of an advise holder, which supports the OLE implementation of the IOleAdviseHolder interface. The methods of this interface are intended to be used to implement the advisory methods of IOleObject, and, when advisory connections have been set up with objects supporting an advisory sink, to send notifications of changes in the object to the advisory sink. The advise holder returned by CreateOleAdviseHolder will suffice for the great majority of applications. The OLE-provided implementation does not, however, support IOleAdviseHolder::EnumAdvise, so if you need to use this method, you will need to implement your own advise holder.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


CreateProcess

This function is used to run a new program. It creates a new process and its primary thread. The new process executes the specified executable file.

A remote application interface (RAPI) version of this function exists, and it is named CeCreateProcess.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL CreateProcess( LPCTSTR lpApplicationName,
LPTSTR lpCommandLine,
LPSECURITY_ATTRIBUTES lpProcessAttributes, LPSECURITY_ATTRIBUTES lpThreadAttributes,
BOOL bInheritHandles, DWORD dwCreationFlags, LPVOID lpEnvironment,
LPCTSTR lpCurrentDirectory, LPSTARTUPINFO lpStartupInfo,
LPPROCESS_INFORMATION lpProcessInformation );

Parameters

lpApplicationName
Pointer to a null-terminated string that specifies the module to execute.

The string can specify the full path and filename of the module to execute or it can specify a partial name. In the case of a partial name, the function uses the current drive and current directory to complete the specification.

The lpApplicationName parameter must be non-NULL and must include the module name.

lpCommandLine
Pointer to a null-terminated string that specifies the command line to execute. The system adds a null character to the command line, trimming the string if necessary, to indicate which file was actually used.

The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.

If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. C runtime processes can use the argc and argv arguments.

If the filename does not contain an extension, .EXE is assumed. If the filename ends in a period (.) with no extension, or the filename contains a path, .EXE is not appended.

Windows CE versions 2.10 and later search the directories indicated by the lpApplicationName parameter in the following order:

  • The windows (\windows) directory
  • The root (\) directory of the device
  • An OEM-dependent directory
  • The OEM-defined shell (\ceshell) directory — Embedded Toolkit users only

Windows CE versions 1.0 through 2.01 search the directories indicated by the lpApplicationName parameter in the following order:

  • The root of the PC Card, if it exists
  • The windows (\windows) directory
  • The root (\ ) directory of the device
lpProcessAttributes
Not supported; set to NULL.
lpThreadAttributes
Not supported; set to NULL.
bInheritHandles
Not supported; set to NULL.
dwCreationFlags
Specifies additional flags that control the priority class and the creation of the process. The following creation flags can be specified in any combination, except as noted:
Value
Description
CREATE_DEFAULT_ERROR_MODE | Not supported.
CREATE_NEW_CONSOLE | The new process has a new console, instead of inheriting the parent’s console. This flag cannot be used with the DETACHED_PROCESS flag.
CREATE_NEW_PROCESS_GROUP | Not supported.
CREATE_SEPARATE_WOW_VDM | Not supported.
CREATE_SHARED_WOW_VDM | Not supported.
CREATE_SUSPENDED | The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT | Not supported.
DEBUG_PROCESS | If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. Child processes of the new process are also debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
If you create a process with this flag set, only the calling thread (the thread that called CreateProcess) can call the WaitForDebugEvent function.
DEBUG_ONLY_THIS_PROCESS | If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. No child processes of the new process are debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
DETACHED_PROCESS | Not supported.

Windows CE does not support the concept of a priority class. The priority of a thread is the only parameter that determines a threads scheduling priority.

For Windows CE version 1.0 and 1.01, the dwCreationFlags parameter only supports the following values: CREATE_SUSPENDED and zero.

lpEnvironment
Not supported; set to NULL.
lpCurrentDirectory
Not supported; set to NULL.
lpStartupInfo
Not supported; set to NULL.
lpProcessInformation
Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The CreateProcess function is used to run a new program. In addition to creating a process, CreateProcess also creates a thread object. The thread is created with an initial stack whose size is described in the image header of the specified program’s executable file. The thread begins execution at the image’s entry point.

The new process and the new thread handles are created with full access rights. For either handle, the handle can be used in any function that requires an object handle to that type.

The process is assigned a 32-bit process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in the OpenProcess function to open a handle to the process. The initial thread in the process is also assigned a 32-bit thread identifier. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the PROCESS_INFORMATION structure.

When specifying an application name in the lpApplicationName string, it doesn’t matter whether the application name includes the filename extension.

ExitThread, CreateThread, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

  • During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.
  • Only one thread in a process can be in a DLL initialization or detach routine at a time.

The created process remains in the system until all threads within the process have terminated and all handles to the process and any of its threads have been closed through calls to CloseHandle. The handles for both the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, it is best to close them immediately after the process is created.

When the last thread in a process terminates, the following events occur:

  • All objects opened by the process are implicitly closed.
  • The process’s termination status (which is returned by GetExitCodeProcess) changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.
  • The thread object of the main thread is set to the signaled state, satisfying any threads that were waiting on the object.
  • The process object is set to the signaled state, satisfying any threads that were waiting on the object.

The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process object.

See Also

CloseHandle, CreateThread, ExitThread, PROCESS_INFORMATION, ResumeThread, TerminateProcess


CreateThread

This function creates a thread to execute within the address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

HANDLE CreateThread(LPSECURITY_ATTRIBUTES lpThreadAttributes,
DWORD dwStackSize, LPTHREAD_START_ROUTINE lpStartAddress,
LPVOID lpParameter, DWORD dwCreationFlags, LPDWORD lpThreadId );

Parameters

lpThreadAttributes
Ignored. Must be NULL.
dwStackSize
Ignored. The default stack size for a thread is determined by the linker setting /STACK.
lpStartAddress
Long pointer to the application-defined function of type LPTHREAD_START_ROUTINE to be executed by the thread and represents the starting address of the thread. For more information on the thread function, see ThreadProc.
lpParameter
Long pointer to a single 32-bit parameter value passed to the thread.
dwCreationFlags
Specifies flags that control the creation of the thread.
Value
Description
CREATE_SUSPENDED | The thread is created in a suspended state, and will not run until the ResumeThread function is called.
0 | The thread runs immediately after creation.

lpThreadId
Long pointer to a 32-bit variable that receives the thread identifier.

If this parameter is NULL, the thread identifier is not returned.

Return Values

A handle to the new thread indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The number of threads a process can create is limited by the available virtual memory. The number of threads that can be created depends on the default stack size. If every thread has one megabyte of stack space., you can create at most 32 threads. If you reduce the default stack size, you can create more threads. However, your application will have better performance if you create one thread per processor and build queues of requests for which the application maintains the context information. A thread would process all requests in a queue before processing requests in the next queue.

The new thread handle is created with THREAD_ALL_ACCESS to the new thread. The handle can be used in any function that requires a thread object handle.

The thread execution begins at the function specified by the lpStartAddress parameter. If this function returns, the DWORD return value is used to terminate the thread in an implicit call to the ExitThread function. Use the GetExitCodeThread function to get the thread’s return value.

The CreateThread function may succeed even if lpStartAddress points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread’s process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting on the object.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

The ExitThread function, CreateThread function, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means that the following restrictions hold:

  • During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.
  • Only one thread in a process can be in a DLL initialization or detach routine at a time.

See Also

CloseHandle, CreateProcess, ExitThread, GetExitCodeThread, GetThreadPriority, ResumeThread, SetThreadPriority


CreateToolhelp32Snapshot

This function takes a snapshot of the processes and the heaps, modules, and threads used by the processes.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

HANDLE WINAPI CreateToolhelp32Snapshot( DWORD dwFlags,
DWORD th32ProcessID);

Parameters

dwFlags
Specifies portions of the system to include in the snapshot. This parameter can be one of the following:
Value
Description
TH32CS_SNAPALL | Equivalent to specifying TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS, and TH32CS_SNAPTHREAD.
TH32CS_SNAPHEAPLIST | Includes the heap list of the specified process in the snapshot.
TH32CS_SNAPMODULE | Includes the module list of the specified process in the snapshot.
TH32CS_SNAPPROCESS | Includes the process list in the snapshot.
TH32CS_SNAPTHREAD | Includes the thread list in the snapshot.
THCS_GETALLMODES | Returns a list of all the modules loaded in the system.

th32ProcessID
Process identifier. This parameter can be zero to indicate the current process. This parameter is used when the TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE value is specified. Otherwise, it is ignored.

Return Value

An open handle to the specified snapshot indicates success. – 1 indicates failure.

Remarks

The snapshot returned is a copy of the current state of the system. To close a snapshot call the CloseToolhelp32Snapshot function.

The snapshot taken by this function is examined by the other tool help functions to provide their results. Access to the snapshot is read only. The snapshot handle acts like an object handle and is subject to the same rules regarding which processes and threads it is valid in.

To retrieve an extended error status code generated by this function, use the GetLastError function.

See Also

CloseToolhelp32Snapshot


CreateTypeLib2

This function creates a type library in the file/in-memory format that makes use of memory-mapped files for 32-bit platforms. Its output parameter (ppctlib) points to a newly created object that supports the ICreateTypeLib2 interface.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT CreateTypeLib2( SYSKIND syskind, LPOLESTR szFile, ICreateTypeLib2 ** ppctlib);

Remarks

Windows CE does not implement the ICreateTypeLib2::SaveAllChanges method.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


DebugActiveProcess

This function allows a debugger to attach to an active process and then debug it.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL DebugActiveProcess( DWORD dwProcessId );

Parameters

dwProcessId
Specifies the identifier for the process to be debugged. The debugger gets debugging access to the process as if it created the process with the DEBUG_ONLY_THIS_PROCESS flag. See the Remarks section for more details.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

After a successful return from DebugActiveProcess, when the debugger is waiting for debug events using the WaitForDebugEvent function, the system sends a CREATE_PROCESS_DEBUG_EVENT debugging event that identifies the primary thread handle that is currently part of the process. The system sends an individual CREATE_THREAD_DEBUG_EVENT debugging event for each of the secondary thread handles that are currently part of the process. All of these handles have permission (that is, access rights) for getting and setting thread contexts using the GetThreadContext and SetThreadContext functions.

For both the CREATE_PROCESS_DEBUG_EVENT and CREATE_THREAD_DEBUG_EVENT debugging events, the lpStartAddress member of the CREATE_PROCESS_DEBUG_INFO structure is NULL.

Close each of these thread handles using the CloseHandle function.

No initial debug breakpoint is set when DebugActiveProcess successfully attaches.

Windows CE versions 2.0 and later provide built in support for Just-In-Time (JIT) debugging. A JIT debugger is registered by placing the name of your debugger in the string registry value JITDebugger located at HKEY_LOCAL_MACHINE\Debug. To enable JIT, you must perform a warm reset on the Windows CE target platform after the above value is added to the registry. When your debugger is invoked by JIT, the process identifier of the debugee is passed on the command line. The Windows CE JIT is a First-Chance exception handler and not a Second-Chance exception handler which is available on Windows NT.

The debugger must have appropriate access to the target process; it must be able to open the process for PROCESS_ALL_ACCESS access. On Windows CE, the debugger has appropriate access if the process identifier is valid.

After the system checks the process identifier and determines that a valid debugging attachment is being made, the function returns TRUE. The debugger is then expected to wait for debugging events by using the WaitForDebugEvent function. The system suspends all threads in the process and sends the debugger events representing the current state of the process.

For each dynamic-link library (DLL) currently loaded into the address space of the target process, the system sends a LOAD_DLL_DEBUG_EVENT debugging event. The system arranges for the first thread in the process to execute a breakpoint instruction after it resumes. Continuing this thread causes it to return to whatever it was doing before the debugger was attached.

After all of this has been done, the system resumes all threads in the process. When the first thread in the process resumes, it executes a breakpoint instruction that causes an EXCEPTION_DEBUG_EVENT debugging event to be sent to the debugger. All future debugging events are sent to the debugger by using the normal mechanism and rules.

See Also

CreateProcess, CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, WaitForDebugEvent


DebugBreak

This function causes a breakpoint exception to occur in the current process so that the calling thread can signal the debugger and force it to take some action. If the process is not being debugged, the search logic of a standard exception handler is used. In most cases, this causes the calling process to terminate because of an unhandled breakpoint exception.

At a Glance

Header file: | Kfuncs.h
Windows CE versions: | 1.0 and later

Syntax

void DebugBreak( void );

Return Values

None.

See Also

GetExceptionInformation


DeleteAndRenameFile

This function deletes the source file (lpszSourFile) after it copies the content of the source file to the destination file (lpszDestFile).

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL DeleteAndRenameFile( LPCWSTR lpszDestFile,
LPCWSTR lpszSourFile );

Parameters

lpszDestFile
[in] Pointer to the null-terminated string that contains the path to the destination file, and cannot be NULL.
lpszSourFile
[in] Pointer to the null-terminated string that contains the path to the source file, and cannot be NULL.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

The DeleteAndRenameFile function works for the object store RAM-based file system only.


DeleteCriticalSection

This function releases all resources used by an unowned critical section object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void DeleteCriticalSection( LPCRITICAL_SECTION lpCriticalSection );

Parameters

lpCriticalSection
[in] Pointer to the critical section object.

Return Values

None.

Remarks

Deleting a critical section object releases all system resources used by the object. Once deleted, the critical section object cannot be specified in the EnterCriticalSection, TryEnterCriticalSection, or LeaveCriticalSection function.

If a critical section is deleted while it is still owned, the state of the threads waiting for ownership of the deleted critical section is undefined.

See Also

EnterCriticalSection, InitializeCriticalSection, LeaveCriticalSection


DeleteFile

This function deletes an existing file from a file system. A remote application interface (RAPI) version of this function exists, and it is named CeDeleteFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DeleteFile(LPCTSTR lpFileName);

Parameters

lpFileName
[in] Pointer to a null-terminated string that specifies the file to be deleted.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If an application attempts to delete a file that does not exist, the DeleteFile function fails.

The DeleteFile function fails if an application attempts to delete a file that is open for normal I/O or as a memory-mapped file.

To close an open file, use the CloseHandle function.

See Also

CloseHandle, CreateFile


DeregisterDevice

This function deregisters a registered device.

At a Glance

Header file: | Winbase.h
Versions: | 1.0 and later

Syntax

BOOL DeregisterDevice(Handle hDevice);

Parameters

hDevice
Handle to a registered device returned from RegisterDevice.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The DeregisterDevice function can be used if a device is removed from the system or is being shut down. An example would be:

DeregisterDevice(h1);

where h1 was returned from a call to RegisterDevice.

See Also

RegisterDevice


DeviceIoControl

This function sends a control code directly to a specified device driver, causing the corresponding device to perform the specified operation.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL DeviceIoControl( HANDLE hDevice, DWORD dwIoControlCode,
LPVOID lpInBuffer, DWORD nInBufferSize, LPVOID lpOutBuffer,
DWORD nOutBufferSize, LPDWORD lpBytesReturned,
LPOVERLAPPED lpOverlapped );

Parameters

hDevice
[in] Handle to the device that is to perform the operation. Call the CreateFile function to obtain a device handle.
dwIoControlCode
[in] Specifies the control code for the operation. This value identifies the specific operation to be performed and the type of device on which the operation is to be performed. No specific values are defined for the dwIoControlCode parameter. However, the writer of a custom device driver can define IOCTL_XXXX control codes, per the CTL_CODE macro. These control codes can then be advertised, and an application can use these control codes with DeviceIoControl to perform the driver-specific functions.
lpInBuffer
[in] Long pointer to a buffer that contains the data required to perform the operation.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer.
lpOutBuffer
[out] Long pointer to a buffer that receives the operation’s output data.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer.
lpBytesReturned
[out] Long pointer to a variable that receives the size, in bytes, of the data stored into the buffer pointed to by lpOutBuffer.

The lpBytesReturned parameter cannot be NULL. Even when an operation produces no output data, and lpOutBuffer can be NULL, the DeviceIoControl function makes use of the variable pointed to by lpBytesReturned. After such an operation, the value of the variable is without meaning.

lpOverlapped
[in] Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

CreateEvent, CreateFile


DialogProc

This function is an application-defined callback function that processes messages sent to a modal or modeless dialog box.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK DialogProc(HWND hwndDlg, UINT uMsg,
WPARAM wParam, LPARAM lParam);

Parameters

hwndDlg
Handle to the dialog box.
uMsg
Specifies the message.
wParam
Specifies additional message-specific information.
lParam
Specifies additional message-specific information.

Return Values

Typically, the dialog box procedure should return TRUE if it processed the message, and FALSE if it did not. If the dialog box procedure returns FALSE, the dialog manager performs the default dialog operation in response to the message.

If the dialog box procedure processes a message that requires a specific return value, the dialog box procedure should set the desired return value by calling SetWindowLong(hwndDlg, DWL_MSGRESULT, lResult) immediately before returning TRUE. Note that you must call SetWindowLong immediately before returning TRUE; doing so earlier may result in the DWL_MSGRESULT value being overwritten by a nested dialog box message.

  • The following messages are exceptions to the general rules:
WM_CHARTOITEM | WM_CTLCOLORSCROLLBAR
WM_COMPAREITEM | WM_CTLCOLORSTATIC
WM_CTLCOLORBTN | WM_INITDIALOG
WM_CTLCOLORDLG | WM_QUERYDRAGICON
WM_CTLCOLOREDIT | WM_VKEYTOITEM
WM_CTLCOLORLISTBOX |

Consult the documentation for the specific message for details on the semantics of the return value.

Remarks

You should use the dialog box procedure only if you use the dialog box class for the dialog box. This is the default class and is used when no explicit class is specified in the dialog box template. Although the dialog box procedure is similar to a window procedure, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the dialog box window procedure.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, DefWindowProc, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, SetFocus, WM_INITDIALOG


DispGetIDsOfNames

This function uses type information to convert a set of names to DISPIDs.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DispGetIDsOfNames(ITypeInfo* ptinfo, OLECHAR FAR* FAR * rgszNames, unsigned int cNames, DISPID FAR* rgdispid);

Parameters

ptinfo
Pointer to the type information for an interface. This type information is specific to one interface and language code, so it is not necessary to pass an interface identifier (IID) or LCID to this function.
rgszNames
Array of name strings that can be the same array passed to DispInvoke in the DISPPARAMS structure. If cNames is greater than 1, the first name is interpreted as a method name, and subsequent names are interpreted as parameters to that method.
cNames
Number of elements in rgszNames.
rgdispid
Pointer to an array of DISPIDs to be filled in by this function. The first identifier corresponds to the method name. Subsequent identifiers are interpreted as parameters to the method.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | The interface is supported.
E_INVALIDARG | One of the arguments is invalid.
DISP_E_UNKNOWNNAME | One or more of the given names were not known. The returned array of DISPIDs contains DISPID_UNKNOWN for each entry that corresponds to an unknown name.
Other return codes | Any of the ITypeInfo::Invoke errors can also be returned.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

This code from the Lines sample file Points.cpp implements the member function GetIDsOfNames for the CPoints class using DispGetIDsOfNames.

STDMETHODIMP
CPoints::GetIDsOfNames(
        REFIID riid,
        char FAR* FAR* rgszNames,
        UINT cNames,
        LCID lcid,
        DISPID FAR* rgdispid)
{
    return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgdispid);
}


DispGetParam

This function retrieves a parameter from the DISPPARAMS structure, checks both named parameters and positional parameters, and coerces the parameter to the specified type.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DispGetParam(DISPPARAMS FAR* pdispparams, unsigned int position, VARTYPE vtTarg, VARIANT FAR* pvarResult, unsigned int FAR* puArgErr);

Parameters

pdispparams
Pointer to the parameters passed to IDispatch::Invoke.
position
Position of the parameter in the parameter list. DispGetParam starts at the end of the array, so if position is 0, the last parameter in the array is returned.
vtTarg
Type the argument should be coerced to.
pvarResult
Pointer to the variant to pass the parameter into.
puArgErr
On return, pointer to the index of the argument that caused a DISP_E_TYPEMISMATCH error. This pointer is returned to Invoke to indicate the position of the argument in DISPPARAMS that caused the error.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADVARTYPE | The variant type vtTarg is not supported.
DISP_E_OVERFLOW | The retrieved parameter could not be coerced to the specified type.
DISP_E_PARAMNOTFOUND | The parameter indicated by position could not be found.
DISP_E_TYPEMISMATCH | The argument could not be coerced to the specified type.
E_INVALIDARG | One of the arguments was invalid.
E_OUTOFMEMORY | Insufficient memory to complete operation.

Remarks

The output parameter pvarResult must be a valid variant. Any existing contents are released in the standard way. The contents of the variant are freed with VariantFree.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

If you have used DispGetParam to get the right side of a property put operation, the second parameter should be DISPID_PROPERTYPUT. For example:

DispGetParam(&dispparams, DISPID_PROPERTYPUT, VT_BOOL, &varResult)

Named parameters cannot be accessed positionally, and vice versa.

Example

The following code example uses DispGetParam to set X and Y properties:

STDMETHODIMP
CPoint::Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    unsigned short wFlags,
    DISPPARAMS FAR* pdispparams,
    VARIANT FAR* pvarResult,
    EXCEPINFO FAR* pExcepInfo,
    unsigned int FAR* puArgErr)
{
    unsigned int uArgErr;
    HRESULT hresult;
    VARIANTARG varg0;
    VARIANT varResultDummy;

    UNUSED(lcid);
    UNUSED(pExcepInfo);

    // Make sure the wFlags are valid.
    if(wFlags & ~(DISPATCH_METHOD | DISPATCH_PROPERTYGET |
        DISPATCH_PROPERTYPUT | DISPATCH_PROPERTYPUTREF))
        return ResultFromScode(E_INVALIDARG);

    // This object only exposes a "default" interface.
    if(!IsEqualIID(riid, IID_NULL))
        return ResultFromScode(DISP_E_UNKNOWNINTERFACE);

    // It simplifies the following code if the caller
    // ignores the return value.
    if(puArgErr == NULL)
        puArgErr = &uArgErr;
    if(pvarResult == NULL)
        pvarResult = &varResultDummy;

    VariantInit(&varg0);

    // Assume the return type is void, unless otherwise is found.
    VariantInit(pvarResult);

    switch(dispidMember){
    case IDMEMBER_CPOINT_GETX:
        V_VT(pvarResult) = VT_I2;
        V_I2(pvarResult) = GetX();
        break;

    case IDMEMBER_CPOINT_SETX:
        HRESULT = DispGetParam(pdispparams, 0, VT_I2, &varg0, puArgErr);
        if(HRESULT != NOERROR)
            return hresult;
        SetX(V_I2(&varg0));
        break;

    case IDMEMBER_CPOINT_GETY:
        V_VT(pvarResult) = VT_I2;
        V_I2(pvarResult) = GetY();
        break;

    case IDMEMBER_CPOINT_SETY:
        HRESULT = DispGetParam(pdispparams, 0, VT_I2, &varg0, puArgErr);
        if(HRESULT != NOERROR)
            return hresult;
        SetY(V_I2(&varg0));
        break;

    default:
        return ResultFromScode(DISP_E_MEMBERNOTFOUND);
    }
    return NOERROR;
}


DispInvoke

This function automatically calls member functions on an interface, given the type information for the interface.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT DispInvoke(void FAR* _this, ITypeInfo FAR* ptinfo,
DISPID dispidMember, unsigned short wFlags,
DISPPARAMS FAR* pparams, VARIANT FAR* pvarResult,
EXCEPINFO pexcepinfo, unsigned int FAR* puArgErr);

Parameters

_this
Pointer to an implementation of the IDispatch interface described by ptinfo.
ptinfo
Pointer to the type information that describes the interface.
dispidMember
Identifies the member. Use GetIDsOfNames or the object’s documentation to obtain the DISPID.
wFlags
Flags describing the context of the Invoke call, as follows:
Value
Description
DISPATCH_METHOD | The member is invoked as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag can be set.
DISPATCH_PROPERTYGET | The member is retrieved as a property or data member.
DISPATCH_PROPERTYPUT | The member is changed as a property or data member.
DISPATCH_PROPERTYPUTREF | The member is changed by a reference assignment, rather than a value assignment. This flag is valid only when the property accepts a reference to an object.

pparams
Pointer to a structure that contains an array of arguments, an array of argument DISPIDs for named arguments, and counts for number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result. This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.
pexcepinfo
Pointer to a structure that contains exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.
puArgErr
Index within rgvarg of the first argument that has an error. Arguments are stored in pdispparams->rgvarg in reverse order, so the first argument is the one with the highest index in the array. This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADPARAMCOUNT | The number of elements provided in DISPPARAMS is different from the number of arguments accepted by the method or property.
DISP_E_BADVARTYPE | One of the arguments in DISPPARAMS is not a valid variant type.
DISP_E_EXCEPTION | The application needs to raise an exception. In this case, the structure passed in pexcepinfo should be filled in.
DISP_E_MEMBERNOTFOUND | The requested member does not exist.
DISP_E_NONAMEDARGS | This implementation of IDispatch does not support named arguments.
DISP_E_OVERFLOW | One of the arguments in DISPPARAMS could not be coerced to the specified type.
DISP_E_PARAMNOTFOUND | One of the parameter IDs does not correspond to a parameter on the method. In this case, puArgErr is set to the first argument that contains the error.
DISP_E_PARAMNOTOPTIONAL | A required parameter was omitted.
DISP_E_TYPEMISMATCH | One or more of the arguments could not be coerced. The index of the first parameter with the incorrect type within rgvarg is returned in puArgErr.
E_INVALIDARG | One of the arguments is invalid.
E_OUTOFMEMORY | Insufficient memory to complete the operation.
Other return codes | Any of the ITypeInfo::Invoke errors can also be returned.

Remarks

The parameter this is a pointer to an implementation of the interface that is being deferred to. DispInvoke builds a stack frame, coerces parameters using standard coercion rules, pushes them on the stack, and then calls the correct member function in the VTBL.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

The following code from the Lines sample file Lines.cpp implements IDispatch::Invoke using DispInvoke. This function uses m_bRaiseException to signal that an error occurred during the DispInvoke call.

STDMETHODIMP
CLines::Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD wFlags,
    DISPPARAMS FAR* pdispparams,
    VARIANT FAR* pvarResult,
    EXCEPINFO FAR* pexcepinfo,
    UINT FAR* puArgErr)
{
    return DispInvoke(
    this, m_ptinfo,
    dispidMember, wFlags, pdispparams,
    pvarResult, pexcepinfo, puArgErr);
}


DllMain

This function is an optional method of entry into a dynamic-link library (DLL). If the function is used, it is called by the system when processes and threads are initialized and terminated, or upon calls to the LoadLibrary and FreeLibrary functions.

DllMain is a placeholder for the library-defined function name. You must specify the actual name you use when you build your DLL. For more information, see the documentation included with your development tools.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI DllMain(HANDLE hinstDLL, DWORD dwReason, LPVOID lpvReserved);

Parameters

hinstDLL
Handle to the DLL. The value is the base address of the DLL. The HINSTANCE of a DLL is the same as the HMODULE of the DLL, so hinstDLL can be used in subsequent calls to the GetModuleFileName function and other functions that require a module handle.
dwReason
Specifies a flag indicating why the DLL entry-point function is being called. This parameter can be one of the following values:
Value
Description
DLL_PROCESS_ATTACH | Indicates that the DLL is being loaded into the virtual address space of the current process as a result of the process starting up or as a result of a call to LoadLibrary. DLLs can use this opportunity to initialize any instance data or to use the TlsAlloc function to allocate a thread local storage (TLS) index.
DLL_THREAD_ATTACH | Indicates that the current process is creating a new thread. When this occurs, the system calls the entry-point function of all DLLs currently attached to the process. The call is made in the context of the new thread. DLLs can use this opportunity to initialize a TLS slot for the thread. A thread calling the DLL entry-point function with DLL_PROCESS_ATTACH does not call the DLL entry-point function with DLL_THREAD_ATTACH.
Note that the entry-point of a DLL function is called with this value only by threads created after the DLL is loaded by the process. When a DLL is loaded using LoadLibrary, existing threads do not call the entry-point function of the newly loaded DLL.
DLL_THREAD_DETACH | Indicates that a thread is exiting cleanly. If the DLL has stored a pointer to allocated memory in a TLS slot, it uses this opportunity to free the memory. The system calls the entry-point function of all currently loaded DLLs with this value. The call is made in the context of the exiting thread.
DLL_PROCESS_DETACH | Indicates that the DLL is being unloaded from the virtual address space of the calling process as a result of either a process exit or a call to FreeLibrary. The DLL can use this opportunity to call the TlsFree function to free any TLS indices allocated by using TlsAlloc and to free any thread local data.

lpvReserved
Specifies further aspects of DLL initialization and cleanup.

If dwReason is DLL_PROCESS_ATTACH, lpvReserved is NULL for dynamic loads and non-NULL for static loads.

If dwReason is DLL_PROCESS_DETACH, lpvReserved is NULL if DllMain has been called by using FreeLibrary and non-NULL if DllMain has been called during process termination.

Return Values

When the system calls the DllMain function with the DLL_PROCESS_ATTACH value, the function returns TRUE if it succeeds or FALSE if initialization fails. If the return value is FALSE when DllMain is called because the process uses the LoadLibrary function, LoadLibrary returns NULL. If the return value is FALSE when DllMain is called during process initialization, the process terminates with an error. To get extended error information, call GetLastError.

When the system calls the DllMain function with any value other than DLL_PROCESS_ATTACH, the return value is ignored.

Remarks

During initial process startup or after a call to LoadLibrary, the system scans the list of loaded DLLs for the process. For each DLL that has not already been called with the DLL_PROCESS_ATTACH value, the system calls the entry-point function of the DLL. This call is made in the context of the thread that caused the process address space to change, such as the primary thread of the process or the thread that called LoadLibrary.

There are cases in which the entry-point function is called for a terminating thread even if the DLL never attached to the thread — for example, the entry-point function was never called with the DLL_THREAD_ATTACH value in the context of the thread in either of these two situations:

  • The thread was the initial thread in the process, so the system called the entry-point function with the DLL_PROCESS_ATTACH value.
  • The thread was already running when a call to the LoadLibrary function was made, so the system never called the entry-point function for it.

When a DLL is unloaded from a process as a result of process termination or as a result of a call to FreeLibrary, the system does not call the entry-point function of the DLL with the DLL_THREAD_DETACH value for the individual threads of the process. The DLL is only given DLL_PROCESS_DETACH notification. DLLs can take this opportunity to clean up all resources for all threads known to the DLL.

On attach, the body of your DLL entry-point function should perform only simple initialization tasks, such as setting up thread local storage (TLS), creating synchronization objects, and opening files. You must not call LoadLibrary in the entry-point function, because you may create dependency loops in the DLL load order. This can result in a DLL being used before the system has executed its initialization code. Similarly, you must not call the FreeLibrary function in the entry-point function on detach, because this can result in a DLL being used after the system has executed its termination code.

Calling Win32 functions other than TLS, object-creation, and file functions may result in problems that are difficult to diagnose. For example, calling User, Shell, COM, and Windows Sockets functions (or any functions that call these functions) can cause access violation errors, because their DLLs call LoadLibrary to load other system components. While it is acceptable to create synchronization objects in DllMain, you should not perform synchronization in DllMain (or a function called by DllMain) because all calls to DllMain are serialized. Waiting on synchronization objects in DllMain can cause a deadlock.

To provide more complex initialization, create an initialization routine for the DLL. You can require applications to call the initialization routine before calling any other routines in the DLL. Otherwise, you can have the initialization routine create a named mutex, and have each routine in the DLL call the initialization routine if the mutex does not exist.


EnterCriticalSection

This function waits for ownership of the specified critical section object. The function returns when the calling thread is granted ownership.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void EnterCriticalSection( LPCRITICAL_SECTION lpCriticalSection );

Parameters

lpCriticalSection
[in] Pointer to the critical section object.

Return Values

None.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection to initialize the object.

To enable mutually exclusive access to a shared resource, each thread calls the EnterCriticalSection function to request ownership of the critical section before executing any section of code that accesses the protected resource. EnterCriticalSection blocks until the thread can take ownership of the critical section. When it has finished executing the protected code, the thread uses the LeaveCriticalSection function to relinquish ownership, enabling another thread to become owner and access the protected resource. The thread must call LeaveCriticalSection once for each time that it entered the critical section. The thread enters the critical section each time EnterCriticalSection succeeds.

After a thread has ownership of a critical section, it can make additional calls to EnterCriticalSection without blocking its execution. This prevents a thread from deadlocking itself while waiting for a critical section that it already owns.

Any thread of the process can use the DeleteCriticalSection function to release the system resources that were allocated when the critical section object was initialized. After this function has been called, the critical section object can no longer be used for synchronization.

If a thread terminates while it has ownership of a critical section, the state of the critical section is undefined.

If a critical section is deleted while it is still owned, the state of the threads waiting for ownership of the deleted critical section is undefined.

See Also

DeleteCriticalSection, InitializeCriticalSection, LeaveCriticalSection


EnumCalendarInfo

This function enumerates the calendar information by calling an application-defined callback function. It passes the callback function a pointer to a string buffer that contains the requested calendar information. This continues until either the last applicable calendar is found or the callback function returns FALSE.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnumCalendarInfo(CALINFO_ENUMPROC lpCalInfoEnumProc, LCID Locale, CALID Calendar, CALTYPE CalType);

Parameters

lpCalInfoEnumProc
[in] Pointer to an application-defined callback function. For more information, see the EnumCalendarInfoProc callback function.
Locale
[in] Specifies the locale to retrieve calendar information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

Calendar
[in] Specifies the calendar for which information is requested. The following values are defined:
Value
Description
ENUM_ALL_CALENDARS | Enumerate all applicable calendars for the locale specified by Locale.
CAL_GREGORIAN | Gregorian (localized)
CAL_GREGORIAN_US | Gregorian (English strings always)
CAL_JAPAN | Japanese Emperor Era
CAL_TAIWAN | Taiwan Region Era
CAL_KOREA | Korean Tangun Era
CAL_HIJRI | Hijri (Arabic Lunar)
CAL_THAI | Thai
CAL_HEBREW | Hebrew
CAL_GREGORIAN_ME_FRENCH | Gregorian Middle East French
CAL_GREGORIAN_ARABIC | Gregorian Arabic
CAL_GREGORIAN_XLIT_ENGLISH | Gregorian transliterated English
CAL_GREGORIAN_XLIT_FRENCH | Gregorian transliterated French

CalType
[in] Indicates the type of calendar information to be returned. See the listing of constant values in the “Remarks” section.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_BADDB
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The CALTYPE constants define particular pieces of calendar information. The following table shows CALTYPE constants that are mutually exclusive—that is, they cannot be used in combination with each other in a function call.

Type
Description
CAL_ICALINTVALUE | An integer value indicating the calendar type of the alternate calendar.
CAL_IYEAROFFSETRANGE | One or more null-terminated strings that specify the year offsets for each of the era ranges. The last string has an extra terminating null character.
CAL_SABBREVDAYNAME1 | Abbreviated native name of the first day of the week.
CAL_SABBREVDAYNAME2 | Abbreviated native name of the second day of the week.
CAL_SABBREVDAYNAME3 | Abbreviated native name of the third day of the week.
CAL_SABBREVDAYNAME4 | Abbreviated native name of the fourth day of the week.
CAL_SABBREVDAYNAME5 | Abbreviated native name of the fifth day of the week.
CAL_SABBREVDAYNAME6 | Abbreviated native name of the sixth day of the week.
CAL_SABBREVDAYNAME7 | Abbreviated native name of the seventh day of the week.
CAL_SABBREVMONTHNAME1 | Abbreviated native name of the first month of the year.
CAL_SABBREVMONTHNAME2 | Abbreviated native name of the second month of the year.
CAL_SABBREVMONTHNAME3 | Abbreviated native name of the third month of the year.
CAL_SABBREVMONTHNAME4 | Abbreviated native name of the fourth month of the year.
CAL_SABBREVMONTHNAME5 | Abbreviated native name of the fifth month of the year.
CAL_SABBREVMONTHNAME6 | Abbreviated native name of the sixth month of the year.
CAL_SABBREVMONTHNAME7 | Abbreviated native name of the seventh month of the year.
CAL_SABBREVMONTHNAME8 | Abbreviated native name of the eighth month of the year.
CAL_SABBREVMONTHNAME9 | Abbreviated native name of the ninth month of the year.
CAL_SABBREVMONTHNAME10 | Abbreviated native name of the tenth month of the year.
CAL_SABBREVMONTHNAME11 | Abbreviated native name of the eleventh month of the year.
CAL_SABBREVMONTHNAME12 | Abbreviated native name of the twelfth month of the year.
CAL_SABBREVMONTHNAME13 | Abbreviated native name of the thirteenth month of the year, if it exists.
CAL_SCALNAME | Native name of the alternate calendar.
CAL_SDAYNAME1 | Native name of the first day of the week.
CAL_SDAYNAME2 | Native name of the second day of the week.
CAL_SDAYNAME3 | Native name of the third day of the week.
CAL_SDAYNAME4 | Native name of the fourth day of the week.
CAL_SDAYNAME5 | Native name of the fifth day of the week.
CAL_SDAYNAME6 | Native name of the sixth day of the week.
CAL_SDAYNAME7 | Native name of the seventh day of the week.
CAL_SERASTRING | One or more null-terminated strings that specify each of the Unicode codepoints specifying the era associated with the given CAL_IYEAROFFSETRANGE. The last string has an extra terminating null character. See example below.
CAL_SLONGDATE | Long date formats for this calendar type.
CAL_SMONTHNAME1 | Native name of the first month of the year.
CAL_SMONTHNAME2 | Native name of the second month of the year.
CAL_SMONTHNAME3 | Native name of the fifth month of the year.
CAL_SMONTHNAME4 | Native name of the fourth month of the year.
CAL_SMONTHNAME5 | Native name of the fifth month of the year.
CAL_SMONTHNAME6 | Native name of the sixth month of the year.
CAL_SMONTHNAME7 | Native name of the seventh month of the year.
CAL_SMONTHNAME8 | Native name of the eighth month of the year.
CAL_SMONTHNAME9 | Native name of the ninth month of the year.
CAL_SMONTHNAME10 | Native name of the tenth month of the year.
CAL_SMONTHNAME11 | Native name of the eleventh month of the year.
CAL_SMONTHNAME12 | Native name of the twelfth month of the year.
CAL_SMONTHNAME13 | Native name of the thirteenth month of the year, if it exists.
CAL_SSHORTDATE | Short date formats for this calendar type.

If the native name for the day of the week or for a month is an empty string, that name is identical to the name given in the corresponding locale information and therefore is not duplicated here.

The CAL_IYEAROFFSETRANGE and CAL_SERASTRING values vary in format depending on the type of optional calendar. The following example shows the values for these types (for each supported alternate calendar type) along with the formula for how to use the CAL_IYEAROFFSETRANGE value to compute the correct year given the Gregorian current year value Y:

CAL_ICALINTVALUE = "1"
CAL_IYEAROFFSETRANGE = ""
CAL_SERASTRING = ""

CAL_ICALINTVALUE = "2"
CAL_IYEAROFFSETRANGE = ""
CAL_SERASTRING = ""

CAL_ICALINTVALUE = "3"
CAL_IYEAROFFSETRANGE = "1989\01926\01912\01868\0"
CAL_SERASTRING = "Ux337B\0Ux337C\0Ux337D\0Ux337E\0"
if (Y>=1989) { Y = (Y–1989)+1; }
if (Y>=1926 && Y<1989) { Y = (Y–1926)+1; }
if (Y>=1912 && Y<1926) { Y = (Y–1912)+1; }
if (Y>=1868 && Y<1912) { Y = (Y–1868)+1; }
if (Y<1868) { Y = Y; }

CAL_ICALINTVALUE = "4"
CAL_IYEAROFFSETRANGE = "1912\0"
CAL_SERASTRING = "Ux4E2D\0Ux83EF\0Ux6C11\0Ux570B\0"
if (Y>=1912) { Y = (Y–1912)+1; }
if (Y<1912) { Y = Y; }

CAL_ICALINTVALUE = "5"
CAL_IYEAROFFSETRANGE = "2333\0"
CAL_SERASTRING = ""
Y = Y+2333;

See Also

EnumDateFormats, EnumCalendarInfoProc


EnumCalendarInfoProc

This function is an application-defined callback function. It is called as a result of a call to the EnumCalendarInfo function, and receives a pointer to a string buffer that contains a calendar information string.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK EnumCalendarInfoProc(
LPWSTR lpCalendarInfoString);

Parameters

lpCalendarInfoString
[out] Pointer to a string buffer that contains a null-terminated calendar information string. This string is formatted according to the CALTYPE value passed to EnumCalendarInfo.

Return Values

TRUE continues enumeration. FALSE stops enumeration.

Remarks

Windows CE supports only the Unicode version of this function.

An EnumCalendarInfoProc function can carry out any desired task.

An application registers an EnumCalendarInfoProc function by passing its address to the EnumCalendarInfo function.

See Also

EnumCalendarInfo


EnumCodePagesProc

This application-defined callback function is used with the EnumSystemCodePages function. It receives a pointer to a string buffer that contains a code page identifier. The CODEPAGE_ENUMPROC type defines a pointer to this callback function. EnumCodePagesProc is a placeholder for the application-defined function name.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK EnumCodePagesProc( LPTSTR lpCodePageString );

Parameters

lpCodePageString
[in] Pointer to a string buffer that contains a code page identifier string with a terminating null character.

Return Values

To continue enumeration, the callback function should return TRUE. To stop enumeration, the callback function should return FALSE.

Remarks

An EnumCodePagesProc function can carry out any desired task.

An application registers an EnumCodePagesProc function by passing its address to the EnumSystemCodePages function.


EnumDateFormats

This function enumerates the long or short date formats that are available for a specified locale, including date formats for any alternate calendars.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnumDateFormats(DATEFMT_ENUMPROC lpDateFmtEnumProc, LCID Locale, DWORD dwFlags);

Parameters

lpDateFmtEnumProc
[in] Pointer to an application-defined callback function. The EnumDateFormats function enumerates date formats by making repeated calls to this callback function. For more information, see the EnumDateFormatsProc callback function.
Locale
[in] Specifies the locale to retrieve date format information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

dwFlags
[in] Specifies the date formats that are of interest. Use one of the following values:
Value
Description
DATE_SHORTDATE | Return short date formats.
DATE_LONGDATE | Return long date formats.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

The DATE_SHORTDATE and DATE_LONGDATE flags are mutually exclusive. Use one or the other, but not both.

For Windows CE versions 2.10 and later, default DATE_SHORTDATE formats for non-U.S. English locales that include the four-digit year are added. The following table shows the formats.

Locale
Date Format
United Kingdom | dd/MM/yyyy
Canada | dd/MM/yyyy
New Zealand | dd/MM/yyyy
Ireland | dd/MM/yyyy
South Africa | dd/MM/yyyy
Caribbean | MM/dd/yyyy
Belize | dd/MM/yyyy
Trinidad | dd/MM/yyyy

See Also

EnumCalendarInfo, EnumDateFormatsProc, EnumTimeFormats


EnumDateFormatsProc

This function is an application-defined callback function. It is called as a result of a call to the EnumDateFormats function, and receives a pointer to a string buffer that contains a date format string.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK EnumDateFormatsProc(LPWSTR lpDateFormatString);

Parameters

lpDateFormatString
[out] Pointer to a string buffer that contains a null-terminated date format string. This string is a long or short date format, depending on the value of the dwFlags parameter passed to EnumDateFormats.

Return Values

TRUE continues enumeration. FALSE stops enumeration.

Remarks

Windows CE supports only the Unicode version of this function.

An EnumDateFormatsProc function can carry out any desired task.

An application registers an EnumDateFormatsProc function by passing its address to the EnumDateFormats function.

See Also

EnumDateFormats


EnumFontFamProc

This function is an application-defined callback function that retrieves data describing available fonts.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int CALLBACK EnumFontFamProc(ENUMLOGFONT FAR *lpelf, TEXTMETRIC FAR *lpntm, int FontType, LPARAM lParam);

Parameters

lpelf
[out] Pointer to an ENUMLOGFONT structure that contains information about the logical attributes of the font. This structure is locally defined.
lpntm
[out] Pointer to a NEWTEXTMETRIC structure that contains information about the physical attributes of the font, if the font is a TrueType font. If the font is not a TrueType font, this parameter points to a TEXTMETRIC structure.
FontType
[in] Specifies the type of the font. This parameter can be a combination of the following values:
DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lParam
[in] Pointer to the application-defined data passed by the EnumFontFamilies function.

Return Values

Nonzero continues enumeration. Zero stops enumeration.

Remarks

An application must register this callback function by passing its address to the EnumFontFamilies function.

The AND (&) operator can be used with the RASTER_FONTTYPE, DEVICE_FONTTYPE, and TRUETYPE_FONTTYPE constants to determine the font type. If the RASTER_FONTTYPE bit is set, the font is a raster font. If the TRUETYPE_FONTTYPE bit is set, the font is a TrueType font. If neither bit is set, the font is a vector font. DEVICE_FONTTYPE is set when a device (for example, a laser printer) supports downloading TrueType fonts or when the font is a device-resident font; it is zero if the device is a display adapter, dot-matrix printer, or other raster device. An application can also use DEVICE_FONTTYPE to distinguish graphics device interface (GDI)-supplied raster fonts from device-supplied fonts. GDI can simulate bold, italic, underline, and strikeout attributes for GDI-supplied raster fonts, but not for device-supplied fonts.

The physical attributes of the font are always contained in a TEXTMETRIC structure.

Windows CE versions 1.0 and 1.01 does not support TrueType fonts. In version 1.0, the value of the FontType parameter will always be RASTER_FONTTYPE.

In Windows CE versions 2.0 and later, FontType can have a value of either RASTER_FONTTYPE or TRUETYPE_FONTTYPE depending on the Windows CE platform. Any Windows CE platform will support only raster fonts or TrueType fonts but not both. The font type (raster or TrueType) is chosen at system design time, and cannot be changed by an application.

See Also

EnumFontFamilies, EnumFonts, ENUMLOGFONT, TEXTMETRIC


EnumFontsProc

This function is an application-defined callback function that processes font data from the EnumFonts function.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

int CALLBACK EnumFontsProc(lplf lplf, lptm lptm, DWORD dwType, LPARAM lpData);

Parameters

lplf
[out] Pointer to a LOGFONT structure that contains information about the logical attributes of the font.
lptm
[out] Pointer to a TEXTMETRIC structure that contains information about the physical attributes of the font.
dwType
[in] Specifies the type of the font. This parameter can be a combination of the following values:
DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lpData
[in] Long pointer to the application-defined data passed by EnumFonts.

Return Values

Nonzero continues enumeration. Zero stops enumeration.

Remarks

The AND (&) operator can be used with the RASTER_FONTTYPE and DEVICE_FONTTYPE constants to determine the font type. The RASTER_FONTTYPE bit of the FontType parameter specifies whether the font is a raster or vector font. If the bit is one, the font is a raster font; if zero, it is a vector font. The DEVICE_FONTTYPE bit of FontType specifies whether the font is a device-based or graphics device interface (GDI)-based font. If the bit is one, the font is a device-based font; if zero, it is a GDI-based font.

If the device is capable of text transformations (scaling, italicizing, and so on) only the base font is enumerated. The user must inquire into the device’s text-transformation abilities to determine which additional fonts are available directly from the device.

An application must register the EnumFontsProc function by passing its address to the EnumFonts function.

Windows CE versions 1.0 and 1.01 does not support TrueType fonts. In version 1.0, the value of the FontType parameter must be RASTER_FONTTYPE.

Windows CE versions 2.0 and later support both TrueType and raster fonts. In version 2.0, FontType can have a value of either RASTER_FONTTYPE or TRUETYPE_FONTTYPE depending on the Windows CE platform. Any given Windows CE platform will support only raster fonts or TrueType fonts but not both.

See Also

EnumFonts, LOGFONT, TEXTMETRIC


EnumLocalesProc

This function is an application-defined callback function. It is called as a result of a call to the EnumSystemLocales function, and receives a pointer to a string buffer that contains a locale identifier.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK EnumLocalesProc(LPWSTR lpLocaleString);

Parameters

lpLocaleString
[out] Pointer to a string buffer that contains a null-terminated locale identifier string.

Return Values

TRUE continues enumeration. FALSE stops enumeration.

Remarks

Windows CE supports only the Unicode version of this function.

An application registers an EnumLocalesProc function by passing its address to the EnumSystemLocales function.

See Also

EnumSystemLocales


EnumSystemCodePages

This function enumerates the code pages that are either installed on or supported by a system.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnumSystemCodePages(
CODEPAGE_ENUMPROC lpCodePageEnumProc, DWORD dwFlags);

Parameters

lpCodePageEnumProc
[in] Pointer to an application-defined callback function. The EnumSystemCodePages function enumerates code pages by making repeated calls to this callback function. For more information, see the EnumCodePagesProc callback function.
dwFlags
[in] Specifies the code pages to enumerate. This parameter can be one of the following values:
Value
Description
CP_INSTALLED | Enumerate only installed code pages.
CP_SUPPORTED | Enumerate all supported code pages.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

The CP_INSTALLED and CP_SUPPORTED flags are mutually exclusive.


EnumSystemLocales

This function enumerates the locales that are either installed on or supported by a system.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnumSystemLocales(LOCALE_ENUMPROC lpLocaleEnumProc, DWORD dwFlags);

Parameters

lpLocaleEnumProc
[in] Pointer to an application-defined callback function. The EnumSystemLocales function enumerates locales by making repeated calls to this callback function. For more information, see the EnumLocalesProc callback function.
dwFlags
[in] Specifies the locale identifiers to enumerate. This parameter can be one of the following values:
Value
Description
LCID_INSTALLED | Enumerate only installed locale identifiers.
LCID_SUPPORTED | Enumerate all supported locale identifiers.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

Remarks

The LCID_INSTALLED and LCID_SUPPORTED flags are mutually exclusive.


EnumTimeFormats

This function enumerates the time formats that are available for a specified locale.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EnumTimeFormats(TIMEFMT_ENUMPROC lpTimeFmtEnumProc, LCID Locale, DWORD dwFlags);

Parameters

lpTimeFmtEnumProc
[in] Pointer to an application-defined callback function. See the EnumTimeFormatsProc callback function for further details.
Locale
[in] Specifies the locale to retrieve time format information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

dwFlags
[in] Currently unused; set to zero.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_PARAMETER
  • ERROR_BADDB
  • ERROR_INVALID FLAGS

See Also

EnumCalendarInfo, EnumDateFormats, EnumTimeFormatsProc


EnumTimeFormatsProc

This function is an application-defined callback function. It is called as a result of a call to the EnumTimeFormats function, and receives a pointer to a string buffer that contains a time format string.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK EnumTimeFormatsProc(LPWSTR lpTimeFormatString);

Parameters

lpTimeFormatString
[out] Pointer to a string buffer that contains a null-terminated time format string.

Return Values

TRUE continues enumeration. FALSE stops enumeration.

Remarks

Windows CE supports only the Unicode version of this function.

An application registers an EnumTimeFormatsProc function by passing its address to the EnumTimeFormats function.

See Also

EnumTimeFormats


EnumWindowsProc

This function is an application-defined callback function that receives top-level window handles as a result of a call to the EnumWindows function.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK EnumWindowsProc(HWND hwnd, LPARAM lParam);

Parameters

hwnd
[out] Handle to a top-level window.
lParam
[in] Specifies the application-defined value given in EnumWindows or EnumDesktopWindows.

Return Values

TRUE continues enumeration. FALSE stops enumeration.

Remarks

An application must register this callback function by passing its address to EnumWindows or EnumDesktopWindows.

See Also

EnumWindows


EqualRect

This function determines whether the two specified rectangles are equal by comparing the coordinates of their upper-left and lower-right corners.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL EqualRect(const RECT *lprc1, const RECT *lprc2);

Parameters

lprc1
Long pointer to a RECT structure that contains the logical coordinates of the first rectangle.
lprc2
Long pointer to a RECT structure that contains the logical coordinates of the second rectangle.

Return Values

Nonzero indicates that the two rectangles are identical. Zero indicates that the two rectangles are not identical.

Windows NT: To get extended error information, call GetLastError.

See Also

IsRectEmpty, PtInRect, RECT


ExitThread

This function ends a thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

VOID ExitThread( DWORD dwExitCode );

Parameters

dwExitCode
[in] Specifies the exit code for the calling thread. Use the GetExitCodeThread function to retrieve a thread’s exit code.

Return Values

None.

Remarks

ExitThread is the preferred method of exiting a thread. When this function is called (either explicitly or by returning from a thread procedure), the current thread’s stack is deallocated and the thread terminates. The entry-point function of all attached dynamic-link libraries (DLLs) is invoked with a value indicating that the thread is detaching from the DLL.

If the thread is the last thread in the process when this function is called, the thread’s process is also terminated.

If the primary thread calls the ExitThread function, the application exits.

The state of the thread object becomes signaled, releasing any other threads that had been waiting for the thread to terminate. The thread’s termination status changes from STILL_ACTIVE to the value of the dwExitCode parameter.

Terminating a thread does not necessarily remove the thread object from the operating system. A thread object is deleted when the last handle to the thread is closed.

The ExitThread and CreateThread functions, as well as a process that is starting as the result of a CreateProcess call, are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

  • During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.
  • Only one thread in a process can be in a DLL initialization or detach routine at a time.

See Also

CreateProcess, CreateThread, GetExitCodeThread


ExtensionPropSheetPageProc

This function is an application-defined callback function that receives the address of the AddPropSheetPageProc function, which resides in the module that creates a property sheet. A property sheet extension must export the ExtensionPropSheetPageProc function.

At a Glance

Windows CE versions: 1.0 and later

Syntax

BOOL CALLBACK ExtensionPropSheetPageProc(LPVOID lpv, LPFNADDPROPSHEETPAGE lpfnAddPropSheetPageProc,
LPARAM lParam);

Parameters

lpv
[in] Long void pointer to an application-defined value that describes an item for which a property sheet page is to be created This parameter can be NULL
lpfnAddPropSheetPageProc
[out] Long pointer to the AddPropSheetPageProc function. The extension dynamic-link library (DLL) calls this function to add a page to the property sheet.
lparam
[in] Application-defined 32-bit value.

Return Values

Nonzero indicates success. Zero indicates failure.

See Also

AddPropSheetPageProc


FileTimeToLocalFileTime

This function converts a file time based on the Coordinated Universal Time (UTC) to a local file time.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL FileTimeToLocalFileTime( const FILETIME *lpFileTime,
LPFILETIME lpLocalFileTime );

Parameters

lpFileTime
[in] Pointer to a FILETIME structure containing the UTC-based file time to be converted into a local file time.
lpLocalFileTime
[out] Pointer to a FILETIME structure to receive the converted local file time. This parameter cannot be the same as the lpFileTime parameter.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

FileTimeToLocalFileTime uses the current settings for the time zone and daylight saving time. Therefore, if it is daylight saving time, this function will take daylight saving time into account, even if the time you are converting is in standard time.

See Also

FILETIME, LocalFileTimeToFileTime


FileTimeToSystemTime

This function converts a 64-bit file time to system time format.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL FileTimeToSystemTime( const FILETIME *lpFileTime,
LPSYSTEMTIME lpSystemTime );

Parameters

lpFileTime
[in] Pointer to a FILETIME structure containing the file time to convert to system date and time format.

The FileTimeToSystemTime function only works with FILETIME values that are less than 0x8000000000000000. The function fails with values equal to or greater than that.

lpSystemTime
[out] Pointer to a SYSTEMTIME structure to receive the converted file time.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

As noted above, the function fails for FILETIME values that are equal to or greater than 0x8000000000000000.

See Also

FILETIME, SYSTEMTIME, SystemTimeToFileTime


FindClose

This function closes the specified search handle. The FindFirstFile and FindNextFile functions use the search handle to locate files with names that match a specified name.

A remote application interface (RAPI) version of this function exists, and it is named CeFindClose.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL FindClose( HANDLE hFindFile );

Parameters

hFindFile
[in] Search handle. This handle must have been previously opened by the FindFirstFile function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

After the FindClose function is called, the handle specified by the hFindFile parameter cannot be used in subsequent calls to either the FindNextFile or FindClose function.

See Also

FindFirstFile, FindNextFile


FindFirstFile

This function searches a directory for a file whose name matches the specified file name. FindFirstFile examines subdirectory names as well as file names.

A remote application interface (RAPI) version of this function exists and it is named CeFindFirstFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE FindFirstFile(LPCTSTR lpFileName,
LPWIN32_FIND_DATA lpFindFileData);

Parameters

lpFileName
[in] Pointer to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the FindFirstFile function parses paths.

lpFindFileData
[out] Pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory.

Return Values

A search handle, used in a subsequent call to FindNextFile or FindClose, indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

The FindFirstFile function opens a search handle and returns information about the first file whose name matches the specified pattern. Once the search handle is established, you can use the FindNextFile function to search for other files that match the same pattern. When the search handle is no longer needed, close it by using the FindClose function.

This function searches for files by name only; it cannot be used for attribute-based searches.

See Also

FindClose, FindNextFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA


FindNextFile

This function continues a file search from a previous call to the FindFirstFile function.

A remote application interface (RAPI) version of this function exists and it is named CeFindNextFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL FindNextFile( HANDLE hFindFile,
LPWIN32_FIND_DATA lpFindFileData );

Parameters

hFindFile
[in] Search handle returned by a previous call to the FindFirstFile function.
lpFindFileData
[out] Pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to FindNextFile to refer to the found file or directory.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Remarks

The FindNextFile function searches for files by name only; it cannot be used for attribute-based searches.

See Also

FindClose, FindFirstFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA


FindResource

This function determines the location of a resource with the specified type and name in the specified module.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HRSRC FindResource( HMODULE hModule, LPCWSTR lpName,
LPCWSTR lpType);

Parameters

hModule
Handle to the module whose executable file contains the resource. In Windows CE, this can not be set to NULL.
lpName
Pointer to the name of the resource. For more information, see the Remarks section.
lpType
Pointer to the resource type. For more information, see the Remarks section. For standard resource types, this parameter can be one of the following values:
Value
Description
RT_ACCELERATOR | Accelerator table
RT_BITMAP | Bitmap resource
RT_CURSOR | Hardware-dependent cursor resource
RT_DIALOG | Dialog box
RT_FONT | Font resource
RT_FONTDIR | Font directory resource
RT_GROUP_CURSOR | Hardware-independent cursor resource
RT_GROUP_ICON | Hardware-independent icon resource
RT_HTML | HTML document
RT_ICON | Hardware-dependent icon resource
RT_MENU | Menu resource
RT_MESSAGETABLE | Message-table entry
RT_RCDATA | Application-defined resource (raw data)
RT_STRING | String-table entry
RT_VERSION | Version resource

Return Values

A handle to the specified resource’s info block indicates success. To obtain a handle to the resource, pass this handle to the LoadResource function. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If the high-order word of the lpName or lpType parameter is zero, the low-order word specifies the integer identifier of the name or type of the given resource. Otherwise, those parameters are long pointers to null-terminated strings. If the first character of the string is a pound sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource’s name or type. For example, the string “#258” represents the integer identifier 258.

The lpName parameter does not support the resource ID zero—that is, FindResource(h, 0 ,t) will not work as expected.

An application should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

When you are finished using an accelerator table, bitmap, cursor, icon, or menu, you can release its associated memory by calling one of the functions in the following table.

Resource
Release function
Accelerator table | DestroyAcceleratorTable
Bitmap | DeleteObject
Cursor | DestroyCursor
Icon | DestroyIcon
Menu | DestroyMenu

The system automatically deletes these resources when the process that created them terminates, however, calling the appropriate function saves memory and decreases the size of the process's working set.

An application can use FindResource to find any type of resource, but this function should be used only if the application must access the binary resource data when making subsequent calls to LoadLibrary.

To use a resource immediately, an application should use one of the following resource-specific functions to find and load the resources in one call:

Function
Description
FormatMessage | Loads and formats a message-table entry.
LoadAccelerators | Loads an accelerator table.
LoadBitmap | Loads a bitmap resource.
LoadCursor | Loads a cursor resource.
LoadIcon | Loads an icon resource.
LoadMenu | Loads a menu resource.
LoadString | Loads a string-table entry.

For example, an application can use the LoadIcon function to load an icon for display on the screen. However, the application should use FindResource and LoadResource if it is loading the icon to copy its data to another application.

String resources are stored in sections of up to 16 strings per section. The strings in each section are stored as a sequence of counted (not null-terminated) Unicode strings. The LoadString function will extract the string resource from its corresponding section.

See Also

LoadAccelerators, LoadBitmap, LoadIcon, LoadMenu, LoadResource, LoadString


FlushFileBuffers

This function clears the buffers for the specified file and causes all buffered data to be written to the file.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WINAPI FlushFileBuffers (HANDLE hFile);

Parameters

hFile
[in] Handle to an open file. The function flushes this file’s buffers. The file handle must have GENERIC_WRITE access to the file.

If hFile is a handle to a communications device, the function only flushes the transmit buffer.

If hFile is a handle to the server end of a named pipe, the function does not return until the client has read all buffered data from the pipe.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The WriteFile function typically writes data to an internal buffer that the operating system writes to disk on a regular basis. The FlushFileBuffers function writes all of the buffered information for the specified file to disk.


FlushInstructionCache

This function flushes the instruction cache for the specified process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL FlushInstructionCache( HANDLE hProcess,
LPCVOID lpBaseAddress, DWORD dwSize );

Parameters

hProcess
Handle to the process that has an instruction cache to flush.
lpBaseAddress
Unsupported; set to NULL.
dwSize
Unsupported; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.


FlushViewOfFile

This function writes to the disk a byte range within a mapped view of a file.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL FlushViewOfFile( LPCVOID lpBaseAddress,
DWORD dwNumberOfBytesToFlush );

Parameters

lpBaseAddress
Pointer to the base address of the byte range to be flushed to the disk representation of the mapped file.
dwNumberOfBytesToFlush
Specifies the number of bytes to flush. This parameter cannot be set to zero.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Flushing a range of a mapped view causes any dirty pages within that range to be written to the disk. Dirty pages are those whose contents have changed since the file view was mapped.

When flushing a memory-mapped file over a network, FlushViewOfFile guarantees that the data has been written from the local computer, but not that the data resides on the remote computer. The server can cache the data on the remote side. Therefore, FlushViewOfFile can return before the data has been physically written to disk. However, you can cause FlushViewOfFile to return only when the physical write is complete by specifying the FILE_FLAG_WRITE_THROUGH flag when you open the file with the CreateFile function.

See Also

CreateFile, MapViewOfFile, UnmapViewOfFile


FoldString

This function maps one string to another, performing a specified transformation option.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int FoldString(DWORD dwMapFlags, LPCTSTR lpSrcStr, int cchSrc, LPTSTR lpDestStr, int cchDest);

Parameters

dwMapFlags
[in] Specifies the type of transformation to be used during mapping. This value can be a combination of the following bit-flag constants:
Value
Description
MAP_FOLDCZONE | Fold compatibility zone characters into standard Unicode equivalents. For information about compatibility zone characters, see the following Remarks section.
MAP_FOLDDIGITS | Map all digits to Unicode characters 0 through 9.
MAP_PRECOMPOSED | Map accented characters to precomposed characters, in which the accent and base character are combined into a single character value. This value cannot be combined with MAP_COMPOSITE.
MAP_COMPOSITE | Map accented characters to composite characters, in which the accent and base character are represented by two character values. This value cannot be combined with MAP_PRECOMPOSED.
MAP_EXPAND_LIGATURES | Not supported.

lpSrcStr
[in] Pointer to the string to be mapped.
cchSrc
[in] Specifies the size, in characters, of the lpSrcStr buffer. If cchSrc is –1, lpSrcStr is assumed to be null-terminated, and the length is calculated automatically.
lpDestStr
[out] Pointer to the buffer to store the mapped string.
cchDest
[in] Specifies the size, in characters, of the lpDestStr buffer. If cchDest is zero, the function returns the number of bytes or characters required to hold the mapped string, and the buffer pointed to by lpDestStr is not used.

Return Values

The number of bytes (ANSI version) or characters (Unicode version) written to the destination buffer, or, if the cchDest parameter is zero, the number of bytes or characters required to hold the mapped string indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The mapped string is null-terminated if the source string is null-terminated.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The compatibility zone in Unicode consists of characters in the range 0xF900 through 0xFFEF that are assigned to characters from other character-encoding standards but are actually variants of characters that are already in Unicode. The compatibility zone is used to support round-trip mapping to these standards. Applications can use the MAP_FOLDCZONE flag to avoid supporting the duplication of characters in the compatibility zone.

See Also

LCMapString, CompareString


FormatMessage

This function formats a message string.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD FormatMessage (DWORD dwFlags, LPCVOID lpSource, DWORD dwMessageId, DWORD dwLanguageId, LPTSTR lpBuffer, DWORD nSize, va_list* Arguments);

Parameters

dwFlags
[in] Specifies aspects of the formatting process and how to interpret the lpSource parameter. The low-order byte of dwFlags specifies how the function handles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

This parameter can be a combination of the following bit flags:
Value
Description
FORMAT_MESSAGE_ALLOCATE_BUFFER | Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of bytes (ANSI version) or characters (Unicode version) to allocate for an output message buffer. The function allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed.
FORMAT_MESSAGE_IGNORE_INSERTS | Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for fetching a message for later formatting. If this flag is set, the Arguments parameter is ignored.
FORMAT_MESSAGE_FROM_STRING | Specifies that lpSource is a pointer to a null-terminated message definition. The message definition may contain insert sequences, just as the message text in a message table resource may. Cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM.
FORMAT_MESSAGE_FROM_HMODULE | Specifies that lpSource is a module handle containing the message-table resource(s) to search. If this lpSource handle is NULL, the current process’s application image file will be searched. Cannot be used with FORMAT_MESSAGE_FROM_STRING.
FORMAT_MESSAGE_FROM_SYSTEM | Specifies that the function should search the system message-table resource(s) for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, the function searches the system message table if the message is not found in the module specified by lpSource. Cannot be used with FORMAT_MESSAGE_FROM_STRING.
If this flag is specified, an application can pass the result of the GetLastError function to retrieve the message text for a system-defined error.
Not all Windows CE-based devices will contain the system message-table resources. This is a selectable part of the Windows CE operating system and is often removed to conserve space.
FORMAT_MESSAGE_ARGUMENT_ARRAY | Specifies that the Arguments parameter is not a va_list structure, but instead is just a pointer to an array of 32-bit values that represent the arguments.

The low-order byte of dwFlags can specify the maximum width of a formatted output line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations to set and retrieve this maximum width value.

The following list shows how FormatMessage interprets the value of the low-order byte.
Value
Description
0 | There are no output line width restrictions. The function stores line breaks that are in the message definition text into the output buffer.
A nonzero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK | The nonzero value is the maximum number of characters in an output line. The function ignores regular line breaks in the message definition text. The function never splits a string delimited by white space across a line break. The function stores hard-coded line breaks in the message definition text into the output buffer. Hard-coded line breaks are coded with the %n escape sequence.
FORMAT_MESSAGE_MAX_WIDTH_MASK | The function ignores regular line breaks in the message definition text. The function stores hard-coded line breaks in the message definition text into the output buffer. The function generates no new line breaks.

lpSource
[in] Pointer to the location of the message definition. The type of this parameter depends upon the settings in the dwFlags parameter.
Value
Description
FORMAT_MESSAGE_FROM_HMODULE | The lpSource parameter is an hModule of the module that contains the message table to search.
FORMAT_MESSAGE_FROM_STRING | The lpSource parameter is an LPTSTR that points to unformatted message text. It will be scanned for inserts and formatted accordingly.

If neither of these flags is set in dwFlags, then lpSource is ignored.

dwMessageId
[in] Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
dwLanguageId
[in] Not supported.
lpBuffer
[out] Pointer to a buffer for the formatted (and null-terminated) message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer using the LocalAlloc function, and places the pointer to the buffer at the address specified in lpBuffer.
nSize
[in] If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the maximum number of characters that can be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of bytes or characters to allocate for an output buffer.
Arguments
[in] Pointer to an array of 32-bit values that are used as insert values in the formatted message. A %1 in the format string indicates the first value in the Arguments array; a %2 indicates the second argument; and so on.

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string.

By default, the Arguments parameter is of type va_list*, which is a language- and implementation-specific data type for describing a variable number of arguments. If you do not have a pointer of type va_list*, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 32-bit values; those values are input to the message formatted as the insert values. Each insert must have a corresponding element in the array.

Return Values

The number of characters stored in the output buffer, excluding the terminating null character, indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This function requires a message definition as input. The message definition can come from a buffer passed into the function. It can come from a message table resource in an already loaded module. Or the caller can ask the function to search the system’s message table resources for the message definition. FormatMessage finds the message definition in a message table resource based on a message identifier. FormatMessage copies the formatted message text to an output buffer, processing any embedded insert sequences if requested.

The FormatMessage function can be used to obtain error message strings for the system error codes returned by GetLastError, as shown in the following sample code.

LPVOID lpMsgBuf;
FormatMessage(
    FORMAT_MESSAGE_ALLOCATE_BUFFER |
    FORMAT_MESSAGE_FROM_SYSTEM |
    FORMAT_MESSAGE_IGNORE_INSERTS,
    NULL,
    GetLastError(),
    0, // Default language
    (LPTSTR) &lpMsgBuf,
    0,
    NULL
);
// Process any inserts in lpMsgBuf.
// ...
// Display the string.
MessageBox( NULL, (LPCTSTR)lpMsgBuf, "Error", MB_OK | MB_ICONINFORMATION );
// Free the buffer.
LocalFree( lpMsgBuf );

Within the message text, several escape sequences are supported for dynamically formatting the message. These escape sequences and their meanings are shown in the following list. All escape sequences start with the percent character (%).

%0
Terminates a message text line without a trailing newline character. This escape sequence can be used to build up long lines or to terminate the message itself without a trailing newline character. It is useful for prompt messages.
%n!printf format string!
Identifies an insert. The value of n can be in the range 1 through 99. The printf format string (which must be bracketed by exclamation marks) is optional and defaults to !s! if not specified.

The printf format string can contain the * specifier for either the precision or the width component. If * is specified for one component, the FormatMessage function uses insert %n+1; it uses %n+2 if * is specified for both components.

Floating-point printf format specifiers—e, E, f, and g—are not supported. The workaround is to to use the sprintf function to format the floating-point number into a temporary buffer, then use that buffer as the insert string.

Any other nondigit character following a percent character is formatted in the output message without the percent character. Following are some examples:

Format string
Resulting output
%% A single percent sign in the formatted message text.
%n | A hard line break when the format string occurs at the end of a line. This format string is useful when FormatMessage is supplying regular line breaks so the message fits in a certain width.
%space | A space in the formatted message text. This format string can be used to ensure the appropriate number of trailing spaces in a message text line.
%. A single period in the formatted message text. This format string can be used to include a single period at the beginning of a line without terminating the message text definition.
%! A single exclamation point in the formatted message text. This format string can be used to include an exclamation point immediately after an insert without its being mistaken for the beginning of a printf format string.

See Also

LoadString, LocalFree


FreeLibrary

This function decrements the reference count of the loaded dynamic-link library (DLL) module. When the reference count reaches zero, the module is unmapped from the address space of the calling process and the handle is no longer valid.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL FreeLibrary( HMODULE hLibModule );

Parameters

hLibModule
Handle to the loaded library module. The LoadLibrary or GetModuleHandle function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Each process maintains a reference count for each loaded library module. This reference count is incremented each time LoadLibrary is called and is decremented each time FreeLibrary is called. A DLL module loaded at process initialization due to load-time dynamic linking has a reference count of one. This count is incremented if the same module is loaded by a call to LoadLibrary.

Before unmapping a library module, the system enables the DLL to detach from the process by calling the DLL’s DllMain function, if it has one, with the DLL_PROCESS_DETACH value. Doing so gives the DLL an opportunity to clean up resources allocated on behalf of the current process. After the entry-point function returns, the library module is removed from the address space of the current process.

It is not safe to call FreeLibrary from DllMain. For more information, see the Remarks section in DllMain.

Calling FreeLibrary does not affect other processes using the same library module.

See Also

LoadLibrary


FSD_MountDisk

This function is called by the file system driver (FSD) to mount the specified disk containing a file system of the type defined.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL FSD_MountDisk( HDSK hdsk );

Parameters

hdsk
[in] Handle to the disk, though not a true Win32 handle.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The FSD must be able to cope with FSD_MountDisk being called redundantly. It must determine from the media itself, not the value of hdsk, whether the disk is already mounted. This is required because the user media may have been removed or may have changed slots while the system was powered off. The value of hdsk has meaning only to FSDMGR functions, not to the FSD.

Use the FSDMGR_ReadDisk and FSDMGR_WriteDisk functions for all input/output to the mounted disk.

See Also

MyFSD_MountDisk, FSD_UnmountDisk


FSD_UnmountDisk

This function is called by the file system driver (FSD) to unmount the specified disk containing a file system of the type defined by the FSD.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL FSD_UnmountDisk( HDSK hdsk );

Parameters

hdsk
[in] Handle to the disk, though not a true Win32 handle.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

A requirement of returning TRUE is that all volumes on the disk previously registered with the FSDMGR_RegisterVolume function must first be deregistered with the FSDMGR_DeregisterVolume function.

See Also

FSDMGR_DeregisterVolume, FSDMGR_RegisterVolume, FSD_MountDisk, MyFSD_UnmountDisk


FSDMGR_CreateFileHandle

This function is called by the file system driver (FSD) to create a handle for a specified file..

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE FSDMGR_CreateFileHandle( HVOL hVol, HANDLE hProc,
PFILE pFile);

Parameters

hVol
[in] Handle to the mounted volume that is returned from FSDMGR_RegisterVolume. This handle is not a true Win32 handle.
hProc
[in] Handle to the originating process handle.
pFile
[out] Pointer to the file-specific data defined by the file system driver for the new handle.

Return Values

A handle associated with the originating process indicates success. INVALID_HANDLE_VALUE indicates failure.

See Also

FSDMGR_RegisterVolume


FSDMGR_CreateSearchHandle

This function creates search, or find, handles.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE FSDMGR_CreateSearchHandle( HVOL hVol, HANDLE hProc,
PSEARCH pSearch);

Parameters

hVol
[in] Handle to the mounted volume that is returned from FSDMGR_RegisterVolume. This handle is not a true Win32 handle.
hProc
[in] Handle to the originating process handle.
pSearch
[out] Pointer to the search-specific data defined by the file system driver for the new handle.

Return Values

A search handle associated with the originating process indicates success. INVALID_HANDLE_VALUE indicates failure.

Remarks

This function returns a handle to the application that called the FindFirstFile function created by the independent software vendor.

See Also

FindFirstFile, FSDMGR_RegisterVolume


FSDMGR_DeregisterVolume

This function unregisters a volume.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

void FSDMGR_DeregisterVolume( HVOL hVol );

Parameters

hVol
[in] Handle to the mounted volume that is returned from FSDMGR_RegisterVolume. This handle is not a true Win32 handle.

Return Values

None.

See Also

FSDMGR_RegisterVolume


FSDMGR_GetDiskInfo

This function gets disk information.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD FSDMGR_GetDiskInfo ( HDSK hDsk, PFDI pfdi);

Parameters

hDsk
[in] Handle to the disk; this is the same value that was passed to FSD_MountDisk. This handle is not a true Win32 handle.
pfdi
[out] Pointer to the FSD_DISK_INFO structure to be filled in.

Return Values

ERROR_SUCCESS indicates the FSD_DISK_INFO structure was successfully filled in. A standard WinAPI error code indicates failure.

See Also

FSD_DISK_INFO, FSD_MountDisk


FSDMGR_GetVolumeName

This function gets the name of a volume, given its handle.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

INT FSDMGR_GetVolumeName( HVOL hVol, PWSTR pwsName,int cchMax );

Parameters

hVol
[in] Handle to the mounted volume that is returned from FSDMGR_RegisterVolume. This handle is not a true Win32 handle.
pwsName
[out] Pointer to the string that contains the volume name. Set to NULL to get the size of the volume name.
cchMax
[in] Maximum number of characters allowed in the buffer, including the terminating NULL. This is ignored if pwsName is NULL.

Return Values

The number of characters returned, not including the terminating NULL, indicates success. Zero indicates failure.

See Also

FSDMGR_RegisterVolume


FSDMGR_ReadDisk

This function reads sectors from a disk.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD FSDMGR_ReadDisk ( HDSK hDsk, DWORD dwSector,
DWORD cSectors, PBYTE pBuffer, DWORD cbBuffer );

Parameters

hDsk
[in] Handle to the mounted disk; this is the same value that was passed to FSD_MountDisk. This handle is not a true Win32 handle.
dwSector
[in] Specifies the starting sector number.
cSectors
[in] Number of sectors to read.
pBuffer
[out] Pointer to a buffer to hold the information that is read.
cbBuffer
[in] Size of the buffer, in bytes.

Return Values

ERROR_SUCCESS indicates success. A standard WinAPI error code indicates failure.

See Also

FSD_MountDisk


FSDMGR_ReadDiskEx

This function reads sectors from a disk into discontiguous buffers.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD FSDMGR_ReadDiskEx ( PFSGI pfsgi, PFSGR pfsgr);

Parameters

pfsgi
[in] Pointer to an FSD_SCATTER_GATHER_INFO structure.
pfsgr
[in] Pointer to an FSD_SCATTER_GATHER_RESULTS structure.

Return Values

ERROR_SUCCESS indicates success. A standard WinAPI error code indicates failure.

Remarks

The pfbi member of the FSD_SCATTER_GATHER_INFO structure points to the FSD_BUFFER_INFO structure or structures, which contain the information read from the mounted volumes. The cSectorsTransferred member of the FSD_SCATTER_GATHER_RESULTS structure contains the total number of sectors transferred. If the driver or system does not support scatter/gather, the output is converted automatically to normal I/O.

See Also

FSD_BUFFER_INFO, FSD_SCATTER_GATHER_INFO, FSD_SCATTER_GATHER_RESULTS, FSDMGR_WriteDiskEx


FSDMGR_RegisterVolume

This function registers a volume on a disk.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

HVOL FSDMGR_RegisterVolume( HDSK hDsk, PWSTR pwsName, PVOLUME pVolume );

Parameters

hDsk
[in] Handle to the disk; this is the same value passed to FSD_MountDisk. This handle is not a true Win32 handle.
pwsName
[in] Pointer to the string that contains the volume name. Use NULL for the default name.
pVolume
[out] Pointer to the volume-specific data defined by the file system driver (FSD).

Return Values

The volume identifier indicates success. NULL indicates failure.

See Also

FSD_MountDisk


FSDMGR_WriteDisk

This function writes sectors to a disk.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD FSDMGR_WriteDisk ( HDSK hDsk, DWORD dwSector,
DWORD cSectors, PBYTE pBuffer, DWORD cbBuffer );

Parameters

hDsk
[in] Handle to the disk; this is the same value that was passed to FSD_MountDisk. This handle is not a true Win32 handle.
dwSector
[in] Specifies starting sector number.
cSectors
[in] Number of sectors to write.
pBuffer
[in] Pointer to the buffer that contains the data to write to the disk.
cbBuffer
[in] Size of the buffer, in bytes.

Return Values

ERROR_SUCCESS indicates success. A standard WinAPI error code indicates failure.

See Also

FSD_MountDisk


FSDMGR_WriteDiskEx

This function writes sectors to a disk from discontiguous buffers.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD FSDMGR_WriteDiskEx ( PFSGI pfsgi, PFSGR pfsgr);

Parameters

pfsgi
[in] Pointer to an FSD_SCATTER_GATHER_INFO structure.
pfsgr
[in] Pointer to an FSD_SCATTER_GATHER_RESULTS structure.

Return Values

ERROR_SUCCESS indicates success. A standard WinAPI error code indicates failure.

Remarks

The pfbi member of the FSD_SCATTER_GATHER_INFO structure points to the FSD_BUFFER_INFO structure or structures, which contain the information to be written to the mounted volumes. The cSectorsTransferred member of the FSD_SCATTER_GATHER_RESULTS structure contains the total number of sectors transferred. If the driver or system does not support scatter/gather, the output is converted automatically to normal I/O.

See Also

FSD_BUFFER_INFO, FSDMGR_ReadDiskEx, FSD_SCATTER_GATHER_INFO, FSD_SCATTER_GATHER_RESULTS


GetACP

This function retrieves the current ANSI code-page identifier for the system.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

UINT GetACP(VOID)

Return Values

The current ANSI code-page identifier for the system or a default identifier if no code page is current indicates success.

Remarks

Following are the ANSI code-page identifiers:

Identifier
Description
874 | Thai
932 | Japan
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan Region; Hong Kong SAR, PRC)
1200 | Unicode (BMP of ISO 10646)
1250 | Windows 3.1 Eastern European
1251 | Windows 3.1 Cyrillic
1252 | Windows 3.1 Latin 1 (US, Western Europe)
1253 | Windows 3.1 Greek
1254 | Windows 3.1 Turkish
1255 | Hebrew
1256 | Arabic
1257 | Baltic

See Also

GetCPInfo, GetOEMCP


GetClassFile

This function supplies the class identifier associated with the specified file name.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.10 and later

Syntax

WINOLEAPI GetClassFile ( LPCWSTR szFileName, CLSID * pclsid);

Parameters

szFileName
[in] Null-terminated string that contains the file name for which you are requesting the associated class identifier.
pclsid
[out] Pointer to the location where the associated class identifier is written on return.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Indicates the class identifier was successfully supplied.
MK_E_CANTOPENFILE | Indicates unable to open the specified filename.
MK_E_INVALIDEXTENSION | Indicates the specified extension in the registry is invalid.

This function can also return any file system errors.

Remarks

When given a filename, the GetClassFile function finds the class identifier associated with that file. Examples of its use are in OleCreateFromFile, which is passed a file name and requires an associated class identifier, and in the OLE implementation of IMoniker::BindToObject, which, when a link to a file-based document is activated, calls GetClassFile to locate the object application that can open the file.

The GetClassFile function searches for the File Extension key in the registry that corresponds to the .ext portion of the filename. If the database entry contains a valid class identifier, this function returns that class identifier.

If the File Extension key is not found or the database entry contains an invalid class identifier, the function returns MK_E_INVALIDEXTENSION.

See Also

StringFromCLSID, WriteClassStg


GetCPInfo

This function retrieves information about any valid installed or available code page.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

BOOL GetCPInfo(UINT CodePage, LPCPINFO lpCPInfo);

Parameters

CodePage
[in] Specifies the code page about which information is to be retrieved. You can specify the code page identifier for any installed or available code page, or you can specify one of the following predefined values:
Value
Description
CP_ACP | Use the system default ANSI code page
CP_MACCP | Not supported.
CP_OEMCP | Use the system default OEM code page

lpCPInfo
[out] Pointer to a CPINFO structure that receives information about the code page.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the specified code page is not installed or not available, GetCPInfo sets the last-error value to ERROR_INVALID_PARAMETER.

See Also

GetACP, GetOEMCP, CPINFO


GetCurrencyFormat

This function formats a number string as a currency string for a specified locale.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int GetCurrencyFormat(LCID Locale, DWORD dwFlags,
LPCTSTR lpValue, const CURRENCYFMT *lpFormat,
LPTSTR lpCurrencyStr, int cchCurrency);

Parameters

Locale
[in] Specifies the locale for which the currency string is to be formatted. If lpFormat is NULL, the function formats the string according to the currency format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the CURRENCYFMT structure (for example, the locale's string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

dwFlags
[in] A bit flag that controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default currency format for the specified locale; or you can specify zero to format the string using any user overrides to the locale's default currency format.

lpValue
[in] Pointer to a null-terminated string that contains the number string to format.

This string can contain only the following characters:

  • Characters ‘0’ through ‘9’
  • One decimal point (dot) if the number is a floating-point value
  • A minus sign in the first character position if the number is a negative value

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat
[in] Pointer to a CURRENCYFMT structure that contains currency formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the currency format of the specified locale.

lpCurrencyStr
[out] Pointer to a buffer to receive the formatted currency string.
cchCurrency
[in] Specifies the size, in characters, of the lpCurrencyStr buffer. If cchCurrency is zero, the function returns the number of bytes or characters required to hold the formatted currency string, and the buffer pointed to by lpCurrencyStr is not used.

Return Values

The number of characters written to the buffer pointed to by lpCurrencyStr, or, if the cchCurrency parameter is zero, the number of characters required to hold the formatted currency string indicates success. The count includes the terminating null. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID FLAGS
  • ERROR_INVALID_PARAMETER

See Also

GetNumberFormat, CURRENCYFMT


GetCurrentProcess

This function returns a pseudohandle for the current process.

At a Glance

Header file: | Kfuncs.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE GetCurrentProcess(void);

Return Values

A pseudohandle to the current process indicates success.

Remarks

A pseudohandle is a special constant that is interpreted as the current process handle. The calling process can use this handle to specify its own process whenever a process handle is required.

This handle has the maximum possible access to the process object. A process can also use the OpenProcess function to open a real handle to itself.

The pseudohandle need not be closed when it is no longer needed. Calling the CloseHandle function with a pseudohandle has no effect.

See Also

CloseHandle, GetCurrentProcessId, GetCurrentThread


GetCurrentProcessId

This function returns the process identifier of the calling process.

At a Glance

Header file: | Kfuncs.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetCurrentProcessId(void);

Return Values

The identifier of the calling process indicates success.

Remarks

Until the process terminates, the process identifier uniquely identifies the process throughout the system. In Windows CE, the processor identifier returned from this function is the same as the process handle.

See Also

GetCurrentProcess


GetCurrentThread

This function returns a pseudohandle for the current thread.

At a Glance

Header file: | Kfuncs.h
Versions: | 1.0 and later

Syntax

HANDLE GetCurrentThread(void);

Return Values

A pseudohandle for the current thread indicates success.

Remarks

A pseudohandle is a special constant that is interpreted as the current thread handle. The calling thread can use this handle to specify itself whenever a thread handle is required.

This handle has the maximum possible access to the thread object.

The function cannot be used by one thread to create a handle that can be used by other threads to refer to the first thread. The handle is always interpreted as referring to the thread that is using it. A thread can create a “real” handle to itself that can be used by other threads, or inherited by other processes, by specifying the pseudohandle as the source handle in a call to the DuplicateHandle function.

The pseudohandle need not be closed when it is no longer needed. Calling the CloseHandle function with this handle has no effect.

See Also

CloseHandle, GetCurrentProcess, GetCurrentThreadId


GetCurrentThreadId

This function returns the thread identifier, which is used as a handle of the calling thread.

At a Glance

Header file: | Kfuncs.h
Versions: | 1.0 and later

Syntax

DWORD GetCurrentThreadId(void);

Return Values

The thread identifier of the calling thread indicates success.

Remarks

Until the thread terminates, the thread identifier uniquely identifies the thread throughout the system. This identifier is also the handle of the thread.

See Also

GetCurrentThread


GetDateFormat

This function formats a date as a date string for a specified locale. The function formats either a specified date or the local system date.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int GetDateFormat(LCID Locale, DWORD dwFlags,
CONST SYSTEMTIME *lpDate, LPCTSTR lpFormat, LPTSTR lpDateStr,
int cchDate);

Parameters

Locale
[in] Specifies the locale for which the date string is to be formatted. If lpFormat is NULL, the function formats the string according to the date format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's day and month names).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

For Windows CE version 1.0, Locale is ignored.

dwFlags
[in] Specifies various function options. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify a combination of the following flags:
Value
Description
DATE_SHORTDATE | Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE | Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_LTRREADING | Not supported.
DATE_RTLREADING | Not supported
LOCALE_NOUSEROVERRIDE | If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default–date format.
LOCALE_USE_CP_ACP | Not supported
DATE_YEARMONTH | Not supported.
DATE_USE_ALT_CALENDAR | Uses the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar.

lpDate
[in] Pointer to a SYSTEMTIME structure that contains the date information to be formatted. If this pointer is NULL, the function uses the current local system date.
lpFormat
[in] Pointer to a format picture string to use to form the date string. If lpFormat is NULL, the function uses the date format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown in the table (for example, “MM” not “mm”). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.
Value
Description
d | Day of month as digits with no leading zero for single-digit days.
dd | Day of month as digits with leading zero for single-digit days.
ddd | Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd | Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M | Month as digits with no leading zero for single-digit months.
MM | Month as digits with leading zero for single-digit months.
MMM | Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM | Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y | Year as last two digits, with a leading zero for years less than 10. The same format as “yy.”
yy | Year as last two digits, with a leading zero for years less than 10.
yyyy | Year represented by full four digits.
gg | Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the date string

“Wed, Aug 31 94”

use the following picture string:

“ddd',' MMM dd yy”

lpDateStr
[out] Pointer to a buffer that receives the formatted date string.
cchDate
[in] Specifies the size, in characters, of the lpDateStr buffer. If cchDate is zero, the function returns the number of characters required to hold the formatted date string, and the buffer pointed to by lpDateStr is not used.

Return Values

The number of characters written to the lpDateStr buffer, or, if the cchDate parameter is zero, the number of characters required to hold the formatted date string indicates success. The count includes the terminating null. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the given locale identifier.

The date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value, and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.

The DATE_SHORTDATE and DATE_LONGDATE flag options are mutually exclusive. If neither one is specified and lpFormat is NULL, then DATE_SHORTDATE is the default.

For Windows CE versions 2.10 and later, default DATE_SHORTDATE formats for non-U.S. English locales that include the four-digit year are added. The following table shows the formats.

Locale
Date Format
United Kingdom | dd/MM/yyyy
Canada | dd/MM/yyyy
New Zealand | dd/MM/yyyy
Ireland | dd/MM/yyyy
South Africa | dd/MM/yyyy
Caribbean | MM/dd/yyyy
Belize | dd/MM/yyyy
Trinidad | dd/MM/yyyy

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L”yyyy” and L”yy” (the ‘L’ indicates a Unicode (16-bit characters) string). If L”y” is passed in, the function assumes L”yy”. If L”yyy” is passed in, the function assumes L”yyyy”. If more than 4 date (L”dddd”) or 4 month (L”MMMM”) pictures are passed in, then the function defaults to L”dddd” or L”MMMM”.

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string would be: L"MMMM ''''yy" The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

See Also

GetTimeFormat, SYSTEMTIME


GetDiskFreeSpaceEx

This function obtains information about the amount of space available on a disk volume: the total amount of space, the total amount of free space, and the total amount of free space available to the user associated with the calling thread.

At a Glance

Header file: | Winbase.h
Versions: | 2.0 and later

Syntax

BOOL GetDiskFreeSpaceEx( LPCWSTR lpDirectoryName,
PULARGE_INTEGER lpFreeBytesAvailableToCaller,
PULARGE_INTEGER lpTotalNumberOfBytes,
PULARGE_INTEGER lpTotalNumberOfFreeBytes );

Parameters

lpDirectoryName
[in] Pointer to a null-terminated string that specifies a directory on the disk of interest. This string can be a UNC name. If this parameter is a UNC name, you must follow it with an additional backslash. For example, you would specify \\MyServer\MyShare as \\MyServer\MyShare\.

If lpDirectoryName is NULL, the GetDiskFreeSpaceEx function obtains information about the object store.

Note that lpDirectoryName does not have to specify the root directory on a disk. The function accepts any directory on the disk.

lpFreeBytesAvailableToCaller
[out] Pointer to a variable to receive the total number of free bytes on the disk that are available to the user associated with the calling thread.
lpTotalNumberOfBytes
[out] Pointer to a variable to receive the total number of bytes on the disk that are available to the user associated with the calling thread.
lpTotalNumberOfFreeBytes
[out] Pointer to a variable to receive the total number of free bytes on the disk.

This parameter can be NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Note that the values obtained by this function are of type ULARGE_INTEGER. Be careful not to truncate these values to 32 bits.


GetErrorInfo

This function obtains the error information pointer set by the previous call to SetErrorInfo in the current logical thread.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.10 and later

Syntax

HRESULT GetErrorInfo( DWORD dwReserved, IErrorInfo **pperrinfo );

Parameters

dwReserved
Reserved for future use; set to zero.
pperrinfo
Pointer to a pointer to a system-implemented generic error object.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
S_FALSE | There was no error object to return.

Remarks

This function returns a pointer to the most recently set IErrorInfo pointer in the current logical thread. It transfers ownership of the error object to the caller, and clears the error state for the thread.

See Also

SetErrorInfo


GetExceptionCode

This function retrieves a code that identifies the type of exception that occurred. GetExceptionCode can be called only from within the filter expression or exception-handler block of a try-except exception handler.

At a Glance

Header file: | Excpt.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetExceptionCode(void);

Return Values

The return value identifies the type of exception. Following are the exception codes likely to occur due to common programming errors:

EXCEPTION_ACCESS_VIOLATION
The thread attempted to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_BREAKPOINT
A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT
The thread attempted to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries, 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_SINGLE_STEP
A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED
The thread attempted to access an array element that is out of bounds, and the underlying hardware supports bounds checking.
EXCEPTION_FLT_DENORMAL_OPERAND
One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO
The thread attempted to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT
The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION
This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW
The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK
The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW
The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_INT_DIVIDE_BY_ZERO
The thread attempted to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW
The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_PRIV_INSTRUCTION
The thread attempted to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_NONCONTINUABLE_EXCEPTION
The thread attempted to continue execution after a noncontinuable exception occurred.

Remarks

The Excpt.h file has to be explicitly included in order to use GetExceptionCode.

The GetExceptionCode function can be called only from within the filter expression or exception-handler block of a try-except statement. The filter expression is evaluated if an exception occurs during execution of the try block, and it determines whether the except block is executed.

The filter expression can invoke a filter function. The filter function cannot call GetExceptionCode. However, the return value of GetExceptionCode can be passed as a parameter to a filter function. The return value of the GetExceptionInformation function can also be passed as a parameter to a filter function. GetExceptionInformation returns a pointer to a structure that includes the exception-code information.

The following code example shows the structure of a try-except statement.

try
{

    // try block

}
except ( FilterFunction(GetExceptionCode() )
{

    // exception handler block

}

In the case of nested try-except statements, each statement’s filter expression is evaluated until one is evaluated as EXCEPTION_EXECUTE_HANDLER or EXCEPTION_CONTINUE_EXECUTION. Each filter expression can invoke GetExceptionCode to get the exception code.

The exception code returned is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception.

When handling the breakpoint exception, it is important to increment the instruction pointer in the context record to continue from this exception.

See Also

GetExceptionInformation


GetExceptionInformation

This function retrieves a machine-independent description of an exception, and information about the machine state that existed for the thread when the exception occurred. GetExceptionInformation can be called only from within the filter expression of a try-except exception handler.

At a Glance

Header file: | Excpt.h
Windows CE versions: | 1.0 and later

Syntax

LPEXCEPTION_POINTERS GetExceptionInformation(void);

Return Values

A pointer to an EXCEPTION_POINTERS structure that contains pointers to two other structures—an EXCEPTION_RECORD structure containing a description of the exception, and a CONTEXT structure containing the machine-state information—indicates success.

Remarks

The Excpt.h file must be explicitly included in order to use GetExceptionInformation.

The filter expression (from which the function is called) is evaluated if an exception occurs during execution of the try block, and it determines whether the except block is executed.

The following code example shows the structure of a try-except statement.

try
{

    // try block

}
except ( FilterFunction(GetExceptionInformation() )
{

    // exception handler block

}

The filter expression can invoke a filter function. The filter function cannot call GetExceptionInformation. However, the return value of GetExceptionInformation can be passed as a parameter to a filter function.

To pass the EXCEPTION_POINTERS information to the exception-handler block, the filter expression or filter function must copy the pointer or the data to safe storage that the handler can later access.

In the case of nested try-except statements, each statement’s filter expression is evaluated until one is evaluated as EXCEPTION_EXECUTE_HANDLER or EXCEPTION_CONTINUE_EXECUTION. Each filter expression can invoke GetExceptionInformation to get exception information.

See Also

EXCEPTION_POINTERS, EXCEPTION_RECORD, GetExceptionCode


GetExitCodeProcess

This function retrieves the termination status of the specified process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL GetExitCodeProcess ( HANDLE hProcess, LPDWORD lpExitCode);

Parameters

hProcess
Handle to the process.
lpExitCode
Pointer to a 32-bit variable to receive the process termination status.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

  • The exit value specified in the ExitProcess or TerminateProcess function.
  • The return value from the main or WinMain function of the process.
  • The exception value for an unhandled exception that caused the process to terminate.

See Also

ExitThread, TerminateProcess, WinMain


GetExitCodeThread

This function retrieves the termination status of the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL GetExitCodeThread( HANDLE hThread, LPDWORD lpExitCode);

Parameters

hThread
Handle to the thread.
lpExitCode
Pointer to a 32-bit variable to receive the thread termination status.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the specified thread has not terminated, the termination status returned is STILL_ACTIVE. If the thread has terminated, the termination status returned may be one of the following:

  • The exit value specified in the ExitThread or TerminateThread function.
  • The return value from the thread function.
  • The exit value of the thread’s process.

See Also

ExitThread


GetFileAttributes

This function returns attributes for a specified file or directory. A remote application interface (RAPI) version of this function exists, and it is named CeGetFileAttributes.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetFileAttributes(LPCTSTR lpFileName);

Parameters

lpFileName
[in] Pointer to a null-terminated string that specifies the name of a file or directory.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the GetFileAttributes function parses paths.

Return Values

The attributes of the specified file or directory, returned in a DWORD, indicates success. 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

The attributes returned upon success can be one or more of the following values:

FILE_ATTRIBUTE_ARCHIVE
The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
The handle identifies a directory.
FILE_ATTRIBUTE_ENCRYPTED
The file or directory is encrypted. For a file, this means that all data streams are encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN
The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_INROM
This file is an operating system file stored in ROM. These files are read-only; they cannot be modified.
FILE_ATTRIBUTE_NORMAL
The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE
The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY
The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_REPARSE_POINT
The file has an associated reparse point.
FILE_ATTRIBUTE_ROMMODULE
This file is an operating system file stored in ROM and executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file, instead the LoadLibrary and CreateProcess functions must be used.
FILE_ATTRIBUTE_ROMSTATICREF
The file is a DLL module that has a static reference from at least one other file that is in the modules section of the image. A file having this attribute can not replace the functionality of the DLL with a RAM copy of the same DLL. A file having this attribute must also have the FILE_ATTRIBUTE_INROM and FILE_ATTRIBUTE_ROMMODULE attributes.
FILE_ATTRIBUTE_SPARSE_FILE
The file is a sparse file.
FILE_ATTRIBUTE_SYSTEM
The file or directory is part of, or is used exclusively by, the operating system.
FILE_ATTRIBUTE_TEMPORARY
The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
FILE_ATTRIBUTE_ROMSTATICREF
The DLL module is statically linked to other modules in ROM. The functionality of this DLL cannot be replaced by a module with the same name that is in a different location.

See Also

FindFirstFile, FindNextFile, SetFileAttributes


GetFileInformationByHandle

This function retrieves information about the specified file.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetFileInformationByHandle( HANDLE hFile,
LPBY_HANDLE_FILE_INFORMATION lpFileInformation );

Parameters

hFile
[in] Handle to the file that you want to obtain information about.

This handle should not be a pipe handle. The GetFileInformationByHandle function does not work with pipe handles.

lpFileInformation
[out] Pointer to a BY_HANDLE_FILE_INFORMATION structure that receives the file information. The structure can be used in subsequent calls to GetFileInformationByHandle to refer to the information about the file.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Depending on the underlying network components of the operating system and the type of server connected to, the GetFileInformationByHandle function may fail, return partial information, or full information for the specified file. In general, you should not use GetFileInformationByHandle unless your application is intended to be run on a limited set of operating system configurations.

See Also

BY_HANDLE_FILE_INFORMATION


GetFileSize

This function retrieves the size, in bytes, of the specified file. A remote application interface (RAPI) version of this function exists, and it is named CeGetFileSize.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetFileSize( HANDLE hFile, LPDWORD lpFileSizeHigh );

Parameters

hFile
[in] Open handle of the file whose size is being returned. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.
lpFileSizeHigh
[out] Pointer to the variable where the high-order word of the file size is returned. This parameter can be NULL if the application does not require the high-order word.

Return Values

The low-order DWORD of the file size indicates success. If lpFileSizeHigh is non-NULL, the function puts the high-order DWORD of the file size into the variable pointed to by that parameter. If lpFileSizeHigh is NULL, 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

If lpFileSizeHigh is non-NULL, 0xFFFFFFFF indicates failure and GetLastError returns a value other than NO_ERROR.

Remarks

Note that if the return value is 0xFFFFFFFF and lpFileSizeHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//
// Case One: calling the function with
//           lpFileSizeHigh == NULL

// Try to obtain hFile's size
dwSize = GetFileSize (hFile, NULL) ;

// If we failed ...
if (dwSize == 0xFFFFFFFF) {

    // Obtain the error code.
    dwError = GetLastError() ;

    // Deal with that failure.
    .
    .
    .

    } // End of error handler

//
// Case Two: calling the function with
//           lpFileSizeHigh != NULL

// Try to obtain hFile's huge size.
dwSizeLow = GetFileSize (hFile, & dwSizeHigh) ;

// If we failed ...
if (dwSizeLow == 0xFFFFFFFF
    &&
    (dwError = GetLastError()) != NO_ERROR ){

    // Deal with that failure.
    .
    .
    .

    } // End of error handler.


GetFileTime

This function retrieves the date and time that a file was created, last accessed, and last modified. A remote application interface (RAPI) version of this function exists, and it is named CeGetFileTime.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetFileTime( HANDLE hFile, LPFILETIME lpCreationTime,
LPFILETIME lpLastAccessTime, LPFILETIME lpLastWriteTime );

Parameters

hFile
[in] Handle to the files for which to get dates and times. The file handle must have been created with GENERIC_READ access to the file.
lpCreationTime
[out] Pointer to a FILETIME structure to receive the date and time the file was created. This parameter can be NULL if the application does not require this information.
lpLastAccessTime
[out] Pointer to a FILETIME structure to receive the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.
lpLastWriteTime
[out] Pointer to a FILETIME structure to receive the date and time the file was last written to. This parameter can be NULL if the application does not require this information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The FAT and NTFS file systems support the file creation, last access, and last write time values. The Windows CE object store returns the same time for all three parameters. In general, file system drivers will vary how they support this function.

The precision of the time for a file in a FAT file system is one second. The time precision for files in other file systems, such as those connected through a network or installed on a peripheral device, depends on the file system but may also be limited by the remote device.

See Also

FILETIME, GetFileSize, SetFileTime


GetLastError

This function returns the calling thread’s last-error code value. A remote application interface (RAPI) version of this function exists, and it is named CeGetLastError.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetLastError( void );

Return Values

The calling thread’s last-error code value indicates success. Functions set this value by calling the SetLastError function. The Return Value section of each reference page notes the conditions under which the function sets the last-error code.

Remarks

You should call the GetLastError function immediately when a function’s return value indicates that such a call will return useful data. That is because some functions call SetLastError(0) when they succeed, wiping out the error code set by the most recently failed function.

Most functions in the Win32 API that set the thread’s last error code value set it when they fail; a few functions set it when they succeed. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or –1. Some functions call SetLastError under conditions of success; those cases are noted in each function’s reference page.

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no system error code has this bit set. If you are defining an error code for your application, set this bit to one. That indicates that the error code has been defined by an application, and ensures that your error code does not conflict with any error codes defined by the system.

To obtain an error string for system error codes, use the FormatMessage function. For a complete list of error codes, see Error Values or the SDK header file WINERROR.H.

See Also

SetLastError


GetLocaleInfo

This function retrieves information about a locale.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int GetLocaleInfo(LCID Locale, LCTYPE LCType, LPTSTR lpLCData,
int cchData);

Parameters

Locale
[in] Specifies the locale to retrieve information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

LCType
[in] Specifies one of the LCTYPE constants to indicate the type of information to be retrieved.

All LCTYPE values are mutually exclusive, with the exception of LOCALE_NOUSEROVERRIDE. An application may use the binary-OR operator to combine LOCALE_NOUSEROVERRIDE with any other LCTYPE value. If passed such an LCType value, the function bypasses user overrides, and returns the system default value for the requested LCID.

lpLCData
[out] Pointer to a buffer to receive the requested data.
cchData
[in] Specifies the size, in characters, of the lpLCData buffer. If cchData is zero, the function returns the number of characters required to hold the information, and the buffer pointed to by lpLCData is not used.

Return Values

The number of bytes or characters written to the destination buffer, or, if the cchData parameter is zero, the number of characters required to hold the locale information indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The GetLocaleInfo function always retrieves information in text format. If the information is a numeric value, the function converts the number to text using decimal notation.

See Also

MAKELCID


GetLocalTime

This function retrieves the current local date and time.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void GetLocalTime( LPSYSTEMTIME lpSystemTime );

Parameters

lpSystemTime
[out] Pointer to a SYSTEMTIME structure to receive the current local date and time.

Return Values

None.

See Also

GetSystemTime, SetLocalTime, SYSTEMTIME


GetModuleFileName

This function gets a module file name.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

WINAPI DWORD GetModuleFileName( HMODULE hModule,
LPWSTR lpwFilename, DWORD nSize );

Parameters

hModule
[in] Handle to the module whose executable filename is being requested. If this parameter is NULL, GetModuleFileName returns the path for the file used to create the calling process.
lpFilename
[out] Pointer to a buffer that is filled in with the path and file name of the given module.
nSize
[in] Specifies the length, in characters, of the lpFilename buffer. If the length of the path and file name exceeds this limit, the string is truncated.

Return Values

The length, in characters, of the string copied to the buffer indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

In Windows CE, a DLL is loaded from only one location by the system.


GetModuleHandle

This function returns a module handle for the specified module if the file has been mapped into the address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.10 and later

Syntax

HMODULE GetModuleHandle ( LPCTSTR lpModuleName );

Parameters

lpModuleName
Pointer to a null-terminated string that contains the name of the module, which must be a .DLL file. If the filename extension is omitted, the default library extension .DLL is appended. The filename string can include a trailing point character (.) to indicate that the module name has no extension.

If this parameter is NULL, GetModuleHandle returns a handle to the file used to create the calling process.

All paths are ignored; only the file name and extension are used.

The file extensions .DLL and .CPL are treated as identical when comparing module names.

Return Values

A handle to the specified module indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The returned handle is not global, inheritable, or duplicative, and it cannot be used by another process.

The handles returned by GetModuleHandle and LoadLibrary can be used in the same functions—for example, GetProcAddress, FreeLibrary, or LoadResource. The difference between the two functions involves the reference count. LoadLibrary maps the module into the address space of the calling process, if necessary, and increments the module’s reference count, if it is already mapped. GetModuleHandle, however, returns the handle to a mapped module without incrementing its reference count.

Note that the reference count is used in FreeLibrary to determine whether to unmap the function from the address space of the process. For this reason, use care when using a handle returned by GetModuleHandle in a call to FreeLibrary because doing so can cause a dynamic-link library (DLL) module to be unmapped prematurely.

This function must also be used carefully in a multithreaded application. There is no guarantee that the module handle remains valid between the time this function returns the handle and the time it is used by another function. For example, a thread might retrieve a module handle by calling GetModuleHandle. Before the thread uses the handle in another function, a second thread could free the module and the system could load another module, giving it the same handle as the module that was recently freed. The first thread would then be left with a module handle that refers to a module different from the one intended.


GetNumberFormat

This function formats a number string as a number string customized for a specified locale.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int GetNumberFormat(LCID Locale, DWORD dwFlags, LPCTSTR lpValue, const NUMBERFMT *lpFormat, LPTSTR lpNumberStr, int cchNumber);

Parameters

Locale
[in] Specifies the locale for which the number string is to be formatted. If lpFormat is NULL, the function formats the string according to the number format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the NUMBERFMT structure (for example, the locale's string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language-neutral locale.

dwFlags
[in] Contains a bit flag that controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default number format for the specified locale; or you can specify zero to format the string using any user overrides to the locale's default number format.

lpValue
[in] Pointer to a null-terminated string that contains the number string to format.

This string can only contain the following characters:

  • Characters ‘0’ through ‘9’
  • One decimal point (dot) if the number is a floating-point value
  • A minus sign in the first character position if the number is a negative value

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat
[in] Pointer to a NUMBERFMT structure that contains number formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the number format of the specified locale.

lpNumberStr
[out] Pointer to a buffer to receive the formatted number string.
cchNumber
[in] Specifies the size, in characters, of the lpNumberStr buffer. If cchNumber is zero, the function returns the number of characters required to hold the formatted number string, and the buffer pointed to by lpNumberStr is not used.

Return Values

The number of characters written to the buffer pointed to by lpNumberStr, or, if the cchNumber parameter is zero, the number of characters required to hold the formatted number string indicates success. The count includes the terminating null. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID FLAGS
  • ERROR_INVALID_PARAMETER

See Also

GetCurrencyFormat, NUMBERFMT


GetOEMCP

This function retrieves the current original equipment manufacturer (OEM) code-page identifier for the system.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

UINT GetOEMCP(void)

Return Values

The current OEM code-page identifier for the system or a default identifier if no code page is current indicates success.

Remarks

Following are the OEM code-page identifiers:

Identifier
Description
437 | MS-DOS United States
708 | Arabic (ASMO 708)
709 | Arabic (ASMO 449+, BCON V4)
710 | Arabic (Transparent Arabic)
720 | Arabic (Transparent ASMO)
737 | Greek (formerly 437G)
775 | Baltic
850 | MS-DOS Multilingual (Latin I)
852 | MS-DOS Slavic (Latin II)
855 | IBM Cyrillic (primarily Russian)
857 | IBM Turkish
860 | MS-DOS Portuguese
861 | MS-DOS Icelandic
862 | Hebrew
863 | MS-DOS Canadian-French
864 | Arabic
865 | MS-DOS Nordic
866 | MS-DOS Russian (former USSR)
869 | IBM Modern Greek
874 | Thai
932 | Japan
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan Region; Hong Kong SAR, PRC)
1361 | Korean (Johab)

See Also

GetACP


GetOpenFileName

This function creates a system-defined dialog box that enables the user to select a file to open.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetOpenFileName( LPOPENFILENAME lpofn );

Parameters

lpofn
[in] Long pointer to an OPENFILENAME structure that contains information used to initialize the dialog box. When GetOpenFileName returns, this structure contains information about the user’s file selection.

Return Values

Nonzero indicates that the user specified a file name and clicked the OK button. The buffer pointed to by the lpstrFile member of the OPENFILENAME structure contains the full path and filename specified by the user.

Zero indicates that the user canceled or closed the Open dialog box or that an error occurred. To get extended error information, call GetLastError. GetOpenFileName sets only the ERROR_INVALID_PARAMETER and ERROR_OUTOFMEMORY errors.

Remarks

Not all members of the OPENFILENAME structure are defined in Windows CE. For information about the defined members, see the reference topic for the OPENFILENAME structure.

On a Palm-size PC, Windows CE modifies the meaning of the following members of the OPENFILENAME structure when it is passed into the GetOpenFileName function.

Flags
If this member is set to the OFN_PROJECT value, the GetOpenFileName function opens the Folder dialog box. Otherwise, the function opens the Open dialog box.
lpstrFile
When GetOpenFileName returns successfully, this member is used to retrieve full path of the selected file name.
lpstrFileTitle
When GetOpenFileName returns successfully, this member is used to retrieve the the project folder name only.
lpstrInitialDir
Pointer to a string that receives the initial folder name, but not the full path name.

When the GetOpenFileName function is called on a Palm-size PC, Windows CE adds the following prespecified undefined members:

  • lpstrCustomFilter
  • lpstrMaxCusFilter
  • lpstrDefExtension
  • lCustData
  • lpfnHook
  • lpstrTemplateName

See Also

EndDialog, GetSaveFileName, OPENFILENAME


GetProcAddress

This function returns the address of the specified exported dynamic-link library (DLL) function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

FARPROC GetProcAddress( HMODULE hModule, LPCWSTR lpProcName );

Parameters

hModule
Handle to the DLL module that contains the function. The LoadLibrary or GetModuleHandle function returns this handle.
lpProcName
Pointer to a null-terminated string containing the function name, or specifies the function’s ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. The lpProcName parameter must be in Unicode.

Return Values

The address of the DLL’s exported function indicates success. NULL indicates failure. To get extended error information, call GetLastError.

When using GetProcAddress to obtain the address of the InitSecurityInterface function, use SECURITY_ENTRYPOINT for the lpProcName parameter.

Remarks

The GetProcAddress function is used to retrieve addresses of exported functions in DLLs.

The spelling and case of the function name pointed to by lpProcName must be identical to that in the EXPORTS statement of the source DLL’s module-definition (.DEF) file. The exported names of Win32 APIs may differ from the names you use when calling these functions in your code. This difference is hidden by macros used in the SDK header files.

The lpProcName parameter can identify the DLL function by specifying an ordinal value associated with the function in the EXPORTS statement. GetProcAddress verifies that the specified ordinal is in the range 1 through the highest ordinal value exported in the .DEF file. The function then uses the ordinal as an index to read the function’s address from a function table. If the .DEF file does not number the functions consecutively from 1 to N (where N is the number of exported functions), an error can occur where GetProcAddress returns an invalid, non-NULL address, even though there is no function with the specified ordinal.

In cases where the function may not exist, the function should be specified by name rather than by ordinal value.

See Also

FreeLibrary, LoadLibrary


GetProcessHeap

This function obtains a handle to the heap of the calling process. This handle can then be used in calls to the HeapAlloc, HeapReAlloc, HeapFree, and HeapSize functions.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE GetProcessHeap(VOID)

Return Values

A handle to the calling process’s heap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The GetProcessHeap function allows you to allocate memory from the process heap without having to first create a heap with the HeapCreate function, as shown in this example:

HeapAlloc(GetProcessHeap(), 0, dwBytes);

Note The handle obtained by calling this function should not be used in calls to the HeapDestroy function.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


GetSaveFileName

This function creates a system-defined dialog box that enables the user to select a file to save.

At a Glance

Header file: | Commdlg.h
Versions: | 1.0 and later

Syntax

BOOL GetSaveFileName( LPOPENFILENAME lpofn );

Parameters

lpofn
[in] Long pointer to an OPENFILENAME structure that contains information used to initialize the dialog box. When GetSaveFileName returns, this structure contains information about the user’s file selection.

Return Values

Nonzero indicates that the user specified a file name and clicked the OK button. The buffer pointed to by the lpstrFile member of the OPENFILENAME structure contains the full path and filename specified by the user.

Zero indicates that the user canceled or closed the Save dialog box or that an error occurred. To get extended error information, call GetLastError. GetSaveFileName sets only the ERROR_INVALID_PARAMETER and ERROR_OUTOFMEMORY errors.

Remarks

Not all members of the OPENFILENAME structure are defined in Windows CE. For information about the defined members, see the reference topic for the OPENFILENAME structure.

On a Palm-size PC, Windows CE modifies the meaning of the following members of the OPENFILENAME structure when it is passed into the GetOpenFileName function.

Flags
If this member is set to the OFN_PROJECT value, the GetOpenFileName function opens the Folder dialog box. Otherwise, the function opens the Open dialog box.
lpstrFile
When GetOpenFileName returns successfully, this member is used to retrieve full path of the selected file name.
lpstrFileTitle
When GetOpenFileName returns successfully, this member is used to retrieve the the project folder name only.
lpstrInitialDir
Pointer to a string that receives the initial folder name, but not the full path name.

When the GetOpenFileName function is called on a Palm-size PC, Windows CE adds the following prespecified undefined members:

  • lpstrCustomFilter
  • lpstrMaxCusFilter
  • lpstrDefExtension
  • lCustData
  • lpfnHook
  • lpstrTemplateName

See Also

GetOpenFileName, WM_CTLCOLORDLG, OPENFILENAME


GetStoreInformation

This function fills in a STORE_INFORMATION structure with the size of the object store and the amount of free space currently in the object store.

A remote application interface (RAPI) version of this function exists, and it is named CeGetStoreInformation.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetStoreInformation( LPSTORE_INFORMATION lpsi );

Parameters

lpsi
[out] Pointer to the STORE_INFORMATION structure to be filled in by this function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

Remarks

The system reserves that last 24K for high priority system operations. This function always reports 24K storage memory less then what is really available.

See Also

STORE_INFORMATION


GetStringType

This function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetStringType (DWORD dwInfoType, LPCWSTR lpSrcStr, int cchSrc, LPWORD lpCharType);

Parameters

dwInfoType
[in] Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:
Value
Description
CT_CTYPE1 | Retrieve character type information.
CT_CTYPE2 | Retrieve bidirectional layout information.
CT_CTYPE3 | Retrieve text processing information.

lpSrcStr
[in] Pointer to the string for which character types are requested. If cchSrc is –1, the string is assumed to be null terminated. This must be a Unicode string.
cchSrc
[in] Specifies the size, in characters, of the string pointed to by the lpSrcStr parameter. If this count includes a terminating null character, the function returns character type information for the terminating null character. If this value is –1, the string is assumed to be null terminated and the length is calculated automatically.
lpCharType
[out] Pointer to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for the number of characters specified in the cchSrc parameter. When the function returns, this array contains one word corresponding to each Unicode character in the source string.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The GetStringType function is designed for Unicode strings only. In the Microsoft Platform SDK, this function is named GetStringTypeW to distinguish it from the similar ANSI-string function, GetStringTypeA. Because Windows CE only supports Unicode, it requires only the single GetStringType function.

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1
These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.
Name
Value
Description
C1_UPPER | 0x0001 | Uppercase
C1_LOWER | 0x0002 | Lowercase
C1_DIGIT | 0x0004 | Decimal digits
C1_SPACE | 0x0008 | Space characters
C1_PUNCT | 0x0010 | Punctuation
C1_CNTRL | 0x0020 | Control characters
C1_BLANK | 0x0040 | Blank characters
C1_XDIGIT | 0x0080 | Hexadecimal digits
C1_ALPHA | 0x0100 | Any linguistic character: alphabetic, syllabary, or ideographic

The following character types are either constant or computable from basic types and do not need to be supported by this function.
Type
Description
Alphanumeric | Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable | Graphic characters and blanks (all C1_* types except C1_CNTRL)

Ctype 2
These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.
Name
Value
Description
Strong
C2_LEFTTORIGHT | 0x0001 | Left to right
C2_RIGHTTOLEFT | 0x0002 | Right to left
Weak
C2_EUROPENUMBER | 0x0003 | European number, European digit
C2_EUROPESEPARATOR | 0x0004 | European numeric separator
C2_EUROPETERMINATOR | 0x0005 | European numeric terminator
C2_ARABICNUMBER | 0x0006 | Arabic number
C2_COMMONSEPARATOR | 0x0007 | Common numeric separator
Neutral
C2_BLOCKSEPARATOR | 0x0008 | Block separator
C2_SEGMENTSEPARATOR | 0x0009 | Segment separator
C2_WHITESPACE | 0x000A | White space
C2_OTHERNEUTRAL | 0x000B | Other neutrals
Not applicable
C2_NOTAPPLICABLE | 0x0000 | No implicit directionality (for example, control codes)

Ctype 3
These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.
Name
Value
Description
C3_NONSPACING | 0x0001 | Nonspacing mark
C3_DIACRITIC | 0x0002 | Diacritic nonspacing mark
C3_VOWELMARK | 0x0004 | Vowel nonspacing mark
C3_SYMBOL | 0x0008 | Symbol
C3_KATAKANA | 0x0010 | Katakana character
C3_HIRAGANA | 0x0020 | Hiragana character
C3_HALFWIDTH | 0x0040 | Half-width character
C3_FULLWIDTH | 0x0080 | Full-width character
C3_IDEOGRAPH | 0x0100 | Ideographic character
C3_KASHIDA | 0x0200 | Arabic Kashida character
C3_LEXICAL | 0x0400 | Punctuation which is counted as part of the word (Kashida, hyphen, feminine/masculine ordinal indicators, equal sign, and so forth)
C3_ALPHA | 0x8000 | All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable
C3_NOTAPPLICABLE | 0x0000 | Not applicable

See Also

GetLocaleInfo, GetStringTypeEx


GetStringTypeEx

This function returns character-type information for the characters in the specified source string. For each character in the string, GetStringTypeEx sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetStringTypeEx(LCID Locale, DWORD dwInfoType,
LPCTSTR lpSrcStr, int cchSrc, LPWORD lpCharType);

Parameters

Locale
[in] Specifies the locale identifier. This value uniquely defines the ANSI code page to use to translate the string pointed to by lpSrcStr from ANSI to Unicode. The function then analyzes each Unicode character for character type information

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT. | Default user locale.

For Windows CE version 1.0, Locale is ignored.

dwInfoType
[in] Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:
Value
Description
CT_CTYPE1 | Retrieve character type information.
CT_CTYPE2 | Retrieve bidirectional layout information.
CT_CTYPE3 | Retrieve text processing information.

lpSrcStr
[in] Pointer to the string for which character types are requested. If cchSrc is –1, the string is assumed to be null terminated.
cchSrc
[in] Specifies the size, in characters, of the string pointed to by the lpSrcStr parameter. If this count includes a terminating null character, the function returns character type information for the terminating null character. If this value is –1, the string is assumed to be null terminated and the length is calculated automatically.
lpCharType
[out] Pointer to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for each character in the source string. When the function returns, this array contains one word corresponding to each character in the source string.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

Windows CE supports only the Unicode version of GetStringTypeEx, which ignores the Locale parameter.

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1
These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.
Name
Value
Description
C1_UPPER | 0x0001 | Uppercase
C1_LOWER | 0x0002 | Lowercase
C1_DIGIT | 0x0004 | Decimal digits
C1_SPACE | 0x0008 | Space characters
C1_PUNCT | 0x0010 | Punctuation
C1_CNTRL | 0x0020 | Control characters
C1_BLANK | 0x0040 | Blank characters
C1_XDIGIT | 0x0080 | Hexadecimal digits
C1_ALPHA | 0x0100 | Any linguistic character: alphabetic, syllabary, or ideographic

The following character types are either constant or computable from basic types and do not need to be supported by this function.
Type
Description
Alphanumeric | Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable | Graphic characters and blank (all C1_* types except C1_CNTRL)

Ctype 2
These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.
Name
Value
Description
Strong
C2_LEFTTORIGHT | 0x0001 | Left to right
C2_RIGHTTOLEFT | 0x0002 | Right to left
Weak
C2_EUROPENUMBER | 0x0003 | European number, European digit
C2_EUROPESEPARATOR | 0x0004 | European numeric separator
C2_EUROPETERMINATOR | 0x0005 | European numeric terminator
C2_ARABICNUMBER | 0x0006 | Arabic number
C2_COMMONSEPARATOR | 0x0007 | Common numeric separator
Neutral
C2_BLOCKSEPARATOR | 0x0008 | Block separator
C2_SEGMENTSEPARATOR | 0x0009 | Segment separator
C2_WHITESPACE | 0x000A | White space
C2_OTHERNEUTRAL | 0x000B | Other neutrals
Not applicable
C2_NOTAPPLICABLE | 0x0000 | No implicit directionality (for example, control codes)

Ctype 3
These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.
Name
Value
Description
C3_NONSPACING | 0x0001 | Nonspacing mark
C3_DIACRITIC | 0x0002 | Diacritic nonspacing mark
C3_VOWELMARK | 0x0004 | Vowel nonspacing mark
C3_SYMBOL | 0x0008 | Symbol
C3_KATAKANA | 0x0010 | Katakana character
C3_HIRAGANA | 0x0020 | Hiragana character
C3_HALFWIDTH | 0x0040 | Half-width character
C3_FULLWIDTH | 0x0080 | Full-width character
C3_IDEOGRAPH | 0x0100 | Ideographic character
C3_KASHIDA | 0x0200 | Arabic Kashida character
C3_LEXICAL | 0x0400 | Punctuation which is counted as part of the word (Kashida, hyphen, feminine/masculine ordinal indicators, equal sign, and so forth)
C3_ALPHA | 0x8000 | All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable
C3_NOTAPPLICABLE | 0x0000 | Not applicable

See Also

GetLocaleInfo, GetStringType


GetSystemDefaultLangID

This function retrieves the system default language identifier.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

LANGID GetSystemDefaultLangID(void);

Return Values

The system default language identifier indicates success.

Remarks

For more information about language identifiers, see Locale Identifiers.

See Also

MAKELANGID


GetSystemDefaultLCID

This function retrieves the system default locale identifier.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

LCID GetSystemDefaultLCID(void);

Return Values

The system default locale identifier indicates success.

Remarks

For more information about locale identifiers, see Locale Identifiers.

See Also

GetLocaleInfo, MAKELCID


GetSystemInfo

This function returns information about the current system. A remote application interface (RAPI) version of this function exists, and it is named CeGetSystemInfo.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

VOID GetSystemInfo( LPSYSTEM_INFO lpSystemInfo);

Parameters

lpSystemInfo
Pointer to a SYSTEM_INFO structure to be filled in by this function.

Return Values

None.

See Also

SYSTEM_INFO


GetSystemPowerStatusEx2

This function retrieves battery status information.

Syntax

DWORD GetSystemPowerStatusEx2(
PSYSTEM_POWER_STATUS_EX2 pSystemPowerStatusEx2,
DWORD dwLen, BOOL fUpdate);

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.12 and later

Parameters

pSystemPowerStatusEx2
[out] Pointer to a buffer that receives power status information.
dwLen
[in] Specifies the length of the buffer pointed to by pSystemPowerStatusEx2.
fUpdate
[in] Specify TRUE to get the latest information from the device driver. Specify FALSE to get cached information that may be out-of-date by several seconds.

Return Values

Length of the data returned in the pSystemPowerStatusEx2 buffer indicates success. Zero indicates failure.

See Also

SYSTEM_POWER_STATUS_EX2


GetSystemTime

This function retrieves the current system date and time. The system time is expressed in Coordinated Universal Time (UTC).

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void GetSystemTime( LPSYSTEMTIME lpSystemTime );

Parameters

lpSystemTime
[out] Pointer to a SYSTEMTIME structure to receive the current system date and time.

Return Values

None.

See Also

GetLocalTime, SetSystemTime, SYSTEMTIME


GetThreadContext

This function retrieves the context of the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL GetThreadContext( HANDLE hThread, LPCONTEXT lpContext);

Parameters

hThread
Handle to the thread whose context is to be retrieved.
lpContext
Pointer to the CONTEXT structure that receives the appropriate context of the specified thread. The value of the ContextFlags member of this structure specifies which portions of a thread’s context are retrieved. The CONTEXT structure is highly computer specific. Currently, there are CONTEXT structures defined for Intel, MIPS, Alpha, ARM, SHx, and PowerPC processors. Refer to the header file WINNT.H for definitions of these structures.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The GetThreadContext function is used to retrieve the context of the specified thread. The function allows a selective context to be retrieved based on the value of the ContextFlags member of the CONTEXT structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate when it is not being debugged.

You cannot get a valid context for a running thread. Use the SuspendThread function to suspend the thread before calling GetThreadContext.

See Also

CONTEXT, SetThreadContext, SuspendThread


GetThreadPriority

This function returns the priority value for the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

int GetThreadPriority( HANDLE hThread);

Parameters

hThread
Handle to the thread.

Return Values

The thread’s priority level indicates success. THREAD_PRIORITY_ERROR_RETURN indicates failure. To get extended error information, call GetLastError.

The thread’s priority level is one of the values described in the following list.

THREAD_PRIORITY_TIME_CRITICAL
Indicates 3 points above normal priority.
THREAD_PRIORITY_HIGHEST

Indicates 2 points above normal priority.

THREAD_PRIORITY_ABOVE_NORMAL
Indicates 1 point above normal priority.

THREAD_PRIORITY_NORMAL

Indicates normal priority.

THREAD_PRIORITY_BELOW_NORMAL
Indicates 1 point below normal priority.

THREAD_PRIORITY_LOWEST

Indicates 2 points below normal priority.

THREAD_PRIORITY_ABOVE_IDLE

Indicates 3 points below normal priority.

THREAD_PRIORITY_IDLE
Indicates 4 points below normal priority.

Remarks

Windows CE does not support priority classes. The order in which threads are scheduled is determined only by their thread priorities.

When manipulating priorities, ensure that a high-priority thread does not consume all of the available CPU time. A thread with a priority level of THREAD_PRIORITY_TIME_CRITICAL will execute until it explicitly yields processing to other threads.

If a THREAD_PRIORITY_TIME_CRITICAL priority level running no other THREAD_PRIORITY_TIME_CRITICAL priority level thread will run until the first thread yields. The system will still be able to service IRQs and ISRs but will not be able to schedule any ISTs.

Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level will scheduling of threads at a lower level take place

See Also

SetThreadPriority


GetThreadTimes

This function obtains timing information about a specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.10 and later

Syntax

BOOL GetThreadTimes (HANDLE hThread, LPFILETIME lpCreationTime,
LPFILETIME lpExitTime, LPFILETIME lpKernelTime,
LPFILETIME lpUserTime);

Parameters

hThread
An open handle that specifies the thread whose timing information is sought.
lpCreationTime
Unsupported; set to zero.
lpExitTime
Unsupported; set to zero.
lpKernelTime
Unsupported; set to zero.
lpUserTime
Pointer to a FILETIME structure that receives the amount of time that the thread has executed in user mode.

The lpUserTime parameter reports the total time a thread has been running. There is no distinction between user and kernel modes. The lpUserTime parameter is no longer valid when the thread exits.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

All times are expressed using FILETIME data structures. Such a structure contains two 32-bit values that combine to form a 64-bit count of 100-nanosecond time units.

Thread creation and exit times are points in time expressed as the amount of time that has elapsed since midnight on January 1, 1601 at Greenwich, England. The Win32 API provides several functions that an application can use to convert such values to more generally useful forms; see Time and Date Functions, and the functions noted in the following See Also section.

Thread kernel mode and user mode times are amounts of time. For example, if a thread has spent one second in kernel mode, this function will fill the FILETIME structure specified by lpKernelTime with a 64-bit value of ten million. That is the number of 100-nanosecond units in one second.


GetTickCount

This function retrieves the number of milliseconds that have elapsed since Windows CE was started.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetTickCount( void );

Return Values

The number of milliseconds that have elapsed since the system was started indicates success.

Remarks

The the resolution of the system timer is based on the OEMs setting. Check with the OEM for details.

The elapsed time is stored as a DWORD value. Therefore, the time will wrap around to zero if the system is run continuously for 49.7 days.

See Also

GetSystemTime, SetSystemTime


GetTimeFormat

This function formats a time as a time string for a specified locale. The function formats either a specified time or the local system time.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

int GetTimeFormat(LCID Locale, DWORD dwFlags,
const SYSTEMTIME *lpTime, LPCTSTR lpFormat, LPTSTR lpTimeStr,
int cchTime);

Parameters

Locale
[in] Specifies the locale for which the time string is to be formatted. If lpFormat is NULL, the function formats the string according to the time format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's time markers).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:
Value
Description
LOCALE_SYSTEM_DEFAULT | Default system locale.
LOCALE_USER_DEFAULT | Default user locale.
LOCALE_NEUTRAL | Default language–neutral locale.

For Windows CE version 1.0, Locale is ignored.

dwFlags
[in] Specifies various function options. You can specify a combination of the following flags:
Value
Description
TIME_NOMINUTESORSECONDS | Do not use minutes or seconds.
TIME_NOSECONDS | Do not use seconds.
TIME_NOTIMEMARKER | Do not use a time marker.
TIME_FORCE24HOURFORMAT | Always use a 24-hour time format.
LOCALE_NOUSEROVERRIDE | If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default time format. This flag cannot be set if lpFormat is non-NULL.

lpTime
[in] Pointer to a SYSTEMTIME structure that contains the time information to be formatted. If this pointer is NULL, the function uses the current local system time.
lpFormat
[in] Pointer to a format picture to use to form the time string. If lpFormat is NULL, the function uses the time format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown (for example, “ss”, not “SS”). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.
Value
Description
h | Hours with no leading zero for single-digit hours; 12-hour clock
hh | Hours with leading zero for single-digit hours; 12-hour clock
H | Hours with no leading zero for single-digit hours; 24-hour clock
HH | Hours with leading zero for single-digit hours; 24-hour clock
m | Minutes with no leading zero for single-digit minutes
mm | Minutes with leading zero for single-digit minutes
s | Seconds with no leading zero for single-digit seconds
ss | Seconds with leading zero for single-digit seconds
t | One character time marker string, such as A or P
tt | Multicharacter time marker string, such as AM or PM

For example, to get the time string

“11:29:40 PM”

use the following picture string:

“hh':'mm':'ss tt”

lpTimeStr
[out] Pointer to a buffer that receives the formatted time string.
cchTime
[in] Specifies the size, in characters, of the lpTimeStr buffer. If cchTime is zero, the function returns the number of characters required to hold the formatted time string, and the buffer pointed to by lpTimeStr is not used.

Return Values

The number of characters written to the buffer pointed to by lpTimeStr indicates success. If the cchTime parameter is zero, the number of characters required to hold the formatted time string indicates success. The count includes the terminating null. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker based on the specified locale identifier. Examples of time markers are “AM” and “PM” for US English.

The time values in the SYSTEMTIME structure pointed to by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the date portions of the SYSTEMTIME structure pointed to by lpTime: wYear, wMonth, wDayOfWeek, and wDay.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separator(s) preceding the minutes and/or seconds element(s).

If TIME_NOTIMEMARKER is specified, the function removes the separator(s) preceding and following the time marker.

If TIME_FORCE24HOURFORMAT is specified, the function displays any existing time marker, unless the TIME_NOTIMEMARKER flag is also set.

The function does not include milliseconds as part of the formatted time string.

To use the LOCALE_NOUSEROVERRIDE flag, lpFormat must be NULL.

No errors are returned for a bad format string. The function simply forms the best time string that it can. If more than two hour, minute, second, or time marker format pictures are passed in, then the function defaults to two. For example, the only time marker pictures that are valid are L”t” and L”tt” .The ‘L’ indicates a string consisting of Unicode 16-bit characters. If L”ttt” is passed in, the function assumes L”tt”.

See Also

GetDateFormat, SYSTEMTIME


GetTimeZoneInformation

This function retrieves the current time-zone parameters. These parameters control the translations between Coordinated Universal Time (UTC) and local time.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD GetTimeZoneInformation(
LPTIME_ZONE_INFORMATION lpTimeZoneInformation );

Parameters

lpTimeZoneInformation
[out] Pointer to a TIME_ZONE_INFORMATION structure to receive the current time-zone parameters.

Return Values

If the function succeeds, the return value is one of the following values:

TIME_ZONE_ID_UNKNOWN
The system cannot determine the current time zone. This error is also returned if you call the SetTimeZoneInformation function and supply the bias values but no transition dates. This value is returned if daylight savings time is not used in the current time zone, because there are no transition dates.
TIME_ZONE_ID_STANDARD
The system is operating in the range covered by the StandardDate member of the TIME_ZONE_INFORMATION structure.
TIME_ZONE_ID_DAYLIGHT
The system is operating in the range covered by the DaylightDate member of the TIME_ZONE_INFORMATION structure.

If the function fails, the return value is TIME_ZONE_ID_INVALID. To get extended error information, call GetLastError.

Prior to Windows version 2.10, a known problem caused this function to always return TIME_ZONE_ID_UNKNOWN.

Remarks

All translations between UTC time and local time are based on the following formula:

UTC = local time + bias

The bias is the difference, in minutes, between UTC time and local time.

See Also

SetTimeZoneInformation, TIME_ZONE_INFORMATION


GetUserDefaultLangID

This function retrieves the user-default language identifier.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

LANGID GetUserDefaultLangID(void);

Return Values

The user -default language identifier indicates success.

Remarks

Windows CE does not support a separate system LANGID and therefore GetSystemDefaultLangID returns the same value.

For more information about language identifiers, see Locale Identifiers.

See Also

GetSystemDefaultLangID, MAKELANGID


GetUserDefaultLCID

This function retrieves the user-default locale identifier.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

LCID GetUserDefaultLCID(void);

Return Values

The user-default locale identifier indicates success.

Remarks

Windows CE does not support a separate system LCID and therefore GetSystemDefaultLCID returns the same value.

For more information about locale identifiers, see Locale Identifiers.

See Also

GetLocaleInfo, GetSystemDefaultLCID, MAKELCID


GetVersionEx

This function obtains extended information about the version of the operating system that is currently running. A remote application interface (RAPI) version of this function exists, and it is named CeGetVersionEx

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL GetVersionEx( LPOSVERSIONINFO lpVersionInformation );

Parameters

lpVersionInformation
[out] Pointer to an OSVERSIONINFO data structure that the function fills with operating system version information.

Before calling the GetVersionEx function, set the dwOSVersionInfoSize member of the OSVERSIONINFO data structure to sizeof(OSVERSIONINFO).

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. The function fails if you specify an invalid value for the dwOSVersionInfoSize member of the OSVERSIONINFO.

Remarks

When using the GetVersionEx function to determine whether your application is running on a particular version of the operating system, check for version numbers that are greater than or equal to the desired version numbers. This ensures that the test succeeds for later versions of the operating system. For example, if your application requires Windows 98, use the following test:

GetVersionEx (&osvi);
bIsWindows98orLater =
   (osvi.dwPlatformId == VER_PLATFORM_WIN32_WINDOWS) &&
   ( (osvi.dwMajorVersion > 4) ||
   ( (osvi.dwMajorVersion == 4) && (osvi.dwMinorVersion > 0) ) );

Identifying the current operating system is usually not the best way to determine whether a particular operating system feature is present. This is because the operating system may have had new features added in a redistributable DLL. Rather than using GetVersionEx to determine the operating system platform or version number, test for the presence of the feature itself.

To determine the best way to test for a feature, refer to the documentation for the feature of interest. The following list discusses some common techniques for feature detection:

  • You can test for the presence of the functions associated with a feature. To test for the presence of a function in a system DLL, call the LoadLibrary function to load the DLL. Then call the GetProcAddress function to determine whether the function of interest is present in the DLL. Use the pointer returned by GetProcAddress to call the function. Note that even if the function is present, it may be a stub that just returns an error code such as ERROR_CALL_NOT_IMPLEMENTED.
  • You can determine the presence of some features by using the GetSystemMetrics function. For example, you can detect multiple display monitors by calling GetSystemMetrics(SM_CMONITORS).
  • There are several versions of the redistributable DLLs that implement shell and common control features.

The value of the dwPlatformID member of the OSVERSIONINFO structure will be VER_PLATFORM_WIN32_CE.

When writing applications for Windows CE 2.01 running on a Japanese H/PC, be aware that the toolbar indicates that the version is 2.0.

For the Auto PC version 1.0, GetLastError returns of the following error values:

ERROR_INVALID_HANDLE
The supplied pointer is NULL.
ERROR_INVALID_DATA

The structure is not properly initialized; the size is set incorrectly.

See Also

OSVERSIONINFO


GlobalMemoryStatus

This function gets information on the physical and virtual memory of the system.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void GlobalMemoryStatus( LPMEMORYSTATUS lpmst );

Parameters

lpBuffer
[out] Pointer to a MEMORYSTATUS structure. The GlobalMemoryStatus function stores information about current memory availability into this structure.

Return Values

None.

Remarks

You can use the GlobalMemoryStatus function to determine how much memory your application can allocate without severely impacting other applications.

The information returned by the GlobalMemoryStatus function is volatile. There is no guarantee that two sequential calls to this function will return the same information.


Heap32First

This function retrieves information about the first block of a heap that has been allocated by a process.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Heap32First( HANDLE hSnapshot,
LPHEAPENTRY32 lphe, DWORD th32ProcessID, DWORD th32HeapID);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function. This parameter is specific to Windows CE.
lphe
Pointer to a HEAPENTRY32 structure.
th32ProcessID
Identifier of the process context that owns the heap.
th32HeapID
Identifier of the heap to enumerate.

Return Value

TRUE indicates that information for the first heap block has been copied to the buffer. FALSE indicates success. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that the heap is invalid or empty.

Remarks

The calling application must set the dwSize member of HEAPENTRY32 to the size, in bytes, of the structure. Heap32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To access subsequent blocks of the same heap, use the Heap32Next function.


Heap32ListFirst

This function retrieves information about the first heap that has been allocated by a specified process.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Heap32ListFirst( HANDLE hSnapshot,
LPHEAPLIST32 lphl);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lphl
Pointer to a HEAPLIST32 structure.

Return Value

TRUE indicates that the first entry of the heap list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no heap list exists or the snapshot does not contain heap list information.

Remarks

The calling application must set the dwSize member of HEAPLIST32 to the size, in bytes, of the structure. Heap32ListFirst changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other heaps in the heap list, use the Heap32ListNext function.


Heap32ListNext

This function retrieves information about the next heap that has been allocated by a process.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Heap32ListNext( HANDLE hSnapshot,
LPHEAPLIST32 lphl);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lphl
Long pointer to a HEAPLIST32 structure.

Return Value

TRUE indicates that the next entry of the heap list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no more heap list entries exist.

Remarks

The calling application must set the dwSize member of HEAPLIST32 to the size, in bytes, of the structure. Heap32ListFirst changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about the first heap in a heap list, use the Heap32ListFirst function.


Heap32Next

This function retrieves information about the next block of a heap that has been allocated by a process.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Heap32Next( HANDLE hSnapshot,
LPHEAPENTRY32 lphe);

Parameters

hSnapShot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function. This parameter is specific to Windows CE.
lphe
Long pointer to a HEAPENTRY32 structure.

Return Value

TRUE indicates that information about the next block in the heap has been copied to the buffer. FALSE indicates failure. The GetLastError function returns ERROR_NO_MORE_FILES when no more objects in the heap exist and ERROR_INVALID_DATA if the heap appears to be corrupt or is modified during the walk in such a way that Heap32Next cannot continue.

Remarks

To retrieve information for the first block of a heap, use the Heap32First function.


HeapAlloc

This function allocates a block of memory from a heap. The allocated memory is not movable.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPVOID HeapAlloc(HANDLE hHeap, DWORD dwFlags,
DWORD dwBytes);

Parameters

hHeap
[in] Handle to the heap from which the memory will be allocated. This parameter is a handle returned by the HeapCreate or GetProcessHeap function.
dwFlags
[in] Specifies several controllable aspects of heap allocation. Specifying any of these flags will override the corresponding flag specified when the heap was created with HeapCreate. You can specify one or more of the following flags:
Value
Description
HEAP_NO_SERIALIZE | Specifies that mutual exclusion will not be used while the HeapAlloc function is accessing the heap.
This flag should not be specified when accessing the process heap. The system may create additional threads within the application’s process that simultaneously access the process heap.
HEAP_ZERO_MEMORY | Specifies that the allocated memory will be initialized to zero. Otherwise, the memory is not initialized to zero.

dwBytes
[in] Specifies the number of bytes to be allocated.

If the heap specified by the hHeap parameter is a “nongrowable” heap, dwBytes must be less than 0x7FFF8. You create a nongrowable heap by calling the HeapCreate function with a nonzero value.

Return Values

A pointer to the allocated memory block indicates success. NULL indicates failure.

If the function fails, it does not call SetLastError. An application cannot call GetLastError for extended error information.

Remarks

If HeapAlloc succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the allocated block, use the HeapSize function.

To free a block of memory allocated by HeapAlloc, use the HeapFree function.

Memory allocated by HeapAlloc is not movable. Since the memory is not movable, it is possible for the heap to become fragmented.

Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

  • The process has only one thread.
  • The process has multiple threads, but only one thread calls the heap functions for a specific heap.
  • The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


HeapCreate

This function creates a heap object that is private to the calling process. This reserves a contiguous block of the process's virtual address space and allocates physical storage for a specified initial portion of this block.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE HeapCreate(DWORD flOptions, DWORD dwInitialSize,
DWORD dwMaximumSize);

Parameters

flOptions
[in] Specifies optional attributes for the new heap. These flags will affect subsequent access to the new heap through calls to the heap functions (HeapAlloc, HeapFree, HeapReAlloc, and HeapSize). You can specify the following flag:
Value
Description
HEAP_NO_SERIALIZE Specifies that mutual exclusion will not be used when the heap functions allocate and free memory from this heap. The default, when the HEAP_NO_SERIALIZE flag is not specified, is to serialize access to the heap. Serialization of heap access allows two or more threads to simultaneously allocate and free memory from the same heap.

dwInitialSize
[in] Specifies the initial size, in bytes, of the heap. This value determines the initial amount of physical storage that is allocated for the heap. The value is rounded up to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.
dwMaximumSize
Unsupported.

Return Values

A handle to the newly created heap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The HeapCreate function creates a private heap object from which the calling process can allocate memory blocks by using the HeapAlloc function. The initial size determines the number of committed pages that are initially allocated for the heap. These pages create a block in the process’s virtual address space into which the heap can grow. If requests by HeapAlloc exceed the current size of committed pages, additional pages are automatically committed from this reserved space, assuming that the physical storage is available.

The memory of a private heap object is accessible only to the process that created it. If a dynamic-link library (DLL) creates a private heap, the heap is created in the address space of the process that called the DLL, and it is accessible only to that process.

The system uses memory from the private heap to store heap support structures, so not all of the specified heap size is available to the process. For example, if the HeapAlloc function requests 64 kilobytes (K) from a heap with a maximum size of 64K, the request may fail because of system overhead.

If the HEAP_NO_SERIALIZE flag is not specified (the simple default), the heap will serialize access within the calling process. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap.

Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

  • The process has only one thread.
  • The process has multiple threads, but only one thread calls the heap functions for a specific heap.
  • The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

HeapAlloc, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


HeapDestroy

This function destroys the specified heap object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL HeapDestroy(HANDLE hHeap);

Parameters

hHeap
[in] Handle to the heap to be destroyed. This parameter should be a heap handle returned by the HeapCreate function. Do not use the handle to the process heap returned by the GetProcessHeap function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Processes can call HeapDestroy without first calling the HeapFree function to free memory allocated from the heap.

See Also

HeapAlloc, HeapCreate, HeapFree, HeapReAlloc, HeapSize


HeapFree

This function frees a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL HeapFree(HANDLE hHeap, DWORD dwFlags, LPVOID lpMem);

Parameters

hHeap
[in] Handle to the heap whose memory block the function frees. This parameter is a handle returned by the HeapCreate or GetProcessHeap function.
dwFlags
[in] Specifies several controllable aspects of freeing a memory block. Only one flag is currently defined; however, all other flag values are reserved for future use. Specifying this flag will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function:
Value
Description
HEAP_NO_SERIALIZE Specifies that mutual exclusion will not be used while HeapFree is accessing the heap.
This flag should not be specified when accessing the process heap. The system may create additional threads within the application’s process that simultaneously access the process heap.

lpMem
[in] Pointer to the memory block to free. This pointer is returned by the HeapAlloc or HeapReAlloc function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

  • The process has only one thread.
  • The process has multiple threads, but only one thread calls the heap functions for a specific heap.
  • The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapReAlloc, HeapSize


HeapReAlloc

This function reallocates a block of memory from a heap. The allocated memory is not movable.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPVOID HeapReAlloc(HANDLE hHeap, DWORD dwFlags,
LPVOID lpMem, DWORD dwBytes);

Parameters

hHeap
[in] Heap from which the memory will be reallocated. This is a handle returned by the HeapCreate or GetProcessHeap function.
dwFlags
[in] Specifies several controllable aspects of heap reallocation. Specifying any of these flags overrides the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function. You can specify one or more of the following flags:
Value
Description
HEAP_NO_SERIALIZE | Specifies that mutual exclusion is not used while HeapReAlloc is accessing the heap.
This flag should not be specified when accessing the process heap. The system may create additional threads within the application’s process that simultaneously access the process heap.
HEAP_REALLOC_IN_PLACE_ONLY | Specifies that there can be no movement when reallocating a memory block to a larger size. If this flag is not specified and the reallocation request is for a larger size, the function may move the block to a new location. If this flag is specified and the block cannot be enlarged without moving, the function fails, leaving the original memory block unchanged.
HEAP_ZERO_MEMORY | If the reallocation request is for a larger size, this flag specifies that the additional region of memory beyond the original size be initialized to zero. The contents of the memory block up to its original size are unaffected.

lpMem
[in] Pointer to the block of memory that the function reallocates. This pointer is returned by an earlier call to the HeapAlloc or HeapReAlloc function.
dwBytes
[in] Specifies the new size of the memory block, in bytes. A memory block’s size can be increased or decreased by using this function.

Return Values

If the function fails, it calls SetLastError. An application can call GetLastError for extended error information.

Remarks

If HeapReAlloc succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the reallocated block, use the HeapSize function.

If HeapReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid.

To free a block of memory allocated by HeapReAlloc, use the HeapFree function.

Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

  • The process has only one thread.
  • The process has multiple threads, but only one thread calls the heap functions for a specific heap.
  • The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapSize


HeapSize

This function returns the size, in bytes, of a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD HeapSize( HANDLE hHeap, DWORD dwFlags, LPCVOID lpMem);

Parameters

hHeap
[in] Handle to the heap in which the memory block resides. This handle is returned by the HeapCreate or GetProcessHeap function.
dwFlags
[in] Specifies several controllable aspects of accessing the memory block. Only one flag is currently defined; however, all other flag values are reserved for future use. Specifying this flag will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function:
Value
Description
HEAP_NO_SERIALIZE Specifies that mutual exclusion will not be used while HeapSize is accessing the heap.
This flag should not be specified when accessing the process heap. The system may create additional threads within the application’s process that simultaneously access the process heap.

lpmem
[in] Pointer to the memory block whose size the function will obtain. This is a pointer returned by the HeapAlloc or HeapReAlloc function.

Return Values

The size, in bytes, of the allocated memory block indicates success. 0xFFFFFFFF indicates failure. The function does not call SetLastError. An application cannot call GetLastError for extended error information.

Remarks

Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

  • The process has only one thread.
  • The process has multiple threads, but only one thread calls the heap functions for a specific heap.
  • The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc


InflateRect

This function increases or decreases the width and height of the specified rectangle. InflateRect adds dx units to the left and right ends of the rectangle and dy units to the top and bottom. The dx and dy parameters are signed values; positive values increase the width and height, and negative values decrease them.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL InflateRect(LPRECT lprc, int dx, int dy);

Parameters

lprc
Long pointer to the RECT structure that increases or decreases in size.
dx
Specifies the amount to increase or decrease the rectangle width. This parameter must be negative to decrease the width.
dy
Specifies the amount to increase or decrease the rectangle height. This parameter must be negative to decrease the height.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

See Also

IntersectRect, OffsetRect, RECT, UnionRect, InsetRect


InitializeCriticalSection

This function initializes a critical section object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void InitializeCriticalSection( LPCRITICAL_SECTION lpCriticalSection );

Parameters

lpCriticalSection
[in] Pointer to the critical section object.

Return Values

None.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. There is no guarantee about the order in which threads will obtain ownership of the critical section, however, the system will be fair to all threads.

The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

Once a critical section object has been initialized, the threads of the process can specify the object in the EnterCriticalSection or LeaveCriticalSection function to provide mutually exclusive access to a shared resource. For similar synchronization between the threads of different processes, use a mutex object.

A critical section object cannot be moved or copied. The process must also not modify the object, but must treat it as logically opaque. Use only the critical section functions provided by the Win32 API to manage critical section objects.

In low memory situations, InitializeCriticalSection can raise a STATUS_NO_MEMORY exception.

See Also

DeleteCriticalSection, EnterCriticalSection, LeaveCriticalSection


InterlockedDecrement

This function both decrements (decreases by one) the value of the specified 32-bit variable and checks the resulting value. InterlockedDecrement prevents more than one thread from using the InterlockedDecrement or InterlockedIncrement function to access the same variable simultaneously.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LONG InterlockedDecrement( LPLONG lpAddend );

Parameters

lpAddend
[in] Pointer to the 32-bit variable to decrement.

Return Values

The return value is the resulting decremented value.

Remarks

The functions InterlockedDecrement, InterlockedCompareExchange, InterlockedExchange, InterlockedExchangeAdd, and InterlockedIncrement provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The variable pointed to by the lpAddend parameter must be aligned on a 32-bit boundary.

See Also

InterlockedExchange, InterlockedIncrement


InterlockedExchange

This function atomically exchanges a pair of 32-bit values.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LONG InterlockedExchange( LPLONG Target, LONG Value );

Parameters

Target
[in] Pointer to the LONG value to exchange. The function sets this LONG value to Value, and returns its prior value.
Value
[in] Specifies a new value for the LONG value pointed to by Target.

Return Values

The prior value of the LONG value pointed to by Target indicates success.

Remarks

The functions InterlockedExchange, InterlockedCompareExchange, InterlockedDecrement, InterlockedExchangeAdd, and InterlockedIncrement provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The variable pointed to by the Target parameter must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedDecrement, InterlockedIncrement


InterlockedIncrement

This function both increments (increases by one) the value of the specified 32-bit variable and checks the resulting value. InterlockedIncrement prevents more than one thread from using the InterlockedDecrement or InterlockedIncrement function to access the same variable simultaneously.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LONG InterlockedIncrement( LPLONG lpAddend );

Parameters

lpAddend
[in] Pointer to the LONG variable to increment.

Return Values

The return value is the resulting incremented value.

Remarks

The functions InterlockedIncrement, InterlockedCompareExchange, InterlockedDecrement, InterlockedExchange, and InterlockedExchangeAdd provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. The threads of different processes can use this mechanism if the variable is in shared memory.

The variable pointed to by the lpAddend parameter must be aligned on a 32-bit boundary.

See Also

InterlockedDecrement, InterlockedExchange


InterlockedTestExchange

This function is an interlocked function that performs a conditional setting of a variable.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LONG WINAPI InterlockedTestExchange(LPLONG Target, LONG OldValue, LONG NewValue );

Parameters

Target
[in] Pointer to the LONG variable to check and set.
OldValue
[in] Specifies the value to check against.
NewValue
[in] Specifies the value to set to conditionally.

Return Values

The value pointed to by Target at the time of the call—that is, the old value—indicates success.

Remarks

The InterlockedTestExchange function is an interlocked function—in other words, it can be considered atomic. It checks to see if the value pointed to by Target is equal to OldValue. If so, it sets Target to NewValue. Since InterlockedTestExchange returns the “old” value pointed to by Target, if the return value is OldValue, then InterlockedTestExchange succeeded and set the value pointed to by Target to NewValue. Otherwise, it failed.


IntersectRect

This function calculates the intersection of two source rectangles and places the coordinates of the intersection rectangle into the destination rectangle. If the source rectangles do not intersect, an empty rectangle (in which all coordinates are set to zero) is placed into the destination rectangle.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IntersectRect(LPRECT lprcDst, const RECT *lprcSrc1,
const RECT *lprcSrc2);

Parameters

lprcDst
Long pointer to the RECT structure that is to receive the intersection of the rectangles pointed to by the lprcSrc1 and lprcSrc2 parameters.
lprcSrc1
Long pointer to the RECT structure that contains the first source rectangle.
lprcSrc2
Long pointer to the RECT structure that contains the second source rectangle.

Return Values

Nonzero indicates that the rectangles intersect. Zero indicates that the rectangles do not intersect.

Windows NT: To get extended error information, call GetLastError.

See Also

InflateRect, OffsetRect, RECT, UnionRect


IsBadCodePtr

This function determines whether the calling process has read access to the memory at the specified address.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsBadCodePtr( FARPROC lpfn );

Parameters

lpfn
Pointer to an address in memory.

Return Values

Zero indicates that the calling process has read access to the specified memory. Nonzero indicates that the calling process does not have read access to the specified memory. To get extended error information, call GetLastError.

If the application is compiled as a debugging version, and the process does not have read access to all bytes in the specified memory range, the function causes an assertion and breaks into the debugger. Leaving the debugger, the function continues as usual, and returns a nonzero value This behavior is by design, as a debugging aid.

Remarks

IsBadCodePtr checks the read access only at the specified address and does not guarantee read access to a range of memory.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadReadPtr, IsBadWritePtr, EXCEPTION_POINTERS, EXCEPTION_RECORD


IsBadReadPtr

This function verifies that the calling process has read access to the specified range of memory.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsBadReadPtr( const void *lp, UINT ucb);

Parameters

lp
Pointer to the first byte of the memory block.
ucb
Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is zero.

Return Values

Zero indicates that the calling process has read access to all bytes in the specified memory range. Nonzero indicates that the calling process does not have read access to all bytes in the specified memory range.

If the application is compiled as a debugging version, and the process does not have read access to all bytes in the specified memory range, the function causes an assertion and breaks into the debugger. Leaving the debugger, the function continues as usual, and returns a nonzero value This behavior is by design, as a debugging aid.

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadWritePtr, IsBadCodePtr


IsBadWritePtr

This function verifies that the calling process has write access to the specified range of memory.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsBadWritePtr( LPVOID lp, UINT ucb );

Parameters

lp
Pointer to the first byte of the memory block.
ucb
Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is zero.

Return Values

Zero indicates that the calling process has write access to all bytes in the specified memory range. Nonzero indicates that the calling process does not have write access to all bytes in the specified memory range.

If the application is compiled as a debugging version, and the process does not have write access to all bytes in the specified memory range, the function causes an assertion and breaks into the debugger. Leaving the debugger, the function continues as usual, and returns a nonzero value This behavior is by design, as a debugging aid.

Remarks

If the calling process has write access to some, but not all, of the bytes in the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process’s access to the memory being tested. Even when the function indicates that the process has write access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadReadPtr


IsCharAlpha

This function determines whether a character is an alphabetic character. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsCharAlpha(TCHAR ch);

Parameters

ch
[in] Specifies the character to be tested.

Return Values

Nonzero indicates that the character is alphabetic. Zero indicates that the character is not alphabetic. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of this function.

See Also

IsCharAlphaNumeric


IsCharAlphaNumeric

This function determines whether a character is either an alphabetic or a numeric character. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsCharAlphaNumeric(TCHAR ch);

Parameters

ch
[in] Specifies the character to be tested.

Return Values

Nonzero indicates that the character is alphanumeric. Zero indicates that the character is not alphanumeric. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of this function.

See Also

IsCharAlpha


IsCharLower

This function determines whether a character is lowercase. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsCharLower(TCHAR ch);

Parameters

ch
[in] Specifies the character to be tested.

Return Values

Nonzero indicates that the character is lowercase.

Zero indicates that the character is not lowercase. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of this function.

See Also

IsCharUpper


IsCharUpper

This function determines whether a character is uppercase. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsCharUpper(TCHAR ch);

Parameters

ch
[in] Specifies the character to be tested.

Return Values

Nonzero indicates that the character is uppercase. Zero indicates that the character is not uppercase. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of this function.

See Also

IsCharLower


IsDBCSLeadByte

This function determines whether a character is a lead byte — that is, the first byte of a character in a double-byte character set (DBCS).

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

BOOL IsDBCSLeadByte(BYTE TestChar);

Parameters

TestChar
[in] Specifies the character to be tested.

Return Values

TRUE indicates that the character is a lead byte. FALSE indicates that either the character is not a lead byte or an error was generated. For extended error information, call GetLastError.

Remarks

Lead bytes are unique to double-byte character sets. A lead byte introduces a double-byte character. Lead bytes occupy a specific range of byte values. The IsDBCSLeadByte function uses the ANSI code page to check lead-byte ranges. To specify a different code page, use the IsDBCSLeadByteEx function.

See Also

MultiByteToWideChar


IsDBCSLeadByteEx

This function determines whether a character is a lead byte — that is, the first byte of a character in a double-byte character set (DBCS).

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

BOOL IsDBCSLeadByteEx(UINT CodePage, BYTE TestChar);

Parameters

CodePage
[in] Identifier of the code page to use to check lead-byte ranges. Can be one of the values listed in the Code Page Identifiers in Unicode and character set Constants or one the following predefined values:
Value
Description
0 | Use system default ANSI code page.
CP_ACP | Use system default ANSI code page.
CP_OEMCP | Use system default OEM code page.

TestChar
[in] Character to test.

Return Values

TRUE indicates that the character is a lead byte. FALSE indicates that either the character is not a lead byte or an error was generated. For extended error information, call GetLastError.


IsRectEmpty

This function determines whether the specified rectangle is empty. An empty rectangle is one that has no area; that is, the coordinate of the right side is less than or equal to the coordinate of the left side, or the coordinate of the bottom side is less than or equal to the coordinate of the top side.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsRectEmpty(const RECT *lprc);

Parameters

lprc
Long pointer to a RECT structure that contains the logical coordinates of the rectangle.

Return Values

Nonzero indicates that the rectangle is empty. Zero indicates that the rectangle is not empty. To get extended error information, call GetLastError.

See Also

EqualRect, PtInRect, RECT


IsValidCodePage

This function determines whether a specified code page is valid.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

BOOL IsValidCodePage(UINT CodePage);

Parameters

CodePage
[in] Specifies the code page to check. Each code page is identified by a unique number.

Return Values

Nonzero indicates that the code page is valid. Zero indicates that the code page is not valid. To get extended error information, call GetLastError.

Remarks

A code page is considered valid only if it is installed in the system.

Following are the code-page identifiers:

Identifier
Description
037 | EBCDIC
437 | MS-DOS United States
500 | EBCDIC "500V1"
708 | Arabic (ASMO 708)
709 | Arabic (ASMO 449+, BCON V4)
710 | Arabic (Transparent Arabic)
720 | Arabic (Transparent ASMO)
737 | Greek (formerly 437G)
775 | Baltic
850 | MS-DOS Multilingual (Latin I)
852 | MS-DOS Slavic (Latin II)
855 | IBM Cyrillic (primarily Russian)
857 | IBM Turkish
860 | MS-DOS Portuguese
861 | MS-DOS Icelandic
862 | Hebrew
863 | MS-DOS Canadian-French
864 | Arabic
865 | MS-DOS Nordic
866 | MS-DOS Russian
869 | IBM Modern Greek
874 | Thai
875 | EBCDIC
932 | Japan
936 | Chinese (PRC, Singapore)
949 | Korean
950 | Chinese (Taiwan Region; Hong Kong SAR, PRC)
1026 | EBCDIC
1200 | Unicode (BMP of ISO 10646)
1250 | Windows 3.1 Eastern European
1251 | Windows 3.1 Cyrillic
1252 | Windows 3.1 US (ANSI)
1253 | Windows 3.1 Greek
1254 | Windows 3.1 Turkish
1255 | Hebrew
1256 | Arabic
1257 | Baltic
1361 | Korean (Johab)
10000 | Macintosh Roman
10001 | Macintosh Japanese
10006 | Macintosh Greek I
10007 | Macintosh Cyrillic
10029 | Macintosh Latin 2
10079 | Macintosh Icelandic
10081 | Macintosh Turkish

See Also

GetACP, GetCPInfo, GetOEMCP


IsValidLocale

This function applies a validity test to a locale identifier. The dwFlags parameter determines the nature of the validity test. Currently, the function tests whether a locale identifier is installed or supported on the calling system.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL IsValidLocale(LCID Locale, DWORD dwFlags);

Parameters

Locale
[in] Specifies the locale identifier to be validated. You can use the MAKELCID macro to create a locale identifier.
dwFlags
[in] Specifies the validity test to apply to the locale identifier. This parameter can be one of the following values:
Value
Description
LCID_INSTALLED | Test whether the locale identifier is both supported and installed.
LCID_SUPPORTED | Test whether the locale identifier is supported.

Return Values

Nonzero indicates that the locale identifier passes the specified validity test. Zero indicates that the locale identifier does not pass the specified validity test.

Remarks

If the LCID_INSTALLED flag is specified and this function returns a nonzero value, the locale identifier is both supported and installed on the system.

If the LCID_SUPPORTED flag is specified and this function returns zero, the locale identifier is supported in the release, but not necessarily installed on the system. Windows CE does not support the downloading of code pages to a device.

See Also

GetLocaleInfo


LCMapString

This function maps one character string to another, performing a specified locale-dependent transformation. LCMapString can also be used to generate a sort key for the input string.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

int LCMapString(LCID Locale, DWORD dwMapFlags, LPCTSTR lpSrcStr, int cchSrc, LPTSTR lpDestStr, int cchDest);

Parameters

Locale
[in] Specifies a locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.
dwMapFlags
[in] Specifies the type of transformation to be used during string mapping or sort key generation. An application can specify more than one of these options on a single transformation, although some combinations are invalid. The following mapping options are defined; restrictions are noted following the table:
Value
Description
LCMAP_BYTEREV | Use byte reversal. For example, if you pass in 0x3450 0x4822 the result is 0x5034 0x2248.
LCMAP_FULLWIDTH | Wide characters (where applicable).
LCMAP_HALFWIDTH | Narrow characters (where applicable).
LCMAP_HIRAGANA | Hiragana.
LCMAP_KATAKANA | Katakana.
LCMAP_LOWERCASE | Use lowercase.
LCMAP_SORTKEY | Produce a normalized wide-character sort key.
LCMAP_UPPERCASE | Use uppercase.
NORM_IGNORECASE | Ignore case.
NORM_IGNOREKANATYPE | Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana will compare as equal.
NORM_IGNORENONSPACE | Ignore nonspacing. This flag also removes Japanese accent characters.
NORM_IGNORESYMBOLS | Ignore symbols.
NORM_IGNOREWIDTH | Do not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT | Treat punctuation the same as symbols.

If the LCMAP_SORTKEY flag is not specified, the LCMapString function performs string mapping. In this case the following restrictions apply:

  • LCMAP_LOWERCASE and LCMAP_UPPERCASE are mutually exclusive.
  • LCMAP_HIRAGANA and LCMAP_KATAKANA are mutually exclusive.
  • LCMAP_HALFWIDTH and LCMAP_FULLWIDTH are mutually exclusive.
  • SORT_STRINGSORT, NORM_IGNOREKANATYPE, NORM_IGNOREWIDTH, and NORM_IGNORECASE are not valid.
  • LCMAP_TRADITIONAL_CHINESE and LCMAP_SIMPLIFIED_CHINESE are mutually exclusive.
  • LCMAP_LOWERCASE and LCMAP_UPPERCASE are not valid in combination with any of the following flags: LCMAP_HIRAGANA, LCMAP_KATAKANA, LCMAP_HALFWIDTH, and LCMAP_FULLWIDTH.

    When the LCMAP_SORTKEY flag is specified, the LCMapString function generates a sort key. In this case the following restriction applies:

  • LCMAP_SORTKEY is mutually exclusive with all other LCMAP_* flags, with the sole exception of LCMAP_BYTEREV.
lpSrcStr
[in] Pointer to a source string that the function maps or uses for sort key generation.
cchSrc
[in] Specifies the size, in characters, of the string pointed to by the lpSrcStr parameter.

This count can include the NULL terminator, or not include it. If the NULL terminator is included in the character count, it does not greatly affect the mapping behavior. That is because NULL is considered to be unsortable, and always maps to itself.

A cchSrc value of –1 specifies that the string pointed to by lpSrcStr is null-terminated. If this is the case, and LCMapString is being used in its string-mapping mode, the function calculates the string’s length itself, and null-terminates the mapped string stored into *lpDestStr.

lpDestStr
[out] Long pointer to a buffer into which the function stores the mapped string or sort key.

If LCMAP_SORTKEY is specified, LCMapString stores a sort key into the buffer. The sort key is stored as an array of byte values in the following format:

[all Unicode sort weights] 0x01 [all Diacritic weights] 0x01 [all Case weights] 0x01 [all Special weights] 0x00

Note that the sort key is null-terminated. This is true regardless of the value of cchSrc. Also note that, even if some of the sort weights are absent from the sort key, due to the presence of one or more ignore flags in dwMapFlags, the 0x01 separators and the 0x00 terminator are still present.

cchDest
[in] Specifies the size, in characters, of the buffer pointed to by lpDestStr.

If the function is being used for string mapping, the size is a character count. If space for a NULL terminator is included in cchSrc, then cchDest must also include space for a NULL terminator.

If the function is being used to generate a sort key, the size is a byte count. This byte count must include space for the sort key 0x00 terminator.

If cchDest is zero, the function’s return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, required to hold the mapped string or sort key. In this case, the buffer pointed to by lpDestStr is not used.

Return Values

If the value of cchDest is nonzero, the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer indicates success. This count includes room for a NULL terminator. If the value of cchDest is zero, the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key indicates success. This size includes room for a NULL terminator. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The mapped string is null terminated if the source string is null terminated.

If the LCMAP_HIRAGANA flag is specified to map Katakana characters to Hiragana characters, and LCMAP_FULLWIDTH is not specified, the function only maps full-width characters to Hiragana. In this case, any half-width Katakana characters are placed as-is in the output string, with no mapping to Hiragana. An application must specify LCMAP_FULLWIDTH if it wants half-width Katakana characters mapped to Hiragana.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Even though Windows CE supports only the Unicode version of this function, the output string is only in WCHAR or CHAR format if the string mapping mode of LCMapString is used. If the sort key generation mode is used, specified by LCMAP_SORTKEY, the output is an array of byte values. An application can compare sort keys by using a byte-by-byte comparison.

An application can call the function with the NORM_IGNORENONSPACE and NORM_IGNORESYMBOLS flags set, and all other options flags cleared, in order to simply strip characters from the input string. If this is done with an input string that is not null-terminated, it is possible for LCMapString to return an empty string and not return an error.

The LCMapString function ignores the Arabic Kashida. If an application calls the function to create a sort key for a string that contains an Arabic Kashida, there will be no sort key value for the Kashida.

The function treats the hyphen and apostrophe a bit differently than other punctuation symbols, so that words like coop and co-op stay together in a list. All punctuation symbols other than the hyphen and apostrophe sort before the alphanumeric characters. An application can change this behavior by setting the SORT_STRINGSORT flag. See CompareString for a more detailed discussion of this issue.

When LCMapString is used to generate a sort key, by setting the LC_MAPSORTKEY flag, the sort key stored into *lpDestStr may contain an odd number of bytes. The LCMAP_BYTEREV option only reverses an even number of bytes. If both options are chosen, the last (odd-positioned) byte in the sort key is not reversed. If the terminating 0x00 byte is an odd-positioned byte, then it remains the last byte in the sort key. If the terminating 0x00 byte is an even-positioned byte, it exchanges positions with the byte that precedes it.

See Also

CompareString, FoldString, MAKELCID


LeaveCriticalSection

This function releases ownership of the specified critical section object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void LeaveCriticalSection( LPCRITICAL_SECTION lpCriticalSection );

Parameters

lpCriticalSection
[in] Pointer to the critical section object.

Return Values

None.

Remarks

The threads of a single process can use a critical-section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical-section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

A thread uses the EnterCriticalSection function to acquire ownership of a critical section object. To release its ownership, the thread must call LeaveCriticalSection once for each time that it entered the critical section.

If a thread calls LeaveCriticalSection when it does not have ownership of the specified critical section object, an error occurs that may cause another thread using EnterCriticalSection to wait indefinitely.

Any thread of the process can use the DeleteCriticalSection function to release the system resources that were allocated when the critical section object was initialized. After this function has been called, the critical section object can no longer be used for synchronization.

See Also

DeleteCriticalSection, EnterCriticalSection, InitializeCriticalSection


Load_AlreadyInstalled

This function determines whether the application has already been installed on a device.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

BOOL Load_AlreadyInstalled(LPSTR lpszAppName);

Parameters

lpszAppName
Long pointer to null-terminated string passed in to the Load_AlreadyInstalled function with the name of the application.

Return Values

TRUE indicates that the application is currently installed, or an error occurred. FALSE indicates that the application is not currently installed.

Remarks

The Load_AlreadyInstalled function requires a prior successful call to the Load_Init function.

Load_AlreadyInstalled is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

If an error occurred during this function, it returns TRUE, so that the caller can prevent accidental overwriting.

The application must have been installed using the Application Loader before this function acknowledges that it has been installed. If the application was put on the device using the H/PC, Palm-size PC Explorer drag-and-drop method, Load_AlreadyInstalled will not find the application.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.

See Also

Load_Init


Load_Exit

This function stops the Remote API (RAPI) services initialized by the Load_Init function.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

void Load_Exit(void);

Return Values

None.

Remarks

The Load_Exit function requires a prior successful call to the Load_Init function.

Load_Exit is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Installing and Managing Applications.

See Also

Load_Init, Load


Load_Init

This function initializes the RAPI service.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

LOADERROR Load_Init(void);

Return Values

One of the following values is returned:

LOAD_SUCCESS
Load process completed successfully.
LOAD_FAILED
Generic load failure.

Remarks

The LoadInit function must return successfully before calling the Load function. Call the Load_Exit function to stop the RAPI service.

LoadInit is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.

See Also

Load_Exit


Load_PegCpuType

This function retrieves a character string that contains the name of the CPU type.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

BOOL Load_PegCpuType(LPSTR lpszCpu);

Parameters

lpszCpu
[out] Upon successful completion of the function, pointer to a null-terminated string that contains the type of CPU running the device.

The valid types pointed to by lpszCpu include the following.
Value
Description
Hitachi SH3 | SH3
MIPS R4000 | MIPS

Return Values

TRUE indicates success. FALSE indicates that an error occurred during the retrieval, or an unknown CPU type was found.

Remarks

The Load_PegCpuType function retrieves the CPU type of the last device to connect to the H/PC, Palm-size PC Explorer program. For Load_PegCpuType to return successfully, H/PC, Palm-size PC Explorer must have previously connected to the device at least once. Load_PegCpuType does not distinguish between MIPS R3910 and R4100 chips—it returns R4000 for both. Use Load_PegGetPlatform if this distinction is important.

If the desktop computer is being used with more than one device, you must run Load_Init first. Otherwise Load_PegCpuType will return information about the last device to be connected, not the current one.

Load_PegCpuType is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.


Load_PegFreeSpace

This function returns the amount of memory available for storing applications on a device.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

DWORD Load_PegFreeSpace(void);

Return Values

The number of bytes of unused memory remaining in the object store indicates success.

Remarks

The Load_PegFreeSpace function requires a prior successful call to the Load_Init function.

Load_PegFreeSpace is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.

See Also

Load_Init


Load_PegGetPlatformName

This function retrieves the CPU type of the device currently connected to the desktop computer.

At a Glance

Windows CE versions: 1.0 and 1.01

Syntax

BOOL Load_PegGetPlatformName(LPTSTR pszPlatformName);

Parameters

pszPlatformName
[out] Upon successful return, pointer to a null-terminated string that contains the specific CPU type of the device connected to the desktop computer.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The Load_PegGetPlatformName function is located in Platform.dll, not with the other apploader functions in PpcLoad.dll.

Unlike Load_PegCpuType, this function distinguishes between the MIPS R3910 and R4100 chips.

The Load_PegGetPlatformName function will fail if a device is not currently connected to the desktop computer.

The string pointed to by the pszPlatformName parameter must be user-allocated of size MAX_PATH.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.

See Also

Load_PegCpuType


Load_RegisterFileInfo

This function registers file information with the H/PC, Palm-size PC Explorer.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

LOADERROR Load_RegisterFileInfo(LPCSTR szFileName,
LPCSTR szIconFile, LPCSTR szFileType, int iIcon);

Parameters

szFileName
Null-terminated string that contains the name of the application to be loaded. It must be set prior to calling Load_RegisterFileInfo. The name should include the file extension but should not include the path.
szIconFile
Null-terminated string that contains the name of the file that contains the icon associated with the application being loaded. It must be set prior to calling Load_RegisterFileInfo. The name should include the file extension and the directory path to the file.
szFileType
Not used; set to a non-NULL string.
iIcon
Index to the icon associated with the file being loaded.

Return Values

One of the following values is returned:

LOAD_SUCCESS
Load process completed successfully.
LOAD_INVALID_PARAMETER
Invalid command line parameter.
LOAD_REG_ERROR
Cannot create registry entry.

Remarks

The Load_RegisterFileInfo function requires a prior successful call to the Load_Init function.

Load_RegisterFileInfo is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

To ensure consistency with other icons displayed by the H/PC, Palm-size PC Explorer, icons should follow the two bit per pixel format and incorporate only the following colors: black, white, dark gray and light gray.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.

See Also

Load_Init


Load

This function is the main entry point to download an application from the desktop computer to the target device.

At a Glance

Header file: | Ppcload.h
Windows CE versions: | 1.0 and 1.01

Syntax

LOADERROR Load(HWND hwndParent, LPSTR lpszCmdLine);

Parameters

hwndParent
Handle to the parent window; used for displaying the progress bar.
lpszCmdLine
Long pointer to the buffer that contains the command-line null-terminated string of arguments to be parsed, as follows:

cpu_type application_name install_directory total_bytes_to_copy
user_name user_company load_file

The command-line arguments must be separated from one another by a space character. All of the items except total_bytes_to_copy should be enclosed by double quote (“) characters. The following is a description of the lpszCmdLine command-line parameters:
Value
Description
cpu_type | Type of CPU on the target platform device. This information can be obtained by calling the Load_PegCpuType function.
application_name | Unique name for the application. This information is used to create a key in the Windows CE registry for storing information about the application.
install_directory | Directory on the target platform device where the application will be stored. Directory names must begin with a backslash (\).
total_bytes_to_copy | Total number of bytes to be copied to the device. The application installer uses this number to set the range of the progress bar displayed during the load process.
user_name | Name of the person using the device. Currently, this parameter is unused and should be an empty string, (““).
user_company | Name of the organization where the person using the device works. Currently, this parameter is unused and should be an empty string, (““).
load_file | Path and name of the file on the desktop computer that contains the list of application installation statements to be executed during the load procedure. This file must be of the form “application_name.load”.

Return Values

One of the following values is returned:

LOAD_ALREADY_LOADING
A previous call to the Load function has not yet completed.
LOAD_SUCCESS
Load process completed successfully.
LOAD_OUTOFSTORAGE
Out of memory on the device.
LOAD_CANCELLEDBYUSER
Load canceled by the user.
LOAD_INVALID_PARAMETER
Invalid command line parameter.
LOAD_FAILED
Generic load failure.
LOAD_FAILEDCANTCLEANUP
Load failure; clean-up cannot be performed on the device.
LOAD_DISCONNECTED
Communications disconnected.
LOAD_CANT_CREATE_DIR
Cannot create the destination directory.
LOAD_REG_ERROR
Cannot create the registry entry.
LOAD_ERROR
Unknown error.

Remarks

The Load function requires a prior successful call to the Load_Init function.

Load is exported by Ppcload.dll, which runs on the desktop computer—it is intended to be called from a setup program.

The file name specified by the application_name parameter must match the file name specified by the load_file parameter. For example, if application_name is “MyFile” the file specified by load_file should be “MyFile.load”.

This function is not supported on Windows CE versions 2.0 and later. For more information on installing applications for versions 2.0 and later, see Connection Services.

See Also

Load_Init, Load_Exit


LoadFSD

This function is called by a device driver to load its associated file system driver (FSD).

At A Glance

Header file: | Winbase.h
Versions: | 2.10 and later

Syntax

BOOL LoadFSD (HANDLE hDevice, LPCWSTR lpFSDName);

Parameters

hDevice
Handle to a registered device, obtained when a block device driver is called with the IOCTL DISK_IOCTL_INITIALIZED.
lpFSDName
Pointer to the name of the FSD to load.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

LoadFSD is typically called by a block device driver to load a file system driver. For example, the block device driver Atadisk.dll loads the file system driver Fatfs.dll.


LoadLibrary

This function maps the specified .DLL file into the address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HINSTANCE LoadLibrary( LPCTSTR lpLibFileName );

Parameters

lpLibFileName
Pointer to a null-terminated string that names the .DLL file. The name specified is the filename of the module and is not related to the name stored in the library module itself, as specified by the LIBRARY keyword in the module-definition (.DEF) file.

If the string specifies a path but the file does not exist in the specified directory, the function fails. When specifying a path, be sure to use backslashes (\), not forward slashes (/).

If the string does not specify a path, the function uses a standard search strategy to find the file. See the Remarks for more information.

Return Values

A handle to the module indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

Two different modules cannot have the same filename, given that the extensions are different. These effectively have the same “module” name. For example, if LoadLibrary is made on “Sample.cpl”, the operating system will not load Sample.cpl, but instead will again load Sample.dll. A similar limitation exists for modules with the same name but residing in different directories. For example, if LoadLibrary is called on “\\Windows\Sample.dll”, and then LoadLibrary is called on “\\MyDir\Sample.dll”, “\\Windows\Sample.dll” will simply be reloaded.

A search path to the executable module cannot be specified. Unless the full path to the module is specified, Windows CE versions 2.10 and later search the following path for the module:

  1. The absolute path specified by the lpLibFileName parameter
  2. ROM for statically-linked .DDL files
  3. The .EXE launch directory
  4. The windows (\windows) directory
  5. The root (\) directory
  6. An OEM-dependent directory
  7. The OEM-defined shell (\ppshell) directory—Embedded Toolkit users only

Windows CE versions 1.0 through 2.01 search the following path for the module:

  1. The root directory of the PC Card RAM expansion card, if one exists.
  2. The windows directory (\Windows).
  3. The root directory (\).

Remarks

LoadLibrary can be used to map a DLL module and return a handle that can be used in GetProcAddress to get the address of a DLL function. Do not use LoadLibrary to load or "run" a .exe file.

If the module is a DLL not already mapped for the calling process, the system calls the DLL’s DllMain function with the DLL_PROCESS_ATTACH value. In Windows CE, a DLL is loaded once, but then it is mapped into each processes address space when a process implicitly or explicitly loads the library with the LoadLibrary function. When Windows CE loads a DLL, all path information is ignored when determining if the DLL is already loaded. This means that a DLL with the same name but a different path can only be loaded once. In addition, a module ending with the extension ".CPL" is treated as if the extension if ".DLL".

It is not safe to call LoadLibrary from DllMain.

Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use—for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress.

If no filename extension is specified in the lpLibFileName parameter, the default library extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension.

When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file in the following sequence:

  1. The absolute path specified by the lpLibFileName parameter
  2. ROM for statically-linked .DDL files
  3. The .EXE launch directory
  4. The windows (\windows) directory
  5. The root (\) directory
  6. An OEM-dependent directory
  7. The OEM-defined shell (\ppshell) directory—Embedded Toolkit users only

Windows CE versions 1.0 through 2.01 search the following path for the module:

  1. The root directory of the PC Card RAM expansion card, if one exists.
  2. The windows directory (\Windows).
  3. The root directory (\).

See Also

FindResource, FreeLibrary, GetProcAddress, LoadResource


LoadRegTypeLib

This function uses registry information to load a type library.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT LoadRegTypeLib( REFGUID rguid, unsigned short wVerMajor, unsigned short wVerMinor, LCID lcid, ITypeLib FAR * FAR * pptlib);

Parameters

rguid
Globally unique identifier (GUID) of the library being loaded.
wVerMajor
Major version number of the library being loaded.
wVerMinor
Minor version number of the library being loaded.
lcid
National language code of the library being loaded.
pptlib
On return, pointer to a pointer to the loaded type library.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the arguments is invalid.
TYPE_E_IOERROR | The function could not read from the file.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_UNKNOWNLCID | The passed in LCID could not be found in the OLE-supported DLLs.
TYPE_E_CANTLOADLIBRARY | The type library or DLL could not be loaded.
Other return codes | All FACILITY_STORAGE and system registry errors can also be returned.

Remarks

Only typelib2 type library is supported and loadable from resource.

The function LoadRegTypeLib defers to LoadTypeLib to load the file.

LoadRegTypeLib compares the requested version numbers against those found in the system registry, and takes one of the following actions:

  • If one of the registered libraries exactly matches both the requested major and minor version numbers, then that type library is loaded.
  • If one or more registered type libraries exactly match the requested major version number, and has a greater minor version number than that requested, the one with the greatest minor version number is loaded.
  • If none of the registered type libraries exactly match the requested major version number (or if none of those that do exactly match the major version number also have a minor version number greater than or equal to the requested minor version number), then LoadRegTypeLib returns an error.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


LoadResource

This function loads the specified resource into global memory.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HGLOBAL LoadResource( HMODULE hModule, HRSRC hResInfo);

Parameters

hModule
Handle to the module whose executable file contains the resource. If hModule is NULL, the system loads the resource from the module that was used to create the current process. In Windows CE versions 1.0 and 1.01, setting this parameter to NULL is not supported.
hResInfo
Handle to the resource to be loaded. This handle must be created by using the FindResource function.

Return Values

A handle to the data associated with the resource indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The return type of LoadResource is HGLOBAL for backward compatibility, not because the function returns a handle to a global memory block.

When you are finished using a bitmap, cursor, icon, or menu, you can release its associated memory by calling one of the functions in the following table.

Resource
Release function
Bitmap | DeleteObject
Cursor | DestroyCursor
Icon | DestroyIcon
Menu | DestroyMenu

The system automatically deletes these resources when the process that loaded them terminates, however, calling the appropriate function saves memory and decreases the size of the process's working set.

Accelerator tables are an exception. They remain in memory until the process terminates.

See Also

FindResource, LoadLibrary


LoadTypeLib

This function loads and registers a typelib2 type library.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT LoadTypeLib( OLECHAR FAR * szFile, ITypeLib FAR * FAR * pptlib);

Parameters

szFile
Null-terminated string that contains the name of the file from which LoadTypeLib should attempt to load a type library.
pptlib
On return, pointer to a pointer to the loaded type library.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the arguments is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_INVALIDSTATE | The type library could not be opened.
TYPE_E_INVDATAREAD | The function could not read from the file.
TYPE_E_UNSUPFORMAT | The type library has an older format.
TYPE_E_UNKNOWNLCID | The LCID could not be found in the OLE-supported DLLs.
TYPE_E_CANTLOADLIBRARY | The type library or DLL could not be loaded.
Other return codes | All FACILITY_STORAGE errors can be returned.

Remarks

Windows CE supports only typelib2 type libraries. The LoadTypeLib function loads type libraries only from a resource, that is from DLL or EXE files. It willl not load foreign or stand-alone type library files.

The function LoadTypeLib loads a type library (usually created with MkTypLib) that is stored in the specified file. If szFile specifies only a file name without any path, LoadTypeLib searches for the file and proceeds as follows:

  • If the file is a stand-alone type library implemented by Typelib.dll, the library is loaded directly.
  • If the file is a DLL or an executable file, it is loaded. By default, the type library is extracted from the first resource of type ITypeLib. To load a different type of library resource, append an integer index to szFile. For example:
    LoadTypeLib("C:\MONTANA\EXE\MFA.EXE\3", pptlib)

    This statement loads the type library resource 3 from the file Mfa.exe file.

  • If the file is none of the above, the file name is parsed into a moniker (an object that represents a file-based link source), and then bound to the moniker. This approach allows LoadTypeLib to be used on foreign type libraries, including in-memory type libraries. Foreign type libraries cannot reside in a DLL or an executable file. For more information on monikers, see the OLE Programmer's Reference in the Win32 SDK.

If the type library is already loaded, LoadTypeLib increments the type library’s reference count and returns a pointer to the type library.

For backward compatibility, LoadTypeLib will register the type library if the path is not specified in the szFile parameter. LoadTypeLib will not register the type library if the path of the type library is specified. It is recommended that RegisterTypeLib be used to register a type library.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


LocalAlloc

This function allocates the specified number of bytes from the heap. In the linear Windows CE API environment, there is no difference between the local heap and the global heap.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HLOCAL LocalAlloc(UINT uFlags, UINT uBytes);

Parameters

uFlags
[in] Specifies how to allocate memory. If zero is specified, the default is the LMEM_FIXED flag. This parameter is one of the following flags:
Value
Description
LMEM_FIXED | Allocates fixed memory. The return value is a pointer to the memory object.
LPTR | Combines the LMEM_FIXED and LMEM_ZEROINIT flags.
LMEM_ZEROINIT | Initializes memory contents to zero.

uBytes
[in] Specifies the number of bytes to allocate.

Return Values

A handle to the newly allocated memory object indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If the heap does not contain sufficient free space to satisfy the request, LocalAlloc returns NULL. Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer.

If this function succeeds, it allocates at least the amount requested. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the LocalSize function.

To free the memory, use the LocalFree function.

For Windows CE version 1.0 and 1.01, the local heap for each process cannot exceed 1 MB. However, a process can create multiple heaps using the HeapCreate function and each of these heaps can be up to 1 MB.

See Also

LocalFree, LocalReAlloc, LocalSize


LocalFileTimeToFileTime

This function converts a local file time to a file time based on the Coordinated Universal Time (UTC).

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL LocalFileTimeToFileTime( const FILETIME *lpLocalFileTime, LPFILETIME lpFileTime );

Parameters

lpLocalFileTime
[in] Pointer to a FILETIME structure that specifies the local file time to be converted into a UTC-based file time.
lpFileTime
[out] Pointer to a FILETIME structure to receive the converted UTC-based file time. This parameter cannot be the same as the lpLocalFileTime parameter.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

LocalFileTimeToFileTime uses the current settings for the time zone and daylight saving time. Therefore, if it is daylight saving time, this function will take daylight saving time into account, even if the time you are converting is in standard time.

See Also

FILETIME, FileTimeToLocalFileTime


LocalFree

This function frees the specified local memory object and invalidates its handle.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HLOCAL LocalFree(HLOCAL hMem);

Parameters

hMem
Handle to the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

NULL indicates success. A handle to the local memory object indicates failure. To get extended error information, call GetLastError.

Remarks

If the process tries to examine or modify the memory after it has been freed, heap corruption may occur or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may be generated.

If the hMem parameter is NULL, LocalFree ignores the parameter and returns NULL.

The LocalFree function will free a locked memory object. A locked memory object has a lock count greater than zero.

If an application is running under a debug version of the system, LocalFree issues a message that tells you that a locked object is being freed. If you are debugging the application, LocalFree enters a breakpoint just before freeing a locked object. This allows you to verify the intended behavior, then continue execution.

See Also

LocalAlloc, LocalReAlloc


LocalReAlloc

This function changes the size or the attributes of a specified local memory object. The size can increase or decrease.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

HLOCAL LocalReAlloc(HLOCAL hMem, UINT uBytes, UINT uFlag);

Parameters

hMem
[in] Handle to the local memory object to be reallocated. This handle is returned by either the LocalAlloc or LocalReAlloc function.
uBytes
[in] New size, in bytes, of the memory block. If uFlags specifies the LMEM_MODIFY flag, this parameter is ignored.
uFlags
[in] Flag that specifies how to reallocate the local memory object. If the LMEM_MODIFY flag is specified, this parameter modifies the attributes of the memory object, and the uBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object.

The LMEM_MODIFY flag can be combined with the following flag:
Value
Description
LMEM_MOVEABLE You cannot combine LMEM_MOVEABLE with LMEM_MODIFY to change a fixed memory object into a movable one. If you do so, the function returns an error.

If this parameter does not specify LMEM_MODIFY, this parameter can be any combination of the following flags:
Value
Description
LMEM_MOVEABLE | In Windows CE, this flag enables the memory allocation to move if it can not be allocated in place.
LMEM_ZEROINIT | Causes the additional memory contents to be initialized to zero if the memory object is growing in size.

Return Values

A handle to the reallocated memory object indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If LocalReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid.

If LocalReAlloc reallocates a movable object, the return value is a handle to the memory object.

If LocalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer.

See Also

LocalAlloc, LocalFree


LocalSize

This function returns the current size, in bytes, of the specified local memory object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

UINT LocalSize(HLOCAL hMem);

Parameters

hMem
[in] Handle to the local memory object. This handle is returned by the LocalAlloc or LocalReAlloc function.

Return Values

The size, in bytes, of the specified local memory object indicates success. Zero indicates that the specified handle is not valid or if the object has been discarded. To get extended error information, call GetLastError.

Remarks

The size of a memory block may be larger than the size requested when the memory was allocated.

See Also

LocalAlloc, LocalReAlloc


MailClose

This function releases the handle to the current mail context.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailClose (HANDLE hMail);

Parameters

hMail
Handle to the mail context to be released. This handle is created by the MailOpen function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

See Also

MailOpen


MailDelete

This function deletes a mail entry from the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailDelete (HANDLE hMail, MailMsg* pmm);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the message to be deleted from the message store. The mail entry deleted is based on the value of the oid member of the structure when this function is called.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

If the entry cannot be found in the message store, the MailDelete function will fail.

See Also

MailGet, MailOpen, MailPut, MailUpdate, MailMsg


MailDeleteAttachment

This function deletes a mail attachment.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

BOOL MailDeleteAttachment (HANDLE hMail, MailMsg * pmm,
MailAtt * pma, BOOL fFullDelete);

Parameters

hMail
Handle to the current mail context. This handle is created by the MailOpen function.
pmm
Pointer to the mail message from which the attachment is to be deleted.
pma
Pointer to the mail attachment to be deleted.
fFullDelete
Boolean that is set to TRUE to delete the entire attachment. Otherwise, the file is deleted, but the header remains.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.


MailError

This function retrieves the error condition set by the last called mail function.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

int MailError (HANDLE hMail);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.

Return Values

The value of the last error code as an integer indicates success.

Remarks

Each call to a mail function sets an error code. The MailError function retrieves the code and returns it as an integer. Negative values indicate warnings, positive values indicate errors, and zero indicates MailError completed successfully. To ensure the correct error value is captured, call MailError immediately after the transport function call.

See Also

MailErrorMsg


MailErrorMsg

This function retrieves the last occurrence of a mail error condition, fills a text string with a description of the error, and sets a pointer to the line number where the error occurred.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

int MailErrorMsg (HANDLE hMail , LPWSTR szBuffer, int iBuffLen,
int* piSrcLine);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
szBuffer
Pointer to a wide character string array that contains a description of the error condition issued by the last called mail function.
iBufferLen
Length, in characters, of the string array receiving the error description.
piSrcLine
Pointer to an integer that contains the line number where the error occurred. If no errors are encountered, the value pointed to by this parameter is set to NULL.

Return Values

The value of the last error code as an integer indicates success.

Remarks

The MailErrorMsg function operates with the same behavior as the MailError function with the exception of the additional information it provides.

See Also

MailError


MailFirst

This function retrieves the first of a specified type of message from a folder in the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailFirst (HANDLE hMail, MailMsg* pmm);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the flags determining which folder the message is in, what type of message it is, and how much of the message to retrieve. The mail flag value in the dwFlags member of the structure is a combination of folder, status, and message flags. The folder flag determines which folder the entry will be retrieved from. One folder flag can be combined with any number of status flags and message flags. The status flags determine what type of message to retrieve and the message flags determine how much of the message is returned.

When MailFirst returns, this structure contains the message retrieved from the message store. Two of the message flags determine how much of the message to retrieve. If MAIL_GET_FLAGS is set, only the flags and the object identifier are returned. Using this option does not require any memory to be allocated for the message. If the MAIL_GET_BODY flag is set, the entire message is loaded into memory. This requires the system to allocate memory from the global heap. If neither of these flags is set, all of the message except the body is retrieved. Memory for this option is allocated from the private heap. To free memory allocated by this function, use the MailFree function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

The MailFirst function obtains the information and fills a MailMsg structure variable with the values retrieved from the message store. Changing the values in MailMsg does not affect the message store until it is reinserted by a call to the MailUpdate function.

See Also

MailFree, MailGet, MailNext, MailUpdate, MailMsg


MailFree

This function returns storage space back to the system from a previous MailFirst, MailGet, or MailNext function call.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailFree (MailMsg* pmm);

Parameters

pmm
Pointer to the MailMsg structure being freed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

The message flags set (in the dwFlags member of MailMsg) before a call to retrieve a message from the message store determine whether the MailFree function needs to allocate memory.

See Also

MailFirst, MailGet, MailNext, MailMsg


MailGet

This function retrieves a mail entry from the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailGet (HANDLE hMail, MailMsg* pmm);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the object identifier of the message to be retrieved and the flags that determine how much of the message will be retrieved.

When MailGet returns, this structure contains the message retrieved from the message store. Two of the message flags determine how much of the message to retrieve. If MAIL_GET_FLAGS is set, only the flags and the object identifier are returned. Using this option does not require any memory to be allocated for the message. If the MAIL_GET_BODY flag is set, the entire message is loaded into memory. This requires the system to allocate memory from the global heap. If neither of these flags is set, all of the message except the body (that is, the header) is retrieved. Memory for this option is allocated from the private heap. To free memory allocated by this function, use the MailFree function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

The entry retrieved is based on the value of the oid member of the MailMsg structure when the MailGet function is called.

Changing the values of the MailMsg variable does not affect the message store until the message is reinserted by calling the MailUpdate function.

For more information about mail flags, see MailMsg.

See Also

MailFree, MailPut, MailUpdate, MailMsg


MailGetAttachment

This function retrieves an attachment to a mail message.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

int MailGetAttachment (HANDLE hMail, MailMsg * pmm, MailAtt * pma);

Parameters

hMail
Handle to the current mail context. This handle is created by the MailOpen function.
pmm
Pointer to the mail message to which the attachment belongs.
pma
Pointer to the mail attachment being requested from the message. The caller must specify the uiAttachmentNumber member to identify the attachment for retrieval. If pma is NULL, the function returns the number of attachments to the message.

Return Values

The number of the retrieved attachment—if one was specified—or the total count of attachments—if none was specified—indicates success. A value of –1 indicates an error.


MailGetField

This function sets a pointer to a specified field in the header string.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

LPWSTR MailGetField (MailMsg* pmm, LPWSTR szName,
BOOL fGetName);

Parameters

pmm
Pointer to the mail message that contains the header being searched.
szName
Null-terminated string that contains the name field that is searched for in the message header (for example, “To”, “From”, “Cc”, “Subject”). The process of searching the header for a match with the field name is not case-sensitive. Therefore, this parameter can be any combination of uppercase and lowercase letters.
fGetName
Boolean that specifies which field of the entry is retrieved. If it set to TRUE, the return value points to the name field. If it is set to FALSE, the return value points to the value field—that is, the field that follows the name field.

Return Values

A pointer to the specified field, as specified by the fGetName parameter, indicates success.

Remarks

The MailGetField function searches the header (that is, the pwcHeaders member) of the MailMsg structure in memory. Before calling MailGetField, the message must be retrieved from the message store by calling MailGet, MailFirst, or MailNext.

The pwcHeaders member of the MailMsg structure points to the message’s header string. The header consists of entries made up of two fields: a name, and an associated value. The name fields are separated from the value fields by a NULL character, and the entries are separated from each other by a NULL character. The header string is terminated with two consecutive NULL characters.

See Also

MailHeaderLen, MailSetField, MailGet, MailFirst, MailNext


MailGetFolderId

This function retrieves the identification number of a mail folder from the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailGetFolderId (HANDLE hMail, BYTE* pbId, LPWSTR szName);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pbId
If the folder name pointed to by szName exists in the message store, the value of this parameter is set to the identification number associated with the name.
szName
Null-terminated string that contains the name of the mail folder being searched.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

See Also

MailGetFolderName


MailGetFolderName

This function retrieves the name of a mail folder from the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailGetFolderName (HANDLE hMail, int* piId, int* piLen LPWSTR szName);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
piId
Pointer to the identification number that specifies the mail folder. The identifier, a unique integer from zero to 255, is set by the MailPutFolder function.

After calling MailGetFolderName, if the folder specified by szName cannot be found, the value pointed to by piId is the identifier of the next folder found. If no folder can be found, then piId points to a negative value.

piLen
Pointer to the length, in characters, of the szName buffer parameter. If the string is longer than (piLen - 1), it is truncated.

After calling MailGetFolderName, the value pointed to by piLen is the actual number of characters needed for the string being passed back to szName plus a Terminating null character character.

szName
Pointer to the buffer that receives the name of the mail folder that corresponds with the specified identification number.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

See Also

MailPutFolder, MailGetFolderId


MailGetSort

This function retrieves the information about the current sort order for the specified mail handle.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

BOOL MailSetSort (HANDLE hMail, PMAILSORTINFO pInfo);

Parameters

hMail
Handle to the open mail context as returned by the MailOpen function.
pInfo
Receives the sort information.

Return Values

TRUE indicates success. FALSE indicates that the mail handle is invalid.

Remarks

Before calling the MailGetSort function, call MailFirst to update the number of applicable messages. To get extended error information, call MailError or MailErrorMsg.


MailGetSvcId

This function retrieves the object identifier of a mail entry from the message store based on the value of the service identifier.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailGetSvcId (HANDLE hMail, MailMsg* pmm);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the service name and identifier being passed in when calling MailGetSvcId. After calling MailGetSvcId, the object identifier (the oid member) and associated flags (the dwFlags member) are passed back in this structure when MailGetSvcId completes successfully.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

See Also

MailMsg


MailHeaderLen

This function computes the number of characters in a header string.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

DWORD MailHeaderLen (MailMsg* pmm);

Parameters

pmm
Pointer to the mail message that contains the header whose length is returned.

Return Values

The length, in characters, of the entire header string indicates success.

Remarks

The MailHeaderLen function searches the header (that is, the pwcHeaders member) of the MailMsg structure in memory. Before calling MailHeaderLen, the message must be retrieved from the message store by calling MailGet, MailFirst, or MailNext.

The pwcHeaders member of the MailMsg structure points to the message’s header string. The header consists of entries made up of two fields: a name, and an associated value. The name fields are separated from the value fields by a NULL character, and the entries are separated from each other by a NULL character. The header string is terminated with two consecutive NULL characters.

See Also

MailMsg, MailGetField, MailSetField


MailLocalAttachmentLen

This function computes the total size of local files of attachments to a message.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

DWORD MailLocalAttachmentLen (HANDLE hMail, MAILMSG * pmm);

Parameters

hMail
Handle to the open mail context, as returned by the MailOpen function.
pmm
Pointer to the mail message to which the attachments belong.

Return Values

The total size of local files of attachments to a message indicates success.

Remarks

To get extended error information, call MailError or MailErrorMsg.


MailNext

After a call to MailFirst, this function retrieves the next of a specified type of mail entry from the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailNext (HANDLE hMail, MailMsg* pmm);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the flags determining which folder the message is in, what type of message it is, and how much of the message to retrieve. The mail flag value in the dwFlags member of the structure is a combination of folder, status, and message flags. The folder flag determines which folder the entry will be retrieved from. One folder flag can be combined with any number of status flags and message flags. The status flags determine what type of message to retrieve, and the message flags determine how much of the message is returned.

When MailNext returns, this structure contains the message retrieved from the message store. Two of the message flags determine how much of the message to retrieve. If MAIL_GET_FLAGS is set, only the flags and the object identifier are returned. Using this option does not require any memory to be allocated for the message. If the MAIL_GET_BODY flag is set, the entire message is loaded into memory. This requires the system to allocate memory from the global heap. If neither of these flags is set, all of the message except the body is retrieved. Memory for this option is allocated from the private heap. To free memory allocated by MailNext use the MailFree function.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

The flags of the MailMsg structure must be set prior to each call to MailNext because each call to MailFirst, MailGet, or MailNext returns the flags of the message as it is stored in the database.

Changing the values of the MailMsg variable does not affect the message store until the message is reinserted by calling the MailUpdate function.

See Also

MailFirst, MailGet, MailMsg


MailOpen

This function opens the message store and obtains a handle to the mail context.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailOpen (HANDLE * phNewMail, BOOL fAllowCreate,);

Parameters

phNewMail
Pointer to the handle created by MailOpen for identifying the mail context.
fAllowCreate
If this Boolean is TRUE, MailOpen attempts to create the message store if it does not already exist. If the message store cannot be created, or if the required system message folders cannot be created, MailOpen fails.

If this Boolean is FALSE and the message store does not exist, MailOpen fails.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

Release the handle created by the MailOpen function with the MailClose function.

See Also

MailClose


MailOpenNotify

This function attempts to open the mail database and specify a window handle to receive DB_CEOID_* notifications of changes made to the database by different handles.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

BOOL MailOpenNotify (HANDLE * phMail, BOOL fAllowCreate,
HWND hwndNotify);

Parameters

phMail
Out parameter to receive the mail handle. This handle is set even if the function fails, so that the MailError function can be called against the returned handle to obtain the specific error message.
fAllowCreate
If this Boolean is TRUE, the database is created if it does not already exist. If this Boolean is FALSE, the call fails when the specified database cannot be opened.
hwndNotify
Handle to the window that receives DB_CEOID_* notifications when the database is modified by handles other than the one used to open it.

Return Values

TRUE indicates success. FALSE indicates failure.


MailPut

This function creates a new mail entry in the message store.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailPut (HANDLE hMail, MailMsg*pmm);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the information for the new entry. MailPut ignores the dwMsgID member of the MailMsg structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

If the MailPut function is successful, the oid member of the MailMsg structure is set with a unique identification number for this mail entry. The oid can be used by other mail functions to reference this entry.

MailPut is for adding new entries to the message store. To change existing entries, use the MailUpdate function.

If necessary, a caller should set the pwcHeader member of the MailMsg structure by calling the MailSetField function. This ensures a proper initialization of the hHeap pointer in the MailMsg structure. Otherwise, MailPut will return an error.

See Also

MailGet, MailMsg


MailPutAttachment

This function adds or change an attachment to a mail message.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

BOOL MailPutAttachment (HANDLE hMail, MailMsg * pmm,
MailAtt * pma);

Parameters

hMail
Handle to the current mail context. This handle is created by the MailOpen function.
pmm
Pointer to the mail message structure to which the attachment is to be added. The message must have been written to the object store so that the oid member has been set properly.
pma
Pointer to the mail attachment structure to be added to the message if the attachment identification number, uiAttachmentNumber, is greater than the current number of attachments. Otherwise it points to the new attachment to replace the existing one of the same uiAttachmentNumber value.

Return Values

TRUE indicates success. FALSE indicates failure. In the latter case, the caller is responsible for the disposition of the file. To get extended error information, call MailError or MailErrorMsg.

Remarks

For a local attachment, that is, when szLocalName (a member of the MailAtt structure) is set to a non-NULL value, the MailPutAttachment function stores a local copy of the original file in a special folder which is constructed from the registry entries for the attachment directory.

There can be up to 64 attachments to a message. When a single file is attached more than once, the MailPutAttachment function ensures that every local file has a unique path (szLocalName).

Since a local file gets moved, the local name (szLocalName) supplied to the MailPutAttachment function will be different from its counterpart retrieved from the MailGetAttachment function.

When a user composes a message with a file attached, she may want to make a copy of the attached file. In this case, the application should make a copy of the original before invoking the MailPutAttachment function. It is unwise to assume that the transport service will perform such an operation.


MailPutFolder

This function is used to add, delete, or rename mail folders.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailPutFolder (HANDLE hMail, BYTE bId, LPWSTR szName);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
bId
Unique integer from zero to 255 that identifies the mail folder. Since a system folder cannot be modified or deleted, this cannot be one of the following identifiers: MAIL_FOLDER_INBOX; MAIL_FOLDER_OUTBOX; MAIL_FOLDER_SENT.
szName
Pointer to a buffer that contains a null-terminated string that identifies the name of the mail folder. If this parameter is NULL, then the folder identified by bId is deleted.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

If the bId parameter identifies a folder that already exists in the message store the MailPutFolder function renames the folder to the szName string. If the folder exists and szName is NULL the folder is deleted. If the bId identifier is not found in the database, a folder is created with the name pointed to by the szName parameter.

See Also

MailGetFolderName, MailGetFolderId


MailRequestAttachment

This function requests a non-local attachment to a service-linked message for download, if the service allows that.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

BOOL MailRequestAttachment (HANDLE hMail, MailMsg * pmm,
MailAtt * pma, BOOL bRetrieve);

Parameters

hMail
Handle to the current mail context. This handle is created by the MailOpen function.
pmm
Pointer to the mail message to which the attachment belongs.
pma
Pointer to the mail attachment being requested. The caller must specify the uiAttachment member to identify the number of the requested attachment.
bRetrieve
Request to download the attachment when this flag is TRUE. Otherwise, cancel the earlier request.

Return Values

TRUE indicates success. FALSE indicates failure, or that the service does not allow individual download.

Remarks

If the request is successful, download will be started next time when the mail client is connected to a server.

To get extended error information, use MailError or MailErrorMsg.


MailSetField

This function is used to add, update, or delete fields from the message header.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailSetField (MailMsg*pmm, LPWSTR szName, LPCWSTR szVal);

Parameters

pmm
Pointer to the mail message that contains the header entry to be changed.
szName
Null-terminated string that contains the name field of the header entry to be added, deleted, or changed. When looking for a match, this parameter can be any combination of uppercase and lowercase letters because the name field is not case-sensitive.
szVal
Null-terminated string that contains the new value for the field. If this parameter is NULL, the entry is deleted from the header string.

Return Values

TRUE indicates success. FALSE indicates failure. The function only fails for memory-related reasons.

Remarks

The MailSetField function searches the header (that is, the pwcHeaders member) of the MailMsg structure in memory. Before calling MailSetField, the message must be retrieved from the message store by calling MailGet, MailFirst, or MailNext.

The pwcHeaders member of the MailMsg structure points to the message’s header string. The header consists of entries made up of two fields: a name, and an associated value. The name fields are separated from the value fields by a NULL character, and the entries are separated from each other by a NULL character. The header string is terminated with two consecutive NULL characters.

If a matching name field is not found in the message store, the entry is added to the header. If the entry name is found, the value field is changed to the new value passed in. If the value field being passed in is NULL and the entry name exists in the header, the entry is deleted.

See Also

MailGetField, MailMsg


MailSetSort

This function sets the order in which mail messages will be retrieved by MailFirst/MailNext calls on the same handle.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

BOOL MailSetSort (HANDLE hMail, MAILSORTFIELD iSort,
BOOL fAscending);

Parameters

hMail
Handle to the open mail context, as returned by the MailOpen function.
iSort
Specifies the field to sort by. See the MAILSORTFIELD.
fAscending
If this Boolean is set to TRUE, the records are sorted in ascending order on the specified key. If this Boolean is set to FALSE, the records are sorted in descending order.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

To get extended error information, call MailError or MailErrorMsg.


MailUpdate

This function replaces an entry in the message store with updated information.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MailUpdate (HANDLE hMail, MailMsg* pmm, BOOL fDoAll);

Parameters

hMail
Handle to the mail context. This handle is created by the MailOpen function.
pmm
Pointer to the MailMsg structure that contains the mail entry with the updated information.
fDoAll
If this Boolean is TRUE, all members of the MailMsg structure are updated. If this Boolean is set to FALSE, only the flags are changed—that is, the dwFlags member in the MailMsg structure pointed to by pmm.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call MailError or MailErrorMsg.

Remarks

The entry being updated is based on the oid member of the MailMsg structure. If the entry does not exist in the database, the MailUpdate function fails.

See Also

MailMsg, MailPut


MapViewOfFile

This function maps a view of a file into the address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

LPVOID MapViewOfFile( HANDLE hFileMappingObject,
DWORD dwDesiredAccess, DWORD dwFileOffsetHigh,
DWORD dwFileOffsetLow, DWORD dwNumberOfBytesToMap);

Parameters

hFileMappingObject
Handle to an open handle of a file-mapping object. The CreateFileMapping function returns this handle.
dwDesiredAccess
Specifies the type of access to the file view and, therefore, the protection of the pages mapped by the file. This parameter can be one of the following values:
Value
Description
FILE_MAP_WRITE | Read-write access. The hFileMappingObject parameter must have been created with PAGE_READWRITE protection. A read-write view of the file is mapped.
FILE_MAP_READ | Read-only access. The hFileMappingObject parameter must have been created with PAGE_READWRITE or PAGE_READONLY protection. A read-only view of the file is mapped.
FILE_MAP_ALL_ACCESS | Same as FILE_MAP_WRITE.
FILE_MAP_COPY | Copy on write access. If you create the map with PAGE_WRITECOPY and the view with FILE_MAP_COPY, you will receive a view to file. If you write to it, the pages are automatically swappable and the modifications you make will not go to the original data file.
Windows 95: You must pass PAGE_WRITECOPY to CreateFileMapping; otherwise, an error will be returned.
Windows NT: There is no restriction as to how the hFileMappingObject parameter must be created. Copy on write is valid for any type of view.

dwFileOffsetHigh
Specifies the high-order 32 bits of the file offset where mapping is to begin.
dwFileOffsetLow
Specifies the low-order 32 bits of the file offset where mapping is to begin. The combination of the high and low offsets must specify an offset within the file that matches the system’s memory allocation granularity, or the function fails. That is, the offset must be a multiple of the allocation granularity. Use the GetSystemInfo function, which fills in the members of a SYSTEM_INFO structure, to obtain the system’s memory allocation granularity.
dwNumberOfBytesToMap
Specifies the number of bytes of the file to map. If dwNumberOfBytesToMap is zero, the entire file is mapped.

Return Values

The starting address of the mapped view indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The 64 KB alignment is not required for the dwFileOffsetLow parameter.

Mapping a file makes the specified portion of the file visible in the address space of the calling process.

Multiple views of a file (or a file-mapping object and its mapped file) are said to be “coherent” if they contain identical data at a specified time. This occurs if the file views are derived from the same file-mapping object. A process can duplicate a file-mapping object handle into another process by using the DuplicateHandle function, or another process can open a file-mapping object by name by using the OpenFileMapping function.

A mapped view of a file is not guaranteed to be coherent with a file being accessed by the ReadFile or WriteFile function.

Windows 95: MapViewOfFile may require the swapfile to grow. If the swapfile cannot grow, the function fails.

Windows NT: If the file-mapping object is backed by the paging file (handle = 0xFFFFFFFF), the paging file must be large enough to hold the entire mapping. If it is not, MapViewOfFile fails.

Note To guard against an access violation, use structured exception handling to protect any code that writes to or reads from a memory mapped view.

See Also

CreateFileMapping, GetSystemInfo, UnmapViewOfFile, SYSTEM_INFO


Module32First

This function retrieves information about the first module associated with a process.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Module32First( HANDLE hSnapshot, LPMODULEENTRY32 lpme);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lpme
Pointer to a MODULEENTRY32 structure.

Return Value

TRUE indicates that the first entry of the module list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no modules exist or the snapshot does not contain module information.

Remarks

The calling application must set the dwSize member of MODULEENTRY32 to the size, in bytes, of the structure. Module32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other modules associated with the specified process, use the Module32Next function.


Module32Next

This function retrieves information about the next module associated with a process or thread.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Module32Next( HANDLE hSnapshot, LPMODULEENTRY32 lpme);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lpme
Pointer to a MODULEENTRY32 structure.

Return Value

TRUE indicates the next entry of the module list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no more modules exist.

Remarks

To retrieve information about first module associated with a process, use the Module32First function.


MoveFile

This function renames an existing file or a directory—including all its children.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL MoveFile(LPCTSTR lpExistingFileName, LPCTSTR lpNewFileNam);

Parameters

lpExistingFileName
[in] Pointer to a null-terminated string that names an existing file or directory.
lpNewFileName
[in] Pointer to a null-terminated string that specifies the new name of a file or directory. The new name must not already exist. A new file may be on a different file system or drive. A new directory must be on the same drive.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The MoveFile function will move (rename) either a file or a directory (including all its children) either in the same directory or across directories. The one caveat is that the MoveFile function will fail on directory moves when the destination is on a different volume.

See Also

CopyFile


MultiByteToWideChar

This function maps a character string to a wide-character (Unicode) string. The character string mapped by this function is not necessarily from a multibyte character set.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

int MultiByteToWideChar(UINT CodePage, DWORD dwFlags,
LPCSTR lpMultiByteStr, int cchMultiByte, LPWSTR lpWideCharStr,
int cchWideChar);

Parameters

CodePage
[in] Specifies the code page to be used to perform the conversion. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the following values:
Value
Description
CP_ACP | ANSI code page
CP_MACCP | Not supported
CP_OEMCP | OEM code page
CP_SYMBOL | Not supported
CP_THREAD_ACP | Not supported

dwFlags
[in] Specifies whether to translate to precomposed or composite wide characters (if a composite form exists), whether to use glyph characters in place of control characters, and how to deal with invalid characters. You can specify a combination of the following flag constants:
Value
Description
MB_PRECOMPOSED | Always use precomposed characters—that is, characters in which a base character and a nonspacing character have a single character value. This is the default translation option. Cannot be used with MB_COMPOSITE.
MB_COMPOSITE | Always use composite characters—that is, characters in which a base character and a nonspacing character have different character values. Cannot be used with MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS | If the function encounters an invalid input character, it fails and GetLastError returns ERROR_NO_UNICODE_TRANSLATION.
MB_USEGLYPHCHARS | Use glyph characters instead of control characters.

A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/non-spacing character combination. In the character è, the e is the base character and the accent grave mark is the nonspacing character.

The function’s default behavior is to translate to the precomposed form. If a precomposed form does not exist, the function attempts to translate to a composite form.

The flags MB_PRECOMPOSED and MB_COMPOSITE are mutually exclusive. The MB_USEGLYPHCHARS flag and the MB_ERR_INVALID_CHARS can be set regardless of the state of the other flags.

lpMultiByteStr
[in] Pointer to the character string to be converted.
cbMultiByte
[in] Specifies the size in bytes of the string pointed to by the lpMultiByteStr parameter. If this value is –1, the string is assumed to be null terminated and the length is calculated automatically.
lpWideCharStr
[out] Pointer to a buffer that receives the translated string.
cchWideChar
[in] Specifies the size, in wide characters, of the buffer pointed to by the lpWideCharStr parameter. If this value is zero, the function returns the required buffer size, in wide characters, and makes no use of the lpWideCharStr buffer.

Return Values

If cchWideChar is nonzero, the number of wide characters written to the buffer pointed to by lpWideCharStr indicates success. If cchWideChar is zero, the required size, in wide characters, for a buffer that can receive the translated string indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER
  • ERROR_NO_UNICODE_TRANSLATION

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns the value ERROR_INVALID_PARAMETER.

The function fails if MB_ERR_INVALID_CHARS is set and it encounters an invalid character in the source string. An invalid character is one that would translate to the default character if MB_ERR_INVALID_CHARS was not set, but is not the default character in the source string, or when a lead byte is found in a string and there is no valid trail byte for DBCS strings. When an invalid character is found, and MB_ERR_INVALID_CHARS is set, the function returns 0 and sets GetLastError with the error ERROR_NO_UNICODE_TRANSLATION.

See Also

WideCharToMultiByte


MyFSD_CloseFile

This function is called when an application closes an open handle for a file that was open on an installable file system. The application does not call this function directly. Instead, use the standard function CloseHandle. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_CloseFile implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_CloseFile( PFILE pFile);

Parameters

pFile
Pointer to the value that the FSD passed to the FSDMGR_CreateFileHandle function when creating the file handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

CloseHandle, FSDMGR_CreateFileHandle, MyFSD_CreateFileW, MyFSD_DeleteFileW, MyFSD_FindClose, MyFSD_FindFirstFileW


MyFSD_CloseVolume

This function closes a volume on a device that has an installable file system.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_CloseVolume( PVOLUME pVolume );

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This function is a notification that the specified volume is being unregistered. The FSD does not need to export this function if it cleans up all associated resources before calling FSDMGR_DeregisterVolume.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

FSDMGR_DeregisterVolume, FSDMGR_RegisterVolume


MyFSD_CreateDirectoryW

This function is called by the file system driver (FSD) manager to create a new directory in an installable file system. The application originally calls the corresponding standard Win32 function CreateDirectory.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_CreateDirectoryW( PVOLUME pVolume,
PCWSTR pwsPathName, PSECURITY_ATTRIBUTES pSecurityAttributes );

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsPathName
[in] Pointer to a null-terminated string that specifies the path of the directory to be created.
pSecurityAttributes
[in] Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

CreateDirectory, FSDMGR_RegisterVolume, MyFSD_RemoveDirectoryW


MyFSD_CreateFileW

This function creates, opens, or truncates a file, pipe, communications resource, disk device, or console in an installable file system. It returns a handle that can be used to access the object. It can also open and return a handle to a directory. The application does not call this function directly. Instead, use the corresponding standard Win32 function CreateFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_CreateFileW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE MyFSD_CreateFileW( PVOLUME pVolume, HANDLE hProc, PCWSTR pwsFileName, DWORD dwAccess, DWORD dwShareMode,
PSECURITY_ATTRIBUTES pSecurityAttributes, DWORD dwCreate,
DWORD dwFlagsAndAttributes, HANDLE hTemplateFile );

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
hProc
Handle to the process that is calling CreateFile. This parameter is the same value that the FSD must pass to the FSDMGR_CreateFileHandle function when creating the handle to return to the application.
pwsFileName
Pointer to a null-terminated string that specifies the name of the object (file, pipe, mailslot, communications resource, disk device, console, or directory) to create or open.
dwAccess
Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. It can be any combination of the following values:
Value
Description
0 | Specifies device query access to the object. An application can query device attributes without accessing the device.
GENERIC_READ | Specifies read access to the object. Data can be read from the file and the file pointer can be moved. Combine with GENERIC_WRITE for read-write access.
GENERIC_WRITE | Specifies write access to the object. Data can be written to the file and the file pointer can be moved. Combine with GENERIC_READ for read-write access.

dwShareMode
Set of bit flags that specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

To share the object, use a combination of one or more of the following values:
Value
Description
FILE_SHARE_READ | Subsequent open operations on the object will succeed only if read access is requested.
FILE_SHARE_WRITE | Subsequent open operations on the object will succeed only if write access is requested.

pSecurityAttributes
Ignored; set to NULL.
dwCreate
Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. It is one of the following values:
Value
Description
CREATE_NEW | Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS | Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
OPEN_EXISTING | Opens the file. The function fails if the file does not exist.
See the Remarks section for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFile function for devices, including the console.
OPEN_ALWAYS | Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreate were CREATE_NEW.
TRUNCATE_EXISTING | Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.

dwFlagsAndAttributes
Specifies the file attributes and flags for the file.
hTemplateFile
Ignored; as a result, CreateFile does not copy the extended attributes to the new file.

Return Values

An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastError returns zero.

INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

CreateFile, MyFSD_CloseFile, FSDMGR_RegisterVolume, VirtualAlloc


MyFSD_DeleteAndRenameFileW

This function deletes the source file, pwsOldFileName, after it copies the content of the source file to the destination file, pwsNewFileName, in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function DeleteAndRenameFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_DeleteAndRenameFileW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_DeleteAndRenameFileW( PVOLUME pVolume
PCWSTR pwsOldFileName, PCWSTR pwsNewFileName);

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsOldFileName
Pointer to the string that contains the path of the source file. This parameter cannot be NULL.
pwsNewFileName
Pointer to the string that contains the path of the destination file. This parameter cannot be NULL.

Return Values

TRUE indicates success. FALSE indicates failure. Call GetLastError to get detailed error messages.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

FSDMGR_RegisterVolume


MyFSD_DeleteFileW

This function deletes an existing file from an installable file system.. The application does not call this function directly. Instead, use the corresponding standard Win32 function DeleteFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_DeleteFileW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_DeleteFileW( PVOLUME pVolume, PCWSTR pwsFileName);

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsFileName
Pointer to a null-terminated string that specifies the file to be deleted.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If an application attempts to delete a file that does not exist, the DeleteFile function fails. It also fails if an application attempts to delete a file that is open for normal I/O or as a memory-mapped file.

To close an open file, the FSD uses the MyFSD_CloseFile function.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

DeleteFile, FSDMGR_RegisterVolume


MyFSD_DeviceIoControl

This function sends a control code directly to a specified device driver, causing the corresponding device to perform the specified operation. The application does not call this function directly. Instead, use the corresponding standard Win32 function DeviceIoControl. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_DeviceIoControl implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_DeviceIoControl( PFILE pFile, DWORD dwIoControlCode,
PVOID pInBuf, DWORD nInBufSize, PVOID pOutBuf,
DWORD nOutBufSize, PDWORD pBytesReturned,
OVERLAPPED *pOverlapped);

Parameters

pFile
[in] Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
dwIoControlCode
[in] Specifies the control code for the operation. This value identifies the specific operation to be performed and the type of device on which the operation is to be performed. It is one of the following values:
Value
Description
FSCTL_ALLOW_EXTENDED_DASD_IO | Signals the file system driver not to perform any I/O boundary checks on partition read or write calls. Instead, boundary checks are performed by the device driver.
FSCTL_DELETE_REPARSE_POINT | Deletes a reparse point for a file or directory.
FSCTL_DISMOUNT_VOLUME | Dismounts a volume.
FSCTL_ENABLE_UPGRADE | Enables or disables upgrading an NTFS volume to NTFS version 5.
FSCTL_GET_COMPRESSION | Obtains the compression state of a file or directory
FSCTL_GET_HFS_INFORMATION | Returns Macintosh Finder information about the file associated with the input handle.
FSCTL_GET_REPARSE_POINT | Returns reparse point data for a file or directory.
FSCTL_LOCK_VOLUME | Locks a volume.
FSCTL_QUERY_ALLOCATED_RANGES | Scans a file for ranges of the file for which disk space is allocated.
FSCTL_QUERY_FAT_BPB | Returns the first 36 bytes of a FAT16 or FAT12 volume.
FSCTL_READ_COMPRESSION | Reserved for future use.
FSCTL_SET_COMPRESSION | Sets the compression state of a file or directory.
FSCTL_SET_REPARSE_POINT | Sets a reparse point on a file or directory.
FSCTL_SET_SPARSE | Marks a file as a sparse file.
FSCTL_SET_ZERO_DATA | Sets a range of a files bytes to zeroes.
FSCTL_UNLOCK_VOLUME | Unlocks a volume.
FSCTL_WRITE_COMPRESSION | Reserved for future use.
IOCTL_DISK_CHECK_VERIFY | Obsolete. Use IOCTL_STORAGE_CHECK_VERIFY
IOCTL_DISK_EJECT_MEDIA | Obsolete. Use IOCTL_STORAGE_EJECT_MEDIA
IOCTL_DISK_FORMAT_TRACKS | Formats a contiguous set of disk tracks.
IOCTL_DISK_GET_DRIVE_GEOMETRY | Obtains information on the physical disk’s geometry.
IOCTL_DISK_GET_DRIVE_LAYOUT | Provides information about each partition on a disk.
IOCTL_DISK_GET_MEDIA_TYPES | Obsolete. Use IOCTL_STORAGE_GET_MEDIA_TYPES
IOCTL_DISK_GET_PARTITION_INFO | Obtains disk partition information.
IOCTL_DISK_LOAD_MEDIA | Obsolete. Use IOCTL_STORAGE_LOAD_MEDIA
IOCTL_DISK_MEDIA_REMOVAL | Obsolete. Use IOCTL_STORAGE_MEDIA_REMOVAL
IOCTL_DISK_PERFORMANCE | Provides disk performance information.
IOCTL_DISK_REASSIGN_BLOCKS | Maps disk blocks to spare-block pool.
IOCTL_DISK_SET_DRIVE_LAYOUT | Partitions a disk.
IOCTL_DISK_SET_PARTITION_INFO | Sets the disk partition type.
IOCTL_DISK_VERIFY | Performs logical format of a disk extent.
IOCTL_SERIAL_LSRMST_INSERT | Enables or disables placement of a line and modem status data into the data stream.
IOCTL_STORAGE_CHECK_VERIFY | Checks for change in a removable-media device.
IOCTL_STORAGE_EJECT_MEDIA | Ejects media from a SCSI device.
IOCTL_STORAGE_GET_MEDIA_TYPES | Obtains information about media support.
IOCTL_STORAGE_LOAD_MEDIA | Loads media into a device.
IOCTL_STORAGE_MEDIA_REMOVAL | Enables or disables the media eject mechanism.

For more detailed information on each control code, see its topic. In particular, each topic provides details on the usage of the pInBuf, nInBufSize, pOutBuf, nOutBufSize, and pBytesReturned parameters.

pInBuffer
[in] Pointer to a buffer that contains the data required to perform the operation.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

nInBufSize
[in] Size, in bytes, of the buffer pointed to by pInBuf.
pOutBuf
[out] Pointer to a buffer that receives the operation’s output data.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

nOutBufSize
[in] Size, in bytes, of the buffer pointed to by pOutBuf.
pBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored into the buffer pointed to by pOutBuf.

The pBytesReturned parameter cannot be NULL. Even when an operation produces no output data and pOutBuf can be NULL, the DeviceIoControl function makes use of the variable pointed to by pBytesReturned. After such an operation, the value of the variable is without meaning.

pOverlapped
Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

DeviceIoControl, CreateEvent, CreateFile, FSDMGR_CreateFileHandle


MyFSD_FindClose

This function closes the specified search handle. The MyFSD_FindFirstFileW and MyFSD_FindNextFileW functions use the search handle to locate files with names that match a specified name. The application does not call this function directly. Instead, use the corresponding standard Win32 function FindClose. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_FindClose implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_FindClose( PSEARCH pSearch );

Parameters

pSearch
Pointer to the value that the FSD passes to the FSDMGR_CreateSearchHandle function when creating the search handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

Remarks

After the MyFSD_FindClose function is called, the handle specified by the hFindFile parameter cannot be used in subsequent calls to either the MyFSD_FindNextFileW or MyFSD_FindClose function.

See Also

FindClose, FindFirstFile, FindNextFile, FSDMGR_CreateSearchHandle


MyFSD_FindFirstFileW

This function searches a directory for a file in an installable file system whose name matches the specified file name. This function also examines subdirectory names as well as file names. The application does not call this function directly. Instead, use the corresponding standard Win32 function FindFirstFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_FindFirstFileW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

HANDLE MyFSD_FindFirstFileW( PVOLUME pVolume, HANDLE hProc,
PCWSTR pwsFileSpec, PWIN32_FIND_DATAW pfd );

Parameters

pVolume
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_RegisterVolume function when it creates the file handle.
hProc
Handle of the process that calls FindFirstFile.
pwsFileSpec
[in] Pointer to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the FindFirstFile function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with FindFirstFile. However, each component in the path cannot be more than MAX_PATH characters long. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps”.

pfd
[out] Pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory.

Return Values

A search handle used in a subsequent call to MyFSD_FindNextFileW or MyFSD_FindClose indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

The MyFSD_FindFirstFileW function opens a search handle and returns information about the first file whose name matches the specified pattern. Once the search handle is established, you can use the MyFSD_FindNextFileW function to search for other files that match the same pattern. When the search handle is no longer needed, close it by using the MyFSD_FindClose function.

This function searches for files by name only; it cannot be used for attribute-based searches.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

FindFirstFile, FindClose, FindNextFile, FSDMGR_RegisterVolume, WIN32_FIND_DATA


MyFSD_FindNextFileW

This function continues a file search from a previous call to the MyFSD_FindFirstFileW function. The application does not call this function directly. Instead, use the corresponding standard Win32 function FindNextFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_FindNextFileW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_FindNextFileW( PSEARCH pSearch, PWIN32_FIND_DATAW pfd );

Parameter

pSearch
[in] Pointer to the value that the FSD passes to the FSDMGR_CreateSearchHandle function creating the search handle.
pfd
[out] Pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to MyFSD_FindNextFileW to refer to the found file or directory.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Remarks

The MyFSD_FindNextFileW function searches for files by name only; it cannot be used for attribute-based searches.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

FindNextFile, MyFSD_FindClose, MyFSD_FindFirstFileW, FSDMGR_CreateSearchHandle, WIN32_FIND_DATA,


MyFSD_FlushFileBuffers

This function clears the buffers for the specified file in an installable file system and causes all buffered data to be written to the file. The application does not call this function directly. Instead, use the corresponding standard Win32 function FlushFileBuffers. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_FlushFileBuffers implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_FlushFileBuffers( PFILE pFile );

Parameters

pFile
Pointer to the value that the FSD passes to the FSDMGR_CreateFileHandle function when creating the file handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The MyFSD_WriteFile function typically write data to an internal buffer that the operating system writes to disk on a regular basis. The FlushFileBuffers function writes all of the buffered information for the specified file to disk.

You can pass the same file handle used with the _lread, _lwrite, _lcreat, and related functions to FlushFileBuffers.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

FSDMGR_CreateFileHandle


MyFSD_GetDiskFreeSpaceW

This function obtains information about the amount of space available on a disk volume in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function GetDiskFreeSpaceEx. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_GetDiskFreeSpaceW implementation of the function.

At a Glance

Header file: | Fsgmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_GetDiskFreeSpaceW( PVOLUME pVolume,
PCWSTR pwsPathName, PDWORD pSectorsPerCluster,
PDWORD pBytesPerSector, PDWORD pFreeClusters PDWORD pClusters );

Parameters

pVolume
[in] Pointer to the value that the FSD defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsPathName
[in] Pointer to a null-terminated string that specifies a directory in the file system to return information about. This string can be a UNC name. If this parameter is a UNC name, you must follow it with an additional backslash. For example, you would specify \\MyServer\MyShare as \\MyServer\MyShare\.

If pwsPathName is NULL, the function obtains information about the disk that contains the current directory.

pSectorsPerCluster
[out] Pointer to a variable that receives the number of sectors per cluster.
pBytesPerSector
[out] Pointer to a variable that receives the number of bytes per sector.
pFreeClusters
[out] Pointer to a variable that receives the total number of free clusters on the disk that are available to the user associated with the calling thread.
pClusters
[out] Pointer to a variable that receives the total number of clusters on the disk that are available to the user associated with the calling thread.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

GetDiskFreeSpaceEx, FSDMGR_RegisterVolume


MyFSD_GetFileAttributesW

This function returns attributes for a specified file or directory in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function GetFileAttributes. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_GetFileAttributesW version of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD MyFSD_GetFileAttributesW( PVOLUME pVolume,
PCWSTR pwsFileName);

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsFileName
Pointer to a null-terminated string that specifies the name of a file or directory.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the GetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by prepending “\\?\” to the path. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with GetFileAttributes. However, each component in the path cannot be more than MAX_PATH characters long. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\bill_g_1\hotstuff\coolapps” is seen as “\\bill_g_1\hotstuff\coolapps”.

Return Values

The attributes of the specified file or directory, returned in a DWORD, indicates success. 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

For more information about the file attributes returned, see GetFileAttributes.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

GetFileAttributes, FSDMGR_RegisterVolume, MyFSD_SetFileAttributesW


MyFSD_GetFileInformationByHandle

This function retrieves information about the specified file in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function GetFileInformationByHandle. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_GetFileInformationByHandle implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_GetFileInformationByHandle( PFILE pFile,
PBY_HANDLE_FILE_INFORMATION pFileInfo );

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
lpFileInfo
Long pointer to a BY_HANDLE_FILE_INFORMATION structure that receives the file information. The structure can be used in subsequent calls to GetFileInformationByHandle to refer to the information about the file.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

GetFileInformationByHandle, BY_HANDLE_FILE_INFORMATION, FSDMGR_CreateFileHandle


MyFSD_GetFileSize

This function retrieves the size, in bytes, of the specified file that resides in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function GetFileSize. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_GetFileSize implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD MyFSD_GetFileSize( PFILE pFile, PDWORD pFileSizeHigh);

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
pFileSizeHigh
Pointer to the variable where the high-order word of the file size is returned. This parameter can be NULL if the application does not require the high-order word.

Return Values

If the function succeeds, the return value is the low-order doubleword of the file size, and, if lpFileSizeHigh is non-NULL, the function puts the high-order doubleword of the file size into the variable pointed to by that parameter.

If the function fails and lpFileSizeHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails and lpFileSizeHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError returns a value other than NO_ERROR.

Remarks

The GetFileSize function obtains the uncompressed size of a file.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

GetFileSize, FSDMGR_CreateFileHandle


MyFSD_GetFileTime

This function retrieves the date and time that a file in an installable file system was created, last accessed, and last modified. The application does not call this function directly. Instead, use the corresponding standard Win32 function GetFileTime. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_GetFileTime implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_GetFileTime( PFILE pFile, FILETIME *pCreation,
FILETIME *pLastAccess, FILETIME *pLastWrite);

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
pCreation
Pointer to a FILETIME structure to receive the date and time the file was created. This parameter can be NULL if the application does not require this information.
pLastAccess
Pointer to a FILETIME structure to receive the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.
pLastWrite
Pointer to a FILETIME structure to receive the date and time the file was last written to. This parameter can be NULL if the application does not require this information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

FILETIME, FSDMGR_CreateFileHandle, GetFileSize, SetFileTime


MyFSD_MountDisk

This function mounts the specified disk containing a file system of the type defined by the file system driver (FSD).

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_MountDisk( HDSK hdsk);

Parameters

hdsk
Handle to the disk.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The FSD must be able to cope with MyFSD_MountDisk being called redundantly. It must determine from the media itself, not the value of hdsk, whether the disk is already mounted. This is required because the user media may have been removed or may have changed slots while the system was powered off. The value of hdsk has meaning only to FSDMGR functions, not to the FSD.

Use the FSDMGR_ReadDisk and FSDMGR_WriteDisk functions for all input/output to the mounted disk.

A definition file (.def) for the MyFSD.dll file must export the MyFSD_MountDisk function as FSD_MountDisk When determining how to load the FSD, Device.exe looks for FSD_MountDisk.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call MyFSD_CreateDirectoryW.

See Also

MyFSD_UnmountDisk, FSD_MountDisk


MyFSD_MoveFileW

This function renames an existing file or a directory—including all its children—that resides in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function MoveFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_MoveFileW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_MoveFileW( PVOLUME pVolume,
PCWSTR pwsOldFileName, PCWSTR pwsNewFileName );

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsOldFileName
Pointer to a null-terminated string that names an existing file or directory.
pwsNewFileName
Pointer to a null-terminated string that specifies the new name of a file or directory. The new name must not already exist. A new file may be on a different file system or drive. A new directory must be on the same drive.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

The MoveFile function will move (rename) either a file or a directory (including all its children) either in the same directory or across directories. The one caveat is that the MoveFile function will fail on directory moves when the destination is on a different volume.

See Also

FSDMGR_RegisterVolume


MyFSD_Notify

This function, an event notification handler, is called by the application to notify a file system driver (FSD) on a per-volume basis.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

void MyFSD_Notify( PVOLUME pVolume, DWORD dwFlags);

Parameters

pVolume
Pointer to the value that the FSD defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
dwFlags
Specifies the event. It is one of the following flags, included in Fsdmgr.h from the Extfile.h file:
  • FSNOTIFY_POWER_ON
  • FSNOTIFY_POWER_OFF
  • FSNOTIFY_DEVICES_ON

Return Values

None.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

See Also

FSDMGR_RegisterVolume


MyFSD_ReadFile

This function reads data from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read. The application does not call this function directly. Instead, use the corresponding standard Win32 function ReadFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_ReadFile implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_ReadFile( PFILE pFile, PVOID pBuffer, DWORD cbRead,
PDWORD pcbRead, OVERLAPPED *pOverlapped );

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
pBuffer
Pointer to the buffer that receives the data read from the file.
cbRead
Number of bytes to be read from the file.
pcbRead
Pointer to the number of bytes read. ReadFile sets this value to zero before doing any work or error checking. If this parameter is zero when ReadFile returns TRUE on a named pipe, the other end of the message-mode pipe called the WriteFile function with nNumberOfBytesToWrite set to zero.

Windows NT: If lpOverlapped is NULL, lpNumberOfBytesRead cannot be NULL.

Windows NT: If lpOverlapped is not NULL, lpNumberOfBytesRead can be NULL. If this is an overlapped read operation, you can get the number of bytes read by calling GetOverlappedResult. If hFile is associated with an I/O completion port, you can get the number of bytes read by calling GetQueuedCompletionStatus.

Windows 95 and Windows 98: This parameter cannot be NULL.

pOverlapped
Pointer to an OVERLAPPED structure. This structure is required if hFile was created with FILE_FLAG_OVERLAPPED.

If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the read operation is complete.

If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure and ReadFile may return before the read operation has been completed. In this case, ReadFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This allows the calling process to continue while the read operation finishes. The event specified in the OVERLAPPED structure is set to the signaled state upon completion of the read operation.

If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the read operation starts at the current file position and ReadFile does not return until the operation has been completed.

If hFile is not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the read operation starts at the offset specified in the OVERLAPPED structure. ReadFile does not return until the read operation has been completed.

Return Values

The ReadFile function returns when one of the following is true: a write operation completes on the write end of the pipe, the number of bytes requested has been read, or an error occurs.

Nonzero indicates success. If the return value is nonzero and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read operation. However, if the file was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the return value is FALSE and GetLastError returns ERROR_HANDLE_EOF when the file pointer goes beyond the current end of file.

Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The lpOverlapped parameter must be set to NULL. Windows CE does not allow files to be created with the overlapped attribute.

Windows CE does not support asynchronous read operations on files.

The hFile parameter cannot be a socket handle.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW.That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails.

An application must meet certain requirements when working with files opened with FILE_FLAG_NO_BUFFERING:

  • File access must begin at byte offsets within the file that are integer multiples of the volume’s sector size. To determine a volume’s sector size, call the GetDiskFreeSpace function.
  • File access must be for numbers of bytes that are integer multiples of the volume’s sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, or 2048 bytes, but not of 335, 981, or 7171 bytes.
  • Buffer addresses for read and write operations must be sector aligned (aligned on addresses in memory that are integer multiples of the volume’s sector size). One way to sector align buffers is to use the VirtualAlloc function to allocate the buffers. This function allocates memory that is aligned on addresses that are integer multiples of the system's page size. Because both page and volume sector sizes are powers of 2, memory aligned by multiples of the system's page size is also aligned by multiples of the volume’s sector size.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes.

Characters can be read from the console input buffer by using ReadFile with a handle to console input. The console mode determines the exact behavior of the ReadFile function.

If a named pipe is being read in message mode and the next message is longer than the nNumberOfBytesToRead parameter specifies, ReadFile returns FALSE and GetLastError returns ERROR_MORE_DATA. The remainder of the message may be read by a subsequent call to the ReadFile or PeekNamedPipe function.

When reading from a communications device, the behavior of ReadFile is governed by the current communication time-outs as set and retrieved using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information about communication time-outs, see COMMTIMEOUTS.

If ReadFile attempts to read from a mailslot whose buffer is too small, the function returns FALSE and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

If the anonymous write pipe handle has been closed and ReadFile attempts to read using the corresponding anonymous read pipe handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE.

The ReadFile function may fail and return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

The ReadFile code to check for the end-of-file condition (eof) differs for synchronous and asynchronous read operations.

When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. The following sample code tests for end-of-file for a synchronous read operation:

// Attempt a synchronous read operation.
bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ;
// Check for end of file.
if (bResult &&  nBytesRead == 0, )
{
    // we’re at the end of the file
}

An asynchronous read operation can encounter the end of a file during the initiating call to ReadFile, or during subsequent asynchronous operation.

If EOF is detected at ReadFile time for an asynchronous read operation, ReadFile returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

If EOF is detected during subsequent asynchronous operation, the call to GetOverlappedResult to obtain the results of that operation returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

To cancel all pending asynchronous I/O operations, use the CancelIo function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

If you are attempting to read from a floppy drive that does not have a floppy disk, the system displays a message box prompting the user to retry the operation. To prevent the system from displaying this message box, call the SetErrorMode function with SEM_NOOPENFILEERRORBOX.

The following sample code illustrates testing for end-of-file for an asynchronous read operation:

// set up overlapped structure fields
// to simplify this sample, we'll eschew an event handle
gOverLapped.Offset     = 0;
gOverLapped.OffsetHigh = 0;
gOverLapped.hEvent     = NULL;

// attempt an asynchronous read operation
bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead,
    &gOverlapped) ;

// if there was a problem, or the async. operation's still pending ...
if (!bResult)
{
    // deal with the error code
    switch (dwError = GetLastError())
    {
        case ERROR_HANDLE_EOF:
        {
            // we're reached the end of the file
            // during the call to ReadFile

            // code to handle that
        }

        case ERROR_IO_PENDING:
        {
            // asynchronous i/o is still in progress

            // do something else for a while
            GoDoSomethingElse() ;

            // check on the results of the asynchronous read
            bResult = GetOverlappedResult(hFile, &gOverlapped,
                &nBytesRead, FALSE) ;

            // if there was a problem ...
            if (!bResult)
            {
                // deal with the error code
                switch (dwError = GetLastError())
                {
                    case ERROR_HANDLE_EOF:
                    {
                        // we're reached the end of the file
                        //during asynchronous operation
                    }

                    // deal with other error cases
                }
            }
        } // end case

        // deal with other error cases

    } // end switch
} // end if

See Also

FSDMGR_CreateFileHandle, MyFSD_CreateFileW, MyFSD_WriteFile


MyFSD_RegisterFileSystemFunction

This function is called by the file system driver manager (FSDMGR) to register a file or folder change notification function with the FSD to insure that the shell maintains an accurate view of the file system.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_RegisterFileSystemFunction( PVOLUME pVolume
SHELLFILECHANGEFUNC_t pfn );

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pfn
Pointer to the function used for file or folder change notifications.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When a non-NULL SHELLFILECHANGEFUNC address is registered, the FSD needs to fill in a FILECHANGEINFO structure with all the appropriate information every time a file or folder change occurs. At a minimum, fill FILECHANGEINFO for the following functions, assuming they succeed:

  • MyFSD_CreateDirectoryW
  • MyFSD_RemoveDirectoryW
  • MyFSD_SetFileAttributesW
  • MyFSD_DeleteFileW
  • MyFSD_MoveFileW

Also register a file information change after the following calls:

  • MyFSD_CreateFileW to create or truncate a file.
  • MyFSD_FlushFileBuffers or MyFSD_CloseFile and a file’s attributes, times, or other information changes.

SHELLFILECHANGEFUNC and FILECHANGEINFO are defined in Extfile.h.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

See Also

MyFSD_CloseFile, MyFSD_CreateDirectoryW, MyFSD_CreateFileW, MyFSD_DeleteFileW, MyFSD_FlushFileBuffers, MyFSD_MoveFileW, MyFSD_RemoveDirectoryW, MyFSD_SetFileAttributesW


MyFSD_RemoveDirectoryW

This function deletes an existing empty directory from an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function RemoveDirectory. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_RemoveDirectoryW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_RemoveDirectoryW( PVOLUME pVolume,
PCWSTR pwsPathName);

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsPathName
Pointer to a null-terminated string that specifies the path of the directory to be removed. The path must specify an empty directory, and the calling process must have delete access to the directory.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

See Also

CreateDirectory, FSDMGR_RegisterVolume


MyFSD_SetEndOfFile

This function moves the end-of-file position for the specified file in an installable file system to the current position of the file pointer. The application does not call this function directly. Instead, use the corresponding standard Win32 function SetEndOfFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_SetEndOfFile implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_SetEndOfFile( PFILE pFile);

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW.That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

This function can be used to truncate or extend a file. If the file is extended, the contents of the file between the old EOF position and the new position are not defined.

If you called CreateFileMapping to create a file-mapping object for hFile, you must first call UnmapViewOfFile to unmap all views and call CloseHandle to close the file-mapping object before you can call SetEndOfFile.

See Also

CreateFile, FSDMGR_CreateFileHandle


MyFSD_SetFileAttributesW

This function sets the attributes of a file that resides in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function SetFileAttributes. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_SetFileAttributesW implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_SetFileAttributesW( PVOLUME pVolume,PCWSTR pwsFileName,
DWORD dwFileAttributes);

Parameters

pVolume
Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.
pwsFileName
Pointer to a string that specifies the name of the file whose attributes are to be set.

Windows 95: This string must not exceed MAX_PATH characters.

Windows NT: There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the SetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) implementation of SetFileAttributes and prepending “\\?\” to the path. However, each component in the path cannot be more than MAX_PATH characters long. The “\\?\” tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with SetFileAttributesW. However, each component in the path cannot be more than MAX_PATH characters long. This also works with UNC names. The “\\?\” is ignored as part of the path. For example, “\\?\C:\myworld\private” is seen as “C:\myworld\private”, and “\\?\UNC\wow\hotstuff\coolapps” is seen as “\\wow\hotstuff\coolapps”.

dwFileAttributes
Specifies the file attributes to set for the file. This parameter can be a combination of the following values. However, all other values override FILE_ATTRIBUTE_NORMAL.
FILE_ATTRIBUTE_ARCHIVE
The file is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_HIDDEN
The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL
The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE
The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY
The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM
The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY
The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

The following table describes how to set the attributes that cannot be set using SetFileAttributes.

FILE_ATTRIBUTE_COMPRESSED
To set a file's compression state, use the DeviceIoControl function with the FSCTL_SET_COMPRESSION operation.
FILE_ATTRIBUTE_DIRECTORY
Files cannot be converted into directories. To create a directory, use the CreateDirectory or CreateDirectoryEx function.
FILE_ATTRIBUTE_ENCRYPTED
To encrypt a file, use the EncryptFile function.
FILE_ATTRIBUTE_REPARSE_POINT
To associate a reparse point with a file, use the DeviceIoControl function with the FSCTL_SET_REPARSE_POINT operation.
FILE_ATTRIBUTE_SPARSE_FILE
To set a file's sparse attribute, use the DeviceIoControl function with the FSCTL_SET_SPARSE operation.
FILE_ATTRIBUTE_SYSTEM
This attribute cannot be set.

See Also

FDMGR_RegisterVolume, MyFSD_GetFileAttributesW


MyFSD_SetFilePointer

This function moves the file pointer of an open file in an installable file system. The application does not call this function directly. Instead, use the corresponding standard Win32 function SetFilePointer. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_SetFilePointer implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

DWORD MyFSD_SetFilePointer( PFILE pFile, LONG lDistanceToMove,
PLONG pDistanceToMoveHigh, DWORD dwMoveMethod );

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
lDistanceToMove
Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. If lpDistanceToMoveHigh is not NULL, lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value that specifies the distance to move. If lpDistanceToMoveHigh is NULL, lDistanceToMove is a 32-bit signed value. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer backward.
pDistanceToMoveHigh
Pointer to the high-order 32 bits of the signed 64-bit distance to move. If you do not need the high-order 32 bits, this pointer may be NULL. When non-NULL, this parameter also receives the high-order DWORD of the new value of the file pointer. For more information, see the Remarks section later in this topic.
dwMoveMethod
Starting point for the file pointer move. It is one of the following values:
Value
Description
FILE_BEGIN | The starting point is zero or the beginning of the file.
FILE_CURRENT | The starting point is the current value of the file pointer.
FILE_END | The starting point is the current end-of-file position.

Return Values

If the SetFilePointer function succeeds and lpDistanceToMoveHigh is NULL, the return value is the low-order DWORD of the new file pointer. If lpDistanceToMoveHigh is not NULL, the function returns the low order DWORD of the new file pointer, and puts the high-order DWORD of the new file pointer into the LONG pointed to by that parameter.

If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF. However, because 0xFFFFFFFF is a valid value for the low-order DWORD of the new file pointer, you must check GetLastError to determine whether an error occurred. If an error occurred, GetLastError returns a value other than NO_ERROR. For a code example that illustrates this point, see the Remarks section later in this topic.

If the new file pointer would have been a negative value, the function fails, the file pointer is not moved, and the code returned by GetLastError is ERROR_NEGATIVE_SEEK.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

You cannot use the SetFilePointer function with a handle to a nonseeking device, such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.

You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object.

If the hFile file handle was opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position is a position that is a whole number multiple of the volume’s sector size. An application can obtain a volume’s sector size by calling the GetDiskFreeSpace function. If an application calls SetFilePointer with distance-to-move values that result in a position that is not sector-aligned and a handle that was opened with FILE_FLAG_NO_BUFFERING, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Note that it is not an error to set the file pointer to a position beyond the end of the file. The size of the file does not increase until you call the SetEndOfFile, WriteFile, or WriteFileEx function. A write operation increases the size of the file to the file pointer position plus the size of the buffer written, leaving the intervening bytes uninitialized.

If the return value is 0xFFFFFFFF and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//
// Case One: calling the function with lpDistanceToMoveHigh == NULL

// Try to move hFile's file pointer some distance
dwPtr = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN) ;

if (dwPtr == 0xFFFFFFFF) // Test for failure
{
    // Obtain the error code
    dwError = GetLastError() ;

    // Deal with failure
    // . . .

} // End of error handler

//
// Case Two: calling the function with lpDistanceToMoveHigh != NULL

// Try to move hFile's file pointer some huge distance
dwPtrLow = SetFilePointer (hFile, lDistLow, & lDistHigh, FILE_BEGIN) ;

// Test for failure
if (dwPtrLow == 0xFFFFFFFF && (dwError = GetLastError()) != NO_ERROR )
{
    // Deal with failure
    // . . .

} // End of error handler

The parameter lpDistanceToMoveHigh is used to manipulate huge files. If it is set to NULL, then lDistanceToMove has a maximum value of 2^31–2, or 2 gigabytes less two. This is because all file pointer values are signed values. Therefore if there is even a small change that the file will grow to that size, you should treat the file as a huge file and work with 64-bit file pointers. With file compression on NTFS, and sparse files, it is possible to have files that large even if the underlying volume is not that large.

If lpDistanceToMoveHigh is not NULL, then lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value. The lDistanceToMove parameter is treated as the low-order 32 bits of the value, and lpDistanceToMoveHigh as the upper 32 bits. Thus, lpDistanceToMoveHigh is a sign extension of lDistanceToMove.

To move the file pointer from zero to 2 gigabytes, lpDistanceToMoveHigh can be either NULL or a sign extension of lDistanceToMove. To move the pointer more than 2 gigabytes, use lpDistanceToMoveHigh and lDistanceToMove as a single 64-bit quantity. For example, to move in the range from 2 gigabytes to 4 gigabytes set the contents of lpDistanceToMoveHigh to zero, or to –1 for a negative sign extension of lDistanceToMove.

To work with 64-bit file pointers, you can declare a LONG, treat it as the upper half of the 64-bit file pointer, and pass its address in lpDistanceToMoveHigh. This means you have to treat two different variables as a logical unit, which is error-prone. The problems can be ameliorated by using the LARGE_INTEGER structure to create a 64-bit value and passing the two 32-bit values by means of the appropriate elements of the union.

It is conceptually simpler and better design to use a function to hide the interface to SetFilePointer. To do so, use something like this:

__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
   LARGE_INTEGER li;

   li.QuadPart = distance;

   li.LowPart = SetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod);

   if (li.LowPart == 0xFFFFFFFF && GetLastError() != NO_ERROR)
   {
      li.QuadPart = –1;
   }

   return li.QuadPart;
}

Note You can use SetFilePointer to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location zero. The file offset returned is the length of the file. However, this practice can have unintended side effects, such as failure to save the current file pointer so that the program can return to that location. It is simpler and safer to use GetFileSize instead.

You can also use the SetFilePointer function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero.

See Also

MyFSD_ReadFile


MyFSD_SetFileTime

This function sets the date and time that a file in an installable file system was created, last accessed, or last modified. The application does not call this function directly. Instead, use the corresponding standard Win32 function SetFileTime. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_SetFileTime implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_SetFileTime( PFILE pFile, CONST FILETIME *pCreation,
CONST FILETIME *pLastAccess, CONST FILETIME *pLastWrite );

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
pCreation
Pointer to a FILETIME structure that contains the date and time the file was created. This parameter can be NULL if the application does not need to set this information.
pLastAccess
Pointer to a FILETIME structure that contains the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or (in the case of executable files) run. This parameter can be NULL if the application does not need to set this information.
pLastWrite
Pointer to a FILETIME structure that contains the date and time the file was last written to. This parameter can be NULL if the application does not want to set this information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

The FAT and NTFS file systems support the file creation, last access, and last write time values.

See Also

FILETIME, FSDMGR_CreateFileHandle, GetFileSize, GetFileTime


MyFSD_UnmountDisk

This function unmounts the specified disk containing a file system of the type defined by the file system driver (FSD).

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_UnmountDisk( HDSK hdsk);

Parameters

hdsk
Handle to the disk.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

A requirement of returning TRUE is that all volumes on the disk previously registered with the FSDMGR_RegisterVolume function must first be deregistered with the FSDMGR_DeregisterVolume function.

A definition file (.def) for the MyFSD.dll file must export the MyFSD_UnmountDisk function as FSD_UnmountDisk. When determining how to unmount the FSD, Device.exe looks for FSD_UnmountDisk.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

See Also

FSDMGR_DeregisterVolume, FSDMGR_RegisterVolume, MyFSD_MountDisk


MyFSD_WriteFile

This function writes data to a file in an installable file system. The function starts writing data to the file at the position indicated by the file pointer. After the write operation has been completed, the file pointer is adjusted by the number of bytes actually written. The application does not call this function directly. Instead, use the corresponding standard Win32 function WriteFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_WriteFile implementation of the function.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

BOOL MyFSD_WriteFile( PFILE pFile, PCVOID pBuffer, DWORD cbWrite,
PDWORD pcbWritten, OVERLAPPED *pOverlapped);

Parameters

pFile
Pointer to the value that the file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.
pBuffer
Pointer to the buffer containing the data to be written to the file.
cbWrite
Number of bytes to write to the file.

A value of zero specifies a null write operation. A null write operation does not write any bytes but does cause the time stamp to change.

Named pipe write operations across a network are limited to 65,535 bytes.

pcbWritten
Pointer to the number of bytes written by this function call. WriteFile sets this value to zero before doing any work or error checking.

Windows NT: If lpOverlapped is NULL, lpNumberOfBytesWritten cannot be NULL.

Windows NT: If lpOverlapped is not NULL, lpNumberOfBytesWritten can be NULL. If this is an overlapped write operation, you can get the number of bytes written by calling GetOverlappedResult. If hFile is associated with an I/O completion port, you can get the number of bytes written by calling GetQueuedCompletionStatus.

Windows 95 and Windows 98: This parameter cannot be NULL.

pOverlapped
Pointer to an OVERLAPPED structure. This structure is required if hFile was opened with FILE_FLAG_OVERLAPPED.

If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the write operation is complete.

If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the write operation starts at the offset specified in the OVERLAPPED structure and WriteFile may return before the write operation has been completed. In this case, WriteFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This allows the calling process to continue processing while the write operation is being completed. The event specified in the OVERLAPPED structure is set to the signaled state upon completion of the write operation.

If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the write operation starts at the current file position and WriteFile does not return until the operation has been completed.

If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, the write operation starts at the offset specified in the OVERLAPPED structure and WriteFile does not return until the write operation has been completed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE does not support asynchronous write operations. The lpOverlapped parameter is ignored and should be set to NULL before calling WriteFile.

Unlike the MS-DOS operating system, Windows CE interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides services to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. Fsdmgr recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing Fsdmgr to call FATFSD_CreateDirectoryW.

An application must meet certain requirements when working with files opened with FILE_FLAG_NO_BUFFERING:

  • File access must begin at byte offsets within the file that are integer multiples of the volume’s sector size. To determine a volume’s sector size, call the GetDiskFreeSpace function.
  • File access must be for numbers of bytes that are integer multiples of the volume’s sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, or 2048 bytes, but not of 335, 981, or 7171 bytes.
  • Buffer addresses for read and write operations must be sector aligned (aligned on addresses in memory that are integer multiples of the volume’s sector size). One way to sector align buffers is to use the VirtualAlloc function to allocate the buffers. This function allocates memory that is aligned on addresses that are integer multiples of the system's page size. Because both page and volume sector sizes are powers of 2, memory aligned by multiples of the system's page size is also aligned by multiples of the volume’s sector size.

If part of the file is locked by another process and the write operation overlaps the locked portion, this function fails.

Accessing the output buffer while a write operation is using the buffer may lead to corruption of the data written from that buffer. Applications must not read from, write to, reallocate, or free the output buffer that a write operation is using until the write operation completes.

Characters can be written to the screen buffer using WriteFile with a handle to console output. The exact behavior of the function is determined by the console mode. The data is written to the current cursor position. The cursor position is updated after the write operation.

The system interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

When writing to a nonblocking, byte-mode pipe handle with insufficient buffer space, WriteFile returns TRUE with *lpNumberOfBytesWritten < nNumberOfBytesToWrite.

When an application uses the WriteFile function to write to a pipe, the write operation may not finish if the pipe buffer is full. The write operation is completed when a read operation (using the ReadFile function) makes more buffer space available.

If the anonymous read pipe handle has been closed and WriteFile attempts to write using the corresponding anonymous write pipe handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE.

The WriteFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

To cancel all pending asynchronous I/O operations, use the CancelIo function. This function only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

If you are attempting to write to a floppy drive that does not have a floppy disk, the system displays a message box prompting the user to retry the operation. To prevent the system from displaying this message box, call the SetErrorMode function with SEM_NOOPENFILEERRORBOX.

See Also

CreateFile, GetLastError, ReadFile, SetEndOfFile


ObjectNotify

This function is called by the server when there is a change or deletion to an object in the device’s object store. ObjectNotify prompts the client if it is interested in this change or deletion. If so, the object identifier the client needs for serialization or de-serialization of the object is sent to the desktop.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ObjectNotify(POBJNOTIFY pNotify);

Parameters

pNotify
[in] Pointer to the OBJNOTIFY structure.

Return Valuess

TRUE indicates that the change or deletion should be synchronized.

Remarks

The ObjectNotify function is not implemented for emulation.


OffsetRect

This function moves the specified rectangle by the specified offsets.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL OffsetRect(LPRECT lprc, int dx, int dy);

Parameters

lprc
Long pointer to a RECT structure that contains the logical coordinates of the rectangle to be moved.
dx
Specifies the amount to move the rectangle left or right. This parameter must be a negative value to move the rectangle to the left.
dy
Specifies the amount to move the rectangle up or down. This parameter must be a negative value to move the rectangle up.

Return Values

Nonzero indicates success. Zero indicates failure.

Windows NT: To get extended error information, call GetLastError.

See Also

InflateRect, IntersectRect, UnionRect, RECT


OleCreate

This function creates an embedded object identified by a CLSID. It is typically used to implement a menu item that allows the end user to insert a new object.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI OleCreate( REFCLSID rclsid, REFIID riid,
DWORD renderopt, FORMATETC * pFormatEtc,
IOleClientSite * pClientSite, IStorage * pStg, void ** ppvObject);

Parameters

rclsid
[in] CLSID of the embedded object that is to be created.
riid
[in] Reference to the identifier of the interface, usually IID_IOleObject (defined in the OLE headers as the interface identifier for IOleObject), through which the caller will communicate with the new object.
renderopt
[in] Value from the enumeration OLERENDER, indicating the locally cached drawing capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.
pFormatEtc
[in] Depending on which of the OLERENDER flags is used as the value of renderopt, pointer to one of the FORMATETC enumeration values. Refer to the OLERENDER enumeration for restrictions. This parameter, along with the renderopt parameter, specifies what the new object can cache initially.
pClientSite
[in] If you want OleCreate to call IOleObject::SetClientSite, pClientSite is the pointer to the IOleClientSite interface on the container. The value can be NULL, in which case you must specifically call IOleClientSite::SetClientSite before attempting operations.
pStg
[in] Pointer to an instance of the IStorage interface on the storage object. This parameter cannot be NULL.
ppvObject
[out] Pointer to the pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObject contains the requested interface pointer.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

Value
Description
S_OK Embedded object created successfully.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

The OleCreate function creates a new embedded object, and is typically called to implement the menu item Insert New Object. When OleCreate returns, the object it has created is blank (contains no data), unless renderopt is OLERENDER_DRAW or OLERENDER_FORMAT, and is loaded. Containers typically then call the OleRun function or IOleObject::DoVerb to show the object for initial editing.

The rclsid parameter specifies the CLSID of the requested object. CLSIDs of registered objects are stored in the system registry. When an application user selects Insert Object, a selection box allows the user to select the type of object desired from those in the registry. When OleCreate is used to implement the Insert Object menu item, the CLSID associated with the selected item is assigned to the rclsid parameter of OleCreate.

The riid parameter specifies the interface the client will use to communicate with the new object. Upon successful return, the ppvObject parameter holds a pointer to the requested interface.

The created object's cache contains information that allows a presentation of a contained object when the container is opened. Information about what should be cached is passed in the renderopt and pFormatetc values. When OleCreate returns, the created object's cache is not necessarily filled. Instead, the cache is filled the first time the object enters the running state. The caller can add additional cache control with a call to IOleCache::Cache after the return of OleCreate and before the object is run. If renderopt is OLERENDER_DRAW or OLERENDER_FORMAT, OleCreate requires that the object support the IOleCache interface. There is no such requirement for any other value of renderopt.

If pClientSite is non-NULL, OleCreate calls IOleObject::SetClientSite through the pClientSite pointer. IOleClientSite is the primary interface by which an object requests services from its container. If pClientSite is NULL, you must make a specific call to IOleObject::SetClientSite before attempting any operations.


OleDraw

This helper function provides a convenient way to draw objects by encapsulating the IViewObject::Draw method and other related maintenance functions for the drawing rectangle.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI OleDraw(IUnknown * pUnk, DWORD dwAspect,
HDC hdcDraw, LPCRECT lprcBounds);

Parameters

pUnk
[in] Pointer to the IUnknown interface on the view object that is to be drawn.
dwAspect
[in] Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT. See DVASPECT for more information.
hdcDraw
[in] Handle to the device context (DC) on which to draw. Cannot be a metafile device context.
lprcBounds
[in] Long pointer to a RECT structure specifying the rectangle in which the object should be drawn. This parameter is converted to a RECTL structure and passed to IViewObject::Draw.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

Value
Description
S_OK | Object was successfully drawn.
OLE_E_BLANK | No data to draw from.
E_ABORT | The draw operation was aborted.
VIEW_E_DRAW | An error occurred in drawing.
OLE_E_INVALIDRECT | The rectangle is invalid.
DV_E_NOIVIEWOBJECT | The object does not support the IViewObject interface.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

The OleDraw helper function calls the QueryInterface method for the object specified (pUnk), asking for an IViewObject interface on that object. Then, OleDraw converts the RECT structure to a RECTL structure, and calls IViewObject::Draw as follows:

lpViewObj->Draw(dwAspect,-1,0,0,0,hdcDraw,&rectl,0,0,0);

Do not use OleDraw to draw into a metafile because it does not specify the lprcWBounds parameter required for drawing into metafiles.


OleIsRunning

This function determines whether a compound document object is currently in the running state.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

BOOL OleIsRunning(LPOLEOBJECT pObject);

Parameter

pObject
[in] Pointer to the IOleObject interface on the object of interest.

Return Value

The return value is TRUE if the object is running; otherwise, it is FALSE.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

You can use OleIsRunning and IRunnableObject::IsRunning interchangeably. OleIsRunning queries the object for a pointer to the IRunnableObject interface and calls its IsRunning method. If successful, the function returns the results of the call to IRunnableObject::IsRunning.

Note The implementation of OleIsRunning in earlier versions of OLE differs from that described here.


OleRun

This function puts an OLE compound document object into the running state.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI OleRun(LPUNKNOWN pUnknown);

Parameter

pUnknown
[in] Pointer to the IUnknown interface on the object, with which it will query for a pointer to the IRunnableObject interface, and then call its Run method.

Return Values

This function supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK
The object was successfully placed in the running state.
OLE_E_CLASSDIFF
The source of an OLE link has been converted to a different class.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

The OleRun function puts an object in the running state. The implementation of OleRun was changed in OLE 2.01 to coincide with the publication of the IRunnableObject interface. You can use OleRun and IRunnableObject::Run interchangeably. OleRun queries the object for a pointer to IRunnableObject. If successful, the function returns the results of calling the IRunnableObject::Run method.

Note The implementation of OleRun in earlier versions of OLE differs from that described here.


OleSave

This function saves an object opened in transacted mode into the specified storage object.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI OleSave( IPersistStorage * pPS, IStorage * pStg,
BOOL fSameAsLoad );

Parameters

pPS
[in] Pointer to the IPersistStorage interface on the object to be saved.
pStg
[in] Pointer to the IStorage interface on the destination storage object to which the object indicated in pPS is to be saved.
fSameAsLoad
[in] Boolean that is set to TRUE if pStg is the same storage object from which the object was loaded or created, or to FALSE if pstg was loaded or created from a different storage object.

Return Values

S_OK
The object was successfully saved.
STG_E_MEDIUMFULL
The object could not be saved due to lack of disk space.

This function can also return any of the error values returned by the IPersistStorage::Save method.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

The OleSave helper function handles the common situation in which an object is open in transacted mode and is then to be saved into the specified storage object which uses the OLE-provided compound file implementation. Transacted mode means that changes to the object are buffered until either of the IStorage methods Commit or Revert is called. Callers can handle other situations by calling the IPersistStorage and IStorage interfaces directly.

OleSave does the following:

  1. Calls the IPersistStorage::GetClassID method to get the CLSID of the object.
  2. Writes the CLSID to the storage object using the WriteClassStg function.
  3. Calls the IPersistStorage::Save method to save the object.
  4. If there were no errors on the save; calls the IStorage::Commit method to commit the changes.

Note Static objects are saved into a stream called CONTENTS. Static metafile objects get saved in "placeable metafile format" and static DIB data gets saved in "DIB file format." These formats are defined to be the OLE standards for metafile and DIB. All data transferred using an IStream interface or a file transferred using IDataObject::GetDataHere must be in these formats. Also, all objects whose default file format is a metafile or DIB must write their data into a CONTENTS stream using these standard formats.


OleSetContainedObject

This function notifies an object embedded in an OLE container to ensure correct reference.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI OleSetContainedObject( LPUNKNOWN pUnk,
BOOL fContained );

Parameters

pUnk
[in] Pointer to the IUnknown interface of the object.
fContained
[in] Boolean that is set to TRUE if the object is an embedded object, or to FALSE otherwise.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK
The object was notified successfully.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

The OleSetContainedObject function notifies an object that it is embedded in an OLE container. The implementation of OleSetContainedObject was changed in OLE 2.01 to coincide with the publication of the IRunnableObject interface. You can use OleSetContainedObject and the IRunnableObject::SetContainedObject method interchangeably. The OleSetContainedObject function queries the object for a pointer to the IRunnableObject interface. If successful, the function returns the results of calling IRunnableObject::SetContainedObject.

Note The implementation of OleSetContainedObject in earlier versions of OLE differs from that described here.


OleSetMenuDescriptor

This function installs or removes OLE dispatching code from the container’s frame window.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI OleSetMenuDescriptor ( HOLEMENU holemenu,
HWND hwndFrame, HWND hwndActiveObject,
LPOLEINPLACEFRAME lpFrame,
LPOLEINPLACEACTIVEOBJECT lpActiveObj );

Parameters

holemenu
[in] Handle to the composite menu descriptor returned by the OleCreateMenuDescriptor function. If NULL, the dispatching code is unhooked.
hwndFrame
[in] Handle to the container's frame window where the in-place composite menu is to be installed.
hwndActiveObject
[in] Handle to the object's in-place activation window. OLE dispatches menu messages and commands to this window.
lpFrame
[in] Long pointer to the IOleInPlaceFrame interface on the container's frame window.
lpActiveObj
[in] Long pointer to the IOleInPlaceActiveObject interface on the active in-place object.

Return Values

This function supports the standard return values E_FAIL, E_INVALIDARG and E_UNEXPECTED, as well as the following:

S_OK
The menu was installed correctly.

Remarks

The hwndActiveObject and the lpActiveObj parameters are not supported. Set to NULL.

The container should call OleSetMenuDescriptor to install the dispatching code on hwndFrame when the object calls the IOleInPlaceFrame::SetMenu method, or to remove the dispatching code by passing NULL as the value for holemenu to OleSetMenuDescriptor.

If both the lpFrame and lpActiveObj parameters are non-NULL, OLE installs the context-sensitive help F1 message filter for the application. Otherwise, the application must supply its own message filter.


OpenProcess

This function returns a handle to an existing process object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

HANDLE OpenProcess( DWORD fdwAccess, BOOL fInherit,
DWORD IDProcess);

Parameters

dwDesiredAccess
Not supported; set to zero.
bInheritHandle
Not supported; set to FALSE.
dwProcessId
Specifies the process identifier of the process to open.

Return Values

An open handle to the specified process indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The handle returned by the OpenProcess function can be used in any function that requires a handle to a process, such as the wait functions, provided the appropriate access rights were requested.

When you are finished with the handle, be sure to close it using the CloseHandle function.


OutputDebugString

This function sends a string to the debugger for the current application.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void OutputDebugString(LPCTSTR lpszOutputString);

Parameters

lpOutputString
Pointer to the null-terminated string to be displayed.

Return Values

None.

Remarks

Windows CE supports only the Unicode version of this function.

If the application has no debugger, the system debugger displays the string. If the application has no debugger and the system debugger is not active, OutputDebugString does nothing.


Process32First

This function retrieves information about the first process encountered in a system snapshot.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Process32First( HANDLE hSnapshot, LPPROCESSENTRY32 lppe);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lppe
Pointer to a PROCESSENTRY32 structure.

Return Value

TRUE indicates that the first entry of the process list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no processes exist or the snapshot does not contain process information.

Remarks

The calling application must set the dwSize member of PROCESSENTRY32 to the size, in bytes, of the structure. Process32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other processes recorded in the same snapshot, use the Process32Next function.


Process32Next

This function retrieves information about the next process recorded in a system snapshot.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Process32Next( HANDLE hSnapshot, LPPROCESSENTRY32 lppe);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lppe
Pointer to a PROCESSENTRY32 structure.

Return Value

TRUE indicates that the next entry of the process list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no processes exist or the snapshot does not contain process information.

Remarks

To retrieve information about the first process recorded in a snapshot, use the Process32First function.


PtInRect

This function determines whether the specified point lies within the specified rectangle. A point is within a rectangle if it lies on the left or top side or is within all four sides. A point on the right or bottom side is considered outside the rectangle.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL PtInRect(const RECT *lprc, POINT pt);

Parameters

lprc
Long pointer to a RECT structure that contains the specified rectangle.
pt
Specifies a POINT structure that contains the specified point.

Return Values

Nonzero indicates that the specified point lies within the rectangle. Zero indicates that the specified point does not lie within the rectangle.

To get extended error information, call GetLastError.

See Also

EqualRect, IsRectEmpty, POINT, RECT


PulseEvent

This function provides a single operation that sets (to signaled) the state of the specified event object and then resets it (to nonsignaled) after releasing the appropriate number of waiting threads.

At a Glance

Header file: | Kfuncs.h
Versions: | 1.0 and later

Syntax

BOOL PulseEvent(HANDLE hEvent);

Parameters

hEvent
Handle to the event object. The CreateEvent function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

For a manual-reset event object, all waiting threads that can be released immediately are released. The function then resets the event object’s state to nonsignaled and returns.

For an auto-reset event object, the function resets the state to nonsignaled and returns after releasing a single waiting thread, even if multiple threads are waiting.

If no threads are waiting, or if no thread can be released immediately, PulseEvent simply sets the event object’s state to nonsignaled and returns.

Note that for a thread using the multiple-object wait functions to wait for all specified objects to be signaled, PulseEvent can set the event object’s state to signaled and reset it to nonsignaled without causing the wait function to return. This happens if not all of the specified objects are simultaneously signaled.

See Also

CreateEvent, ResetEvent, SetEvent, WaitForSingleObject


QueryPerformanceCounter

This function retrieves the current value of the high-resolution performance counter if one is provided by the OEM.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL QueryPerformanceCounter(
LARGE_INTEGER * lpPerformanceCount);

Parameters

lpPerformanceCount
Pointer to a variable that the function sets, in counts, to the current performance-counter value. If the installed hardware does not support a high-resolution performance counter, this parameter can be to zero.

Return Values

Nonzero indicates that the installed hardware supports a high-resolution performance counter. Zero indicates that the installed hardware does not support a high-resolution performance counter.

See Also

QueryPerformanceFrequency


QueryPerformanceFrequency

This function retrieves the frequency of the high-resolution performance counter if one is provided by the OEM.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL QueryPerformanceFrequency (LARGE_INTEGER * lpFrequency);

Parameters

lpFrequency
Pointer to a variable that the function sets, in counts per second, to the current performance-counter frequency. If the installed hardware does not support a high-resolution performance counter, this parameter can be to zero.

Return Values

Nonzero indicates that the installed hardware supports a high-resolution performance counter. Zero indicates that the installed hardware does not support a high-resolution performance counter.

See Also

QueryPerformanceCounter


RaiseException

This function raises an exception in the calling thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void RaiseException(DWORD dwExceptionCode, DWORD dwExceptionFlags,
DWORD nNumberOfArguments, const DWORD *lpArguments);

Parameters

dwExceptionCode
Specifies the application-defined exception code of the exception being raised. The filter expression and exception-handler block of an exception handler can use the GetExceptionCode function to retrieve this value.

Note that the system will clear bit 28 of dwExceptionCode. This bit is a reserved exception bit, used by the system for its own purposes. For example, after calling the RaiseException function with a dwExceptionCode value of 0xFFFFFFFF, the system displays a message indicating that the exception number is 0xEFFFFFFF.

dwExceptionFlags
Specifies the exception flags. This can be either zero to indicate a continuable exception, or EXCEPTION_NONCONTINUABLE to indicate a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.
nNumberOfArguments
Specifies the number of arguments in the lpArguments array. This value must not exceed EXCEPTION_MAXIMUM_PARAMETERS. This parameter is ignored if lpArguments is NULL.
lpArguments
Long pointer to an array of 32-bit arguments. This parameter can be NULL. These arguments can contain any application-defined data that needs to be passed to the filter expression of the exception handler.

Return Values

None.

Remarks

The RaiseException function enables a process to use structured exception handling to handle private, software-generated, application-defined exceptions.

Raising an exception causes the exception dispatcher to go through the following search for an exception handler:

  1. The system first attempts to notify the process’s debugger, if any.
  2. If the process is not being debugged, or if the associated debugger does not handle the exception, the system attempts to locate a frame-based exception handler by searching the stack frames of the thread in which the exception occurred. The system searches the current stack frame first, then proceeds backward through preceding stack frames.
  3. If no frame-based handler can be found, or no frame-based handler handles the exception, the system makes a second attempt to notify the process’s debugger.
  4. If the process is not being debugged, or if the associated debugger does not handle the exception, the system provides default handling based on the exception type.

The values specified in the dwExceptionCode, dwExceptionFlags, nNumberOfArguments, and lpArguments parameters can be retrieved in the filter expression of a try-except frame-based exception handler by calling the GetExceptionInformation function. A debugger can retrieve these values by calling the WaitForDebugEvent function.

See Also

GetExceptionCode, GetExceptionInformation


Random

This function generates a random number.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD Random();

Return Values

A randomly generated DWORD.


RapiFreeBuffer

This function frees the memory on the desktop computer allocated by a call to CeFindAllDatabases, CeFindAllFiles, or CeReadRecordProps.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and 1.1

Syntax

HRESULT RapiFreeBuffer( LPVOID Buffer );

Parameters

Buffer
[in] Pointer to the buffer to be freed.

Return Values

S_OK indicates success. E_FAIL indicates failure.

Remarks

Any RAPI function that allocates memory on the desktop computer on the users’ behalf must be freed by calling the RapiFreeBuffer function.

For Windows CE versions 2.0 and later, the name of this function is CeRapiFreeBuffer.


ReadClassStg

This function reads the CLSID previously written to a storage object with the WriteClassStg.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI ReadClassStg( IStorage * pStg, CLSID * pclsid);

Parameters

pStg
[in] Pointer to the IStorage interface on the storage object containing the CLSID to be retrieved.
pclsid
[out] Pointer to where the CLSID is written. Can return CLSID_NULL.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK
The CLSID was returned successfully.

This function also returns any of the error values returned by the IStorage::Stat method.

Windows CE Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Remarks

This function is simply a helper function that calls the IStorage::Stat method and retrieves the CLSID previously written to the storage object with a call to WriteClassStg from the STATSTG structure.


ReadClassStm

This function reads the CLSID previously written to a stream object with the WriteClassStm method.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI ReadClassStm( IStream * pStm, CLSID * pclsid);

Parameters

pStm
[in] Pointer to the IStream interface on the stream object containing the CLSID to be read. This CLSID must have been previously written to the stream object using WriteClassStm.
pclsid
[out] Pointer to where the CLSID is to be written.

Return Values

S_OK
The CLSID was successfully retrieved.
STG_E_READFAULT
End of file was reached.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Most applications do not call the ReadClassStm method directly.


ReadFile

This function reads data from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL ReadFile( HANDLE hFile, LPVOID lpBuffer,
DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped );

Parameters

hFile
[in] Handle to the file to be read. The file handle must have been created with GENERIC_READ access to the file. This parameter cannot be a socket handle.
lpBuffer
[out] Pointer to the buffer that receives the data read from the file.
nNumberOfBytesToRead
[in] Number of bytes to be read from the file.
lpNumberOfBytesRead
[out] Pointer to the number of bytes read. ReadFile sets this value to zero before doing any work or error checking.
lpOverlapped
[in] Unsupported; set to NULL.

Return Values

The ReadFile function returns when one of the following is true: the number of bytes requested has been read or an error occurs.

Nonzero indicates success. If the return value is nonzero and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read operation. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes.

When reading from a communications device, the behavior of ReadFile is governed by the current communication time-outs as set and retrieved using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information about communication time-outs, see COMMTIMEOUTS.

The ReadFile function may fail and return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. Windows CE does not support asynchronous read operations on files. The following sample code tests for end-of-file for a synchronous read operation:

// Attempt a synchronous read operation.
bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ;
// Check for end of file.
if (bResult &&  nBytesRead == 0, )
{
    // we’re at the end of the file
}

See Also

CreateFile, GetCommTimeouts, SetCommTimeouts, WriteFile, COMMTIMEOUTS


ReadProcessMemory

This function reads memory in a specified process. The entire area to be read must be accessible, or the operation fails.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ReadProcessMemory( HANDLE hProcess, LPCVOID lpBaseAddress,
LPVOID lpBuffer, DWORD nSize, LPDWORD lpNumberOfBytesRead);

Parameters

hProcess
Handle to the process whose memory is being read. In Windows CE, any call to OpenProcess will return a process handle with the proper access rights.
lpBaseAddress
Pointer to the base address in the specified process to be read. Before any data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for read access. If this is the case, the function proceeds; otherwise, the function fails.
lpBuffer
Pointer to a buffer that receives the contents from the address space of the specified process.
nSize
Specifies the requested number of bytes to read from the specified process.
lpNumberOfBytesRead
Pointer to the actual number of bytes transferred into the specified buffer. If lpNumberOfBytesRead is NULL, the parameter is ignored.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

The function fails if the requested read operation crosses into an area of the process that is inaccessible.

Remarks

ReadProcessMemory copies the data in the specified address range from the address space of the specified process into the specified buffer of the current process. The process whose address space is read is typically, but not necessarily, being debugged.

The entire area to be read must be accessible. If it is not, the function fails as noted previously.

See Also

WriteProcessMemory


RegCloseKey

This function releases the handle of the specified key. A remote application interface (RAPI) version of this function exists, and it is called CeRegCloseKey.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegCloseKey( HKEY hKey );

Parameters

hKey
[in] Handle to the open key to close.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The handle for a specified key should not be used after it has been closed, because it will no longer be valid. Key handles should not be left open any longer than necessary.

The RegCloseKey function always writes information to the registry before returning, eliminating the need to flush keys in the Windows CE registry.

See Also

RegCreateKeyEx, RegDeleteKey, RegOpenKeyEx, RegSetValueEx


RegCreateKeyEx

This function creates the specified key. If the key already exists in the registry, the function opens it. A remote application interface (RAPI) version of this function exists, and it is called CeRegCreateKeyEx.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegCreateKeyEx( HKEY hKey, LPCWSTR lpszSubKey,
DWORD Reserved, LPWSTR lpszClass, DWORD dwOptions,
REGSAM samDesired, LPSECURITY_ATTRIBUTES lpSecurityAttributes,
PHKEY phkResult, LPDWORD lpdwDisposition );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

Windows CE does not support the HKEY_CURRENT_CONFIG, HKEY_PERFORMANCE_DATA, or HKEY_DYN_DATA predefined reserved handle values.

The key opened or created by the RegCreateKeyEx function is a subkey of the key identified by the hKey parameter.

lpSubKey
[in] Pointer to a null-terminated string specifying the name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter. This subkey must not begin with the backslash character (‘\’). This parameter cannot be NULL. In Windows CE, the maximum length of a key name is 255 characters, not including the terminating NULL character. You can also only nest 16 levels of sub-keys in Windows CE.
Reserved
[in] Reserved; set to 0.
lpClass
[in] Pointer to a null-terminated string that specifies the class (object type) of this key. This parameter is ignored if the key already exists. In Windows CE, the maximum length of a class string is 255 characters, not including the terminating NULL character.
dwOptions
[in] Ignored; set to 0 to ensure compatibility with future versions of Windows CE.
samDesired
[in] Ignored; set to 0 to ensure compatibility with future versions of Windows CE.
lpSecurityAttributes
[in] Set to NULL. Windows CE automatically assigns the key a default security descriptor.
phkResult
[out] Pointer to a variable that receives a handle to the opened or created key. When you no longer need the returned handle, call the RegCloseKey function to close it.
lpdwDisposition
[out] Pointer to a variable that receives one of the following disposition values:
Value
Description
REG_CREATED_NEW_KEY | The key did not exist and was created.
REG_OPENED_EXISTING_KEY | The key existed and was simply opened without being changed.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key that the RegCreateKeyEx function creates has no values. An application can use the RegSetValueEx function to set key values.

The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

RegCreateKeyEx can create keys under the HKEY_LOCAL_MACHINE and HKEY_USERS registries.

An application can use RegCreateKeyEx to temporarily lock a portion of the registry. When the locking process creates a new key, it receives the disposition value REG_CREATED_NEW_KEY, indicating that it “owns” the lock. Another process attempting to create the same key receives the disposition value REG_OPENED_EXISTING_KEY, indicating that another process already owns the lock.

See Also

RegDeleteKey


RegDeleteKey

This function deletes a named subkey from the specified registry key. The subkey to be deleted cannot have any subkeys.

A remote application interface (RAPI) version of this function exists, and it is called CeRegDeleteKey.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegDeleteKey( HKEY hKey, LPCWSTR lpszSubKey );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The key specified by the lpSubKey parameter must be a subkey of the key identified by hKey.

lpSubKey
[in] Pointer to a null-terminated string specifying the name of the key to delete. This parameter cannot be NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

If the function succeeds, RegDeleteKey removes the specified key from the registry. The entire key, including all of its values, is removed. An application cannot call RegDeleteKey for a key that an application currently has open.

To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

See Also

RegCloseKey, RegCreateKeyEx, RegOpenKeyEx


RegDeleteValue

This function removes a named value from the specified registry key. A remote application interface (RAPI) version of this function exists, and it is called CeRegDeleteValue.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegDeleteValue( HKEY hKey, LPCWSTR lpszValueName );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpValueName
[in] Pointer to a null-terminated string that names the value to remove. If this parameter is NULL or points to an empty string, the default value of the key is removed. A default value is create by calling RegCreateValueEx with a NULL or empty string value name.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).

See Also

RegSetValueEx


RegEnumKeyEx

This function enumerates subkeys of the specified open registry key. RegEnumKeyEx retrieves information about one subkey each time it is called and it retrieves the class name of the subkey and the time it was last modified.

A remote application interface (RAPI) version of this function exists, and it is called CeRegEnumKeyEx.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegEnumKeyEx(HKEY hKey, DWORD dwIndex,
LPWSTR lpName, LPDWORD lpcbName, LPDWORD lpReserved,
LPWSTR lpClass, LPDWORD lpcbClass, PFILETIME lpftLastWriteTime );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The enumerated keys are subkeys of the key identified by hKey.

dwIndex
[in] Specifies the index of the subkey to retrieve. This parameter should be zero for the first call to the RegEnumKeyEx function and then incremented for subsequent calls.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.

lpName
[out] Pointer to a buffer that receives the name of the subkey, including the terminating null character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.
lpcbName
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer specified by the lpName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.
lpReserved
[in] Reserved; set to NULL.
lpClass
[out] Pointer to a buffer that contains the class of the enumerated subkey when the function returns. This parameter can be NULL if the class is not required.
lpcbClass
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer specified by the lpClass parameter. The size should include the terminating null character. When the function returns, lpcbClass contains the number of characters stored in the buffer. The count returned does not include the terminating null character. This parameter can be NULL only if lpClass is NULL.
lpftLastWriteTime
[in] Ignored; set to NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

To enumerate subkeys, an application should initially call the RegEnumKeyEx function with the dwIndex parameter set to zero. An application should then increment the dwIndex parameter and call RegEnumKeyEx until there are no more subkeys (until the function returns ERROR_NO_MORE_ITEMS).

An application can also set dwIndex to the index of the last subkey on the first call to the function and decrement the index until the subkey with the index 0 is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey function.

While an application is using the RegEnumKeyEx function, it should not make calls to any registration functions that might change the key being enumerated.

The key identified by hKey must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ includes KEY_ENUMERATE_SUB_KEYS). Use the RegCreateKeyEx or RegOpenKeyEx function to open the key.

See Also

RegCreateKeyEx, RegDeleteKey, RegOpenKeyEx, RegQueryInfoKey


RegEnumValue

This function enumerates the values for the specified open registry key. RegEnumValue copies one indexed value name and data block for the key each time it is called.

A remote application interface (RAPI) version of this function exists, and it is called CeRegEnumValue.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegEnumValue( HKEY hKey, DWORD dwIndex,
LPWSTR lpszValueName, LPDWORD lpcchValueName,
LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData,
LPDWORD lpcbData );

Parameters

hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The enumerated values are associated with the key identified by hKey.

dwIndex
[in] Specifies the index of the value to retrieve. This parameter should be zero for the first call to the RegEnumValue function and then be incremented for subsequent calls.

Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.

lpValueName
[out] Pointer to a buffer that receives the name of the value, including the terminating null character.
lpcbValueName
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbValueName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.
lpReserved
[in] Reserved; set to NULL.
lpType
[out] Pointer to a variable that receives the type code for the value entry. The type code can be one of the following values:
Value
Description
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format. This is equivalent to REG_DWORD.
In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format.
In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.

The lpType parameter can be NULL if the type code is not required.

lpData
[out] Pointer to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required.
lpcbData
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if lpData is NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

To enumerate values, an application should initially call the RegEnumValue function with the dwIndex parameter set to zero. The application should then increment dwIndex and call the RegEnumValue function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0 is enumerated. To retrieve the index of the last value, use the RegQueryInfoKey function.

While using RegEnumValue, an application should not call any registration functions that might change the key being queried.

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

To determine the maximum size of the name and data buffers, use the RegQueryInfoKey function.

See Also

RegCreateKeyEx, RegEnumKeyEx, RegOpenKeyEx, RegQueryInfoKey


RegFlushKey

This function writes all the attributes of the specified open key into the registry.

A remote application interface (RAPI) version of this function exists, and it is called CeRegFlushKey.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 2.10 and later

Syntax

LONG RegFlushKey( HKEY hKey );

Parameters

hKey
[in] Handle to a currently open key, which is validated but ignored. It can also be one of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

If RegFlushKey is called, the operating system attempts to flush the entire registry to the platform-supported storage. The implementation of this function OEM-dependent, which results in the following scenarios:

  • If an OEM does not support persistent registry storage, then a call to this function fails.
  • If an OEM does support persistent registry storage, then a call to this function flushes the entire registry to the OEM for storage.
  • If the OEM fails the flush request, then RegFlushKey fails.

Unlike RegCloseKey, the RegFlushKey function returns only when all the data has been written to the registry.

The RegFlushKey function may also write out parts of or all of the other keys. Calling this function excessively can have a negative effect on an application’s performance.

By default, Windows CE does not support a lazy flush of the registry; therefore, it is important that all applications call RegFlushKey to save important registry information. Call RegFlushKey after a group of changes have been made, but not for every individual registry change. Frequent calling of RegFlushKey can degrade performance. Platforms that need to implement a lazy-flush or power-down flush can do so by calling RegFlushKey at anytime from a shell, from a low priority thread, or in the power-off switch handler in the keyboard driver.


RegisterDevice

This function registers a new device.

At a Glance

Header file: | Winbase.h
Versions: | 1.0 and later

Syntax

HANDLE RegisterDevice( LPCWSTR lpszType DWORD dwIndex LPCWSTR lpszLib DWORD dwInfo);

Parameters

lpszType
Long pointer to the null-terminated string that contains the device identifier prefix (for example COM, DEV, PGR); must be 3 characters long.
dwIndex
Specifies the device identifier index; must be a number from 0 through 9. For example, the index value for COM2 would be 2.
lpszLib
Long pointer to the null-terminated string that contain that device driver DLL module name.
dwInfo
Specifies instance information.

Return Value

A handle to a device indicates success. Zero indicates failure. This is passed to the following functions that are exported by the client driver: PRE_Open, PRE_Deinit, PRE_PowerUp, and PRE_PowerDown.

For stream-based devices, the drivers are DLL files. Each driver is initialized by a call to the RegisterDevice function (performed by the server process). The IpszLib parameter is used to open the device. The IpszType parameter is a three character string which is used to identify the function entry points in the DLL, so that multiple devices can exist in one DLL. The lpszLib parameter is the name of the DLL that contains the entry points. Finally dwInfo is passed in to the initialization routine. So, for example, if there were two serial ports on a device, and Comm.dll was the DLL implementing the serial driver, it would likely present the following initialization calls:

h1 = RegisterDevice(L"COM", 1, L"comm.dll",0x3f8);
hs

Remarks

The DeregisterDevice function can be used if a device is removed from the system or is being shut down. An example would be:

DeregisterDevice(h1);

where h1 was returned from a call to RegisterDevice.

See Also

DeregisterDevice


RegisterTypeLib

This function adds information about a type library to the system registry.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT RegisterTypeLib( ITypeLib FAR* ptlib, OLECHAR FAR* szFullPath, OLECHAR FAR* szHelpDir);

Parameters

ptlib
Pointer to the type library being registered.
szFullPath
Null-terminated string that contains the fully qualified path specification for the type library being registered.
szHelpDir
Null-terminated string that contains the directory in which the Help file for the library being registered can be found. Can be NULL.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | One or more of the arguments is invalid.
TYPE_E_IOERROR | The function could not write to the file.
TYPE_E_REGISTRYACCESS | The system registration database could not be opened.
TYPE_E_INVALIDSTATE | The type library could not be opened.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

The function RegisterTypeLib can be used during application initialization to register the application’s type library correctly.

In addition to filling in a complete registry entry under the type library key, RegisterTypeLib adds entries for each of the dispinterfaces and Automation-compatible interfaces, including dual interfaces. This information is required to create instances of these interfaces. Coclasses are not registered (that is, RegisterTypeLib does not write any values to the CLSID key of the coclass).


RegOpenKeyEx

This function opens the specified key.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegOpenKeyEx( HKEY hKey, LPCWSTR lpszSubKey,
DWORD ulOptions, REGSAM samDesired, PHKEY phkResult );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

Windows CE does not support the HKEY_CURRENT_CONFIG, HKEY_PERFORMANCE_DATA, or HKEY_DYN_DATA predefined reserved handle values.

lpSubKey
[in] Pointer to a null-terminated string containing the name of the subkey to open. If this parameter is NULL or a pointer to an empty string, the function will open a new handle to the key identified by the hKey parameter. In this case, the function will not close the handles previously opened.
ulOptions
[in] Reserved; set to 0.
samDesired
[in] Not supported; set to zero.
phkResult
[out] Pointer to a variable that receives a handle to the opened key. When you no longer need the returned handle, call the RegCloseKey function to close it.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

Unlike the RegCreateKeyEx function, the RegOpenKeyEx function does not create the specified key if the key does not exist in the registry.

See Also

RegCreateKeyEx, RegDeleteKey


RegQueryInfoKey

This function retrieves information about a specified registry key.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegQueryInfoKey ( HKEY hKey, LPWSTR lpClass,
LPDWORD lpcbClass, LPDWORD lpReserved, LPDWORD lpcSubKeys,
LPDWORD lpcbMaxSubKeyLen, LPDWORD lpcbMaxClassLen,
LPDWORD lpcValues, LPDWORD lpcbMaxValueNameLen,
LPDWORD lpcbMaxValueLen, LPDWORD lpcbSecurityDescriptor,
PFILETIME lpftLastWriteTime );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpClass
[out] Pointer to a buffer that receives the key’s class name. This parameter can be NULL.
lpcbClass
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpClass parameter. This size should include the terminating null character. When the function returns, this variable contains the length of the class string stored in the buffer. The count returned does not include the terminating null character. If the buffer is not big enough, the function returns ERROR_MORE_DATA, and the variable contains the size of the string, in characters, without counting the null character.

If lpClass is NULL, lpcbClass can be NULL.

If the lpClass parameter is a valid address, but this parameter is not, the function returns ERROR_INVALID_PARAMETER.

lpReserved
[in] Reserved; set to NULL.
lpcSubKeys
[out] Pointer to a variable that receives the number of subkeys contained by the specified key. This parameter can be NULL.
lpcbMaxSubKeyLen
[out] Pointer to a variable that receives the length, in characters, of the key’s subkey with the longest name. The count returned does not include the terminating null character. This parameter can be NULL.
lpcbMaxClassLen
[out] Pointer to a variable that receives the length, in characters, of the longest string specifying a subkey class. The count returned does not include the terminating null character. This parameter can be NULL.
lpcValues
[out] Pointer to a variable that receives the number of values associated with the key. This parameter can be NULL.
lpcbMaxValueNameLen
[out] Pointer to a variable that receives the length, in characters, of the key’s longest value name. The count returned does not include the terminating null character. This parameter can be NULL.
lpcbMaxValueLen
[out] Pointer to a variable that receives the length, in bytes, of the longest data component among the values of the key. This parameter can be NULL.
lpcbSecurityDescriptor
[in] Not used; set to NULL.
lpftLastWriteTime
[in] Ignored; set to NULL.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

See Also

RegDeleteKey, RegEnumKeyEx, RegEnumValue, RegQueryValueEx


RegQueryValueEx

This function retrieves the type and data for a specified value name associated with an open registry key.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegQueryValueEx( HKEY hKey, LPCWSTR lpValueName,
LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData,
LPDWORD lpcbData );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpValueName
[in] Pointer to a string containing the name of the value to query. If this parameter is NULL or an empty string, the function retrieves the type and data for the key’s unnamed value. A registry key does not automatically have an unnamed or default value. Unnamed values can be of any type.
lpReserved
[in] Reserved; set to NULL.
lpType
[out] Pointer to a variable that receives the type of data associated with the specified value. The value returned through this parameter will be one of the following:
Value
Description
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format. This is equivalent to REG_DWORD.
In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format.
In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”).
REG_LINK | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string.

The lpType parameter can be NULL if the type is not required.

lpData
[out] Pointer to a buffer that receives the value’s data. This parameter can be NULL if the data is not required.
lpcbData
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, this variable contains the size of the data copied to lpData.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then lpcbData will also include the size of the terminating null character.

The lpcbData parameter can be NULL only if lpData is NULL.

If the buffer specified by lpData parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbData.

If lpData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData. This lets an application determine the best way to allocate a buffer for the value’s data.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

The key identified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

Windows CE supports only the Unicode version of this function.

See Also

RegCreateKeyEx, RegEnumKeyEx, RegEnumValue, RegOpenKeyEx, RegQueryInfoKey


RegSetValueEx

This function stores data in the value field of an open registry key. It can also set additional value and type information for the specified key.

At a Glance

Header file: | Winreg.h
Windows CE versions: | 1.0 and later

Syntax

LONG RegSetValueEx( HKEY hKey, LPCWSTR lpValueName,
DWORD Reserved, DWORD dwType, const BYTE *lpData, DWORD cbData );

Parameters

hKey
[in] Handle to a currently open key or any of the following predefined reserved handle values:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
lpValueName
[in] Pointer to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key. If this parameter is NULL or an empty string, the function sets the type and data for the key’s unnamed value. Registry keys do not have default values, but they can have one unnamed value, which can be of any type. The maximum length of a value name is 255, not including the terminating NULL character.
Reserved
[in] Reserved; must be zero.
dwType
[in] Specifies the type of information to be stored as the value’s data. This parameter can be one of the following values:
Value
Description
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format. This is equivalent to REG_DWORD.
In little-endian format, a multi-byte value is stored in memory from the lowest byte (the “little end”) to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format.
In big-endian format, a multi-byte value is stored in memory from the highest byte (the “big end”) to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, “%PATH%”).
REG_LINK | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string.
Do not use the REG_SZ type to store hard-coded paths to the system root directory or to the drive containing the system files. Instead, use the REG_EXPAND_SZ type with environment variables such as "%SystemRoot%". This ensures that the path will be up-to-date even if the user remaps the system drive to a different drive letter.

lpData
[in] Pointer to a buffer containing the data to be stored with the specified value name.
cbData
[in] Specifies the size, in bytes, of the information pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating null character. The maximum size of data allowed in Windows CE is 4 KB.

Return Values

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set.

Remarks

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

Windows CE supports only the Unicode version of this function.

See Also

RegCreateKeyEx, RegOpenKeyEx, RegQueryValueEx


ReleaseMutex

This function releases ownership of the specified mutex object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL ReleaseMutex( HANDLE hMutex);

Parameters

hMutex
[in] Handle to the mutex object. The CreateMutex function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The ReleaseMutex function fails if the calling thread does not own the mutex object.

A thread gets ownership of a mutex by specifying a handle to the mutex in one of the wait functions. The thread that creates a mutex object can also get immediate ownership without using one of the wait functions. When the owning thread no longer needs to own the mutex object, it calls the ReleaseMutex function.

While a thread has ownership of a mutex, it can specify the same mutex in additional wait-function calls without blocking its execution. This prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call ReleaseMutex once for each time that the mutex satisfied a wait.

See Also

CreateMutex


ReleaseStgMedium

This function frees the specified storage medium.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.10 and later

Syntax

void ReleaseStgMedium ( STGMEDIUM * pmedium, );

Parameter

pmedium
[in] Pointer to the storage medium that is to be freed.

Return Value

None.

Remarks

The ReleaseStgMedium function calls the appropriate method or function to release the specified storage medium. Use this function during data transfer operations where storage medium structures are parameters. In addition to identifying the type of the storage medium, this structure specifies the appropriate IUnknown::Release method for releasing the storage medium when it is no longer needed.

It is common to pass a STGMEDIUM from one body of code to another, in which the one called can allocate a medium and return it to the caller. ReleaseStgMedium permits flexibility in whether the receiving body of code owns the medium, or whether the original provider of the medium still owns it, in which case the receiving code needs to inform the provider that it can free the medium.

When the original provider of the medium is responsible for freeing the medium, the provider calls ReleaseStgMedium, specifying the medium and the appropriate IUnknown pointer as the punkForRelease structure member. Depending on the type of storage medium being freed, one of the following actions is taken, followed by a call to the Release method on the specified IUnknown pointer:

Medium
ReleaseStgMedium Action
TYMED_HGLOBAL | None.
TYMED_GDI | None.
TYMED_ENHMF | None.
TYMED_MFPICT | None.
TYMED_FILE | Frees the file name string using standard memory management mechanisms.
TYMED_ISTREAM | Calls IStream::Release.
TYMED_ISTORAGE | Calls IStorage::Release.

The provider indicates that the receiver of the medium is responsible for freeing the medium by specifying NULL for the punkForRelease structure member. Then the receiver calls ReleaseStgMedium, which makes a call as described in the following table depending on the type of storage medium being freed:

Medium
ReleaseStgMedium Action
TYMED_HGLOBAL | Calls the LocalFree function on the handle.
TYMED_GDI | Calls the Win32 DeleteObject function on the handle.
TYMED_ENHMF | Deletes the enhanced metafile.
TYMED_FILE | Frees the disk file by deleting it. Frees the file name string by using the standard memory management paradigm.
TYMED_ISTREAM | Calls IStream::Release.
TYMED_ISTORAGE | Calls IStorage::Release.

In either case, after the call to ReleaseStgMedium, the specified storage medium is invalid and can no longer be used.

See Also

STGMEDIUM


RemoveDirectory

This function deletes an existing empty directory. A remote application interface (RAPI) version of this function exists, and it is called CeRemoveDirectory.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL RemoveDirectory(LPCTSTR lpPathName);

Parameters

lpPathName
[in] Pointer to a null-terminated string that specifies the path of the directory to be removed. The path must specify an empty directory, and the calling process must have delete access to the directory.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

CreateDirectory


ReportStatus

This function is periodically called by the server to get status on the Windows CE platform synchronization objects.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

BOOL ReportStatus(LPWSTR lpszObjType, UINT uCode, UINT uParam);

Parameters

lpszObjType
[in] Long pointer to the null-terminated string that contains the name of the object type. Setting lpszObjType to the string “all object types” returns status for all objects.
uCode
[in] Unsigned integer that contains the status code. For a list of the possible values, see the description for the uStatus parameter of the IReplStore::ReportStatus method.
uParam
[in] Unsigned integer that contains the status parameter. For a description see the uparam parameter of the IReplStore::ReportStatus method.

Return Values

TRUE if successful; otherwise FALSE.


ResetEvent

This function sets the state of the specified event object to nonsignaled.

At a Glance

Header file: | Kfuncs.h
Versions: | 1.0 and later

Syntax

BOOL ResetEvent( HANDLE hEvent );

Parameters

hEvent
Handle to the event object. The CreateEvent function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

ResetEvent returns FALSE if the handle to the event object is invalid.

The state of an event object remains nonsignaled until it is explicitly set to signaled by the SetEvent or PulseEvent function. This nonsignaled state blocks the execution of any threads that have specified the event object in a call to one of the wait functions.

The ResetEvent function is used primarily for manual-reset event objects, which must be set explicitly to the nonsignaled state. Auto-reset event objects automatically change from signaled to nonsignaled after a single waiting thread is released.

See Also

CreateEvent, PulseEvent, SetEvent


ResumeThread

This function decrements a thread’s suspend count. When the suspend count is decremented to zero, the execution of the thread is resumed.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD ResumeThread( HANDLE hThread );

Parameters

hThread
Specifies a handle for the thread to be restarted.

Return Values

The thread’s previous suspend count indicates success. 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

Remarks

The ResumeThread function checks the suspend count of the subject thread. If the suspend count is 0, the thread is not currently suspended. Otherwise, the subject thread’s suspend count is decremented. If the resulting value is 0, then the execution of the subject thread is resumed.

If the return value is 0, the specified thread was not suspended. If the return value is 1, the specified thread was suspended but was restarted. If the return value is greater than 1, the specified thread is still suspended.

Note that while reporting debug events, all threads within the reporting process are frozen. Debuggers are expected to use the SuspendThread and ResumeThread functions to limit the set of threads that can execute within a process. By suspending all threads in a process except for the one reporting a debug event, it is possible to “single step” a single thread. The other threads are not released by a continue operation if they are suspended.

See Also

SuspendThread


SafeArrayAccessData

This function increments the lock count of an array, and retrieves a pointer to the array data.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

SeeHRESULT SafeArrayAccessData( SAFEARRAY FAR * psa,
void HUGEP * FAR * ppvData);

Parameters

psa
[in] Pointer to an array descriptor created by SafeArrayCreate.
ppvData
[in] On exit, pointer to a pointer to the array data.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_UNEXPECTED | The array could not be locked.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

The following code example sorts a safe array of one dimension that contains BSTRs by accessing the array elements directly. This approach is faster than using SafeArrayGetElement and SafeArrayPutElement.

long i, j, min;
BSTR BSTRTemp;
BSTR HUGEP *pBSTR;
HRESULT hr;

// Get a pointer to the elements of the array.
hr = SafeArrayAccessData(psa, (void HUGEP* FAR*)&pBSTR);
if (FAILED(hr))
goto error;

// Bubble sort.
cElements = lUBound–lLBound+1;
for (i = 0; i < cElements–1; i++)
{
    min = i;
    for (j = i+1; j < cElements; j++)
    {
        if (wcscmp(pBSTR[j], pBSTR[min]) < 0)
            min = j;
    }

    // Swap array[min] and array[i].
    BSTRTemp = pBSTR[min];
    pBSTR[min] = pBSTR[i];
    pBSTR[i] = BSTRTemp;

}

SafeArrayUnaccessData(psa);


SafeArrayAllocData

This function allocates memory for a safe array, based on a descriptor created with SafeArrayAllocDescriptor.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayAllocData(SAFEARRAY FAR * psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayAllocDescriptor.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_UNEXPECTED | The array could not be locked.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

The following code example creates a safe array using the SafeArrayAllocDescriptor and SafeArrayAllocData functions.

SAFEARRAY FAR* FAR*ppsa;
unsigned int ndim = 2;
HRESULT HRESULT = SafeArrayAllocDescriptor(ndim, ppsa);
if( FAILED(hresult))
    return ERR_OutOfMemory;
(*ppsa)->rgsabound[ 0 ].lLbound = 0;
(*ppsa)->rgsabound[ 0 ].cElements = 5;
(*ppsa)->rgsabound[ 1 ].lLbound = 1;
(*ppsa)->rgsabound[ 1 ].cElements = 4;
HRESULT = SafeArrayAllocData(*ppsa);
if( FAILED(hresult)) {
    SafeArrayDestroyDescriptor(*ppsa)
    return ERR_OutOfMemory;
}

See Also

SafeArrayDestroyData, SafeArrayDestroyDescriptor


SafeArrayAllocDescriptor

This function allocates memory for a safe array descriptor, allowing the creation of safe arrays that contain elements with data types other than those provided by SafeArrayCreate.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayAllocDescriptor( unsigned int cDims,
SAFEARRAY FAR* FAR* ppsaOut);

Parameters

cDims
Number of dimensions of the array.
ppsaOut
Pointer to a location in which to store the created array descriptor.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_UNEXPECTED | The array could not be locked.

Remarks

This function allows the creation of safe arrays that contain elements with data types other than those provided by SafeArrayCreate. After creating an array descriptor using SafeArrayAllocDescriptor, set the element size in the array descriptor, an call SafeArrayAllocData to allocate memory for the array elements. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

The following code example creates a safe array using the SafeArrayAllocDescriptor and SafeArrayAllocData functions.

SAFEARRAY FAR* FAR*ppsa;
unsigned int ndim = 2;
HRESULT HRESULT = SafeArrayAllocDescriptor( ndim, ppsa );
if( FAILED( HRESULT ) )
    return ERR_OutOfMemory;
(*ppsa)->rgsabound[ 0 ].lLbound = 0;
(*ppsa)->rgsabound[ 0 ].cElements = 5;
(*ppsa)->rgsabound[ 1 ].lLbound = 1;
(*ppsa)->rgsabound[ 1 ].cElements = 4;
HRESULT = SafeArrayAllocData( *ppsa );
if( FAILED( HRESULT ) ) {
    SafeArrayDestroyDescriptor( *ppsa )
    return ERR_OutOfMemory;
}

See Also

SafeArrayAllocData, SafeArrayDestroyData, SafeArrayDestroyDescriptor


SafeArrayCopy

This function creates a copy of an existing safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayCopy(SAFEARRAY FAR* psa,
SAFEARRAY FAR* FAR* ppsaOut);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.
ppsaOut
Pointer to a location in which to return the new array descriptor.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_OUTOFMEMORY | Insufficient memory to create the copy.

Remarks

SafeArrayCopy calls the string or variant manipulation functions if the array to copy contains either of these data types. If the array being copied contains object references, the reference counts for the objects are incremented. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

See Also

SysAllocStringLen, VariantCopy, VariantCopyInd


SafeArrayCopyData

This function copies the source array to the target array after releasing any resources in the target array. This function is similar to SafeArrayCopy, except that the target array has to be set up by the caller. The target is not allocated or reallocated.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayCopyData(SAFEARRAY FAR* psaSource, SAFEARRAY FAR* FAR* psaTarget);

Parameters

psaSource
Pointer to the safe array to be copied.
psaTarget
On exit, pointer to the array referred to by psaTarget that contains a copy of the data in psaSource.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safearray descriptor.
E_OUTOFMEMORY | Insufficient memory to create the copy.

Remarks

Visual Basic for Applications and Automation use the same set of rules with cases in which the size or types of source and destination arrays do not match. The rules of Visual Basic are described in the following comments. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SafeArrayCreate

This function creates a new array descriptor, allocates and initializes the data for the array, and returns a pointer to the new array descriptor.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayCreate( VARTYPE vt, unsigned int cDims, SAFEARRRAYBOUND FAR* rgsabound);

Parameters

vt
Base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal.
cDims
Number of dimensions in the array. The number cannot be changed after the array is created.
rgsabound
Pointer to a vector of bounds (one for each dimension) to allocate for the array.

Return Values

A pointer to the array descriptor indicates success. NULL indicates that the array could not be created.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

HRESULT PASCAL __export CPoly::EnumPoints(IEnumVARIANT FAR* FAR* ppenum)
{
    unsigned int i;
    HRESULT hresult;
    VARIANT var;
    SAFEARRAY FAR* psa;
    CEnumPoint FAR* penum;
    POINTLINK FAR* ppointlink;
    SAFEARRAYBOUND rgsabound[1];
    rgsabound[0].lLbound = 0;
    rgsabound[0].cElements = m_cPoints;
    psa = SafeArrayCreate(VT_VARIANT, 1, rgsabound);
    if(psa == NULL){HRESULT = ReportResult(0, E_OUTOFMEMORY, 0, 0);
        goto LError0}

    // Code omitted here for brevity.

LError0:;
    return hresult;
}


SafeArrayCreateVector

This function creates a one-dimensional array whose lower bound is always zero. A safe array created with SafeArrayCreateVector is a fixed size, so the constant FADF_FIXEDSIZE is always set.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayCreateVector(VARTYPE vt, long lLbound,
unsigned int cElements);

Parameters

vt
Base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal.
lLbound
Lower bound for the array; can be negative.
cElements
Number of elements in the array.

Return Values

A pointer to the array descriptor indicates success. NULL indicates that the array could not be created.

Remarks

SafeArrayCreateVector allocates a single block of memory that contains a SAFEARRAY structure for a single-dimension array (24 bytes), immediately followed by the array data. All of the existing safe array functions work correctly for safe arrays that are allocated with SafeArrayCreateVector.

A SafeArrayCreateVector is allocated as a single block of memory. Both the SafeArray descriptor and the array data block are allocated contiguously in one allocation, which speeds up array allocation. However, a user can allocate the descriptor and data area separately using the SafeArrayAllocDescriptor and SafeArrayAllocData calls. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SafeArrayDestroy

This function destroys an existing array descriptor and all of the data in the array. If objects are stored in the array, Release is called on each object in the array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayDestroy( SAFEARRAY FAR * psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The array is currently locked.
E_INVALIDARG | The item pointed to by psa is not a safe array descriptor.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

STDMETHODIMP_(ULONG) CEnumPoint::Release()
{
    if(--m_refs == 0){
        if(m_psa != NULL)
        SafeArrayDestroy(m_psa);
        delete this;
        return 0;
    }
    return m_refs;
}


SafeArrayDestroyData

This function destroys all the data in a safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayDestroyData( SAFEARRAY FAR * psa);

Parameters

psa
Pointer to an array descriptor.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The array is currently locked.
E_INVALIDARG | The item pointed to by psa is not a safe array descriptor.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Remarks

This function is typically used when freeing safe arrays that contain elements with data types other than variants. If objects are stored in the array, Release is called on each object in the array.

See Also

SafeArrayAllocData, SafeArrayAllocDescriptor, SafeArrayDestroyDescriptor


SafeArrayDestroyDescriptor

This function destroys a decriptor of a safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayDestroyDescriptor(SAFEARRAY FAR * psa);

Parameters

psa
Pointer to a safe array descriptor.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The array is currently locked.
E_INVALIDARG | The item pointed to by psa is not a safe array descriptor.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Remarks

This function is typically used to destroy the descriptor of a safe array that contains elements with data types other than variants. Destroying the array descriptor does not destroy the elements in the array. Before destroying the array descriptor, call SafeArrayDestroyData to free the elements.


SafeArrayGetDim

This function returns the number of dimensions in the array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayGetDim( SAFEARRAY FAR * psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.

Return Values

Returns the number of dimensions in the array.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

HRESULT
CEnumPoint::Create(SAFEARRAY FAR* psa, CEnumPoint FAR* FAR* ppenum)
{
    long lBound;
    HRESULT hresult;
    CEnumPoint FAR* penum;

    // Verify that the SafeArray is the proper shape.
    if(SafeArrayGetDim(psa) != 1)
        return ReportResult(0, E_INVALIDARG, 0, 0);

    // Code omitted here for brevity.

}


SafeArrayGetElement

This function retrieves a single element of the array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayGetElement(SAFEARRAY FAR* psa, long FAR* rgIndices, void FAR* pv);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.
rgIndices
Pointer to a vector of indexes for each dimension of the array. The right-most (least significant) dimension is rgIndices[0]. The left-most dimension is stored at rgIndices[psa->cDims –1].
pv
Void pointer to the location to place the element of the array.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADINDEX | The specified index is invalid.
E_INVALIDARG | One of the arguments is invalid.
E_OUTOFMEMORY | Memory could not be allocated for the element.

Remarks

This function calls SafeArrayLock and SafeArrayUnlock automatically, before and after retrieving the element. The caller must provide a storage area of the correct size to receive the data. If the data element is a string, object, or variant, the function copies the element in the correct way. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

STDMETHODIMP CEnumPoint::Next(
    ULONG celt,
    VARIANT FAR rgvar[],
    ULONG FAR* pceltFetched)
{
    unsigned int i;
    long ix;
    HRESULT hresult;

    for(i = 0; i < celt; ++i)
        VariantInit(&rgvar[i]);

    for(i = 0; i < celt; ++i){
        if(m_iCurrent == m_celts){
        HRESULT = ReportResult(0, S_FALSE, 0, 0);
            goto LDone;
    }

        ix = m_iCurrent++;
        HRESULT = SafeArrayGetElement(m_psa, &ix, &rgvar[i]);
        if(FAILED(hresult))
            goto LError0;
    }
    HRESULT = NOERROR;

LDone:;
    *pceltFetched = i;
    return hresult;

LError0:;
    for(i = 0; i < celt; ++i)
        VariantClear(&rgvar[i]);
    return hresult;
}


SafeArrayGetElemsize

This function retrieves the size (in bytes) of the elements of a safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayGetElemsize(SAFEARRAY FAR* psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.

Return Values

Returns the size (in bytes) of the elements of a safe array.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SafeArrayGetLBound

This function returns the lower bound for any dimension of a safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayGetLBound(SAFEARRAY FAR* psa,
unsigned int nDim, long FAR* plLbound);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.
nDim
Specifies the array dimension for which to get the lower bound.
plLbound
Pointer to the location to return the lower bound.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADINDEX | The specified index is out of bounds.
E_INVALIDARG | One of the arguments is invalid.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

HRESULT
CEnumPoint::Create(SAFEARRAY FAR* psa, CEnumPoint FAR* FAR* ppenum)
{
    long lBound;
    HRESULT hresult;
    CEnumPoint FAR* penum;

    // Verify that the SafeArray is the proper shape.
    HRESULT = SafeArrayGetLBound(psa, 1, &lBound);
    if(FAILED(hresult))
        return hresult;

    // Code omitted here for brevity.

}


SafeArrayGetUBound

This function returns the upper bound for any dimension of a safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayGetUBound(SAFEARRAY FAR* psa,
unsigned int nDim, long FAR* plUbound);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.
nDim
Specifies the array dimension for which to get the upper bound.
plUbound
Pointer to the location to return the upper bound.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADINDEX | The specified index is out of bounds.
E_INVALIDARG | One of the arguments is invalid.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

HRESULT
CEnumPoint::Create(SAFEARRAY FAR* psa, CEnumPoint FAR* FAR* ppenum)
{
    long lBound;
    HRESULT hresult;
    CEnumPoint FAR* penum;

    // Verify that the SafeArray is the proper shape.
    HRESULT = SafeArrayGetUBound(psa, 1, &lBound);
    if(FAILED(hresult))
        goto LError0;

    // Code omitted here for brevity.

LError0:;
    penum->Release();

    return hresult;
}


SafeArrayLock

This function increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayLock(SAFEARRAY FAR* psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_UNEXPECTED | The array could not be locked.

Remarks

The pointer in the array descriptor is valid until SafeArrayUnlock is called. Calls to SafeArrayLock can be nested. An equal number of calls to SafeArrayUnlock are required. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

An array cannot be deleted while it is locked.


SafeArrayPtrOfIndex

This function returns a pointer to an array element.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayPtrOfIndex(SAFEARRAY FAR* psa,
long FAR* rgIndices, void HUGEP* FAR* ppvData);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.
rgIndices
Array of index values that identify an element of the array. All indexes for the element must be specified.
ppvData
On return, pointer to the void pointer to the element identified by the values in rgIndices.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
DISP_E_BADINDEX | The specified index was invalid.

Remarks

The array should be locked before SafeArrayPtrOfIndex is called. Failing to lock the array can cause unpredictable results. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SafeArrayPutElement

This function assigns a single element to the array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayPutElement(SAFEARRAY FAR* psa,
long FAR* rgIndices, void FAR* pv);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.
rgIndices
Pointer to a vector of indexes for each dimension of the array. The right-most (least significant) dimension is rgIndices[0]. The left-most dimension is stored at rgIndices[psa->cDims –1].
pv
Void pointer to the data to assign to the array. The variant types VT_DISPATCH, VT_UNKNOWN, and VT_BSTR are pointers, and do not require another level of indirection.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADINDEX | The specified index was invalid.
E_INVALIDARG | One of the arguments is invalid.
E_OUTOFMEMORY | Memory could not be allocated for the element.

Remarks

This function automatically calls SafeArrayLock and SafeArrayUnlock before and after assigning the element. If the data element is a string, object, or variant, the function copies it correctly. If the existing element is a string, object, or variant, it is cleared correctly. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Note Multiple locks can be on an array. Elements can be put into an array while the array is locked by other operations.

Example

HRESULT PASCAL __export CPoly::EnumPoints(IEnumVARIANT FAR* FAR* ppenum)
{
    unsigned int i;
    HRESULT hresult;
    VARIANT var;
    SAFEARRAY FAR* psa;
    CEnumPoint FAR* penum;
    POINTLINK FAR* ppointlink;
    SAFEARRAYBOUND rgsabound[1];
    rgsabound[0].lLbound = 0;
    rgsabound[0].cElements = m_cPoints;

    psa = SafeArrayCreate(VT_VARIANT, 1, rgsabound);
    if(psa == NULL){
        HRESULT = ResultFromScode(E_OUTOFMEMORY);
        goto LError0;
    }

    // Code omitted here for brevity.

        V_VT(&var) = VT_DISPATCH;
        HRESULT = ppointlink->ppoint->QueryInterface(
        IID_IDispatch, (void FAR* FAR*)&V_DISPATCH(&var));
        if(HRESULT != NOERROR)
            goto LError1;

        ix[0] = i;
        SafeArrayPutElement(psa, ix, &var);

        ppointlink = ppointlink->next;
    }

    HRESULT = CEnumPoint::Create(psa, &penum);
    if(HRESULT != NOERROR)
        goto LError1;
    *ppenum = penum;
    return NOERROR;

LError1:;
    SafeArrayDestroy(psa);

LError0:;
    return hresult;
}


SafeArrayRedim

This function changes the right-most (least significant) bound of a safe array.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayRedim(SAFEARRAY FAR* psa, SAFEARRAYBOUND FAR* psaboundNew);

Parameters

psa
Pointer to an array descriptor.
psaboundNew
Pointer to a new safe array bound structure that contains the new array boundary. Only the least significant dimension of an array can be changed.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The array is currently locked.
E_INVALIDARG | The item pointed to by psa is not a safe array descriptor.

Remarks

If you reduce the bound of an array, SafeArrayRedim deallocates the array elements outside the new array boundary. If the bound of an array is increased, SafeArrayRedim allocates and initializes the new array elements. The data is preserved for elements that exist in both the old and new array. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SafeArrayUnaccessData

This function decrements the lock count of an array, and invalidates the pointer retrieved by SafeArrayAccessData.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayUnaccessData(SAFEARRAY FAR* psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_UNEXPECTED | The array could not be unlocked.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SafeArrayUnlock

This function decrements the lock count of an array so it can be freed or resized.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SafeArrayUnlock(SAFEARRAY FAR* psa);

Parameters

psa
Pointer to an array descriptor created by SafeArrayCreate.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_INVALIDARG | The psa parameter was not a valid safe array descriptor.
E_UNEXPECTED | The array could not be unlocked.

Remarks

This function is called after access to the data in an array is finished. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SetDaylightTime

This function sets the current state of daylight savings time.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

void SetDaylightTime( DWORD dst );

Parameters

dst
Integer that indicates whether or not day light savings time is in effect. A value of 1 indicates that daylight savings time is in effect; a value of 0 indicates that standard time is in effect.

Return Values

None.

Remarks

Windows CE does not automatically correct the time to account for daylight savings time. To enable Windows CE to correctly calculate the time, call this function with dst set to 1 when daylight savings time begins; call it with dst set to 0 when it ends.

See Also

SetTimeZoneInformation


SetEndOfFile

This function moves the end-of-file position for the specified file to the current position of the file pointer. A remote application interface (RAPI) version of this function exists, and it is called CeSetEndOfFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetEndOfFile( HANDLE hFile );

Parameters

hFile
[in] Handle to the file to have its EOF position moved. The file handle must have been created with GENERIC_WRITE access to the file.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This function can be used to truncate or extend a file. If the file is extended, the contents of the file between the old EOF position and the new position are not defined.

If you called CreateFileMapping to create a file-mapping object for hFile, you must first call UnmapViewOfFile to unmap all views and call CloseHandle to close the file-mapping object before you can call SetEndOfFile.

See Also

CreateFile


SetErrorInfo

This function sets the error information object for the current thread of execution.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SetErrorInfo( DWORD dwReserved, IErrorInfo * perrinfo);

Parameters

dwReserved
Reserved for future use; set to zero.
perrinfo
Pointer to an error object.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK Success.

Remarks

This function releases the existing error information object, if one exists, and sets the pointer to perrinfo. Use this function after creating an error object that associates the object with the current thread of execution.

If the property or method that calls SetErrorInfo is called by DispInvoke, then DispInvoke will fill the EXCEPINFO parameter with the values specified in the error information object. DispInvoke will return DISP_E_EXCEPTION when the property or method returns a failure return value for DispInvoke.

Virtual function table (VTBL) binding controllers that do not use IDispatch::Invoke can get the error information object by using GetErrorInfo. This allows an object that supports a dual interface to use SetErrorInfo, regardless of whether the client uses VTBL binding or IDispatch. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

ICreateErrorInfo *pcerrinfo;
    IErrorInfo *perrinfo;
    HRESULT hr;

hr = CreateErrorInfo(&pcerrinfo);
hr = pcerrinfo->QueryInterface(IID_IErrorInfo, (LPVOID FAR*) &perrinfo);
if (SUCCEEDED(hr))
    {
        SetErrorInfo(0, perrinfo);
        perrinfo->Release();
    }
    pcerrinfo->Release();


SetEvent

This function sets the state of the specified event object to signaled.

At a Glance

Header file: | Kfuncs.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetEvent(HANDLE hEvent);

Parameters

hEvent
Handle to the event object. The CreateEvent function returns this handle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The state of a manual-reset event object remains signaled until it is set explicitly to the nonsignaled state by the ResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object by calling one of the wait functions, can be released while the object’s state is signaled.

The state of an auto-reset event object remains signaled until a single waiting thread is released, at which time the system automatically sets the state to nonsignaled. If no threads are waiting, the event object’s state remains signaled.

See Also

CreateEvent, PulseEvent, ResetEvent, WaitForSingleObject


SetFileAttributes

This function sets the attributes of a file. A remote application interface (RAPI) version of this function exists, and it is called CeSetFileAttributes.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetFileAttributes(LPCTSTR lpFileName, DWORD dwFileAttributes);

Parameters

lpFileName
[in] Pointer to a string that specifies the name of the file whose attributes are to be set.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the SetFileAttributes function parses paths.

dwFileAttributes
[in] Specifies the file attributes to set for the file. This parameter can be a combination of the following values. However, all other values override FILE_ATTRIBUTE_NORMAL.
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_HIDDEN | The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE | The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY | The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM | The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY | The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The following table describes how to set the attributes that cannot be set using SetFileAttributes.

Attribute
How to Set
FILE_ATTRIBUTE_COMPRESSED | To set a file's compression state, use the DeviceIoControl function with the FSCTL_SET_COMPRESSION operation.
FILE_ATTRIBUTE_DIRECTORY | Files cannot be converted into directories. To create a directory, use the CreateDirectory function.
FILE_ATTRIBUTE_REPARSE_POINT | To associate a reparse point with a file, use the DeviceIoControl function with the FSCTL_SET_REPARSE_POINT operation.
FILE_ATTRIBUTE_SPARSE_FILE | To set a file's sparse attribute, use the DeviceIoControl function with the FSCTL_SET_SPARSE operation.
FILE_ATTRIBUTE_SYSTEM | This attribute cannot be set.

Not all file systems support all attributes.

See Also

GetFileAttributes


SetFilePointer

This function moves the file pointer of an open file. A remote application interface (RAPI) version of this function exists, and it is called CeSetFilePointer.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD SetFilePointer( HANDLE hFile, LONG lDistanceToMove,
PLONG lpDistanceToMoveHigh, DWORD dwMoveMethod );

Parameters

hFile
[in] Handle to the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.
lDistanceToMove
Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. If lpDistanceToMoveHigh is not NULL, lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value that specifies the distance to move. If lpDistanceToMoveHigh is NULL, lDistanceToMove is a 32-bit signed value. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer backward.
lpDistanceToMoveHigh
[in] Pointer to the high-order 32 bits of the signed 64-bit distance to move. If you do not need the high-order 32 bits, this pointer can be NULL. When non-NULL, this parameter also receives the high-order DWORD of the new value of the file pointer. For more information, see the Remarks section later in this topic.
dwMoveMethod
[in] Specifies the starting point for the file pointer move. This parameter can be one of the following values.
Value
Description
FILE_BEGIN | The starting point is zero or the beginning of the file.
FILE_CURRENT | The starting point is the current value of the file pointer.
FILE_END | The starting point is the current end-of-file position.

Return Values

The low-order DWORD of the new file pointer indicates success and that lpDistanceToMoveHigh is NULL. If lpDistanceToMoveHigh is not NULL, the function returns the low order DWORD of the new file pointer, and puts the high-order DWORD of the new file pointer into the LONG pointed to by that parameter.

If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF. However, because 0xFFFFFFFF is a valid value for the low-order DWORD of the new file pointer, you must check GetLastError to determine whether an error occurred. If an error occurred, GetLastError returns a value other than NO_ERROR. For a code example that illustrates this point, see the Remarks section later in this topic.

If the new file pointer would have been a negative value, the function fails, the file pointer is not moved, and the code returned by GetLastError is ERROR_NEGATIVE_SEEK.

Remarks

You cannot use the SetFilePointer function with a handle to a nonseeking such as communications device.

You can use the SetFilePointer function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero.

You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object. For more information about these objects, see Working with Processes and Threads.

It is not an error to set the file pointer to a position beyond the end of the file. The size of the file does not increase until you call the SetEndOfFile or WriteFile function. A write operation increases the size of the file to the file pointer position plus the size of the buffer written, leaving the intervening bytes uninitialized.

If the return value is 0xFFFFFFFF and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//
// Case One: calling the function with lpDistanceToMoveHigh == NULL

// Try to move hFile's file pointer some distance
dwPtr = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN) ;

if (dwPtr == 0xFFFFFFFF) // Test for failure
{
 // Obtain the error code
 dwError = GetLastError() ;

 // Deal with failure
 // . . .

} // End of error handler

//
// Case Two: calling the function with lpDistanceToMoveHigh != NULL

// Try to move hFile's file pointer some huge distance
dwPtrLow = SetFilePointer (hFile, lDistLow, & lDistHigh, FILE_BEGIN) ;

// Test for failure
if (dwPtrLow == 0xFFFFFFFF && (dwError = GetLastError()) != NO_ERROR )
{
 // Deal with failure
 // . . .

} // End of error handler

The parameter lpDistanceToMoveHigh is used to manipulate huge files. If it is set to NULL, then lDistanceToMove has a maximum value of 2^31–2, or 2 gigabytes less two. This is because all file pointer values are signed values. Therefore if there is even a small chance that the file will grow to that size, you should treat the file as a huge file and work with 64-bit file pointers.

If lpDistanceToMoveHigh is not NULL, then lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value. The lDistanceToMove parameter is treated as the low-order 32 bits of the value, and lpDistanceToMoveHigh as the upper 32 bits. Thus, lpDistanceToMoveHigh is a sign extension of lDistanceToMove.

To move the file pointer from 0 to 2 gigabytes, lpDistanceToMoveHigh can be either NULL or a sign extension of lDistanceToMove. To move the pointer more than 2 gigabytes, use lpDistanceToMoveHigh and lDistanceToMove as a single 64-bit quantity. For example, to move in the range from 2 gigabytes to 4 gigabytes, set the contents of lpDistanceToMoveHigh to zero, or to –1 for a negative sign extension of lDistanceToMove.

To work with 64-bit file pointers, you can declare a LONG, treat it as the upper half of the 64-bit file pointer, and pass its address in lpDistanceToMoveHigh. This means you have to treat two different variables as a logical unit, which is error-prone. The problems can be ameliorated by using the LARGE_INTEGER structure to create a 64-bit value and passing the two 32-bit values by means of the appropriate elements of the union.

It is conceptually simpler and better design to use a function to hide the interface to SetFilePointer. To do so, use something like this:

__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
 LARGE_INTEGER li;

 li.QuadPart = distance;

 li.LowPart = SetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod);

 if (li.LowPart == 0xFFFFFFFF && GetLastError() != NO_ERROR)
 {
 li.QuadPart = –1;
 }

 return li.QuadPart;
}

You can use SetFilePointer to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location zero. The file offset returned is the length of the file. However, this practice can have unintended side effects, such as failure to save the current file pointer so that the program can return to that location. It is simpler and safer to use GetFileSize instead.

See Also

ReadFile


SetFileTime

This function sets the date and time that a file was created, last accessed, or last modified. A remote application interface (RAPI) version of this function exists, and it is called CeSetFileTime.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetFileTime( HANDLE hFile, const FILETIME *lpCreationTime,
const FILETIME *lpLastAccessTime, const FILETIME *lpLastWriteTime );

Parameters

hFile
[in] Handle to the file for which to set the dates and times. The file handle must have been created with GENERIC_WRITE access to the file.
lpCreationTime
[in] Pointer to a FILETIME structure that contains the date and time the file was created. This parameter can be NULL if the application does not need to set this information.
lpLastAccessTime
[in] Pointer to a FILETIME structure that contains the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or (in the case of executable files) run. This parameter can be NULL if the application does not need to set this information.
lpLastWriteTime
[in] Pointer to a FILETIME structure that contains the date and time the file was last written to. This parameter can be NULL if the application does not want to set this information.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Not all file systems support all file time parameters. The Windows CE object store stores only one file time and it can be set by any one of the three parameters.

See Also

FILETIME, GetFileSize, GetFileTime


SetLastError

This function sets the last-error code for the calling thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void SetLastError( DWORD dwErrCode);

Parameters

dwErrCode
Specifies the last-error code for the thread.

Return Values

None.

Remarks

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no system error code has this bit set. If you are defining an error code for your application, set this bit to indicate that the error code has been defined by your application and to ensure that your error code does not conflict with any system-defined error codes.

This function is intended primarily for dynamic-link libraries (DLLs). Calling this function after an error occurs lets the DLL emulate the behavior of a Win32 function.

Most Win32 functions call SetLastError when they fail. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or –1. Some functions call SetLastError under conditions of success; those cases are noted in each function’s reference page.

Applications can retrieve the value saved by this function by using the GetLastError function. The use of GetLastError is optional; an application can call it to find out the specific reason for a function failure.

The last-error code is kept in thread local storage so that multiple threads do not overwrite each other’s values.

See Also

GetLastError, TlsGetValue


SetLocaleInfo

This function sets an item of locale information. It does so by making an entry in the process portion of the locale table. This setting only affects the user override portion of the locale settings; it does not set the system defaults.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetLocaleInfo(LCID Locale, LCTYPE LCType, LPWTSTR lpLCData);

Parameters

Locale
[in] Specifies the locale whose information the function will set. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.
LCType
[in] Specifies the type of locale information to be set by the function. Note that only one LCTYPE may be specified per call. Not all LCTYPE values are valid; see the list of valid LCTYPE values in the following Remarks section.
lpLCData
[in] Pointer to a null-terminated string that contains the locale information the function will set. The information must be in the specified LCTYPE’s particular format.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INVALID_ACCESS
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The following LCTYPE values are valid for this function:

LOCALE_ICALENDARTYPE | LOCALE_SDATE
LOCALE_ICURRDIGITS | LOCALE_SDECIMAL
LOCALE_ICURRENCY | LOCALE_SGROUPING
LOCALE_IDIGITS | LOCALE_SLIST
LOCALE_IFIRSTDAYOFWEEK | LOCALE_SLONGDATE
LOCALE_IFIRSTWEEKOFYEAR | LOCALE_SMONDECIMALSEP
LOCALE_ILZERO | LOCALE_SMONGROUPING
LOCALE_IMEASURE | LOCALE_SMONTHOUSANDSEP
LOCALE_INEGCURR | LOCALE_SNEGATIVESIGN
LOCALE_INEGNUMBER | LOCALE_SPOSITIVESIGN
LOCALE_IPAPERSIZE | LOCALE_SSHORTDATE
LOCALE_ITIME | LOCALE_STHOUSAND
LOCALE_S1159 | LOCALE_STIME
LOCALE_S2359 | LOCALE_STIMEFORMAT
LOCALE_SCURRENCY | LOCALE_SYEARMONTH

Windows CE versions 1.0 through 2.01 do not support the LOCALE_IPAPERSIZE LCTYPE value.

See Also

GetLocaleInfo


SetLocalTime

This function sets the current local time and date.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetLocalTime( const SYSTEMTIME *lpSystemTime );

Parameters

lpSystemTime
[in] Pointer to a SYSTEMTIME structure that contains the current local date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

GetLocalTime, GetSystemTime, SYSTEMTIME


SetRect

This function sets the coordinates of the specified rectangle. This is equivalent to assigning the left, top, right, and bottom arguments to the appropriate members of the RECT structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetRect(LPRECT lprc, int xLeft, int yTop, int xRight, int yBottom);

Parameters

lprc
Long pointer to the RECT structure that contains the rectangle to be set.
xLeft
Specifies the x-coordinate of the rectangle’s upper-left corner.
yTop
Specifies the y-coordinate of the rectangle’s upper-left corner.
xRight
Specifies the x-coordinate of the rectangle’s lower-right corner.
yBottom
Specifies the y-coordinate of the rectangle’s lower-right corner.

Return Values

Nonzero indicates success. Zero indicates failure.

To get extended error information, call GetLastError.

See Also

CopyRect, SetRectEmpty, RECT


SetRectEmpty

This function creates an empty rectangle in which all coordinates are set to zero.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetRectEmpty(LPRECT lpr);

Parameters

lprc
Long pointer to the RECT structure that contains the coordinates of the rectangle.

Return Values

Nonzero indicates success. Zero indicates failure.

To get extended error information, call GetLastError.

See Also

CopyRect, RECT, SetRect


SetSystemTime

This function sets the current system time and date. The system time is expressed in Coordinated Universal Time (UTC).

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetSystemTime( const SYSTEMTIME *lpSystemTime );

Parameters

lpSystemTime
[in] Pointer to a SYSTEMTIME structure that contains the current system date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

GetSystemTime, SYSTEMTIME


SetThreadContext

This function sets the context in the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL SetThreadContext( HANDLE hThread,
CONST CONTEXT * lpContext);

Parameters

hThread
Handle to the thread whose context is to be set.
lpContext
Pointer to the CONTEXT structure that contains the context to be set in the specified thread. The value of the ContextFlags member of this structure specifies which portions of a thread’s context to set. Some values in the CONTEXT structure that cannot be specified are silently set to the correct value. This includes bits in the CPU status register that specify the privileged processor mode, global enabling bits in the debugging register, and other states that must be controlled by the operating system.

Return Values

Nonzero indicates that the context was set. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The function allows the selective context to be set based on the value of the ContextFlags member of the context structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate even when it is not being debugged.

Do not try to set the context for a running thread; the results are unpredictable. Use the SuspendThread function to suspend the thread before calling SetThreadContext.

See Also

CONTEXT, GetThreadContext, SuspendThread


SetThreadPriority

This function sets the priority value for the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetThreadPriority( HANDLE hThread, int nPriority);

Parameters

hThread
Handle to the thread whose priority value is to be set.
nPriority
Specifies the priority value for the thread. This parameter can be one of the following values:
Value
Description
THREAD_PRIORITY_TIME_CRITICAL | Indicates 3 points above normal priority.
THREAD_PRIORITY_HIGHEST | Indicates 2 points above normal priority.
THREAD_PRIORITY_ABOVE_NORMAL | Indicates 1 point above normal priority.
THREAD_PRIORITY_NORMAL | Indicates normal priority.
THREAD_PRIORITY_BELOW_NORMAL | Indicates 1 point below normal priority.
THREAD_PRIORITY_LOWEST | Indicates 2 points below normal priority.
THREAD_PRIORITY_ABOVE_IDLE | Indicates 3 points below normal priority.
THREAD_PRIORITY_IDLE | Indicates 4 points below normal priority.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE does not support priority classes. The order in which threads are scheduled is determined only by their thread priorities.

Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level does scheduling of threads at a lower level take place.

The SetThreadPriority function enables setting the base priority level of a thread without consideration of priority classes.

All threads initially start at THREAD_PRIORITY_NORMAL. Use the GetThreadPriority function to get the priority value of a thread.

Use thread priority values to differentiate the relative priorities of the tasks of a process. For example, a thread that handles input for a window could have a higher priority level than a thread that performs intensive calculations for the CPU.

When manipulating priorities, ensure that a high-priority thread does not consume all of the available CPU time. A thread with a priority level of THREAD_PRIORITY_TIME_CRITICAL will execute until it explicitly yields processing to other threads. Processing of these threads is not yielded to other threads with the THREAD_PRIORITY_TIME_CRITICAL priority level. Such a thread can interfere with the normal operation of the operating system if the thread does not explicitly yield processing quickly.

See Also

GetThreadPriority


SetTimeZoneInformation

This function sets the current time-zone parameters. These parameters control translations from Coordinated Universal Time (UTC) to local time.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SetTimeZoneInformation(
const TIME_ZONE_INFORMATION *lpTimeZoneInformation );

Parameters

lpTimeZoneInformation
[in] Pointer to a TIME_ZONE_INFORMATION structure that contains the time-zone parameters to set.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

All translations between UTC and local time are based on the following formula:

UTC = local time + bias

The bias is the difference, in minutes, between UTC and local time.

See Also

GetTimeZoneInformation, TIME_ZONE_INFORMATION


SHAddToRecentDocs

This function adds a document to the shell’s list of recently used documents or clears all documents from the list. The user gains access to the list through the Start menu of a taskbar or other top-level application.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

WINSHELLAPI void WINAPI SHAddToRecentDocs(UINT uFlags, LPCVOID pv);

Parameters

uFlags
[in] Flag that indicates the meaning of the pv parameter. It is one of the following values:
Value
Description
SHARD_PATH | The pv parameter contains the address of a path string.
SHARD_PIDL | The pv parameter contains the address of an item identifier list (PIDL) that identifies a file object. PIDLs that identify nonfile objects are not allowed.

pv
[in] Void pointer to a character buffer that contains the path and file name of the document, or the address of an ITEMIDLIST structure that contains an item identifier list that uniquely identifies the document. If this parameter is NULL, the function clears all documents from the list.

Return Values

None.

Remarks

In Windows CE, you cannot add more than ten documents to the recently used documents list.


SHCreateShortcut

This function creates a shortcut. A remote application interface (RAPI) version of this function exists, and it is called CeSHCreateShortcut.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SHCreateShortcut(LPTSTR szShortcut, LPTSTR szTarget);

Parameters

szShortcut
Null-terminated string that contains the name of the shortcut to create. Passing a NULL value for this parameter will cause an exception
szTarget
Null-terminated string that contains the target path of the shortcut. The size of the buffer is limited to 256 characters.


Shell_NotifyIcon

This function sends a message to the system to add, modify, or delete an icon from the taskbar status area.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

WINSHELLAPI BOOL WINAPI Shell_NotifyIcon(DWORD dwMessage, PNOTIFYICONDATA pnid);

Parameters

dwMessage
[in] Specifies the message value to send. It is one of these values:
Value
Description
NIM_ADD | Adds an icon to the status area.
NIM_DELETE | Deletes an icon from the status area.
NIM_MODIFY | Modifies an icon in the status area.

pnid
[in] Pointer to a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage.

Return Values

Nonzero indicates success. Zero indicates failure.


ShellExecuteEx

This function performs an action on a file. The file can be an executable file or a document.

At a Glance

Header file: | Shellapi.h
Versions: | 1.0 and later

Syntax

WINSHELLAPI BOOL WINAPI ShellExecuteEx(LPSHELLEXECUTEINFO lpExecInfo);

Parameters

lpExecInfo
Long pointer to a SHELLEXECUTEINFO structure that contains and receives information about the application being executed.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the function succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to the instance handle to the application that the function started. If the function fails, hInstApp is one of the SE_ERR_ error values indicating the cause of the failure. (An instance handle will always be greater than 32 and an error value less than 32.) Note that the SE_ERR_ error values are for compatibility with the ShellExecute function; use the GetLastError function to retrieve error information.

The error value returned by GetLastError corresponds to the SE_ERR_ values and is one of the values described in the following table.

Value
Description
ERROR_FILE_NOT_FOUND | The specified file was not found.
ERROR_PATH_NOT_FOUND | The specified path was not found.
ERROR_DDE_FAIL | The DDE transaction failed.
ERROR_NO_ASSOCIATION | There is no application associated with the given file name extension.
ERROR_ACCESS_DENIED | Access to the specified file is denied.
ERROR_DLL_NOT_FOUND | One of the library files necessary to run the application can’t be found.
ERROR_CANCELLED | The function prompted the user for the location of the application, but the user canceled the request.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to perform the specified action.
ERROR_SHARING_VIOLATION | A sharing violation occurred.

See Also

SHELLEXECUTEINFO


SHGetFileInfo

This function retrieves information about an object in the file system, such as a file, a folder, a directory, or a drive root.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

WINSHELLAPI DWORD WINAPI SHGetFileInfo(LPCTSTR pszPath, DWORD dwFileAttributes, SHFILEINFO FAR *psfi, UINT cbFileInfo, UINT uFlags);

Parameters

pszPath
[in] Pointer to a buffer that contains the path and file name. Both absolute and relative paths are valid.

If the uFlags parameter includes the SHGFI_PIDL flag, this parameter must be the address of an ITEMLIST (PIDL) structure that contains the list of item identifiers that uniquely identifies the file within the shell's namespace. The PIDL must be a fully qualified PIDL. Relative PIDLs are not allowed.

If the uFlags parameter includes the SHGFI_USEFILEATTRIBUTES flag, this parameter does not have to be a valid file name. The function will proceed as if the file exists with the specified name and with the file attributes passed in the dwFileAttributes parameter. This allows you to obtain information about a file type by passing just the extension for pszPath and passing FILE_ATTRIBUTE_NORMAL in dwFileAttributes.

This string can use either short (the 8.3 form) or long file names.

dwFileAttributes
[in] Combination of one or more file attribute flags (FILE_ATTRIBUTE_* values). If uFlags does not include the SHGFI_USEFILEATTRIBUTES flag, this parameter is ignored.

Windows CE supports the following additional values for the dwFileAttributes parameter:
Value
Description
FILE_ATTRIBUTE_INROM | The file is an operating system file stored in ROM. These files are read-only.
FILE_ATTRIBUTE_ROMMODULE | The file is an operating system file stored in ROM, designed to execute in place. In other words, code from this file is executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file, instead the LoadLibrary and CreateProcess functions must be used.

psfi
[in] Pointer to a SHFILEINFO structure to receive the file information.
cbFileInfo
[in] Size, in bytes, of the SHFILEINFO structure pointed to by the psfi parameter.
uFlags
[in] Flags that specify the file information to retrieve. It can be a combination of the following values:
Value
Description
SHGFI_ATTR_SPECIFIED | Modifies SHGFI_ATTRIBUTES. Indicates that the dwAttributes member of the SHFILEINFO structure at psfi contains the specific attributes that are desired.
SHGFI_ATTRIBUTES | Retrieve the item attributes. The attributes are copied to the dwAttributes member of the structure specified in the psfi parameter.
SHGFI_DISPLAYNAME | Retrieve the display name for the file. The name is copied to the szDisplayName member of the structure specified in psfi. The returned display name uses the long file name, if there is one, rather than the 8.3 form of the file name.
SHGFI_EXETYPE | Retrieve the type of the executable file if pszPath identifies an executable file. This flag cannot be specified with any other flags.
SHGFI_ICON | Retrieve the handle to the icon that represents the file and the index of the icon within the system image list. The handle is copied to the hIcon member of the structure specified by psfi, and the index is copied to the iIcon member. The return value is the handle to the system image list. You must call the DestroyIcon function on this icon handle.
SHGFI_ICONLOCATION
Retrieve the name of the file that contains the icon representing the file. The name is copied to the szDisplayName member of the structure specified in psfi.
SHGFI_LARGEICON | Modify SHGFI_ICON, causing the function to retrieve the file's large icon.
SHGFI_LINKOVERLAY | Modify SHGFI_ICON, causing the function to add the link overlay to the file's icon.
SHGFI_OPENICON | Modify SHGFI_ICON, causing the function to retrieve the file's open icon. A container object displays an open icon to indicate that the container is open.
SHGFI_PIDL | Indicate that pszPath is the address of an ITEMIDLIST structure rather than a path name.
SHGFI_SELECTED | Modify SHGFI_ICON, causing the function to blend the file's icon with the system highlight color.
SHGFI_SHELLICONSIZE | Modify SHGFI_ICON, causing the function to retrieve a shell-sized icon. If this flag is not specified the function sizes the icon according to the system metric values.
SHGFI_SMALLICON | Modify SHGFI_ICON, causing the function to retrieve the file's small icon.
SHGFI_SYSICONINDEX | Retrieve the index of the icon within the system image list. The index is copied to the iIcon member of the structure specified by psfi. The return value is the handle to the system image list.
SHGFI_TYPENAME | Retrieve the string that describes the file's type. The string is copied to the szTypeName member of the structure specified in psfi.
SHGFI_USEFILEATTRIBUTES | Indicates that the function should not attempt to access the file specified by pszPath. Rather, it should act as if the file specified by pszPath exists with the file attributes passed in dwFileAttributes. This flag cannot be combined with the SHGFI_ATTRIBUTES, SHGFI_EXETYPE, or SHGFI_PIDL flags.

Return Values

Returns a value whose meaning depends on the uFlags parameter. If uFlags contains the SHGFI_EXETYPE flag, the return value specifies the type of the executable file. It will be one of the following values:

Value
Executable File Type
0 Nonexecutable file or an error condition
Low-order word = NE or PE and
high-order word = 3.0, 3.5, or 4.0 		Windows application
Low-order word = MZ and
high-order word = 0 		MS-DOS .exe, .com, or .bat file
Low-order word = PE and
high-order word = 0 		Win32 console application

If uFlags contains SHGFI_SYSICONINDEX, the return value is the handle to the system image list that contains the large icon images. If SHGFI_SMALLICON is included with SHGFI_SYSICONINDEX, the return value is the handle to the image list that contains the small icon images.

If uFlags does not contain SHGFI_EXETYPE or SHGFI_SYSICONINDEX, the return value is nonzero if successful, or zero otherwise.

Remarks

For Windows CE versions 2.10 and later, SHGetFileInfo does not support the following values for uFlags:

  • SHGFI_ATTRIBUTES
  • SHGFI_EXETYPE
  • SHGFI_ICONLOCATION
  • SHGFI_LINKOVERLAY
  • SHGFI_OPENICON
  • SHGFI_SELECTED
  • SHGFI_SHELLICONSIZE

Also for Windows CE versions 2.10 and later, SHGetFileInfo supports the SHGFI_PIDL flag for the H/PC platform only.

See Also

DestroyIcon, HIWORD, LOWORD, SHFILEINFO


SHGetMalloc

This function retrieves a pointer to the shell’s IMalloc interface. A shell extension must use this interface to allocate memory that is later freed by the shell. Applications can also use this interface to allocate and free their own memory.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SHGetMalloc(LPMALLOC *ppMalloc);

Parameters

ppMalloc
[out] Pointer to a pointer that receives the shell’s IMalloc interface pointer.

Return Values

NONERROR indicates success. E_FAIL indicates failure.


SHGetPathFromIDList

This function converts an item identifier list to a file system path.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 2.0 and later

Syntax

WINSHELLAPI BOOL WINAPI SHGetPathFromIDList( LPCITEMIDLIST pidl, LPSTR pszPath );

Parameters

pidl
[in] Pointer to an item identifier list that specifies a file or directory location relative to the root of the namespace (the desktop).
pszPath
[out] Pointer to a buffer to receive the file system path. This buffer must be at least MAX_PATH characters in size.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If the location specified by the pidl parameter is not part of the file system, this function will fail.


SHGetShortcutTarget

This function retrieves the shortcut’s target path. A remote application interface (RAPI) version of this function exists, and it is called CeSHGetShortcutTarget.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SHGetShortcutTarget(LPTSTR szShortcut, LPTSTR szTarget, int cbMax);

Parameters

szShortcut
Null-terminated string that contains the name of the shortcut to create.
szTarget
Null-terminated string that gets the target path of the shortcut. The buffer must be at least cbMax characters long.
cbMax
Maximum number of characters that can be copied to the buffer.

Return Values

True indicates success. FALSE indicates failure.


SHGetSpecialFolderLocation

This function retrieves the location of a special folder, such as My Handheld PC, Recycle Bin, Control Panel, Desktop, Printers, Fonts, or various file system directories.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 2.0 only

Syntax

WINSHELLAPI HRESULT WINAPI SHGetSpecialFolderLocation
( HWND hwndOwner, int nFolder, LPITEMIDLIST *ppidl );

Parameters

hwndOwner
[in] Handle to the owner window the client should specify if it displays a dialog box or message box.
nFolder
[in] Value specifying the folder for which to retrieve the location. It is one of the following values:
Value
Description
CSIDL_ALTSTARTUP | File system directory that corresponds to the user's nonlocalized Startup program group.
CSIDL_APPDATA | File system directory that serves as a common repository for application-specific data.
CSIDL_BITBUCKET | File system directory that contains file objects in the user's Recycle Bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.
CSIDL_COMMON_ALTSTARTUP | File system directory that corresponds to the nonlocalized Startup program group for all users.
CSIDL_COMMON_DESKTOPDIRECTORY | File system directory that contains files and folders that appear on the desktop for all users.
CSIDL_COMMON_FAVORITES | File system directory that serves as a common repository for all users' favorite items.
CSIDL_COMMON_PROGRAMS | File system directory that contains the directories for the common program groups that appear on the Start menu for all users.
CSIDL_COMMON_STARTMENU | File system directory that contains the programs and folders that appear on the Start menu for all users.
CSIDL_COMMON_STARTUP | File system directory that contains the programs that appear in the Startup folder for all users.
CSIDL_CONTROLS | Virtual folder containing icons for the Control Panel applications.
CSIDL_COOKIES | File system directory that serves as a common repository for Internet cookies.
CSIDL_DESKTOP | Windows Desktop, which is a virtual folder at the root of the namespace.
CSIDL_DESKTOPDIRECTORY | File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).
CSIDL_DRIVES | My Computer, which is a virtual folder that contains everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.
CSIDL_FAVORITES | File system directory that serves as a common repository for the user's favorite items.
CSIDL_FONTS | Virtual folder containing fonts.
CSIDL_HISTORY | File system directory that serves as a common repository for Internet history items.
CSIDL_INTERNET | Virtual folder representing the Internet.
CSIDL_INTERNET_CACHE | File system directory that serves as a common repository for temporary Internet files.
CSIDL_NETHOOD | File system directory containing objects that appear in the network neighborhood.
CSIDL_NETWORK | Network Neighborhood Folder, which is a virtual folder that represents the top level of the network hierarchy.
CSIDL_PERSONAL | File system directory that serves as a common repository for documents.
CSIDL_PRINTERS | Virtual folder containing installed printers.
CSIDL_PRINTHOOD | File system directory that serves as a common repository for printer links.
CSIDL_PROGRAMS | File system directory that contains the user's program groups (which are also file system directories).
CSIDL_RECENT | File system directory that contains the user's most recently used documents.
CSIDL_SENDTO | File system directory that contains Send To menu items.
CSIDL_STARTMENU | File system directory containing Start menu items.
CSIDL_STARTUP | File system directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT or starts Windows 95.
CSIDL_TEMPLATES | File system directory that serves as a common repository for document templates.

ppidl
[in] Pointer to a pointer to an item identifier list specifying the folder’s location relative to the root of the namespace (the desktop). The calling application is responsible for freeing this pointer with the shell's IMalloc interface (see SHGetMalloc).

Return Values

NOERROR indicates success. An OLE-defined error result indicates failure.


SHLoadDIBitmap

This function loads a bitmap from the specified file.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

HBITMAP SHLoadDIBitmap(LPCTSTR szFileName);

Parameters

szFileName
Null-terminated string that contains the fully qualified path and file name that the bitmap will be loaded from.

Return Values

If the function succeeds, the return value is the handle to the bitmap loaded from the file, otherwise the return value is NULL.


SHShowOutOfMemory

This function displays a system-defined dialog box notifying the user that memory is full.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

int SHShowOutOfMemory(HWND hwndOwner, UINT grfFlags);

Parameters

hwndOwner
Handle to the window that owns the dialog box.
grfFlags
Reserved; set to zero.

Return Values

None.


SizeofResource

This function returns the size, in bytes, of the specified resource.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD SizeofResource(HMODULE hModule, HRSRC hResInfo);

Parameters

hModule
Handle to the module whose executable file contains the resource.
hResInfo
Handle to the resource. This handle must be created by using the FindResource function.

Return Values

The number of bytes in the resource indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

FindResource, LoadResource


Sleep

This function suspends the execution of the current thread for a specified interval.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

void Sleep(DWORD dwMilliseconds);

Parameters

dwMilliseconds
Specifies the time, in milliseconds, for which to suspend execution. A value of zero causes the thread to relinquish the remainder of its time slice to any other thread of equal priority that is ready to run. If there are no other threads of equal priority ready to run, the function returns immediately, and the thread continues execution. A value of INFINITE causes an infinite delay.

Return Values

None.

Remarks

A thread can relinquish the remainder of its time slice by calling this function with a sleep time of zero milliseconds.

You have to be careful when using Sleep and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. If you have a thread that uses Sleep with infinite delay, the system will deadlock. Two examples of code that indirectly creates windows are DDE and COM CoInitialize. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than Sleep.


SplAddUserDict

This function adds a word to an internal or external user dictionary.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplAddUserDict( HSPL hspl, int nID, const WCHAR * pwszAdd,
const WCHAR * pwszChange );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
nID
Identifier of the spelling dictionary.
pwszAdd
Pointer to a string that contains the word to add.
pwszChange
Pointer to a string that contains the word that replaces the incorrect word. If nID is either SPL_CHANGE_ALWAYS_LEX or SPL_CHANGE_ONCE_LEX, this parameter points to the word that replaces the word pwszAdd points to. Otherwise, this parameter is NULL.

Return Values

1 indicates success. 0 indicates failure.

Remarks

The internal dictionaries SPL_CHANGE_ALWAYS_LEX and SPL_CHANGE_ONCE_LEX support automatic substitution for a word in their lists—for example, “ISV” can be changed to “independent software vender.” When adding a word to either of these dictionaries, include the incorrect word in pwszAdd and the correct word in pwszChange.

For the SPL_IGNORE_LEX internal dictionary, pwszAdd points to the word to ignore and pwszChange is set to NULL.

Internal user dictionaries are created as empty word lists when an application calls SplInit to start a spelling session. External user dictionaries are typically created by the user and saved for use during future spelling sessions when an application calls the SplQuit function. During a spelling session, applications can edit internal and external user dictionaries by using SplAddUserDict to add words, using SplRemUserDict to remove words, and using SplClrUserDict to clear all entries in an internal or external user dictionary.

To create an external user dictionary, specify the path to the new dictionary to with a call to the SplInit function. To base the contents of the new dictionary on an existing external user dictionary, specify that dictionary in the SplInit call as well and use the SplEnumUserDict function to capture the contents of the existing dictionary. An application uses this output to display the contents to a user, who interacts with an application to modify the contents. To place words from a modified word list in the new dictionary, an application calls SplAddUserDict. The new external user dictionary is saved when the application calls SplQuit.

See Also

SplClrUserDict, SplEnumUserDict, SplInit, SplRemUserDict, SplSizeUserDict


SplCheck

This function is called by an application to notify the spelling checker to look for errors in a text buffer.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplCheck( HSPL hspl, SPLBUFFER * psb,);

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
psb
Pointer to the SPLBUFFER structure that contains the string to be checked.

Return Values

1 indicates success. 0 indicates failure.

Remarks

Before using SplCheck, an application must initialize the spelling session with the SplInit function and can set options with the SplOptionSet function. An application can specify the spelling checker’s behavior using the SplOptionSet, SplSuggest, and SplReplace functions.

After each call to SplCheck, an application checks SPLBUFFER for results and sets the SPLBUFFER members to specify where in the input buffer the spelling checker resumes checking with the next SplCheck call.

See Also

SPLBUFFER, SplInit, SplOptionSet, SplReplace, SplSuggest


SplClrUserDict

This function clears the contents of an internal or external user dictionary. The main dictionary cannot be cleared.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplClrUserDict( HSPL hspl, int nID);

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
nID
Identifier of the spelling dictionary to be removed.

Return Values

1 indicates success. 0 indicates failure.

Remarks

SplClrUserDict provides a means to clear internal and external user dictionaries that are not relevant to text that is currently being checked. Removing an internal user dictionary may be necessary if an application initializes the spelling checker when the application starts. In this case, the spelling checker maintains the internal user dictionaries throughout the spelling session until the application exits. An application may want to clear the contents of an internal dictionary when more than one document is checked for spelling during a single execution of an application.

When an application calls SplQuit, which ends a spelling session, all three internal user dictionaries are removed from memory.

See Also

SplAddUserDict, SplInit, SplQuit, SplRemUserDict


SplEnumUserDict

This function enumerates the words in internal and external user dictionaries, allowing an application to manipulate or display dictionary contents.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplEnumUserDict( HSPL hspl, int nID, DWORD nIndex,
SPLBUFFER * psb );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
nID
Identifier of the user dictionary.
nIndex
Index of the word at which enumeration begins.
psb
Pointer to the SPLBUFFER structure.

Return Values

1 indicates success. 0 indicates failure.

Remarks

The main dictionary cannot be enumerated.

By enumerating user dictionaries, an application can present a dictionary’s contents to a user, who can then select words to be removed by means of the SplRemUserDict function, or specify words to be added by means of the SplAddUserDict function. The SplClrUserDictionary function clears the contents of a dictionary.

The SplEnumUserDict function places null-terminated words from the specified dictionary into the output buffer pointed to by the pwszOut member of the SPLBUFFER structure. The aspl member is an array of pointers to each word in the output buffer.

Because the output buffer contains a maximum of eight words, an application needs to continue calling SplEnumUserDict to enumerate dictionaries that are larger than eight words. To indicate that there are more words in the dictionary, SplEnumUserDict sets the dwErr member of SPLBUFFER to SPL_MORE_INFO_THAN_BUFFER_CAN_HOLD. In this case, use the nIndex parameter as a placeholder to a mark where in the dictionary to begin enumeration on the next call. When all the entries in a dictionary are enumerated, dwErr is set to SPL_OK, and the cspl member indicates how many words are in the output buffer.

When the entries of an enumerated dictionary consist of paired words, such as in the SPL_CHANGE_ALWAYS_LEX internal user dictionary, an entry has a separate aspl member in SPLBUFFER for each word in the pair.

See Also

SplAddUserDict, SPLBUFFER, SplClrUserDict, SplInit, SplRemUserDict


SplInit

This function is called by an application to initialize a spelling session. SplInit generates a handle for a spelling session, allocates buffer memory, loads the main dictionary and external user dictionaries, and creates the internal user dictionaries.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplInit( HSPL * phspl, int clex, WCHAR ** ppwsz );

Parameters

phspl
Pointer to the handle of the new spelling session. The SplInt function creates this handle and places it at the location pointed to by this parameter. Subsequent calls by an application must include this handle to associate a call to a particular spelling session.
clex
Number of user dictionaries that are defined. If clex is 0, the SplCheck function uses only the main dictionary.
ppwsz
Pointer to a list of pointers, each of which point to a null-terminated string that contains the path and file name for an external user dictionary. If clex is 0, this parameter must be NULL.

Return Values

1 indicates success. 0 indicates failure.

Remarks

Windows CE supplies a read-only main spelling dictionary on the device. By default, this dictionary is used during every spelling session. Currently, Windows CE does not support replacing this main dictionary with a dictionary supplied by the application.

In addition to loading the main dictionary, SplInit creates the following three internal user dictionaries:

SPL_IGNORE_LEX
Contains words that the spelling checker finds, but the user does not want to change. The spelling checker ignores words in this list for the remainder of the spelling session.
SPL_CHANGE_ALWAYS_LEX
Contains words that the spelling checker finds, paired with words that replace subsequent occurrences of the found words.
SPL_CHANGE_ONCE
Contains words that the spelling checker finds and the user changes. The spelling checker continues to find subsequent occurrences of the words.

These internal dictionaries are empty at initialization and removed by the SplQuit function when the spelling session is over.

The application can also specify external user dictionaries to load. The ppwsz parameter points to a list of pointers, each of specify the path and file name of an external user dictionary. If you load one external user dictionary, ppwsz is a pointer to a single pointer. Use the clex parameter to indicate how many external user dictionaries to load. There is no limit to the number of external user dictionaries the application can define.

External user dictionaries are typically created by the user and saved for use during future spelling sessions when an application calls the SplQuit function. During a spelling session, applications can add words to an external user dictionary using SplAddUserDict, remove words using SplRemUserDict, and clear the contents of an external user dictionary using SplClrUserDict.

SplInit assigns identifiers to the internal user dictionaries and to any external user dictionaries pointed to by ppwsz. Use these identifiers in other spelling functions to specify a dictionary. The parameter that identifies a dictionary is nID. Values that SplInit assigns to nID are listed in the following table.

Value
Dictionary
–3 | SPL_IGNORE_LEX
–2 | SPL_CHANGE_ALWAYS_LEX
–1 | SPL_CHANGE_ONCE
0 | External user dictionary 1
1 | External user dictionary 2
clex–1 | External user dictionary clex

To determine the value of the nID parameter for an external user dictionary, subtract one from its position in the dictionary list that the ppwsz parameter points to. For example, if there are three external user dictionaries to load, clex equals 3. The nID of the last dictionary loaded is clex–1, which equals 2.

Because initializing a spelling session is time-consuming, consider doing it when the calling application starts and keeping the spelling session active until the calling application ends. Remember, however, that a spelling session has exclusive access to external user dictionaries until the calling application exits. This means that a second application cannot load external user dictionaries that are already in use.

If it is possible for a user to simultaneously run multiple applications that can use the spelling checker, it might be best to initialize the spelling checker when the user requests it instead of initializing it when the calling application starts. When the application is done with the spelling checker, it calls the SplQuit function and the external user dictionary or dictionaries are available for use by another spelling session.

The main dictionary is available for multiple spelling sessions because it is read-only. The internal user dictionaries are created for each spelling session and removed at the end of each session; therefore, access to them by multiple spelling sessions is not an issue.

See Also

SplAddUserDict, SplClrUserDict, SplQuit, SplRemUserDict


SplLimitGet

This function retrieves the error tolerance for the spelling session.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplLimitGet( HSPL hspl, DWORD *pdw );

Parameters

hspl
Handle to the spelling session.
pdw
Pointer to the DWORD that represents the error tolerance for the spelling session.

Return Values

1 indicates success. 0 indicates failure.

Remarks

The spelling error tolerance is a limit that an application’s automatic replace feature can use. When a misspelling exceeds the error tolerance, the spelling checker does not return suggestions for the misspelled word. Use the SplLimitSet function to set the error tolerance.

See Also

SplLimitSet


SplLimitSet

This function sets a spelling error tolerance that an application’s automatic replace feature can use. When a misspelling exceeds the error tolerance, the spelling checker does not return suggestions for the misspelled word.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplLimitSet ( HSPL hslp, DWORD dw);

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
dw
Specifies the error tolerance.

The spelling errors in the following list are ordered from the least severe to the most severe. The spelling checker does not provide a suggestion when it encounters either the specified error type or any error more severe than the set limit.

The dw parameter is one of the following error types:
Value
Description
SPL_LIMIT_NONE | The only spelling suggestion returned is for a word that is correctly spelled one way. For example, the suggestion for “i” is “I,” and the suggestion for “thier” is “their.”
SPL_LIMIT_CAPITAL | An error is corrected by capitalizing the initial letter of the word.
SPL_LIMIT_DROP_DOUBLE_CONSONANT | An error is corrected by substituting a double consonant for a single consonant.
SPL_LIMIT_ADD_DOUBLE_CONSONANT | An error is corrected by substituting a single consonant for a double consonant.
SPL_LIMIT_TRANSPOSE_VOWEL | An error is corrected by transposing two vowels.
SPL_LIMIT_DROP_DOUBLE_VOWEL | An error is corrected by substituting a single vowel for a double vowel.
SPL_LIMIT_ADD_DOUBLE_VOWEL | An error is corrected by substituting a double vowel for a single vowel.
SPL_LIMIT_TRANSPOSE_CONSONANT | An error is corrected by transposing two consonants.
SPL_LIMIT_TRANSPOSE | An error is corrected by transposing any two letters.
SPL_LIMIT_SUBSTITUTE_VOWEL | An error is corrected by substituting a vowel for another vowel.
SPL_LIMIT_DROP | An error is corrected by dropping a letter.
SPL_LIMIT_ADD | An error is corrected by adding a letter.
SPL_LIMIT_SUBSTITUTE_CONSONANT | An error is corrected by substituting a consonant for another consonant.
SPL_LIMIT_SUBSTITUTE | An error is corrected by substituting a letter for another letter.

Return Values

1 indicates success. 0 indicates failure.

Remarks

Typically, automatic replacement features set a low error tolerance limit; for instance, at SPL_LIMIT_NONE or SPL_LIMIT_CAPITAL.

In addition to setting an error limit for an automatic replace feature, the error types listed for dw are used to score suggestions that the spelling checker returns to the output buffer of the SPLBUFFER structure. For more information about scoring suggestions, see SplSuggest and SPLSUGGEST.

See Also

SPLBUFFER, SplInit, SplLimitGet, SplReplace, SPLSUGGEST


SplOptionGet

This function retrieves the options that the application set for a spelling session.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplOptionGet( HSPL hspl, DWORD * pdw);

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
pdw
Pointer to the DWORD that represents the options for the spelling session.

Return Values

1 indicates success. 0 indicates failure.

Remarks

A typical use of this function is to get the current options and then change the options with a call to the SplOptionSet function.

See Also

SplInit, SplOptionSet


SplOptionSet

This function sets the options for a spelling session.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplOptionSet ( HSPL hspl, DWORD dw );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
dw
Specifies options for the spelling session. It a bit flag that is any combination of the following values:
Value
Description
SPL_FIND_INITIAL_NUMERALS | Spelling checker finds words that begin with numerals.
SPL_FIND_REPEAT_WORD | Spelling checker finds double words, for example, “the the.”
SPL_IGNORE_ALL_CAPS | Spelling checker ignores words that consist of all capital letters.
SPL_IGNORE_INITIAL_CAP | Spelling checker ignores all initial capitalization errors.
SPL_IGNORE_MIXED_DIGITS | Spelling checker ignores words containing both digits and letters.
SPL_IGNORE_ROMAN_NUMERALS | Spelling checker ignores Roman numerals.
SPL_IGNORE_SINGLE_LETTER | Spelling checker ignores any single-letter words.
SPL_SCORE_SUGGESTIONS | Spelling checker scores the suggestions it provides and stores the value in the nScore member of SPLSUGGEST If this option is not set, the nScore member of the SPLSUGGEST structure is empty.
SPL_SINGLE_STEP_SUGGEST | Spelling checker suggests only the most likely spelling for a word.
SPL_SUGGEST_FROM_USER_DICT | Spelling checker suggests words from the internal and external user dictionaries before suggesting words from the main dictionary.

Return Values

1 indicates success. 0 indicates failure.

Remarks

Not all options are available on a particular spelling checker. Calling SplOptionGet returns the options that are enabled.

Use the OR operator to set multiple options with one call.

Turning on SPL_SCORE_SUGGESTIONS stores a value in the nScore member of SPLSUGGEST for each spelling suggestion that the spelling checker returns. The spelling checker bases the value on how severe the mistake is and indicates how likely it is that the suggestion is correct. The greater the value of the score, the less likely it is that the suggestion is correct. To keep such unlikely suggestions from being written to the SPLBUFFER structure, use the SplLimitSet function. To get suggestions and scores from the spelling checker, call the SplSuggest function.

See Also

SPLBUFFER, SplOptionGet, SPLSUGGEST, SplInit, SplLimitSet


SplQuit

This function is called by an application to end a spelling session and frees all resources that the SplInit function allocated for a spelling session.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplQuit ( HSPL hspl );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.

Return Values

1 indicates success. 0 indicates failure.

Remarks

SplQuit saves external user dictionaries and removes the internal user dictionaries.

See Also

SplInit


SplRemUserDict

This function removes a word from an internal or external user dictionary.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplRemUserDict ( HSPL hspl, int nID, const WCHAR * pwsz );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
nID
Identifier of the user dictionary.
pwsz
Pointer to a string that contains the word to remove from the dictionary.

Return Values

1 indicates success. 0 indicates failure.

Remarks

Words cannot be removed from the main dictionary.

When an application calls SplQuit, which ends a spelling session, the three internal user dictionaries are removed from memory; therefore, changes to those dictionaries affect the current spelling session only. Changes to external user dictionaries are saved for use during future spelling sessions.

See Also

SplAddUserDict, SplClrUserDict, SplInit, SplQuit, SplSizeUserDict


SplReplace

This function offers a suggestion that an application can use to automatically replace a misspelled word. An application that implements an inline spelling checker with an automatic replacement feature can use this function to automatically correct errors as a user inputs words.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplReplace( HSPL hspl, SPLBUFFER * psb );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
psb
Pointer to the SPLBUFFER structure for the checked word.

Return Values

1 indicates success. 0 indicates failure.

Remarks

To use SplReplace, an application must set a replacement error tolerance by calling the SplLimitSet function.

SplReplace combines the processing abilities of the SplCheck and SplSuggest functions for use in an inline spelling checker with an automatic replacement feature.

See Also

SPLBUFFER, SplCheck, SplInit, SplLimitSet, SplSuggest


SplSizeUserDict

This function gets the number of words in an internal or external user dictionary

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplSizeUserDict( HSPL hspl, int nID, DWORD * pdw );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
nID
Identification of the spelling dictionary.
pdw
Pointer to the DWORD the represents the size of the user dictionary.

Return Values

1 indicates success. 0 indicates failure.

Remarks

This function lets an application query the size of a user dictionary.

See Also

SplInit


SplSuggest

This function writes the spelling checker’s suggested spelling corrections to an output buffer pointed to by the pwszOut member of the SPLSUGGEST structure. It also can provide a score for each suggestion that indicates the likelihood that the suggestion is correct.

At a Glance

Header file: | Splapi.h
Windows CE versions: | 2.10 and later

Syntax

int SplSuggest( HSPL hspl, SPLBUFFER * psb );

Parameters

hspl
Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.
psb
Pointer to the SPLBUFFER structure in which the application locates the suggestions.

Return Values

1 indicates success. 0 indicates failure.

Remarks

The suggested words in the output buffer are null-terminated and ordered from the most likely to be correct to the least likely to be correct. An additional NULL character indicates the end of the output buffer. The size of the output buffer needs to be large enough for eight suggestions of a reasonable length; 128 characters is usually sufficient.

To score suggestions, set the SPL_SCORE_SUGGESTIONS flag in the dw parameter of the SplOptionSet function.

The score for a suggestion is based on the error types, as described in the following table. The score of each error type is determined by subtracting its value as defined in Splapi.h from 256. The higher the score, the more severe the error.

Error Type
Score
Description
SPL_LIMIT_NONE | 0 | The only spelling suggestion returned is for a word that is correctly spelled one way. For example, the suggestion for “i” is “I,” and the suggestion for “thier” is “their.”
SPL_LIMIT_CAPITAL | 1 | An error is corrected by capitalizing the initial letter of the word.
SPL_LIMIT_DROP_DOUBLE_CONSONANT | 14 | An error is corrected by substituting a double consonant for a single consonant.
SPL_LIMIT_ADD_DOUBLE_CONSONANT | 14 | An error is corrected by substituting a single consonant for a double consonant.
SPL_LIMIT_TRANSPOSE_VOWEL | 15 | An error is corrected by transposing two vowels.
SPL_LIMIT_DROP_DOUBLE_VOWEL | 16 | An error is corrected by substituting a single vowel for a double vowel.
SPL_LIMIT_ADD_DOUBLE_VOWEL | 16 | An error is corrected by substituting a double vowel for a single vowel.
SPL_LIMIT_TRANSPOSE_CONSONANT | 18 | An error is corrected by transposing two consonants.
SPL_LIMIT_TRANSPOSE | 19 | An error is corrected by transposing any two letters.
SPL_LIMIT_SUBSTITUTE_VOWEL | 21 | An error is corrected by substituting a vowel for another vowel.
SPL_LIMIT_DROP | 31 | An error is corrected by dropping a letter.
SPL_LIMIT_ADD | 35 | An error is corrected by adding a letter.
SPL_LIMIT_SUBSTITUTE_CONSONANT | 41 | An error is corrected by substituting a consonant for another consonant.
SPL_LIMIT_SUBSTITUTE | 43 | An error is corrected by substituting a letter for another letter.

For each suggestion, the error type describes what the spelling checker changed in the misspelled word to produce the suggestion. If the spelling checker capitalized the word to produce the suggestion, the score is 1. If the spelling checker substituted a double vowel for a single vowel to produce the suggestion, the score is 16. An application can use scores to determine whether to present suggestions to a user.

When the spelling checker corrects more than one error to arrive at a suggestion, the score is the sum of the error types. For example, a suggestion for the inputted word “monduy” is “Monday,” with a score of 22. The spelling checker capitalized the word—the SPL_LIMIT_CAPITAL error value is1—and changed “u” to “a”—the SPL_LIMIT_SUBSTITUTE_VOWEL error is 21.

The SplLimitSet function uses the same error types to set an error tolerance for an application that implements an inline spelling checker with an automatic replacement feature.

See Also

SPLBUFFER, SplInit, SplLimitSet, SplOptionSet, SPLSUGGEST


StgCreateDocfile

This function creates a new compound file storage object using the OLE-provided compound file implementation for the IStorage interface.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI StgCreateDocfile( const WCHAR * pwcsName,
DWORD grfMode, DWORD reserved, IStorage ** ppstgOpen);

Parameters

pwcsName
[in] Pointer to the path of the compound file to create. It is passed uninterpreted to the file system. This can be a relative name or NULL. If NULL, a temporary compound file is allocated with a unique name.
grfMode
[in] Specifies the access mode to use when opening the new storage object. For more information, see the STGM enumeration. If the caller specifies transacted mode together with STGM_CREATE or STGM_CONVERT, the overwrite or conversion takes place at the time the storage object is opened and therefore is not revertible.
reserved
[in] Reserved for future use; set to zero.
ppstgOpen
[out] Pointer to the location of the IStorage pointer to the new storage object.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Indicates that the compound file was successfully created.
STG_E_ACCESSDENIED | Indicates that access was denied because the caller has insufficient permission, or another caller has the file open and locked.
STG_E_FILEALREADYEXISTS | Indicates that the compound file already exists and grfMode is set to STGM_FAILIFTHERE.
STG_E_INSUFFICIENTMEMORY | Indicates that the compound file was not created due to a lack of memory.
STG_E_INVALIDFLAG | Indicates a bad flag combination in the grfMode pointer.
STG_E_INVALIDNAME | Indicates a bad name in the pwcsName parameter.
STG_E_INVALIDPOINTER | Indicates a bad pointer in the pwcsName parameter or the ppStgOpen parameter.
STG_E_LOCKVIOLATION | Indicates that access was denied because another caller has the file open and locked.
STG_E_SHAREVIOLATION | Indicates that access was denied because another caller has the file open and locked.
STG_E_TOOMANYOPENFILES | Indicates that the compound file was not created due to a lack of file handles.
STG_S_CONVERTED | Indicates that the specified file was successfully converted to Storage format.

This function can also return any file system errors or Win32 errors wrapped in an HRESULT.

Remarks

The StgCreateDocfile function creates a new storage object using the COM-provided, compound-file implementation for the IStorage interface. The name of the open compound file can be retrieved by calling the IStorage::Stat method.

StgCreateDocfile creates the file if it does not exist. If it does exist, the use of the STGM_CREATE, STGM_CONVERT, and STGM_FAILIFTHERE flags in the grfMode parameter indicate how to proceed. See the STGM enumeration for more information on these values.

If the compound file is opened in transacted mode (the grfMode parameter specifies STGM_TRANSACTED) and a file with this name already exists, the existing file is not altered until all outstanding changes are committed. If the calling process lacks write access to the existing file (because of access control in the file system), the grfMode parameter can only specify STGM_READ and not STGM_WRITE or STGM_READWRITE. The resulting new open compound file can still be written to, but a subsequent commit operation will fail (in transacted mode, write permissions are enforced at commit time).

Specifying STGM_SIMPLE provides a much faster implementation of a compound file object in a limited, but frequently-used case. This can be used by applications that require a compound file implementation with multiple streams and no storages. The simple mode does not support all of the methods on IStorage. For more information, refer to the STGM enumeration.

If the grfMode parameter specifies STGM_TRANSACTED and no file yet exists with the name specified by the pwcsName parameter, the file is created immediately. In an access-controlled file system, the caller must have write permissions in the file system directory in which the compound file is created. If STGM_TRANSACTED is not specified, and STGM_CREATE is specified, an existing file with the same name is destroyed before creating the new file.

StgCreateDocfile can be used to create a temporary compound file by passing a NULL value for the pwcsName parameter. However, these files are temporary only in the sense that they have a system-provided unique name – likely one that is meaningless to the user. The caller is responsible for deleting the temporary file when finished with it, unless STGM_DELETEONRELEASE was specified for the grfMode parameter.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


StgCreateDocfileOnILockBytes

This function creates and opens a new compound file storage object on top of a byte array object provided by the caller. The storage object supports the OLE-provided, compound-file implementation for the IStorage interface.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI StgCreateDocfileOnILockBytes( ILockBytes * plkbyt, DWORD grfMode, DWORD reserved, IStorage ** ppstgOpen);

Parameters

plkbyt
[in] Pointer to the ILockBytes interface on the underlying byte array object on which to create a compound file.
grfMode
[in] Specifies the access mode to use when opening the new compound file. For more information, see the STGM enumeration.
reserved
[in] Reserved for future use; set to zero.
ppstgOpen
[out] Pointer to the location of the IStorage pointer on the new storage object.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK
 Indicates that the compound file was successfully created.
STG_E_ACCESSDENIED
 Indicates that access was denied because the caller has insufficient permission, or another caller has the file open and locked.
STG_E_FILEALREADYEXISTS
 Indicates that the compound file already exists and the grfMode parameter is set to STGM_FAILIFTHERE.
STG_E_INSUFFICIENTMEMORY
 Indicates that the storage object was not created due to a lack of memory.
STG_E_INVALIDPOINTER
 Indicates a bad pointer was in the pLkbyt parameter or the ppStgOpen parameter.
STG_E_INVALIDFLAG
 Indicates a bad flag combination was in the grfMode parameter.
STG_E_TOOMANYOPENFILES
 Indicates the storage object was not created due to a lack of file handles.
STG_E_LOCKVIOLATION
 Indicates that access was denied because another caller has the file open and locked.
STG_E_SHAREVIOLATION
 Indicates that access was denied because another caller has the file open and locked.
STG_S_CONVERTED
 Indicates that the compound file was successfully converted. The original byte array object was successfully converted to IStorage format.

This function can also return any file system errors, or Win32 errors wrapped in an HRESULT, or ILockBytes interface error return values.

Remarks

The StgCreateDocfileOnILockBytes and StgOpenStorageOnILockBytes functions are not available for the non-desktop compatible implementation by means of CESYSGEN.

The StgCreateDocfileOnILockBytes function creates a storage object on top of a byte array object using the COM-provided, compound-file implementation of the IStorage interface. StgCreateDocfileOnILockBytes can be used to store a document in a relational database. The byte array (indicated by the pLkbyt parameter, which points to the ILockBytes interface on the object) is used for the underlying storage in place of a disk file.

Except for specifying a programmer-provided byte-array object, StgCreateDocfileOnILockBytes is similar to the StgCreateDocfile function. For more information, refer to StgCreateDocfile.

The newly created compound file is opened according to the access modes in the grfMode parameter. For conversion purposes, the file is always considered to already exist. As a result, it is not useful to use the STGM_FAILIFTHERE value, because it always causes an error to be returned. However, STGM_CREATE and STGM_CONVERT are both still useful.

The ability to build a compound file on top of a byte array object is provided to support having the data (underneath an IStorage and IStream tree structure) live in a non-persistent space. Given this capability, there is nothing preventing a document that is stored in a file from using this facility. For example, a container might do this to minimize the impact on its file format caused by adopting COM. However, it is recommended that COM documents adopt the IStorage interface for their own outer-level storage. This has the following advantages:

  • The storage structure of the document is the same as its storage structure when it is an embedded object, reducing the number of cases the application needs to handle.
  • One can write tools to access the OLE embeddings and links within the document without special knowledge of the document's file format. An example of such a tool is a copy utility that copies all the documents included in a container containing linked objects. A copy utility like this needs access to the contained links to determine the extent of files to be copied.
  • The IStorage implementation addresses the problem of how to commit the changes to the file. An application using the ILockBytes interface must handle these issues itself.
  • Future file systems will likely implement the IStorage and IStream interfaces as their native abstractions, rather than layer on top of a byte array as is done in compound files. Such a file system could be built so documents using the IStorage interface as their outer level containment structure would get an automatic efficiency gain by having the layering flattened when files are saved on the new file system.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


StgOpenStorage

This function opens an existing root storage object in the file system. You can use this function to open compound files, but you cannot use it to open directories, files, or summary catalogs. Nested storage objects can only be opened using their parent’s IStorage::OpenStorage method.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI StgOpenStorage( const WCHAR * pwcsName,
IStorage * pstgPriority, DWORD grfMode, SNB snbExclude,
DWORD reserved, IStorage ** ppstgOpen);

Parameters

pwcsName
[in] Pointer to the path of the file containing the storage object to open. This parameter is ignored if the pStgPriority parameter is not NULL.
pstgPriority
[in] Most often NULL. If not NULL, this parameter is used instead of the pwcsName parameter to specify the pointer to the IStorage interface on the storage object to open. It points to a previous opening of a root storage object, most often one that was opened in priority mode.

After the StgOpenStorage function returns, the storage object specified in the pStgPriority parameter on function entry is invalid, and can no longer be used. Instead, use the one specified in the ppStgOpen parameter instead.

[in] Specifies the access mode to use to open the storage object.

snbExclude
[in] If not NULL, this parameter points to a block of elements in the storage that are to be excluded as the storage object is opened. The exclusion occurs independent of whether a snapshot copy happens on the open. May be NULL.
reserved
[in] Reserved for future use; set to zero.
ppstgOpen
[out] Pointer to the IStorage* pointer variable that receives the interface pointer to the opened storage.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The storage object was successfully opened.
STG_E_FILENOTFOUND | The specified file does not exist.
STG_E_ACCESSDENIED | Access was denied because the caller had insufficient permission, or another caller had the file open and locked.
STG_E_LOCKVIOLATION | Access was denied because another caller had the file open and locked.
STG_E_SHAREVIOLATION | Access was denied because another caller had the file open and locked.
STG_E_FILEALREADYEXISTS | The file exists but is not a storage object.
STG_E_TOOMANYOPENFILES | The storage object was not opened because there are too many open files.
STG_E_INSUFFICIENTMEMORY | The storage object was not opened due to a lack of memory.
STG_E_INVALIDNAME | There is a bad name in the pwcsName parameter.
STG_E_INVALIDPOINTER | There is a bad pointer in the snbExclude, pwcsName, pstgPriority, or ppStgOpen parameter.
STG_E_INVALIDFLAG | There is a bad flag combination in the grfMode parameter.
STG_E_INVALIDFUNCTION | STGM_DELETEONRELEASE was specified in the grfMode parameter.
STG_E_OLDFORMAT | The storage object being opened was created by the Beta 1 storage provider. This format is no longer supported.
STG_E_NOTSIMPLEFORMAT | The STGM_SIMPLE flag was specified in the grfMode parameter and the storage object being opened was not written in simple mode.
STG_E_OLDDLL | The DLL being used to open this storage object is a version prior to the one used to create it.
STG_E_PATHNOTFOUND | The specified path does not exist.

This function can also return any file system errors or Win32 errors wrapped in an HRESULT.

Remarks

The StgOpenStorage function opens the specified root storage object according to the access mode in the grfMode parameter, and, if successful, supplies an IStorage pointer to the opened storage object in the ppstgOpen parameter.

To support the Simple mode for saving a storage object with no substorages, the StgOpenStorage function accepts the following flag combinations as valid modes in the grfMode parameter: STGM_SIMPLE|STGM_READWRITE|STGM_SHARE_EXCLUSIVE and STGM_SIMPLE|STGM_READ|STGM_SHARE_EXCLUSIVE.

To support the single-writer, multi-reader, direct mode, the following flag combinations are valid modes in the grfMode parameter: STGM_READWRITE|STGM_SHARE_DENY_WRITE and STGM_READ|STGM_SHARE_DENY_NONE.

Opening a storage object in read and/or write mode without denying writer permission to others (the grfMode parameter specifies STGM_SHARE_DENY_WRITE) can be a time-consuming operation since the StgOpenStorage call must make a snapshot of the entire storage object.

Applications often try to open storage objects with the following access permissions:

STGM_READ_WRITE | STGM_SHARE_DENY_WRITE
 // transacted vs. direct mode omitted for exposition

If the application succeeds, it never needs to do a snapshot copy. If it fails, the application can revert to using the permissions and make a snapshot copy:

STGM_READ_WRITE
 // transacted vs. direct mode omitted for exposition

In this case, the application should prompt the user before doing a time-consuming copy. Alternatively, if the document sharing semantics implied by the access modes are appropriate, the application could try to open the storage as follows:

STGM_READ | STGM_SHARE_DENY_WRITE
 // transacted vs. direct mode omitted for exposition

In this case, if the application succeeds, a snapshot copy will not have been made (because STGM_SHARE_DENY_WRITE was specified, denying others write access).

To reduce the expense of making a snapshot copy, applications can open storage objects in priority mode (grfMode specifies STGM_PRIORITY).

The snbExclude parameter specifies a set of element names in this storage object that are to be emptied as the storage object is opened: streams are set to a length of zero; storage objects have all their elements removed. By excluding certain streams, the expense of making a snapshot copy can be significantly reduced. Almost always, this approach is used after first opening the storage object in priority mode, then completely reading the now-excluded elements into memory. This earlier priority mode opening of the storage object should be passed through the pstgPriority parameter to remove the exclusion implied by priority mode. The calling application is responsible for rewriting the contents of excluded items before committing. Thus, this technique is most likely only useful to applications whose documents do not require constant access to their storage objects while they are active.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


StgOpenStorageOnILockBytes

This function opens an existing storage object that does not reside in a disk file, but instead has an underlying byte array provided by the caller.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI StgOpenStorageOnILockBytes( ILockBytes * plkbyt,
IStorage * pStgPriority, DWORD grfMode, SNB snbExclude,
DWORD reserved, IStorage ** ppstgOpen);

Parameters

plkbyt
[in] ILockBytes pointer to the underlying byte array object that contains the storage object to be opened.
pStgPriority
[in] Most often NULL. If not NULL, this parameter is used instead of the plkbyt parameter to specify the storage object to open. In this case, it points to the IStorage interface on a previously opened root storage object, most often one that was opened in priority mode.

After the StgOpenStorageOnILockBytes function returns, the storage object specified in the pStgPriority parameter on function entry is invalid, and can no longer be used; use the one specified in the ppStgOpen parameter instead.

grfMode
[in] Specifies the access mode to use to open the storage object.
snbExclude
[in] Can be NULL. If not NULL, this parameter points to a block of elements in this storage that are to be excluded as the storage object is opened. This exclusion occurs independent of whether a snapshot copy happens on the open.
reserved
[in] Reserved for future use; set to zero.
ppstgOpen
[out] Pointer to the location of an IStorage pointer to the opened storage on successful return.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Indicates that the storage object was successfully opened.
STG_E_FILENOTFOUND | Indicates that the specified byte array does not exist.
STG_E_ACCESSDENIED | Indicates that access was denied because the caller has insufficient permission, or another caller has the file open and locked.
STG_E_LOCKVIOLATION | Indicates that access was denied because another caller has the file open and locked.
STG_E_SHAREVIOLATION | Indicates that access was denied because another caller has the file open and locked.
STG_E_FILEALREADYEXISTS | Indicates that the byte array exists but is not a storage object.
STG_E_TOOMANYOPENFILES | Indicates that the storage object was not opened because there are too many open files.
STG_E_INSUFFICIENTMEMORY | Indicates that the storage object was not opened due to a lack of memory.
STG_E_INVALIDNAME | Indicates that either pwcsName or snbExclude contains an invalid name.
STG_E_INVALIDPOINTER | Indicates that snbExclude, pwcsName, pstgPriority, or ppStgOpen contains an invalid pointer.
STG_E_INVALIDFLAG | Indicates that the grfMode parameter contains a bad flag combination.
STG_E_INVALIDFUNCTION | Indicates that the access mode STGM_DELETEONRELEASE was specified in the grfMode parameter.
STG_E_OLDDLL | Indicates that the DLL being used to open this storage object is a version prior to the one used to create it.
STG_E_OLDFORMAT | Indicates that the storage object being opened was created by the Beta 1 storage provider. This format is no longer supported.

This function can also return any file system errors, or Win32 errors wrapped in an HRESULT, or ILockBytes interface error return values.

Remarks

The StgCreateDocfileOnILockBytes and StgOpenStorageOnILockBytes functions are not available for the non-desktop compatible implementation by means of CESYSGEN.

StgOpenStorageOnILockBytes opens the specified root storage object. The storage object is opened according to the access mode in the grfMode parameter; a pointer to the IStorage interface on the opened storage object is supplied through the ppstgOpen parameter.

The storage object must have been previously created by the StgCreateDocfileOnILockBytes function.

Except for specifying a programmer-provided byte-array object, StgOpenStorageOnILockBytes is similar to the StgOpenStorage function. For more information, refer to StgOpenStorage.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


StringFromCLSID

This function converts a class identifier into a string of printable characters. Different class identifiers always convert to different strings.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI StringFromCLSID(REFCLSID rclsid, LPOLESTR * ppsz);

Parameters

rclsid
[in] Class identifier to be converted.
ppsz
[out] Address of LPOLESTR pointer variable that receives a pointer to the resulting null-terminated string.

Return Values

S_OK indicates the class identifier was successfully converted and returned. The standard return value E_OUTOFMEMORY is also supported.

Remarks

The StringFromCLSID function calls the StringFromGuid2 function to convert a globally unique identifier (GUID) into a string of printable characters.

The caller is responsible for freeing the memory allocated for the string by calling CoTaskMemFree.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


StringFromGUID2

This function converts a globally unique identifier (GUID) into a string of printable characters.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

StringFromGUID2(REFGUID rguid, LPOLESTR lpsz, int cbMax);

Parameters

rguid
[in] Interface identifier to be converted.
lpsz
[out] Long pointer to the resulting null-terminated string on return.
cbMax
[in] Character count of the string indicated by lpsz.

Return Values

Nonzero indicates the number of characters in the returned string, including the terminating null character. Zero indicates that the buffer is too small for returned string.

Remarks

The string that the lpsz parameter receives has a format like that of the following sample:

{c200e360-38c5–11ce-ae62-08002b2b79ef}

where the successive fields break the GUID into the form DWORD-WORD-WORD-WORD-WORD.DWORD covering the 128-bit GUID. The string includes enclosing braces, which are an OLE convention.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


StringFromIID

This function converts an interface identifier into a string of printable characters.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI StringFromIID(REFIID rclsid, LPOLESTR * lplpsz);

Parameters

rclsid
[in] Interface identifier to be converted.
lplpsz
[out] Address of LPOLESTR pointer variable that receives a pointer to the resulting null-terminated string.

Return Values

S_OK indicates that the character string was successfully returned. The standard return value E_OUTOFMEMORY is also supported.

Remarks

The string returned by the function is freed in the standard way, using the task allocator.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.


SubtractRect

This function obtains the coordinates of a rectangle determined by subtracting one rectangle from another.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SubtractRect(LPRECT lprcDst, const RECT *lprcSrc1,
const RECT *lprcSrc2);

Parameters

lprcDst
Long pointer to a RECT structure that receives the coordinates of the rectangle determined by subtracting the rectangle pointed to by lprcSrc2 from the rectangle pointed to by lprcSrc1.
lprcSrc1
Long pointer to a RECT structure from which the function subtracts the rectangle pointed to by lprcSrc2.
lprcSrc2
Long pointer to a RECT structure that the function subtracts from the rectangle pointed to by lprcSrc1.

Return Values

Nonzero indicates success. Zero indicates failure.

To get extended error information, call GetLastError.

Remarks

The function only subtracts the rectangle specified by lprcSrc2 from the rectangle specified by lprcSrc1 when the rectangles intersect completely in either the x- or y-direction. For example, if *lprcSrc1 has the coordinates (10,10,100,100) and *lprcSrc2 has the coordinates (50,50,150,150), the function sets the coordinates of the rectangle pointed to by lprcDst to (10,10,100,100). If *lprcSrc1 has the coordinates (10,10,100,100) and *lprcSrc2 has the coordinates (50,10,150,150), however, the function sets the coordinates of the rectangle pointed to by lprcDst to (10,10,50,100).

See Also

IntersectRect, RECT, UnionRect


SuspendThread

This function suspends the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD SuspendThread(HANDLE hThread);

Parameters

hThread
Handle to the thread.

Return Values

The thread’s previous suspend count indicates success. 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

Remarks

If the function succeeds, execution of the specified thread is suspended and the thread’s suspend count is incremented.

Suspending a thread causes the thread to stop executing user-mode (application) code.

If the thread is making a kernel call, SuspendThread fails. An application may need to repeat the SuspendThread several times for it to succeed.

Each thread has a suspend count (with a maximum value of MAXIMUM_SUSPEND_COUNT). If the suspend count is greater than zero, the thread is suspended; otherwise, the thread is not suspended and is eligible for execution. Calling SuspendThread causes the target thread’s suspend count to be incremented. Attempting to increment past the maximum suspend count causes an error without incrementing the count.

The ResumeThread function decrements the suspend count of a suspended thread.

See Also

ResumeThread


SysAllocString

This function allocates a new string and copies the passed string into it. SysAllocString returns null if there is insufficient memory or if a null pointer is passed in.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

BSTR SysAllocString(OLECHAR FAR * sz);

Parameters

sz
Null-terminated string to copy. The sz parameter must be a Unicode string in 32-bit applications, and an ANSI string in 16-bit applications.

Return Values

A pointer to a BSTR that contains the string indicates success. NULL indicates that insufficient memory exists or the sz parameter was NULL.

Example

inline void CStatBar::SetText(OLECHAR FAR* sz)
{
    SysFreeString(m_BSTRMsg);
    m_BSTRMsg = SysAllocString(sz);
}

Remarks

Windows CE supports only Unicode strings.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

You can free strings created with SysAllocString using SysFreeString.

Example

inline void CStatBar::SetText(OLECHAR FAR* sz)
{
    SysFreeString(m_BSTRMsg);
    m_BSTRMsg = SysAllocString(sz);
}


SysAllocStringByteLen

This function takes an ANSI string as input, and returns a BSTR that contains an ANSI string. This function does not perform any ANSI to Unicode translation.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

BSTR SysAllocStringByteLen(char FAR * psz, unsigned int len);

Parameters

psz
Null-terminated string to copy, or NULL to keep the string uninitialized.
len
Number of bytes to copy from psz. A null character is placed afterwards, allocating a total of len+1 bytes.

Allocates a new string of len bytes, copies len bytes from the passed string into it, and then appends a null character. Valid only for 32-bit systems.

Return Values

A pointer to a copy of the string indicates success. NULL inidcates that insufficient memory exists.

Remarks

This function is provided to create BSTRs that contain binary data. You can use this type of BSTR only in situations where it will not be translated from ANSI to Unicode, or vice versa.

For example, do not use these BSTRs between a 16-bit and a 32-bit application running on a 32-bit Windows system. The OLE 16-bit to 32-bit (and 32-bit to 16-bit) interoperability layer will translate the BSTR and corrupt the binary data. The preferred method of passing binary data is to use a SAFEARRAY of VT_UI1, which will not be translated by OLE.

If psz is NULL, a string of the requested length is allocated, but not initialized. The string psz can contain embedded null characters, and does not need to end with a NULL. Free the returned string later with SysFreeString.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SysAllocStringLen

This function allocates a new string, copies cch characters from the passed string into it, and then appends a null character.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

BSTR SysAllocStringLen(OLECHAR FAR * pch, unsigned int cch);

Parameters

pch
Pointer to cch characters to copy, or NULL to keep the string uninitialized.
cch
Number of characters to copy from pch. A null character is placed afterwards, allocating a total of cch+1 characters.

Return Values

A pointer to a copy of the string indicates success. NULL indicates that insufficient memory exists.

Remarks

If pch is NULL, a string of the requested length is allocated, but not initialized. The pch string can contain embedded null characters and does not need to end with a NULL. Free the returned string later with SysFreeString.

Windows CE supports only Unicode strings.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SysFreeString

This function frees a string allocated previously by SysAllocString, SysAllocStringByteLen, SysReAllocString, SysAllocStringLen, or SysReAllocStringLen.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SysFreeString(BSTR bstr);

Parameters

bstr
Unicode string that was allocated previously, or NULL. If NULL, the function simply returns.

Return Values

None.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

CStatBar::~CStatBar()
{
    SysFreeString(m_BSTRMsg);
}


SysReAllocString

This function allocates a new BSTR and copies the passed string into it, then frees the BSTR referenced by pbstr, and finally resets pbstr to point to the new BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SysReAllocString(BSTR FAR * pbstr, OLECHAR FAR * sz);

Parameters

pbstr
Pointer to a variable that contains a BSTR.
sz
Null-terminated string to copy.

Return Values

FALSE indicates that insufficient memory exists.

Remarks

Windows CE supports only Unicode strings.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SysReAllocStringLen

This function creates a new BSTR that contains a specified number of characters from an old BSTR, and frees the old BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SysReAllocStringLen(BSTR FAR* pbstr, OLECHAR FAR* pch, unsigned int cch);

Parameters

pbstr
Pointer to a variable that contains a BSTR.
pch
Pointer to cch characters to copy, or NULL to keep the string uninitialized.
cch
Number of characters to copy from pch. A null character is placed afterward, allocating a total of cch+1 characters.

Return Values

TRUE indicates that the string is reallocated successfully. FALSE indicates that insufficient memory exists.

Remarks

The SysReAllocStringLen function allocates a new string, copies cch characters from the passed string into it, and then appends a null character. Frees the BSTR referenced currently by pbstr, and resets pbstr to point to the new BSTR. If pch is NULL, a string of length cch is allocated but not initialized.

The pch string can contain embedded null characters and does not need to end with a NULL.

Windows CE supports only Unicode strings.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


SysStringByteLen

This function returns the length (in bytes) of a BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SysStringByteLen(BSTR bstr);

Parameters

bstr
Unicode string that was allocated previously. It cannot be NULL.

Return Values

The number of bytes in bstr, not including a terminating null character, indicates success.

Remarks

The returned value may be different from fstrlen(bstr) if the BSTR was allocated with Sys[Re]AllocStringLen or SysAllocStringByteLen, and the passed-in characters included a null character in the first len characters. For a BSTR allocated with Sys[Re]AllocStringLen or SysAllocStringByteLen, this function always returns the number of bytes specified in the len parameter at allocation time.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

// Display the status message.

TextOut(
    hdc,
    rcMsg.left + (m_dxFont / 2),
    rcMsg.top + ((rcMsg.bottom - rcMsg.top - m_dyFont) / 2),
    m_BSTRMsg, SysStringByteLen(m_BSTRMsg));


SysStringLen

This function returns the length of a BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SysStringLen(BSTR bstr);

Parameters

bstr
Unicode string that was allocated previously. It cannot be NULL.

Return Values

The number of characters in bstr, not including a terminating null character, indicates success.

Remarks

The returned value may be different from _fstrlen(bstr) if the BSTR was allocated with Sys[Re]AllocStringLen or SysAllocStringByteLen, and the passed-in characters included a null character in the first cch characters. For a BSTR allocated with Sys[Re]AllocStringLen or SysAllocStringByteLen, the SysStringLen function always returns the number of characters specified in the cch parameter at allocation time.

Windows CE supports only Unicode strings.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

// Display the status message.
//
TextOut(
    hdc,
    rcMsg.left + (m_dxFont / 2),
    rcMsg.top + ((rcMsg.bottom - rcMsg.top - m_dyFont) / 2),
    m_BSTRMsg, SysStringLen(m_BSTRMsg));


SystemIdleTimerReset

This function resets a system timer that controls whether or not the device will automatically go into a suspended state.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.12 and later

Syntax

void WINAPI SystemIdleTimerReset( void);

Return Values

None.

Remarks

In Windows CE, the default behavior is to go into a suspended state after a specified period of time expires. This time interval is specified in the registry. Calling SystemIdleTimerReset overrides the registry setting by resetting the timer.

This function must be use appropriately. On battery powered devices, a program that never suspends (or sleeps) by continually calling SystemIdleTimerReset can quickly drain the batteries.

The frequency in which to call SystemIdleTimerReset in order to keep a device awake can be determined retrieving the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Power


SystemParametersInfo

This function queries or sets system-wide parameters, and updates the user profile during the process.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

BOOL SystemParametersInfo ( UINT uiAction, UINT uiParam,
PVOID pvParam, UINT fWinIni);

Parameters

uiAction
[in] Specifies the system-wide parameter to query or set. This parameter can be one of the following values:
Value
Description
SPI_GETBATTERYIDLETIMEOUT | Gets the amount of time that Windows CE will stay on with battery power before it suspends due to user inaction. The pvParam parameter points to a DWORD that returns the time in seconds. This flag is ignored if pvParam is zero.
SPI_GETEXTERNALIDLETIMEOUT | Gets the amount of time that Windows CE will stay on with AC power before it suspends due to user inaction. The pvParam parameter points to a DWORD that returns the time in seconds. This flag is ignored if pvParam is zero.
SPI_GETMOUSE | Retrieves the two mouse threshold values and the mouse speed.
SPI_GETOEMINFO | Returns a string containing the model number and manufacturer name. The uiParam parameter specifies the length of the buffer in pvParam, which on successful return contains the string in Unicode characters.
SPI_GETPLATFORMTYPE | Returns a string specifying the type of Windows CE device, such as “H/PC.” The uiParam parameter specifies the length of the buffer in pvParam, which on successful return contains the string in Unicode characters. This string allows applications like H/PC Explorer to determine the device type.
SPI_GETWAKEUPIDLETIMEOUT | Gets the amount of time that Windows CE will stay on after a user notification that reactivates a suspended device. The pvParam parameter points to a DWORD that returns the time in seconds. This flag is ignored if pvParam is zero.
SPI_GETWORKAREA | Retrieves the size of the work area; the portion of the screen not obscured by the tray.
SPI_SETBATTERYIDLETIMEOUT | Sets the amount of time that Windows CE will stay on with battery power before it suspends due to user inaction. The Windows CE operating system will remain on, with battery power, as long as the keyboard or touch screen is active. The uiParam parameter specifies the time to set in seconds. This flag is ignored if uiParam is set to zero.
SPI_SETEXTERNALIDLETIMEOUT
Sets the amount of time that Windows CE will stay on with AC power before it suspends due to user inaction. The Windows CE operating system will remain on, with AC power, as long as the keyboard or touch screen is active. The uiParam parameter specifies the time in seconds. This flag is ignored if uiParam is set to zero.
SPI_SETMOUSE | Sets the two mouse threshold values and the mouse speed.
SPI_SETWAKEUPIDLETIMEOUT | Sets the amount of time that Windows CE will stay on after a user notification that reactivates the suspended device. The uiParam parameter specifies the time in seconds. This flag is ignored if uiParam is set to zero.
SPI_SETWORKAREA | Sets the size of the work area—the portion of the screen not obscured by the taskbar.

uiParam
[in] Depends on the system parameter being queried or set. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify zero for this parameter.
pvParam
[out] Depends on the system parameter being queried or set. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify NULL for this parameter.

If the pvParam buffer is used to get the platform type or OEM information string and the buffer is too small, this function fails with ERROR_INSUFFICIENT_BUFFER in the last error.

fWinIni
[in] Boolean that, if a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change. This parameter can be zero or can be one of the following values:
Value
Description
SPIF_UPDATEINIFILE | Writes the new system-wide parameter setting to the user profile.
SPIF_SENDCHANGE | Broadcasts the WM_SETTINGCHANGE message after updating the user profile.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This function is intended for use with applications, such as the Control Panel, that allow the user to customize the environment.

Windows CE supports only the Unicode version of this function.

See Also

GetSystemMetrics


SystemTimeToFileTime

This function converts a system time to a file time.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL SystemTimeToFileTime( const SYSTEMTIME *lpSystemTime,
LPFILETIME lpFileTime );

Parameters

lpSystemTime
[in] Pointer to a SYSTEMTIME structure that contains the time to be converted.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

lpFileTime
[out] Pointer to a FILETIME structure to receive the converted system time.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

See Also

FILETIME, FileTimeToSystemTime, SYSTEMTIME


SystemTimeToVariantTime

This function converts the variant representation of time to system-time values.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT SystemTimeToVariantTime(SYSTEMTIME lpSystemTime, double * pvtime);

Parameters

lpSystemTime
Long pointer to the system time.
pvtime
Void pointer to the returned variant time.

Remarks

A variant time is stored as an 8-byte real value (double), representing a date between January 1, 1753 and December 31, 2078, inclusive. The value 2.0 represents January 1, 1900; 3.0 represents January 2, 1900, and so on. Adding 1 to the value increments the date by a day. The fractional part of the value represents the time of day. Therefore, 2.5 represents noon on January 1, 1900; 3.25 represents 6:00 A.M. on January 2, 1900, and so on. Negative numbers represent the dates prior to December 30, 1899.

The SYSTEMTIME structure is useful for the following reasons:

  • It spans all time/date periods. MS-DOS date/time is limited to representing only those dates between 1/1/1980 and 12/31/2107.
  • The date/time elements are all easily accessible without needing to do any bit decoding.
  • The National Data Support data and time formatting functions GetDateFormat and GetTimeFormat take a SYSTEMTIME value as input. For more information, see the Win32 Programmer’s Reference in the Win32 SDK.
  • It is the default Win32 time/date data format supported by Windows NT and Windows 95.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


TerminateProcess

This function terminates the specified process and all of its threads.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TerminateProcess(HANDLE hProcess, DWORD uExitCode);

Parameters

hProcess
Handle to the process to terminate.
uExitCode
Specifies the exit code for the process and for all threads terminated as a result of this call. Use the GetExitCodeProcess function to retrieve the process’s exit value. Use the GetExitCodeThread function to retrieve a thread’s exit value.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The TerminateProcess function is used to unconditionally cause a process to exit. Use it only in extreme circumstances. The state of global data maintained by dynamic-link libraries (DLLs) may be compromised if TerminateProcess.

TerminateProcess causes all threads within a process to terminate, and causes a process to exit, but DLLs attached to the process are not notified that the process is terminating.

Terminating a process causes the following:

  1. All of the object handles opened by the process are closed.
  2. All of the threads in the process terminate their execution.
  3. The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.
  4. The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.
  5. The termination status of the process changes from STILL_ACTIVE to the exit value of the process.

Terminating a process does not cause child processes to be terminated.

Terminating a process does not necessarily remove the process object from the system. A process object is deleted when the last handle to the process is closed.

For Windows CE version 1.0, the uExitCode parameter is ignored because process exit codes are not supported.


TerminateThread

This function stops the specified thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL TerminateThread( HANDLE hThread, DWORD dwExitCode );

Parameters

hThread
Handle to the thread to terminate.
dwExitCode
Specifies the exit code for the thread. Use the GetExitCodeThread function to retrieve a thread’s exit value.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

TerminateThread is used to cause a thread to exit. When this occurs, the target thread has no chance to execute any user-mode code and its initial stack is not deallocated. DLLs attached to the thread are not notified that the thread is terminating.

This function reduces memory leaks by clearing the stack before exiting. It also terminates the thread process only if the thread in question is the main or primary thread.

TerminateThread is a dangerous function that should only be used in the most extreme cases. You should call TerminateThread only if you know exactly what the target thread is doing, and you control all of the code that the target thread could possibly be running at the time of the termination. For example, TerminateThread can result in the following problems:

  • If the target thread owns a critical section, the critical section will not be released.
  • If the target thread is executing certain kernel32 calls when it is terminated, the kernel32 state for the thread’s process could be inconsistent.
  • If the target thread is manipulating the global state of a shared DLL, the state of the DLL could be destroyed, affecting other users of the DLL.

A thread cannot protect itself against TerminateThread, other than by controlling access to its handles. The thread handle returned by the CreateThread and CreateProcess functions has THREAD_TERMINATE access, so any caller holding one of these handles can terminate your thread.

If the target thread is the last thread of a process when this function is called, the thread’s process is also terminated.

The state of the thread object becomes signaled, releasing any other threads that had been waiting for the thread to terminate. The thread’s termination status changes from STILL_ACTIVE to the value of the dwExitCode parameter.

Terminating a thread does not necessarily remove the thread object from the system. A thread object is deleted when the last thread handle is closed.


Thread32First

This function retrieves information about the first thread of any process encountered in a system snapshot.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Thread32First( HANDLE hSnapshot, LPTHREADENTRY32 lpte);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lpte
Pointer to a THREADENTRY32 structure.

Return Value

TRUE indicates that the first entry of the thread list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no threads exist or the snapshot does not contain thread information.

Remarks

The calling application must set the dwSize member of THREADENTRY32 to the size, in bytes, of the structure. Thread32First changes dwSize to the number of bytes written to the structure. This will never be greater than the initial value of dwSize, but it may be smaller. If the value is smaller, do not rely on the values of any members whose offsets are greater than this value.

To retrieve information about other threads recorded in the same snapshot, use the Thread32Next function.


Thread32Next

This function retrieves information about the next thread of any process encountered in the system memory snapshot.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Thread32Next( HANDLE hSnapshot, LPTHREADENTRY32 lpte);

Parameters

hSnapshot
Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.
lpte
Pointer to a THREADENTRY32 structure.

Return Value

TRUE indicates that the next entry of the thread list has been copied to the buffer. FALSE indicates failure. The ERROR_NO_MORE_FILES error value, returned by GetLastError, indicates that no threads exist or the snapshot does not contain thread information.

Remarks

To retrieve information about the first thread recorded in a snapshot, use the Thread32First function.


TimerProc

This function is an application-defined callback function that processes WM_TIMER messages.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

void CALLBACK TimerProc(HWND hwnd, UINT uMsg, UINT idEvent, DWORD dwTime);

Parameters

hwnd
[in] Handle to the window associated with the timer.
uMsg
[in] Specifies the WM_TIMER message.
idEvent
[in] Identifier of the timer.
dwTime
[in] Specifies the number of milliseconds that have elapsed since the system was started. This is the value returned by the GetTickCount function.

Return Values

None.

See Also

KillTimer, SetTimer, WM_TIMER, GetTickCount


TlsAlloc

This function allocates a thread local storage (TLS) index. Any thread of the process can subsequently use this index to store and retrieve values that are local to the thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD TlsAlloc(void);

Return Values

A TLS index indicates success. 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError.

Remarks

The threads of the process can use the TLS index in subsequent calls to the TlsFree, TlsSetValue, or TlsGetValue functions.

TLS indexes are typically allocated during process or dynamic-link library (DLL) initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot. To store a value in its slot, a thread specifies the index in a call to TlsSetValue. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

The constant TLS_MINIMUM_AVAILABLE defines the minimum number of TLS indexes available in each process. This minimum is guaranteed to be at least 64 for all systems.

TLS indexes are not valid across process boundaries. A DLL cannot assume that an index assigned in one process is valid in another process.

A DLL might use TlsAlloc, TlsSetValue, TlsGetValue, and TlsFree as follows:

  1. When a DLL attaches to a process, the DLL uses TlsAlloc to allocate a TLS index. The DLL then allocates some dynamic storage and uses the TLS index in a call to TlsSetValue to store the address in the TLS slot. This concludes the per-thread initialization for the initial thread of the process. The TLS index is stored in a global or static variable of the DLL.
  2. Each time the DLL attaches to a new thread of the process, the DLL allocates some dynamic storage for the new thread and uses the TLS index in a call to TlsSetValue to store the address in the TLS slot. This concludes the per-thread initialization for the new thread.
  3. Each time an initialized thread makes a DLL call requiring the data in its dynamic storage, the DLL uses the TLS index in a call to TlsGetValue to retrieve the address of the dynamic storage for that thread.

For additional information on thread local storage, see Writing Memory-Efficient Applications.

See Also

TlsFree, TlsGetValue, TlsSetValue


TlsFree

This function releases a thread local storage (TLS) index, making it available for reuse.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TlsFree(DWORD dwTlsIndex);

Parameters

dwTlsIndex
Specifies a TLS index that was allocated by the TlsAlloc function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If the threads of the process have allocated dynamic storage and used the TLS index to store pointers to this storage, they should free the storage before calling TlsFree. The TlsFree function does not free any dynamic storage that has been associated with the TLS index. It is expected that DLLs call this function (if at all) only during their process detach routine.

For a brief discussion of typical uses of the TLS functions, see the Remarks section of the TlsAlloc function.

See Also

TlsAlloc, TlsGetValue, TlsSetValue


TlsGetValue

This function retrieves the value in the calling thread’s thread local storage (TLS) slot for a specified TLS index. Each thread of a process has its own slot for each TLS index.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPVOID TlsGetValue( DWORD dwTlsIndex );

Parameters

dwTlsIndex
[in] Specifies a TLS index that was allocated by the TlsAlloc function.

Return Values

The value stored in the calling thread’s TLS slot associated with the specified index indicates success. Zero indicates failure. To get extended error information, call GetLastError.

The data stored in a TLS slot can have a value of zero. In this case, the return value is zero and GetLastError returns NO_ERROR.

Remarks

TLS indexes are typically allocated by the TlsAlloc function during process or DLL initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot for that index. The storage slot for each thread is initialized to NULL. A thread specifies a TLS index in a call to TlsSetValue, to store a value in its slot. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

TlsSetValue and TlsGetValue were implemented with speed as the primary goal. These functions perform minimal parameter validation and error checking. In particular, this function succeeds if dwTlsIndex is in the range 0 through (TLS_MINIMUM_AVAILABLE – 1). It is up to the programmer to ensure that the index is valid.

Win32 functions that return indications of failure call SetLastError when they fail. They generally do not call SetLastError when they succeed. The TlsGetValue function is an exception to this general rule. The TlsGetValue function calls SetLastError to clear a thread’s last error when it succeeds. That allows checking for the error-free retrieval of NULL values.

See Also

GetLastError, SetLastError, TlsAlloc, TlsFree, TlsSetValue


TlsSetValue

This function stores a value in the calling thread's thread local storage (TLS) slot for a specified TLS index. Each thread of a process has its own slot for each TLS index.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TlsSetValue( DWORD dwTlsIndex, LPVOID lpTlsValue );

Parameters

dwTlsIndex
[in] Specifies a TLS index that was allocated by the TlsAlloc function.
lpTlsValue
[in] Pointer to the value to be stored in the calling thread’s TLS slot specified by dwTlsIndex.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

TLS indexes are typically allocated by the TlsAlloc function during process or DLL initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot for that index. The storage slot for each thread is initialized to NULL. A thread specifies a TLS index in a call to TlsSetValue to store a value in its slot. The thread specifies the same index in a subsequent call to TlsGetValue to retrieve the stored value.

TlsSetValue and TlsGetValue were implemented with speed as the primary goal. These functions perform minimal parameter validation and error checking. In particular, this function succeeds if dwTlsIndex is in the range 0 through (TLS_MINIMUM_AVAILABLE – 1). It is up to the programmer to ensure that the index is valid.

See Also

TlsAlloc, TlsFree, TlsGetValue


Toolhelp32ReadProcessMemory

This function copies memory allocated to another process into an application-supplied buffer.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WINAPI Toolhelp32ReadProcessMemory( DWORD th32ProcessID, LPCVOID lpBaseAddress, LPVOID lpBuffer, DWORD cbRead,
LPDWORD lpNumberOfBytesRead);

Parameters

th32ProcessID
Identifier of the process whose memory is being copied. This parameter can be zero to copy the memory of the current process.
lpBaseAddress
Base address in the specified process to read. Before transferring any data, the system verifies that all data in the base address and memory of the specified size is accessible for read access. If this is the case, the function proceeds. Otherwise, the function fails.
lpBuffer
Pointer to a buffer that receives the contents of the address space of the specified process.
cbRead
Number of bytes to read from the specified process.
lpNumberOfBytesRead
Pointer to the number of bytes copied to the specified buffer. If this parameter is NULL, it is ignored.

Return Value

TRUE indicates success. FALSE indicates failure.


TransportConnect

This function connects to a service for transmission or reception.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportConnect(HANDLE hService, DWORD dwFlags, HWND hNotify, (BOOL) (*CallBack)(int iStatus, BOOL bUnknownmax));

Parameters

hService
[in] Handle to a SERVICE structure.
dwFlags
[in] Specifies a bitmask of transmit and receive flags. It is one of the following values:
Value
Description
TRANSPORT_SEND | Indicates a request to start the transmit functionality of the service.
TRANSPORT_RECV | Indicates a request to start the receive functionality of the service.

hNotify
[in] Handle to the window that receives any notification messages that may be sent from a transport service routine. The SAMPLE service can call the SendMessage function to send the following notification messages to hNotify.
Value
Description
TRANSPORT_CONN_LOST (WM_USER + 1) | Sent to hNotify to inform Inbox that the connection has closed in the background. For example, this could be sent if a remote modem connection was lost. The SendMessage parameters wparam and lparam are ignored. SendMessage always returns zero.
TRANSPORT_REFRESH (WM_USER + 2) | Sent to hNotify to request Inbox to refresh its connection to the service. For example, this could be used if Inbox has an open connection to the service and the service determines that a new message has arrived. The SendMessage parameters wparam and lparam are ignored. SendMessage always returns zero.

CallBack
[in] If this CallBack routine is not NULL, it can be called from a Transport* function, for example. The CallBack routine displays a status window, indicating the progress toward completion.

The CallBack routine is passed an integer value between 0 and 99 (iStatus), indicating the progress toward completion. In this case, bUnknownmax must be set to FALSE.

If the maximum value of iStatus might be greater than 99 (that is, the maximum is unknown), then bUnknownmax must be set to TRUE.

Return Values

TRUE indicates success. FALSE indicates failure, or that hService is invalid.

Remarks

The transport service provider must implement the TransportConnect function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

The dwFlags parameter should be checked to determine whether this is a call to connect the transmit service or the receive service. The CallBack routine can be saved in the hService SERVICE structure, so that it can be called from other transport service routines.

The CallBack parameter implemented in the Inbox client application always returns TRUE.

See Also

TransportDisconnect


TransportCount

This function determines the number of pending messages in the mailbox and returns this count in the lpNumMsgs parameter.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportCount(HANDLE hService, LPWORD lpNumMsgs);

Parameters

hService
[in] Handle to a SERVICE structure.
lpNumMsgs
[in] Long pointer that receives the number of messages found in the mailbox.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement the TransportCount function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

For the sample transport service, TransportCount searches the mail directory specified in the szMailDir member of the designated SERVICE structure and determines the number of message files present. It sets the values of the wNumMsgs and wHighNum members of the specified SERVICE structure accordingly. If lpNumMsgs is a valid pointer, it is set to the number of messages found. This value is also saved in the wNumMsgs member of the SERVICE structure.


TransportDel

This function deletes a specific message located on the mail server.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportDelete(HANDLE hService, MailMsg *MsgPtr);

Parameters

hService
[in] Handle to a SERVICE structure.
MsgPtr
[in] Pointer to the MailMsg structure. The szSvcID member of the MailMsg structure specifies the service identifier of the message to be deleted.

This member is compared with the message identifiers stored in the Uids member of the specified SERVICE structure. The information maintained in hService is then used in support of deleting the message.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call TransportError or TransportErrorMsg. For example, if the message identifier cannot be found, the iErr member of the specified MailMsg structure is set to TRANS_ERR_INV_MSG_ID.

Remarks

The transport service provider must implement the TransportDel function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

For the sample service, TransportDel removes the file specified in the MsgPtr structure.


TransportDisconnect

This function disconnects the current transmit and/or receive service.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportConnect(HANDLE hService);

Parameters

hService
[in] Handle to a SERVICE structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement the TransportDisconnect function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportConnect, TransportRelease


TransportError

This function returns a transport defined error code for the last mail error that occurred.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

int TransportError(HANDLE hService);

Parameters

hService
[in] Handle to a SERVICE structure.

Return Values

The sample TransportError routine returns an integer error number for the last error that occurred. If no error has occurred, TransportError must return TRANS_ERR_NONE (with associated error string “No error,” returned by TransportErrorMsg). Note that this is required for every transport service’s implementation of TransportError.

Other custom error values can be defined by the transport service. For example, the sample transport service defines the following values:

TRANS_ERR_NO_SVC_DIR
Service directory unavailable.
TRANS_ERR_HANDLE_NOT_ALLOC
Could not allocate memory for service handle.
TRANS_ERR_CANT_OPEN
Could not create message file.
TRANS_ERR_CANT_SEND
Could not open mail message.
TRANS_ERR_INV_MSG_ID
Invalid message identifier specified.
TRANS_ERR_NO_MSG_BUF
Could not allocate message buffer.
TRANS_ERR_READ
There was an error reading the message.

Remarks

The transport service provider must implement the TransportError function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportErrorMsg


TransportErrorMsg

This function returns a string associated with an integer error number, for the last error that occurred.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

int TransportErrorMsg(HANDLE hService, LPWSTR szBuf, int iBufLen,
int *piSrcLine,);

Parameters

hService
[in] Handle to a SERVICE structure.
szBuf
[out] Buffer to hold the error string.
iBufLen
[in] Length of szBuff, in wide characters—that is, Unicode characters; not bytes.
piSrcLine
[out] Pointer to the line where the error occurred—retrieved from the iErrLine member of the SERVICE structure.

Return Values

A string describing the nature of the error is placed in szBuf, and the line number at which the error occurred is placed in piSrcLine.

Remarks

In Windows CE version 2.0, the piSrcLine parameter can be set to –1 to inform the client that the user is aware of the problem and that it needs not to display any more messages.

In general the transport should not display error dialogs. But if the transport uses a communication service which has set up error dialogs, the transport might have to assume the responsibility to display the error information.

The transport service provider must implement the TransportErrorMsg function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

For example, the sample transport service returns one of the following error strings in szBuf.

Error String
String Resource Error Code
"No error" | TRANS_ERR_NONE
"Service directory unavailable." | TRANS_ERR_NO_SVC_DIR
"Could not allocate memory for service handle." | TRANS_ERR_HANDLE_NOT_ALLOC
"Could not create message file." | TRANS_ERR_CANT_OPEN
"Could not open mail message." | TRANS_ERR_CANT_SEND
"Invalid message identifier specified." | TRANS_ERR_INV_MSG_ID
"Could not allocate message buffer." | TRANS_ERR_NO_MSG_BUF
"There was an error reading the message." | TRANS_ERR_READ
"Unknown Error" | (String table that contains error messages failed to load properly.)

See Also

TransportError


TransportFreeMsg

This function destroys the MailMsg heap allocated by TransportRecv and resets the heap, header, and message body pointers to NULL.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportFreeMessage(MailMsg * MsgPtr);

Parameters

hService
[in] Handle to a SERVICE structure.

Return Values

TRUE indicates success. FALSE indicates that MsgPtr is invalid or that the hHeap member of the specified MailMsg structure does not exist.

Remarks

The transport service provider must implement the TransportFreeMsg function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportRecv


TransportInit

This function takes a pointer to a service handle and initializes internal data for the service.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportInit (HANDLE *NewService, LPWSTR szCommonKey, LPWSTR szTransportKey,);

Parameters

NewService
[in] Service handle that is returned by TransportInit.
szCommonKey
[in] Null-terminates string that contains the top-level registry key—for example, HKEY_LOCAL_MACHINE\PMail.
szTransportKey
[in] Null-terminated string that contains the registry key for this transport—for example, HKEY_LOCAL_MACHINE\PMail\ServiceInfo\SAMPLE.

Return Values

TRUE indicates success. FALSE indicates failure; for example, NewService was not a valid pointer, or the heap allocation of the SERVICE structure failed.

Remarks

The transport service provider must implement the TransportInit function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

TransportInit allocates a local heap for a SERVICE structure and initializes several fields. TransportInit can perform initializations using values from the registry. This is the first function called after the service DLL is loaded.

To load and initialize an IMAP4 transport server without connecting, call TransportInit with the connectoid to “(none).” This technique does not work with a POP3 transport.

See Also

TransportRelease


TransportNonIpm

This function serves to set non-Interpersonal Message (non-IPM) properties to a message.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 2.0 and later

Syntax

BOOL TransportNonIpm (MailMsg * pmm);

Parameters

pmm
[in] Pointer to the mail message to which the non-IPM properties may be written.

Return Values

TRUE indicates success. FALSE indicates an error.

Remarks

A non-IPM is any message that is processed by an application, rather than read directly by the user. For example, Schedule+ messages are non-IPM messages. An application must interpret the data before the user can read and use them.

Transport DLLs can, but are not required to, expose the TransportNonIpm function. A mail client calls the function to set non-IPM properties for the message which has been downloaded to the message store and whose headers include a “Type” field. To set the non-IPM properties, the transport DLL makes use of the oid member of the MailMsg structure. To save space and overhead, IPM messages should not have a “Type” field set.


TransportProps

This function is used to add or modify information for the user’s mail service properties. TransportProps is not required to be implemented and can simply return TRUE. Note that a user interface is required to display the information.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportProps(HWND hwndParent, LPWSTR szCommonKey, LPWSTR szTransportKey,);

Parameters

hwndParent
[in] Handle to the parent window.
szCommonKey
[in] Null-terminated string that contains the top-level registry key. For Inbox, this is the HKEY_LOCAL_MACHINE\PMail\ServiceInfo key.
szTransportKey
[in] Null-terminated string that contains the transport registry key. This is the key that is associated with the user’s unique mail service.

For the sample transport service, this is the HkEY_LOCAL_MACHINE\PMail\ServiceInfo\MyMail key.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The transport service provider must implement the TransportProps function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

For example, under the ServiceInfo key (that is the key defined identified by the parameter szCommonKey), a key named SAMPLE could exist. This registry key contains values that represent information such as the user’s settings and preferences. As part of this routine, such preferences as saving the user’s password can be set in the registry.


TransportRecv

This function gets a specific message from the mail server. The number of MailMsg messages that can be retrieved is between 1 and the number returned by TransportCount.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportRecv(HANDLE hService, WORD wMessageId,
short sNumLines, MailMsg *MsgPtr, lpMailAttArray *lplpMaa);

Parameters

hService
[in] Handle to a SERVICE structure.
wMessageId
[in] Identifier of the message for this session. If this value is zero, the unique message identifier stored in the szSvcId member of the MailMsg structure is used.
sNumLines
[in] Number of lines to receive. For the sample service, sNumLines is assigned value indicating the number of lines to be read.

If only message information is to be returned, sNumLines is set to one of the following flags:
Value
Description
TRANSPORT_MSG_EXIST | Used to check for the existence of a message, without allocating any memory. Neither the message header nor the message body is read.
TRANSPORT_ALL_LINES | Returns the unique identifier stored in the szSvcId member of the MailMsg structure as determined from wSessionId.
TRANSPORT_HEADERS | Parses the message header and places the information in MsgPtr, also without allocating any memory. The message body is not read.

MsgPtr
[in] Pointer to MailMsg structure that receives the message information.
lplpMaa
[in] For Windows CE versions 1.0 and 1.01, this parameter is reserved; set to NULL. For versions 2.0 and later, it is a long pointer to lpMailAttArray, which is itself a long pointer to a MailAttArray structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement the TransportRecv function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

For the sample transport service, TransportRecv receives a message by means of hService and copies the message (or message information) into the MsgPtr structure. If the calling application wishes only to check for the existence of the message, or just obtain header information, the calling application sets sNumLines to TRANSPORT_MSG_EXIST.

A typical TransportRecv routine opens the file that contains the message (specified in hService), allocates heap space, parses the header, and fills the various MsgPtr fields with the appropriate information. After assigning pointers to the heap, header, and body fields of MsgPtr, the sample TransportRecv frees the memory allocated to MsgPtr, but leaves the heap it created intact. The heap must be destroyed by using TransportFreeMsg.

If the lplpMaa parameter returns a valid pointer and the transport determines that attachments are to be added to the message, then a MailAttArray structure should be allocated from the message heap and initialized with appropriate attachment information.

See Also

TransportFreeMsg


TransportRelease

This function frees the memory heap and all resources allocated for this transport service by TransportInit.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportRelease(HANDLE hService);

Parameters

hService
[in] Handle to a SERVICE structure.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The transport service provider must implement the TransportRelease function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

TransportRelease is called before the service DLL is unloaded. For the sample transport service, TransportRelease frees the heap allocated by TransportInit and also calls TransportDisconnect.

See Also

TransportInit, TransportDisconnect


TransportSend

This function sends a message—in the form of a MailMsg structure—using the transmit server.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportSend(HANDLE hService, MailMsg *MsgPtr);

Parameters

hService
[in] Handle to a SERVICE structure.
MsgPtr
[in] Pointer to a MailMsg structure that contains the message to be sent.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement the TransportSend function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

Because the sample transport service interfaces with the file system, the sample TransportSend involves creating and writing to a file (using CreateFile and WriteFile) that is located in the inbox. The MsgPtr structure contains the message header, body, and information that may be written to the file. In the sample SERVICE structure, the directory path serving as the inbox location is defined in the szMailDir member.

In order to display the progress status of the message transfer, the sample TransportSend routine also utilizes the CallBack routine that was passed to the TransportConnect function.

The sample service writes to the file system. If, for example, the service was for electronic mail, this routine would transfer the message using the transmit server for this service.

See Also

TransportRecv


TransportSetPassword

This function serves to change a user’s service password.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 2.0 and later

Syntax

BOOL TransportSetPassword(HANDLE * InPtr, LPWSTR pszPassword, BOOL fRemember);

Parameters

InPtr
[in] Handle to the SERVICE structure.
lszPassword
[in] Null-terminated string to hold the user’s password. Transport should make a copy of it.
fRemember
Boolean that is set to TRUE to save the new password for use in the future. Otherwise, it is only to be used for the current session.

Return Values

TRUE indicates that the password is saved, depending on the value of fRemember, in memory for the current session or in the registry for future sessions. FALSE indicates failure.

Remarks

Transport DLLs can expose this function. This practice is encouraged, but not required. A mail client, such as Inbox, calls the function when the user changes her service password through the client.

In Windows CE version 2.0, the POP3 transport encrypts the user’s password before saving it in the registry. Inbox is refrained from touching the transport’s registry entries. Before connecting the transport, the client application calls the TransportSetPassword function whenever the user supplies a password. This makes the transport the sole partner responsible for password encryption. The client application does not need to have any knowledge of the encryption.

The transports in Windows CE version 1.01 do not expose this function. The Inbox application updates the transport section of the registry with the unencrypted password as entered by the user in the Password dialog.

When transport DLLs in Windows CE version 2.0 do not expose the TransportSetPassword function, they can prompt for and save the password themselves as they would in Windows CE version 1.01.


TransportView

This function processes and displays encoded data following the mail header information (that is, the message body) contained in the MsgPtr structure.

At a Glance

Header file: | Smtp.h
Windows CE versions: | 1.0 and later

Syntax

BOOL TransportView(HWND hwndParent, MailMsg *MsgPtr);

Parameters

hService
[in] Handle to a SERVICE structure.
MsgPtr
[in] Pointer to a MailMsg structure that contains pointers to the message content along with other information about the message.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The transport service provider must implement the TransportView function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

TransportView is called by the service application if the “Type:” field and value are present in the mail header. If the “Type:” field exists (see the pwcHeaders member of the MailMsg structure), then the value must specify a registry name that identifies the DLL that is to be loaded and used to process the encoded message data. For example, an application such as Inbox searches the registry key HKEY_LOCAL_MACHINE\PMail\MessageTypes. The value name under this key (that is, the value name for the “Type:” field in the message header) identifies the DLL that Inbox will dynamically load. Inbox loads the specified DLL and calls the TransportView function. After this function performs the desired processing on the body of the mail message and returns, Inbox frees the DLL.

If a service is added from Inbox, the DLL name must be registered under the above referenced registry key, and the DLL must contain the TransportView function. However, note that for a custom-written application, the registry path and viewer DLL can be defined as desired.

Example

The following registry entry would register a DLL named Myviewer. So, when a mail message is opened by the user which contains a “Type: MyViewer” header, the transport loads MyViewer.dll and Inbox calls TransportView with the referenced mail message.

'HKEY_LOCAL_MACHINE'
  [PMail]
    [MessageTypes]
      SZ: MyViewerName = MyViewer.dll

See Also

MailMsg, MailGetField


Uninstall_Exit

This function prototype is called after the uninstallation completes. This function can be used for custom operations such as saving database data into a file and deleting the database, informing the user on where the user data files are stored, or informing the user on how to reinstall the application.

Syntax

codeUNINSTALL_EXIT Uninstall_Exit(HWND hwndParent);

Parameters

hwndParent
Handle to the parent window.

Return Values

codeUNINSTALL_EXIT_DONE
Successful uninstallation.

Remarks

The Uninstall_Exit function prototype is part of Setup.dll, an ISV-created file for custom operations dealing with installation and uninstallation of applications.


Uninstall_Init

This function prototype is called before the uninstallation begins. This function can be used for custom operations such as closing the application if it is running.

Syntax

codeUNINSTALL_INIT Uninstall_Init(HWND hwndParent, LPCTSTR pszInstallDir);

Parameters

hwndParent
Handle to the parent window.
pszInstallDir
Null-terminated string that contains the name of the install directory of the application.

Return Values

codeUNINSTALL_INIT_CONTINUE
Continue with uninstallation.
codeUNINSTALL_INIT_CANCEL
Cancel uninstallation.

Remarks

The Uninstall_Init function prototype is part of Setup.dll, an ISV-created file for custom operations dealing with installation and uninstallation of applications.


UnionRect

This function creates the union of two rectangles. The union is the smallest rectangle that contains both source rectangles.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

BOOL UnionRect(LPRECT lprcDst, const RECT *lprcSrc1,
const RECT *lprcSrc2);

Parameters

lprcDst
Long pointer to the RECT structure that will receive a rectangle containing the rectangles pointed to by the lprcSrc1 and lprcSrc2 parameters.
lprcSrc1
Long pointer to the RECT structure that contains the first source rectangle.
lprcSrc2
Long pointer to the RECT structure that contains the second source rectangle.

Return Values

Nonzero indicates that the specified structure contains a nonempty rectangle. Zero indicates that the specified structure does not contain a nonempty rectangle.

To get extended error information, call GetLastError.

Remarks

The system ignores the dimensions of an empty rectangle—that is, a rectangle in which all coordinates are set to zero, so that it has no height or no width.

See Also

InflateRect, IntersectRect, OffsetRect, RECT


UnmapViewOfFile

This function unmaps a mapped view of a file from the calling process’s address space.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

BOOL UnmapViewOfFile( LPCVOID lpBaseAddress);

Parameters

lpBaseAddress
Pointer to the base address of the mapped view of a file that is to be unmapped. This value must be identical to the value returned by a previous call to the MapViewOfFile function.

Return Values

Nonzero indicates success. All dirty pages within the specified range are written “lazily” to disk. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Although an application may close the file handle used to create a file mapping object, the system holds the corresponding file open until the last view of the file is unmapped.

See Also

MapViewOfFile


VarBoolFromCy

This function converts variant data types to BOOL from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromStr([in] CURRENCY cyIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromDate

This function converts variant data types to BOOL from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromDate([in] DATE dateIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromDec

This function converts variant data types to BOOL from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromDec([in] DECIMAL * pdecIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromDisp

This function converts variant data types to BOOL from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromDisp([in] IDispatch * pdispIn, [in] LCID lcid, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromI1

This function converts variant data types to BOOL from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromI1([in] char cIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromI2

This function converts variant data types to BOOL from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromI2([in] short sIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromI4

This function converts variant data types to BOOL from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromI4([in] long lIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromR4

This function converts variant data types to BOOL from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromR4([in] float fltIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromR8

This function converts variant data types to BOOL from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromR8([in] double dblIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromStr

This function converts variant data types to BOOL from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromUI1

This function converts variant data types to BOOL from unsigned char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromUI1([in] BYTE bIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromUI2

This function converts variant data types to BOOL from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromUI2([in] USHORT uiIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBoolFromUI4

This function converts variant data types to BOOL from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBoolFromUI4([in] ULONG ulIn, [out] BOOL * pboolOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromBool

This function converts variant data types to BSTR from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromBool([in] BOOL boolIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromCy

This function converts variant data types to BSTR from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromCy([in] CURRENCY cyIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromDate

This function converts variant data types to BSTR from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromDate([in] DATE dateIn, [in] LCID lcid, in] ULONG dwFlags, out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromDec

This function converts variant data types to BSTR from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromDec([in] DECIMAL * pdecIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromDisp

This function converts variant data types to BSTR from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromDisp([in] IDispatch FAR * sIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromI1

This function converts variant data types to BSTR from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromI1([in] char cIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromI2

This function converts variant data types to BSTR from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromI2([in] short sIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromI4

This function converts variant data types to BSTR from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromI4([in] long lIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromR4

This function converts variant data types to BSTR from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromR4([in] float fttIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromR8

This function converts variant data types to BSTR from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromR8([in] double dblIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromUI1

This function converts variant data types to BSTR from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromUI1([in] BYTE bIn, [in] LCID lcid, [in] ULONG dwFlags, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromUI2

This function converts variant data types to BSTR from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromUI2([in] USHORT uiIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pbstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarBstrFromUI4

This function converts variant data types to BSTR from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarBstrFromUI4([in] ULONG ulIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BSTR pstrOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromBool

This function converts variant data types to CURRENCY from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromBool([in] BOOL boolIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromDate

This function converts variant data types to CURRENCY from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromDate([in] DATE dateIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromDec

This function converts variant data types to CURRENCY from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromDec([in] DECIMAL * pdecIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromDisp

This function converts variant data types to CURRENCY from IDispatch .

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromDisp([in] IDispatch FAR * pdispIn, [in] LCID lcid, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromI1

This function converts variant data types to CURRENCY from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromI1([in] char cbIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromI2

This function converts variant data types to CURRENCY from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromI2([in] short sIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromI4

This function converts variant data types to CURRENCY from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromI4([in] long lIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromR4

This function converts variant data types to CURRENCY from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Remarks

Syntax

WINOLEAUTAPI VarCyFromR4([in] float fltIn, [out] CURRENCY * pcyOut);

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromR8

This function converts variant data types to CURRENCY from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromR8([in] double dblIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromStr

This function converts variant data types to CURRENCY from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromUI1

This function converts variant data types to CURRENCY from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromUI1([in] BYTE bIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromUI2

This function converts variant data types to CURRENCY from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromUI2([in] USHORT uiIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarCyFromUI4

This function converts variant data types to CURRENCY from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarCyFromUI4([in] ULONG ulIn, [out] CURRENCY * pcyOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromBool

This function converts variant data types to DATE from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromBool([in] BOOL boolIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromCy

This function converts variant data types to DATE from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromCy([in] CURRENCY cyIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromDec

This function converts variant data types to DATE from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromDec([in] DECIMAL * pdecIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromDisp

This function converts variant data types to DATE from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromDisp([in] IDispatch FAR * pdispIn, [in] LCID lcid, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromI1

This function converts variant data types to DATE from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromI1([in] char cIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromI2

This function converts variant data types to DATE from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromI2([in] short sIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromI4

This function converts variant data types to DATE from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromI4([in] long lIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromR4

This function converts variant data types to DATE from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromR4([in] float fltIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromR8

This function converts variant data types to DATE from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromR8([in] double dblIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromStr

This function converts variant data types to DATE from OLECHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromStr([in] OLECHAR * strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromUdate

This function packs a date.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VarDateFromUdate( [in] UDATE * pudateIn, [in] unsigned long * dwFlags, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromUI1

This function converts variant data types to DATE from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromUI1([in] unsigned char bIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromUI2

This function converts variant data types to DATE from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromUI2([in] unsigned short uiIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDateFromUI4

This function converts variant data types to DATE from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDateFromUI4([in] unsigned long ulIn, [out] DATE * pdateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromBool

This function converts variant data types to DECIMAL from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromBool([in] BOOL boolIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromCy

This function converts variant data types to DECIMAL from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromCy([in] CURRENCY cIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromDate

This function converts variant data types to DECIMAL from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromDate([in] DATE dateIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromDisp

This function converts variant data types to DECIMAL from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromDisp([in] IDispatch * pdispIn, [in] LCID lcid, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromI1

This function converts variant data types to DECIMAL from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromI1([in] char cIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromI2

This function converts variant data types to DECIMAL from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromI2([in] short sIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromI4

This function converts variant data types to DECIMAL from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromI4([in] long lIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromR4

This function converts variant data types to DECIMAL from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromR4([in] float fltIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromR8

This function converts variant data types to DECIMAL from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromR8([in] double dblIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromStr

This function converts variant data types to DECIMAL from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromUI1

This function converts variant data types to DECIMAL from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromUI1([in] BYTE bIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromUI2

This function converts variant data types to DECIMAL from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromUI2([in] USHORT uiIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarDecFromUI4

This function converts variant data types to DECIMAL from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarDecFromUI1([in] ULONG ulIn, [out] DECIMAL * pdecOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromBool

This function converts variant data types to char from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromBool([in] BOOL boolIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromCy

This function converts variant data types to char from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromCy([in] CURRENCY cyIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromDate

This function converts variant data types to char from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromDate([in] DATE dateIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromDec

This function converts variant data types to char from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromDec([in] DECIMAL * pdecIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromDisp

This function converts variant data types to char from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromDisp([in] IDispatch * pdispIn, [in] LCID lcid, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromI2

This function converts variant data types to char from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromI2([in] short sIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromI4

This function converts variant data types to char from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromI4([in] long lIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromR4

This function converts variant data types to char from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromR4([in] float fltIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromR8

This function converts variant data types to char from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromR8([in] double dblIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromStr

This function converts variant data types to char from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromUI1

This function converts variant data types to char from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromUI1([in] BYTE bIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromUI2

This function converts variant data types to char from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromUI2([in] USHORT uiIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI1FromUI4

This function converts variant data types to char from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI1FromUI4([in] ULONG ulIn, [out] char * pcOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromBool

This function converts variant data types to short from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromBool([in] BOOL boolIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromCy

This function converts variant data types to short from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromCy([in] CURRENCY cybIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromDate

This function converts variant data types to short from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromDate([in] DATE dateIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromDec

This function converts variant data types to Short from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromDec([in] DECIMAL * pdecIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromDisp

This function converts variant data types to short from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromDisp([in] IDispatch FAR * pdispIn, [in] LCID lcid, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromI1

This function converts variant data types to short from CHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromI1([in] CHAR cIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromI4

This function converts variant data types to short from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromI4([in] LONG lIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromR4

This function converts variant data types to short from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromR4([in] float fltIn, out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromR8

This function converts variant data types to short from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromR8([in] double dblIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromStr

This function converts variant data types to short from OLECHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromStr([in] OLECHAR FAR* strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromUI1

This function converts variant data types to short from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromUI1([in] BYTE bIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromUI2

This function converts variant data types to short from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromUI2([in] USHORT uiIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI2FromUI4

This function converts variant data types to short from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI2FromUI4([in] ULONG ulIn, [out] short * psOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromBool

This function converts variant data types to long from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromBool([in] BOOL boolIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromCy

This function converts variant data types to long from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromCy([in] CURRENTY cyIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromDate

This function converts variant data types to long from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromUI1([in] DATE dateIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromDec

This function converts variant data types to long from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromDec([in] DECIMAL * pdecIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromDisp

This function converts variant data types to long from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromDisp([in] IDispatch FAR * pdispIn, [in] LCID lcid, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromI1

This function converts variant data types to long from CHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromI1([in] CHAR cIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromI2

This function converts variant data types to long from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromUI1([in] short sIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromR4

This function converts variant data types to long from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromR4([in] float fltIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromR8

This function converts variant data types to long from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromR8([in] double dblIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromStr

This function converts variant data types to long from OLECHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromStr([in] OLECHAR * strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromUI1

This function converts variant data types to long from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromUI1([in] BYTE bIn, out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromUI2

This function converts variant data types to long from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromUI2([in] USHORT uiIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarI4FromUI4

This function converts variant data types to long from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarI4FromUI4([in] ULONG ulIn, [out] long * plOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VariantChangeType

This function converts a variant from one type to another.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantChangeType( VARIANTARG FAR * pvargDest, VARIANTARG FAR * pvarSrc, unsigned short wFlags, VARTYPE vt);

Parameters

pvargDest
Pointer to the VarBoolFromDispto receive the coerced type. If this is the same as pvarSrc, the variant is converted in place.
pvarSrc
Pointer to the source VARIANTARG to be coerced.
wFlags
Flags that control the coercion. The only defined flag is VARIANT_NOVALUEPROP, which prevents the function from attempting to coerce an object to a fundamental type by getting the Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications.
vt
Specifies the type to coerce to. If the return code is S_OK, the vt member of the VARIANTARG specified by *pvargDest is always the same as this value.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADVARTYPE | The variant type vt is not a valid type of variant.
DISP_E_OVERFLOW | The data pointed to by pvarSrc does not fit in the destination type.
DISP_E_TYPEMISMATCH | The argument could not be coerced to the specified type.
E_INVALIDARG | One of the arguments is invalid.
E_OUTOFMEMORY | Memory could not be allocated for the conversion.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

The VariantChangeType function handles coercions between the fundamental types (including numeric-to-string and string-to-numeric coercions). A variant that has VT_BYREF set is coerced to a value by obtaining the referenced value. An object is coerced to a value by invoking the object's Value property (DISPID_VALUE).

Typically, the implementor of IDispatch::Invoke determines which member is being accessed, and then calls VariantChangeType to get the value of one or more arguments. For example, if the IDispatch call specifies a SetTitle member that takes one string argument, the implementor would call VariantChangeType to attempt to coerce the argument to VT_BSTR. If VariantChangeType does not return an error, the argument could then be obtained directly from the bstrVal member of the VARIANTARG. If VariantChangeType returns DISP_E_TYPEMISMATCH, the implementor would set *puArgErr to 0 (indicating the argument in error) and return DISP_E_TYPEMISMATCH from IDispatch::Invoke.

Arrays of one type cannot be converted to arrays of another type with this function.

Note The type of a VARIANTARG should not be changed in the rgvarg array in place.


VariantChangeTypeEx

This function converts a variant from one type to another, using a LCID.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantChangeTypeEx( VARIANTARG FAR * pvargDest, VARIANTARG FAR * pvarSrc, LCID lcid, unsigned short wFlags, VARTYPE vt);

Parameters

pvargDest
Pointer to the VARIANTARG to receive the coerced type. If this is the same as pvarSrc, the variant is converted in place.
pvarSrc
Pointer to the source VARIANTARG to be coerced.
lcid
LCID for the variant to coerce. The LCID is useful when the type of the source or destination VARIANTARG is VT_BSTR, VT_DISPATCH, or VT_DATE.
wFlags
Flags that control the coercion. The only defined flag is VARIANT_NOVALUEPROP, which prevents the function from attempting to coerce an object to a fundamental type by getting its Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications.
vt
Specifies the type to coerce to. If the return code is S_OK, the vt member of the VARIANTARG specified by *pvargDest is guaranteed to be equal to this value.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_BADVARTYPE | The variant type vt is not a valid type of variant.
DISP_E_OVERFLOW | The data pointed to by pvarSrc does not fit in the destination type.
DISP_E_TYPEMISMATCH | The argument could not be coerced to the specified type.
E_INVALIDARG | One of the arguments is invalid.
E_OUTOFMEMORY | Memory could not be allocated for the conversion.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

The VariantChangeTypeEx function handles coercions between the fundamental types (including numeric-to-string and string-to-numeric coercions). To change a type with the VT_BYREF flag set to one without VT_BYREF, change the referenced value to VariantChangeTypeEx. To coerce objects to fundamental types, obtain the value of the Value property.

Typically, the implementor of IDispatch::Invoke determines which member is being accessed, and then calls VariantChangeType to get the value of one or more arguments. For example, if the IDispatch call specifies a SetTitle member that takes one string argument, the implementor would call VariantChangeTypeEx to attempt to coerce the argument to VT_BSTR.

If VariantChangeTypeEx does not return an error, the argument could then be obtained directly from the bstrVal member of the VARIANTARG. If VariantChangeTypeEx returns DISP_E_TYPEMISMATCH, the implementor would set *puArgErr to 0 (indicating the argument in error) and return DISP_E_TYPEMISMATCH from IDispatch::Invoke.

Arrays of one type cannot be converted to arrays of another type with this function.

Note The type of a VARIANTARG should not be changed in the rgvarg array in place.


VariantClear

This function clears a variant.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantClear(VARIANTARG FAR * pvarg);

Parameters

pvarg
Pointer to the VARIANTARG to clear.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The variant contains an array that is locked.
DISP_E_BADVARTYPE | The variant type pvarg is not a valid type of variant.
E_INVALIDARG | One of the arguments is invalid.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Use this function to clear variables of type VARIANTARG (or VARIANT) before the memory that contains the VARIANTARG is freed (as when a local variable goes out of scope).

The function clears a VARIANTARG by setting the vt member to VT_EMPTY and the wReserved member to 0. The current contents of the VARIANTARG are released first. If the vt member is VT_BSTR, the string is freed. If the vt member is VT_DISPATCH, the object is released. If the vt member has the VT_ARRAY bit set, the array is freed.

In certain cases, it may be preferable to clear a variant in code without calling VariantClear. For example, you can change the type of a VT_I4 variant to another type without calling this function. However, you must call VariantClear if a VT_* type is received but cannot be handled. Using VariantClear in these cases ensures that code will continue to work if Automation adds new variant types in the future.

Example

for(i = 0; i < celt; ++i)
    VariantClear(&rgvar[i]);


VariantCopy

This function frees the destination variant and makes a copy of the source variant.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantCopy( VARIANTARG FAR * pvargDest, VARIANTARG FAR * pvargSrc);

Parameters

pvargDest
Pointer to the VARIANTARG to receive the copy.
pvargSrc
Pointer to the VARIANTARG to be copied.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The variant contains an array that is locked.
DISP_E_BADVARTYPE | The source and destination have an invalid variant type (usually uninitialized).
E_OUTOFMEMORY | Memory could not be allocated for the copy.
E_INVALIDARG | One of the arguments is invalid.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

First, free any memory that is owned by pvargDest, such as VariantClear (pvargDest must point to a valid initialized variant, and not simply to an uninitialized memory location). Then pvargDest receives an exact copy of the contents of pvargSrc.

If pvargSrc is a VT_BSTR, a copy of the string is made. If pvargSrc is a VT_ARRAY, the entire array is copied. If pvargSrc is a VT_DISPATCH or VT_UNKNOWN, AddRef is called to increment the object’s reference count.


VariantCopyInd

This function frees any existing content of the destination variant and makes a copy of the source VARIANTARG, performing the necessary indirection if the source is specified to be VT_BYREF.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantCopyInd( VARIANT FAR * pvarDest, VARIANTARG FAR * pvargSrc);

Parameters

pvarDest
Pointer to the VARIANTARG that receives the copy.
pvargSrc
Pointer to the VARIANTARG that is copied.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
DISP_E_ARRAYISLOCKED | The variant contains an array that is locked.
DISP_E_BADVARTYPE | The source and destination have an invalid variant type (usually uninitialized).
E_OUTOFMEMORY | Memory could not be allocated for the copy.
E_INVALIDARG | The argument pvargSrc was VT_ARRAY.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

This function is useful when a copy of a variant is needed, and to guarantee that it is not VT_BYREF, such as when handling arguments in an implementation of IDispatch::Invoke.

For example, if the source is a (VT_BYREF | VT_I2), the destination will be a BYVAL | VT_I2. The same is true for all legal VT_BYREF combinations, including VT_VARIANT.

If pvargSrc is (VT_BYREF | VT_VARIANT), and the contained variant is VT_BYREF, the contained variant is also dereferenced.

This function frees any existing contents of pvarDest.


VariantInit

This function initializes a variant.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantInit( VARIANTARG FAR * pvarg);

Parameters

pvarg
Pointer to the VARIANTARG that will be initialized.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

The VariantInit function initializes the VARIANTARG by setting the vt member to VT_EMPTY. Unlike VariantClear, this function does not interpret the current contents of the VARIANTARG. Use VariantInit to initialize new local variables of type VARIANTARG (or VARIANT).

Example

for(i = 0; i < celt; ++i)
    VariantInit(&rgvar[i]);


VariantTimeToSystemTime

This function converts the variant representation of time to system time values.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VariantTimeToSystemTime(double vtime, LPSYSTEMTIME lpSystemTime);

Parameters

vtime
Specifies the variant time that will be converted.
lpSystemTime
Long pointer to the location where the converted time is stored.

Return Values

The return value obtained from the returned INT is one of the following.

Value
Description
True | Success.
False | Failure.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

A variant time is stored as an 8-byte real value (double), representing a date between January 1, 1753 and December 31, 2078, inclusive. The value 2.0 represents January 1, 1900; 3.0 represents January 2, 1900, and so on. Adding 1 to the value increments the date by a day. The fractional part of the value represents the time of day. Therefore, 2.5 represents noon on January 1, 1900; 3.25 represents 6:00 A.M. on January 2, 1900, and so on. Negative numbers represent the dates prior to December 30, 1899.

Using the SYSTEMTIME structure is useful because:

  • It spans all time/date periods. MS-DOS date/time is limited to representing only those dates between 1/1/1980 and 12/31/2107.
  • The date/time elements are all easily accessible without needing to do any bit decoding.
  • The National Language Support data and time formatting functions GetDateFormat and GetTimeFormat take a SYSTEMTIME value as input.
  • It is the default Win32 time and date data format supported by Windows NT and Windows 95.


VarNumFromParseNum

This function converts the parsed number to a number of the VARIANT type.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VarNumFromParseNum( [in] NUMPARSE * pnumprs, [in] unsigned char * rgbDig, [in] unsigned long dwVtBits, [out] VARIANT * pvar);

Parameters

pnumprs
Parsed results. cDig = size of rgbDic
rgbDig
Contains the values of the digits. The cDig member of NUMPARSE contains the number of digits.
dwVtBits
Contains one bit set for each type that is acceptable as a return value (in many cases, just one bit).

The following VarNumFromParseNum flags indicate acceptable result types:
VTBIT_I1 | VTBIT_UI4
VTBIT_UI1 | VTBIT_R4
VTBIT_I2 | VTBIT_R8
VTBIT_UI2 | VTBIT_CY
VTBIT_I4 | VTBIT_DECIMAL

pvar
Pointer to the result variant.

Return Value

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
DISP_E_OVERFLOW | The number is too large to be represented in an allowed type. There is no error if precision is lost in the conversion.

For rounding decimal numbers, the digit array must be at least one digit longer than the maximum required for data types. The maximum number of digits required for the DECIMAL data type is 29, so the digit array must have room for 30 digits. There must also be enough digits to accept the number in octal, if that parsing options is selected. (Hexadecimal and octal numbers are limited by VarNumFromParseNum to the magnitude of an unsigned long [32 bits], so they need 11 octal digits.)

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarParseNumFromStr

This function parses a string and creates a type-independent description of the number it represents.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VarParseNumFromStr( [in] OLECHAR * strIn, [in] LCID lcid, [in] unsigned long dwFlags, [in] NUMPARSE * pnumprs, [out] unsigned char * rgbDig);

Parameters

strIn
Input string to be converted to a number.
lcid
Locale identifier
pnumprs
Parsed results.
dwFlags
Enables the caller to control parsing, therefore defining the acceptable syntax of a number. If this field is set to zero, the input string must contain nothing but decimal digits. Setting each defined flag bit enables parsing of that syntactic feature. Standard Automation parsing (for example, as used by VarI2FromStr) has all flags set (NUMPRS_STD).
rgbDig
Array filled in with the values for the digits in the range 0–7, 0–9, or 0–15, depending on whether the number is octal, decimal, or hexadecimal. All leading zeros have been stripped off. For decimal numbers, trailing zeros are also stripped off, unless the number is zero, in which case a single zero digit will be present.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Internal memory allocation failed. (Used for DBCS only to create a copy with all wide characters mapped narrow.)
DISP_E_TYPEMISMATCH | There is no valid number in the string, or there is no closing parenthesis to match an opening one. In the former case, cDig and cchUsed in the NUMPARSE structure will be zero. In the latter, the NUMPARSE structure and digit array are fully updated, as if the closing parenthesis was present.
DISP_E_OVERFLOW | For hexadecimal and octal digits, there are more digits than will fit into the array. For decimal, the exponent exceeds the maximum possible. In both cases, the NUMPARSE structure and digit array are fully updated (for decimal, the cchUsed member excludes the entire exponent).

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromBool

This function converts variant data types to float from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromBool([in] BOOL boolIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromCy

This function converts variant data types to float from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromCy([in] CURRENCY cyIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromDate

This function converts variant data types to float from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromDate([in] DATE dateIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromDec

This function converts variant data types to float from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromDec([in] DECIMAL * pdecIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromDisp

This function converts variant data types to float from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromDisp([in] IDispatch FAR * pdispIn, [in] LCID lcid, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromI1

This function converts variant data types to float from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromI1([in] DOUBLE cIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromI2

This function converts variant data types to float from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromI2([in] short sIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromI4

This function converts variant data types to float from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromI4([in] long lIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromR8

This function converts variant data types to float from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromR8([in] DOUBLE dblIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromStr

This function converts variant data types to float from OLECHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromStr([in] OLECHAR * strIn, [in] LCID lcid, [in] Ulong dwFlags, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromUI1

This function converts variant data types to float from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromUI1([in] BYTE bIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromUI2

This function converts variant data types to float from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromUI2([in] USHORT uiIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR4FromUI4

This function converts variant data types to float from unsigned Long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR4FromUI4([in] ULONG ulIn, [out] float * pfltOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromBool

This function converts variant data types to double from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromBool([in] BOOL boolIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromCy

This function converts variant data types to double from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromCy([in] CURRENCY cyIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromDate

This function converts variant data types to double from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromDate([in] DATE dateIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromDec

This function converts variant data types to double from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromDec([in] DECIMAL * pdecIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromDisp

This function converts variant data types to double from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromDips([in] IDispatch FAR * pdispIn, [in] LCID lcid, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromI1

This function converts variant data types to double from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromI1([in] char cIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromI2

This function converts variant data types to double from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromI2([in] short sIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromI4

This function converts variant data types to double from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromI4([in] long lIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromR4

This function converts variant data types to double from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromR4([in] float fltIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromStr

This function converts variant data types to double from OLECHAR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromStr([in] OLECHAR * strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromUI1

This function converts variant data types to double from unsigned char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromUI1([in] BYTE bIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromUI2

This function converts variant data types to double from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromUI2([in] USHORT uiIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarR8FromUI4

This function converts variant data types to double from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarR8FromI4([in] ULONG ulIn, [out] double * pdblOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUdateFromDate

This function unpacks a date.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VarUdateFromDate([in] DATE * dateIn, [in] unsigned long * dwFlags, [out] UDATE * pudateOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromBool

This function converts variant data types to BYTE from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromBool([in] BOOL boolIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromCy

This function converts variant data types to BYTE from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromCy([in] CURRENCY cyIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromDate

This function converts variant data types to BYTE from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromDate([in] DATE dateIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromDec

This function converts variant data types to BYTE from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromDec([in] DECIMAL * pdecIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromDisp

This function converts variant data types to BYTE from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromDisp([in] IDispatch * pdispIn, [in] LCID lcid, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromI1

This function converts variant data types to BYTE from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromI1([in] char cIn, out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromI2

This function converts variant data types to BYTE from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromI2([in] short sIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromI4

This function converts variant data types to BYTE from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromI4([in] long lIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromR4

This function converts variant data types to BYTE from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromR4([in] float fltIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromR8

This function converts variant data types to BYTE from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromR8([in] double dblIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromStr

This function converts variant data types to BYTE from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromUI2

This function converts variant data types to BYTE from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromUI2([in] USHORT uiIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI1FromUI4

This function converts variant data types to BYTE from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI1FromUI4([in] ULONG ulIn, [out] BYTE * pbOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromBool

This function converts variant data types to unsigned short from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromBool([in] BOOL boolIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromCy

This function converts variant data types to unsigned short from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromCy([in] CURRENCY cyIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromDate

This function converts variant data types to unsigned short from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromDate([in] DATE dateIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromDec

This function converts variant data types to unsigned short from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromDec([in] DECIMAL * pdecIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromDisp

This function converts variant data types to unsigned short from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromDisp([in] IDispatch * pdispIn, [in] LCID lcid, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromI1

This function converts variant data types to unsigned short from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromI1([in] char cIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromI2

This function converts variant data types to unsigned short from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromI2([in] short sIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromI4

This function converts variant data types to unsigned short from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromI4([in] long lIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromR4

This function converts variant data types to unsigned short from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromR4([in] float fltIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromR8

This function converts variant data types to unsigned short from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromR8([in] double dblIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromStr

This function converts variant data types to unsigned short from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromUI1

This function converts variant data types to unsigned short from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromUI1([in] BYTE bIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI2FromUI4

This function converts variant data types to unsigned short from unsigned long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI2FromUI4([in] ULONG ulIn, [out] USHORT * puiOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromBool

This function converts variant data types to unsigned long from BOOL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromBool([in] BOOL boolIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromCy

This function converts variant data types to unsigned long from CURRENCY.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromCy([in] CURRENCY cyIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromDate

This function converts variant data types to unsigned long from DATE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromDate([in] DATE dateIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromDec

This function converts variant data types to unsigned long from DECIMAL.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromDec([in] DECIMAL * pdecIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromDisp

This function converts variant data types to unsigned long from IDispatch.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromDisp([in] IDispatch * pdispIn, [in] LCID lcid, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromI1

This function converts variant data types to unsigned long from char.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromI1([in] char cIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromI2

This function converts variant data types to unsigned long from short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromI2([in] short sIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromI4

This function converts variant data types to unsigned long from long.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromI4([in] long lIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromR4

This function converts variant data types to unsigned long from float.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromR4([in] float fltIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromR8

This function converts variant data types to unsigned long from double.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromR8([in] double dblIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromStr

This function converts variant data types to unsigned long from BSTR.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromStr([in] BSTR strIn, [in] LCID lcid, [in] ULONG dwFlags, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromUI1

This function converts variant data types to unsigned long from BYTE.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromUI1([in] BYTE bIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VarUI4FromUI2

This function converts variant data types to unsigned long from unsigned short.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAUTAPI VarUI4FromUI2([in] USHORT uiIn, [out] ULONG * pulOut);

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VectorFromBstr

This function returns a vector, assigning each character in the BSTR to an element of the vector.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

HRESULT VectorFromBstr(BSTR bstr, SAFEARRAY FAR * FAR * ppsa);

Parameters

bstr
Unicode string to be converted to a vector.
ppsa
On exit, pointer to a one-dimensional safe array that contains the characters in the BSTR.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Value
Description
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
E_INVALIDARG | BSTR is NULL.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.


VirtualAlloc

This function reserves or commits a region of pages in the virtual address space of the calling process. Memory allocated by VirtualAlloc is automatically initialized to zero.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

LPVOID VirtualAlloc(LPVOID lpAddress, DWORD dwSize,
DWORD flAllocationType, DWORD flProtect);

Parameters

lpAddress
Long pointer to the desired starting address of the region to allocate. If the memory is being reserved, the specified address is rounded down to the next 64-kilobyte boundary. If the memory is already reserved and is being committed, the address is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function. If this parameter is NULL, the system determines where to allocate the region.
dwSize
Specifies the size, in bytes, of the region. If the lpAddress parameter is NULL, this value is rounded up to the next page boundary. Otherwise, the allocated pages include all pages containing one or more bytes in the range from lpAddress to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region.
flAllocationType
Specifies the type of allocation. You can specify any combination of the following flags:
Value
Description
MEM_COMMIT | Allocates physical storage in memory or in the paging file on disk for the specified region of pages.
An attempt to commit an already committed page will not cause the function to fail. This means that a range of committed or decommitted pages can be committed without having to worry about a failure.
MEM_RESERVE | Reserves a range of the process’s virtual address space without allocating any physical storage. The reserved range cannot be used by any other allocation operations (the malloc function, the LocalAlloc function, and so on) until it is released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function.
MEM_RESET | Not supported.
MEM_TOP_DOWN | Allocates memory at the highest possible address.

flProtect
Specifies the type of access protection. If the pages are being committed, any one of the following flags can be specified, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:
Value
Description
PAGE_READONLY | Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE | Enables both read and write access to the committed region of pages.
PAGE_EXECUTE | Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ | Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE | Enables execute, read, and write access to the committed region of pages.
PAGE_GUARD | Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm.
The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: It cannot be used with PAGE_NOACCESS. When an access attempt leads the system to turn off guard page status, the underlying page protection takes over.
If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS | Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE | Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as “no cache.” This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

Return Values

The base address of the allocated region of pages indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The following flProtect flags are not supported:

  • PAGE_WRITECOPY
  • PAGE_EXECUTE_WRITECOPY

VirtualAlloc can perform the following operations:

  • Commit a region of pages reserved by a previous call to the VirtualAlloc function.
  • Reserve a region of free pages.
  • Reserve and commit a region of free pages.

You can use VirtualAlloc to reserve a block of pages and then make additional calls to VirtualAlloc to commit individual pages from the reserved block. This enables a process to reserve a range of its virtual address space without consuming physical storage until it is needed.

Each page in the process’s virtual address space is in one of three states:

Free
The page is not committed or reserved and is not accessible to the process. VirtualAlloc can reserve, or simultaneously reserve and commit, a free page.
Reserved
The range of addresses cannot be used by other allocation functions, but the page is not accessible and has no physical storage associated with it. VirtualAlloc can commit a reserved page, but it cannot reserve it a second time. The VirtualFree function can release a reserved page, making it a free page.
Committed
Physical storage is allocated for the page, and access is controlled by a protection code. The system initializes and loads each committed page into physical memory only at the first attempt to read or write to that page. When the process terminates, the system releases the storage for committed pages. VirtualAlloc can commit an already committed page. This means that you can commit a range of pages, regardless of whether they have already been committed, and the function will not fail. VirtualFree can decommit a committed page, releasing the page’s storage, or it can simultaneously decommit and release a committed page.

If the lpAddress parameter is not NULL, the function uses the lpAddress and dwSize parameters to compute the region of pages to be allocated. The current state of the entire range of pages must be compatible with the type of allocation specified by the flAllocationType parameter. Otherwise, the function fails and none of the pages are allocated. This compatibility requirement does not preclude committing an already committed page; see the preceding list.

See Also

LocalAlloc, VirtualFree, VirtualProtect, VirtualQuery


VirtualFree

This function releases or decommits (or both) a region of pages within the virtual address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL VirtualFree(LPVOID lpAddress, DWORD dwSize,
DWORD dwFreeType);

Parameters

lpAddress
Pointer to the base address of the region of pages to be freed. If the dwFreeType parameter includes the MEM_RELEASE flag, this parameter must be the base address returned by the VirtualAlloc function when the region of pages was reserved.
dwSize
Specifies the size, in bytes, of the region to be freed. If the dwFreeType parameter includes the MEM_RELEASE flag, this parameter must be zero. Otherwise, the region of affected pages includes all pages containing one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes both pages to be freed.
dwFreeType
Specifies the type of free operation. One, but not both, of the following flags can be specified:
Value
Description
MEM_DECOMMIT | Decommits the specified region of committed pages.
An attempt to decommit an uncommitted page will not cause the function to fail. This means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure.
MEM_RELEASE | Releases the specified region of reserved pages. If this flag is specified, the dwSize parameter must be zero, or the function fails.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

VirtualFree can perform one of the following operations:

  • Decommit a region of committed or uncommitted pages.
  • Release a region of reserved pages.
  • Decommit and release a region of committed or uncommitted pages.

To release a region of pages, the entire range of pages must be in the same state (all reserved or all committed) and the entire region originally reserved by the VirtualAlloc function must be released at the same time. If only part of the pages in the original reserved region are committed, you must first call VirtualFree to decommit the committed pages and then call VirtualFree again to release the entire block.

Pages that have been released are free pages available for subsequent allocation operations. Attempting to read from or write to a free page results in an access violation exception.

VirtualFree can decommit an uncommitted page; this means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure. Decommitting a page releases its physical storage, either in memory or in the paging file on disk. If a page is decommitted but not released, its state changes to reserved, and it can be committed again by a subsequent call to VirtualAlloc. Attempting to read from or write to a reserved page results in an access violation exception.

The current state of the entire range of pages must be compatible with the type of free operation specified by the dwFreeType parameter. Otherwise, the function fails and no pages are released or decommitted.

See Also

LocalAlloc, VirtualAlloc


VirtualProtect

This function changes the access protection on a region of committed pages in the virtual address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL VirtualProtect( LPVOID lpAddress, DWORD dwSize,
DWORD flNewProtect, PDWORD lpflOldProtect);

Parameters

lpAddress
Pointer to the base address of the region of pages whose access protection attributes are to be changed.

All pages in the specified region must have been allocated in a single call to the VirtualAlloc function. The pages cannot span adjacent regions that were allocated by separate calls to VirtualAlloc.

dwSize
Specifies the size, in bytes, of the region whose access protection attributes are to be changed. The region of affected pages includes all pages containing one or more bytes in the range from the lpAddress parameter to (lpAddress+dwSize). This means that a 2-byte range straddling a page boundary causes the protection attributes of both pages to be changed.
flNewProtect
Specifies the new access protection. You can specify any one of the following flags, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as necessary:
Value
Description
PAGE_READONLY | Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE | Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY | Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE | Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ | Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE | Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY | Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD | Pages in the region become guard pages. Any attempt to access a guard page causes the system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm.
The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: it cannot be used with PAGE_NOACCESS. When an access attempt leads the system to turn off guard page status, the underlying page protection takes over.
If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS | Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE | Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as “no cache.” This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

lpflOldProtect
Long pointer to a variable that the function sets to the previous access protection value of the first page in the specified region of pages. If this parameter is NULL or does not point to a valid variable, the function fails.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The following flProtect flags are not supported:

  • PAGE_WRITECOPY
  • PAGE_EXECUTE_WRITECOPY

You can set the access protection value on committed pages only. If the state of any page in the specified region is not committed, the function fails and returns without modifying the access protection of any pages in the specified region.

The VirtualProtect function changes the access protection of memory in the calling process, and the VirtualProtectEx function changes the access protection of memory in a specified process.

See Also

VirtualAlloc


VirtualQuery

This function provides information about a range of pages in the virtual address space of the calling process.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD VirtualQuery(LPCVOID lpAddress,
PMEMORY_BASIC_INFORMATION lpBuffer,
DWORD dwLength);

Parameters

lpAddress
Pointer to the base address of the region of pages to be queried. This value is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.
lpBuffer
Pointer to a MEMORY_BASIC_INFORMATION structure in which information about the specified page range is returned.
dwLength
Specifies the size, in bytes, of the buffer pointed to by the lpBuffer parameter.

Return Values

The actual number of bytes returned in the information buffer indicates success.

Remarks

VirtualQuery provides information about a region of consecutive pages beginning at a specified address that share the following attributes:

  • The state of all pages is the same with the MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE flag.
  • If the initial page is not free, all pages in the region are part of the same initial allocation of pages reserved by a call to the VirtualAlloc function.
  • The access of all pages is the same with the PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE flag.

The function determines the attributes of the first page in the region and then scans subsequent pages until it scans the entire range of pages or until it encounters a page with a nonmatching set of attributes. The function returns the attributes and the size, in bytes, of the region of pages with matching attributes. For example, if there is a 20 megabyte (MB) region of free memory, and VirtualQuery is called on a page that is 10 MB into the region, the function will obtain a state of MEM_FREE and a size of 10 MB.

This function reports on a region of pages in the memory of the calling process, and the VirtualQueryEx function reports on a region of pages in the memory of a specified process.

See Also

GetSystemInfo, MEMORY_BASIC_INFORMATION


WaitForDebugEvent

This function waits for a debugging event to occur in a process being debugged.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WaitForDebugEvent(LPDEBUG_EVENT lpDebugEvent,
DWORD dwMilliseconds);

Parameters

lpDebugEvent
Pointer to a DEBUG_EVENT structure that is filled with information about the debugging event.
dwMilliseconds
Specifies the number of milliseconds to wait for a debugging event. If this parameter is zero, the function tests for a debugging event and returns immediately. If the parameter is INFINITE, the function does not return until a debugging event has occurred.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Only the thread that created the process being debugged can call WaitForDebugEvent.

See Also

ContinueDebugEvent, DebugActiveProcess, DebugBreak, DEBUG_EVENT, OutputDebugString


WaitForMultipleObjects

This function returns when one of the following occurs:

  • Either any one of the specified objects are in the signaled state.
  • The time-out interval elapses.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

DWORD WaitForMultipleObjects(DWORD nCount,
CONST HANDLE *lpHandles, BOOL bWaitAll, DWORD dwMilliseconds);

Parameters

nCount
Specifies the number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.
lpHandles
Pointer to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.
fWaitAll
Specifies the wait type. This parameter must be set to FALSE. This causes function to return when the state of any one of the objects set to is signaled. The return value indicates the object whose state caused the function to return.
dwMilliseconds
Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the bWaitAll parameter are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. This value can be one of the following.

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount –1)
The return value minus WAIT_OBJECT_0 indicates the lpHandles array index of the object that satisfied the wait. If more than one object became signaled during the call, this is the array index of the signaled object with the smallest index value of all the signaled objects.
WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount –1)
The return value minus WAIT_ABANDONED_0 indicates the lpHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_TIMEOUT
The time-out interval elapsed and the condition specified by the fWaitAll parameter are not satisfied.

WAIT_FAILED indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE does not support waiting for semaphores, change notification objects, input, and timers.

For Windows CE versions 1.0 and 1.01, this function cannot wait on process or thread handles.

The WaitForMultipleObjects function determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the criteria to be met.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. When fWaitAll is FALSE, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the objects not selected are unaffected.

The WaitForMultipleObjects function can specify handles of any of the following object types in the lpHandles array:

  • Event
  • Mutex
  • Process
  • Thread

Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. Two examples of code that indirectly creates windows are DDE and COM CoInitialize. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForMultipleObjects.

See Also

CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateThread, PulseEvent, ResetEvent, SetEvent, WaitForSingleObject


WaitForSingleObject

This function returns when the specified object is in the signaled state or when the time-out interval elapses.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

DWORD WaitForSingleObject( HANDLE hHandle, DWORD dwMilliseconds );

Parameters

hHandle
Handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section.
dwMilliseconds
Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object’s state is nonsignaled. If dwMilliseconds is zero, the function tests the object’s state and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. This value can be one of the following.

Value
Description
WAIT_ABANDONED | The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_OBJECT_0 | The state of the specified object is signaled.
WAIT_TIMEOUT | The time-out interval elapsed, and the object’s state is nonsignaled.

WAIT_FAILED indicates failure. Waiting on an invalid handle causes WaitForSingleObject to return WAIT_FAILED.

To get extended error information, call GetLastError.

Remarks

Windows CE does not support waiting for semaphores, change notification objects, input, and timers.

For Windows CE versions 1.0 and 1.01, this function cannot wait on process or thread handles.

The WaitForSingleObject function checks the current state of the specified object. If the object’s state is nonsignaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for the object state to become signaled or the time-out interval to elapse.

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The WaitForSingleObject function can wait for the following objects:

  • Event
  • Mutex
  • Process
  • Thread

Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. Two examples of code that indirectly creates windows are DDE and COM CoInitialize. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObject.

See Also

CreateEvent, CreateFile, PulseEvent, ResetEvent, SetEvent, Sleep


WideCharToMultiByte

This function maps a wide-character string to a new character string. The new character string is not necessarily from a multibyte character set.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.01 and later

Syntax

int WideCharToMultiByte(UINT CodePage, DWORD dwFlags,
LPCWSTR lpWideCharStr, int cchWideChar, LPSTR lpMultiByteStr,
int cchMultiByte, LPCSTR lpDefaultChar, LPBOOL lpUsedDefaultChar);

Parameters

CodePage
[in] Specifies the code page used to perform the conversion. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the following values:
Value
Description
CP_ACP | ANSI code page
CP_MACCP | Not supported
CP_OEMCP | OEM code page
CP_SYMBOL | Not supported
CP_THREAD_ACP | Not supported

dwFlags
[in] Specifies the handling of unmapped characters. The function performs more quickly when none of these flags is set. The following flag constants are defined:
Value
Description
WC_COMPOSITECHECK | Convert composite characters to precomposed characters.
WC_DISCARDNS | Discard nonspacing characters during conversion.
WC_SEPCHARS | Generate separate characters during conversion. This is the default conversion behavior.
WC_DEFAULTCHAR | Replace exceptions with the default character during conversion.

When WC_COMPOSITECHECK is specified, the function converts composite characters to precomposed characters. A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/nonspacing character combination. In the character è, the e is the base character, and the accent grave mark is the nonspacing character.

When an application specifies WC_COMPOSITECHECK, it can use the last three flags in this list (WC_DISCARDNS, WC_SEPCHARS, and WC_DEFAULTCHAR) to customize the conversion to precomposed characters. These flags determine the function’s behavior when there is no precomposed mapping for a base/nonspace character combination in a wide-character string. These last three flags can only be used if the WC_COMPOSITECHECK flag is set.

The function’s default behavior is to generate separate characters (WC_SEPCHARS) for unmapped composite characters.

lpWideCharStr
[in] Pointer to the wide-character string to be converted.
cchWideChar
[in] Specifies the number of Unicode (16-bit) characters in the string pointed to by the lpWideCharStr parameter. If this value is –1, the string is assumed to be null-terminated and the length is calculated automatically.
lpMultiByteStr
[out] Pointer to the buffer to receive the translated string.
cbMultiByte
[in] Specifies the size in bytes of the buffer pointed to by the lpMultiByteStr parameter. If this value is zero, the function returns the number of bytes required for the buffer. (In this case, the lpMultiByteStr buffer is not used.)
lpDefaultChar
[in] Pointer to the character used if a wide character cannot be represented in the specified code page. If this parameter is NULL, a system default value is used. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.
lpUsedDefaultChar
[in/out] Pointer to a flag that indicates whether a default character was used. The flag is set to TRUE if one or more wide characters in the source string cannot be represented in the specified code page. Otherwise, the flag is set to FALSE. This parameter may be NULL. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

Return Values

If cbMultiByte is nonzero, the number of bytes written to the buffer pointed to by lpMultiByteStr indicates success. If cbMultiByte is zero, the required size, in bytes, for a buffer that can receive the translated string indicates success. Zero indicates failure. To get extended error information, call GetLastError. Possible values for GetLastError include the following:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

An application can use the lpDefaultChar parameter to change the default character used for the conversion.

As noted earlier, the WideCharToMultiByte function operates most efficiently when both lpDefaultChar and lpUsedDefaultChar are NULL. The following table shows the behavior of WideCharToMultiByte for the four combinations of lpDefaultChar and lpUsedDefaultChar :

lpDefaultChar
lpUsedDefaultChar
Result
NULL | NULL | No default checking. This is the most efficient, quick way to use this function.
non-NULL | NULL | Uses the specified default character, but does not set lpUsedDefaultChar.
NULL | non-NULL | Uses the system default character and sets lpUsedDefaultChar if necessary.
non-NULL | non-NULL | Uses the specified default character and sets lpUsedDefaultChar if necessary.

See Also

MultiByteToWideChar


WindowProc

This function is an application-defined callback function that processes messages sent to a window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam);

Parameters

hwnd
[in] Handle to the window.
uMsg
[in] Specifies the message.
wParam
[in] Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.
lParam
[in] Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

Return Values

The return value is the result of the message processing and depends on the message sent.

See Also

CallWindowProc, DefWindowProc, RegisterClass


WinMain

This function is called by the system as the initial entry point for WindowsCE-based applications.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPWSTR lpCmdLine, int nShowCmd);

Parameters

hInstance
[in] Handle to the current instance of the application.
hPrevInstance
[in] Handle to the previous instance of the application. For a Win32-based application, this parameter is always NULL.

If you need to detect whether another instance already exists, create a uniquely named mutex using the CreateMutex function. CreateMutex will succeed even if the mutex already exists, but the GetLastError function will return ERROR_ALREADY_EXISTS. This indicates that another instance of your application exists, because it created the mutex first.

lpCmdLine
[in] Pointer to a null-terminated string that specifies the command line for the application, excluding the program name.
nCmdShow
[in] Specifies how the window is to be shown. This parameter can be one of the following values:
Value
Description
SW_HIDE | Hides the window and activates another window.
SW_SHOW | Activates a window and displays it in its current size and position.
SW_SHOWNA | Displays a window in its current state. The active window remains active.
SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position (same as SW_RESTORE).

Return Values

The exit value contained in that message’s wParam parameter indicates success, and that the function terminates when it receives a WM_QUIT message. Zero indicates that the function terminates before entering the message loop.

Remarks

Your WinMain should initialize the application, display its main window, and enter a message retrieval-and-dispatch loop that is the top-level control structure for the remainder of the application’s execution. Terminate the message loop when it receives a WM_QUIT message. At that point, your WinMain should exit the application, returning the value passed in the WM_QUIT message’s wParam parameter. If WM_QUIT was received as a result of calling PostQuitMessage, the value of wParam is the value of the PostQuitMessage function’s nExitCode parameter.

See Also

DispatchMessage, GetMessage, PostQuitMessage, TranslateMessage


WriteClassStg

This function stores the specified CLSID in a storage object.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI WriteClassStg( IStorage * pStg, REFCLSID rclsid);

Parameters

pStg
[in] IStorage pointer to the storage object that gets a new CLSID.
rclsid
[in] CLSID to be stored with the object.

Return Values

S_OK
Indicates the CLSID was successfully written to the file.
STG_E_MEDIUMFULL
Indicates the CLSID could not be written due to lack of memory.

IStorage::SetClass method error return values.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

The WriteClassStg function writes a CLSID to the specified storage object so it can be read by the ReadClassStg function. Container applications typically call this function before calling the IPersistStorage::Save method.


WriteClassStm

This function writes a CLSID to the specified stream object so it can be read by the ReadClassStm function. Most applications do not call WriteClassStm directly.

At a Glance

Header file: | Ole2.h
Windows CE versions: | 2.0 and later

Syntax

WINOLEAPI WriteClassStm( IStream * pStm, REFCLSID rclsid);

Parameters

pStm
[in] IStream pointer to the stream into which the CLSID is to be written.
rclsid
[in] CLSID to write to the stream.

Return Values

S_OK
Indicates the CLSID was successfully written.
STG_E_MEDIUMFULL
The CLSID could not be written because there is no space left on device.

IStorage::SetClass method error return values.

Remarks

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

The WriteClassStm function writes a CLSID to the specified stream object so it can be read by the ReadClassStm function. Most applications do not call WriteClassStm directly.


WriteFile

This function writes data to a file. WriteFile starts writing data to the file at the position indicated by the file pointer. After the write operation has been completed, the file pointer is adjusted by the number of bytes actually written.

A remote application interface (RAPI) version of this function exists, and it is called CeWriteFile.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

BOOL WriteFile( HANDLE hFile, LPCVOID lpBuffer,
DWORD nNumberOfBytesToWrite, LPDWORD lpNumberOfBytesWritten,
LPOVERLAPPED lpOverlapped );

Parameters

hFile
[in] Handle to the file to be written to. The file handle must have been created with GENERIC_WRITE access to the file.
lpBuffer
[in] Pointer to the buffer containing the data to be written to the file.
nNumberOfBytesToWrite
[in] Number of bytes to write to the file.

A value of zero specifies a null write operation. A null write operation does not write any bytes but does cause the time stamp to change. WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

Named pipe write operations across a network are limited to 65,535 bytes.

lpNumberOfBytesWritten
[out] Pointer to the number of bytes written by this function call. WriteFile sets this value to zero before doing any work or error checking.
lpOverlapped
[in] Unsupported; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

If part of the file is locked by another process and the write operation overlaps the locked portion, this function fails.

Accessing the output buffer while a write operation is using the buffer may lead to corruption of the data written from that buffer. Applications must not read from, write to, reallocate, or free the output buffer that a write operation is using until the write operation completes.

See Also

CreateFile, GetLastError, ReadFile, SetEndOfFile


WriteProcessMemory

This function writes memory in a specified process. The entire area to be written to must be accessible, or the operation fails.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

BOOL WriteProcessMemory( HANDLE hProcess, LPVOID lpBaseAddress,
LPVOID lpBuffer, DWORD nSize, LPDWORD lpNumberOfBytesWritten);

Parameters

hProcess
Handle returned from the OpenProcess function that provided full access to the process.
lpBaseAddress
Pointer to the base address in the specified process to be written to. Before any data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for write access. If this is the case, the function proceeds; otherwise, the function fails.
lpBuffer
Pointer to the buffer that supplies data to be written into the address space of the specified process.
nSize
Specifies the requested number of bytes to write into the specified process.
lpNumberOfBytesWritten
Pointer to the actual number of bytes transferred into the specified process. This parameter is optional. If lpNumberOfBytesWritten is NULL, the parameter is ignored.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. The function fails if the requested write operation crosses into an area of the process that is inaccessible.

Remarks

WriteProcessMemory copies the data from the specified buffer in the current process to the address range of the specified process. The process whose address space is being written to is typically, but not necessarily, being debugged.

The entire area to be written to must be accessible. If it is not, the function fails as noted previously.

See Also

ReadProcessMemory


wsprintf

This function formats and stores a series of characters and values in a buffer. Any arguments are converted and copied to the output buffer according to the corresponding format specification in the format string. The wsprintf function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

int wsprintf( LPTSTR lpOut, LPCTSTR lpFmt, …argument );

Parameters

lpOut
[out] Pointer to a buffer to receive the formatted output. The maximum size of the buffer is 1024 bytes.
lpFmt
[in] Pointer to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the Remarks section.
...
[in] Specifies one or more optional arguments. The number and type of argument parameters depend on the corresponding format-control specifications in the lpFmt parameter.

Return Values

The number of characters stored in the output buffer, not counting the terminating null character, indicates success. A value less than the length of the format-control string indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of wsprintf.

The format-control string contains format specifications that determine the output format for the arguments following the lpFmt parameter. Format specifications, discussed below, always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted (for example, %% produces a single percent-sign character).

The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and copied to the output buffer according to the format specification. The second format specification causes the second argument to be converted and copied, and so on. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

A format specification has the following form:

%[-][#][0][width][.precision]type

Each field is a single character or a number signifying a particular format option. The type characters that appear after the last optional format field determine whether the associated argument is interpreted as a character, a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s). The optional fields control other aspects of the formatting. Following are the optional and required fields and their meanings:

Field
Description
– Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted, the output is padded to the left, justifying it to the right.
# Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).
0 | Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces.
width | Copy the specified minimum number of characters to the output buffer. The width field is a nonnegative integer. The width specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or if the width field is not present, all characters of the value are printed, subject to the precision specification.
.precision | For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument is less than the specified precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.
For strings, copy the specified maximum number of characters to the output buffer.
type | Output the corresponding argument as a character, a string, or a number. This field can be any of the following character sequences:

Sequence
Insert
c | A single character. This sequence is interpreted as type WCHAR.
C | A single character. This sequence is interpreted as type CHAR.
d | A signed decimal integer argument. This sequence is equivalent to the i sequence.
hc, hC | A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type CHAR, even when the calling application uses the #define UNICODE compile flag.
hd | A signed short integer argument.
hs, hS | A string. This sequence is always interpreted as type LPSTR, even when the calling application uses the #define UNICODE compile flag.
hu | An unsigned short integer argument.
i | A signed decimal integer. This sequence is equivalent to the d sequence.
lc, lC | A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type WCHAR, even when the calling application does not use the #define UNICODE compile flag.
ld | A long signed decimal integer. This sequence is equivalent to the li sequence.
li | A long signed decimal integer. This sequence is equivalent to the ld sequence.
ls, lS | A string. This sequence is always interpreted as type LPWSTR, even when the calling application does not use the #define UNICODE compile flag. This sequence is equivalent to the ws sequence.
lu | A long unsigned integer.
lx, lX | A long unsigned hexadecimal integer in lowercase or uppercase.
s | A string. This sequence is interpreted as type LPWSTR.
S | A string. This sequence is interpreted as type LPSTR.
u | An unsigned integer argument.
x, X | An unsigned hexadecimal integer in lowercase or uppercase.

Unlike other Win32 functions, wsprintf uses the C calling convention (_cdecl), rather than the Pascal calling convention. As a result, it is the responsibility of the calling process to pop arguments off the stack, and arguments are pushed on the stack from right to left. In C-language modules, the C compiler performs this task.

See Also

wvsprintf


wvsprintf

This function formats and stores a series of characters and values in a buffer. The items pointed to by the argument list are converted and copied to an output buffer according to the corresponding format specification in the format-control string. The function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

int wvsprintf( LPTSTR lpOut, LPCTSTR lpFmt, va_list ArgList );

Parameters

lpOutput
[out] Pointer to a buffer to receive the formatted output.
lpFormat
[in] Pointer to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see wsprintf.
arglist
[in] Variable argument list; each element of the list specifies an argument for the format-control string. The number, type, and interpretation of the arguments depend on the corresponding format-control specifications in the lpFmt parameter.

Return Values

The number of characters stored in the buffer, not counting the terminating null character, indicates success. A value less than the length of the format-control string indicates failure. To get extended error information, call GetLastError.

Remarks

Windows CE supports only the Unicode version of wvsprintf.

The function copies the format-control string into the output buffer character by character, starting with the first character in the string. When it encounters a format specification in the string, the function retrieves the value of the next available argument (starting with the first argument in the list), converts that value into the specified format, and copies the result to the output buffer. The function continues to copy characters and expand format specifications in this way until it reaches the end of the format-control string. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

See Also

wsprintf


ARRAYDESC

This structure is contained within the TYPEDESC structure and used to describe the types of the array elements and the dimensions of the array.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _tagARRAYDESC {
TYPEDESC tdescElem;
unsigned short cDims;
SAFEARRAYBOUND rgbounds[1];
} ARRAYDESC;

Members

tdescElem
Element type.
cDims
Dimension count.
rgbounds
Variable length array containing one element for each dimension.


AUTH_IDENTITY

This structure is used to establish the identity of the client and is authentication-service specific.

At a Glance

Header file: | Objbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _AUTH_IDENTITY {
[size_is(UserLength+1)] USHORT *User;
ULONG UserLength;
[size_is(DomainLength+1)] USHORT * Domain;
ULONG DomainLength;
[size_is(DomainLength+1)] USHORT *Password;
ULONG Flags;
} AUTH_IDENTITY;


BINDPTR

This structure holds a pointer to a FUNCDESC, VARDESC or ITypeComp interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef union tagBINDPTR {
FUNCDESC FAR *lpfuncdesc;
VARDESC FAR *lpvardesc;
ITypeComp FAR *lptcomp;
} BINDPTR;


BY_HANDLE_FILE_INFORMATION

This structure contains information retrieved by the GetFileInformationByHandle function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _BY_HANDLE_FILE_INFORMATION {
DWORD dwFileAttributes;
FILETIME ftCreationTime;
FILETIME ftLastAccessTime;
FILETIME ftLastWriteTime;
DWORD dwVolumeSerialNumber;
DWORD nFileSizeHigh;
DWORD nFileSizeLow;
DWORD nNumberOfLinks;
DWORD nFileIndexHigh;
DWORD nFileIndexLow;
} BY_HANDLE_FILE_INFORMATION;

Members

dwFileAttributes
Specifies file attributes. It can be one or more of the following values:
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file or directory is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED | The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY | The handle identifies a directory.
FILE_ATTRIBUTE_ENCRYPTED | The file or directory is encrypted. For a file, this means that all of the data streams are encrypted. For a directory, this means that encryption is the default for newly created files and directories.
FILE_ATTRIBUTE_HIDDEN | The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_INROM | This file is an operating system file stored in ROM. These files are read-only; they cannot be modified.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE | The file data is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY | The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_REPARSE_POINT | The file has an associated reparse point.
FILE_ATTRIBUTE_ROMMODULE | This file is an operating system file stored in ROM, designed to execute in place. In other words, code from this file is executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file, instead the LoadLibrary and CreateProcess functions must be used.
FILE_ATTRIBUTE_ROMSTATICREF | The DLL module is statically linked to another module in the ROM file system. This prevents the DLL module from being replaced by a RAM version of the DLL.
FILE_ATTRIBUTE_SPARSE_FILE | The file is a sparse file.
FILE_ATTRIBUTE_SYSTEM | The file or directory is part of the operating system or is used exclusively by the operating system.
FILE_ATTRIBUTE_TEMPORARY | The file is being used for temporary storage. File systems attempt to keep all the data in memory for quicker access, rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.

ftCreationTime
Specifies the time the file was created. If the underlying file system does not support this time member, ftCreationTime is zero.
ftLastAccessTime
Specifies the time the file was last accessed. If the underlying file system does not support this time member, ftLastAccessTime is zero.
ftLastWriteTime
Specifies the last time the file was written to.
dwVolumeSerialNumber
Specifies the serial number of the volume that contains the file.
nFileSizeHigh
Specifies the high-order word of the file size.
nFileSizeLow
Specifies the low-order word of the file size.
nNumberOfLinks
Specifies the number of links to this file. For the FAT file system this member is always 1. For NTFS, it may be more than 1.
nFileIndexHigh
Specifies the high-order word of a unique identifier associated with the file.
nFileIndexLow
Specifies the low-order word of a unique identifier associated with the file. This identifier and the volume serial number uniquely identify a file. This number may change when the system is restarted or when the file is opened. After a process opens a file, the identifier is constant until the file is closed. An application can use this identifier and the volume serial number to determine whether two handles refer to the same file.

See Also

GetFileInformationByHandle


CE_FIND_DATA

This structure describes a file found by the CeFindAllFiles function.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _CE_FIND_DATA {
DWORD dwFileAttributes;
FILETIME ftCreationTime;
FILETIME ftLastAccessTime;
FILETIME ftLastWriteTime;
DWORD nFileSizeHigh;
DWORD nFileSizeLow;
DWORD dwOID;
WCHAR cFileName[MAX_PATH];
} CE_FIND_DATA;

Members

dwFileAttributes
Specifies the file attributes of the file found. It can be one or more of the following values.
Value
Description
FILE_ATTRIBUTE_ARCHIVE | The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED | The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY | The file is a directory.
FILE_ATTRIBUTE_HAS_CHILDREN | The directory has subdirectories.
FILE_ATTRIBUTE_HIDDEN | The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_INROM | This file is an operating system file stored in ROM. These files are read-only; they cannot be modified.
FILE_ATTRIBUTE_NORMAL | The file has no other attributes set. This value is valid only if used alone.
FILE_ATTRIBUTE_READONLY | The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_ROMMODULE | This file is an operating system file stored in ROM, designed to execute in place. In other words, code from this file is executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file, instead the LoadLibrary and CreateProcess functions must be used.
FILE_ATTRIBUTE_SYSTEM | The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY | The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file’s data remains in memory without being flushed to the media because the file will soon be deleted.

ftCreationTime
Specifies a FILETIME structure containing the time the file was created.
ftLastAccessTime
Specifies a FILETIME structure containing the time that the file was last accessed.
ftLastWriteTime
Specifies a FILETIME structure containing the time that the file was last written to.
nFileSizeHigh
Specifies the high-order DWORD value of the file size, in bytes. This value is zero unless the file size is greater than MAXDWORD. The size of the file is equal to (nFileSizeHigh * MAXDWORD) + nFileSizeLow.
nFileSizeLow
Specifies the low-order DWORD value of the file size, in bytes.
dwOID
Specifies the object identifier of the file.
cFileName
Null-terminated string that contains the name of the file.


CE_USER_NOTIFICATION

This structure contains information used to initialize the user notifications settings dialog box, and receives the user’s notification preferences entered by way of the dialog box. Also used when setting a user notification.

At a Glance

Header file: | Notify.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct UserNotificationType {
DWORD ActionFlags;
TCHAR *pwszDialogTitle;
TCHAR *pwszDialogText;
TCHAR *pwszSound;
DWORD nMaxSound;
DWORD dwReserved;
} CE_USER_NOTIFICATION, *PCE_USER_NOTIFICATION;

Members

ActionFlags
Specifies the action to take when a notification event occurs. It can be a combination of the following flags:
Value
Description
PUN_LED | Flashes the LED.
PUN_VIBRATE | Vibrates the device.
PUN_DIALOG | Displays the user notification dialog box. When this structure is passed to the CeSetUserNotification function, the pwszDialogTitle and pwszDialogText members must provide the title and text of the dialog box.
PUN_SOUND | Plays the sound specified by the pwszSound member. When passed to PSVN, the pwszSound member must provide the name of the sound file.
PUN_REPEAT | Repeats the pwszSound for 10–15 seconds. Only valid if PUN_SOUND is set.

Any flag that is not valid on the current hardware platform is ignored.

pwszDialogTitle
Pointer to the string that contains the title of the user notification dialog box. If this member is NULL, no dialog is displayed. The CeGetUserNotificationPreferences function ignores this member.
pwszDialogText
Pointer to the string that contains the text of the user notification dialog box. If this member is NULL, no dialog is displayed. The CeGetUserNotificationPreferences function ignores this member.
pwszSound
Pointer to a buffer that contains the unqualified name of a sound file to play. This member is ignored if the ActionFlags member does not include the PUN_SOUND flag.
nMaxSound
Specifies the maximum length of the string that the CeGetUserNotificationPreferences function can copy into the pwszSound buffer. Because the string may be a path name in a future release, the buffer must be at least the length derived by the following expression: PATH_MAX * sizeof(TCHAR). This member is ignored by the CeSetUserNotification function.
dwReserved
Reserved; set to zero.

Remarks

The CE_USER_NOTIFICATION structure is passed in the CeGetUserNotificationPreferences function. Initial settings are used to populate the dialog box. If the function returns TRUE, the returned settings should be saved, and considered when calling CeSetUserNotification. Settings for hardware not on the current device will be ignored.

It is also used when calling CeSetUserNotification, to describe what should happen when the notification time is reached.

See Also

CeGetUserNotificationPreferences, CeSetUserNotification


CEBLOB

This structure contains information about a Binary Large Object (BLOB)s of data in the object store.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CEBLOB {
DWORD dwCount;
LPBYTE lpb;
} CEBLOB;

Members

dwCount
Specifies the size, in bytes, of the BLOB.
lpb
Pointer to the beginning of the BLOB.

See Also

CEVALUNION


CEDB_FIND_DATA

This structure contains information about a database in the Windows CE object store. This structure is used by the CeFindAllDatabases function.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and later

Syntax

struct CEDB_FIND_DATA {
CEOID OidDb;
CEDBASEINFO DbInfo;
};

Members

OidDb
Object identifier of a database in the Windows CE object store.
DbInfo
CEDBASEINFO structure that contains information about a database.

See Also

CEDBASEINFO


CEDBASEINFO

This structure contains information about a database object. This structure is used by the CeSetDatabaseInfo and CeCreateDatabaseEx functions.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CEDBASEINFO {
DWORD dwFlags;
WCHAR szDbaseName[CEDB_MAXDBASENAMELEN];
DWORD dwDbaseType;
WORD wNumRecords;
WORD wNumSortOrder;
DWORD dwSize;
FILETIME ftLastModified;
SORTORDERSPEC rgSortSpecs[CEDB_MAXSORTORDER];
} CEDBASEINFO;

Members

dwFlags
The low-order word specifies the valid members of this structure. This member is one or a combination of the following flags:
Value
Description
CEDB_VALIDMODTIME | The ftLastModified member is valid and should be used.
CEDB_VALIDNAME | The szDbaseName member is valid and should be used.
CEDB_VALIDTYPE | The dwDbaseType member is valid and should be used.
CEDB_VALIDSORTSPEC | The rgSortSpecs member is valid and should be used.
CEDB_VALIDDBFLAGS | The low-order word of the dwFlags member is valid and should be used.

The high-order word specifies the associated database properties. This member is the following flag:
Value
Description
CEDB_NOCOMPRESS The database is not compressed. If this flag is used with CeSetDatabaseInfoEx, a compressed database is uncompressed. If this flag is used with CeCreateDatabaseEx, the database is not compressed.
To compress a database, CeSetDatabaseInfoEx or CeCreateDatabaseEx is called with CEDB_VALIDDBFLAGS set and the CEDB_NOCOMPRESS bit cleared. By default, all databases are compressed. If you are going to change the compression, it should be done at creation time.

szDbaseName
Null-terminated string that contains the name of the database. The string can have up to 32 characters, including the terminating null character. This member must be set when used for CeCreateDatabaseEx.
dwDbaseType
Specifies the type identifier for the database.
wNumRecords
Returns the number of records in the database.
wNumSortOrder
Number of sort orders active in the database. Up to four sort orders can be active at a time.
dwSize
Specifies, in bytes, the size of the database.
ftLastModified
Returns the last time this database was modified.
rgSortSpecs
Array containing the sort order descriptions. Only the first n array members are valid, where n is the value specified by the wNumSortOrder member. If no sort orders are specified for CeCreateDatabaseEx or when CEDB_VALIDSORTSPEC is not specified, then a default sort order is assigned to the database.

Remarks

For Windows CE versions 2.10 and later, dwFlags has additional meaning, but is still compatible with previous versions. The high-order word of dwFlags specifies additional database properties.

See Also

CeCreateDatabaseEx, CEOIDINFO, CeSetDatabaseInfoEx, HIWORD, LOWORD


CEDIRINFO

This structure contains information about a directory object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CEDIRINFO {
DWORD dwAttributes;
CEOID oidParent;
WCHAR szDirName[MAX_PATH];
} CEDIRINFO;

Members

dwAttributes
Specifies the attributes of the directory.
oidParent
Object identifier of the parent directory.
szDirName
Null-terminated string that contains the name and path of the directory.

See Also

CEOIDINFO


CEFILEINFO

This structure contains information about a file object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CEFILEINFO {
DWORD dwAttributes;
CEOID oidParent;
WCHAR szFileName[MAX_PATH];
FILETIME ftLastChanged;
DWORD dwLength;
} CEFILEINFO;

Members

dwAttributes
Specifies the attributes of the file.
oidParent
Object identifier of the parent directory.
szFileName
Null-terminated string that contains the name and path of the file.
ftLastChanged
Time stamp that indicates when the contents of the file were last changed.
dwLength
Specifies the length, in bytes, of the file.

See Also

CEOIDINFO


CENOTIFICATION

This structure contains information about a change in a the object store or a mounted database volume.

Syntax

typedef struct _CENOTIFICATION {
DWORD dwSize
DWORD dwParam;
UINT uType;
CEGUID guid;
CEOID oid;
CEOID oidParent;
} CENOTINOTIFICATION;

Members

dwSize
Specifies the size of the CENOTIFICATION structure.
dwParam
User-defined value assigned in the CENOTIFIREQUEST structure.
uType
Describes the notification type. It is one of the following flags:
Value
Description
DB_CEOID_CREATED | New OID object was created.
DB_CEOID_DATABASE_DELETED | Database was deleted on a volume.
DB_CEOID_RECORD_DELETED | Record was deleted in a database.
DB_CEOID_FILE_DELETED | File was deleted. Only available to a OEM replication process.
DB_CEOID_DIRECTORY_DELETED | Directory was deleted. Only available to a OEM replication process.
DB_CEOID_CHANGED | Object was modified.

guid
Globally unique identifier (CEGUID) of the mounted database volume or object store that the notification applies.
oid
OID of the object that was changed.
oidParent
OID of the parent object.

Remarks

The notification structure returned by the system must be freed after the notification has been processed. Call CeFreeNotification to free the notification structure.

See Also

CeFreeNotification, CeOpenDatabaseEx


CENOTIFYREQUEST

This structure contains information to initialize the database and object store notification process. This structure is passed to the CeOpenDatabaseEx or CeRegisterReplNotification (OEM function) functions to initiate the process.

Syntax

typedef struct _CENOTIFYREQUEST {
DWORD dwSize;
HWND hWnd;
DWORD dwFlags;
HANDLE hHeap;
DWORD dwParam;
} CENOTIREQUEST;

Members

dwSize
Specifies the size of the CENOTIFYREQUEST structure.
hWnd
Handle to the window that receives notifications.
dwFlags
Specifies how notifications are handled. It is one of the following values:
Value
Description
0 | Version 1.0 to version 2.0 behavior.
CEDB_EXNOTIFICATION | Request to receive a pointer to a CENOTIFICATION structure that identifies which objects have changed. Applications working with mounted database volumes must set this flag to receive proper notification of changes in a volume.

hHeap
Handle to a heap that is used to allocate the notification structure. If this is NULL, the system allocates memory in the default heap of the process.
dwParam
User-defined parameter that is returned in the CENOTIFICATION structure when an application is notified of a change.

Remarks

The CENOTIFICATION structure returned by system must be freed after the notification has been processed. To free the CENOTIFICATION structure you must call CeFreeNotifcation.


CEOIDINFO

This structure contains information about an object in the object store or database volume.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CEOIDINFO {
WORD wObjType;
DWORD dwSize;
WORD wPad;
union {
CEFILEINFO infFile;
CEDIRINFO infDirectory;
CEDBASEINFO infDatabase;
CERECORDINFO infRecord;
};
} CEOIDINFO;

Members

wObjType
Specifies the type of the object. It is one of the following values:
Value
Description
OBJTYPE_INVALID | The object store contains no valid object that has this object identifier.
OBJTYPE_FILE | The object is a file.
OBJTYPE_DIRECTORY | The object is a directory.
OBJTYPE_DATABASE | The object is a database.
OBJTYPE_RECORD | The object is a record inside a database.

dwSize
Specifies the size of CEOIDINFOEX, that is, sizeof(CEOIDINFOEX).
wPad
Aligns the structure on a double-word boundary.
infFile
CEFILEINFO structure that contains information about a file. This member is valid only if wObjType is OBJTYPE_FILE.
infDirectory
CEDIRINFO structure that contains information about a directory. This member is valid only if wObjType is OBJTYPE_DIRECTORY.
infDatabase
CEDBASEINFO structure that contains information about a database. This member is valid only if wObjType is OBJTYPE_DATABASE.
infRecord
CERECORDINFO structure that contains information about a record in a database. This member is valid only if wObjType is OBJTYPE_RECORD.

See Also

CEDBASEINFO, CEDIRINFO, CEFILEINFO, CERECORDINFO


CEPROPVAL

This structure contains a property value.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CEPROPVAL {
CEPROPID propid;
WORD wLenData;
WORD wFlags;
CEVALUNION val;
} CEPROPVAL;
typedef CEPROPVAL *PCEPROPVAL;

Members

propid
Identifier of the property value. The high-order word is an application-defined identifier, and the low-order word is a predefined constant value that indicates the data type of the value specified by the val member. The low-order word can be one of the following values:
Value
Description
CEVT_BLOB | A CEBLOB structure.
CEVT_BOOL | A Boolean value.
CEVT_FILETIME | A FILETIME structure.
CEVT_I2 | A 16-bit signed integer.
CEVT_I4 | A 32-bit signed integer.
CEVT_LPWSTR | A null-terminated string.
CEVT_R8 | A 64-bit signed interger.
CEVT_UI2 | A 16-bit unsigned integer.
CEVT_UI4 | A 32-bit unsigned integer.

wLenData
Not used.
wFlags
Special flags for the property. It is one of the following values:
Value
Description
CEDB_PROPNOTFOUND | Set by the CeReadRecordProps function if the property was not found.
CEDB_PROPDELETE | If passed to the CeWriteRecordProps function, this flag causes the property to be deleted.

val
Actual value for simple types, or a pointer for strings or Binary Large Objects (BLOBs).

See Also

CeReadRecordProps, CeSeekDatabase, CeWriteRecordProps, HIWORD, LOWORD


CERECORDINFO

This structure contains information about a record object.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef struct _CERECORDINFO {
CEOID oidParent;
} CERECORDINFO;

Members

oidParent
Object identifier of the parent database.

See Also

CEOIDINFO


CEVALUNION

This union contains a value for a property.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.01 and later

Syntax

typedef union _CEVALUNION {
short iVal;
USHORT uiVal;
long lVal;
ULONG ulVal;
FILETIME filetime;
LPWSTR lpwstr;
CEBLOB blob;
BOOL boolVal
 double dblVal
} CEVALUNION;

Members

iVal
Specifies an integer.
uiVal
Specifies an unsigned integer.
lVal
Specifies a long integer.
ulVal
Specifies an unsigned long integer.
filetime
Specifies a FILETIME structure.
lpwstr
Pointer to a null-terminated string.
blob
Specifies a CEBLOB structure.
boolVal
Specifies a BOOL type.
dblVal
Specifies a signed double.

See Also

CEBLOB, FILETIME


CFF_CONVERTOPTIONS

This structure contains information that the ICeFileFilterOptions::SetFilterOptions method uses to set file filter options.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCFF_CONVERTOPTIONS{
ULONG cbSize;
BOOL bNoModalUI;
} CFF_CONVERTOPTIONS;

Members

cbSize
Size of the structure. This value should be initialized by the caller.
bNoModalUI
Boolean that is set to TRUE if the caller wants the converter to suppress all modal UI during the conversion.


CFF_DESTINATIONFILE

This structure contains information about a destination file. A file filter uses the information to write the converted data to the file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCFF_DESTINATIONFILE{
TCHAR szFullpath[_MAX_PATH];
TCHAR szPath[_MAX_PATH];
TCHAR szFilename[_MAX_FNAME];
TCHAR szExtension[_MAX_EXT];
} CFF_DESTINATIONFILE;

Members

szFullpath
Null-terminated string that contains the default full path of the destination file, for example, “C:\Temp\Myfont.fnt”.
szPath
Null-terminated string that contains the path of the directory where the destination file should be created, for example, “C:\Temp”.
szFilename
Null-terminated string that contains only the default name of the destination file. For example, if the destination file name is Myfont.fnt, then the value of szFilename is “Myfont”.
szExtension
Null-terminated string that contains the file name extension of the destination file, for example, “fnt”.

Remarks

The szFullpath and szFilename members are described as default values because the file filter is allowed to modify the name of the destination file. For example, the Font file converter creates “Arial8.fnt” and “Arial10.fnt” from Arial.Ttf when the user selects the 8-point and 10-point font sizes. However, changing file names and creating multiple destination files only works when importing files from the desktop PC to the Windows CE device, and not when exporting files from the Windows CE device to the desktop PC.


CFF_SOURCEFILE

This structure contains information about a source file. A file filter uses the information to locate the source file and read its contents.

At a Glance

Header file: | Replifilt.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCFF_SOURCEFILE {
TCHAR szFullpath[_MAX_PATH];
TCHAR szPath[_MAX_PATH];
TCHAR szFilename[_MAX_FNAME];
TCHAR szExtension[_MAX_EXT];
DWORD cbSize;
FILETIME ftCreated;
FILETIME ftModified;
} CFF_SOURCEFILE;

Members

szFullpath
Null-terminated string that contains the fully qualified path of the source file, for example, “C:\Temp\Myfont.fon”.
szPath
Null-terminated string that contains the path of the directory that contains the source file, for example, “C:\Temp”.
szFilename
Null-terminated string that contains only the name of the source file. For example, if the source file name is Myfont.fon, then the value of szFilename is “Myfont”.
szExtension
Null-terminated string that contains the file name extension of the source file, for example, “fon”.
cbSize
Specifies the size of the source file.
ftCreated
Specifies a FILETIME structure that indicates the time when the source file was created.
ftModified
Specifies a FILETIME structure that indicates the time when the file was last modified.


CHARSETINFO

This structure contains information about a character set.

At a Glance

Header file: | Wingdi.h
Windows CE versions: |

Syntax

typedef struct {
UINT ciCharset;
UNIT ciACP;
FONTSIGNATURE fs;
} CHARSETINFO;

Members

ciCharset
Character set value.
ciACP
ANSI code-page identifier.
fs
FONTSIGNATURE structure that identifies the Unicode and code-page font signature values.

See Also

TranslateCharsetInfo, FONTSIGNATURE


CHOOSECOLOR

This structure contains information the ChooseColor function uses to initialize the Color common dialog box. After a user closes the dialog box, the system uses this structure to return information about the user’s selection.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCHOOSECOLOR {
DWORD lStructSize;
HWND hwndOwner;
HINSTANCE hInstance;
COLORREF rgbResult;
COLORREF *lpCustColors;
DWORD Flags;
LPARAM lCustData;
LPCCHOOKPROC lpfnHook;
LPCTSTR lpTemplateName;
} CHOOSECOLOR, *LPCHOOSECOLOR;

Members

lStructSize
Specifies the length, in bytes, of the structure.
hwndOwner
Handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
hInstance
If the CC_ENABLETEMPLATEHANDLE flag is set in the Flags member, this member is the handle of a memory object that contains a dialog box template. If the CC_ENABLETEMPLATE flag is set, hInstance identifies a module that contains a dialog box template named by the lpTemplateName member. If neither CC_ENABLETEMPLATEHANDLE nor CC_ENABLETEMPLATE is set, this member is ignored.
rgbResult
If the CC_RGBINIT flag is set, this member specifies the color initially selected when the dialog box is created. If the specified color value is not among the available colors, the system selects the nearest solid color available. If rgbResult is zero or CC_RGBINIT is not set, the initially selected color is black. If the user clicks the OK button, rgbResult specifies the user’s color selection.
lpCustColors
Long pointer to an array of 16 COLORREF values that contain red, green, blue (RGB) values for the custom color boxes in the dialog box. If the user modifies these colors, the system updates the array with the new RGB values. To preserve new custom colors between calls to the ChooseColor function, you should allocate static memory for the array.
Flags
Set of bit flags used to initialize the Color common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:
Value
Description
CC_ANYCOLOR | Causes the dialog box to display all available colors in the set of basic colors.
CC_ENABLEHOOK | Enables the hook procedure specified in the lpfnHook member of this structure. This flag is used only to initialize the dialog box.
CC_ENABLETEMPLATE | Indicates that the hInstance and lpTemplateName members specify a dialog box template to use in place of the default template. This flag is used only to initialize the dialog box.
CC_ENABLETEMPLATEHANDLE | Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpTemplateName member if this flag is specified. This flag is used only to initialize the dialog box.
CC_FULLOPEN | Causes the dialog box to display the additional controls that allow the user to create custom colors. If this flag is not set, the user must click the Define Custom Color button to display the custom color controls.
CC_PREVENTFULLOPEN | Disables the Define Custom Colors button.
CC_RGBINIT | Causes the dialog box to use the color specified in the rgbResult member as the initial color selection.
CC_SOLIDCOLOR | Causes the dialog box to display only solid colors in the set of basic colors.

lCustData
Specifies application-defined data that the system passes to the hook procedure identified by the lpfnHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the CHOOSECOLOR structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.
lpfnHook
Long pointer to a CCHookProc hook procedure that can process messages intended for the dialog box. This member is ignored unless the CC_ENABLEHOOK flag is set in the Flags member.
lpTemplateName
Long pointer to a null-terminated string that names the dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard dialog box template. For numbered dialog box resources, lpTemplateName can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the CC_ENABLETEMPLATE flag is set in the Flags member.

See Also

ChooseColor, MAKEINTRESOURCE, WM_INITDIALOG


COAUTHINFO

This structure is used to determine the authentication settings.

At a Glance

Header file: | Wtypes.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _COAUTHINFO {
DWORD dwAuthnSvc;
DWORD dwAuthzSvc;
[string] WCHAR * pwszServerPrincName;
DWORD dwAuthnLevel;
DWORD ddwImpersonationLevel;
AUTH_IDENTITY *pAuthIdentityData;
DWORD dwCapabilities;
} COAUTHINFO;

Members

dwAuthnSvc
[in] Specifies a single DWORD value from the list of RPC_C_AUTHN_xxx constants indicating the authentication service to use. It may be RPC_C_AUTHN_NONE if no authentication is required. RPC_C_AUTHN_WINNT is the default and RPC_C_AUTHN_GSS_KERBEROS is also supported.
dwAuthzSvc
[in] Specifies a single DWORD value from the list of RPC_C_AUTHZ_xxx constants indicating the authorization service to use. If you are using the NT authentication service, use RPC_C_AUTHZ_NONE.
pwszServerPrincName
Pointer to a character string that indicates the server principal name to use with the authentication service. If you are using RPC_C_AUTHN_WINNT, the principal name must be NULL.
dwAuthnLevel
[in] Specifies a single DWORD value from the list of RPC_C_AUTHN_LEVEL_xxx constants indicating the authentication level to use.
dwImpersonationLevel
[in] Specifies the impersonation level to be used. This value must be RPC_C_IMP_LEVEL_IMPERSONATE.
pAuthIdentityData
Pointer to a COAUTHIDENTITY structure that establishes a nondefault client identity. If NULL, the actual identity of the client is used. Values of structure members are authentication-service specific. This value must be NULL if dwAuthnSvc is not NTLMSSP or Kerberos. The form of the COAUTHIDENTITY structure is identical to that of the Windows NT SEC_WINNT_AUTH_IDENTITY structure.
dwCapabilities
[in] Specifies a DWORD defining flags that indicate the further capabilities of this proxy. Currently, this value must be EOAC_NONE.

Remarks

A pointer to a COAUTHINFO structure is a member of the COSERVERINFO structure. The COAUTHINFO structure provides security information to object creation functions across the network. The values of the COAUTHINFO structure determine the authentication settings used while making a remote activation request from the client machine to the server machine.

If pAuthInfo in COSERVERINFO is set to NULL, NTLMSSP with the identity of the actual client will be used. However, a non-NULL COAUTHINFO structure can be specified for pAuthInfo to meet any one of the following special needs:

  • To specify a different client identity for machine remote activations. The specified identity will be used for the launch permission check on the server rather than the real client identity.
  • To specify that Kerberos, rather than NTLMSSP, is used for machine remote activation. A nondefault client identity may or may not be specified.
  • To request unsecure activation.
  • To specify a proprietary authentication service.

Specifying a COAUTHINFO structure allows DCOM activations to work correctly with security providers other than NTLMSSP. You can also specify additional security information used during remote activations for interoperability with alternate implementations of DCOM.

For more information on the uses of COAUTHINFO, see COSERVERINFO.


CONFINFO

This structure is used to retrieve information about two conflicting items. The server uses a dialog box to present this information to the user, who can then choose an option for resolving the conflict.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagConfInfo{
 UINT cbStruct;
HREPLFLD hFolder;
HREPLITEM hLocalItem;
HREPLITEM hRemoteItem;
char szLocalName[ MAX_OBJTYPE_NAME ];
char szLocalDesc[ 512 ];
char szRemoteName[ MAX_OBJTYPE_NAME ];
char szRemoteDesc[ 512 ];
} CONFINFO, *PCONFINFO;

Members

cbStruct
Size of this structure.
hFolder
Handle to the folder where the objects are stored.
hLocalItem
Handle to the local object.
hRemoteItem
Handle to the remote object.
szLocalName
Null-terminated string that contains the name of the local object client would like to show to the user.
szLocalDesc
Null-terminated string that contains the description of the local object client would like to show to the user.
szRemoteName
Null-terminated string that contains the name of the remote object client would like to show to the user.
szRemoteDesc
Null-terminated string that contains the description of the remote object client would like to show to the user.

See Also

IReplStore::GetConflictInfo


CONTEXT

This structure contains processor-specific register data. Currently there are CONTEXT structures defined for Intel, MIPS, Alpha, SHx, ARM, and PowerPC processors. Refer to the WinNT.h header file for definitions of these structures.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Remarks

Windows CE defines an additional CONTEXT structure for SHx and ARM processors which is also found in the WinNT.h header file.


CONTROLINFO

This structure contains parameters that describe a control’s keyboard mnemonics and keyboard behavior.

At a Glance

Header file: | Ocidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCONTROLINFO
{
ULONG cb;
HACCEL hAccel;
USHORT cAccel;
DWORD dwFlags;
} CONTROLINFO;

Members

cb
Size of the CONTROLINFO structure.
hAccel
Handle to an array of Windows ACCEL structures, each structure describing a keyboard mnemonic. The array is allocated with the GlobalAlloc function. The control always maintains the memory for this array; the caller of IOleControl::GetControlInfo should not attempt to free the memory.
cAccel
Number of mnemonics described in the hAccel member. This value can be zero to indicate no mnemonics.
dwFlags
Specifies the keyboard behavior of the control. It is one of the following values:
Value
Description
CTRLINFO_EATS_RETURN | When the control has the focus, it will process the RETURN key.
CTRLINFO_EATS_ESCAPE | When the control has the focus, it will process the ESCAPE key.
When the control has the focus, the dialog box containing the control cannot use the RETURN or ESCAPE keys as mnemonics for the default and cancel buttons.


COPYDATASTRUCT

This structure contains data to be passed to another application by the WM_COPYDATA message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagCOPYDATASTRUCT {
DWORD dwData;
DWORD cbData;
PVOID lpData;
} COPYDATASTRUCT;

Members

dwData
Specifies up to 32 bits of data to be passed to the receiving application.
cbData
Specifies the size, in bytes, of the data pointed to by the lpData member.
lpData
Long pointer to data to be passed to the receiving application. This member can be NULL.

See Also

WM_COPYDATA


COSERVERINFO

This structure is used to identify a remote machine resource to the new or enhanced activation functions.

At a Glance

Header file: | Wtypes.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _COSERVERINFO {
DWORD dwReserved1;
LPWSTR pwszName;
COAUTHINFO *pAuthInfo;
DWORD dwReserved2;
} COSERVERINFO;

Members

dwReserved1
Reserved for future use; set to zero.
pwszName
Pointer to the name of the machine to be used.
pAuthInfo
Set to a pointer to a COAUTHINFO structure to override the default activation security for machine remote activations. Otherwise, set to NULL to indicate that default values should be used. For more information, see the Remarks section.
dwReserved2
Reserved for future use; set to zero.

Remarks

The COSERVERINFO structure is used primarily to identify a remote system in object creation functions. Machine resources are named using the naming scheme of the network transport. By default, all UNC and DNS names names are allowed.

If pAuthInfo is set to NULL, NTLMSSP with the identity of the actual client will be used. To meet any one of the needs in the following list, pAuthInfo can be set to point to a non-NULL COAUTHINFO structure:

  • To specify a different client identity for machine remote activations. The specified identity will be used for the launch permission check on the server rather than the real client identity.
  • To specify that Kerberos, rather than NTLMSSP, is used for machine remote activation. A nondefault client identity may or may not be specified.
  • To request unsecure activation.
  • To specify a proprietary authentication service.

If pAuthInfo is not NULL, those values will be used to specify the authentication settings for the remote call. These settings will be passed to RpcBindingSetAuthInfoEx.

If the pAuthInfo member is not specified, any values in the AppID section of the registry will be used to override the following default authentication settings:

dwAuthnSvc
RPC_C_AUTHN_WINNT
dwAuthzSvc
RPC_C_AUTHZ_NONE
pszServerPrincName
NULL
dwAuthnLevel
RPC_C_AUTHN_LEVEL_CONNECT
dwImpersonationLevel
RPC_C_IMP_LEVEL_IMPERSONATE
pvAuthIdentityData
NULL
dwCapabilities
RPC_C_QOS_CAPABILITIES_DEFAULT


CPINFO

This structure contains information about a code page.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

struct _cpinfo {
UINT MaxCharSize;
BYTE DefaultChar[MAX_DEFAULTCHAR];
BYTE LeadByte[MAX_LEADBYTES];
} CPINFO;

Members

MaxCharSize
Specifies the maximum length, in bytes, of a character in this code page.
DefaultChar
Specifies the default character used in translations into this code page. This character is used by the WideCharToMultiByte function if an explicit default character is not given.
LeadByte
Specifies a fixed-length array of lead-byte ranges, where the number of lead-byte ranges is variable. If there are no lead bytes in this code page, then every element of the array is NULL. If there are lead bytes in this code page, a starting value and ending value is given for each range. Ranges are inclusive. The maximum number of lead-byte ranges for any code page is 5. The array uses two bytes to describe each range, with a double-byte terminating null character after the last range.

Remarks

Lead bytes are unique to double-byte character sets (DBCS). A lead byte is the first byte of a 2-byte character in a DBCS. Lead bytes occupy a specific range of byte values.

See Also

GetCPInfo, WideCharToMultiByte


CPLINFO

This structure contains resource information and a user-defined value for a dialog box supported by a Control Panel application.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagCPLINFO {
int idIcon;
int idName;
int idInfo;
LONG lData;
} CPLINFO;

Members

idIcon
Resource identifier of the icon that represents the dialog box.
idName
Resource identifier of the string that contains the short name for the dialog box. This name is intended to be displayed below the icon.
idInfo
Resource identifier of the string that contains the description for the dialog box that is intended to be displayed when the application icon is selected.
lData
Data defined by the application. When the Control Panel sends the CPL_DBCLK and CPL_STOP messages, it passes this value back to your application.

Remarks

If the icon or display strings of the dialog box can change based on the state of the computer, you can specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings. Using this technique is significantly slower, however, because the Control Panel will need to load your application each time it sends the CPL_NEWINQUIRE message.

See Also

CPL_NEWINQUIRE, NEWCPLINFO


CREATE_PROCESS_DEBUG_INFO

This structure contains process creation information that can be used by a debugger.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _CREATE_PROCESS_DEBUG_INFO {
HANDLE hFile;
HANDLE hProcess;
HANDLE hThread;
LPVOID lpBaseOfImage;
DWORD dwDebugInfoFileOffset;
DWORD nDebugInfoSize;
LPVOID lpThreadLocalBase;
LPTHREAD_START_ROUTINE lpStartAddress;
LPVOID lpImageName;
WORD fUnicode;
} CREATE_PROCESS_DEBUG_INFO;

Members

hFile
Handle to the process’s image file. In Windows CE, this member is always NULL.
hProcess
Handle to the process. If this member is NULL, the handle is not valid. Otherwise, the debugger can use the member to read from and write to the process’s memory.
hThread
Handle to the initial thread of the process identified by the hProcess member. If hThread is NULL, the handle is not valid. Otherwise, the debugger has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread, allowing the debugger to read from and write to the registers of the thread and to control execution of the thread.
lpBaseOfImage
Pointer to the base address of the executable image that the process is running.
dwDebugInfoFileOffset
Specifies the offset to the debugging information in the file identified by the hFile member. This member is always set to zero.
nDebugInfoSize
Specifies the size, in bytes, of the debugging information in the file. This member is always set to zero.
lpThreadLocalBase
Pointer to a block of data. At offset 0x2C into this block is another pointer, called ThreadLocalStoragePointer, that points to an array of per-module thread local storage blocks. This gives a debugger access to per-thread data in the threads of the process being debugged using the same algorithms that a compiler would use.
lpStartAddress
Pointer to the starting address of the thread. This value may only be an approximation of the thread’s starting address, because any application with appropriate access to the thread can change the thread’s context by using the SetThreadContext function.
lpImageName
Pointer to the file name associated with the hFile member. This member may be NULL, or it may contain the address of a string pointer in the address space of the process being debugged. That address may, in turn, either be NULL or point to the actual filename. If fUnicode is a nonzero value, the name string is Unicode; otherwise, it is ANSI.

This member is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL or *lpImageName (in the address space of the process being debugged) is NULL. Specifically, the system does not provide an image name for a create process event, and will not likely pass an image name for the first DLL event. The system also does not provide this information in the case of debug events that originate from a call to the DebugActiveProcess function.

fUnicode
Indicates whether a file name specified by the lpImageName member is Unicode or ANSI. A nonzero value indicates Unicode; zero indicates ANSI.

Remarks

The lpImageName member is a pointer into the address space of the process that is being debugged. To retrieve the actual image name, use the ReadProcessMemory function in the following manner.

ReadProcessMemory( hProcess, lpImageName, lpBuffer, nSize,
   &NumberOfBytesRead );

For the DebugActiveProcess function, if the dwDebugEventCode member of the DEBUG_EVENT structure has a value of CREATE_PROCESS_DEBUG_EVENT or CREATE_THREAD_DEBUG_EVENT, the lpStartAddress member is NULL.

The lpThreadLocalBase member points directly to the Thread Local Storage (TLS) data block of the process that is being debugged. To obtain the TLS data for a slot, call the ReadProcessMemory function and pass the following calculated value for the lpBaseAddress parameter: lpThreadLocalBase+4*<slot number>.

See Also

CREATE_PROCESS_DEBUG_INFO, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO, ReadProcessMemory, SetThreadContext


CREATESTRUCT

This structure defines the initialization parameters passed to the window procedure of an application.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagCREATESTRUCT {
LPVOID lpCreateParams;
HINSTANCE hInstance;
HMENU hMenu;
HWND hwndParent;
int cy;
int cx;
int y;
int x;
LONG style;
LPCTSTR lpszName;
LPCTSTR lpszClass;
DWORD dwExStyle;
} CREATESTRUCT;

Members

lpCreateParams
Long pointer to additional data that can be used to create the window. If the window is being created as a result of a call to the CreateWindow or CreateWindowEx function, this member contains the value of the lpParam parameter specified in the function call.

If the window being created is an MDI window, this member contains a pointer to an MDICREATESTRUCT structure.

Windows NT: If the window is being created from a dialog template, this member is the address of a SHORT value that specifies the size, in bytes, of the window creation data. The value is immediately followed by the creation data. For more information, see the following Remarks section.

hInstance
Handle to the module that owns the new window.
hMenu
Handle to the menu to be used by the new window.
hwndParent
Handle to the parent window, if the window is a child window. If the window is owned, this member identifies the owner window. If the window is not a child or owned window, this member is NULL.
cy
Specifies the height of the new window, in pixels.
cx
Specifies the width of the new window, in pixels.
y
Specifies the y-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.
x
Specifies the x-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.
style
Specifies the style for the new window.
lpszName
Long pointer to a null-terminated string that specifies the name of the new window.
lpszClass
Long pointer to a null-terminated string that specifies the class name of the new window.
dwExStyle
Specifies the extended style for the new window.

Remarks

You should access the data represented by the lpCreateParams member using a pointer that has been declared using the UNALIGNED type, because the pointer may not be DWORD aligned. This is demonstrated in the following code example:

typedef struct tagMyData
{
 // Define creation data here.
} MYDATA;

typedef struct tagMyDlgData
{
 SHORT cbExtra;
 MYDATA myData;
} MYDLGDATA, UNALIGNED *PMYDLGDATA;

PMYDLGDATA pMyDlgdata =
 (PMYDLGDATA) (((LPCREATESTRUCT) lParam)->lpCreateParams);

See Also

CreateWindow, CreateWindowEx


CREATE_THREAD_DEBUG_INFO

This structure contains thread-creation information that can be used by a debugger.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _CREATE_THREAD_DEBUG_INFO {
HANDLE hThread;
LPVOID lpThreadLocalBase;
LPTHREAD_START_ROUTINE lpStartAddress;
} CREATE_THREAD_DEBUG_INFO;

Members

hThread
Handle to the thread whose creation caused the debugging event. If this member is NULL, the handle is not valid. Otherwise, the debugger has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread, allowing the debugger to read from and write to the registers of the thread and control execution of the thread.
lpThreadLocalBase
Pointer to a block of data. At offset 0x2C into this block is another pointer, called ThreadLocalStoragePointer, that points to an array of per-module thread local storage blocks. This gives a debugger access to per-thread data in the threads of the process being debugged using the same algorithms that a compiler would use.
lpStartAddress
Pointer to the starting address of the thread. This value may only be an approximation of the thread's starting address, because any application with appropriate access to the thread can change the thread's context by using the SetThreadContext function.

See Also

CREATE_PROCESS_DEBUG_INFO, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO, SetThreadContext


CURRENCYFMT

This structure contains information that defines the format of a currency string. The GetCurrencyFormat function uses this information to customize a currency string for a specified locale.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _currencyfmt {
UINT NumDigits;
UINT LeadingZero;
UINT Grouping;
LPTSTR lpDecimalSep;
LPTSTR lpThousandSep;
UINT NegativeOrder;
UINT PositiveOrder;
LPTSTR lpCurrencySymbol;
} CURRENCYFMT;

Members

NumDigits
Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.
LeadingZero
Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.
Grouping
Specifies the size of each group of digits to the left of the decimal. Values in the range 0 – 9 are valid.
lpDecimalSep
Pointer to a null-terminated decimal separator string.
lpThousandSep
Pointer to a null-terminated thousand separator string.
NegativeOrder
Specifies the negative currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGCURR.
PositiveOrder
Specifies the positive currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ICURRENCY.
lpCurrencySymbol
Pointer to a null-terminated currency symbol string.

See Also

GetCurrencyFormat


CUSTDATA

This structure is used for retrieving custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCUSTDATA {
DWORD cCustData;
LPCUSTDATAITEM prgCustData;
} CUSTDATA, *LPCUSTDATA;

Members

cCustData
Number of custom data items in prgCustData.
prgCustData
Pointer to an array of custom data items.


CUSTDATAITEM

This structure is used for holding custom data.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagCUSTDATAITEM {
GUID guid;
VARIANTARG varValue;
} CUSTDATAITEM, *LPCUSTDATAITEM;

Members

guid
Globally unique identifier (GUID) for this data item.
varValue
Value of this data item.


DEBUG_EVENT

This structure describes a debugging event.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _DEBUG_EVENT {
DWORD dwDebugEventCode;
DWORD dwProcessId;
DWORD dwThreadId;
union {
EXCEPTION_DEBUG_INFO Exception;
CREATE_THREAD_DEBUG_INFO CreateThread;
CREATE_PROCESS_DEBUG_INFO CreateProcessInfo;
EXIT_THREAD_DEBUG_INFO ExitThread;
EXIT_PROCESS_DEBUG_INFO ExitProcess;
LOAD_DLL_DEBUG_INFO LoadDll;
UNLOAD_DLL_DEBUG_INFO UnloadDll;
OUTPUT_DEBUG_STRING_INFO DebugString;
RIP_INFO RipInfo;
} u;
} DEBUG_EVENT;

Members

dwDebugEventCode
Specifies a debugging event code that identifies the type of debugging event. It is one of the following values:
Value
Description
EXCEPTION_DEBUG_EVENT | Reports an exception debugging event. The value of u.Exception specifies an EXCEPTION_DEBUG_INFO structure.
CREATE_THREAD_DEBUG_EVENT | Reports a create-thread debugging event. The value of u.CreateThread specifies a CREATE_THREAD_DEBUG_INFO structure.
CREATE_PROCESS_DEBUG_EVENT | Reports a create-process debugging event. The value of u.CreateProcessInfo specifies a CREATE_PROCESS_DEBUG_INFO structure.
EXIT_THREAD_DEBUG_EVENT | Reports an exit-thread debugging event. The value of u.ExitThread specifies an EXIT_THREAD_DEBUG_INFO structure.
EXIT_PROCESS_DEBUG_EVENT | Reports an exit-process debugging event. The value of u.ExitProcess specifies an EXIT_PROCESS_DEBUG_INFO structure.
LOAD_DLL_DEBUG_EVENT | Reports a load-dynamic-link-library (DLL) debugging event. The value of u.LoadDll specifies a LOAD_DLL_DEBUG_INFO structure.
UNLOAD_DLL_DEBUG_EVENT | Reports an unload-DLL debugging event. The value of u.UnloadDll specifies an UNLOAD_DLL_DEBUG_INFO structure.
OUTPUT_DEBUG_STRING_EVENT | Reports an output-debugging-string debugging event. The value of u.DebugString specifies an OUTPUT_DEBUG_STRING_INFO structure.

dwProcessId
Specifies the identifier of the process in which the debugging event occurred. A debugger uses this value to locate the debugger’s per-process structure. These values are not necessarily small integers that can be used as table indices.
dwThreadId
Specifies the identifier of the thread in which the debugging event occurred. A debugger uses this value to locate the debugger’s per-thread structure. These values are not necessarily small integers that can be used as table indices.
u
Specifies additional information relating to the debugging event. This union takes on the type and value appropriate to the type of debugging event, as described in the dwDebugEventCode member.

Remarks

If the WaitForDebugEvent function succeeds, it fills in the members of a DEBUG_EVENT structure.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, EXIT_PROCESS_DEBUG_INFO, EXIT_THREAD_DEBUG_INFO, EXCEPTION_DEBUG_INFO, LOAD_DLL_DEBUG_INFO, OUTPUT_DEBUG_STRING_INFO, UNLOAD_DLL_DEBUG_INFO, WaitForDebugEvent


DELETEITEMSTRUCT

This structure describes a deleted list box or combo box item. The lParam parameter of a WM_DELETEITEM message contains a pointer to this structure. When an item is removed from a list box or combo box or when a list box or combo box is destroyed, Windows sends the WM_DELETEITEM message to the owner for each deleted item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagDELETEITEMSTRUCT (
UINT CtlType;
UINT CtlID;
UINT itemID;
HWND hwndItem;
UINT itemData;
} DELETEITEMSTRUCT;

Members

CtlType
Specifies whether the item was deleted from a list box or a combo box. It is one of the following values:
Value
Description
ODT_LISTBOX | Item was deleted from a list box.
ODT_COMBOBOX | Item was deleted from a combo box.

CtlID
Specifies the identifier of the list box or combo box.
itemID
Index of the item in the list box or combo box being removed.
hwndItem
Handle to the control.
itemData
Specifies application-defined data for the item. This value is passed to the control in the lParam parameter of the message that adds the item to the list box or combo box.

See Also

WM_DELETEITEM


DEVINFO

This structure is used to store information about a device.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagDevInfo {
DWORD pid;
char szName[ MAX_PATH];
char szType[ 80 ];
char szPath[ MAX_PATH ]
} DEVINFO, *PDEVINFO;

Members

pid
Pointer to the device identifier.
szName
Null-terminated string that contains the name of the device.
szType
Null-terminated string that contains the type of the device.
szPath
Null-terminated string that contains the path of the device.


DEVNAMES

This structure contains strings that identify the driver, device, and output port names for a printer. The PageSetupDlg function uses these strings to initialize the system-defined Print property sheet or Print dialog box. When the user closes the property sheet or dialog box, information about the selected printer is returned in this structure.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagDEVNAMES {
WORD wDriverOffset;
WORD wDeviceOffset;
WORD wOutputOffset;
WORD wDefault;
} DEVNAMES;

Members

wDriverOffset
(In/Out) Specifies the offset in bytes from the beginning of this structure to a null-terminated string that contains the file name (without the extension) of the device driver. On input, this string is used to determine the printer to display initially in the dialog box.
wDeviceOffset
(In/Out) Specifies the offset in bytes from the beginning of this structure to the null-terminated string that contains the name of the device.
wOutputOffset
(In/Out) Specifies the offset in bytes from the beginning of this structure to the null-terminated string that contains the device name for the physical output medium (output port).
wDefault
(In/Out) Specifies whether the strings contained in the DEVNAMES structure identify the default printer. This string is used to verify that the default printer has not changed since the last print operation. If any of the strings do not match, a warning message is displayed informing the user that the document may need to be reformatted.

On output, the wDefault member is changed only if the Print Setup dialog box was displayed and the user chose the OK button. The DN_DEFAULTPRN flag is used if the default printer was selected. If a specific printer is selected, the flag is not used. All other flags in this member are reserved for internal use by the dialog box procedure for the Print property sheet or Print dialog box.

Remarks

The PageSetupDlg function fills this structure with byte offsets rather than character offsets.

See Also

DEVMODE, PageSetupDlg, PAGESETUPDLG


DISPPARAMS

This structure is used by IDispatch::Invoke to contain the arguments passed to a method or property.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagDISPPARAMS {
VARIANTARG FAR *rgvarg;
DISPID FAR *rgdispidNameArgs;
unsigned int cArgs;
unsigned int cNamedArgs;
} DISPPARAMS;

Members

rgvarg
Array of arguments.
rgdispidNamedArgs
Dispatch identifiers of named arguments.
cArgs
Number of arguments.
cNamedArgs
Number of named arguments.


DLGITEMTEMPLATE

This structure defines the dimensions and style of a control in a dialog box. One or more of these structures are combined with a DLGTEMPLATE structure to form a dialog box template.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct {
DWORD style;
DWORD dwExtendedStyle;
short x;
short y;
short cx;
short cy;
WORD id;
} DLGITEMTEMPLATE;

Members

style
Specifies the style of the control. This member can be a combination of window style values (such as WS_BORDER) and one or more of the control style values (such as BS_PUSHBUTTON and ES_LEFT).
dwExtendedStyle
Specifies extended styles for a window. This member is not used to create controls in dialog boxes, but applications that use dialog box templates can use it to create other types of windows.
x
Specifies the x-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box’s client area.
y
Specifies the y-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box’s client area.
cx
Specifies the width, in dialog box units, of the control.
cy
Specifies the height, in dialog box units, of the control.
id
Specifies the control identifier.

Remarks

In a standard template for a dialog box, the DLGITEMTEMPLATE structure is always immediately followed by three variable-length arrays specifying the class, title, and creation data for the control. Each array consists of one or more 16-bit elements.

Each DLGITEMTEMPLATE structure in the template must be aligned on a DWORD boundary. The class and title arrays must be aligned on WORD boundaries. The creation data array must be aligned on a WORD boundary.

Immediately following each DLGITEMTEMPLATE structure is a class array that identifies the window class of the control. If the first element of this array is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system class. The ordinal can be one of the atom values shown in the following table.

Value
Description
0x0080 | Button
0x0081 | Edit
0x0082 | Static
0x0083 | List box
0x0084 | Scroll bar
0x0085 | Combo box

Following the class array is a title array that contains the initial text or resource identifier of the control. If the first element of this array is 0xFFFF, the array has one additional element that specifies an ordinal value of a resource, such as an icon, in an executable file. You can use a resource identifier for controls, such as static icon controls, that load and display an icon or other resource rather than text. If the first element is any value other than 0xFFFF, the system treats the array as a null-terminated Unicode string that specifies the initial text.

The creation data array begins at the next WORD boundary after the title array. This creation data can be of any size and format. If the first word of the creation data array is nonzero, it indicates the size, in bytes, of the creation data (including the size word). The control’s window procedure must be able to interpret the data. When the system creates the control, it passes a pointer to this data in the lParam parameter of the WM_CREATE message that it sends to the control.

If you specify character strings in the class and title arrays, you must use Unicode strings. To create code that works on both Windows 95/98 and Windows NT, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam


DRAWITEMSTRUCT

This structure provides information the owner window must have to determine how to paint an owner-drawn control or menu item. The owner window of the owner-drawn control or menu item receives a pointer to this structure as the lParam parameter of the WM_DRAWITEM message.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagDRAWITEMSTRUCT {
UINT CtlType;
UINT CtlID;
UINT itemID;
UINT itemAction;
UINT itemState;
HWND hwndItem;
HDC hDC;
RECT rcItem;
DWORD itemData;
} DRAWITEMSTRUCT;

Members

CtlType
Specifies the control type. It is one of the following values:
Value
Description
ODT_BUTTON | Owner-drawn button
ODT_LISTVIEW | List view control
ODT_MENU | Owner-drawn menu item
ODT_TAB | Tab control

CtlID
Specifies the identifier of the combo box, list box, button, or static control. This member is not used for a menu item.
itemID
Specifies the menu item identifier for a menu item or the index of the item in a list box or combo box. For an empty list box or combo box, this member can be –1. This allows the application to draw only the focus rectangle at the coordinates specified by the rcItem member even though there are no items in the control. This indicates to the user whether the list box or combo box has the focus. How the bits are set in the itemAction member determines whether the rectangle is to be drawn as though the list box or combo box has the focus.
itemAction
Specifies the drawing action required. It can be one or more of the following values:
Value
Description
ODA_DRAWENTIRE | The entire control needs to be drawn.
ODA_FOCUS | The control has lost or gained the keyboard focus. The itemState member should be checked to determine whether the control has the focus.
ODA_SELECT | The selection status has changed. The itemState member should be checked to determine the new selection state.

itemState
Specifies the visual state of the item after the current drawing action takes place. It can be a combination of the following values:
Value
Description
ODS_CHECKED | The menu item is to be checked. This bit is used only in a menu.
ODS_DEFAULT | The item is the default item.
ODS_DISABLED | The item is to be drawn as disabled.
ODS_FOCUS | The item has the keyboard focus.
ODS_GRAYED | The item is to be grayed. This bit is used only in a menu.
ODS_SELECTED | The menu item’s status is selected.

hwndItem
Handle to the control for combo boxes, list boxes, buttons, and static controls. For menus, this member identifies the menu containing the item.
hDC
Handle to a device context; this device context must be used when performing drawing operations on the control.
rcItem
Specifies a rectangle that defines the boundaries of the control to be drawn. This rectangle is in the device context specified by the hDC member. The system automatically clips anything the owner window draws in the device context for combo boxes, list boxes, and buttons, but does not clip menu items. When drawing menu items, the owner window must not draw outside the boundaries of the rectangle defined by the rcItem member.
itemData
Specifies the application-defined 32-bit value associated with the menu item. For a control, this member specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LBS_HASSTRINGS or CBS_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value that was passed to the list box or combo box in the lParam parameter of one of the following messages:
  • CB_ADDSTRING
  • CB_INSERTSTRING
  • LB_ADDSTRING
  • LB_INSERTSTRING

If ctlType is ODT_BUTTON or ODT_STATIC, itemData is zero.

Remarks

Windows CE does not support owner–drawn combo boxes and list boxes.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA, LB_ADDSTRING, LB_INSERTSTRING, WM_DRAWITEM


DVEXTENTINFO

This structure is used to provide sizing hints from the container for the object to use as the user resizes it.

At a Glance

Header file: | Ocidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagDVEXTENTINFO{
ULONG cb;
DWORD dwExtentMode;
SIZEL sizelProposed;
} DVEXTENTINFO;

Members

cb
Size of the structure, in bytes. The size includes this member as well as the dwExtentMode and sizelProposed members.
dwExtentMode
Indicates whether the sizing mode is content or integral sizing.
sizelProposed
Specifies the proposed size in content sizing or the preferred size in integral sizing.


DVTARGETDEVICE

This structure is used to specify information about the target device for which data is being composed.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagDVTARGETDEVICE{
DWORD tdSize;
WORD tdDriverNameOffset;
WORD tdDeviceNameOffset;
WORD tdPortNameOffset;
WORD tdExtDevmodeOffset;
BYTE tdData;
} DVTARGETDEVICE;

Members

tdSize
Size, in bytes, of the DVTARGETDEVICE structure. The initial size is included so the structure can be copied more easily.
tdDriverNameOffset
Offset, in bytes, from the beginning of the structure to the device driver name, which is stored as a null-terminated string in the tdData buffer.
tdDeviceNameOffset
Offset, in bytes, from the beginning of the structure to the device name, which is stored as a null-terminated string in the tdData buffer. This value can be zero to indicate no device name.
tdPortNameOffset
Offset, in bytes, from the beginning of the structure to the port name, which is stored as a null-terminated string in the tdData buffer. This value can be zero to indicate no port name.
tdExtDevmodeOffset
Offset, in bytes, from the beginning of the structure to the DEVMODE structure retrieved by calling ExtDeviceMode.
tdData
Array of bytes containing data for the target device. It is not necessary to include empty strings in tdData (for names where the offset value is zero).

Remarks

Some OLE 1 client applications incorrectly construct target devices by allocating too few bytes in the DEVMODE structure for the OLETARGETDEVICE. They typically only supply the number of bytes in the DEVMODE.dmSize member. The number of bytes to be allocated should be the sum of DEVMODE.dmSize + DEVMODE.dmDriverExtra. When a call is made to the CreateDC function with an incorrect target device, the printer driver tries to access the additional bytes and unpredictable results can occur. To protect against a crash and make the additional bytes available, OLE pads the size of OLE 2 target devices created from OLE 1 target devices.


ELEMDESC

This structure is used for holding the type description and process transfer information for a variable, a function, or a function parameter.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagELEMDESC {
TYPEDESC tdesc;
union {
IDLDESC idldesc;
PARAMDESC paramdesc;
};
} ELEMDES, *LPELEMDESC;

Members

tdesc
Type of the element.
idldesc
Information for remoting the element; provides backward compatibility.
paramdesc
Information about the parameter.


EXCEPINFO

This structure describes an exception that occurred during IDispatch::Invoke.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagEXCEPINFO {
unsigned short wCode;
unsigned short wReserved;
BSTR bstrSource;
BSTR bstrDescription;
BSTR bstrHelpFile;
unsigned long dwHelpContext;
void FAR *pvReserved;
HRESULT (STDAPICALLTYPE FAR *pfnDeferredFillIn)
(struct tagEXCEPINFO FAR *);
SCODE scode;
} EXCEPINFO;

Members

wCode
Code that identifies the error. Error codes should be greater than 1000. Either this member or the return value member must be filled in; the other must be set to 0.
wReserved
Reserved; set to 0.
bstrSource
Unicode string that contains the textual, human-readable name of the source of the exception. Typically, this is an application name. This member should be filled in by the implementor of IDispatch.
bstrDescription
Unicode string that contains the textual, human-readable description of the error intended for the customer. If no description is available, use NULL.
bstrHelpFile
Unicode string that contains the fully qualified drive, path, and file name of a Help file with more information about the error. If no Help is available, use NULL.
dwHelpContext
Specifies the Help context identifier of the topic within the Help file. This member should be filled in if and only if the bstrHelpFile member is not NULL.
pvReserved
Reserved; set to NULL.
pfnDeferredFillIn
Pointer to a function that takes an EXCEPINFO structure as an argument and returns an HRESULT value. If deferred, fill-in is not desired, this member should be set to NULL.
scode
Return value describing the error. Either this member or wCode (but not both) must be filled in; the other must be set to 0. For use with 16-bit versions only.

Remarks

Use the pfnDeferredFillIn member to allow an object to defer filling in the bstrDescription, bstrHelpFile, and dwHelpContext members until they are needed. This member might be used, for example, if loading the string for the error is a time-consuming operation. To use deferred fill-in, the object puts a function pointer in this slot and does not fill any of the other members except wCode, which is required.

To get additional information, the caller passes the EXCEPINFO structure back to the pexcepinfo callback function, which fills in the additional information. When the ActiveX object and the ActiveX client are in different processes, the ActiveX object calls pfnDeferredFillIn before returning to the controller.


EXCEPTION_DEBUG_INFO

This structure contains exception information that can be used by a debugger.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _DEBUG_EVENT {
typedef struct _EXCEPTION_DEBUG_INFO {
EXCEPTION_RECORD ExceptionRecord;
DWORD dwFirstChance;
} EXCEPTION_DEBUG_INFO;

Members

ExceptionRecord
Contains an EXCEPTION_RECORD structure with information specific to the exception. This includes the exception code, flags, address, a pointer to a related exception, extra parameters, and so on.
dwFirstChance
Indicates whether the debugger has previously encountered the exception specified by the ExceptionRecord member. If the dwFirstChance member is nonzero, this is the first time the debugger has encountered the exception. Debuggers typically handle breakpoint and single-step exceptions when they are first encountered. If this member is zero, the debugger has previously encountered the exception. This occurs only if, during the search for structured exception handlers, either no handler was found or the exception was continued.

See Also

DEBUG_EVENT, EXCEPTION_RECORD


EXCEPTION_POINTERS

This structure contains an exception record with a machine-independent description of an exception and a context record with a machine-dependent description of the processor context at the time of the exception.

At a Glance

Header file: | Excpt.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _EXCEPTION_POINTERS {
PEXCEPTION_RECORD ExceptionRecord;
PCONTEXT ContextRecord;
} EXCEPTION_POINTERS;

Members

ExceptionRecord
Pointer to an EXCEPTION_RECORD structure that contains a machine-independent description of the exception.
ContextRecord
Pointer to a CONTEXT structure that contains a processor-specific description of the state of the processor at the time of the exception.

See Also

GetExceptionInformation, CONTEXT, EXCEPTION_RECORD


EXCEPTION_RECORD

This structure describes an exception.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _EXCEPTION_RECORD {
DWORD ExceptionCode;
DWORD ExceptionFlags;
struct _EXCEPTION_RECORD *ExceptionRecord;
PVOID ExceptionAddress;
DWORD NumberParameters;
DWORD ExceptionInformation[EXCEPTION_MAXIMUM_PARAMETERS];
} EXCEPTION_RECORD;

Members

ExceptionCode
Specifies the reason the exception occurred. This is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception. Following are the exception codes likely to occur due to common programming errors:
Value
Description
EXCEPTION_ACCESS_VIOLATION | The thread tried to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED | The thread tried to access an array element that is out of bounds and the underlying hardware supports bounds checking.
EXCEPTION_BREAKPOINT | A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT | The thread tried to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries; 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_FLT_DENORMAL_OPERAND | One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO | The thread tried to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT | The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION | This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW | The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK | The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW | The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_ILLEGAL_INSTRUCTION | The thread tried to execute an invalid instruction.
EXCEPTION_IN_PAGE_ERROR | The thread tried to access a page that was not present, and the system was unable to load the page. For example, this exception might occur if a network connection is lost while running a program over the network.
EXCEPTION_INT_DIVIDE_BY_ZERO | The thread tried to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW | The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_INVALID_DISPOSITION | An exception handler returned an invalid disposition to the exception dispatcher. Programmers using a high-level language such as C should never encounter this exception.
EXCEPTION_NONCONTINUABLE_EXCEPTION | The thread tried to continue execution after a noncontinuable exception occurred.
EXCEPTION_PRIV_INSTRUCTION | The thread tried to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_SINGLE_STEP | A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_STACK_OVERFLOW | The thread used up its stack.

Another exception code is likely to occur when debugging console processes. It does not arise because of a programming error. The DBG_CONTROL_C exception code occurs when CTRL+C is input to a console process that handles CTRL+C signals and is being debugged. This exception code is not meant to be handled by applications. It is raised only for the benefit of the debugger, and is raised only when a debugger is attached to the console process.

ExceptionFlags
Specifies the exception flags. This member can be either zero, indicating a continuable exception, or EXCEPTION_NONCONTINUABLE indicating a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.
ExceptionRecord
Pointer to an associated EXCEPTION_RECORD structure. Exception records can be chained together to provide additional information when nested exceptions occur.
ExceptionAddress
Specifies the address where the exception occurred.
NumberParameters
Specifies the number of parameters associated with the exception. This is the number of defined elements in the ExceptionInformation array.
ExceptionInformation
Specifies an array of additional 32-bit arguments that describe the exception. The RaiseException function can specify this array of arguments. For most exception codes, the array elements are undefined. For the following exception code, the array elements are defined as follows:
Value
Description
EXCEPTION_ACCESS_VIOLATION The first element of the array contains a read-write flag that indicates the type of operation that caused the access violation. If this value is zero, the thread attempted to read the inaccessible data. If this value is 1, the thread attempted to write to an inaccessible address.
The second array element specifies the virtual address of the inaccessible data.

See Also

EXCEPTION_POINTERS, GetExceptionInformation, RaiseException


EXIT_PROCESS_DEBUG_INFO

This structure contains an exiting process’s exit code.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _EXIT_PROCESS_DEBUG_INFO {
DWORD dwExitCode;
} EXIT_PROCESS_DEBUG_INFO;

Members

dwExitCode
Specifies the exit code for the process.

See Also

DEBUG_EVENT


EXIT_THREAD_DEBUG_INFO

This structure contains an exiting thread’s exit code.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _EXIT_THREAD_DEBUG_INFO {
DWORD dwExitCode;
} EXIT_THREAD_DEBUG_INFO;

Members

dwExitCode
Specifies the exit code for the thread.

See Also

DEBUG_EVENT


FILETIME

This structure is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _FILETIME { // ft
DWORD dwLowDateTime;
DWORD dwHighDateTime;
} FILETIME;

Members

dwLowDateTime
Specifies the low 32 bits of the Win32 date/time value.
dwHighDateTime
Specifies the upper 32 bits of the Win32 date/time value.

Remarks

The FILETIME data structure is used in the time conversion functions between MS-DOS and Win32.

See Also

CompareFileTime, FileTimeToLocalFileTime, FileTimeToSystemTime, GetFileTime, LocalFileTimeToFileTime, SetFileTime, SystemTimeToFileTime


FONTSIGNATURE

This structure contains information identifying the code pages and Unicode subranges for which a specified font provides glyphs.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagFONTSIGNATURE {
DWORD fsUsb[4];
DWORD fsCsb [2];
} FONTSIGNATURE;

Members

fsUsb
Specifies a 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant bit is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard.
fsCsb
Specifies a 64-bit code-page bitfield (CPB) that identifies a specific character set or code page. Code pages are in the lower 32 bits of this bitfield. The high 32 are used for non-Windows code pages.

Remarks

The graphics device interface (GDI) relies on Windows code pages fitting within a 32-bit value. Furthermore, the highest two bits within this value are reserved for GDI internal use and may not be assigned to code pages.

See Also

TranslateCharsetInfo, CHARSETINFO


FORMATETC

This structure is a generalized clipboard format, enhanced to encompass a target device, the aspect, or view of the data, and a storage medium.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagFORMATETC {
unsigned long cfFormat;
DVTARGETDEVICE * ptd;
unsigned long dwAspect;
long lindex;
unsigned long tymed;
} FORMATETC, * LPFORMATETC;

Members

cfFormat
Particular clipboard format of interest. There are three types of formats recognized by OLE:
  • Standard interchange formats, such as CF_TEXT.
  • Private application formats understood only by the application offering the format, or by other applications offering similar features.
  • OLE formats, which are used to create linked or embedded objects.
ptd
Pointer to a DVTARGETDEVICE structure containing information about the target device for which the data is being composed. A NULL value is used whenever the specified data format is independent of the target device or when the caller doesn’t care what device is used. In the latter case, if the data requires a target device, the object should pick an appropriate default device (often the display for visual components). Data obtained from an object with a NULL target device, such as most metafiles, is independent of the target device. The resulting data is usually the same as it would be if the user chose the Save As command from the File menu and selected an interchange format.
dwAspect
Specifies one of the DVASPECT enumeration constants that indicate how much detail should be contained in the rendering. A single clipboard format can support multiple aspects or views of the object. Most data and presentation transfer and caching methods pass aspect information. For example, a caller might request an object’s iconic picture, using the metafile clipboard format to retrieve it. Note that only one DVASPECT value can be used in dwAspect. That is, dwAspect cannot be the result of a BOOLEAN OR operation on several DVASPECT values.
lindex
Part of the aspect when the data must be split across page boundaries. The most common value is –1, which identifies all of the data. For the aspects DVASPECT_THUMBNAIL and DVASPECT_ICON, lindex is ignored.
tymed
One of the TYMED enumeration constants which indicate the type of storage medium used to transfer the object’s data. Data can be transferred using whatever medium makes sense for the object. For example, data can be passed using global memory, a disk file, or structured storage objects. For more information, see the TYMED enumeration.

Remarks

The FORMATETC structure is used by methods in the data transfer and presentation interfaces as a parameter specifying the data being transferred.

Windows CE does not support the CF_ENHMETAFILE or CF_METAFILEPICT values in the cfFormat member.

See Also

TYMED


FSD_BUFFER_INFO

This structure contains information on a buffer.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _FSD_BUFFER_INFO{
PBYTE pBuffer;
DWORD cbBuffer
} FSD_BUFFER_INFO, *PFBI;

Members

pBuffer
Pointer to a buffer.
cbBuffer
Size of the buffer, in bytes.

Remarks

This structure is used in FSD_SCATTER_GATHER_INFO to point to the buffers where the data is stored—if read from disk—or read from—if data is written to disk. You can have multiple FSD_BUFFER_INFO structures, but they must be contiguous and the pfbi member of the FSD_SCATTER_GATHER_INFO structure must point to the first FSD_BUFFER_INFO structure.

See Also

FSD_SCATTER_GATHER_INFO


FSD_DISK_INFO

This structure has information about a disk.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _FSD_DISK_INFO{
DWORD cSectors;
DWORD cbSector;
DWORD cCylinders;
DWORD cHeadsPerCylinder;
DWORD cSectorsPerTrack;
DWORD dwFlags
} FSD_DISK_INFO, *PFDI;

Members

cSectors
Number of sectors on the disk.
cbSector
Number of bytes in the sector.
cCylinders
Number of cylinders on the disk.
cHeadsPerCylinder
Number of heads per cylinder.
cSectorsPerTrack
Number of sectors per track.
dwFlags
Bitmask of flags used to specify the diagnostics for the disk. It is one of the following:
Flag
Hex value
Description
FDI_MBR | 0x00000001 | Device type has or needs a master block record (MBR).
FDI_CHS_UNCERTAIN | 0x00000002 | Driver-generated checksum values are suspect.
FDI_UNFORMATTED | 0x00000004 | Low-level format is needed for this disk. A DISK_IOCTL_FORMAT_MEDIA message must be sent to the device driver.
FDI_PAGEABLE | 0x00000008 | Device can be used for demand paging.
FDI_READONLY | 0x00000010 | Device is read-only.
FDI_RESERVED | 0xffffffe0 | Reserved.

Remarks

This structure is returned by FSDMGR_GetDiskInfo.

See Also

FSDMGR_GetDiskInfo


FSD_SCATTER_GATHER_INFO

This structure contains information on the data to be read from or written to the mounted volume.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _FSD_SCATTER_GATHER_INFO{
DWORD dwFlags;
DWORD idDsk;
DWORD dwSector;
DWORD cSectors;
PFDI pfdi;
DWORD cfbi;
 PFBI pfbi;
PFNFSG pfnCallBack
} FSD_SCATTER_GATHER_INFO, *PFSGI;

Members

dwFlags
Reserved; set to zero.
idDsk
Disk identifier, as passed to the MyFSD_MountDisk function, written by the independent software vendor.
dwSector
Specifies the starting sector number.
cSectors
Number of sectors to transfer.
pfdi
Pointer to the address of a FSD_DISK_INFO structure.
cfbi
Count of FSD_BUFFER_INFO structures. This member can be zero.
pfbi
Pointer to zero or more FSD_BUFFER_INFO structures. If there is more than one FSD_BUFFER_INFO structure, the structures must be created contiguously, as in an array of such structures, and the pointer must point to the first FSD_BUFFER_INFO structure.
pfnCallBack
Pointer to a callback function.

Remarks

This structure is used by FSDMGR_ReadDiskEx and FSDMGR_WriteDiskEx.

See Also

FSDMGR_ReadDiskEx, FSDMGR_WriteDiskEx , FSD_SCATTER_GATHER_RESULTS, FSD_BUFFER_INFO


FSD_SCATTER_GATHER_RESULTS

This structure contains the number of sectors transferred when calling the FSDMGR_ReadDiskEx or FSDMGR_WriteDiskEx functions.

At a Glance

Header file: | Fsdmgr.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct _FSD_SCATTER_GATHER_RESULTS{
DWORD dwFlags;
 DWORD cSectorsTransferred
} FSD_SCATTER_GATHER_RESULTS, *PFSGR;

Members

dwFlags
Reserved.
cSectorsTransferred
Total number of sectors transferred.

Remarks

This structure is returned by FSDMGR_ReadDiskEx and FSDMGR_WriteDiskEx.

See Also

FSDMGR_ReadDiskEx, FSDMGR_WriteDiskEx, FSD_SCATTER_GATHER_INFO


FUNCDESC

This structure is used to define a function description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagFUNCDESC {
MEMBERID memid;
/* [size_is(cScodes)] */ SCODE RPC_FAR *lprgscode;
/* [size_is(cParams)] */ ELEMDESC __RPC_FAR *lprgelemdescParam;
FUNCKIND funckind;
INVOKEKIND invkind;
CALLCONV callconv;
short cParams;
short cParamsOpt;
short oVft;
short cScodes;
ELEMDESC elemdescFunc;
WORD wFuncFlags;
} FUNCDESC;

Members

memid
Function member identifier.
lprgscode
lprgelemdescParam
funckind
Specifies whether the function is virtual, static, or dispatch-only.
invkind
Invocation kind. Indicates if this is a property function, and if so, what kind.
callconv
Specifies the function’s calling convention.
cParams
Count of total number of parameters, both required and optional.
cParamsOpt
Count of optional parameters.
ovft
For FUNC_VIRTUAL, specifies the offset in the VTBL.
cScodes
Count of permitted return values.
elemdescFunc
Contains the return type of the function.
wFuncFlags
Definition of flags follows.

Remarks

The cParamsOpt member specifies the form of optional parameters accepted by the function, as follows:

  • A value of 0 specifies that no optional arguments are supported.
  • A value of –1 specifies that the method’s last parameter is a pointer to a safe array of variants. Any number of variant arguments greater than cParams –1 must be packaged by the caller into a safe array and passed as the final parameter. This array of optional parameters must be freed by the caller after control is returned from the call.
  • Any other number indicates that the last n parameters of the function are variants and do not need to be specified by the caller explicitly. The parameters left unspecified should be filled in by the compiler or interpreter as variants of type VT_ERROR with the value DISP_E_PARAMNOTFOUND.

For 16-bit systems (Macintosh), the members cScodes and lprgscode store the count and the set of errors that a function can return. If cScodes = –1, then the set of errors is unknown. If cScodes = –1, or if cScodes = 0, then lprgscodeis undefined.


HEAPENTRY32

This structure describes one entry (block) of a heap that is being examined.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagHEAPENTRY32
{
DWORD dwSize;
HANDLE hHandle;
DWORD dwAddress;
DWORD dwBlockSize;
DWORD dwFlags;
DWORD dwLockCount;
DWORD dwResvd;
DWORD th32ProcessID;
DWORD th32HeapID;
} HEAPENTRY32;
typedef HEAPENTRY32 * PHEAPENTRY32;
typedef HEAPENTRY32 * LPHEAPENTRY32;

Members

dwSize
Specifies the length, in bytes, of the structure. Before calling the Heap32First function, set this member to sizeof(HEAPENTRY32). If you do not initialize dwSize, Heap32First will fail.
hHandle
Handle to the heap block.
dwAddress
Specifies the linear address of the start of the block.
dwBlockSize
Specifies the size, in bytes, of the heap block.
dwFlags
Specifies a bitmask of fags. It is one of the following values:
Value
Description
LF32_BIGBLOCK | A large piece of memory that has been virtually allocated.
LF32_DECOMMIT | Decommited memory block.
LF32_FIXED | The memory block has a fixed (unmovable) location.
LF32_FREE | The memory block is not used.

dwLockCount
Specifies the lock count on the memory block. The lock count is incremented each time the LocalLock function is called on the block either by the application or the DLL that the heap belongs to.
dwResvd
Reserved; do not use.
th32ProcessID
Identifier of the process to examine. The contents of this member can be used by Win32 API elements.
th32HeapID
Heap identifier in the owning process context. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.

Remarks

Windows CE does not support movable blocks.


HEAPLIST32

This structure describes an entry from a list that enumerates the heaps used by a specified process.

At a Glance

Header file: | Tlhelp32.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagHEAPLIST32 {
DWORD dwSize;
DWORD th32ProcessID;
DWORD th32HeapID;
DWORD dwFlags;
} HEAPLIST32;
typedef HEAPLIST32 * PHEAPLIST32;
typedef HEAPLIST32 * LPHEAPLIST32;

Members

dwSize
Specifies the length, in bytes, of the structure. Before calling the Heap32ListFirst function, set this member to sizeof(HEAPLIST32). If you do not initialize dwSize, Heap32First will fail.
th32ProcessID
Identifier of the process to examine. The contents of this member can be used by Win32 API elements.
th32HeapID
Heap identifier in the owning process context. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.
dwFlags
Specifies a bitmask of flags. The following flag is currently defined:
Value
Description
HF32_DEFAULT Process’s default heap.


hostent

This structure is allocated by Windows Sockets. An application should never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information that it needs before issuing any other Windows Sockets API calls.

At a Glance

Header file: | Winsock.h
Windows CE versions: | 1.0 and later

Syntax

struct hostent {
char FAR *h_name;
char FAR *FAR *h_aliases;
short h_addrtype;
short h_length;
char FAR * FAR * h_addr_list;
};

Members

h_name
Official name of the host (PC).If using the DNS or similar resolution system, it is the Fully Qualified Domain Name (FQDN) that caused the server to return a reply. If using a local “hosts” file, it is the first entry after the IP address.
h_aliases
Null-terminated array of alternate names.
h_addrtype
Type of address being returned.
h_length
Length, in bytes, of each address.
h_addr_list
Null-terminated list of addresses for the host. Addresses are returned in network byte order. The macro h_addr is defined to be h_addr_list[0] for compatibility with older software.


HREFTYPE

This data type specifies a handle to identify a type description.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef unsigned long HREFTYPE;


HREPLFLD

This structure is used as a handle to a folder stored by a client.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _REPLFLD FAR *HREPLFLD;

Members

HREPLFLD
Handle to a folder stored by a client.


HREPLITEM

This structure is used as a handle to a data object stored by a client. It is used as a generic handle to refer to either HREPLOBJ or HREPLFLD.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _REPLITEM FAR *HREPLITEM;

Members

HREPLFLD
Handle to a data object stored by a client.


HREPLOBJ

This structure is used as a handle to an object stored by a client.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _REPLOBJ FAR *HREPLOBJ;

Members

HREPLITEM
Handle to an object stored by clients.


HTMLCONTEXT

This structure contains information about the target of an ALT+Tap event inside an HTML viewer control. The HTML viewer control passes the container application a pointer to an HTMLCONTEXT structure in the pnmHtmlContext parameter of the NM_CONTEXTMENU notification message.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagHTMLCONTEXT {
NMHDR hdr;
POINT pt;
UINT uTypeFlags;
LPSTR szLinkHREF;
LPSTR szImageSrc;
HBITMAP hbmImage;
DWORD dwImageCookie;
} HTMLCONTEXT;

Members

hdr
NMHDR structure, specifying the type of notification message being sent and identifying the control that sent it.
pt
Point that contains the screen coordinates of the event.
uTypeFlags
Desginates the type of object on which the user ALT+Tapped. It is one of the following values:
Value
Description
HTMLCONTEXT_BACKGROUND | The target of the ALT+Tap event is a background object. This could be anything other than a link or an image.
HTMLCONTEXT_LINK | The target of the ALT+Tap event is an HTML link.
HTMLCONTEXT_IMAGE | The target of the ALT+Tap event is an image.
HTMLCONTEXT_IMAGENOTLOADED | The target of the ALT+Tap event is an image that has not been loaded yet.

szLinkHREF
Null-terminated string that contains the URL of the link on which the user ALT+Tapped. The value in this member is only valid if the HTMLCONTEXT_LINK flag is set in the uTypeFlags member.
szImageSrc
Null-terminated string that contains the source URL of the image that is the target of the ALT+Tap event. The value in this member is only valid if the HTMLCONTEXT_IMAGE flag is set in the uTypeFlags member.
hbmImage
Handle to the bitmap associated with the image on which the user ALT+Tapped. The value in this member is only valid if the HTMLCONTEXT_IMAGE flag is set in the uTypeFlags member.
dwImageCookie
Specifies the cookie value that was originally passed from the application to the HTML viewer control in the dwCookie member of the INLINEIMAGEINFO structure referenced in the lParam of the DTM_SETIMAGE message. The value in this member is only valid if the HTMLCONTEXT_IMAGE flag is set in the uTypeFlags member.

Remarks

Never modify any of the data inside the HTMLCONTEXT structure. The HTML viewer control uses this data internally. Do not attempt to store or free any of the pointers contained in this structure. If you need to retain one of the strings for later use, make a copy of it.

See Also

NM_CONTEXTMENU


HWXGUIDE

This structure specifies the location of the input boxes on the screen.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagHWXGUIDE {
UINT cHorzBox;
UINT cVertBox;
INT xOrigin;
INT yOrigin;
UINT cxBox;
UINT cyBox;
UINT cxOffset;
UINT cyOffset;
UINT cxWriting;
UINT cyWriting;
UINT cyMid;
UINT cyBase;
UINT nDir
} HWXGUIDE, *PHWXGUIDE;

Members

cHorzBox
Number of input boxes positioned horizontally.
cVertBox
Number of input boxes positioned vertically.
xOrigin
Specifies the x-coordinate for the upper-left corner of the input area.
yOrigin
Specifies the y-coordinate for the upper-left corner of the input area.
cxBox
Width of a single box.
cyBox
Height of a single box.
cxOffset
Specifies the x-coordinate offset within a box to the upper-left of the writing area.
cyOffset
Specifies the y-coordinate offset within a box to the upper-left of the writing area.
cxWriting
Width of the writing area.
cyWriting
Height of the writing area.
cyMid
Midline information measured from the top of the writing area. For English or any language based on Latin letters, it must be set to the appropriate value. For the Far East languages—Japanese, Chinese, and Korean—this member is not used and must be set to zero.
cyBase
Baseline value measured from the top of the writing area. For English or any language based on Latin letters, it must be set to the appropriate value. For the Far East languages—Japanese, Chinese, and Korean—this member is not used and must be set to zero.
Ndir
Writing direction. The following values are defined, but each is not necessarily supported:
HWX_BIDIRECTIONAL
HWX_HORIZONTAL
HWX_VERTICAL

If an application specifies an unsupported writing direction in a call to HwxSetGuide, an error is returned.

Remarks

This structure is passed in to HwxSetGuide, and it specifies where the boxes are located on the screen. All positions are in scaled screen coordinates. You should do the scaling so that cyWriting is about 1,000 units. To avoid speed and rounding problems, use an integral multiple of your actual size.

The writing area must be centered. To do this, set cxBox, cxOffset, and cxWriting such that cxBox = = 2 * cxOffset + cxWriting.

See Also

HwxSetGuide


HWXRESULTS

This structure contains the results from processing the handwriting recognition context (HRC) information.

At a Glance

Header file: | Recog.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagHWXRESULTS {
USHORT indxBox;
WCHAR rgChar[1]
} HWXRESULTS, *PHWXRESULTS;

Members

indxBox
Zero-based index into HWXGUIDE structure where the character was written.
rgChar
Variable-sized array of characters returned.

Remarks

This structure is filled in by HwxGetResults. The rgChar array is actually a variable-sized array of alternate results. The number of alternate results is passed into HwxGetResults.

See Also

HwxGetResults, HWXGUIDE


IDLDESC

This structure is used for holding information needed for transferring a structure element, parameter, or function return value between processes.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagIDLDESC {
ULONG dwReserved;
USHORT wIDLFlags;
};
} IDLDESC, *LPIDLDESC;

Members

dwReserved
Reserved; set to NULL.
wIDLFlags
Flag that is one of the following values:
Value
Description
IDLFLAG_NONE | Whether the parameter passes or receives information is unspecified.
IDLFLAG_FIN | Parameter passes information from the caller to the callee.
IDLFLAG_FOUT | Parameter returns information from the callee to the caller.
IDLFLAG_FLCID | Parameter is the local identifier of a client application.
IDLFLAG_FRETVAL | Parameter is the return value of the member.


IMENUMINFO

This structure contains information on an installed input method (IM).

At a Glance

Header file: | Sipapi.h
Windows CE versions: | 2.10 and later

Syntax

struct_IMENUMINFO{
TCHAR szName[MAX_PATH];
CLSID Clsid;
}IMENUMINFO;

Members

szName
Length of IM default name, set by the IM installation in the registry, that has a maximum of MAX_PATH and includes the NULL character.
Clsid
Class identifier (CLSID) of the installed IM.

See Also

SIPEnumIMProc


IMINFO

This structure contains information regarding the size and available bitmaps for the input method (IM).

At a Glance

Header file: | Server.h (Sip.idl for Palm-size PC)
Windows CE versions: | 2.01 and later

Syntax

typedef struct {
DWORD cbSize;
HIMAGELIST hImageNarrow;
HIMAGELIST hImageWide;
int iNarrow;
int iWide;
DWORD fdwFlags;
RECT rcSipRect;
} IMINFO;

Members

cbSize
Size of the IMINFO structure. For the Palm-size PC, this member must be filled in by the input panel prior to calling IInputMethod::GetInfo.
hImageNarrow
Handle to an image list that contains the narrow 16x16 masked bitmaps for the IM. The input panel displays a bitmap from this image list to indicate the currently selected IM.
hImageWide
Handle to an image list that contains the wide 32x16 masked bitmaps. The input panel displays a bitmap from this image list to indicate the currently selected IM.
iNarrow
Index to the hImageNarrow image list indicating which bitmap should be displayed by the input panel. The IM can change the bitmap displayed in the input panel taskbar button by calling IIMCallback::SetImInfo. The IM should change the bitmap on the Input Panel button when the IM is first selected into the input panel.
iWide
Index to the hImageWide image list indicating which bitmap should be displayed by the input panel. The IM can change the bitmap displayed in the input panel taskbar button by calling IIMCallback::SetImInfo. The IM should change the bitmap on the Input Panel button when the IM is first selected into the input panel.
rcSipRect
Rectangle, in screen coordinates, representing the size and location of the input panel. This sizing and placement information, returned from IInputMethod::GetInfo, is optionally used by the input panel to determine the default size and placement for the input panel. The IIMCallback::SetImInfo method specifies the new size and placement of the input panel window.

Remarks

The Input Panel button displays the 32x16 bitmap button when there are only a few other controls on the taskbar. At times, there may not be enough room on the taskbar to display all the controls. During these times, the Input Panel button shrinks to half its normal width and uses the 16x16 bitmap.


INLINEIMAGEINFO

This structure is sent in the DTM_SETIMAGE message from the application to the HTML control.

At a Glance

Header file: | Htmlctrl.c
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagINLINEIMAGEINFO {
DWORD dwCookie;
int iOrigHeight;
int iOrigWidth;
HBITMAP hbm;
BOOL bOwnBitmap;
} INLINEIMAGEINFO, *LPINLINEIMAGEINFO;

Members

dwCookie
Specifies the cookie value passed in the dwCookie member of the NM_HTMLVIEW structure when an NM_INLINE_IMAGE notification message is received from the HTML control.
iOrigHeight
Original height of the image.
iOrigWidth
Original width of the image.
hbm
Handle to the bitmap of the image.
bOwnBitmap
Boolean that is set to TRUE if the HTML control will destroy the bitmap when the page is destroyed, or to FALSE if the HTML control will not destroy the bitmap.

See Also

DTM_IMAGEFAIL, DTM_SETIMAGE, NM_INLINE_IMAGE


INPUT

This structure is used by the SendInput function to synthesize keystrokes, stylus and mouse motions, and button clicks.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagINPUT {
DWORD type;
union
{
MOUSEINPUT mi;
KEYBDINPUT ki;
HARDWAREINPUT hi;
};
} INPUT, *PINPUT, FAR* LPINPUT;

Members

type
Indicates the type of device information this structure carries. It is one of the following values:
Value
Description
INPUT_HARDWARE | The hi union member is valid.
INPUT_KEYBOARD | The ki union member is valid.
INPUT_MOUSE | The mi union member is valid.

mi
MOUSEINPUT structure that contains information about simulated mouse input.
ki
KEYBDINPUT structure that contains information about simulated keyboard input.
hi
HARDWAREINPUT structure that contains information about a simulated input device message.

Remarks

Windows CE does not support the INPUT_HARDWARE value in the type member.

This structure is used with the SendInput sample application.

This structure contains information identical to that used in the parameter list for a call to the keybd_event, mouse_event, or hardware_event functions.

See Also

SendInput


ITEMIDLIST

This structure contains a list of item identifiers.

At a Glance

Header file: | Shlobj.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _ITEMIDLIST {
SHITEMID mkid;
} ITEMIDLIST, * LPITEMIDLIST;
typedef const ITEMIDLIST * LPCITEMIDLIST;

Members

mkid
List of item identifiers.


LOAD_DLL_DEBUG_INFO

This structure contains information about a dynamic-link library (DLL) that has just been loaded.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _LOAD_DLL_DEBUG_INFO {
HANDLE hFile;
LPVOID lpBaseOfDll;
DWORD dwDebugInfoFileOffset;
DWORD nDebugInfoSize;
LPVOID lpImageName;
WORD fUnicode;
} LOAD_DLL_DEBUG_INFO;

Members

hFile
Ignored. Set to NULL.
lpBaseOfDll
Long pointer to the base address of the DLL in the address space of the process loading the DLL.
dwDebugInfoFileOffset
Ignored. Must be 0.
nDebugInfoSize
Ignored. Must be 0.
lpImageName
Long pointer to the address space of the process that is being debugged. Use the ReadProcessMemory function to retrieve the actual image name.

This member is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL or *lpImageName (in the address space of the process being debugged) is NULL. Specifically, the system will never provide an image name for a create process event, and it will not likely pass an image name for the first DLL event. The system will also never provide this information in the case of debugging events that originate from a call to the DebugActiveProcess function.

fUnicode
Indicates whether a filename specified by lpImageName is Unicode or ANSI. A nonzero value for this member indicates Unicode; zero indicates ANSI.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, DebugActiveProcess, DEBUG_EVENT


MailAtt

This structure is used to describe a single attachment to a mail message.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct MailAtt_s {
UINT uiAttachmentNumber;
DWORD dwFlags;
ULONG ulCharacterPosition;
ULONG ulSize;
LPWSTR szOriginalName;
LPWSTR szLocalName;
} MailAtt, *lpMailAtt;

Members

uiAttachmentNumber
Number, counting from 1, to indicate which attachment is specified.
dwFlags
This member has three bit-masks to categorize three groups of the mail attachment flags: *_ALL_*, *_THIS_*, and *_NUMBER_*.
Value
Description
ATT_ALL_FLAGS_MASK | For flags that apply to all attachments to the message. Currently, no such flags are defined in this category.
ATT_THIS_FLAGS_MASK | For flags that apply only to a specified attachment. The following table shows the two flags that are currently defined in the category.
ATT_DISP_RETRIEVE | User has requested to download the non-local attachment to the message. Set only if ATT_DOWNLOADABLE is set.
ATT_DOWNLOADABLE | The originating transport is capable of downloading the attachment independently.
ATT_NUMBER_MASK | For number masks used to mark the number of attachment files (or headers) to the mail message. Currently, no number mask is defined.

ulCharacterPosition
Character position of the attachment in the text portion of the message. Not currently supported.
ulSize
Size of the attached file. For MailPutAttachment it must be specified for a non-local attachment when szLocalName is NULL. For MailgetAttachment it is assigned to the size of the attached file for either a local or a non-local attachment.
szOriginalName
Null-terminated string that contains the name of the original file of attached to the message, without path information.
szLocalName
Null-terminated string that contains the path name of the attached file on a Windows CE device. It must be set to NULL for a nonlocal attachment.

Remarks

From the user point of view, an attachment is the file (szOriginalName) attached to the message. For an application developer, however, the attachment may be conveniently viewed as consisting of a header and the attached file. The header is the MailAtt data structure itself. The original file name does not contain path information.

An application developer may want to work with either local or non-local attachments. A local attachment has a header and a copy (szLocalName) of the original file (szOriginalName) stored on a Windows CE device. A nonlocal attachment does not store the attached file locally and is simply a place-holder for the original file. For a non-local attachment, szLocalName must be set NULL and ulSize specified.

Nonlocal attachments are possible only when a message is linked to a service. For some services, an attachment header can be used to make the file local on demand.


MailAttArray

This structure is used to describe a series of mail attachments.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct MailAttArray_s {
DWORD dwFlags;
UINT uiAttCount;
lpMailAtt AttArray[];
} MailAttArray, *lpMailAttArray;

Members

dwFlags
Specifies a bitmask of flags that apply to all of the attachments. Flags not in the ATT_ALL_FALGS_MASK area are ignored. Currently, no valid flags are supported.
uiAttCount
Count of attachments in the following AttArray.
AttArray
Array of MailAtt structures. The uiAttCount member specifies the number of the elements in the array.


MailMsg

This structure is used by the Mail and Transport functions to store the contents of messages being sent and received.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct MailMsg {
DWORD dwMsgId;
DWORD dwFlags;
DWORD dwMsgLen;
WORD wBodyLen;
FILETIME ftDate;
LPWSTR szSvcId;
LPWSTR szSvcNam;
WCHAR *pwcHeaders;
LPWSTR szBody;
CEOID oid;
HANDLE hHeap
} MailMsg;

Members

dwMsgId
Specifies an internal identification number maintained by the system. This identification number is used by library routines to access messages in the message store. Applications should not attempt to change the value stored in this member.
dwFlags
Specifies the folder that contains the message, the status of the message, and how the message is handled. These mail flags are divided into three categories: folder flags, status flags, and message flags. The flags and a brief description of their meanings are listed below.

Folder flags determine which folder to locate or store the message in. Use only one of the following folder flags in combination with status and message flags:
Value
Description
MAIL_FOLDER_ALL | Folder flag mask
MAIL_FOLDER_FIRST | Start of user-defined folders
MAIL_FOLDER_LAST | End of user-defined folders
MAIL_FOLDER_SENT | Copy of sent mail
MAIL_FOLDER_OUTBOX | Local OUTBOX (last local folder)
MAIL_FOLDER_INBOX | Universal INBOX
MAIL_FOLDER_ANY | Search for any folder during “Get”
MAIL_FOLDER_TARGET | Target folder for MAIL_COPY

Status flags verify the status of the message being stored or retrieved, or whether the message has attachment. Status flags can be used to determine what type of messages to search for when calling MailFirst and MailNext functions. These flags can be any combination of the following values:
Value
Description
MAIL_STATUS_ALL | Status flag mask.
MAIL_STATUS_FREE | Message deleted - free slot.
MAIL_STATUS_DELETE | Message set to be deleted.
MAIL_STATUS_COPY | Message set to be copied to local target.
MAIL_STATUS_READ | Message marked as having been read.
MAIL_STATUS_SERVICE | INBOX Message exists on a service.
MAIL_STATUS_COMPOSED | Set for outgoing messages (newly composed, replied, or forwarded). In Windows CE version 2.0, an outgoing message can be saved and later re-edited using the outgoing dialog box that includes the SEND button.
MAIL_STATUS_REMOTE | INBOX body exists only on service.
MAIL_STATUS_NOT | Look for invert of status bits (GET).
MAIL_STATUS_ANY | (MAIL_STATUS_NOT | MAIL_STATUS_FREE).
MAIL_STATUS_ALIVE | (MAIL_STATUS_ANY | MAIL_STATUS_DELETE).
MAIL_STATUS_LOCAL | (MAIL_STATUS_ALIVE | MAIL_STATUS_SERVICE).
MAIL_STATUS_BODY | (MAIL_STATUS_ALIVE | MAIL_STATUS_REMOTE).
MAIL_STATUS_UNREAD | (MAIL_STATUS_ALIVE | MAIL_STATUS_READ).
MAIL_STATUS_ATTACHMENTS | The message has attachments.
MAIL_STATUS_ATT_REQ | The message’s attachment is marked for download.

Message flags determine how the message will be handled and how much of the message is retrieved on a mail get. If none of the message flags are set, all members but the body are retrieved. Of the following flags, use any combination of the first two flags with one of the remaining flags.
Value
Description
MAIL_FLAGS_ALL | Message flag mask.
MAIL_KEEP | Move from OUTBOX to FILE after sent. In Windows CE version 2.0, this flag is no longer used. Instead, the client application checks the current registry settings to determine whether it does or does not save a message in the Sent Item folder.
MAIL_GET_BODY | Get body (during a MailGet).
MAIL_GET_FLAGS | Get only flags member (during a get).
MAIL_FULL | Get full body when copying.

dwMsgLen
Specifies the size, in bytes, of the entire message on the service.
wBodyLen
Specifies the size, in bytes, of the message as maintained in the message store.
ftDate
Specifies the date and time the message was received by the service.
szSvcId
Null-terminated string that contains a unique identification number assigned by the service. The service uses this identification number to access the desired message.
szSvcNam
Null-terminated string that contains the name of the service. Applications can use this name to link messages to a particular service.
pwcHeaders
Pointer to the header members. The header consists of entries made up of two members, a name and an associated value. The name members are separated from the value members by a NULL character, and the entries are separated from each other by a NULL character. The header string is terminated with two consecutive NULL characters.
szBody
Null-terminated string that contains the body of the message.
oid
Object identifier. The object identifier is assigned by the system and can be used as a key for storing and receiving messages. The object identifier is set when the message is inserted in the message store using the MailPut function and returned in this member when the MailFirst or MailNext functions are called.
hHeap
Handle to the private heap used for all storage related to this message. Any storage allocated to this heap is freed when the MailFree function is called.

Remarks

A mail message can be either local or linked to a service. Local messages exist only the device. User-composed messages fall into this category. Service-lined messages, on the other hand, exist on a service somewhere, but are referenced locally. Messages that are synchronized and retrieved by means of the SMTP/POP3 transport fall into this category.


MailNonIpmInfo

This structure is used internally by transports to describe non-Interpersonal Message (IPM) data on a message.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct MailNonIpmInfo_s {
LPWSTR szMessageClass;
UINT uiPropcount;
CEPROPVAL propArray[];
} MailNonIpmInfo, *lpMailNonIpmInfo;

Members

szMessageClass
Null-terminated string that contains the header “Type” of the non-IPM message.
uiPropCount
Count of non-IPM properties in the following propArray.
propArray
Array of CEPROPVAL structures. The uiPropCount member specifies the number of the elements in the array.


MAILSORTINFO

This structure is used to describe the order in which messages are sorted for a particular mail handle.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _MAILSORTINFO {
MAILSORTFIELD iSort;
BOOL fAscending;
int cMsgs;
} MAILSORTINFO, *PMAILSORTINFO;

Members

iSort
Specifies the member by which the database is sorted for the specified mail handle. See the MAILSORTFIELD enumeration.
fAscending
Boolean that is set to TRUE if the records are sorted in ascending order on the specified key, or to FALSE if the records are sorted in descending order.
cMsgs
Specifies the number of messages currently in the store.


MEASUREITEMSTRUCT

This structure informs Windows CE of the dimensions of an owner-drawn control or menu item. This allows Windows CE to process user interaction with the control correctly.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagMEASUREITEMSTRUCT {
UINT CtlType;
UINT CtlID;
UINT itemID;
UINT itemWidth;
UINT itemHeight;
DWORD itemData;
} MEASUREITEMSTRUCT;

Members

CtlType
Specifies the control type. It can be one of the following values:
Value
Description
ODT_BUTTON | Owner-drawn button
ODT_LISTVIEW | Owner-draw list view control
ODT_MENU | Owner-drawn menu

CtlID
Identifier of the combo box, list box, or button. This member is not used for a menu.
itemID
Identifier for a menu item or the position of a list box or combo box item. This value is specified for a list box only if it has the LBS_OWNERDRAWVARIABLE style; this value is specified for a combo box only if it has the CBS_OWNERDRAWVARIABLE style.
itemWidth
Specifies the width, in pixels, of a menu item. Before returning from the message, the owner of the owner-drawn menu item must fill this member.
itemHeight
Specifies the height, in pixels, of an individual item in a list box or a menu. Before returning from the message, the owner of the owner-drawn combo box, list box, or menu item must fill out this member.
itemData
Specifies the application-defined 32-bit value associated with the menu item. For a control, this member specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LB_HASSTRINGS or CB_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value passed to the list box or combo box in the lParam parameter of one of the following messages:
  • CB_ADDSTRING
  • CB_INSERTSTRING
  • LB_ADDSTRING
  • LB_INSERTSTRING

Remarks

Windows CE does not support owner-drawn combo boxes and list boxes.

The owner window of an owner-drawn control receives a pointer to the MEASUREITEMSTRUCT structure as the lParam parameter of a WM_MEASUREITEM message. The owner-drawn control sends this message to its owner window when the control is created. The owner then fills in the appropriate members in the structure for the control and returns. This structure is common to all owner-drawn controls.

If an application does not fill the appropriate members of MEASUREITEMSTRUCT, the control or menu item may not be drawn properly.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA, LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA, WM_MEASUREITEM


MEMBERID

This data type is used to identify the member in a type description.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

Typedef DISPID MEMBERID;

Remarks

This is a 32-bit integral value in the following format.

Bits
Value
0–15 | Offset. Any value is permissible.
16–21 The nesting level of this type information in the inheritance hierarchy. For example:
interface mydisp : IDispatch

The nesting level of IUnknown is 0, IDispatch is 1, and MyDisp is 2.
22–25 | Reserved. Must be zero.
26–28 | Value of the DISPID.
29 | True if this is the member ID for a FUNCDESC; otherwise False.
30–31 | Must be 01.

Negative identifiers are reserved for use by Automation.


MEMORY_BASIC_INFORMATION

This structure contains information about a range of pages in the virtual address space of a process. The VirtualQuery function uses this structure.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _MEMORY_BASIC_INFORMATION {
PVOID BaseAddress;
PVOID AllocationBase;
DWORD AllocationProtect;
DWORD RegionSize;
DWORD State;
DWORD Protect;
DWORD Type;
} MEMORY_BASIC_INFORMATION;
typedef MEMORY_BASIC_INFORMATION *PMEMORY_BASIC_INFORMATION;

Members

BaseAddress
Pointer to the base address of the region of pages.
AllocationBase
Pointer to the base address of a range of pages allocated by the VirtualAlloc function. The page pointed to by the BaseAddress member is contained within this allocation range.
AllocationProtect
Specifies the access protection given when the region was initially allocated. One of the following flags can be present, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags:
Value
Description
PAGE_READONLY | Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE | Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY | Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE | Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ | Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE | Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY | Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD | Protects the page with the underlying page protection. However, access to the region causes a “guard page entered” condition to be raised in the subject process. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
PAGE_NOACCESS | Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE | Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be set to no cache. This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

RegionSize
Specifies the size, in bytes, of the region beginning at the base address in which all pages have identical attributes.
State
Specifies the state of the pages in the region. One of the following states is indicated:
Value
Description
MEM_COMMIT | Indicates committed pages for which physical storage has been allocated, either in memory or in the paging file on disk.
MEM_FREE | Indicates free pages not accessible to the calling process and available to be allocated. For free pages, the information in the AllocationBase, AllocationProtect, Protect, and Type members is undefined.
MEM_RESERVE | Indicates reserved pages where a range of the process’s virtual address space is reserved without any physical storage being allocated. For reserved pages, the information in the Protect member is undefined.

Protect
Specifies the access protection of the pages in the region. One of the flags listed for the AllocationProtect member is specified.
Type
Specifies the type of pages in the region. The following types are defined:
Value
Description
MEM_IMAGE | Indicates that the memory pages within the region are mapped into the view of an image section.
MEM_MAPPED | Indicates that the memory pages within the region are mapped into the view of a section.
MEM_PRIVATE | Indicates that the memory pages within the region are private (that is, not shared by other processes).

See Also

VirtualAlloc, VirtualQuery


MEMORYSTATUS

This structure contains information about current memory availability. The GlobalMemoryStatus function uses this structure.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _MEMORYSTATUS {
DWORD dwLength;
DWORD dwMemoryLoad;
DWORD dwTotalPhys;
DWORD dwAvailPhys;
DWORD dwTotalPageFile;
DWORD dwAvailPageFile;
DWORD dwTotalVirtual;
DWORD dwAvailVirtual;
} MEMORYSTATUS, *LPMEMORYSTATUS;

Members

dwLength
Specifies the size, in bytes, of the MEMORYSTATUS data structure. You do not need to set this member before calling the GlobalMemoryStatus function; the function sets it.
dwMemoryLoad
Specifies a number between 0 and 100 that gives a general idea of current memory utilization, in which 0 indicates no memory use and 100 indicates full memory use.
dwTotalPhys
Indicates the total number of bytes of physical memory.
dwAvailPhys
Indicates the number of bytes of physical memory available.
dwTotalPageFile
Indicates the total number of bytes that can be stored in the paging file. Note that this number does not represent the actual physical size of the paging file on disk.
dwAvailPageFile
Indicates the number of bytes available in the paging file.
dwTotalVirtual
Indicates the total number of bytes that can be described in the user mode portion of the virtual address space of the calling process.
dwAvailVirtual
Indicates the number of bytes of unreserved and uncommitted memory in the user mode portion of the virtual address space of the calling process.

See Also

GlobalMemoryStatus


MENUITEMINFO

This structure contains information about a menu item.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagMENUITEMINFO {
UINT cbSize;
UINT fMask;
UINT fType;
UINT fState;
UINT wID;
HMENU hSubMenu;
HBITMAP hbmpChecked;
HBITMAP hbmpUnchecked;
DWORD dwItemData;
LPTSTR dwTypeData;
UINT cch;
} MENUITEMINFO, FAR *LPMENUITEMINFO;

Members

cbSize
Size of structure, in bytes.
fMask
Members to retrieve or set. It can be one or more of these values:
Value
Description
MIIM_CHECKMARKS | Retrieves or sets the hbmpChecked and hbmpUnchecked members.
MIIM_DATA | Retrieves or sets the dwItemData member.
MIIM_ID | Retrieves or sets the wID member.
MIIM_STATE | Retrieves or sets the fState member.
MIIM_SUBMENU | Retrieves or sets the hSubMenu member.
MIIM_TYPE | Retrieves or sets the fType and dwTypeData members.

fType
Menu item type. It can be one or more of these values:
Value
Description
MFT_BITMAP | Displays the menu item using a bitmap. The low-order word of the dwTypeData member is the bitmap handle, and the cch member is ignored.
MFT_MENUBARBREAK | Places the menu item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu). For a drop-down menu, submenu, or shortcut menu, a vertical line separates the new column from the old.
MFT_MENUBREAK | Places the menu item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu). For a drop-down menu, submenu, or shortcut menu, the columns are not separated by a vertical line.
MFT_OWNERDRAW | Assigns responsibility for drawing the menu item to the window that owns the menu. The window receives a WM_MEASUREITEM message before the menu is displayed for the first time, and a WM_DRAWITEM message whenever the appearance of the menu item must be updated. If this value is specified, the dwTypeData member contains an application-defined 32-bit value.
MFT_RADIOCHECK | Displays checked menu items using a radio-button mark instead of a check mark if the hbmpChecked member is NULL.
MFT_RIGHTJUSTIFY | Right-justifies the menu item and any subsequent items. This value is valid only if the menu item is in a menu bar.
MFT_RIGHTORDER | Windows 95, Windows NT 5.0, and later: Specifies that menus cascade right-to-left (the default is left-to-right). This is used to support right-to-left languages, such as Arabic and Hebrew.
MFT_SEPARATOR | Specifies that the menu item is a separator. A menu item separator appears as a horizontal dividing line. The dwTypeData and cch members are ignored. This value is valid only in a drop-down menu, submenu, or shortcut menu.
MFT_STRING | Displays the menu item using a text string. The dwTypeData member is the pointer to a null-terminated string, and the cch member is the length of the string.

The MFT_BITMAP, MFT_SEPARATOR, and MFT_STRING values cannot be combined with one another.

fState
Menu item state. It can be one or more of these values:
Value
Description
MFS_CHECKED | Checks the menu item. For more information about checked menu items, see the hbmpChecked member.
MFS_DEFAULT | Specifies that the menu item is the default. A menu can contain only one default menu item, which is displayed in bold.
MFS_DISABLED | Disables the menu item so that it cannot be selected, but does not gray it.
MFS_ENABLED | Enables the menu item so that it can be selected. This is the default state.
MFS_GRAYED | Disables the menu item and grays it so that it cannot be selected.
MFS_HILITE | Highlights the menu item.
MFS_UNCHECKED | Unchecks the menu item. For more information about unchecked menu items, see the hbmpUnchecked member.
MFS_UNHILITE | Removes the highlight from the menu item. This is the default state.

wID
Application-defined 16-bit value that identifies the menu item.
hSubMenu
Handle to the drop-down menu or submenu associated with the menu item. If the menu item is not an item that opens a drop-down menu or submenu, this member is NULL.
hbmpChecked
Handle to the bitmap to display next to the item if it is checked. If this member is NULL, a default bitmap is used. If the MFT_RADIOCHECK type value is specified, the default bitmap is a bullet. Otherwise, it is a check mark.
hbmpUnchecked
Handle to the bitmap to display next to the item if it is not checked. If this member is NULL, no bitmap is used.
dwItemData
Specifies the application-defined value associated with the menu item.
dwTypeData
Specifies the content of the menu item. This member is used only if the MIIM_TYPE flag is set in the fMask member.

Before calling GetMenuItemInfo, the application must set this member to point to a buffer whose length is specified by the cch member. If the retrieved menu item is of the type MFT_STRING, then GetMenuItemInfo copies the menu item text to the buffer. If the retrieved menu item is of some other type, then GetMenuItemInfo sets the dwTypeData member to a value whose type is specified by the fType member.

When using with the SetMenuItemInfo function, this member should contains a value whose type is specified by the fType member.

cch
Length of the menu item text when information is received about a menu item of the MFT_STRING type. This member is used only if the MIIM_TYPE flag is set in the fMask member and is zero otherwise. This member is ignored when the content of a menu item is set by calling SetMenuItemInfo.

Before calling GetMenuItemInfo, the application must set this member to the length of the buffer pointed to by the dwTypeData member. If the retrieved menu item is of type MFT_STRING (as indicated by the fType member), then GetMenuItemInfo sets cch to the length of the retrieved string. If the retrieved menu item is of some other type, GetMenuItemInfo sets the cch member to zero.

Remarks

The MENUITEMINFO structure is used with the GetMenuItemInfo, InsertMenuItem, and SetMenuItemInfo functions.

See MenuItemInfo and GetMenuItemInfo to determine which members are supported for each operation.

In SetMenuItemInfo, only the following flags are valid for the fMask member of the MENUITEMINFO structure pointed to by the lpmii parameter:

  • MIIM_DATA
  • MIIM_ID
  • MIIM_TYPE

See Also

GetMenuItemInfo, WM_DRAWITEM, WM_MEASUREITEM


METAFILEPICT

This structure defines the metafile picture format used for exchanging metafile data through the clipboard.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagMETAFILEPICT {
LONG mm;
LONG xExt;
LONG yExt;
HMETAFILE hMF;
} METAFILEPICT;

Members

mm
Specifies the mapping mode in which the picture is drawn.
xExt
Specifies the size of the metafile picture for all modes except the MM_ISOTROPIC and MM_ANISOTROPIC modes. (For more information about these modes, see the yExt member.) The x-extent specifies the width of the rectangle within which the picture is drawn. The coordinates are in units that correspond to the mapping mode.
yExt
Specifies the size of the metafile picture for all modes except the MM_ISOTROPIC and MM_ANISOTROPIC modes. The y-extent specifies the height of the rectangle within which the picture is drawn. The coordinates are in units that correspond to the mapping mode.

For MM_ISOTROPIC and MM_ANISOTROPIC modes, which can be scaled, the xExt and yExt members contain an optional suggested size in MM_HIMETRIC units. For MM_ANISOTROPIC pictures, xExt and yExt can be zero when no suggested size is supplied. For MM_ISOTROPIC pictures, an aspect ratio must be supplied even when no suggested size is given. (If a suggested size is given, the aspect ratio is implied by the size.) To give an aspect ratio without implying a suggested size, set xExt and yExt to negative values whose ratio is the appropriate aspect ratio. The magnitude of the negative xExt and yExt values is ignored; only the ratio is used.

hMF
Handle to a memory metafile.

See Also

SetClipboardData


METHODDATA

This structure is used to describe a method or property.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagMETHODDATA {
OLECHAR FAR *szName;
PARAMDATA FAR * ppData;
DISPID dispid;
unsigned int iMeth;
CALLCONV cc;
unsigned int cArgs;
unsigned short wFlags;
VARTYPE vtReturn;
} METHODDATA;

Members

szName
Null-terminated string that contains the method name.
ppData
Parameters for the method. The first parameter is ppdata[0], and so on.
dispid
Identifier of the method, as used in IDispatch.
iMeth
Index of the method in the VTBL of the interface. The indexes start with 0.
cc
Specifies the calling convention. The CDECL and Pascal calling conventions are supported by the dispatch interface creation functions.
cArgs
Number of arguments for the method.
wFlags
Flags that indicate whether the method is used for getting or setting a property. DISPATCH_METHOD indicates that this is not used for a property. DISPATCH_PROPERTYGET indicates that the method is used to get a property value. DISPATCH_PROPERTYPUT indicates that the method is used to set the value of a property. DISPATCH_PROPERTYPUTREF indicates that the method is used to make the property refer to a passed-in object.
vtReturn
Return type for the method.


MMTIME

This structure contains timing information for different types of multimedia data.

At a Glance

Header file: | Mmsystem.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct mmtime_tag {
UINT wType;
union {
DWORD ms;
DWORD sample;
DWORD cb;
DWORD ticks;
struct {
BYTE hour;
BYTE min;
BYTE sec;
BYTE frame;
BYTE fps;
BYTE dummy;
BYTE pad[2]
} smpte;
struct {
DWORD songptrpos;
} midi;
} u;
} MMTIME;

Members

wType
Time format. It is one of the following values:
Value
Description
TIME_BYTES | Current byte offset from beginning of the file.
TIME_MIDI | MIDI time.
TIME_MS | Time in milliseconds.
TIME_SAMPLES | Number of waveform-audio samples.
TIME_SMPTE | SMPTE (Society of Motion Picture and Television Engineers) time.
TIME_TICKS | Ticks within a MIDI stream.

ms
Number of milliseconds. Used when wType is TIME_MS.
sample
Number of samples. Used when wType is TIME_SAMPLES.
cb
Byte count. Used when wType is TIME_BYTES.
ticks
Ticks in MIDI stream. Used when wType is TIME_TICKS.
smpte
SMPTE time structure. Used when wType is TIME_SMPTE.
songptrpos
Song pointer position.
midi
MIDI time structure. Used when wType is TIME_MIDI.
hour
Hours.
min
Minutes.
sec
Seconds.
frame
Frames.
fps
Frames per second—24, 25, 29 (30 drop), or 30.
dummy
Dummy byte for alignment.
pad
Padding.


MODULEENTRY32

This structure describes an entry from a list that enumerates the modules used by a specified process.

At a Glance

Header file: | Thelp32.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagMODULEENTRY32 {
DWORD dwFlags
DWORD dwSize;
DWORD th32ModuleID;
DWORD th32ProcessID;
DWORD GlblcntUsage;
DWORD ProccntUsage;
BYTE *modBaseAddr;
DWORD modBaseSize;
HMODULE hModule;
TCHAR szModule[MAX_MODULE_NAME32 + 1];
TCHAR szExePath[MAX_PATH];
} MODULEENTRY32;
typedef MODULEENTRY32 * PMODULEENTRY32;
typedef MODULEENTRY32 * LPMODULEENTRY32;

Members

dwFlags
Reserved.
dwSize
Specifies the length, in bytes, of the structure. Before calling the Module32First function, set this member to sizeof(MODULEENTRY32). If you do not initialize dwSize, Module32First will fail.
th32ModuleID
Module identifier in the context of the owning process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.
th32ProcessID
Identifier of the process being examined. The contents of this member can be used by Win32 API elements.
GlblcntUsage
Global usage count on the module.
ProccntUsage
Module usage count in the context of the owning process.
modBaseAddr
Base address of the module in the context of the owning process.
modBaseSize
Size, in bytes, of the module.
hModule
Handle to the module in the context of the owning process.
szModule
Null-terminated string that contains the module name.
szExePath
Null-terminated string that contains the location (path) of the module.

Remarks

The modBaseAddr and hModule members are valid only in the context of the process specified by th32ProcessID.


NEWCPLINFO

This structure contains resource information and a user-defined value for a dialog box supported by a Control Panel application.

At a Glance

Header file: | Cpl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagNEWCPLINFO {
DWORD dwSize;
DWORD dwFlags;
DWORD dwHelpContext;
LONG lData;
HICON hIcon;
TCHAR szName[32];
TCHAR szInfo[64];
TCHAR szHelpFile[128];
} NEWCPLINFO;

Members

dwSize
Specifies the length of the structure, in bytes.
dwFlags
Ignored.
dwHelpContext
Ignored.
lData
Data defined by the application. When the Control Panel sends the CPL_DBCLK and CPL_STOP messages, it passes this value back to your application.
hIcon
Handle to the icon that represents the dialog box. This icon is intended to be displayed by the application that controls the Control Panel application.
szName
Null-terminated string that contains the dialog box name. The name is intended to be displayed below the icon.
szInfo
Null-terminated string that contains the dialog box description. The description is intended to be displayed when the icon for the dialog box is selected.
szHelpFile
Ignored.

Remarks

The dwHelpContext and szHelpSize members are not used by the control panel explorer in Windows CE for the Handheld PC.

For ldata, applications should return the icon resource ID for the control panel (same as hIcon, but the resource ID instead of the icon handle.)

See Also

CPLINFO, CPL_NEWINQUIRE


NM_HTMLVIEW

This structure is pointed to by the LPARAM of the WM_NOTIFY message sent by the HTML control. The NMHDR is the standard notification structure that contains information about the instance (HWND, and so on) sending the notification message. The definitions of the szTarget, szData, and dwCookie members vary with the specific HTML Control notification message.

At a Glance

Header file: | Htmlctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagNM_HTMLVIEW {
NMHDR hdr;
LPSTR szTarget;
LPSTR szData;
DWORD dwCookie;
} NM_HTMLVIEW;

Members

hdr
NMHDR structure identifying the window sending the notification message.
szTarget
Null-terminated string whose usage is unique to the notification message, as shown in the following table.
Value
Description
NM_HOTSPOT | String that contains the contents of the HREF member in the HTML text.
NM_INLINE_IMAGE | String that contains the text from the SRC parameter of the IMG tag in the HTML text.
NM_INLINE_SOUND | String that contains the text from the SRC parameter of the BGSOUND tag in the HTML text.
NM_META | String that contains the title of the HTML document.
NM_TITLE | String that contains the contents of the HTTP-EQUIV parameter of the META tag in the HTML document.

szData
Null-terminated string whose usage is unique to the notification message, as shown in the following table.
Value
Description
NM_HOTSPOT | String that contains the query data for a POST form submission.
NM_INLINE_IMAGE | Not used.
NM_INLINE_SOUND | Not used.
NM_META | String that contains the contents of the CONTENT parameter of the META tag in the HTML document.
NM_TITLE | Not used.

dwCookie
Contains a value whose usage is unique to the notification message, as shown in the following table.
Value
Description
NM_HOTSPOT | Not used.
NM_INLINE_IMAGE | Cookie value that must be passed from the application to the HTML control in the DTM_SETIMAGE or DTM_IMAGEFAIL message.
NM_INLINE_SOUND | Loop count value from the LOOP parameter of the BGSOUND tag.
NM_META | Not used.
NM_TITLE | Not used.

See Also

NM_HOTSPOT, NM_INLINE_IMAGE, NM_INLINE_SOUND, NM_META, NM_TITLE


NOTIFYICONDATA

This structure contains information that the system needs to process taskbar status area messages.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _NOTIFYICONDATA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
WCHAR szTip[64];
} NOTIFYICONDATA, *PNOTIFYICONDATA;

Members

cbSize
Size of this structure, in bytes.
hWnd
Handle to the window that will receive notification messages associated with an icon in the taskbar status area.
uID
Application-defined identifier of the taskbar icon.
uFlags
Array of flags that indicate which of the other members contain valid data. This member can be a combination of the following:
Value
Description
NIF_ICON | The hIcon member is valid.
NIF_MESSAGE | The uCallbackMessage member is valid.
NIF_TIP | The szTip member is valid.

uCallbackMessage
Application-defined message identifier. The system uses this identifier for notification messages that it sends to the window identified in hWnd. These notifications are sent when a mouse event occurs in the bounding rectangle of the icon.
hIcon
Handle to the icon to add, modify, or delete.
szTip
Null-terminated string that contains ToolTip text to display for the icon.


NUMBERFMT

This structure contains information that defines the format of a number string. The GetNumberFormat function uses this information to customize a number string for a specified locale.

At a Glance

Header file: | Winnls.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _numberfmt {
UINT NumDigits;
UINT LeadingZero;
UINT Grouping;
LPTSTR lpDecimalSep;
LPTSTR lpThousandSep;
UINT NegativeOrder;
} NUMBERFMT;

Members

NumDigits
Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.
LeadingZero
Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.
Grouping
Specifies the size of each group of digits to the left of the decimal. Values in the range 0 – 9 are valid.
lpDecimalSep
Long pointer to a null-terminated decimal separator string.
lpThousandSep
Long pointer to a null-terminated thousand separator string.
NegativeOrder
Specifies the negative number mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGNUMBER.

Remarks

For more information about the LCTYPE constants, see the Windows CE Programming Guide.

See Also

GetNumberFormat


OBJNOTIFY

This structure is used to notify the ActiveSync service provider that an object in the Windows CE file system has changed or been deleted.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagObjNotify{
UINT cbStruct;
OBJTYPENAME szObjType[ MAX_OBJTYPE_NAME ];
UINT uFlags;
UINT uPartnerBit;
CEOID oidObject;
CEOIDINFO oidInfo;
UINT cOidChg;
UINT cOidDel;
UINT *poid
} OBJNOTIFY, *POBJNOTIFY;

Members

cbStruct
[in] Size of the structure, in bytes.
SzObjType
[in] Null-terminated string that contains the name of the object type.
uFlags
[in] Unsigned integer that contains one of the following values:
ONF_FILE
The object is a file.
ONF_DIRECTORY
The object is a directory.
ONF_DATABASE
The object is a database.
ONF_RECORD
The object is a record.
ONF_CHANGED
Set if the file system object is changed.
ONF_DELETED
Set if the file system object is deleted.
ONF_CLEAR_CHANGE
Client should clear the change bit for the object whose object identifier is pointed at by poid.
ONF_CALL_BACK
[out] Client asks server to call ObjectNotify two seconds later.
ONF_CALLING_BACK
Set if this call is a result of ONF_CALL_BACK being set earlier.
uPartnerBit
[in] Specifies either 1 if the desktop currently connected is partner #1 or 2 if the desktop is partner #2.
oidObject
[in] Object identifier of the file system object, representing a file, a database, or a database record.
OidInfo
[in] Stores information about the object if the object has not been deleted.
cOidChg
[out] When ONF_CHANGED is set, this is the number of oid’s that should be replicated. Set to 0 if no object should be replicated because of this change.

When both ONF_CHANGED and ONF_DELETED are not set, this is the number of oid’s in the first part of the list for objects that are changed.

cOidDel
[out] When ONF_DELETED is set, this is the number of deleted oid’s that should be replicated. Set to 0 if no object should be replicated because of this delete.

When both ONF_CHANGED and ONF_DELETED are not set, this is the number of object identifiers in the later part of the list for objects that are not changed.

poid
[out] Pointer to an array of object identifiers that should be marked as needed for replication. The first cOidChg elements are for the changed objects, the last cOidDel elements are for the deleted objects. Memory pointed to by this pointer is owned by the ActiveSync service provider. It will not be freed by replication.

Remarks

This structure is passed to the ObjectNotify function to inform the provider that an event that changes or deletes an object in the Windows CE file system has occurred. The provider should return, by means of this structure, how many replication objects have changed or been deleted because of this change or deletion to a file system object.

When ONF_CHANGED is set, cOidChg is the number of object id’s in the list that should be synchronized (cOidDel is not used).

When ONF_DELETED is set, cOidDel is the number of deleted object id’s in the list that should be synchronized (cOidChg is not used).

See Also

ObjectNotify


OBJTYPEINFO

This structure is used to store information about an object type.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagObjTypeInfo {
UINT cbStruct;
OBJTYPENAMEW szObjType;
UINT uFlags;
WCHAR szName[ 80 ]
UINT cObjects;
UINT cbAllObj;
FILETIME ftLastModified
} OBJTPYEINFO, *POBJTYPEINFO;

Members

cbStruct
[in] Size of the structure in bytes.
szObjtype
[in] Null-terminated string that contains the name of the object type.
uFlags
Reserved.
szName
[out] Null-terminated string that contains the name of a file system object storing all these objects.
cObjects
[out] Number of existing objects of this type.
cbAllObj
[out] Total number of bytes used to store existing objects.
ftLastModified

[out] Specifies the last time any object was modified.


OBJUIDATA

This structure is used by IReplStore::GetObjTypeUIData to send UI related data about an object type to the Store.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagObjUIData{
 UINT cbStruct;
HICON hIconLarge;
HICON hIconSmall;
char szName[ MAX_PATH ];
char szSyncText[ MAX_PATH ];
char szTypeText[ 80 ];
char szPlTypeText[ 80 ];
} OBJUIDATA, *POBJUIDATA;

Members

cbStruct
Size of this structure.
hIconLarge
Handle of a large icon used in the list view display of the H/PC Explorer.
hIconSmall
Handle of a small icon used in the list view display of the H/PC Explorer.
szName
Null-terminated string that contains the text to be displayed in the “Name” column of the H/PC Explorer.
szSyncText
Null-terminated string that contains the text to be displayed in the “Sync Copy In” column of the H/PC Explorer.
szTypeText
Null-terminated string that contains the text to be displayed in the “Type” column of the H/PC Explorer.
szPlTypeText
Null-terminated string that contains the plural form of text to be displayed in the “Type” column of the H/PC Explorer.

See Also

IReplStore::GetObjTypeUIData


OFNOTIFY

This structure contains information about the WM_NOTIFY message sent to a hook procedure from an Explorer-style Open or Save As dialog box. The address of the OFNOTIFY structure is passed as the lParam parameter of the WM_NOTIFY message.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _OFNOTIFY {
NMHDR hdr;
LPOPENFILENAME lpOFN;
LPTSTR pszFile;
} OFNOTIFY, FAR *LPOFNOTIFY;

Members

hdr
NMHDR structure. The code member of the NMHDR structure can be one of the following notification codes that identify the message being sent: CDN_FILEOK, CDN_FOLDERCHANGE, CDN_HELP, CDN_INITDONE, CDN_SELCHANGE, CDN_SHAREVIOLATION, CDN_TYPECHANGE.
lpOFN
Long pointer to the OPENFILENAME structure that was specified when the Open or Save As dialog box was created. For some of the notification messages, this structure contains additional information about the event that caused the notification.
pszFile
Pointer to the null-terminated string that contains the file name for which a network sharing violation has occurred. This member is valid only with the CDN_SHAREVIOLATION notification message.

See Also

CDN_FILEOK, CDN_FOLDERCHANGE, CDN_HELP, CDN_INITDONE, CDN_SELCHANGE, CDN_SHAREVIOLATION, CDN_TYPECHANGE, NMHDR, OPENFILENAME


OPENFILENAME

This structure contains information the operating system uses to initialize the system-defined Open or Save As dialog box. After the user closes the dialog box, the system returns information about the user’s selection in this structure.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagOFN { /* ofn */
DWORD lStructSize;
HWND hwndOwner;
HINSTANCE hInstance;
LPCSTR lpstrFilter;
LPSTR lpstrCustomFilter;
DWORD nMaxCustFilter;
DWORD nFilterIndex;
LPSTR lpstrFile;
DWORD nMaxFile;
LPSTR lpstrFileTitle;
DWORD nMaxFileTitle;
LPSTR lpstrInitialDir;
LPCSTR lpstrTitle;
DWORD Flags;
WORD nFileOffset;
WORD nFileExtension;
LPCSTR lpstrDefExt;
DWORD lCustData;
LPOFNHOOKPROC lpfnHook;
LPCSTR lpTemplateName;
} OPENFILENAME;

Members

lStructSize
Specifies the length, in bytes, of the structure.
hwndOwner
Handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
hInstance
Not supported.
lpstrFilter
Long pointer to a buffer that contains pairs of null-terminated filter strings. The last string in the buffer must be terminated by two NULL characters.

The first string in each pair is a display string that describes the filter (for example, “Text Files”), and the second string specifies the filter pattern (for example, “*.TXT”). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, “*.TXT;*.DOC;*.BAK”). A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string.

The system does not change the order of the filters. It displays them in the File Types combo box in the order specified in lpstrFilter.

If lpstrFilter is NULL, the dialog box does not display any filters.

lpstrCustomFilter
Not supported.
nMaxCustFilter
Not supported.
nFilterIndex
Specifies the index of the currently selected filter in the File Types control. The buffer pointed to by lpstrFilter contains pairs of strings that define the filters. The first pair of strings has an index value of 1, the second pair 2, and so on. You can specify an index on input to indicate the initial filter description and filter pattern for the dialog box. When the user selects a file, nFilterIndex returns the index of the currently displayed filter.

If nFilterIndex is zero, the system uses the first filter in the lpstrFilter buffer.

lpstrFile
Long pointer to a buffer that contains a file name used to initialize the File Name edit control. The first character of this buffer must be NULL if initialization is not necessary. When the GetOpenFileName or GetSaveFileName function returns successfully, this buffer contains the drive designator, path, file name, and extension of the selected file.

If the buffer is too small, the function returns FALSE. In this case, the first two bytes of the lpstrFile buffer contain the required size, in bytes or characters.

nMaxFile
Specifies the size, in bytes (ANSI version) or 16-bit characters (Unicode version), of the buffer pointed to by lpstrFile. The GetOpenFileName and GetSaveFileName functions return FALSE if the buffer is too small to contain the file information. The buffer should be at least 256 characters long.
lpstrFileTitle
Long pointer to a buffer that receives the file name and extension (without path information) of the selected file. This member can be NULL.
nMaxFileTitle
Specifies the size, in bytes (ANSI version) or 16-bit characters (Unicode version), of the buffer pointed to by lpstrFileTitle. This member is ignored if lpstrFileTitle is NULL.
lpstrInitialDir
Long pointer to a string that specifies the initial file directory. If this member is NULL, the system uses the root directory.
lpstrTitle
Long pointer to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, Save As or Open).
Flags
A bitmask of flags used to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. This member can be a combination of the following flags:
OFN_ALLOWMULTISELECT
Not supported.
OFN_CREATEPROMPT
If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name; otherwise, the dialog box remains open.
OFN_ENABLEHOOK
Not supported.
OFN_ENABLESIZING
Not supported.
OFN_ENABLETEMPLATE
Not supported.
OFN_ENABLETEMPLATEHANDLE
Not supported.
OFN_EXPLORER
Ignored. The Explorer user interface is always used.
OFN_EXTENSIONDIFFERENT
Specifies that the user typed a file name extension that differs from the extension specified by lpstrDefExt. The function does not use this flag if lpstrDefExt is NULL.
OFN_FILEMUSTEXIST
Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OFN_PATHMUSTEXIST flag is also used.
OFN_HIDEREADONLY
Not supported.
OFN_LONGNAMES
Ignored. The Explorer user interface is always used.
OFN_NOCHANGEDIR
Not supported.
OFN_NODEREFERENCELINKS
Directs the dialog box to return the path and file name of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and file name of the file referenced by the shortcut
OFN_NOLONGNAMES
Not supported.
OFN_NONETWORKBUTTON
Not supported.
OFN_NOREADONLYRETURN
Not supported.
OFN_NOTESTFILECREATE
Not supported.
OFN_NOVALIDATE
Ignored. A file name is always validated.
OFN_OVERWRITEPROMPT
Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OFN_PATHMUSTEXIST
Specifies that the user can type only valid paths and file names. If this flag is used and the user types an invalid path and file name in the File Name entry field, the dialog box function displays a warning in a message box.
OFN_READONLY
Not supported.
OFN_SHAREAWARE
Not supported.
OFN_SHOWHELP
Not supported.
nFileOffset
Specifies the zero-based offset, in bytes (ANSI version) or 16-bit characters (Unicode version), from the beginning of the path to the file name in the string pointed to by lpstrFile. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member contains the value 13 to indicate the offset of the “file.ext” string.
nFileExtension
Specifies the zero-based offset, in bytes (ANSI version) or 16-bit characters (Unicode version), from the beginning of the path to the file name extension in the string pointed to by lpstrFile. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member contains the value 18. If the user did not type an extension and lpstrDefExt is NULL, this member specifies an offset to the terminating null character. If the user typed “.” as the last character in the file name, this member specifies zero.
lpstrDefExt
Long pointer to a buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to the file name if the user fails to type an extension. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). If this member is NULL and the user fails to type an extension, no extension is appended.
lCustData
Not supported.
lpfnHook
Not supported.
lpTemplateName
Not supported.

See Also

GetOpenFileName, GetSaveFileName


OSVERSIONINFO

This structure contains operating system version information. The information includes major and minor version numbers, a build number, a platform identifier, and descriptive text about the operating system. This structure is used with the GetVersionEx function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _OSVERSIONINFO{
DWORD dwOSVersionInfoSize;
DWORD dwMajorVersion;
DWORD dwMinorVersion;
DWORD dwBuildNumber;
DWORD dwPlatformId;
TCHAR szCSDVersion[128];
} OSVERSIONINFO;

Members

dwOSVersionInfoSize
Specifies the size, in bytes, of this data structure. Set this member to sizeof(OSVERSIONINFO) before calling the GetVersionEx function.
dwMajorVersion
Identifies the major version number of the operating system. For example, for Windows CE version 2.10, the major version number is 2.
dwMinorVersion
Identifies the minor version number of the operating system. For example, for Windows CE version 2.10, the minor version number is 1.
dwBuildNumber
Identifies the build number of the operating system or is set to 0.
dwPlatformId
Identifies the operating system platform. This member can be one of the following values:
VER_PLATFORM_WIN32s
Win32s on Windows 3.1.
VER_PLATFORM_WIN32_WINDOWS
Win32 on Windows 95 or Windows 98.

For Windows 95, dwMinorVersion is zero.

For Windows 98, dwMinorVersion is greater than zero.

VER_PLATFORM_WIN32_NT
Win32 on Windows NT.
VER_PLATFORM_WIN32_CE
Win32 on Windows CE.
szCSDVersion
Null-terminated string that provides arbitrary additional information about the operating system.

See Also

GetVersionEx


OUTPUT_DEBUG_STRING_INFO

This structure contains the address, format, and length, in bytes, of a debugging string.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _OUTPUT_DEBUG_STRING_INFO {
LPSTR lpDebugStringData;
WORD fUnicode;
WORD nDebugStringLength;
} OUTPUT_DEBUG_STRING_INFO;

Members

lpDebugStringData
Pointer to the debugging string in the calling process’s address space. The debugger can use the ReadProcessMemory function to retrieve the value of the string.
fUnicode
Specifies the format of the debugging string. If this member is zero, the debugging string is 8-bit ASCII; if it is nonzero, the string is 16-bit Unicode™.
nDebugStringLength
Specifies the length, in bytes, of the debugging string. The length includes the string’s terminating null character.

See Also

DEBUG_EVENT, ReadProcessMemory


PAGESETUPDLG

This structure contains information used by the PageSetupDlg function to initialize the Page Setup common dialog box.

For Windows CE versions 2.10 and later, this structure replaces the PRINTDLG structure.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.10 and later

Syntax

typedef struct tagPSD {
DWORD lStructSize;
HWND hwndOwner;
HGLOBAL hDevMode;
HGLOBAL hDevNames;
DWORD Flags;
POINT ptPaperSize;
RECT rtMinMargin;
RECT rtMargin;
HINSTANCE hInstance;
LPARAM lCustData;
LPPAGESETUPHOOK lpfnPageSetupHook;
LPPAGEPAINTHOOK lpfnPagePaintHook;
LPCTSTR lpPageSetupTemplateName;
HGLOBAL hPageSetupTemplate;
} PAGESETUPDLG, * LPPAGESETUPDLG;

Members

lStructSize
Specifies the size, in bytes, of this structure.
hwndOwner
Handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
hDevMode
Handle to a global memory object that contains a DEVMODE structure. On input, if a handle is given, the values in the corresponding DEVMODE structure are used to initialize the controls in the dialog box. On output, the dialog box sets hDevMode to a global memory handle for a DEVMODE structure that contains values specifying the user’s selections. If the user’s selections are not available, the dialog box sets hDevMode to NULL.
hDevNames
Handle to a global memory object that contains a DEVNAMES structure. This structure contains three strings that specify the driver name, the printer name, and the output port name. On input, if a handle is given, the strings in the corresponding DEVNAMES structure are used to initialize controls in the dialog box. On output, the dialog box sets hDevNames to a global memory handle for a DEVNAMES structure that contains strings specifying the user’s selections. If the user’s selections are not available, the dialog box sets hDevNames to NULL.
Flags
Set of bit flags that you can use to initialize the Page Setup common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. It can be a combination of the following flags:
PSD_DEFAULTMINMARGINS
Not supported.
PSD_DISABLEMARGINS
Disables the margin controls, preventing the user from setting the margins.
PSD_DISABLEORIENTATION
Disables the orientation controls, preventing the user from setting the page orientation.
PSD_DISABLEPAGEPAINTING
Not supported.
PSD_DISABLEPAPER
Disables the paper controls, preventing the user from setting page parameters such as the paper size and source.
PSD_DISABLEPRINTRANGE
In Windows CE, this flag disables the Print Range group box of the dialog box.
PSD_DISABLEPRINTER
Disables the Printer button, preventing the user from invoking a dialog box that contains additional printer setup information.
PSD_ENABLEPAGEPAINTHOOK
Not supported.
PSD_ENABLEPAGESETUPHOOK
Enables the hook procedure specified in the lpfnPageSetupHook member.
PSD_ENABLEPAGESETUPTEMPLATE
Indicates that the hInstance and lpPageSetupTemplateName members specify a dialog box template to use in place of the default template.
PSD_ENABLEPAGESETUPTEMPLATEHANDLE
Indicates that the hPageSetupTemplate member identifies a data block that contains a preloaded dialog box template. The system ignores the lpPageSetupTemplateName member if this flag is specified.
PSD_INHUNDREDTHSOFMILLIMETERS
Indicates that hundredths of millimeters are the unit of measurement for margins and paper size. The values in the rtMargin, rtMinMargin, and ptPaperSize members are in hundredths of millimeters. You can set this flag on input to override the default unit of measurement for the user’s locale. When the function returns, the dialog box sets this flag to indicate the units used.
PSD_INTHOUSANDTHSOFINCHES
Indicates that thousandths of inches are the unit of measurement for margins and paper size. The values in the rtMargin, rtMinMargin, and ptPaperSize members are in thousandths of inches. You can set this flag on input to override the default unit of measurement for the user’s locale. When the function returns, the dialog box sets this flag to indicate the units used.
PSD_INWININIINTLMEASURE
Not supported.
PSD_MARGINS
Causes the system to use the values specified in the rtMargin member as the initial widths for the left, top, right, and bottom margins. If PSD_MARGINS is not set, the system sets the initial widths to one inch for all margins.
PSD_MINMARGINS
Causes the system to use the values specified in the rtMinMargin member as the minimum allowable widths for the left, top, right, and bottom margins. The system prevents the user from entering a width that is less than the specified minimum. If PSD_MINMARGINS is not specified, the system sets the minimum allowable widths to those allowed by the printer.
PSD_NONETWORKBUTTON
Not supported.
PSD_NOWARNING
Not supported.
PSD_RANGESELECTION
In Windows CE, this flag sets the Selection button on the dialog box as the default print range. If PSD_RANGESELECTION is not set, the print range is set to the All button
PSD_RETURNDEFAULT
PageSetupDlg does not display the dialog box. Instead, it sets the hDevNames and hDevMode members to handles to DEVMODE and DEVNAMES structures that are initialized for the system default printer. PageSetupDlg returns an error if either hDevNames or hDevMode is not NULL.
PSD_SHOWHELP
Not supported.
ptPaperSize
Not supported.
rtMinMargin
Specifies the minimum allowable widths for the left, top, right, and bottom margins. The system ignores this member if the PSD_MINMARGINS flag is not set. These values must be less than or equal to the values specified in the rtMargin member. The PSD_INTHOUSANDTHSOFINCHES or PSD_INHUNDREDTHSOFMILLIMETERS flag indicates the units of measurement.
rtMargin
Specifies the widths of the left, top, right, and bottom margins. If you set the PSD_MARGINS flag, rtMargin specifies the initial margin values. When PageSetupDlg returns, rtMargin contains the margin widths selected by the user. The PSD_INHUNDREDTHSOFMILLIMETERS or PSD_INTHOUSANDTHSOFINCHES flag indicates the units of measurement.
hInstance
If the PSD_ENABLEPAGESETUPTEMPLATE flag is set in the Flags member, hInstance is the handle to the application or module instance that contains the dialog box template named by the lpPageSetupTemplateName member.
lCustData
Specifies application-defined data that the system passes to the hook procedure identified by the lpfnPageSetupHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the PAGESETUPDLG structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.
lpfnPageSetupHook
Long pointer to a PageSetupHook hook procedure that can process messages intended for the dialog box. This member is ignored unless the PSD_ENABLEPAGESETUPHOOK flag is set in the Flags member.
lpfnPagePaintHook
Not supported.
lpPageSetupTemplateName
Long pointer to a null-terminated string that names the dialog box template resource in the module identified by the hInstance member. This template is substituted for the standard dialog box template. For numbered dialog box resources, lpPageSetupTemplateName can be a value returned by the MAKEINTRESOURCE macro. This member is ignored unless the PSD_ENABLEPAGESETUPTEMPLATE flag is set in the Flags member.
hPageSetupTemplate
If the PSD_ENABLEPAGESETUPTEMPLATEHANDLE flag is set in the Flags member, hPageSetupTemplate is the handle to a memory object that contains a dialog box template.

Remarks

After the user closes the dialog box, the system returns information about the user-defined page members in this structure.

If the PSD_INHUNDREDTHSOFMILLIMETERS and PSD_INTHOUSANDTHSOFINCHES flags are not specified, the system queries the LOCALE_IMEASURE value of the default user locale to determine the unit of measure (either hundredths of millimeters or thousandths of inches) for the margin widths and paper size.

If both hDevNames and hDevMode have valid handles and the printer name specified by the wDeviceOffset member of the DEVNAMES structure is not the same as the name specified by the dmDeviceName member of the DEVMODE structure, the system uses the name specified by wDeviceOffset by default.

The PageSetupDlg function fills the DEVNAMES structure with byte offsets rather than the expected character offsets.

See Also

WM_INITDIALOG


PARAMDATA

This structure is used to describe a parameter accepted by a method or property.

At a Glance

Header file: | Oleauto.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagPARAMDATA {
OLECHAR FAR *szName;
VARTYPE vtReturn;
} PARAMDATA;

Members

szName
Null-terminated string that contains the parameter name. Names should follow standard conventions for programming language access; that is, no embedded spaces or control characters, and 32 or fewer characters. The name should be localized because each type description provides names for a particular locale.
vt
The VARTYPE that will be used by the receiver. If more than one parameter type is accepted, VT_VARIANT should be specified.


PARAMDESC

This structure is used for holding information for transferring a structure element, parameter, or function return value between processes.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagPARAMDESC {
unsigned long lpVarValue;
unsigned short wParamFlags;
};
} PARAMDESC;

The lpVarValue member contains a pointer to a VARIANT that describes the default value for this parameter, if the PARAMFLAG_FOPT and PARAMFLAG_FHASDEFAULT bit of wParamFlags is set.l.


PEG_USER_NOTIFICATION

This structure contains information used to initialize the user notifications settings dialog box, and receives the user’s notification preferences entered by way of the dialog box. Also used when setting a user notification. See CE_USER_NOTIFICATION.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct UserNotificationType {
DWORD ActionFlags;
TCHAR *pwszDialogTitle;
TCHAR *pwszDialogText;
TCHAR *pwszSound;
DWORD nMaxSound;
DWORD dwReserved;
} PEG_USER_NOTIFICATION, *PPEG_USER_NOTIFICATION;

Members

ActionFlags
Specifies the action to take when a notification event occurs. It can be a combination of the following flags.
PUN_LED
Flash the LED.
PUN_VIBRATE
Vibrate the device.
PUN_DIALOG
Display the user notification dialog box. When this structure is passed to the PegSetUserNotification function, the pwszDialogTitle and pwszDialogText members must provide the title and text of the dialog box.
PUN_SOUND
Play the sound specified by the pwszSound member. When passed to PSVN, the i member must provide the name of the sound file.
PUN_REPEAT
Repeat the pwszSound for 10–15 seconds. Only valid if PUN_SOUND is set.

Any flag that is not valid on the current hardware platform is ignored.

pwszDialogTitle
Pointer to a string that contains the title of the user notification dialog box. If this member is NULL, no dialog is displayed. The PegGetUserNotificationPreferences function ignores this member.
pwszDialogText
Pointer to the string that contains the text of the user notification dialog box. If this member is NULL, no dialog is displayed. The PegGetUserNotificationPreferences function ignores this member.
pwszSound
Pointer to a buffer that contains the unqualified name of a sound file to play. This member is ignored if the ActionFlags member does not include the PUN_SOUND flag.
nMaxSound
Specifies the maximum length of the string that the PegGetUserNotificationPreferences function can copy into the pwszSound buffer. Because the string may be a path name in a future release, the buffer must be at least the length derived by the following expression: PATH_MAX * sizeof(TCHAR). This member is ignored by the PegSetUserNotification function.
dwReserved
Reserved; set to zero.

Remarks

The PEG_USER_NOTIFICATION structure is passed in the PegGetUserNotificationPreferences function. Initial settings are used to populate the dialog. If the function returns TRUE, the returned settings should be saved, and considered when calling PegSetUserNotification. Settings for hardware not on the current device are ignored.

It is also used when calling PegSetUserNotification, to describe what should happen when the notification time is reached.

See Also

CeGetUserNotificationPreferences, CeSetUserNotification


PFF_CONVERTINFO

This structure contains information that the IPegasusFileFilter::NextConvertFile method uses to perform file conversions.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPFF_CONVERTINFO{
BOOL bImport;
HWND hwndParent;
BOOL bYesToAll;
IPegasusFileFilterSite *pffs;
} PFF_CONVERTINFO;

Members

bImport
Boolean that is nonzero if the conversion is importing files to the H/PC; otherwise, it is zero, which indicates the conversion is exporting files from the H/PC.
hwndParent
Handle to the window that a file filter can use as the parent window for a dialog box.
bYesToAll
Boolean that determines whether the Yes to All button is included in the Overwrite file? dialog box. This dialog box asks the user to verify that the destination file(s) should be overwritten. If there is more than one subconversion, the filter should set this member to TRUE to include the Yes to All button; otherwise, the filter should set this member to FALSE.
pffs
Pointer to an IPegasusFileFilterSite interface used for opening and closing files.

Remarks

This structure is supported by Windows CE version 1.0. For version 2.0 see CFF_CONVERTINFO.


PFF_DESTINATIONFILE

This structure contains information about a destination file. A file filter uses the information to write the converted data to the file.

At a Glance

Header file: | Replfilt.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPFF_DESTINATIONFILE{
TCHAR szFullpath[_MAX_PATH];
TCHAR szPath[_MAX_PATH];
TCHAR szFilename[_MAX_FNAME];
TCHAR szExtension[_MAX_EXT];
} PFF_DESTINATIONFILE;

Members

szFullpath
Null-terminated string that contains the default full path of the destination file, for example, “C:\Temp\Myfont.fnt.”
szPath
Null-terminated string that contains the path of the directory where the destination file should be created, for example, “C:\Temp.”
szFilename
Null-terminated string that contains only the default name of the destination file. For example, if the destination file name is Myfont.fnt, then the value of szFilename is “Myfont.”
szExtension
Null-terminated string that contains the file name extension of the destination file, for example, “fnt.”

Remarks

The szFullpath and szFilename members are described as i values since the file filter is allowed to modify the name of the destination file. For example, the Font file converter creates “Arial8.fnt” and “Arial10.fnt” from Arial.Ttf when the user selects the 8-point and 10-point font sizes. Note, however, that changing file names and creating multiple destination files only works when importing files from the desktop computer to the target device, and not when exporting files from the target device to the desktop computer.

Remarks

This structure is supported by Windows CE version 1.0. For version 2.0 see CFF_DESTINATIONFILE .


PFF_SOURCEFILE

This structure contains information about a source file. A file filter uses the information to locate the source file and read its contents.

At a Glance

Header file: | Replifilt.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPFF_SOURCEFILE {
TCHAR szFullpath[_MAX_PATH];
TCHAR szPath[_MAX_PATH];
TCHAR szFilename[_MAX_FNAME];
TCHAR szExtension[_MAX_EXT];
DWORD cbSize;
FILETIME ftCreated;
FILETIME ftModified;
} PFF_SOURCEFILE;

Members

szFullpath
Null-terminated string that contains the fully qualified path of the source file, for example, “C:\Temp\Myfont.fon.”
szPath
Null-terminated string that contains the path of the directory that contains the source file, for example, “C:\Temp.”
szFilename
Null-terminated string that contains only the name of the source file. For example, if the source file name is Myfont.fon, then the value of szFilename is “Myfont.”
szExtension
Null-terminated string that contains the file name extension of the source file, for example, “fon.”
cbSize
Specifies the size of the source file.
ftCreated
Specifies a FILETIME structure that indicates the time when the source file was created.
ftModified
Specifies a FILETIME structure that indicates the time when the file was last modified.

Remarks

This structure is supported by Windows CE version 1.0. For version 2.0 see CFF_SOURCEFILE .


POINTS

This structure defines the coordinates of a point.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPOINTS {
SHORT x;
SHORT y;
} POINTS;

Members

x
Specifies the x-coordinate of the point.
y
Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, PtInRect, WindowFromPoint, POINT


PRINTDLG

This structure contains information the PrintDlg function uses to initialize the Print common dialog box. After a user closes the dialog box, the system uses this structure to return information about the user’s print option selections.

For Windows CE versions 2.10 and later, this structure has been replaced by the PAGESETUPDLG structure.

At a Glance

Header file: | Commdlg.h
Windows CE versions: | 2.0 and 2.01

Syntax

typedef struct tagPD {
DWORD cbStruct;
HWND hwndOwner;
HDC hdc;
DWORD dwFlags;
RECT rcMinMargin;
RECT rcMargin;
HINSTANCE hinst;
LPARAM lCustData;
LPPRINTHOOKPROC pfnPrintHook;
LPCTSTR pszPrintTemplateName;
HGLOBAL hglbPrintTemplateResource;
} PRINTDLG , *LPPRINTDLG ;

Members

cbStruct
Specifies the structure size, in bytes.
hwndOwner
Handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
hdc
When PrintDlg returns, hdc contains the handle to the device context of the printer.
dwFlags
Specifies a bitmask of flags used to initialize the Print common dialog box. When the dialog box returns, it sets these flags to indicate the user’s input. It can be a combination of the following flags:
PD_SELECTALLPAGES
On input, this flag causes the All radio button to be selected when the dialog is created. On output, it indicates that the user selected the All radio button.
PD_SELECTSELECTION
On input, this flag causes the Selection radio button to be in the selected state when the dialog box is created. On output, it indicates that the user selected the Selection radio button. If this flag is not specified, the All radio button is selected by default.
PD_SELECTDRAFTMODE
Indicates the user selected the Draft mode check box.
PD_SELECTA4
Indicates the user selected “A4” size paper.
PD_SELECTLETTER
Indicates the user selected letter size paper.
PD_SELECTINFRARED
Indicates the user selected the infrared printer port.
PD_SELECTSERIAL
Indicates the user selected the serial printer port.
PD_DISABLEPAPERSIZE
Disables paper size selection.
PD_DISABLEPRINTRANGE
Disables print range selection.
PD_DISABLEMARGINS
Disables margin selection.
PD_DISABLEORIENTATION
Disables page orientation selection.
PD_RETURNDEFAULTDC
Returns the device context (DC) of the default printer without displaying the dialog.
PD_ENABLEPRINTHOOK
Enables the hook procedure specified in the pfnPrintHook member. This enables the hook procedure for the Print dialog box.
PD_ENABLEPRINTTEMPLATE
Indicates that the hinst and pszPrintTemplateName members specify a dialog box template to use in place of the default template for the Print dialog box.
PD_ENABLEPRINTTEMPLATEHANDLE
Indicates that the hglbPrintTemplateResource member identifies a data block that contains a preloaded dialog box template. The system uses this template in place of the default template for the Print dialog box. The system ignores the pszPrintTemplateName member if this flag is specified.
PD_SELECTPORTRAIT
On input, this flag specifies the Print dialog box should be initialized with Portrait orientation selected as the default. On output, this flag indicates that the user selected Portrait orientation.
PD_SELECTLANDSCAPE
On input, this flag specifies the Print dialog box should be initialized with Landscape orientation selected as the default. On output, this flag indicates the user selected Landscape orientation.
PD_MARGINS
On input, this flag specifies that the rcMargin member contains initial margin values. On output, it indicates that the rcMargin member contains user-specified margin values.

If this flag is not specified, the Print dialog box uses the default margins, which are 1 inch for the top and bottom margins and 1.25 inches for the left and right margins.

PD_INTHOUSANDTHSOFINCHES
Indicates the unit of measure in which margins are specified. If neither this flag nor the PD_INHUNDREDTHSOFMILLIMETERS flag is specified, the Print dialog box uses the LOCALE_IMEASURE setting in the locale table to determine whether to use the U.S. system of measurements or the metric system.
PD_INHUNDREDTHSOFMILLIMETERS
Indicates the unit of measure in which margins are specified. If neither this flag nor the PD_INHUNDREDTHSOFMILLIMETERS flag is specified, the Print dialog box uses the LOCALE_IMEASURE setting in the locale table to determine whether to use the U.S. system of measurements or the metric system.
PD_MINMARGINS
On input, this flag specifies that the rcMinMargin member contains initial minimum margin values. On output it indicates that the rcMinMargin member contains user-specified minimum margin values. If the value in the rcMinMargin member is zero on output, it means the user did not specify any minimum margin values.
rcMargin
Specifies the widths of the left, top, right, and bottom margins. If you set the PSD_MARGINS flag, rcMargin specifies the initial margin values. When PrintDlg returns, rcMargin contains the margin widths selected by the user. The PSD_INHUNDREDTHSOFMILLIMETERS or PSD_INTHOUSANDTHSOFINCHES flag indicates the units of measurement.
rcMinMargin
Specifies the minimum allowable widths for the left, top, right, and bottom margins. The system ignores this member if the PSD_MINMARGINS flag is not set. These values must be less than or equal to the values specified in the rcMargin member. The PSD_INTHOUSANDTHSOFINCHES or PSD_INHUNDREDTHSOFMILLIMETERS flag indicates the units of measurement.
hinst
Handle to the application or module instance that contains the dialog box template named by the pszPrintTemplateName member. This member is only valid if the PD_ENABLEPRINTTEMPLATE or PD_ENABLESETUPTEMPLATE flag is set in the dwFlags member.
lCustData
Specifies application-defined data that the system passes to the hook procedure identified by the pfnPrintHook member. When the system sends the WM_INITDIALOG message to the hook procedure, the message’s lParam parameter is a pointer to the PRINTDLG structure specified when the dialog was created. The hook procedure can use this pointer to get the lCustData value.
pfnPrintHook
Pointer to a PrintHookProc hook procedure that can process messages intended for the Print dialog box. This member is ignored unless the PD_ENABLEPRINTHOOK flag is set in the Flags member.
pszPrintTemplateName
Pointer to a null-terminated string that names a dialog box template resource in the module identified by the hinst member. This template is substituted for the standard Print dialog box template. This member is ignored unless the PD_ENABLEPRINTTEMPLATE flag is set in the Flags member.
hglbPrintTemplateResource
If the PD_ENABLEPRINTTEMPLATEHANDLE flag is set in the Flags member, hglbPrintTemplateResource is the handle to a memory object that contains a dialog box template. This template is substituted for the standard Print dialog box template.

Remarks

If the application does not specify the paper orientation, the Print dialog box reads the last paper orientation the user selected, which it saved to the registry. If there is no value in the registry, the dialog box selects portrait as the default. The dialog box also uses the last printer, port, and paper size the user selected. If these values are not in the registry, the dialog box selects the first printer, first port, and a paper size that is appropriate for the regional setting as the defaults.

See Also

PrintDlg, WM_INITDIALOG


PROCESS_INFORMATION

This structure is filled in by the CreateProcess function with information about a newly created process and its primary thread.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _PROCESS_INFORMATION {
HANDLE hProcess;
HANDLE hThread;
DWORD dwProcessId;
DWORD dwThreadId;
} PROCESS_INFORMATION;

Members

hProcess
Returns a handle to the newly created process. The handle is used to specify the process in all functions that perform operations on the process object.
hThread
Returns a handle to the primary thread of the newly created process. The handle is used to specify the thread in all functions that perform operations on the thread object.
dwProcessId
Returns a global process identifier that can be used to identify a process. The value is valid from the time the process is created until the time the process is terminated.
dwThreadId
Returns a global thread identifier that can be used to identify a thread. The value is valid from the time the thread is created until the time the thread is terminated.

See Also

CreateProcess


PROCESSENTRY32

This structure describes an entry from a list that enumerates the processes residing in the system address space when a snapshot was taken.

At a Glance

Header file: | Thelp32.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagPROCESSENTRY32 {
DWORD dwSize;
DWORD cntUsage;
DWORD th32ProcessID;
DWORD th32DefaultHeapID;
DWORD th32ModuleID;
DWORD cntThreads;
DWORD th32ParentProcessID;
LONG pcPriClassBase;
DWORD dwFlags;
TCHAR szExeFile[MAX_PATH];
DWORD th32MemoryBase;
DWORD th32AccessKey;
} PROCESSENTRY32;
typedef PROCESSENTRY32 * PPROCESSENTRY32;
typedef PROCESSENTRY32 * LPPROCESSENTRY32;

Members

dwSize
Specifies the length, in bytes, of the structure. Before calling the Process32First function, set this member to sizeof(PROCESSENTRY32). If you do not initialize dwSize, Process32First will fail.
cntUsage
Number of references to the process. Must be 1.
th32ProcessID
Identifier of the process. The contents of this member can be used by Win32 API elements.
th32DefaultHeapID
Identifier of the default heap for the process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by Win32 API elements.
th32ModuleID
Module identifier of the process. Must be 0.
cntThreads
Number of execution threads started by the process.
th32ParentProcessID
Identifier of the process that created the process being examined. Must be 0.
pcPriClassBase
Base priority of any threads created by this process. Value is always THREAD_PRIORITY_NORMAL
dwFlags
Reserved; do not use.
szExeFile
Null-terminated string that contains the path and file name of the executable file for the process.
Th32memoryBase
Load address of the executable file.
th32AccessKey
Array of bits. Each bit signifies permission to see the address space of one process. For the PROCESSENTRY32 structure, the key contains the bit required to see that address space.

Remarks

All strings are Unicode.


RAPIINIT

This structure contains information used to initialize a RAPI connection.

At a Glance

Header file: | Rapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RAPIINIT {
DWORD cbSize;
HANDLE heRapiInit;
HANDLE hrRapiInit;
} RAPIINIT;

Members

cbSize
Specifies the size of the RAPIINIT structure being passed in.
heRapiInit
Specifies a handle to an event. The event is set when the RAPI connection is made or an error occurs.
hrRapiInit
Specifies the results, success or failure, of the RAPI connection.

See Also

CeRapiInitEx


RECT

This structure defines the coordinates of the upper-left and lower-right corners of a rectangle.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _RECT {
LONG left;
LONG top;
LONG right;
LONG bottom;
} RECT;

Members

left
Specifies the x-coordinate of the upper-left corner of the rectangle.
top
Specifies the y-coordinate of the upper-left corner of the rectangle.
right
Specifies the x-coordinate of the lower-right corner of the rectangle.
bottom
Specifies the y-coordinate of the lower-right corner of the rectangle.

Remarks

When RECT is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels. This structure is identical to the RECTL structure.

See Also

FillRect


REPLSETUP

This structure is used to initiate the object handler.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagReplSetup{
 UINT cbStruct;
BOOL fRead;
DWORD dwFlags;
HRESULT hr;
TCHAR szObjType[ MAX_OBJTYPE_NAME ];
IReplNotify *pNotify;
DWORD oid;
DWORD oidNew;
IReplStore *pStore ;
HREPLFLD hFolder;
HREPLITEM hItem;
} REPLSETUP, *PREPLSETUP;

Members

cbStruct
[in] Size of this structure
fRead
[in] Boolean that is set to TRUE if setting up for reading (serializing) the object, or to FALSE if setting up for writing (deserializing) the object.
dwFlags
[in] Reserved by replication.
Hr
[out] Result of the read/write operation.
szObjType
[in] Null-terminated string that contains the name of the object type.
pNotify
[in] Pointer to IReplNotify::IUnknown interface.
Oid
[in] Identifier of the object.
oidNew
[out] Identifier of the new object. This is different from the object identifier if a new object was created during writing.
pStore
[in] Pointer to IReplStore interface. This parameter exists in the desktop computer only. It is unused for device side use.
hFolder
[in] Handle to the folder. This parameter exists in the desktop computer only. It is unused for device side use.
hItem
[in/out] Handle to the object to be read or written. This parameter exists in the desktop computer only. It is unused for device side use.

See Also

IReplObjHandler::Setup


SAFEARRAY

This structure holds a safe array and its attributes.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagSAFEARRAY {
unsigned short cDims;
unsigned short fFeatures;
unsigned short cbElements;
unsigned short cLocks;
unsigned long handle;
void HUGEP *pvData;
SAFEARRAYBOUND rgsabound[1];
} SAFEARRAY;

Members

cDims
Count of dimensions in this array.
fFeatures
Flags used by the SafeArray routines.
cbElements
Size of an element of the array. Does not include size of pointed-to data.
cLocks
Number of times the array has been locked without corresponding unlock. cbElements
cLocks
handle
Unused, but kept for compatibility.
pvData;
Void pointer to the data.
rgsabound
One bound for each dimension.

Remarks

The array rgsabound is stored with the left-most dimension in rgsabound[0] and the right-most dimension in rgsabound[cDims – 1]. If an array was specified in a C-like syntax as a [2][5], it would have two elements in the rgsabound vector. Element 0 has an lLbound of 0 and a cElements of 2. Element 1 has an lLbound of 0 and a cElements of 5.

The fFeatures flags describe attributes of an array that can affect how the array is released. This allows freeing the array without referencing its containing variant. The bits are accessed using the following constants:

#define FADF_AUTO 0x0001 // Array is allocated on the stack.
#define FADF_STATIC 0x0002 // Array is statically allocated.
#define FADF_EMBEDDED 0x0004 // Array is embedded in a structure.
#define FADF_FIXEDSIZE 0x0010 // Array may not be resized or
 // reallocated.
#define FADF_BSTR 0x0100 // An array of BSTRs.
#define FADF_UNKNOWN 0x0200 // An array of IUnknown*.
#define FADF_DISPATCH 0x0400 // An array of IDispatch*.
#define FADF_VARIANT 0x0800 // An array of VARIANTs.
#define FADF_RESERVED 0xF0E8 // Bits reserved for future use.


SAFEARRAYBOUDN

SAFEARRAYBOUND

This structure represents the bounds of one dimension of the safe array.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagSAFEARRAYBOUND {
unsiggned long cElements;
long lLbound;
} SAFEARRAYBOUND;


SCROLLINFO

This structure contains scroll bar parameters to be set by the SetScrollInfo function or retrieved by the GetScrollInfo function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagSCROLLINFO { // si
UINT cbSize;
UINT fMask;
int nMin;
int nMax;
UINT nPage;
int nPos;
int nTrackPos;
} SCROLLINFO;
typedef SCROLLINFO FAR *LPSCROLLINFO;

Members

cbSize
Specifies the size, in bytes, of this structure.
fMask
Specifies the scroll bar parameters to set or retrieve. It can be a combination of the following values:
SIF_ALL
Combination of SIF_PAGE, SIF_POS, SIF_RANGE, and SIF_TRACKPOS.
SIF_DISABLENOSCROLL
This value is used only when setting a scroll bar’s parameters. If the scroll bar’s new parameters make the scroll bar unnecessary, disable the scroll bar instead of removing it.
SIF_PAGE
The nPage member contains the page size for a proportional scroll bar.
SIF_POS
The nPos member contains the scroll box position, which is not updated while the user drags the scroll box.
SIF_RANGE
The nMin and nMax members contain the minimum and maximum values for the scrolling range.
SIF_TRACKPOS
The nTrackPos member contains the current position of the scroll box while the user is dragging it.
nMin
Specifies the minimum scrolling position.
nMax
Specifies the maximum scrolling position.
nPage
Specifies the page size. A scroll bar uses this value to determine the appropriate size of the proportional scroll box.
nPos
Specifies the position of the scroll box.
nTrackPos
Specifies the immediate position of a scroll box that the user is dragging. An application can retrieve this value while processing the SB_THUMBTRACK notification message. An application cannot set the immediate scroll position; the SetScrollInfo function ignores this member.

See Also

SBM_GETSCROLLINFO, SBM_SETSCROLLINFO, GetScrollInfo, SetScrollInfo


SHELLEXECUTEINFO

This structure specifies an enumerated type that defines flags used with the IShellFolder::EnumObjects method.

The SHELLEXECUTEINFO structure contains information used by the ShellExecuteEx function.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _SHELLEXECUTEINFO {
DWORD cbSize;
ULONG fMask;
HWND hwnd;
LPCSTR lpVerb;
LPCSTR lpFile;
LPCSTR lpParameters;
LPCSTR lpDirectory;
int nShow;
HINSTANCE hInstApp;

// Optional members
LPVOID lpIDList;
LPCSTR lpClass;
HKEY hkeyClass;
DWORD dwHotKey;
HANDLE hIcon;
HANDLE hProcess;
} SHELLEXECUTEINFO, FAR *LPSHELLEXECUTEINFO;

Members

cbSize
Size of the structure, in bytes.
fMask
Array of flags that indicate the content and validity of the other structure members. For Windows CE versions 1.0 and 1.01, fMask flags are unsupported. For Windows CE versions 2.0 and later, fMask can be a combination of the following values:
SEE_MASK_FLAG_NO_UI
Does not display an error message box if an error occurs.
SEE_MASK_NOCLOSEPROCESS
Leaves the process running after the ShellExecuteEx function exits. The hProcess member receives the handle to the process.
hwnd
Window handle to any message boxes that the system may produce while executing this function.
lpVerb
Long pointer to a string specifying the name of a verb. The verb specifies an action for the application to perform. The set of available verbs depends on the particular file or folder. It includes the commands listed in the context menu and the registry. This member defaults to Open if no verb is specified. The following verbs are usually valid:
edit
Opens an editor. If lpFile is not a document file, the function will fail.
explore
The function explores the folder specified by lpFile.
open
The function opens the file specified by the lpFile parameter. The file can be an executable file or a document file. It can also be a folder.
print
The function prints the document file specified by lpFile. If lpFile is not a document file, the function will fail.
properties
Displays the file or folder's properties.
lpFile
Long pointer to a null-terminated string that specifies the name of the file to open or print. The function can open an executable file or a document file, but it can only print a document file. If the path is not included with the name, the current directory is assumed.
lpParameters
Long pointer to a null-terminated string that contains the application parameters. The parameters must be separated by spaces. To include double quotation marks, you must enclose the marks in double quotation marks, as in the following code example:
sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

In this case, the application receives three parameters: An, example:, and “quoted text”.

If the lpFile member specifies a document file, this member should be NULL.

lpDirectory
Pointer to a null-terminated string that specifies the name of the working directory. If this member is not specified, the current directory is used as the working directory.
nShow
Show flags. Can be one of the SW_* values described for the ShowWindow function. If the lpFile specifies an executable file, this member specifies how the application is to be shown when it is opened.
hInstApp
Instance handle to the application that the ShellExecuteEx function started. If the function fails, this member receives one of the following error values, which are less than or equal to 32:
SE_ERR_FNF
File not found.
SE_ERR_PNF
Path not found.
SE_ERR_ACCESSDENIED
Access denied.
SE_ERR_OOM
Out of memory.
SE_ERR_DLLNOTFOUND
Dynamic-link library not found.
SE_ERR_SHARE
Cannot share an open file.
SE_ERR_ASSOCINCOMPLETE
File association information not complete.
SE_ERR_DDETIMEOUT
DDE operation timed out.
SE_ERR_DDEFAIL
DDE operation failed.
SE_ERR_DDEBUSY
DDE operation is busy.
SE_ERR_NOASSOC
File association not available.
lpIDList
Ignored.
lpClass
Ignored.
hkeyClass
Ignored.
dwHotKey
Ignored.
hIcon
Ignored.
hProcess
Handle to the newly started application. This member is set on return and is always NULL if fMask is not set to SEE_MASK_NOCLOSEPROCESS.

See Also

ITEMIDLIST, ShellExecuteEx, ShowWindow


SHFILEINFO

This structure contains information about a file object.

At a Glance

Header file: | Shellapi.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _SHFILEINFO {
HICON hIcon;
int iIcon;
DWORD dwAttributes;
char szDisplayName[MAX_PATH];
char szTypeName[80];
} SHFILEINFO;

Members

hIcon
Handle to the icon that represents the file.
iIcon
Index of the icon image within the system image list.
dwAttributes
Specifies the attributes of the file object.
szDisplayName
Null-terminated string that contains the name of the file as it appears in the Windows shell, or the path and file name of the file that contains the icon representing the file.
szTypeName
Null-terminated string that describes the type of file.

Remarks

This structure is used with the SHGetFileInfo function.


SIPINFO

This structure contains information about the current state of the input panel, such as the input panel size, screen location, docked status, and visibility status.

At a Glance

Header file: | Sipapi.h (Sip_api.idl for Palm-size PC)
Windows CE versions: | 2.01 and later

Syntax

typedef struct {
DWORD cbSize;
DWORD fdwFlags;
RECT rcVisibleDesktop;
RECT rcSipRect;
DWORD dwImDataSize;
VOID *pvImData;
} SIPINFO;

Members

cbSize
Size, in bytes, of the SIPINFO structure. This member must be filled in by the application with the sizeof operator. Because the system can check the size of the structure to determine the operating system version number, this member allows for future enhancements to the SIPINFO structure while maintaining backward compatibility.
fdwFlags
Specifies flags representing state information of the input panel. It is any combination of the following bit flags:
SIPF_ON
The input panel is on, or visible.
SIPF_DOCKED
The input panel is docked, or not floating.
SIPF_LOCKED
The input panel is locked, meaning that the user cannot change its visible status.
rcVisibleDesktop
Rectangle, in screen coordinates, that represents the area of the desktop not obscured by the input panel. If the input panel is floating, this rectangle is equivalent to the working area. Full-screen applications that respond to input panel size changes can set their window rectangle to this rectangle. If the input panel is docked but does not occupy an entire edge, then this rectangle represents the largest rectangle not obscured by the input panel. If an application wants to use the screen space around the input panel, it needs to reference rcSipRect.
rcSipRect
Rectangle, in screen coordinates, the represents the size and location of the input panel. An application does not generally use this information unless it needs to wrap around a floating or a docked input panel that does not occupy an entire edge.
dwImDataSize
Specifies the size of the data pointed to by the pvImData member.
pvImData
Void pointer to input method (IM)-defined data. The IM calls the IInputMethod::GetImData and IInputMethod::SetImData methods to send and receive information from this structure.

Remarks

For the Palm-size PC version 1.0, SHSipInfo can either set a SIPINFO structure with the current input panel state, or take a SIPINFO structure and use its values to set the current input panel state. Call SipSetInfo to achieve the same results in Windows CE versions 2.10 and later.

SIPINFO is also used by an application and an IM to send and receive IM-specific information. The IM receives information about the SIPINFO function through the IInputMethod::GetSipInfo method.


SIZE

This structure specifies the width and height of a rectangle.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagSIZE {
LONG cx;
LONG cy;
} SIZE;

Members

cx
Specifies the rectangle’s width.
cy
Specifies the rectangle’s height.

Remarks

The rectangle dimensions stored in this structure may correspond to viewport extents, window extents, text extents, bitmap dimensions, or the aspect-ratio filter for some extended functions.


SORTORDERSPEC

This structure contains information about a sort order in a database.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _SORTORDERSPEC {
CEPROPID propid;
DWORD dwFlags;
} SORTORDERSPEC;

Members

propid
Identifier of the property to be sorted on. Sorts on binary properties are not allowed.
dwFlags
Specifies the sort flags. It is one or a combination of the following flags:
CEDB_SORT_DESCENDING
The sort is done in descending order. By default, the sort is done in ascending order.
CEDB_SORT_CASEINSENSITIVE
The sort operation is case insensitive. This value is valid only for strings.
CEDB_SORT_UNKNOWNFIRST
Records that do not contain this property are placed before all the other records. By default, such records are placed after all other records.
CEDB_SORT_GENERICORDER
The default sort order—ascending order, case sensitive—is used. Records that do not contain the sort property are placed at the end of the list.

Remarks

The system supports only simple sorts on a primary key. Records with the same key value are be sorted in arbitrary order.

See Also

CeCreateDatabase, CeDBASEINFO


STATSTG

The STATSTG structure contains statistical information about an open storage, stream, or byte array object. This structure is used in the IEnumSTATSTG, ILockBytes, IStorage, and IStream interfaces.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagSTATSTG {
LPOLESTR pwcsName;
DWORD type;
ULARGE_INTEGER cbSize;
FILETIME mtime;
FILETIME ctime;
FILETIME atime;
DWORD grfMode;
DWORD grfLocksSupported;
CLSID clsid;
DWORD grfStateBits;
DWORD reserved;
} STATSTG;

Members

pwcsName
Points to a NULL-terminated string containing the name. Space for this string is allocated by the method called and freed by the caller (refer to CoTaskMemFree). You can specify not to return this member by specifying the STATFLAG_NONAME value when you call a method that returns a STATSTG structure, except for calls to IEnumSTATSTG::Next, which provides no way to specify this value.
type
Indicates the type of storage object. This is one of the values from the STGTY enumeration.
cbSize
Specifies the size in bytes of the stream or byte array.
mtime
Indicates the last modification time for this storage, stream, or byte array.
ctime
Indicates the creation time for this storage, stream, or byte array.
atime
Indicates the last access time for this storage, stream or byte array.
grfMode
Indicates the access mode specified when the object was opened. This member is only valid in calls to Stat methods.
grfLocksSupported
Indicates the types of region locking supported by the stream or byte array. See the LOCKTYPES enumeration for the values available. This member is not used for storage objects.
clsid
Indicates the class identifier for the storage object; set to CLSID_NULL for new storage objects. This member is not used for streams or byte arrays.
grfStateBits
Indicates the current state bits of the storage object, that is, the value most recently set by the IStorage::SetStateBits method. This member is not valid for streams or byte arrays.
reserved
Reserved for future use.

See Also

IStorage::SetElementTimes


STGMEDIUM

This structure describes a medium of transfer for data objects.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagSTGMEDIUM {
unsigned long tymed;
union {
Handle hGlobal;
char *lpszFileName;
LPSTREAM pstm;
LPSTORAGE pstg;
};
LPUNKNOWN pUnkForRelease;
} STGMEDIUM;

Members

tymed
Type of storage medium. The marshaling and unmarshaling routines use this value to determine which union member was used. This value must be one of the elements of the TYMED enumeration.
union member
Handle, string, or interface pointer that the receiving process can use to access the data being transferred. If tymed is TYMED_NULL, the union member is undefined; otherwise, it is one of the following:
hBitmap
Handle to a bitmap. The tymed member is TYMED_GDI.
hMetaFilePict
Handle to a metafile. The tymed member is TYMED_MFPICT.
hEnhMetaFile
Handle to an enhanced metafile. The tymed member is TYMED_ENHMF.
hGlobal
Global memory handle. The tymed member is TYMED_HGLOBAL.
lpszFileName
Long pointer to the null-terminated string that contains the path of a disk file that contains the data. The tymed member is TYMED_FILE.
pstm
Pointer to an IStream interface. The tymed member is TYMED_ISTREAM.
pstg
Pointer to an IStorage interface. The tymed member is TYMED_ISTORAGE.
pUnkForRelease
Pointer to an interface instance that allows the sending process to control the way the storage is released when the receiving process calls the ReleaseStgMedium function. If pUnkForRelease is NULL, ReleaseStgMedium uses default procedures to release the storage; otherwise, ReleaseStgMedium uses the specified IUnknown interface.

Remarks

Th string you pass in the lpszFileName member must be allocated by using either GlobalAlloc or malloc.

See Also

TYMED


STORE_INFORMATION

This structure contains the size of the object store and the amount of free space currently in the object store.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct STORE_INFORMATION {
DWORD dwStoreSize;
DWORD dwFreeSize;
} STORE_INFORMATION, *LPSTORE_INFORMATION;

Members

dwStoreSize
Specifies the size, in bytes, of the object store.
dwFreeSize

Specifies the amount of free space, in bytes, in the object store.


STOREINFO

This structure is used to identify an instance of the store.

At a Glance

Header file: | Cesync.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagStoreInfo {
UINT cbStruct;
UINT uFlags;
TCHAR szProgId[ 256 ];
TCHAR szStoreDesc[ 200 ];
UINT uTimerRes;
UINT cbMaxStoreId;
UINT cbStoreId;
LPBYTE lpbStoreId;
} STOREINFO, *PSTOREINFO;

Members

cbStruct
[in] Size of this structure
uFlags
[out] Combination of the following flags:
SCF_SINGLE_THREAD
Set if the implementation only supports single thread operation.
SCF_SIMULATE_RTS
Set if the implementation wants to simulate detection of real-time change/deletes
szProgId
[out] Null-terminated string that contains the name of the programmatic identifier of the store object.
szStoreDesc
[out] Null-terminated string that contains the description of the store, to be displayed to the user.
uTimerRes
[in/out] Resolution of timer in micro-seconds. 5,000 by default. Applicable only when SCF_SIMULATE_RTS is set in uFlags.
cbMaxStoreId
[in] Maximum size of the store identifier that can be stored in buffer pointed by lpbStoreId.
cbStoreId
[out] Actual size of the store identifier stored in buffer pointed by lpbStoreId
lpbStoreId
[out] Long pointer to a buffer of anything that uniquely identifies the current store instance, for example, a schedule file.

Remarks

Calls to the IReplStore interface methods can come from different threads. If the client does not support multi-threading, it must set fSingleThreadOnly to FALSE, so the server will serialize the calls to the methods and make them all come from the primary thread of the application. szStoreDesc can have a value such as “Schedule+ File”. It is displayed to the user whenever the store identifier indicates a different store, such as a different Schedule+ file, has been installed.

See Also

IReplStore::GetStoreInfo


STYLESTRUCT

This structure contains the window styles for a window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagSTYLESTRUCT {
DWORD styleOld;
DWORD styleNew;
} STYLESTRUCT, * LPSTYLESTRUCT;

Members

style
Specifies an array of window style or extended-style flags.

See Also

WM_STYLECHANGED


SYSTEM_INFO

This structure contains information about the current computer system. This includes the processor type, page size, original equipment manufacturer (OEM) identifier, and other such information.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _SYSTEM_INFO {
DWORD dwOemId;
struct {
WORD wProcessorArcheitecture;
WORD wReserved;
}
DWORD dwPageSize;
LPVOID lpMinimumApplicationAddress;
LPVOID lpMaximumApplicationAddress;
DWORD dwActiveProcessorMask;
DWORD dwNumberOfProcessors;
DWORD dwProcessorType;
DWORD dwAllocationGranularity;
WORD wProcessorLevel;
WORD wProcessorRevision;
} SYSTEM_INFO, *LPSYSTEM_INFO;

Members

dwOemId
An obsolete member that is not used by Windows CE.
wProcessorArchitecture
Specifies the system’s processor architecture. It is no longer relevant. Use the wProcessorArchitecture, wProcessorLevel, and wProcessorRevision members to determine the type of processor.
  • PROCESSOR_ARCHITECTURE_INTEL
  • PROCESSOR_ARCHITECTURE_MIPS
  • PROCESSOR_ARCHITECTURE_ALPHA
  • PROCESSOR_ARCHITECTURE_PPC
  • PROCESSOR_ARCHITECTURE_UNKNOWN
dwReserved
Reserved for future use.
dwPageSize
Specifies the page size and the granularity of page protection and commitment. This is the page size used by the VirtualAlloc function.
lpMinimumApplicationAddress
Pointer to the lowest memory address accessible to applications and dynamic-link libraries (DLLs).
lpMaximumApplicationAddress
Pointer to the highest memory address accessible to applications and DLLs.
dwActiveProcessorMask
Specifies a mask representing the set of processors configured into the system. Bit 0 is processor 0; bit 31 is processor 31.
dwNumberOfProcessors
Specifies the number of processors in the system.
dwProcessorType
Specifies the type of processor in the system. This member is no longer relevant. Use the wProcessorArchitecture, wProcessorLevel, and wProcessorRevision members to determine the type of processor.

This member is one of the following values:

  • PROCESSOR_INTEL_386
  • PROCESSOR_INTEL_486
  • PROCESSOR_INTEL_PENTIUM
  • PROCESSOR_INTEL_486
  • PROCESSOR_MIPS_R3000
  • PROCESSOR_MIPS_R4000
  • PROCESSOR_HITACHI_SH3
  • PROCESSOR_HITACHI_SH4
  • PROCESSOR_PPC_403
  • PROCESSOR_PPC_821
  • PROCESSOR_STRONGARM
  • PROCESSOR_ARM720
dwAllocationGranularity
Specifies the granularity with which virtual memory is allocated. For example, a VirtualAlloc request to allocate 1 byte will reserve an address space of dwAllocationGranularity bytes. This value was hard coded as 64K in the past, but other hardware architectures may require different values.
wProcessorLevel
Specifies the system’s architecture-dependent processor level.

If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_INTEL, wProcessorLevel can be one of the following values:

4
Intel 80486
5
Pentium

If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_MIPS, wProcessorLevel is of the form 00XX, where XX is an 8-bit implementation number (bits 8-15 of the PRId register). The member can be the following value:

3
MIPS R3000
0004
MIPS R4000

If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_PPC, wProcessorLevel is of the form XXXX, where XXXXis a 16-bit processor version number (the high-order 16 bits of the Processor Version Register).

wProcessorRevision
Specifies an architecture-dependent processor revision. The following table shows how the revision value is assembled for each type of processor architecture.
Intel 80386 or 80486
A value of the form xxyz.

If xx is equal to 0xFF, y - 0xA is the model number, and z is the stepping identifier. For example, an Intel 80486-D0 system returns 0xFFD0.

If xx is not equal to 0xFF, xx + ‘A’ is the stepping letter and yz is the minor stepping.

Intel Pentium, Cyrix, or NextGen 586
A value of the form xxyy, where xx is the model number and yy is the stepping. For example, a value of 0x0201 indicates Model 2, Stepping 1.
MIPS
A value of the form 00xx, where xx is the 8-bit revision number of the processor (the low-order 8 bits of the PRId register).
ALPHA
A value of the form xxyy, where xxyy is the low-order 16 bits of the processor revision number from the firmware. Display this value as follows:

Model ‘A’+xx, Pass yy

PPC
A value of the form xxyy, where xxyy is the low-order 16 bits of the Processor Version Register. Display this value as a fixed point number:

xx.yy

See Also

GetSystemInfo


SYSTEM_POWER_STATUS_EX

This structure contains information about the power status of the system.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _SYSTEM_POWER_STATUS_EX {
BYTE ACLineStatus;
BYTE BatteryFlag;
BYTE BatteryLifePercent;
BYTE Reserved1;
DWORD BatteryLifeTime;
DWORD BatteryFullLifeTime;
BYTE Reserved2;
BYTE BackupBatteryFlag;
BYTE BackupBatteryLifePercent;
BYTE Reserved3;
DWORD BackupBatteryLifeTime;
DWORD BackupBatteryFullLifeTime;
} SYSTEM_POWER_STATUS_EX, *PSYSTEM_POWER_STATUS_EX, *LPSYSTEM_POWER_STATUS_EX;

Members

ACLineStatus
AC power status. It is one of the following values:
0
Offline
1
Online
255
Unknown status

All other values are reserved.

BatteryFlag
Battery charge status. It can be a combination of the following values:
1
High
2
Low
4
Critical
8
Charging
128
No system battery
255
Unknown status

All other values are reserved.

BatteryLifePercent
Percentage of full battery charge remaining. This member can be a value in the range 0 to 100, or 255 if status is unknown. All other values are reserved.
Reserved1
Reserved; set to zero.
BatteryLifeTime
Number of seconds of battery life remaining, or 0xFFFFFFFF if remaining seconds are unknown.
BatteryFullLifeTime
Number of seconds of battery life when at full charge, or 0xFFFFFFFF if full lifetime is unknown.
Reserved2
Reserved; set to zero.
BackupBatteryFlag
Backup battery charge status. It is one of the following values:
BATTERY_FLAG_HIGH
BATTERY_FLAG_CRITICAL
BATTERY_FLAG_CHARGING
BATTERY_FLAG_NO_BATTERY
BATTERY_FLAG_UNKNOWN
BATTERY_FLAG_LOW

BackupBatteryLifePercent
Percentage of full backup battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN.
Reserved3
Reserved; set to zero
BackupBatteryLifeTime
Number of seconds of backup battery life remaining, or BATTERY_LIFE_UNKNOWN if remaining seconds are unknown.
BackupBatteryFullLifeTime
Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full lifetime is unknown.


SYSTEM_POWER_STATUS_EX2

This structure contains information about the power status of the system.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.12 and later

Syntax

typedef struct _SYSTEM_POWER_STATUS_EX2 {
BYTE ACLineStatus;
BYTE BatteryFlag;
BYTE BatteryLifePercent;
BYTE Reserved1;
DWORD BatteryLifeTime;
DWORD BatteryFullLifeTime;
BYTE Reserved2;
BYTE BackupBatteryFlag;
BYTE BackupBatteryLifePercent;
BYTE Reserved3;
DWORD BackupBatteryLifeTime;
DWORD BackupBatteryFullLifeTime;
WORD BatteryVoltage;
DWORD BatteryCurrent;
DWORD BatteryAverageCurrent;
DWORD BatteryAverageInterval;
DWORD BatterymAHourConsumed;
DWORD BatteryTemperature;
DWORD BackupBatteryVoltage;
BYTE BatteryChemistry;
} SYSTEM_POWER_STATUS_EX2, *PSYSTEM_POWER_STATUS_EX2, *LPSYSTEM_POWER_STATUS_EX2;

Members

ACLineStatus
AC power status. It is one of the following values:
  • AC_LINE_OFFLINE
  • AC_LINE_ONLINE
  • AC_LINE_BACKUP_POWER
  • AC_LINE_UNKNOWN
BatteryFlag
Battery charge status. It is one of the following values:
  • BATTERY_FLAG_HIGH
  • BATTERY_FLAG_LOW
  • BATTERY_FLAG_CRITICAL
  • BATTERY_FLAG_CHARGING
  • BATTERY_FLAG_NO_BATTERY
  • BATTERY_FLAG_UNKNOWN
BatteryLifePercent
Percentage of full battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN if percentage of battery life remaining is unknown.
Reserved1
Must be zero.
BatteryLifeTime
Number of seconds of battery life remaining, or BATTERY_LIFE_UNKNOWN if number of seconds of battery life remaining is unknown.
BatteryFullLifeTime
Number of seconds of battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full lifetime of battery is unknown.
Reserved2
Must be zero.
BackupBatteryFlag
Backup battery charge status. It is one of the following values:
  • BATTERY_FLAG_HIGH
  • BATTERY_FLAG_LOW
  • BATTERY_FLAG_CRITICAL
  • BATTERY_FLAG_CHARGING
  • BATTERY_FLAG_NO_BATTERY
  • BATTERY_FLAG_UNKNOWN
BackupBatteryLifePercent
Percentage of full backup battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN if percentage of backup battery life remaining is unknown.
Reserved3
Must be zero.
BackupBatteryLifeTime
Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if number of seconds of backup battery life remaining is unknown.
BackupBatteryFullLifeTime
Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full lifetime of backup battery is unknown.
BatteryVoltage
Number of millivolts (mV) of battery voltage. It can range from 0 to 65535.
BatteryCurrent
Number of milliamps (mA) of instantaneous current drain. It can range from 0 to 32767 for charge and 0 to –32768 for discharge.
BatteryAverageCurrent
Average number of milliamps of short term device current drain. It can range from 0 to 32767 for charge and 0 to –32768 for discharge.
BatteryAverageInterval
Number of milliseconds (mS) that is the time constant interval used in reporting BatteryAverageCurrent.
BatterymAHourConsumed
Average number of milliamp hours (mAh) of long-term cumulative average discharge. It can range from 0 to –32768. This value is reset when the batteries are charged or changed.
BatteryTemperature
Battery temperature reported in 0.1 degree Celsius increments. It can range from –3276.8 to 3276.7.
BackupBatteryVoltage
Number of millivolts (mV) of backup battery voltage. It can range from 0 to 65535.
BatteryChemistry
Type of battery. It can be one of the following values:
  • BATTERY_CHEMISTRY_ALKALINE
  • BATTERY_CHEMISTRY_NICD
  • BATTERY_CHEMISTRY_NIMH
  • BATTERY_CHEMISTRY_LION
  • BATTERY_CHEMISTRY_LIPOLY
  • BATTERY_CHEMISTRY_UNKNOWN

See Also

GetSystemPowerStatus


SYSTEMTIME

This structure represents a date and time using individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _SYSTEMTIME { // st
WORD wYear;
WORD wMonth;
WORD wDayOfWeek;
WORD wDay;
WORD wHour;
WORD wMinute;
WORD wSecond;
WORD wMilliseconds;
} SYSTEMTIME;

Members

wYear
Specifies the current year.
wMonth
Specifies the current month; January = 1, February = 2, and so on.
wDayOfWeek
Specifies the current day of the week; Sunday = 0, Monday = 1, and so on.
wDay
Specifies the current day of the month.
wHour
Specifies the current hour.
wMinute
Specifies the current minute.
wSecond
Specifies the current second.
wMilliseconds
Specifies the current millisecond.

Remarks

It is not recommended that you add and subtract values from the SYSTEMTIME structure to obtain relative times. Instead, you should

  • Convert the SYSTEMTIME structure to a FILETIME structure.
  • Copy the resulting FILETIME structure to a ULARGE_INTEGER structure.
  • Use normal 64-bit arithmetic on the ULARGE_INTEGER value.

See Also

GetLocalTime, GetSystemTime, SetLocalTime, SetSystemTime, FILETIME


THREADENTRY32

This structure describes an entry from a list that enumerates the threads executing in the system when a snapshot was taken.

At a Glance

Header file: | Thelp32.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagTHREADENTRY32{
DWORD dwSize;
DWORD cntUsage;
DWORD th32ThreadID;
DWORD th32OwnerProcessID;
LONG tpBasePri;
LONG tpDeltaPri;
DWORD dwFlags;
DWORD th32AccessKey;
DWORD th32CurrentProcessID;
} THREADENTRY32;
typedef THREADENTRY32 * PTHREADENTRY32;
typedef THREADENTRY32 * LPTHREADENTRY32;

Members

dwSize
Specifies the length, in bytes, of the structure. Before calling the Thread32First function, set this member to sizeof(THREADENTRY32). If you do not initialize dwSize, Thread32First will fail.
cntUsage
Number of references to the thread. A thread exists as long as its usage count is nonzero. As soon as its usage count becomes zero, a thread terminates.
th32ThreadID
Identifier of the thread. This identifier is compatible with the thread identifier returned by the CreateProcess function.
th32OwnerProcessID
Identifier of the process that created the thread. The contents of this member can be used by Win32 API elements.
tpBasePri
Initial priority level assigned to a thread. This member can be one of the following values:
THREAD_PRIORITY_IDLE
Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes.
THREAD_PRIORITY_LOWEST
Indicates 2 points below normal priority for the priority class.
THREAD_PRIORITY_BELOW_NORMAL
Indicates 1 point below normal priority for the priority class.
THREAD_PRIORITY_NORMAL
Indicates normal priority for the priority class.
THREAD_PRIORITY_ABOVE_NORMAL
Indicates 1 point above normal priority for the priority class.
THREAD_PRIORITY_HIGHEST
Indicates 2 points above normal priority for the priority class.
THREAD_PRIORITY_TIME_CRITICAL
Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes.
tpDeltaPri
Change in the priority level of a thread. This value is a signed delta from the base priority level assigned to the thread.
dwFlags
Reserved; do not use.

Remarks

Windows CE supports the following additional members:

th32AccessKey
Array of bits. Each bit signifies permission to see the address space of one process. In the THREADENTRY32 structure, the key contains the bits the thread currently has, thus defining the processes it can currently see.
th32CurrentProcessID
Process identifier where the thread is executing.


TIME_ZONE_INFORMATION

This structure specifies information specific to the time zone.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _TIME_ZONE_INFORMATION {
LONG Bias;
WCHAR StandardName[32];
SYSTEMTIME StandardDate;
LONG StandardBias;
WCHAR DaylightName[32];
SYSTEMTIME DaylightDate;
LONG DaylightBias;
} TIME_ZONE_INFORMATION;

Members

Bias
Specifies the current bias, in minutes, for local time translation on this computer. The bias is the difference, in minutes, between Coordinated Universal Time (UTC) and local time. All translations between UTC and local time are based on the following formula:
UTC = local time + bias

This member is required.

StandardName
Specifies a null-terminated string associated with standard time on this operating system. For example, this member could contain “EST” to indicate Eastern Standard Time. This string is not used by the operating system, so anything stored there by using the SetTimeZoneInformation function is returned unchanged by the GetTimeZoneInformation function. This string can be empty.
StandardDate
Specifies a SYSTEMTIME structure that contains a date and local time when the transition from daylight time to standard time occurs on this operating system. If this date is not specified, the wMonth member in the SYSTEMTIME structure must be zero. If this date is specified, the DaylightDate value in the TIME_ZONE_INFORMATION structure must also be specified.

This member supports two date formats. Absolute format specifies an exact date and time when standard time begins. In this form, the wYear, wMonth, wDay, wHour, wMinute, wSecond, and wMilliseconds members of the SYSTEMTIME structure are used to specify an exact date.

Day-in-month format is specified by setting the wYear member to zero, setting the wDayOfWeek member to an appropriate weekday, and using a wDay value in the range 1 through 5 to select the correct day in the month. Using this notation, the first Sunday in April can be specified, as can the last Thursday in October (5 is equal to “the last”).

StandardBias
Specifies a bias value to be used during local time translations that occur during standard time. This member is ignored if a value for the StandardDate member is not supplied.

This value is added to the value of the Bias member to form the bias used during standard time. In most time zones, the value of this member is zero.

DaylightName
Specifies a null-terminated string associated with daylight time on this operating system. For example, this member could contain “PDT” to indicate Pacific Daylight Time. This string is not used by the operating system, so anything stored there by using the SetTimeZoneInformation function is returned unchanged by the GetTimeZoneInformation function. This string can be empty.
DaylightDate
Specifies a SYSTEMTIME structure that contains a date and local time when the transition from standard time to daylight time occurs on this operating system. If this date is not specified, the wMonth member in the SYSTEMTIME structure must be zero. If this date is specified, the StandardDate value in the TIME_ZONE_INFORMATION structure must also be specified. This member supports the absolute and day-in-month time formats described for the StandardDate member.
DaylightBias
Specifies a bias value to be used during local time translations that occur during daylight time. This member is ignored if a value for the DaylightDate member is not supplied.

This value is added to the value of the Bias member to form the bias used during daylight time. In most time zones, the value of this member is –60.

See Also

GetTimeZoneInformation, SetTimeZoneInformation, SYSTEMTIME


TPMPARAMS

This structure contains extended parameters for the TrackPopupMenuEx function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct tagTPMPARAMS {
UINT cbSize;
RECT rcExclude;
} TPMPARAMS, FAR *LPTPMPARAMS;

Members

cbsize
Size of structure, in bytes.
rcExclude
Rectangle to exclude when positioning the window, in screen coordinates.

See Also

TrackPopupMenuEx, Rectangle


TYPEATTR

This structure is used to hold attributes of an ITypeInfo interface.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagTYPEATTR {
GUID guid;
LCID lcid;
unsigned long dwReserved;
MEMBERID memidConstructor;
MEMBERID memidDestructor;
OLECHAR FAR *lpstrSchema;
unsigned long cbSizeInstance;
TYPEKIND typekind;
unsigned short cFuncs;
unsigned short cVars;
unsigned short cImplTypes;
unsigned short cbAlignment;
unsigned short wTypeFlags;
unsigned short wMajorVerNum;
unsigned short wMinorVerNum;
TYPEDESC tdescAlias;
IDLDESC idldescType;
} TYPEATTR, FAR *LPTYPEATTR;

Members

guid
Globally unique identifier (GUID) of the type information.
lcid
Locale of member names and doc strings.
dwReserved
Reserved.
memidConstructor
Identifier of constructor, or MEMBERID_NIL if none.
memidDestructor
Identifier of destructor, or MEMBERID_NIL if none.
lpstrSchema
Reserved for future use.
cbSizeInstance
Size of an instance of this type.
typekind
Kind of type this information describes.
cFuncs
Number of functions.
cVars
Number of variables/data members.
cImplTypes
Number of implemented interfaces.
cbSizeVft
The size of this type’s VTBL.
cbAlignment
Byte alignment for an instance of this type.
wTypeFlags
wMajorVerNum
Major version number.
wMinorVerNum
Minor version number.
descAlias
If typekind == TKIND_ALIAS, specifies the type for which this type is an alias.
idldescType
IDL attributes of the described type.

Remarks

The cbAlignment member indicates how addresses are aligned. A value of 0 indicates alignment on the 64 KB boundary; 1 indicates no special alignment. For other values, n indicates aligned on byte n.


TYPEDESC

This structure is used to describe the type of a variable, the return type of a function, or the type of a function parameter.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagTYPEDESC {
union {ESC FAR *lptdesc;
struct FARSTRUCT ta
struct FARSTRUCT tagTYPEDgARAYDESC FAR *lpadesc;
HREFTYPE hreftype;
} UNION_NAME(u);
VARTYPE vt;
} TYPEDESC;

Members

lptdesc
VT_CARRAY.
lpadesc
VT_USERDEFINED is used to get type information for a user-defined type.
hreftype
vt

Remarks

If the variable is VT_SAFEARRAY or VT_PTR, the union portion of the TYPEDESC contains a pointer to a TYPEDESC that specifies the element type.


UDACCEL

This structure contains acceleration information for an up-down control.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct {
int nSec;
int nInc;
} UDACCEL;

Members

nSec
Amount of elapsed time, in seconds, before the position change increment specified by nInc is used.
nInc
Position change increment to use after the time specified by nSec elapses.

See Also

UDM_GETACCEL, UDM_SETACCEL


ULARGE_INTEGER

This union provides a 64-bit data type which is accessible as two DWORDs or as a single DWORDLONG.

At a Glance

Header file: | Wtype.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct ULARGE_INTEGER {
ULONGLONG QuadPart;
} ULARGE_INTEGER;

Members

LowPart
Specifies the low-order 32 bits.
HighPart
Specifies the high-order 32 bits.
QuadPart
Specifies a 64-bit unsigned integer.

Remarks

The ULARGE_INTEGER structure is actually a union. If your compiler has built-in support for 64-bit integers, use the QuadPart member to store the 64-bit integer. Otherwise, use the LowPart and HighPart members to store the 64-bit integer.


UNLOAD_DLL_DEBUG_INFO

This structure contains information about a dynamic-link library (DLL) that has just been unloaded.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct _UNLOAD_DLL_DEBUG_INFO {
LPVOID lpBaseOfDll;
} UNLOAD_DLL_DEBUG_INFO;

Members

lpBaseOfDll
Long pointer to the base address of the DLL in the address space of the process unloading the DLL.

See Also

DEBUG_EVENT


VARDESC

This structure describes a variable, constant, or data member.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct FARSTRUCT tagVARDESC {
MEMBERID memid;
OLECHAR FAR *lpstrSchema;
union {
unsigned long oInst;
VARIANT FAR *lpvarValue;
} UNION_NAME(u);
ELEMDESC elemdescVar;
unsigned short wVarFlags;
VARKIND varkind;
} VARDESC

Members

memid
lpstrSchema
Reserved for future use.
oInst
VAR_CONST, the value of the constant.
lpvarValue
elemdescVar
wVarFlags
varkind


VARIANT and VARIANTARG

This structure is used to describe arguments passed within DISPPARAMS, and VARIANT to specify variant data that cannot be passed by reference. The VARIANT type cannot have the VT_BYREF bit set.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef struct tagVARIANT {
VARTYPE vt;
unsigned short wReserved1;
unsigned short wReserved2;
unsigned short wReserved3;
union {
unsigned char bVal;
short iVal;
long lVal;
float fltVal;.
double dblVal;
VARIANT_BOOL boolVal;
SCODE scode;
CY cyVal;
DATE date;
BSTR bs trVal;
IUnknown FAR* punkVal;
IDispatch FAR* pdispVal;
SAFEARRAY FAR* pa rray;
unsigned char FAR* pbVal;
short FAR* piVal;
long FAR* plVal;
float FAR* pfltVal;
double FAR* pdblVal;
VARIANT_BOOL FAR* pboolVal;
SCODE FAR* pscode;
CY FAR* pcyVal;
DATE FAR* pdate;
BSTR FAR* pbstrVal;
IUnknown FAR* FAR* ppunkVal;
IDispatch FAR* FAR* ppdispVal;
SAFEARRAY FAR* FAR* pparray;
VARIANT FAR* pvarVal;
void FAR* byref;
};
};
typedef struct FARSTRUCT tagVARIANT VARIANT;
typedef struct FARSTRUCT tagVARIANT VARIANTARG;

Members

vt
wReserved1
wReserved2
wReserved3
bVal
VT_UI1.
iVal
VT_I2.
lVal
VT_I4.
fltVal
VT_R4.
dblVal
VT_R8.
boolVal
VT_BOOL.
scode
VT_ERROR.
cyVal
VT_CY.
date
VT_DATE.
bstrVal
VT_BSTR.
punkVal
VT_UNKNOWN.
pdispVal
VT_DISPATCH.
parray
VT_ARRAY | *.
pbVal
VT_BYREF | VT_UI1.
piVal
VT_BYREF | VT_I2.
plVal
VT_BYREF | VT_I4.
pfltVal
VT_BYREF | VT_R4.
pdblVal
VT_BYREF | VT_R8.
pboolVal
VT_BYREF | VT_BOOL.
pscode
VT_BYREF | VT_ERROR.
pcyVal
VT_BYREF | VT_CY.
pdate
VT_BYREF | VT_DATE.
pbstrVal
VT_BYREF | VT_BSTR.
ppunkVal;
VT_BYREF | VT_UNKNOWN.
ppdispVal;
VT_BYREF | VT_DISPATCH.
pparray;
VT_ARRAY | *.
pvarVal
VT_BYREF | VT_VARIANT.
byref
Generic ByRef

Return Values

To simplify extracting values from VARIANTARGs, Automation provides a set of functions for manipulating this type. Use of these functions is strongly recommended to ensure that applications apply consistent coercion rules.

The vt value governs the interpretation of the union as follows:

VT_EMPTY
No value was specified. If an optional argument to an Automation method is left blank, do not pass a VARIANT of type VT_EMPTY. Instead, pass a VARIANT of type VT_ERROR with a value of DISP_E_PARAMNOTFOUND.
VT_EMPTY | VT_BYREF
Not valid.
VT_UI1
An unsigned 1-byte character is stored in bVal.
VT_UI1 | VT_BYREF
A reference to an unsigned 1-byte character was passed. A pointer to the value is in pbVal.
VT_I2
A 2-byte integer value is stored in iVal.
VT_I2 | VT_BYREF
A reference to a 2-byte integer was passed. A pointer to the value is in piVal.
VT_I4
A 4-byte integer value is stored in lVal.
VT_I4 | VT_BYREF
A reference to a 4-byte integer was passed. A pointer to the value is in plVal.
VT_R4
An IEEE 4-byte real value is stored in fltVal.
VT_R4 | VT_BYREF
A reference to an IEEE 4-byte real value was passed. A pointer to the value is in pfltVal.
VT_R8
An 8-byte IEEE real value is stored in dblVal.
VT_R8 | VT_BYREF
A reference to an 8-byte IEEE real value was passed. A pointer to its value is in pdblVal.
VT_CY
A currency value was specified. A currency number is stored as an 8-byte, two's complement integer, scaled by 10,000 to give a fixed-point number with 15 digits to the left of the decimal point and 4 digits to the right. The value is in cyVal.
VT_CY | VT_BYREF
A reference to a currency value was passed. A pointer to the value is in pcyVal.
VT_BSTR
A string was passed; it is stored in bstrVal. This pointer must be obtained and freed by the BSTR functions.
VT_BSTR | VT_BYREF
A reference to a string was passed. A BSTR* that points to a BSTR is in pbstrVal. The referenced pointer must be obtained or freed by the BSTR functions.
VT_NULL
A propagating null value was specified. (This should not be confused with the null pointer.) The null value is used for tri-state logic, as with SQL.
VT_NULL | VT_BYREF
Not valid.
VT_ERROR
An SCODE was specified. The type of the error is specified in scodee. Generally, operations on error values should raise an exception or propagate the error to the return value, as appropriate.
VT_ERROR | VT_BYREF
A reference to an SCODE was passed. A pointer to the value is in pscode.
VT_BOOL
A Boolean (True/False) value was specified. A value of 0xFFFF (all bits 1) indicates True; a value of 0 (all bits 0) indicates False. No other values are valid.
VT_BOOL | VT_BYREF
A reference to a Boolean value. A pointer to the Boolean value is in pbool.
VT_DATE
A value denoting a date and time was specified. Dates are represented as double-precision numbers, where midnight, January 1, 1900 is 2.0, January 2, 1900 is 3.0, and so on. The value is passed in date.

This is the same numbering system used by most spreadsheet programs, although some specify incorrectly that February 29, 1900 existed, and thus set January 1, 1900 to 1.0.

VT_DATE | VT_BYREF
A reference to a date was passed. A pointer to the value is in pdate.
VT_DISPATCH
A pointer to an object was specified. The pointer is in pdispVal. This object is known only to implement IDispatch. The object can be queried as to whether it supports any other desired interface by calling QueryInterface on the object. Objects that do not implement IDispatch should be passed using VT_UNKNOWN.
VT_DISPATCH | VT_BYREF
A pointer to a pointer to an object was specified. The pointer to the object is stored in the location referred to by ppdispVal.
VT_VARIANT
Invalid. VARIANTARGs must be passed by reference.
VT_VARIANT | VT_BYREF
A pointer to another VARIANTARG is passed in pvarVal. This referenced VARIANTARG will never have the VT_BYREF bit set in vt, so only one level of indirection can ever be present. This value can be used to support languages that allow functions to change the types of variables passed by reference.
VT_UNKNOWN
A pointer to an object that implements the IUnknown interface is passed in punkVal.
VT_UNKNOWN | VT_BYREF
A pointer to the IUnknown interface is passed in ppunkVal. The pointer to the interface is stored in the location referred to by ppunkVal.
VT_ARRAY | <anything>
An array of data type <anything> was passed. (VT_EMPTY and VT_NULL are invalid types to combine with VT_ARRAY.) The pointer in pbyrefVal points to an array descriptor, which describes the dimensions, size, and in-memory location of the array.


VARTYPE

This is an enumeration type used in VARIANT, TYPEDESC, OLE property sets, and safe arrays.

The enumeration constants listed in the following VARENUM section are valid in the vt member of a VARIANT structure.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef unsigned short VARTYPE;
enum VARENUM{
VT_EMPTY = 0, // Not specified
VT_NULL = 1, // NULL
VT_I2 = 2, // 2-byte signed int
VT_I4 = 3, // 4-byte signed int
VT_R4 = 4, // 4-byte real
VT_R8 = 5, // 8-byte real
VT_CY = 6, // Currency
VT_DATE = 7, // Date
VT_BSTR = 8, // Binary string
VT_DISPATCH = 9, // IDispatch FAR*
VT_ERROR = 10, // Scodes
VT_BOOL = 11, // Boolean; True=-1, False=0
VT_VARIANT = 12, // VARIANT FAR*
VT_UNKNOWN = 13, // IUnknown FAR*
VT_UI1 = 17, // Unsigned char

// Other constants that are not valid in VARIANTs omitted here.

};
VT_RESERVED = (int) 0x8000 // By reference, a pointer to the data is passed
VT_BYREF = (int) 0x4000
VT_ARRAY = (int) 0x2000 // A safe array of the data is passed


WIN32_FIND_DATA

This structure describes a file found by the FindFirstFile or FindNextFile function.

At a Glance

Header file: | Winbase.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _WIN32_FIND_DATA {
DWORD dwFileAttributes;
FILETIME ftCreationTime;
FILETIME ftLastAccessTime;
FILETIME ftLastWriteTime;
DWORD nFileSizeHigh;
DWORD nFileSizeLow;
DWORD dwOID;
TCHAR cFileName[MAX_PATH];
} WIN32_FIND_DATA;

Members

dwFileAttributes
Specifies the file attributes of the file found. It can be one or more of the following values:
FILE_ATTRIBUTE_ARCHIVE
The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
The handle identifies a directory.
FILE_ATTRIBUTE_ENCRYPTED
The file or directory is encrypted. For a file, this means that all data streams are encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN
The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_INROM
This file is an operating system file stored in ROM. These files are read-only; they cannot be modified.
FILE_ATTRIBUTE_NORMAL
The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE
The file data is not immediately available. Indicates that the file data has been physically moved to offline storage.
FILE_ATTRIBUTE_READONLY
The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_REPARSE_POINT
The file has an associated reparse point.
FILE_ATTRIBUTE_ROMMODULE
This file is an operating system file stored in ROM and executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file, instead the LoadLibrary and CreateProcess functions must be used.
FILE_ATTRIBUTE_ROMSTATICREF
The file is a DLL module that has a static reference from at least one other file that is in the modules section of the image. A file having this attribute can not replace the functionality of the DLL with a RAM copy of the same DLL. A file having this attribute must also have the FILE_ATTRIBUTE_INROM and FILE_ATTRIBUTE_ROMMODULE attributes.
FILE_ATTRIBUTE_SPARSE_FILE
The file is a sparse file.
FILE_ATTRIBUTE_SYSTEM
The file or directory is part of the operating system or is used exclusively by the operating system.
FILE_ATTRIBUTE_TEMPORARY
The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access, rather than flushing it back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
ftCreationTime
Specifies a FILETIME structure containing the time the file was created. FindFirstFile and FindNextFile report file times in Coordinated Universal Time (UTC) format. These functions set the FILETIME members to zero if the file system containing the file does not support this time member. You can use the FileTimeToLocalFileTime function to convert from UTC to local time, and then use the FileTimeToSystemTime function to convert the local time to a SYSTEMTIME structure containing individual members for the month, day, year, weekday, hour, minute, second, and millisecond.
ftLastAccessTime
Specifies a FILETIME structure containing the time that the file was last accessed. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.
ftLastWriteTime
Specifies a FILETIME structure containing the time that the file was last written to. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.
nFileSizeHigh
Specifies the high-order DWORD value of the file size, in bytes. This value is zero unless the file size is greater than MAXDWORD. The size of the file is equal to (nFileSizeHigh * MAXDWORD) + nFileSizeLow.
nFileSizeLow
Specifies the low-order DWORD value of the file size, in bytes.
dwOID
Specifies the object identifier of the file.
cFileName
Null-terminated string that is the name of the file.

Remarks

If a file has a long file name, the complete name appears in the cFileName member, and the 8.3 format truncated version of the name appears in the cAlternateFileName member. Otherwise, cAlternateFileName is empty. As an alternative, you can use the GetShortPathName function to find the 8.3 format version of a file name.

See Also

FindFirstFile, FindNextFile, FILETIME, FileTimeToLocalFileTime, FileTimeToSystemTime


WINDOWPOS

This structure contains information about the size and position of a window.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

typedef struct _WINDOWPOS {
HWND hwnd;
HWND hwndInsertAfter;
int x;
int y;
int cx;
int cy;
UINT flags;
} WINDOWPOS;

Members

hwnd
Handle to the window.
hwndInsertAfter
Specifies the position of the window in z-order (front-to-back position). This member can be a handle to the window behind which this window is placed, or can be one of the special values listed with the SetWindowPos function.
x
Specifies the position of the left edge of the window.
y
Specifies the position of the top edge of the window.
cx
Specifies the window width, in pixels.
cy
Specifies the window height, in pixels.
flags
Specifies the window position. It is one of the following values:
SWP_DRAWFRAME
Draws a frame (defined in the window’s class description) around the window.
SWP_FRAMECHANGED
Sends a WM_NCCALCSIZE message to the window, even if the window’s size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window’s size is being changed.
SWP_HIDEWINDOW
Hides the window.
SWP_NOACTIVATE
Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter member).
SWP_NOCOPYBITS
Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE
Retains the current position (ignores the X and Y members).
SWP_NOOWNERZORDER
Does not change the owner window’s position in the Z order.
SWP_NOREDRAW
Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION
Same as the SWP_NOOWNERZORDER flag.
SWP_NOSENDCHANGING
Prevents the window from receiving the WM_WINDOWPOSCHANGING message.
SWP_NOSIZE
Retains the current size (ignores the cx and cy members).
SWP_NOZORDER
Retains the current z-order (ignores the hWndInsertAfter member).
SWP_SHOWWINDOW
Displays the window.

Windows CE Remarks

In Windows CE, the WINDOWPOS structure does not support the following flags in the Flags member.

  • SWP_DRAWFRAME
  • SWP_NOCOPYBITS
  • SWP_NOOWNERZORDER
  • SWP_NOREDRAW
  • SWP_NOREPOSITION
  • SWP_NOSENDCHANGING

Windows CE versions 2.0 and later support all flags.

See Also

SetWindowPos


DB_CEOID_CHANGED

This message is sent when an object in the object store has been modified.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.01 and later

Syntax

DB_CEOID_CHANGED oidChanged = (CEOID) wParam;
oidParent = (CEOID) lParam;

Parameters

oidChanged
Identifier of the object that was modified.
oidParent
Identifier of the parent object of the modified object.

Remarks

When writing applications for Windows CE version 1.0, use the DB_PEGOID_CHANGED message.

See Also

CeOpenDatabase


DB_CEOID_CREATED

This message is sent when a new object is created in the object store.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.01 and later

Syntax

DB_CEOID_CREATED oidCreated = (CEOID) wParam;
oidParent = (CEOID) lParam;

Parameters

oidCreated
Identifier of the newly created object.
oidParent
Identifier of the parent object of the newly created object.

Remarks

When writing applications for Windows CE version 1.0, use the DB_PEGOID_CREATED message.

See Also

CeOpenDatabase


DB_CEOID_RECORD_DELETED

This message is sent when a record has been deleted from the object store.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.0 and later

Syntax

DB_CEOID_RECORD_DELETED oidDeletedRec = (CEOID) wParam;
oidParent = (CEOID) lParam;

Parameters

oidDeletedRec
Identifier of the record that was deleted.
oidParent
Identifier of the parent object of the deleted record.

See Also

CeOpenDatabase


DB_PEGOID_CHANGED

This message is sent when an object in the object store has been modified. See DB_CEOID_CHANGED.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.0 and later

Syntax

DB_PEGOID_CHANGED oidChanged = (PEGOID) wParam;
oidParent = (PEGOID) lParam;

Parameters

oidChanged
Identifier of the object that was modified.
oidParent
Identifier of the parent object of the modified object.

See Also

CeOpenDatabase


DB_PEGOID_CREATED

This message is sent when a new object is created in the object store. See DB_CEOID_CREATED.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.0 and later

Syntax

DB_PEGOID_CREATED oidCreated = (PEGOID) wParam;
oidParent = (PEGOID) lParam;

Parameters

oidCreated
Identifier of the newly created object.
oidParent
Identifier of the parent object of the newly created object.

See Also

CeOpenDatabase


DB_PEGOID_RECORD_DELETED

This message is sent when a record has been deleted from the object store.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.0 and later

Syntax

DB_PEGOID_RECORD_DELETED oidDeletedRec = (PEGOID) wParam;
oidParent = (PEGOID) lParam;

Parameters

oidDeletedRec
Identifier of the record that was deleted.
oidParent
Identifier of the parent object of the deleted record.

See Also

CeOpenDatabase


WM_DBNOTIFICATION

This message identifies a change to an object in the object store, or mounted database volume. The message is only received if and application has registered to receive notifications. To receive notification, use the CeOpenDatabaseEx function.

Parameters

wParam
Set to 0.
lParam
Pointer to a CENOTIFICATION structure that must be freed after it has been processed.

Remarks

The pointer to the CENOTIFICAITON structure is freed by calling CeFreeNotification.

See Also

CeOpenDatabaseEx


WM_TIMER

This message is posted to the installing thread's message queue or sent to the appropriate TimerProc callback function after each interval specified in the SetTimer function used to install a timer.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

WM_TIMER wTimerID = wParam; tmprc = (TIMERPROC *) lParam;

Parameters

wTimerID
Specifies the timer identifier.
tmprc
Pointer to an application-defined callback function that was passed to the SetTimer function when the timer was installed.

Return Values

An application should return zero if it processes this message.

Remarks

The WM_TIMER message is a low-priority message. The GetMessage and PeekMessage functions retrieve this message only when no other higher-priority messages are in the thread’s message queue.

See Also

DispatchMessage, SetTimer, TimerProc


CHECK_INVALIDGUID

This macro checks if a CEGUID is equal to the result of CREATE_INVALIDGUID.

At a Glance

Header file: | Windbase.h
Windows CE versions | 2.10 and later

Syntax

BOOL CHECK_INVALIDGUID( PCEGUID pceguid );

Parameters

pceguid
Pointer to the CEGUID to check.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

CeMountDBVol, CREATE_INVALIDGUID


CHECK_SYSTEMGUID

This macro checks a CEGUID to determine if it identifies the object store database volume

At a Glance

Header file: | Windbase.h
Windows CE versions | 2.10 and later

Syntax

BOOL CHECK_SYSTEMGUID( PCEGUID pceguid );

Parameters

pceguid
Pointer to the CEGUID to check..

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

CREATE_INVALIDGUID, CREATE_SYSTEMGUID


CREATE_INVALIDGUID

This macro creates a CEGUID that does not identify any database volume.

At a Glance

Header file: | Windbase.h
Windows CE versions | 2.10 and later

Syntax

VOID CREATE_INVALIDGUID( PCEGUID pceguid );

Parameters

pceguid
Pointer to a CEGUID that receives an identifier that specifies an invalid database volume CEGUID.

Remarks

The CEGUID created by this macro is required by CeEnumDBVolumes to start enumeration of currently mounted database volumes.

See Also

CeEnumDBVolumes, CeMountDBVol, CHECK_INVALIDGUID


CREATE_SYSTEMGUID

This macro creates a CEGUID that identifies the object store database volume.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 2.10 and later

Syntax

VOID CREATE_SYSTEMGUID( PCEGUID pceguid);

Parameters

pceguid
Pointer to a CEGUID identifier that receives the CEGUID identifier of the database volume in the object store.

Remarks

Use this macro to generate the CEGUID identifier of the object store volume.

See Also

CeCreateDatabaseEx, CeDeleteDatabaseEx, CeFindFirstDatabaseEx, CeFindNextDatabaseEx, CeOidGetInfoEx, CeOpenDatabaseEx, CeSetDatabaseInfoEx, CHECK_SYSTEMGUID


FORWARD_WM_NOTIFY

This macro sends or posts the WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

VOID FORWARD_WM_NOTIFY( hwnd, idFrom, pnmhdr, fn );

Parameters

hwnd
Handle to the window that receives the WM_NOTIFY message.
idFrom
Identifier of the control sending the message.
pnmhdr
Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.
fn
Function that sends or posts the WM_NOTIFY message. It can be either the SendMessage or PostMessage function.

Return Values

The meaning of the value depends on the fn parameter.

Remarks

The FORWARD_WM_NOTIFY macro is defined as follows:

#define FORWARD_WM_NOTIFY(hwnd, idFrom, pnmhdr, fn) \
    (void)(fn)((hwnd), WM_NOTIFY, (WPARAM)(int)(id), \
    (LPARAM)(NMHDR FAR*)(pnmhdr))

See Also

NMHDR, PostMessage, SendMessage, WM_NOTIFY


GetBValue

This macro retrieves an intensity value for the blue component of a 32-bit red, green, blue (RGB) value.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BYTE GetBValue( DWORD rgb );

Parameters

rgb
Specifies an RGB color value.

Return Values

The return value is the intensity of the blue component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetBValue macro is defined as follows:

#define GetBValue(rgb)   ((BYTE) ((rgb) >> 16))

See Also

GetGValue, GetRValue, PALETTERGB, RGB


GetGValue

This macro retrieves an intensity value for the green component of a 32-bit red, green, blue (RGB) value.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BYTE GetGValue( DWORD rgb );

Parameters

rgb
Specifies an RGB color value.

Return Values

The return value is the intensity of the green component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetGValue macro is defined as follows:

#define GetGValue(rgb)   ((BYTE) (((WORD) (rgb)) >> 8))

See Also

GetBValue, GetRValue, PALETTERGB, RGB


GetRValue

This macro retrieves an intensity value for the red component of a 32-bit red, green, blue (RGB) value.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

BYTE GetRValue( DWORD rgb );

Parameters

rgb
Specifies an RGB color value.

Return Values

The return value is the intensity of the red component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetRValue macro is defined as follows:

#define GetRValue(rgb)   ((BYTE) (rgb))

See Also

GetBValue, GetGValue, PALETTERGB, RGB


HANDLE_WM_NOTIFY

This macro calls a function that processes the WM_NOTIFY message.

At a Glance

Header file: | Commctrl.h
Windows CE versions: | 1.0 and later

Syntax

HANDLE_WM_NOTIFY( hwnd, wParam, lParam, fn );

Parameters

hwnd
Handle to the window that received WM_NOTIFY.
wParam
First parameter of WM_NOTIFY.
lParam
Second parameter of WM_NOTIFY.
fn
Function that is to process WM_NOTIFY.

Return Values

The meaning of the value depends on the fn parameter.

Remarks

The HANDLE_WM_NOTIFY macro is defined as follows:

#define HANDLE_WM_NOTIFY(hwnd, wParam, lParam, fn) \
    (fn)((hwnd), (int)(wParam), (NMHDR FAR*)(lParam))

See Also

WM_NOTIFY


HIBYTE

This macro retrieves the high-order byte from the specified 16-bit value.

At a Glance

Header file: | Windef.h
Platforms: | H/PC
Windows CE versions: | 1.0 and later

Syntax

BYTE HIBYTE( WORD wValue );

Parameters

wValue
Specifies the value to be converted.

Return Values

The return value is the high-order byte of the specified value.

Remarks

The HIBYTE macro is defined as follows:

#define HIBYTE(w)   ((BYTE) (((WORD) (w) >> 8) & 0xFF))

See Also

HIWORD, LOBYTE


HIWORD

This macro retrieves the high-order word from the specified 32-bit value.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

WORD HIWORD( DWORD dwValue );

Parameters

dwValue
Specifies the value to be converted.

Return Values

The return value is the high-order word of the specified value.

Remarks

The HIWORD macro is defined as follows:

#define HIWORD(l)   ((WORD) (((DWORD) (l) >> 16) & 0xFFFF))

See Also

HIBYTE, LOWORD


InsetRect

This macro calls the InflateRect function, passing in the negative value of the specified x- and y-coordinates.

At a Glance

Header file: | Windowsx.h
Windows CE versions: | 1.0 and later

Syntax

BOOL InsetRect( LPRECT lprc, int dx, int dy );

Parameters

lprc
Long pointer to the RECT structure that increases or decreases in size.
dx
Specifies the amount to increase or decrease the rectangle width. This parameter must be negative to increase the width.
dy
Specifies the amount to increase or decrease the rectangle height. This parameter must be negative to increase the height.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

See Also

InflateRect


LOBYTE

This macro retrieves the low-order byte from the specified 16-bit value.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

BYTE LOBYTE( WORD wValue );

Parameters

wValue
Specifies the value to be converted.

Return Values

The return value is the low-order byte of the specified value.

Remarks

The LOBYTE macro is defined as follows:

#define LOBYTE(w)   ((BYTE) (w))

See Also

HIBYTE, LOWORD


LOWORD

This macro retrieves the low-order word from the specified 32-bit value.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

WORD LOWORD( DWORD dwValue );

Parameters

dwValue
Specifies the value to be converted.

Return Values

The return value is the low-order word of the specified value.

Remarks

The LOWORD macro is defined as follows:

#define LOWORD(l)   ((WORD) (l))

See Also

HIWORD, LOBYTE


MAKEINTRESOURCE

This macro converts an integer value to a resource type compatible with Windows resource-management functions. This macro is used in place of a string containing the name of the resource.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LPTSTR MAKEINTRESOURCE( WORD wInteger; );

Parameters

wInteger
Specifies the integer value to be converted.

Return Values

The return value is the specified value in the low-order word and zero in the high-order word.

Remarks

The return value should be passed only to the Win32 resource-management functions, as the lpType parameter.

The MAKEINTRESOURCE macro is defined as follows:

#define MAKEINTRESOURCE(i)  (LPTSTR) ((DWORD) ((WORD) (i)))


MAKELANGID

This macro creates a language identifier from a primary language identifier and a sub-language identifier.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

WORD MAKELANGID( USHORT usPrimaryLanguage,
USHORT usSubLanguage );

Parameters

usPrimaryLanguage
Specifies the primary language identifier. It is one of the following predefined values:
LANG_AFRIKAANS | LANG_KONKANI
LANG_ALBANIAN | LANG_KOREAN
LANG_ARABIC | LANG_LATVIAN
LANG_ARMENIAN | LANG_LITHUANIAN
LANG_ASSAMESE | LANG_MACEDONIAN
LANG_AZERI | LANG_MALAY
LANG_BASQUE | LANG_MALAYALAM
LANG_BELARUSIAN | LANG_MANIPURI
LANG_BENGALI | LANG_MARATHI
LANG_BULGARIAN | LANG_NEPALI
LANG_CATALAN | LANG_NEUTRAL
LANG_CHINESE | LANG_NORWEGIAN
LANG_CROATIAN | LANG_ORIYA
LANG_CZECH | LANG_POLISH
LANG_DANISH | LANG_PORTUGUESE
LANG_DUTCH | LANG_PUNJABI
LANG_ENGLISH | LANG_ROMANIAN
LANG_ESTONIAN | LANG_RUSSIAN
LANG_FAEROESE | LANG_SANSKRIT
LANG_FARSI | LANG_SERBIAN
LANG_FINNISH | LANG_SINDHI
LANG_FRENCH | LANG_SLOVAK
LANG_GEORGIAN | LANG_SLOVENIAN
LANG_GERMAN | LANG_SPANISH
LANG_GREEK | LANG_SWAHILI
LANG_GUJARATI | LANG_SWEDISH
LANG_HEBREW | LANG_TAMIL
LANG_HINDI | LANG_TATAR
LANG_HUNGARIAN | LANG_TELUGU
LANG_ICELANDIC | LANG_THAI
LANG_INDONESIAN | LANG_TURKISH
LANG_ITALIAN | LANG_UKRANIAN
LANG_JAPANESE | LANG_URDU
LANG_KANNADA | LANG_UZBEK
LANG_KASHMIRI | LANG_VIETNAMESE
LANG_KAZAK

For a user-defined language, usPrimaryLanguage can be a value in the range 0x0200 to 0x03FF. All other values are reserved for system use.

usSubLanguage
Specifies the secondary language identifier. It is one of the following values:
SUBLANG_ARABIC_SAUDI_ARABIA | SUBLANG_GERMAN_AUSTRIAN
SUBLANG_ARABIC_IRAQ | SUBLANG_GERMAN_LUXEMBOURG
SUBLANG_ARABIC_EGYPT | SUBLANG_GERMAN_LIECHTENSTEIN
SUBLANG_ARABIC_LIBYA | SUBLANG_ITALIAN
SUBLANG_ARABIC_ALGERIA | SUBLANG_ITALIAN_SWISS
SUBLANG_ARABIC_MOROCCO | SUBLANG_KASHMIRI_INDIA
SUBLANG_ARABIC_TUNISIA | SUBLANG_KOREAN
SUBLANG_ARABIC_OMAN | SUBLANG_LITHUANIAN
SUBLANG_ARABIC_YEMEN | SUBLANG_LITHUANIAN_CLASSIC
SUBLANG_ARABIC_SYRIA | SUBLANG_MALAY_BRUNEI_DARUSSALAM
SUBLANG_ARABIC_JORDAN | SUBLANG_MALAY_MALAYSIA
SUBLANG_ARABIC_LEBANON | SUBLANG_NEPALI_INDIA
SUBLANG_ARABIC_KUWAIT | SUBLANG_NEUTRAL
SUBLANG_ARABIC_UAE | SUBLANG_NORWEGIAN_BOKMAL
SUBLANG_ARABIC_BAHRAIN | SUBLANG_NORWEGIAN_NYNORSK
SUBLANG_ARABIC_QATAR | SUBLANG_PORTUGUESE
SUBLANG_AZERI_CYRILLIC | SUBLANG_PORTUGUESE_BRAZILIAN
SUBLANG_AZERI_LATIN | SUBLANG_SERBIAN_LATIN
SUBLANG_CHINESE_TRADITIONAL | SUBLANG_SERBIAN_CYRILLIC
SUBLANG_CHINESE_SIMPLIFIED | SUBLANG_SPANISH
SUBLANG_CHINESE_HONGKONG | SUBLANG_SPANISH_MEXICAN
SUBLANG_CHINESE_SINGAPORE | SUBLANG_SPANISH_MODERN
SUBLANG_CHINESE_MACAU | SUBLANG_SPANISH_GUATEMALA
SUBLANG_DEFAULT | SUBLANG_SPANISH_COSTA_RICA
SUBLANG_DUTCH | SUBLANG_SPANISH_PANAMA
SUBLANG_DUTCH_BELGIAN | SUBLANG_SPANISH_DOMINICAN_REPUBLIC
SUBLANG_ENGLISH_US | SUBLANG_SPANISH_VENEZUELA
SUBLANG_ENGLISH_UK | SUBLANG_SPANISH_COLOMBIA
SUBLANG_ENGLISH_AUS | SUBLANG_SPANISH_PERU
SUBLANG_ENGLISH_CAN | SUBLANG_SPANISH_ARGENTINA
SUBLANG_ENGLISH_NZ | SUBLANG_SPANISH_ECUADOR
SUBLANG_ENGLISH_EIRE | SUBLANG_SPANISH_CHILE
SUBLANG_ENGLISH_SOUTH_AFRICA | SUBLANG_SPANISH_URUGUAY
SUBLANG_ENGLISH_JAMAICA | SUBLANG_SPANISH_PARAGUAY
SUBLANG_ENGLISH_CARIBBEAN | SUBLANG_SPANISH_BOLIVIA
SUBLANG_ENGLISH_BELIZE | SUBLANG_SPANISH_EL_SALVADOR
SUBLANG_ENGLISH_TRINIDAD | SUBLANG_SPANISH_HONDURAS
SUBLANG_ENGLISH_PHILIPPINES | SUBLANG_SPANISH_NICARAGUA
SUBLANG_ENGLISH_ZIMBABWE | SUBLANG_SPANISH_PUERTO_RICO
SUBLANG_FRENCH | SUBLANG_SWEDISH
SUBLANG_FRENCH_BELGIAN | SUBLANG_SWEDISH_FINLAND
SUBLANG_FRENCH_CANADIAN | SUBLANG_SYS_DEFAULT
SUBLANG_FRENCH_SWISS | SUBLANG_URDU_INDIA
SUBLANG_FRENCH_LUXEMBOURG | SUBLANG_URDU_PAKISTAN
SUBLANG_FRENCH_MONACO | SUBLANG_UZBEK_CYRILLIC
SUBLANG_GERMAN | SUBLANG_UZBEK_LATIN
SUBLANG_GERMAN_SWISS

For a user-defined secondary language, usSubLanguage can be a value in the range 0x20 to 0x3F. All other values are reserved for system use.

Return Values

The return value is a language identifier.

Remarks

The following three combinations of usPrimaryLanguage and usSubLanguage have special meaning:

Primary language identifier
Secondary language identifier
Meaning
LANG_NEUTRAL | SUBLANG_NEUTRAL | Language neutral
LANG_NEUTRAL | SUBLANG_DEFAULT | User default language
LANG_NEUTRAL | SUBLANG_SYS_DEFAULT | System default language

The MAKELANGID macro is defined as follows:

#define MAKELANGID(p, s) ((((WORD) (s)) << 10) | (WORD) (p))

See Also

MAKELCID


MAKELCID

This macro creates a locale identifier from a language identifier.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

DWORD MAKELCID( WORD wLanguageID WORD wSortID );

Parameters

wLanguageID
Specifies the language identifier. This parameter is a combination of a primary language identifier and a secondary language identifier and is usually created by using the MAKELANGID macro.
wSortID
Specifies the sort identifier. The following sort identifiers are defined:
SORT_DEFAULT
Specifies the default sort.
SORT_JAPANESE_XJIS
Specifies Japanese XJIS order.
SORT_JAPANESE_UNICODE
Specifies Japanese Unicode order.
SORT_CHINESE_BIG5
Specifies Chinese BIG5 order.
SORT_CHINESE_UNICODE
Specifies Chinese Unicode order.
SORT_KOREAN_KSC
Specifies Korean KSC order.
SORT_KOREAN_UNICODE
Specifies Korean Unicode order.

Return Values

The return value is a locale identifier.

Remarks

The MAKELCID macro is defined as follows:

#define MAKELCID(lgid, srtid)  \
    ((DWORD)((((DWORD)((WORD  )(srtid))) << 16) |  \
            ((DWORD)((WORD  )(lgid)))))

See Also

MAKELANGID


MAKELONG

This macro creates an unsigned 32-bit value by concatenating two specified 16-bit values.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

DWORD MAKELONG( WORD wLow, WORD wHigh );

Parameters

wLow
Specifies the low-order word of the new long value.
wHigh
Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKELONG macro is defined as follows:

#define MAKELONG(a, b) \
    ((LONG) (((WORD) (a)) | ((DWORD) ((WORD) (b))) << 16))


MAKELPARAM

This macro creates an unsigned 32-bit value for use as an lParam parameter in a message. The macro concatenates two specified 16-bit values.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LPARAM MAKELPARAM( WORD wLow, WORD wHigh );

Parameters

wLow
Specifies the low-order word of the new long value.
wHigh
Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKELPARAM macro is defined as follows:

#define MAKELPARAM(l, h)   ((LPARAM) MAKELONG(l, h))

See Also

MAKELONG, MAKELRESULT, MAKEWPARAM


MAKELRESULT

This macro creates an unsigned 32-bit value for use as a return value from a window procedure. The macro concatenates two specified 16-bit values.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LRESULT MAKELRESULT( WORD wLow, WORD wHigh );

Parameters

wLow
Specifies the low-order word of the new long value.
wHigh
Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKELRESULT macro is defined as follows:

#define MAKELRESULT(l, h)   ((LRESULT) MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKEWPARAM


MAKEROP4

This macro creates a quaternary raster operation (ROP) code for use by the MaskBlt function. The macro takes two ternary ROP codes as input, one for the foreground and one for the background, and packs their Boolean operation indexes into the high-order word of a 32-bit value. MAKEROP4 ignores the low-order word.

At a Glance

Header file | Wingdi.h
Windows CE versions | 2.0 and later

Syntax

DWORD MAKEROP4(DWORD fore, DWORD back);

Parameters

fore
Specifies a foreground ternary raster operation code.
back
Specifies a background ternary raster operation code

Return Values

The return value is a DWORD quaternary raster operation code for use with the MaskBlt function.

Remarks

The MAKEROP4 macro is defined as follows:

#define MAKEROP4(fore,back)
          (DWORD)((((back) << 8) & 0xFF000000) | (fore))

See Also

MaskBlt


MAKEWORD

This macro creates an unsigned 16-bit integer by concatenating two spscified unsigned character values.

At a Glance

Header file: | Windef.h
Windows CE versions: | 1.0 and later

Syntax

WORD MAKEWORD( BYTE bLow, BYTE bHigh );

Parameters

bLow
Specifies the low-order byte of the new short value.
bHigh
Specifies the high-order byte of the new short value.

Return Values

The return value is an unsigned 16-bit integer value.

Remarks

The MAKEWORD macro is defined as follows:

#define MAKEWORD(a, b) \
    ((WORD) (((BYTE) (a)) | ((WORD) ((BYTE) (b))) << 8))


MAKEWPARAM

This macro creates an unsigned 32-bit value for use as a wParam parameter in a message. The macro concatenates two specified 16-bit values.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

LPARAM MAKEWPARAM( WORD wLow, WORD wHigh );

Parameters

wLow
Specifies the low-order word of the new long value.
wHigh
Specifies the high-order word of the new long value.

Return Values

The return value is an unsigned 32-bit value.

Remarks

The MAKEWPARAM macro is defined as follows:

#define MAKEWPARAM(l, h)   ((LPARAM) MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKELRESULT


MapWindowRect

This macro calls the function MapWindowPoints.

At a Glance

Header file: | Windowsx.h
Windows CE versions: | 1.0 and later

Syntax

MapWindowRect( HWND hwndFrom, HWND hwndTo, LPRECT lprc );

Parameters

hwndFrom
Handle to the source window.
hwndto
Handle to the target window.
lprc
Long pointer to the rectangle to be mapped. During input, this rectangle is relative to the source window. During output, it is relative to the target window.


PALETTERGB

This macro accepts three values that represent the relative intensities of red, green, and blue and returns a palette-relative red, green, blue (RGB) specifier consisting of 2 in the high-order byte and an RGB value in the three low-order bytes (with a value representing the intensity of red, green, or blue in each of the bytes). An application using a color palette can pass this specifier, instead of an explicit RGB value, to functions that expect a color.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF PALETTERGB( BYTE bRed, BYTE bGreen, BYTE bBlue );

Parameters

bRed
Specifies the intensity of the red color field.
bGreen
Specifies the intensity of the green color field.
bBlue
Specifies the intensity of the blue color field.

Return Values

The return value is a palette-relative RGB specifier. For output devices that support logical palettes, the system matches a palette-relative RGB value to the nearest color in the logical palette of the device context as though the application had specified an index to that palette entry. If an output device does not support a system palette, the system uses the palette-relative RGB as though it were a conventional RGB doubleword returned by the RGB macro.

Remarks

The PALETTERGB macro is defined as follows:

#define PALETTERGB(r, g, b)  (0x02000000 | RGB(r, g, b))

See Also

RGB


POINTSTOPOINT

This macro copies the contents of a POINTS structure into a POINT structure.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

POINTSTOPOINT( POINT pt, POINTS pts );

Parameters

pt
Specifies the POINT structure to receive the contents of the POINTS structure.
pts
Specifies the POINTS structure to copy.

Remarks

The POINTSTOPOINT macro is defined as follows:

#define POINTSTOPOINT(pt, pts) {(pt).x = (SHORT) LOWORD(pts); \
                               (pt).y = (SHORT) HIWORD(pts);}

See Also

POINT, POINTS


PRIMARYLANGID

This macro extracts a primary language identifier from a language identifier.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

WORD PRIMARYLANGID ( WORD lgid );

Parameters

lgid
Specifies the language identifier. This value is a combination of a primary language identifier and a secondary language identifier and is usually created by using the MAKELANGID macro.

Return Values

The return value is a primary language identifier. The following primary language identifiers are defined:

LANG_AFRIKAANS | LANG_KONKANI
LANG_ALBANIAN | LANG_KOREAN
LANG_ARABIC | LANG_LATVIAN
LANG_ARMENIAN | LANG_LITHUANIAN
LANG_ASSAMESE | LANG_MACEDONIAN
LANG_AZERI | LANG_MALAY
LANG_BASQUE | LANG_MALAYALAM
LANG_BELARUSIAN | LANG_MANIPURI
LANG_BENGALI | LANG_MARATHI
LANG_BULGARIAN | LANG_NEPALI
LANG_CATALAN | LANG_NEUTRAL
LANG_CHINESE | LANG_NORWEGIAN
LANG_CROATIAN | LANG_ORIYA
LANG_CZECH | LANG_POLISH
LANG_DANISH | LANG_PORTUGUESE
LANG_DUTCH | LANG_PUNJABI
LANG_ENGLISH | LANG_ROMANIAN
LANG_ESTONIAN | LANG_RUSSIAN
LANG_FAEROESE | LANG_SANSKRIT
LANG_FARSI | LANG_SERBIAN
LANG_FINNISH | LANG_SINDHI
LANG_FRENCH | LANG_SLOVAK
LANG_GEORGIAN | LANG_SLOVENIAN
LANG_GERMAN | LANG_SPANISH
LANG_GREEK | LANG_SWAHILI
LANG_GUJARATI | LANG_SWEDISH
LANG_HEBREW | LANG_TAMIL
LANG_HINDI | LANG_TATAR
LANG_HUNGARIAN | LANG_TELUGU
LANG_ICELANDIC | LANG_THAI
LANG_INDONESIAN | LANG_TURKISH
LANG_ITALIAN | LANG_UKRANIAN
LANG_JAPANESE | LANG_URDU
LANG_KANNADA | LANG_UZBEK
LANG_KASHMIRI | LANG_VIETNAMESE
LANG_KAZAK |

Remarks

The PRIMARYLANGID macro is defined as follows:

#define PRIMARYLANGID(lgid)    ((WORD  )(lgid) & 0x3ff)

See Also

MAKELANGID, SUBLANGID


RGB

This macro selects a red, green, blue (RGB) color based on the specified color values and the capabilities of the output device.

At a Glance

Header file: | Wingdi.h
Windows CE versions: | 1.0 and later

Syntax

COLORREF RGB( BYTE bRed, BYTE bGreen, BYTE bBlue );

Parameters

cRed
Specifies the intensity of the red color.
cGreen
Specifies the intensity of the green color.
cBlue
Specifies the intensity of the blue color.

Return Values

The return value is the resultant RGB color.

Remarks

The intensity for each argument is in the range 0 through 255. If all three intensities are zero, the result is black. If all three intensities are 255, the result is white.

For information about using color values in a color palette, see the description of the PALETTERGB macro.

The RGB macro is defined as follows:

#define RGB(r, g ,b)  ((DWORD) (((BYTE) (r) | \
    ((WORD) (g) << 8)) | \
    (((DWORD) (BYTE) (b)) << 16)))

See Also

PALETTERGB


SetDlgMsgResult

This macro maps to the SetWindowLong function.

At a Glance

Header file: | Winuser.h
Windows CE versions: | 1.0 and later

Syntax

SetDlgMsgResult ( HWND hwnd, int msg, LONG result);

See Also

SetWindowLong


SUBLANGID

This macro extracts a sublanguage identifier from a language identifier.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

WORD SUBLANGID ( WORD lgid );

Parameters

lgid
Specifies the language identifier. This value is a combination of a primary language identifier and a secondary language identifier and is usually created by using the MAKELANGID macro.

Return Values

The return value is a secondary language identifier. The following secondary language identifiers are defined:

SUBLANG_ARABIC_SAUDI_ARABIA | SUBLANG_GERMAN_AUSTRIAN
SUBLANG_ARABIC_IRAQ | SUBLANG_GERMAN_LUXEMBOURG
SUBLANG_ARABIC_EGYPT | SUBLANG_GERMAN_LIECHTENSTEIN
SUBLANG_ARABIC_LIBYA | SUBLANG_ITALIAN
SUBLANG_ARABIC_ALGERIA | SUBLANG_ITALIAN_SWISS
SUBLANG_ARABIC_MOROCCO | SUBLANG_KASHMIRI_INDIA
SUBLANG_ARABIC_TUNISIA | SUBLANG_KOREAN
SUBLANG_ARABIC_OMAN | SUBLANG_LITHUANIAN
SUBLANG_ARABIC_YEMEN | SUBLANG_LITHUANIAN_CLASSIC
SUBLANG_ARABIC_SYRIA | SUBLANG_MALAY_BRUNEI_DARUSSALAM
SUBLANG_ARABIC_JORDAN | SUBLANG_MALAY_MALAYSIA
SUBLANG_ARABIC_LEBANON | SUBLANG_NEPALI_INDIA
SUBLANG_ARABIC_KUWAIT | SUBLANG_NEUTRAL
SUBLANG_ARABIC_UAE | SUBLANG_NORWEGIAN_BOKMAL
SUBLANG_ARABIC_BAHRAIN | SUBLANG_NORWEGIAN_NYNORSK
SUBLANG_ARABIC_QATAR | SUBLANG_PORTUGUESE
SUBLANG_AZERI_CYRILLIC | SUBLANG_PORTUGUESE_BRAZILIAN
SUBLANG_AZERI_LATIN | SUBLANG_SERBIAN_LATIN
SUBLANG_CHINESE_TRADITIONAL | SUBLANG_SERBIAN_CYRILLIC
SUBLANG_CHINESE_SIMPLIFIED | SUBLANG_SPANISH
SUBLANG_CHINESE_HONGKONG | SUBLANG_SPANISH_MEXICAN
SUBLANG_CHINESE_SINGAPORE | SUBLANG_SPANISH_MODERN
SUBLANG_CHINESE_MACAU | SUBLANG_SPANISH_GUATEMALA
SUBLANG_DEFAULT | SUBLANG_SPANISH_COSTA_RICA
SUBLANG_DUTCH | SUBLANG_SPANISH_PANAMA
SUBLANG_DUTCH_BELGIAN | SUBLANG_SPANISH_DOMINICAN_REPUBLIC
SUBLANG_ENGLISH_US | SUBLANG_SPANISH_VENEZUELA
SUBLANG_ENGLISH_UK | SUBLANG_SPANISH_COLOMBIA
SUBLANG_ENGLISH_AUS | SUBLANG_SPANISH_PERU
SUBLANG_ENGLISH_CAN | SUBLANG_SPANISH_ARGENTINA
SUBLANG_ENGLISH_NZ | SUBLANG_SPANISH_ECUADOR
SUBLANG_ENGLISH_EIRE | SUBLANG_SPANISH_CHILE
SUBLANG_ENGLISH_SOUTH_AFRICA | SUBLANG_SPANISH_URUGUAY
SUBLANG_ENGLISH_JAMAICA | SUBLANG_SPANISH_PARAGUAY
SUBLANG_ENGLISH_CARIBBEAN | SUBLANG_SPANISH_BOLIVIA
SUBLANG_ENGLISH_BELIZE | SUBLANG_SPANISH_EL_SALVADOR
SUBLANG_ENGLISH_TRINIDAD | SUBLANG_SPANISH_HONDURAS
SUBLANG_ENGLISH_PHILIPPINES | SUBLANG_SPANISH_NICARAGUA
SUBLANG_ENGLISH_ZIMBABWE | SUBLANG_SPANISH_PUERTO_RICO
SUBLANG_FRENCH | SUBLANG_SWEDISH
SUBLANG_FRENCH_BELGIAN | SUBLANG_SWEDISH_FINLAND
SUBLANG_FRENCH_CANADIAN | SUBLANG_SYS_DEFAULT
SUBLANG_FRENCH_SWISS | SUBLANG_URDU_INDIA
SUBLANG_FRENCH_LUXEMBOURG | SUBLANG_URDU_PAKISTAN
SUBLANG_FRENCH_MONACO | SUBLANG_UZBEK_CYRILLIC
SUBLANG_GERMAN | SUBLANG_UZBEK_LATIN
SUBLANG_GERMAN_SWISS |

Remarks

The SUBLANGID macro is defined as follows:

#define SUBLANGID(lgid)        ((WORD  )(lgid) >> 10)

See Also

MAKELANGID, PRIMARYLANGID


TEXT

This macro identifies a string as Unicode when the UNICODE compile flag is used or as an ANSI string when Unicode is not defined.

At a Glance

Header file: | Winnt.h
Windows CE versions: | 1.0 and later

Syntax

TEXT( LPTSTR string );

Parameters

string
Specifies the string to be interpreted as either Unicode or ANSI.

Remarks

The TEXT macro is defined as follows:

#define TEXT(quote) L##quote


TypeFromPropID

This macro retrieves the type identifier from a property identifier.

At a Glance

Header file: | Windbase.h
Windows CE versions: | 1.0 and later

Syntax

WORD TypeFromPropID( PEGPROPID propid );

Parameters

propid
Property identifier from which to retrieve the type identifier.

Remarks

The TypeFromPropID macro is defined as follows:

#define TypeFromPropID(propid) LOWORD(propid)


CALLCONV

The CALLCONV enumeration identifies the calling convention used by a method described in the METHODDATA structure.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagCALLCONV {
CC_CDECL =1,
CC_MSCPASCAL =2,
CC_PASCAL =CC_MSCPASCAL,
CC_MACPASCAL =3,
CC_STDCALL =4,
CC_RESERVED =5,
CC_SYSCALL =6,
CC_MPWCDECL =7,
CC_MPWPASCAL =8,
CC_MAX =9
} CALLCONV;

Remarks

On 16-bit Windows systems, functions implemented with the CC_CDECL calling convention cannot have a return type of float or double. This includes functions that return DATE, which is a floating-point type.


DESCKIND

The DESCKIND enumeration identifies the type description being bound to.

At a Glance

Header file: | Oaidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagDESCKIND {
DESCKIND_NONE,
DESCKIND_FUNCDESC,
DESCKIND_VARDESC,
DESCKIND_TYPECOMP,
DESCKIND_IMPLICITAPPOBJ
} DESCKIND;

Elements

DESCKIND_NONE
No match was found.
DESCKIND_FUNCDESC
A FUNCDESC was returned.
DESCKIND_VARDESC
A VARDESC was returned.
DESCKIND_TYPECOMP
A TYPECOMP was returned.
DESCKIND_IMPLICITAPPOBJ
An IMPLICITAPPOBJ was returned.


DVASPECT

The DVASPECT enumeration values specify the desired data or view aspect of the object when drawing or getting data.

At a Glance

Header file: | Wtypes.h
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagDVASPECT
{
DVASPECT_CONTENT = 1,
DVASPECT_THUMBNAIL = 2,
DVASPECT_ICON = 4,
DVASPECT_DOCPRINT = 8
} DVASPECT;

Elements

DVASPECT_CONTENT
Provides a representation of an object so it can be displayed as an embedded object inside of a container. This value is typically specified for compound document objects. The presentation can be provided for the screen or printer.
DVASPECT_THUMBNAIL
Provides a thumbnail representation of an object so it can be displayed in a browsing tool. The thumbnail is approximately a 120 by 120 pixel, 16-color (recommended) device-independent bitmap potentially wrapped in a metafile.
DVASPECT_ICON
Provides an iconic representation of an object.
DVASPECT_DOCPRINT
Provides a representation of the object on the screen as though it were printed to a printer using the Print command from the File menu. The described data may represent a sequence of pages.

Remarks

Values of this enumeration are used to define the dwAspect field of the FORMATEC structure. Only one DVASPECT value can be used to specify a single presentation aspect in a FORMATETC structure. The FORMATETC structure is used in many OLE functions and interface methods that require information on data presentation.

The default value of MiscStatus is used if a subkey corresponding to the specified DVASPECT is not found. To set an OLE control, specify DVASPECT==1. This will cause the following to occur in the Registry:

HKEY_CLASSES_ROOT\CLSID\ . . .\MiscStatus = 1

See Also

OleDraw, FORMATETC


FUNCKIND

The FUNCKIND enumeration lists various kinds of access of a function.

At a Glance

Header file: | Oaidl.idl
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagFUNCKIND {
FUNC_VIRTUAL,
FUNC_PUREVIRTUAL,
FUNC_NONVIRTUAL,
FUNC_STATIC,
FUNC_DISPATCH,
} FUNCKIND;

Elements

FUNC_PUREVIRTUAL
The function is accessed through the virtual function table (VTBL), and takes an implicit this pointer.
FUNC_VIRTUAL
The function is accessed the same as PUREVIRTUAL, except the function has an implementation.
FUNC_NONVIRTUAL
The function is accessed by static address and takes an implicit i pointer.
FUNC_STATIC
The function is accessed by static address and does not take an implicit this pointer.
FUNC_DISPATCH
The function can be accessed only through IDispatch.


INVOKEKIND

The INVOKEKIND enumeration is used to specify the way in which a function is to be invoked by IDispatch::Invoke.

At a Glance

Header file: | Oaidl.idl
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagINVOKEKIND {
INVOKE_FUNC = DISPATCH_METHOD,
INVOKE_PROPERTYGET = DISPATCH_PROPERTYGET,
INVOKE_PROPERTYPUT = DISPATCH_PROPERTYPUT,
INVOKE_PROPERTYPUTREF = DISPATCH_PROPERTYPUTREF
} INVOKEKIND;

Elements

INVOKE_FUNC
The member is called using a normal function invocation syntax.
INVOKE_PROPERTYGET
The function is invoked using a normal property-access syntax.
INVOKE_PROPERTYPUT
The function is invoked using a property value assignment syntax. Syntactically, a typical programming language might represent changing a property in the same way as assignment. For example: object.property : = value
INVOKE_PROPERTYPUTREF
The function is invoked using a property reference assignment syntax.

Remarks

In C, value assignment is written as *pobj1 = *pobj2, while reference assignment is written as pobj1 = pobj2. Other languages have other syntactic conventions. A property or data member can support only a value assignment, a reference assignment, or both. For a detailed description of property functions, see Chapter 5, "Dispatch Interface and API Functions." The INVOKEKIND enumeration constants are the same constants that are passed to IDispatch::Invoke to specify the way in which a function is invoked.


MAILSORTFIELD

The MAILSORTFIELD enumeration specifies the fields by which mail messages may be sorted.

At a Glance

Header file: | Msgstore.h
Windows CE versions: | 2.0 and later

Syntax

typedef enum {
MAIL_SORT_FROM,
MAIL_SORT_SUBJ,
MAIL_SORT_DATE,
MAIL_SORT_SIZE
} MAILSORTFIELD;

Elements

MAIL_SORT_FROM
Sort message by senders.
MAIL_SORT_SUBJ
Sort messages by subject.
MAIL_SORT_DATE
Sort messages by date.
MAIL_SORT_SIZE
Sort messages by size.


STGM

These enumeration values are used in the storage and stream interfaces to indicate the conditions for creating and deleting the object and access modes for the object.

The following STGM values are used in the IStorage, IStream, and IPropertySetStorage interfaces, and in the StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage, and StgOpenStorageEx functions to indicate the conditions for creating and deleting the object and access modes for the object.

STGM_DIRECT | 0x00000000L
STGM_TRANSACTED | 0x00010000L
STGM_SIMPLE | 0x08000000L
STGM_READ | 0x00000000L
STGM_WRITE | 0x00000001L
STGM_READWRITE | 0x00000002L
STGM_SHARE_DENY_NONE | 0x00000040L
STGM_SHARE_DENY_READ | 0x00000030L
STGM_SHARE_DENY_WRITE | 0x00000020L
STGM_SHARE_EXCLUSIVE | 0x00000010L
STGM_PRIORITY | 0x00040000L
STGM_DELETEONRELEASE | 0x04000000L
STGM_CREATE | 0x00001000L
STGM_CONVERT | 0x00020000L
STGM_FAILIFTHERE | 0x00000000L
STGM_NOSCRATCH | 0x00100000L
STGM_NOSNAPSHOT | 0x00200000L
STGM_DIRECT_SWMR | 0x00400000L

Elements

STGM_DIRECT
In direct mode, each change to a storage element is written as it occurs. This is the default.
STGM_TRANSACTED
In transacted mode, changes are buffered and are written only if an explicit commit operation is called. To ignore the changes, call the Revert method in the IStream, IStorage, or IPropertyStorage interfaces. The COM compound file and NSS implementations of IStorage do not support transacted streams, which means that streams can be opened only in direct mode, and you cannot revert changes to them. Transacted storages are, however, supported. The compound file, NSS standalone, and NTFS implementations of IPropertySetStorage similarly do not support transacted, simple mode property sets as these property sets are stored in streams. However, non-simple property sets, which can be created by specifying the PROPSETFLAG_NONSIMPLE flag in the grfFlags parameter of IPropertySetStorage::Create, are supported.
STGM_SIMPLE
STGM_SIMPLE is a mode that provides a much faster implementation of a compound file in a limited, but frequently used case. It is described in detail in the following Remarks section.
STGM_DIRECT_SWMR
The STGM_DIRECT_SWMR supports direct mode for single-writer, multi-reader file operations.
STGM_READ
For stream objects, STGM_READ allows you to call the ISequentialStream::Read method. For storage objects, you can enumerate the storage elements and open them for reading.
STGM_WRITE
STGM_WRITE lets you save changes to the object.
STGM_READWRITE
STGM_READWRITE is the combination of STGM_READ and STGM_WRITE.
STGM_SHARE_DENY_NONE
Specifies that subsequent openings of the object are not denied read or write access.
STGM_SHARE_DENY_READ
Prevents others from subsequently opening the object in STGM_READ mode. It is typically used on a root storage object.
STGM_SHARE_DENY_WRITE
Prevents others from subsequently opening the object in STGM_WRITE mode. This value is typically used to prevent unnecessary copies made of an object opened by multiple users. If this value is not specified, a snapshot is made, independent of whether there are subsequent opens or not. Thus, you can improve performance by specifying this value.
STGM_SHARE_EXCLUSIVE
The combination of STGM_SHARE_DENY_READ and STGM_SHARE_DENY_WRITE.
STGM_PRIORITY
Opens the storage object with exclusive access to the most recently committed version. Thus, other users cannot commit changes to the object while you have it open in priority mode. You gain performance benefits for copy operations, but you prevent others from committing changes. So, you should limit the time you keep objects open in priority mode. You must specify STGM_DIRECT and STGM_READ with priority mode.
STGM_DELETEONRELEASE
Indicates that the underlying file is to be automatically destroyed when the root storage object is released. This capability is most useful for creating temporary files.
STGM_CREATE
Indicates that an existing storage object or stream should be removed before the new one replaces it. A new object is created when this flag is specified, only if the existing object has been successfully removed.

This flag is used in the following situations:

  • When you are trying to create a storage object on disk but a file of that name already exists.
  • When you are trying to create a stream inside a storage object but a stream with the specified name already exists.
  • When you are creating a byte array object but one with the specified name already exists.
STGM_CONVERT
Creates the new object while preserving existing data in a stream named CONTENTS. In the case of a storage object or a byte array, the old data is flattened to a stream regardless of whether the existing file or byte array currently contains a layered storage object.
STGM_FAILIFTHERE
Causes the create operation to fail if an existing object with the specified name exists. In this case, STG_E_FILEALREADYEXISTS is returned. STGM_FAILIFTHERE applies to both storage objects and streams.
STGM_NOSCRATCH
In transacted mode, a scratch file is usually used to save until the commit operation. Specifying STGM_NOSCRATCH permits the unused portion of the original file to be used as scratch space. This does not affect the data in the original file, and is a much more efficient use of memory.
STGM_NOSNAPSHOT
This flag is used when opening a storage with STGM_TRANSACTED and without STGM_SHARE_EXCLUSIVE or STGM_SHARE_DENY_WRITE. In this case, specifying STGM_NOSNAPSHOT prevents the system-provided implementation from creating a snapshot copy of the file. Instead, changes to the file are written to the end of the file. Unused space is not reclaimed unless consolidation is done during the commit, and there is only one current writer on the file. When the file is opened in no snapshot mode, another open cannot be done without specifying STGM_NOSNAPSHOT—in other words, you can't combine no-snapshot with other modes.

Remarks

You can combine these flags but you can only choose one flag from each group of related flags. Groups are indicated under the headings in the previous section.

The STGM_SIMPLE flag is applicable only when combined with the following flags:

STGM_CREATE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

The STGM_DIRECT flag can be combined with one of the following flags:

STGM_READ | STGM_SHARE_DENY_WRITE
 or
STGM_READWRITE | STGM_SHARE_EXCLUSIVE
 or
STGM_READ | STGM_PRIORITY

Note that direct mode is implied by the absence of STGM_TRANSACTED.

With single-writer, multi-reader, direct mode, the following flag combinations are valid:

STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE
and
STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

This mode is useful for applications that perform complete save operations. It has the following constraints:

  • There is no support for substorages.
  • Access to streams follows a linear pattern. Once a stream is released, that stream cannot be opened for read/write operations again. The IStorage::OpenStream method is not supported in this implementation.
  • The storage and stream objects cannot be marshaled.
  • Each stream is at least 4096 bytes in length. If fewer than 4096 bytes are written into a stream by the time the stream is released, the stream will be extended to contain 4096 bytes.
  • In this compound file implementation, only a subset of the methods of IStorage and IStream are available.

Specifically, in simple mode, supported IStorage methods are QueryInterface, AddRef, Release, CreateStream, Commit, and SetClass. In addition, SetElementTimes is supported with a NULL name, allowing applications to set times on a root storage in simple mode.

Supported IStream methods are QueryInterface, AddRef, Release, Seek, and SetSize. Also, Read and Write methods on ISequentialStream are supported.

All the other methods of IStorage and IStream return STG_E_INVALIDFUNCTION.

File optimization modes such as STGM_SIMPLE, STGM_NOSCRATCH, and STGM_NOSNAPSHOT are not supported for NTFS native structured storage files. When storing storage objects on NTFS systems in native file format, the files are automatically converted to regular file format for all non-NT and FAT partitions.


TYMED

The TYMED enumeration is used in the STGMEDIUM structure.

At a Glance

Header file: | Objidl.h
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagTYMED {
TYMED_HGLOBAL = 1,
TYMED_FILE = 2,
TYMED_ISTREAM = 4,
TYMED_ISTORAGE = 8,
TYMED_NULL = 0,
} TYMED;

Elements

TYMED_HGLOBAL
The storage medium is a global memory handle (HGLOBAL). Allocate the global handle with the GMEM_SHARE flag. If the STGMEDIUM punkForRelease member is NULL, the destination process should use GlobalFree to release the memory.
TYMED_FILE
The storage medium is a disk file identified by a path. If the STGMEDIUM punkForRelease member is NULL, the destination process should use OpenFile to delete the file.
TYMED_ISTREAM
The storage medium is a stream object identified by an IStream pointer. Use ISequentialStream::Read to read the data. If the STGMEDIUM punkForRelease member is NULL, the destination process should use IStream::Release to release the stream component.
TYMED_ISTORAGE
The storage medium is a storage component identified by an IStorage pointer. The data is in the streams and storages contained by this IStorage instance. If the STGMEDIUM punkForRelease member is NULL, the destination process should use IStorage::Release to release the storage component.
TYMED_GDI
The storage medium is a GDI component (HBITMAP). If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteObject to delete the bitmap.
TYMED_MFPICT
The storage medium is a metafile (HMETAFILE). Use the Windows or Win32 functions to access the metafile's data. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteMetaFile to delete the bitmap.
TYMED_ENHMF
The storage medium is an enhanced metafile. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteEnhMetaFile to delete the bitmap.
TYMED_NULL
No data is being passed.

Remarks

Windows CE does not support the values TYMED_GDI, TYMED_MFPICT, or TYMED_ENHMF.

During data transfer operations, a storage medium is specified. This medium must be released after the data transfer operation. The provider of the medium indicates its choice of ownership scenarios in the value it provides in the STGMEDIUM structure. A NULL value for the IUNKNOWN field indicates that the receiving body of code owns and can free the medium. A non-NULL pointer specifies that ReleaseStgMedium can always be called to free the medium.

See Also

STGMEDIUM


TYPEKIND

The TYPEKIND enumeration specifies various types of data and functions.

At a Glance

Header file: | Oaidl.idl
Windows CE versions: | 2.0 and later

Syntax

typedef enum tagTYPEKIND {
TKIND_ENUM = 0,
TKIND_RECORD,
TKIND_MODULE,
TKIND_INTERFACE
TKIND_DISPATCH,
TKIND_COCLASS,
TKIND_ALIAS
TKIND_UNION
TKIND_MAX
} TYPEKIND;

Elements

TKIND_ALIAS
A type that is an alias for another type.
TKIND_COCLASS
A set of implemented component object interfaces.
TKIND_DISPATCH
A set of methods and properties that are accessible through IDispatch::Invoke. By default, dual interfaces return TKIND_DISPATCH.
TKIND_ENUM
A set of enumerators.
TKIND_INTERFACE
A type that has virtual functions, all of which are pure.
TKIND_MODULE
A module that can only have static functions and data (for example, a DLL).
TKIND_RECORD
A structure with no methods.
TKIND_UNION
A union, all of whose members have an offset of zero.
TKIND_MAX
End of ENUM marker.


Simple Data Types

Various simple data types define the size and meaning of parameters, return values, and members associated with the functions, messages, and structures of Windows CE.

Type
Definition
ABORTPROC | Pointer to an application-defined callback function that the operating system calls when a print job is to be canceled during spooling.
ATOM | Atom (a reference to a character string in an atom table).
BOOL | Boolean variable (should be TRUE or FALSE).
BOOLEAN | Boolean variable (should be TRUE or FALSE).
BYTE | Byte (8 bits).
CCHAR | Windows character.
CEOID | Unique object identifier that can be used to specify an object in the Windows CE Object Store.
CEGUID | Globally unique identifier that can be used to specify a database volume
CHAR | Windows character.
COLORREF | Red, green, blue (RGB) color value (32 bits).
CONST | Variable whose value is to remain constant during execution.
CRITICAL_SECTION | Critical-section object.
DLGPROC | Pointer to an application-defined dialog box callback procedure.
DWORD | Doubleword (32 bits).
DWORDLONG | Double (64 bits).
FARPROC | Pointer to a callback function.
FLOAT | Floating-point variable.
FONTENUMPROC | Pointer to an application-defined callback function that enumerates fonts.
GLOBALHANDLE | Handle of a global memory block.
HACCEL | Handle of an accelerator table.
HANDLE | Handle of an object.
HBITMAP | Handle of a bitmap.
HBRUSH | Handle of a brush.
HCURSOR | Handle of a cursor.
HDC | Handle of a device context (DC).
HFILE | Handle of a file.
HFONT | Handle of a font.
HGDIOBJ | Handle of a GDI object.
HGLOBAL | Handle of a global memory block.
HHOOK | Handle of a hook.
HICON | Handle of an icon.
HINSTANCE | Handle of an instance.
HKEY | Handle of a registry key.
HKL | Handle of a keyboard layout.
HLOCAL | Handle of a local memory block.
HMENU | Handle of a menu.
HMODULE | Handle of a module.
HPALETTE | Handle of a palette.
HPEN | Handle of a pen.
HRGN | Handle of a region.
HRSRC | Handle of a resource.
HWINSTA | Handle of a workstation.
HWND | Handle of a window.
INT | Signed integer.
LANGID | Language identifier.
LCID | Locale identifier.
LCTYPE | Locale type.
LOCALHANDLE | Handle of a local memory block.
LONG | 32-bit signed value.
LONGLONG | Double (64 bits).
LP | Pointer to a null-terminated Unicode™ string.
LPARAM | 32-bit message parameter.
LPBOOL | Pointer to a Boolean variable.
LPBYTE | Pointer to a byte.
LPCCH | Pointer to a constant Windows character.
LPCH | Pointer to a Windows character.
LPCOLORREF | Pointer to a COLORREF value.
LPCRITICAL_SECTION | Pointer to a critical-section object.
LPCSTR | Pointer to a constant null-terminated Windows character string.
LPCTSTR | Pointer to a constant null-terminated Unicode or Windows character string.
LPCWCH | Pointer to a constant null-terminated Unicode character.
LPCWSTR | Pointer to a constant null-terminated Unicode character string.
LPDWORD | Pointer to an unsigned doubleword (32 bits).
LPHANDLE | Pointer to a handle.
LPINT | Pointer to a signed integer.
LPLONG | Pointer to a signed long (32 bits).
LPSTR | Pointer to a null-terminated Windows character string.
LPTCH | Pointer to a Unicode character or a Windows character.
LPTSTR | Pointer to a null-terminated Windows or Unicode character string.
LRESULT | Signed result of message processing.
LPVOID | Pointer to any type.
LPWCH | Pointer to a Unicode character.
LPWORD | Pointer to an unsigned word (16 bits).
LPWSTR | Pointer to a null-terminated Unicode character string.
LUID | Locally unique identifier.
NPSTR | Pointer to a null-terminated Windows character string.
NWPSTR | Pointer to a null-terminated Unicode string.
PBOOL | Pointer to a Boolean variable.
PBOOLEAN | Pointer to a Boolean variable.
PBYTE | Pointer to a byte.
PCCH | Pointer to a constant Windows character.
PCH | Pointer to a Windows character.
PCHAR | Pointer to a Windows character.
PCSTR | Pointer to a constant null-terminated Windows character string.
PCWCH | Pointer to a constant Unicode character.
PCWSTR | Pointer to a constant null-terminated Unicode character string.
PDWORD | Pointer to an unsigned doubleword (32 bits).
PEGOID | Unique object identifier that can be used to specify an object in the Windows CE Object Store.
PFLOAT | Pointer to a floating-point variable.
PHANDLE | Pointer to a handle.
PHKEY | Pointer to a registry key.
PINT | Pointer to a signed integer.
PLCID | Pointer to a locale identifier.
PLONG | Pointer to a signed long (32 bits).
PLUID | Pointer to a locally unique identifier (LUID).
PROC | Pointer to a callback function.
PSHORT | Pointer to a signed short (16 bits).
PSID | Pointer to a security identifier (SID).
PSTR | Pointer to a null-terminated Windows character string.
PSZ | Pointer to a null-terminated Windows character string.
PTBYTE | Pointer to a Windows or Unicode character.
PTCH | Pointer to a Windows or Unicode character.
PTCHAR | Pointer to a Windows or Unicode character.
PTSTR | Pointer to a null-terminated Windows or Unicode character string.
PUCHAR | Pointer to an unsigned Windows character.
PUINT | Pointer to an unsigned integer.
PULONG | Pointer to an unsigned long (32 bits).
PUSHORT | Pointer to an unsigned short (16 bits).
PVOID | Pointer to any type.
PWCH | Pointer to a Unicode character.
PWCHAR | Pointer to a Unicode character.
PWORD | Pointer to an unsigned word (16 bits).
PWSTR | Pointer to a null-terminated Unicode character string.
REGSAM | Security access mask for registry key.
SHORT | Short integer.
SPHANDLE | Pointer to a handle.
TBYTE | Windows or Unicode character.
TCHAR | Unicode character or Windows character.
TIMERPROC | Pointer to an application-defined timer callback function.
UCHAR | Unsigned Windows character.
UINT | Unsigned integer.
ULONG | Unsigned long integer (32 bits).
USHORT | Unsigned short integer (16 bits).
VOID | Any type.
WCHAR | Unicode character.
WNDENUMPROC | Pointer to an application-defined callback function that enumerates windows.
WNDPROC | Pointer to an application-defined window procedure.
WORD | Unsigned word (16 bits).
WPARAM | 32-bit message parameter.


Error Values

This appendix lists the system error codes returned by the GetLastError function for many of the Win32 functions and the network error codes returned by the Net functions. These errors are listed in the following topics:

  • System Errors - Alphabetical Order
  • System Errors - Numerical Order
  • Net Errors - Alphabetical Order
  • Net Errors - Numerical Order


System Errors - Alphabetical Order

The following table shows possible system error values.

Name
Description
Code
EPT_S_CANT_CREATE | The endpoint mapper database could not be created. | 1899
EPT_S_CANT_PERFORM_OP | The server endpoint cannot perform the operation. | 1752
EPT_S_INVALID_ENTRY | The entry is invalid. | 1751
EPT_S_NOT_REGISTERED | There are no more endpoints available from the endpoint mapper. | 1753
ERROR_ACCESS_DENIED | Access is denied. | 5
ERROR_ACCOUNT_DISABLED | Logon failure—account currently disabled. | 1331
ERROR_ACCOUNT_EXPIRED | The user's account has expired. | 1793
ERROR_ACCOUNT_LOCKED_OUT | The referenced account is currently locked out and may not be logged on to. | 1909
ERROR_ACCOUNT_RESTRICTION | Logon failure—user account restriction. | 1327
ERROR_ACTIVE_CONNECTIONS | Active connections still exist. | 2402
ERROR_ADAP_HDW_ERR | A network adapter hardware error occurred. | 57
ERROR_ADDRESS_ALREADY_ASSOCIATED | The network transport endpoint already has an address associated with it. | 1227
ERROR_ADDRESS_NOT_ASSOCIATED | An address has not yet been associated with the network endpoint. | 1228
ERROR_ALIAS_EXISTS | The specified local group already exists. | 1379
ERROR_ALLOTTED_SPACE_EXCEEDED | No more memory is available for security information updates. | 1344
ERROR_ALREADY_ASSIGNED | The local device name is already in use. | 85
ERROR_ALREADY_EXISTS | Cannot create a file when that file already exists. | 183
ERROR_ALREADY_INITIALIZED | An attempt was made to perform an initialization operation when initialization has already been completed. | 1247
ERROR_ALREADY_REGISTERED | The service is already registered. | 1242
ERROR_ALREADY_RUNNING_LKG | The system is currently running with the last-known-good configuration. | 1074
ERROR_ALREADY_WAITING | The specified printer handle is already being waited on | 1904
ERROR_APP_WRONG_OS | The specified program is not a Windows or MS-DOS program. | 1151
ERROR_ARENA_TRASHED | The storage control blocks were destroyed. | 7
ERROR_ARITHMETIC_OVERFLOW | Arithmetic result exceeded 32 bits. | 534
ERROR_ATOMIC_LOCKS_NOT_SUPPORTED | The file system does not support atomic changes to the lock type. | 174
ERROR_AUTODATASEG_EXCEEDS_64k | The operating system cannot run this application program. | 199
ERROR_BAD_ARGUMENTS | The argument string passed to DosExecPgm is not correct. | 160
ERROR_BAD_COMMAND | The device does not recognize the command. | 22
ERROR_BAD_DESCRIPTOR_FORMAT | A security descriptor is not in the right format (absolute or self-relative). | 1361
ERROR_BAD_DEV_TYPE | The network resource type is not correct. | 66
ERROR_BAD_DEVICE | The specified device name is invalid. | 1200
ERROR_BAD_DRIVER | The specified driver is invalid. | 2001
ERROR_BAD_DRIVER_LEVEL | The system does not support the command requested. | 119
ERROR_BAD_ENVIRONMENT | The environment is incorrect. | 10
ERROR_BAD_EXE_FORMAT | Is not a valid application. | 193
ERROR_BAD_FORMAT | An attempt was made to load a program with an incorrect format. | 11
ERROR_BAD_IMPERSONATION_LEVEL | Either a required impersonation level was not provided, or the provided impersonation level is invalid. | 1346
ERROR_BAD_INHERITANCE_ACL | The inherited access control list (ACL) or access control entry (ACE) could not be built. | 1340
ERROR_BAD_LENGTH | The program issued a command but the command length is incorrect. | 24
ERROR_BAD_LOGON_SESSION_STATE | The logon session is not in a state that is consistent with the requested operation. | 1365
ERROR_BAD_NET_NAME | The network name cannot be found. | 67
ERROR_BAD_NET_RESP | The specified server cannot perform the requested operation. | 58
ERROR_BAD_NETPATH | The network path was not found. | 53
ERROR_BAD_PATHNAME | The specified path is invalid. | 161
ERROR_BAD_PIPE | The pipe state is invalid. | 230
ERROR_BAD_PROFILE | The network connection profile is corrupted. | 1206
ERROR_BAD_PROVIDER | The specified network provider name is invalid. | 1204
ERROR_BAD_REM_ADAP | The remote adapter is not compatible. | 60
ERROR_BAD_THREADID_ADDR | The address for the thread identifier is not correct. | 159
ERROR_BAD_TOKEN_TYPE | The type of the token is inappropriate for its attempted use. | 1349
ERROR_BAD_UNIT | The system cannot find the specified device . | 20
ERROR_BAD_USERNAME | The specified user name is invalid. | 2202
ERROR_BAD_VALIDATION_CLASS | The validation information class requested was invalid. | 1348
ERROR_BADDB | The configuration registry database is corrupt. | 1009
ERROR_BADKEY | The configuration registry key is invalid. | 1010
ERROR_BEGINNING_OF_MEDIA | The beginning of the tape or partition was encountered. | 1102
ERROR_BOOT_ALREADY_ACCEPTED | The current boot has already been accepted for use as the last-known-good control set. | 1076
ERROR_BROKEN_PIPE | The pipe has been ended. | 109
ERROR_BUFFER_OVERFLOW | The file name is too long. | 111
ERROR_BUS_RESET | The I/O bus was reset. | 1111
ERROR_BUSY | The requested resource is in use. | 170
ERROR_BUSY_DRIVE | The system cannot perform a JOIN or SUBST at this time. | 142
ERROR_CALL_NOT_IMPLEMENTED | This function is not valid on this platform. | 120
ERROR_CAN_NOT_COMPLETE | Cannot complete this function. | 1003
ERROR_CAN_NOT_DEL_LOCAL_WINS | The local WINS can not be deleted. | 4001
ERROR_CANCEL_VIOLATION | A lock request was not outstanding for the supplied cancel region. | 173
ERROR_CANCELLED | The operation was canceled by the user. | 1223
ERROR_CANNOT_COPY | The copy functions cannot be used. | 266
ERROR_CANNOT_FIND_WND_CLASS | Cannot find window class. | 1407
ERROR_CANNOT_IMPERSONATE | Unable to impersonate using a named pipe until data has been read from that pipe. | 1368
ERROR_CANNOT_MAKE | The directory or file cannot be created. | 82
ERROR_CANNOT_OPEN_PROFILE | Unable to open the network connection profile. | 1205
ERROR_CANT_ACCESS_DOMAIN_INFO | Indicates that a Windows NT Server could not be contacted or that objects within the domain are protected such that necessary information could not be retrieved. | 1351
ERROR_CANT_DISABLE_MANDATORY | The group cannot be disabled. | 1310
ERROR_CANT_OPEN_ANONYMOUS | Cannot open an anonymous level security token. | 1347
ERROR_CANTOPEN | The configuration registry key could not be opened. | 1011
ERROR_CANTREAD | The configuration registry key could not be read. | 1012
ERROR_CANTWRITE | The configuration registry key could not be written. | 1013
ERROR_CHILD_MUST_BE_VOLATILE | Cannot create a stable subkey under a volatile parent key. | 1021
ERROR_CHILD_NOT_COMPLETE | The %1 application cannot be run in Windows NT mode. | 129
ERROR_CHILD_WINDOW_MENU | Child windows cannot have menus. | 1436
ERROR_CIRCULAR_DEPENDENCY | Circular service dependency was specified. | 1059
ERROR_CLASS_ALREADY_EXISTS | Class already exists. | 1410
ERROR_CLASS_DOES_NOT_EXIST | Class does not exist. | 1411
ERROR_CLASS_HAS_WINDOWS | Class still has open windows. | 1412
ERROR_CLIPBOARD_NOT_OPEN | Thread does not have a clipboard open. | 1418
ERROR_CLIPPING_NOT_SUPPORTED | The requested clipping operation is not supported. | 2005
ERROR_COMMITMENT_LIMIT | The paging file is too small for this operation to complete. | 1455
ERROR_CONNECTION_ABORTED | The network connection was aborted by the local system. | 1236
ERROR_CONNECTION_ACTIVE | An invalid operation was attempted on an active network connection. | 1230
ERROR_CONNECTION_COUNT_LIMIT | A connection to the server could not be made because the limit on the number of concurrent connections for this account has been reached. | 1238
ERROR_CONNECTION_INVALID | An operation was attempted on a nonexistent network connection. | 1229
ERROR_CONNECTION_REFUSED | The remote system refused the network connection. | 1225
ERROR_CONNECTION_UNAVAIL | The device is not currently connected but it is a remembered connection. | 1201
ERROR_CONTINUE | Continue with work in progress. | 1246
ERROR_CONTROL_ID_NOT_FOUND | Control identifier not found. | 1421
ERROR_COUNTER_TIMEOUT | A serial I/O operation completed because the time-out period expired. In other words, the IOCTL_SERIAL_XOFF_COUNTER did not reach zero. | 1121
ERROR_CRC | Data error (cyclic redundancy check). | 23
ERROR_CURRENT_DIRECTORY | The directory cannot be removed. | 16
ERROR_DATABASE_DOES_NOT_EXIST | The database specified does not exist. | 1065
ERROR_DC_NOT_FOUND | Invalid device context (DC) handle. | 1425
ERROR_DDE_FAIL | An error occurred in sending the command to the application. | 1156
ERROR_DEPENDENT_SERVICES_RUNNING | A stop control has been sent to a service that other running services are dependent on. | 1051
ERROR_DESTROY_OBJECT_OF_OTHER_THREAD | Cannot destroy object created by another thread. | 1435
ERROR_DEV_NOT_EXIST | The specified network resource or device is no longer available. | 55
ERROR_DEVICE_ALREADY_REMEMBERED | An attempt was made to remember a device that had previously been remembered. | 1202
ERROR_DEVICE_IN_USE | The device is in use by an active process and cannot be disconnected. | 2404
ERROR_DEVICE_NOT_PARTITIONED | Tape partition information could not be found when loading a tape. | 1107
ERROR_DIFFERENT_SERVICE_ACCOUNT | The account specified for this service is different from the account specified for other services running in the same process. | 1079
ERROR_DIR_NOT_EMPTY | The directory is not empty. | 145
ERROR_DIR_NOT_ROOT | The directory is not a subdirectory of the root directory. | 144
ERROR_DIRECT_ACCESS_HANDLE | Attempt to use a file handle to an open disk partition for an operation other than raw disk I/O. | 130
ERROR_DIRECTORY | The directory name is invalid. | 267
ERROR_DISCARDED | The segment is already discarded and cannot be locked. | 157
ERROR_DISK_CHANGE | The program stopped because an alternate diskette was not inserted. | 107
ERROR_DISK_CORRUPT | The disk structure is corrupted and non-readable. | 1393
ERROR_DISK_FULL | There is not enough space on the disk. | 112
ERROR_DISK_OPERATION_FAILED | While accessing the hard disk, a disk operation failed even after retries. | 1127
ERROR_DISK_RECALIBRATE_FAILED | While accessing the hard disk, a recalibrate operation failed, even after retries. | 1126
ERROR_DISK_RESET_FAILED | While accessing the hard disk, a disk controller reset was needed, but even that failed. | 1128
ERROR_DLL_INIT_FAILED | A dynamic link library (DLL) initialization routine failed. | 1114
ERROR_DLL_NOT_FOUND | One of the library files needed to run this application cannot be found. | 1157
ERROR_DOMAIN_CONTROLLER_NOT_FOUND | Could not find the domain controller for this domain. | 1908
ERROR_DOMAIN_EXISTS | The specified domain already exists. | 1356
ERROR_DOMAIN_LIMIT_EXCEEDED | An attempt was made to exceed the limit on the number of domains per server. | 1357
ERROR_DOMAIN_TRUST_INCONSISTENT | The name or security identifier (SID) of the domain specified is inconsistent with the trust information for that domain. | 1810
ERROR_DRIVE_LOCKED | The disk is in use or locked by another process. | 108
ERROR_DUP_DOMAINNAME | The workgroup or domain name is already in use by another computer on the network. | 1221
ERROR_DUP_NAME | A duplicate name exists on the network. | 52
ERROR_DUPLICATE_SERVICE_NAME | The name is already in use as either a service name or a service display name. | 1078
ERROR_DYNLINK_FROM_INVALID_RING | The operating system cannot run this application program. | 196
ERROR_EA_ACCESS_DENIED | Access to the extended attribute was denied. | 994
ERROR_EA_FILE_CORRUPT | The extended attribute file on the mounted file system is corrupt. | 276
ERROR_EA_LIST_INCONSISTENT | The extended attributes are inconsistent. | 255
ERROR_EA_TABLE_FULL | The extended attribute table file is full. | 277
ERROR_EAS_DIDNT_FIT | The extended attributes did not fit in the buffer. | 275
ERROR_EAS_NOT_SUPPORTED | The mounted file system does not support extended attributes. | 282
ERROR_END_OF_MEDIA | The physical end of the tape has been reached. | 1100
ERROR_ENVVAR_NOT_FOUND | The system could not find the environment option that was entered. | 203
ERROR_EOM_OVERFLOW | Physical end of tape encountered. | 1129
ERROR_EVENTLOG_CANT_START | No event log file could be opened, so the event logging service did not start. | 1501
ERROR_EVENTLOG_FILE_CHANGED | The event log file has changed between read operations. | 1503
ERROR_EVENTLOG_FILE_CORRUPT | The event log file is corrupted. | 1500
ERROR_EXCEPTION_IN_SERVICE | An exception occurred in the service when handling the control request. | 1064
ERROR_EXCL_SEM_ALREADY_OWNED | The exclusive semaphore is owned by another process. | 101
ERROR_EXE_MACHINE_TYPE_MISMATCH | The image file %1 is valid, but is for a machine type other than the current machine. | 216
ERROR_EXE_MARKED_INVALID | The operating system cannot run %1. | 192
ERROR_EXTENDED_ERROR | An extended error has occurred. | 1208
ERROR_FAIL_I24 | Fail on INT 24. | 83
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT | The service process could not connect to the service controller. | 1063
ERROR_FILE_CORRUPT | The file or directory is corrupted and non-readable. | 1392
ERROR_FILE_EXISTS | The file exists. | 80
ERROR_FILE_INVALID | The volume for a file has been externally altered so that the opened file is no longer valid. | 1006
ERROR_FILE_NOT_FOUND | The system cannot find the file specified. | 2
ERROR_FILEMARK_DETECTED | A tape access reached a filemark. | 1101
ERROR_FILENAME_EXCED_RANGE | The file name or extension is too long. | 206
ERROR_FLOPPY_BAD_REGISTERS | The floppy disk controller returned inconsistent results in its registers. | 1125
ERROR_FLOPPY_ID_MARK_NOT_FOUND | No identifier address mark was found on the floppy disk. | 1122
ERROR_FLOPPY_UNKNOWN_ERROR | The floppy disk controller reported an error that is not recognized by the floppy disk driver. | 1124
ERROR_FLOPPY_WRONG_CYLINDER | Mismatch between the floppy disk sector identifier field and the floppy disk controller track address. | 1123
ERROR_FULL_BACKUP | The backup failed. Check the directory to which you are backing the database. | 4004
ERROR_FULLSCREEN_MODE | The requested operation cannot be performed in full-screen mode. | 1007
ERROR_GEN_FAILURE | A device attached to the system is not functioning. | 31
ERROR_GENERIC_NOT_MAPPED | Generic access types were contained in an access mask that should already be mapped to nongeneric types. | 1360
ERROR_GLOBAL_ONLY_HOOK | This hook procedure can only be set globally. | 1429
ERROR_GRACEFUL_DISCONNECT | The network connection was gracefully closed. | 1226
ERROR_GROUP_EXISTS | The specified group already exists. | 1318
ERROR_HANDLE_DISK_FULL | The disk is full. | 39
ERROR_HANDLE_EOF | Reached the end of the file. | 38
ERROR_HOOK_NEEDS_HMOD | Cannot set nonlocal hook without a module handle. | 1428
ERROR_HOOK_NOT_INSTALLED | The hook procedure is not installed. | 1431
ERROR_HOOK_TYPE_NOT_ALLOWED | Hook type not allowed. | 1458
ERROR_HOST_UNREACHABLE | The remote system is not reachable by the transport. | 1232
ERROR_HOTKEY_ALREADY_REGISTERED | Hot key is already registered. | 1409
ERROR_HOTKEY_NOT_REGISTERED | Hot key is not registered. | 1419
ERROR_HWNDS_HAVE_DIFF_PARENT | All handles to windows in a multiple-window position structure must have the same parent. | 1441
ERROR_ILL_FORMED_PASSWORD | Unable to update the password. The value provided for the new password contains values that are not allowed in passwords. | 1324
ERROR_INC_BACKUP | The backup failed. Was a full backup done before? | 4003
ERROR_INCORRECT_ADDRESS | The network address could not be used for the operation requested. | 1241
ERROR_INFLOOP_IN_RELOC_CHAIN | The operating system cannot run %1. | 202
ERROR_INSUFFICIENT_BUFFER | The data area passed to a system call is too small. | 122
ERROR_INTERNAL_DB_CORRUPTION | Unable to complete the requested operation because of either a catastrophic media failure or a data structure corruption on the disk. | 1358
ERROR_INTERNAL_DB_ERROR | The local security authority database contains an internal inconsistency. | 1383
ERROR_INTERNAL_ERROR | The security account database contains an internal inconsistency. | 1359
ERROR_INVALID_ACCEL_HANDLE | Invalid accelerator table handle. | 1403
ERROR_INVALID_ACCESS | The access code is invalid. | 12
ERROR_INVALID_ACCOUNT_NAME | The name provided is not a properly formed account name. | 1315
ERROR_INVALID_ACL | The access control list (ACL) structure is invalid. | 1336
ERROR_INVALID_ADDRESS | Attempt to access invalid address. | 487
ERROR_INVALID_AT_INTERRUPT_TIME | Cannot request exclusive semaphores at interrupt time. | 104
ERROR_INVALID_BLOCK | The storage control block address is invalid. | 9
ERROR_INVALID_BLOCK_LENGTH | When accessing a new tape of a multivolume partition, the current block size is incorrect. | 1106
ERROR_INVALID_CATEGORY | The IOCTL call made by the application program is not correct. | 117
ERROR_INVALID_COMBOBOX_MESSAGE | Invalid message for a combo box because it does not have an edit control. | 1422
ERROR_INVALID_COMPUTERNAME | The format of the specified computer name is invalid. | 1210
ERROR_INVALID_CURSOR_HANDLE | Invalid cursor handle. | 1402
ERROR_INVALID_DATA | The data is invalid. | 13
ERROR_INVALID_DATATYPE | The specified data type is invalid. | 1804
ERROR_INVALID_DLL | One of the library files needed to run this application is damaged. | 1154
ERROR_INVALID_DOMAIN_ROLE | This operation is only allowed for the Primary Domain Controller (PDC) of the domain. | 1354
ERROR_INVALID_DOMAIN_STATE | The domain was in the wrong state to perform the security operation. | 1353
ERROR_INVALID_DOMAINNAME | The format of the specified domain name is invalid. | 1212
ERROR_INVALID_DRIVE | The system cannot find the drive specified. | 15
ERROR_INVALID_DWP_HANDLE | Invalid handle to a multiple-window position structure. | 1405
ERROR_INVALID_EA_HANDLE | The specified extended attribute handle is invalid. | 278
ERROR_INVALID_EA_NAME | The specified extended attribute name was invalid. | 254
ERROR_INVALID_EDIT_HEIGHT | Height must be less than 256. | 1424
ERROR_INVALID_ENVIRONMENT | The environment specified is invalid. | 1805
ERROR_INVALID_EVENT_COUNT | The number of specified semaphore events for DosMuxSemWait is not correct. | 151
ERROR_INVALID_EVENTNAME | The format of the specified event name is invalid. | 1211
ERROR_INVALID_EXE_SIGNATURE | Cannot run %1 in Windows NT mode. | 191
ERROR_INVALID_FILTER_PROC | Invalid hook procedure. | 1427
ERROR_INVALID_FLAG_NUMBER | The flag passed is not correct. | 186
ERROR_INVALID_FLAGS | Invalid flags. | 1004
ERROR_INVALID_FORM_NAME | The specified form name is invalid. | 1902
ERROR_INVALID_FORM_SIZE | The specified form size is invalid. | 1903
ERROR_INVALID_FUNCTION | Incorrect function. | 1
ERROR_INVALID_GROUP_ATTRIBUTES | The specified attributes are invalid, or incompatible with the attributes for the group as a whole. | 1345
ERROR_INVALID_GROUPNAME | The format of the specified group name is invalid. | 1209
ERROR_INVALID_GW_COMMAND | Invalid GW_* command. | 1443
ERROR_INVALID_HANDLE | The handle is invalid. | 6
ERROR_INVALID_HOOK_FILTER | Invalid hook procedure type. | 1426
ERROR_INVALID_HOOK_HANDLE | Invalid hook handle. | 1404
ERROR_INVALID_ICON_HANDLE | Invalid icon handle. | 1414
ERROR_INVALID_ID_AUTHORITY | The value provided was an invalid value for an identifier authority. | 1343
ERROR_INVALID_INDEX | Invalid index. | 1413
ERROR_INVALID_KEYBOARD_HANDLE | Invalid keyboard layout handle. | 1457
ERROR_INVALID_LB_MESSAGE | Invalid message for single-selection list box. | 1432
ERROR_INVALID_LEVEL | The system call level is not correct. | 124
ERROR_INVALID_LIST_FORMAT | The DosMuxSemWait list is not correct. | 153
ERROR_INVALID_LOGON_HOURS | Logon failure—account logon time restriction violation. | 1328
ERROR_INVALID_LOGON_TYPE | A logon request contained an invalid logon type value. | 1367
ERROR_INVALID_MEMBER | A new member could not be added to a local group because the member has the wrong account type. | 1388
ERROR_INVALID_MENU_HANDLE | Invalid menu handle. | 1401
ERROR_INVALID_MESSAGE | The window cannot act on the sent message. | 1002
ERROR_INVALID_MESSAGEDEST | The format of the specified message destination is invalid. | 1218
ERROR_INVALID_MESSAGENAME | The format of the specified message name is invalid. | 1217
ERROR_INVALID_MINALLOCSIZE | The operating system cannot run %1. | 195
ERROR_INVALID_MODULETYPE | The operating system cannot run %1. | 190
ERROR_INVALID_MSGBOX_STYLE | Invalid message box style. | 1438
ERROR_INVALID_NAME | The file name, directory name, or volume label syntax is incorrect. | 123
ERROR_INVALID_NETNAME | The format of the specified network name is invalid. | 1214
ERROR_INVALID_ORDINAL | The operating system cannot run %1. | 182
ERROR_INVALID_OWNER | This security identifier may not be assigned as the owner of this object. | 1307
ERROR_INVALID_PARAMETER | The parameter is incorrect. | 87
ERROR_INVALID_PASSWORD | The specified network password is not correct. | 86
ERROR_INVALID_PASSWORDNAME | The format of the specified password is invalid. | 1216
ERROR_INVALID_PIXEL_FORMAT | The pixel format is invalid. | 2000
ERROR_INVALID_PRIMARY_GROUP | This security identifier may not be assigned as the primary group of an object. | 1308
ERROR_INVALID_PRINT_MONITOR | The specified print monitor does not have the required functions. | 3007
ERROR_INVALID_PRINTER_COMMAND | The printer command is invalid. | 1803
ERROR_INVALID_PRINTER_NAME | The printer name is invalid. | 1801
ERROR_INVALID_PRINTER_STATE | The state of the printer is invalid. | 1906
ERROR_INVALID_PRIORITY | The specified priority is invalid. | 1800
ERROR_INVALID_SCROLLBAR_RANGE | Scroll bar range cannot be greater than 0x7FFF. | 1448
ERROR_INVALID_SECURITY_DESCR | The security descriptor structure is invalid. | 1338
ERROR_INVALID_SEGDPL | The operating system cannot run %1. | 198
ERROR_INVALID_SEGMENT_NUMBER | The system detected a segment number that was not correct. | 180
ERROR_INVALID_SEPARATOR_FILE | The specified separator file is invalid. | 1799
ERROR_INVALID_SERVER_STATE | The security account manager (SAM) or local security authority (LSA) server was in the wrong state to perform the security operation. | 1352
ERROR_INVALID_SERVICE_ACCOUNT | The account name is invalid or does not exist. | 1057
ERROR_INVALID_SERVICE_CONTROL | The requested control is not valid for this service. | 1052
ERROR_INVALID_SERVICE_LOCK | The specified service database lock is invalid. | 1071
ERROR_INVALID_SERVICENAME | The format of the specified service name is invalid. | 1213
ERROR_INVALID_SHARENAME | The format of the specified share name is invalid. | 1215
ERROR_INVALID_SHOWWIN_COMMAND | Cannot show or remove the window in the way specified. | 1449
ERROR_INVALID_SID | The security identifier structure is invalid. | 1337
ERROR_INVALID_SIGNAL_NUMBER | The signal being posted is not correct. | 209
ERROR_INVALID_SPI_VALUE | Invalid system-wide (SPI_*) parameter. | 1439
ERROR_INVALID_STACKSEG | The operating system cannot run %1. | 189
ERROR_INVALID_STARTING_CODESEG | The operating system cannot run %1. | 188
ERROR_INVALID_SUB_AUTHORITY | The subauthority part of a security identifier is invalid for this particular use. | 1335
ERROR_INVALID_TARGET_HANDLE | The target internal file identifier is incorrect. | 114
ERROR_INVALID_THREAD_ID | Invalid thread identifier. | 1444
ERROR_INVALID_TIME | The specified time is invalid. | 1901
ERROR_INVALID_USER_BUFFER | The supplied user buffer is not valid for the requested operation. | 1784
ERROR_INVALID_VERIFY_SWITCH | The verify-on-write switch parameter value is not correct. | 118
ERROR_INVALID_WINDOW_HANDLE | Invalid window handle. | 1400
ERROR_INVALID_WINDOW_STYLE | The window style or class attribute is invalid for this operation. | 2002
ERROR_INVALID_WORKSTATION | Logon failure—user not allowed to log on to this computer. | 1329
ERROR_IO_DEVICE | The request could not be performed because of an I/O device error. | 1117
ERROR_IO_INCOMPLETE | Overlapped I/O event is not in a signaled state. | 996
ERROR_IO_PENDING | Overlapped I/O operation is in progress. | 997
ERROR_IOPL_NOT_ENABLED | The operating system is not presently configured to run this application. | 197
ERROR_IRQ_BUSY | Unable to open a device that was sharing an interrupt request (IRQ) with other devices. At least one other device that uses that IRQ was already opened. | 1119
ERROR_IS_JOIN_PATH | Not enough resources are available to process this command. | 147
ERROR_IS_JOIN_TARGET | A JOIN or SUBST command cannot be used for a drive that contains previously joined drives. | 133
ERROR_IS_JOINED | An attempt was made to use a JOIN or SUBST command on a drive that has already been joined. | 134
ERROR_IS_SUBST_PATH | The path specified is being used in a substitute. | 146
ERROR_IS_SUBST_TARGET | An attempt was made to join or substitute a drive for which a directory on the drive is the target of a previous substitute. | 149
ERROR_IS_SUBSTED | An attempt was made to use a JOIN or SUBST command on a drive that has already been substituted. | 135
ERROR_ITERATED_DATA_EXCEEDS_64k | The operating system cannot run %1. | 194
ERROR_JOIN_TO_JOIN | The system tried to join a drive to a directory on a joined drive. | 138
ERROR_JOIN_TO_SUBST | The system tried to join a drive to a directory on a substituted drive. | 140
ERROR_JOURNAL_HOOK_SET | The journal hook procedure is already installed. | 1430
ERROR_KEY_DELETED | Illegal operation attempted on a registry key that has been marked for deletion. | 1018
ERROR_KEY_HAS_CHILDREN | Cannot create a symbolic link in a registry key that already has subkeys or values. | 1020
ERROR_LABEL_TOO_LONG | The volume label you entered exceeds the label character limit of the target file system. | 154
ERROR_LAST_ADMIN | The last remaining administration account cannot be disabled or deleted. | 1322
ERROR_LB_WITHOUT_TABSTOPS | This list box does not support tab stops. | 1434
ERROR_LICENSE_QUOTA_EXCEEDED | The service being accessed is licensed for a particular number of connections. No more connections can be made to the service at this time because there are already as many connections as the service can accept. | 1395
ERROR_LISTBOX_ID_NOT_FOUND | The list box identifier was not found. | 1416
ERROR_LM_CROSS_ENCRYPTION_REQUIRED | A cross-encrypted password is necessary to change this user password. | 1390
ERROR_LOCAL_USER_SESSION_KEY | No encryption key is available. A well-known encryption key was returned. | 1303
ERROR_LOCK_FAILED | Unable to lock a region of a file. | 167
ERROR_LOCK_VIOLATION | The process cannot access the file because another process has locked a portion of the file. | 33
ERROR_LOCKED | The segment is locked and cannot be reallocated. | 212
ERROR_LOG_FILE_FULL | The event log file is full. | 1502
ERROR_LOGIN_TIME_RESTRICTION | Attempting to log in during an unauthorized time of day for this account. | 1239
ERROR_LOGIN_WKSTA_RESTRICTION | The account is not authorized to log in from this station. | 1240
ERROR_LOGON_FAILURE | Logon failure—unknown user name or bad password. | 1326
ERROR_LOGON_NOT_GRANTED | Logon failure—the user has not been granted the requested logon type at this computer. | 1380
ERROR_LOGON_SESSION_COLLISION | The logon session identifier is already in use. | 1366
ERROR_LOGON_SESSION_EXISTS | Cannot start a new logon session with an identifier that is already in use. | 1363
ERROR_LOGON_TYPE_NOT_GRANTED | Logon failure—the user has not been granted the requested logon type at this computer. | 1385
ERROR_LUIDS_EXHAUSTED | No more locally unique identifiers (LUIDs) are available. | 1334
ERROR_MAPPED_ALIGNMENT | The base address or the file offset specified does not have the proper alignment. | 1132
ERROR_MAX_THRDS_REACHED | No more threads can be created in the system. | 164
ERROR_MEDIA_CHANGED | The media in the drive may have changed. | 1110
ERROR_MEMBER_IN_ALIAS | The specified account name is already a member of the local group. | 1378
ERROR_MEMBER_IN_GROUP | Either the specified user account is already a member of the specified group, or the specified group cannot be deleted because it contains a member. | 1320
ERROR_MEMBER_NOT_IN_ALIAS | The specified account name is not a member of the local group. | 1377
ERROR_MEMBER_NOT_IN_GROUP | The specified user account is not a member of the specified group account. | 1321
ERROR_MEMBERS_PRIMARY_GROUP | The user cannot be removed from a group because the group is currently the user's primary group. | 1374
ERROR_MENU_ITEM_NOT_FOUND | A menu item was not found. | 1456
ERROR_META_EXPANSION_TOO_LONG | The global file name characters, “*” or “?,” are entered incorrectly or too many global file name characters are specified. | 208
ERROR_METAFILE_NOT_SUPPORTED | The requested metafile operation is not supported. | 2003
ERROR_MOD_NOT_FOUND | The specified module could not be found. | 126
ERROR_MORE_DATA | More data is available. | 234
ERROR_MORE_WRITES | A serial I/O operation was completed by another write to the serial port. The IOCTL_SERIAL_XOFF_COUNTER reached zero.) | 1120
ERROR_MR_MID_NOT_FOUND | The system cannot find message text for message number 0x%1 in the message file for %2. | 317
ERROR_NEGATIVE_SEEK | An attempt was made to move the file pointer before the beginning of the file. | 131
ERROR_NESTING_NOT_ALLOWED | Cannot nest calls to LoadModule. | 215
ERROR_NET_WRITE_FAULT | A write fault occurred on the network. | 88
ERROR_NETLOGON_NOT_STARTED | An attempt was made to logon, but the network logon service was not started. | 1792
ERROR_NETNAME_DELETED | The specified network name is no longer available. | 64
ERROR_NETWORK_ACCESS_DENIED | Network access is denied. | 65
ERROR_NETWORK_BUSY | The network is busy. | 54
ERROR_NETWORK_UNREACHABLE | The remote network is not reachable by the transport. | 1231
ERROR_NO_ASSOCIATION | No application is associated with the specified file for this operation. | 1155
ERROR_NO_BROWSER_SERVERS_FOUND | The list of servers for this workgroup is not currently available | 6118
ERROR_NO_DATA | The pipe is being closed. | 232
ERROR_NO_DATA_DETECTED | No more data is on the tape. | 1104
ERROR_NO_IMPERSONATION_TOKEN | An attempt has been made to operate on an impersonation token by a thread that is not currently impersonating a client. | 1309
ERROR_NO_INHERITANCE | Indicates an ACL contains no inheritable components. | 1391
ERROR_NO_LOG_SPACE | System could not allocate the required space in a registry log. | 1019
ERROR_NO_LOGON_SERVERS | There are currently no logon servers available to service the logon request. | 1311
ERROR_NO_MEDIA_IN_DRIVE | No media in drive. | 1112
ERROR_NO_MORE_DEVICES | No more local devices. | 1248
ERROR_NO_MORE_FILES | There are no more files. | 18
ERROR_NO_MORE_ITEMS | No more data is available. | 259
ERROR_NO_MORE_SEARCH_HANDLES | No more internal file identifiers available. | 113
ERROR_NO_NET_OR_BAD_PATH | No network provider accepted the given network path. | 1203
ERROR_NO_NETWORK | The network is not present or not started. | 1222
ERROR_NO_PROC_SLOTS | The system cannot start another process at this time. | 89
ERROR_NO_QUOTAS_FOR_ACCOUNT | No system quota limits are specifically set for this account. | 1302
ERROR_NO_SCROLLBARS | The window does not have scroll bars. | 1447
ERROR_NO_SECURITY_ON_OBJECT | Unable to perform a security operation on an object that has no associated security. | 1350
ERROR_NO_SHUTDOWN_IN_PROGRESS | Unable to abort the system shutdown because no shutdown was in progress. | 1116
ERROR_NO_SIGNAL_SENT | No process in the command subtree has a signal handler. | 205
ERROR_NO_SPOOL_SPACE | Space to store the file waiting to be printed is not available on the server. | 62
ERROR_NO_SUCH_ALIAS | The specified local group does not exist. | 1376
ERROR_NO_SUCH_DOMAIN | The specified domain did not exist. | 1355
ERROR_NO_SUCH_GROUP | The specified group does not exist. | 1319
ERROR_NO_SUCH_LOGON_SESSION | A specified logon session does not exist. It may already have been terminated. | 1312
ERROR_NO_SUCH_MEMBER | A new member could not be added to a local group because the member does not exist. | 1387
ERROR_NO_SUCH_PACKAGE | A specified authentication package is unknown. | 1364
ERROR_NO_SUCH_PRIVILEGE | A specified privilege does not exist. | 1313
ERROR_NO_SUCH_USER | The specified user does not exist. | 1317
ERROR_NO_SYSTEM_MENU | The window does not have a system menu. | 1437
ERROR_NO_SYSTEM_RESOURCES | Insufficient system resources exist to complete the requested service. | 1450
ERROR_NO_TOKEN | An attempt was made to reference a token that does not exist. | 1008
ERROR_NO_TRUST_LSA_SECRET | The workstation does not have a trust secret. | 1786
ERROR_NO_TRUST_SAM_ACCOUNT | The SAM database on the Windows NT Server does not have a computer account for this workstation trust relationship. | 1787
ERROR_NO_UNICODE_TRANSLATION | No mapping for the Unicode character exists in the target multibyte code page. | 1113
ERROR_NO_USER_SESSION_KEY | There is no user session key for the specified logon session. | 1394
ERROR_NO_VOLUME_LABEL | The disk has no volume label. | 125
ERROR_NO_WILDCARD_CHARACTERS | No wildcards were found. | 1417
ERROR_NOACCESS | Invalid access to memory location. | 998
ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT | The account used is an interdomain trust account. Use your global user account or local user account to access this server. | 1807
ERROR_NOLOGON_SERVER_TRUST_ACCOUNT | The account used is a server trust account. Use your global user account or local user account to access this server. | 1809
ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT | The account used is a computer account. Use your global user account or local user account to access this server. | 1808
ERROR_NON_MDICHILD_WINDOW | Cannot process a message from a window that is not a multiple-document interface (MDI) window. | 1445
ERROR_NONE_MAPPED | No mapping between account names and security IDs was done. | 1332
ERROR_NONPAGED_SYSTEM_RESOURCES | Insufficient system resources exist to complete the requested service. | 1451
ERROR_NOT_ALL_ASSIGNED | Not all privileges referenced are assigned to the caller. | 1300
ERROR_NOT_AUTHENTICATED | The operation being requested was not performed because the user has not been authenticated. | 1244
ERROR_NOT_CHILD_WINDOW | The window is not a child window. | 1442
ERROR_NOT_CONNECTED | This network connection does not exist. | 2250
ERROR_NOT_CONTAINER | Cannot enumerate a noncontainer. | 1207
ERROR_NOT_DOS_DISK | The specified disk or diskette cannot be accessed. | 26
ERROR_NOT_ENOUGH_MEMORY | Not enough storage is available to process this command. | 8
ERROR_NOT_ENOUGH_QUOTA | Not enough quota is available to process this command. | 1816
ERROR_NOT_ENOUGH_SERVER_MEMORY | Not enough server storage is available to process this command. | 1130
ERROR_NOT_JOINED | The system tried to delete the JOIN of a drive that is not joined. | 136
ERROR_NOT_LOCKED | The segment is already unlocked. | 158
ERROR_NOT_LOGGED_ON | The operation being requested was not performed because the user has not logged on to the network. The specified service does not exist. | 1245
ERROR_NOT_LOGON_PROCESS | The requested action is restricted for use by logon processes only. The calling process has not registered as a logon process. | 1362
ERROR_NOT_OWNER | Attempt to release mutex not owned by caller. | 288
ERROR_NOT_READY | The device is not ready. | 21
ERROR_NOT_REGISTRY_FILE | The system has attempted to load or restore a file into the registry, but the specified file is not in a registry file format. | 1017
ERROR_NOT_SAME_DEVICE | The system cannot move the file to a different disk drive. | 17
ERROR_NOT_SUBSTED | The system tried to delete the substitution of a drive that is not substituted. | 137
ERROR_NOT_SUPPORTED | The network request is not supported. | 50
ERROR_NOTIFY_ENUM_DIR | A notify change request is being completed and the information is not being returned in the caller's buffer. The caller now needs to enumerate the files to find the changes. | 1022
ERROR_NT_CROSS_ENCRYPTION_REQUIRED | A cross-encrypted password is necessary to change a user password. | 1386
ERROR_NULL_LM_PASSWORD | The password is too complex to be converted to a LAN Manager password. The LAN Manager password returned is a null string. | 1304
ERROR_OLD_WIN_VERSION | The specified program requires a newer version of Windows. | 1150
ERROR_OPEN_FAILED | The system cannot open the device or file specified. | 110
ERROR_OPEN_FILES | This network connection has files open or requests pending. | 2401
ERROR_OPERATION_ABORTED | The I/O operation has been aborted because of either a thread exit or an application request. | 995
ERROR_OUT_OF_PAPER | The printer is out of paper. | 28
ERROR_OUT_OF_STRUCTURES | Storage to process this request is not available. | 84
ERROR_OUTOFMEMORY | Not enough storage is available to complete this operation. | 14
ERROR_PAGED_SYSTEM_RESOURCES | Insufficient system resources exist to complete the requested service. | 1452
ERROR_PAGEFILE_QUOTA | Insufficient quota to complete the requested service. | 1454
ERROR_PARTIAL_COPY | Only part of a ReadProcessMemory or WriteProcessMemory request was completed. | 299
ERROR_PARTITION_FAILURE | Tape could not be partitioned. | 1105
ERROR_PASSWORD_EXPIRED | Logon failure—the specified account password has expired. | 1330
ERROR_PASSWORD_MUST_CHANGE | The user must change his password before he logs on the first time. | 1907
ERROR_PASSWORD_RESTRICTION | Unable to update the password because a password update rule has been violated. | 1325
ERROR_PATH_BUSY | The path specified cannot be used at this time. | 148
ERROR_PATH_NOT_FOUND | The system cannot find the path specified. | 3
ERROR_PIPE_BUSY | All pipe instances are busy. | 231
ERROR_PIPE_CONNECTED | There is a process on other end of the pipe. | 535
ERROR_PIPE_LISTENING | Waiting for a process to open the other end of the pipe. | 536
ERROR_PIPE_NOT_CONNECTED | No process is on the other end of the pipe. | 233
ERROR_POPUP_ALREADY_ACTIVE | Pop-up menu already active. | 1446
ERROR_PORT_UNREACHABLE | No service is operating at the destination network endpoint on the remote system. | 1234
ERROR_POSSIBLE_DEADLOCK | A potential deadlock condition has been detected. | 1131
ERROR_PRINT_CANCELLED | Your file waiting to be printed was deleted. | 63
ERROR_PRINT_MONITOR_ALREADY_INSTALLED | The specified print monitor has already been installed. | 3006
ERROR_PRINT_MONITOR_IN_USE | The specified print monitor is currently in use. | 3008
ERROR_PRINT_PROCESSOR_ALREADY_INSTALLED | The specified print processor has already been installed. | 3005
ERROR_PRINTER_ALREADY_EXISTS | The printer already exists. | 1802
ERROR_PRINTER_DELETED | The specified printer has been deleted. | 1905
ERROR_PRINTER_DRIVER_ALREADY_INSTALLED | The specified printer driver is already installed. | 1795
ERROR_PRINTER_DRIVER_IN_USE | The specified printer driver is currently in use. | 3001
ERROR_PRINTER_HAS_JOBS_QUEUED | The requested operation is not allowed when there are jobs queued to the printer. | 3009
ERROR_PRINTQ_FULL | The printer queue is full. | 61
ERROR_PRIVATE_DIALOG_INDEX | Using private DIALOG window words. | 1415
ERROR_PRIVILEGE_NOT_HELD | A required privilege is not held by the client. | 1314
ERROR_PROC_NOT_FOUND | The specified procedure could not be found. | 127
ERROR_PROCESS_ABORTED | The process terminated unexpectedly. | 1067
ERROR_PROTOCOL_UNREACHABLE | The remote system does not support the transport protocol. | 1233
ERROR_READ_FAULT | The system cannot read from the specified device. | 30
ERROR_REC_NON_EXISTENT | The name does not exist in the WINS database. | 4005
ERROR_REDIR_PAUSED | The specified printer or disk device has been paused. | 72
ERROR_REDIRECTOR_HAS_OPEN_HANDLES | The redirector is in use and cannot be unloaded. | 1794
ERROR_REGISTRY_CORRUPT | The registry is corrupted. The structure of one of the files that contains registry data is corrupted, or the system's image of the file in memory is corrupted, or the file could not be recovered because the alternate copy or log was absent or corrupted. | 1015
ERROR_REGISTRY_IO_FAILED | An I/O operation initiated by the registry failed unrecoverably. The registry could not read in, or write out, or flush, one of the files that contain the system's image of the registry. | 1016
ERROR_REGISTRY_RECOVERED | One of the files in the registry database had to be recovered by use of a log or alternate copy. The recovery was successful. | 1014
ERROR_RELOC_CHAIN_XEEDS_SEGLIM | The operating system cannot run %1. | 201
ERROR_REM_NOT_LIST | The remote computer is not available. | 51
ERROR_REMOTE_SESSION_LIMIT_EXCEEDED | An attempt was made to establish a session to a network server, but there are already too many sessions established to that server. | 1220
ERROR_REQ_NOT_ACCEP | No more connections can be made to this remote computer at this time because there are already as many connections as the computer can accept. | 71
ERROR_REQUEST_ABORTED | The request was aborted. | 1235
ERROR_REQUIRES_INTERACTIVE_WINDOWSTATION | This operation requires an interactive window station. | 1459
ERROR_RESOURCE_DATA_NOT_FOUND | The specified image file did not contain a resource section. | 1812
ERROR_RESOURCE_LANG_NOT_FOUND | The specified resource language identifier cannot be found in the image file. | 1815
ERROR_RESOURCE_NAME_NOT_FOUND | The specified resource name cannot be found in the image file. | 1814
ERROR_RESOURCE_TYPE_NOT_FOUND | The specified resource type cannot be found in the image file. | 1813
ERROR_RETRY | The operation could not be completed. A retry should be performed. | 1237
ERROR_REVISION_MISMATCH | Indicates two revision levels are incompatible. | 1306
ERROR_RING2_STACK_IN_USE | The ring 2 stack is in use. | 207
ERROR_RING2SEG_MUST_BE_MOVABLE | The code segment cannot be greater than or equal to 64 KB. | 200
ERROR_RMODE_APP | The specified program was written for an earlier version of Windows. | 1153
ERROR_RPL_NOT_ALLOWED | Replication with a nonconfigured partner is not allowed. | 4006
ERROR_RXACT_COMMIT_FAILURE | An internal security database corruption has been encountered. | 1370
ERROR_RXACT_INVALID_STATE | The transaction state of a registry subtree is incompatible with the requested operation. | 1369
ERROR_SAME_DRIVE | The system cannot join or substitute a drive to or for a directory on the same drive. | 143
ERROR_SCREEN_ALREADY_LOCKED | Screen already locked. | 1440
ERROR_SECRET_TOO_LONG | The length of a secret exceeds the maximum length allowed. | 1382
ERROR_SECTOR_NOT_FOUND | The drive cannot find the sector requested. | 27
ERROR_SEEK | The drive cannot locate a specific area or track on the disk. | 25
ERROR_SEEK_ON_DEVICE | The file pointer cannot be set on the specified device or file. | 132
ERROR_SEM_IS_SET | The semaphore is set and cannot be closed. | 102
ERROR_SEM_NOT_FOUND | The specified system semaphore name was not found. | 187
ERROR_SEM_OWNER_DIED | The previous ownership of this semaphore has ended. | 105
ERROR_SEM_TIMEOUT | The semaphore time-out period has expired. | 121
ERROR_SEM_USER_LIMIT | Insert the diskette for drive %1. | 106
ERROR_SERIAL_NO_DEVICE | No serial device was successfully initialized. The serial driver will unload. | 1118
ERROR_SERVER_DISABLED | The server is currently disabled. | 1341
ERROR_SERVER_HAS_OPEN_HANDLES | The server is in use and cannot be unloaded. | 1811
ERROR_SERVER_NOT_DISABLED | The server is currently enabled. | 1342
ERROR_SERVICE_ALREADY_RUNNING | An instance of the service is already running. | 1056
ERROR_SERVICE_CANNOT_ACCEPT_CTRL | The service cannot accept control messages at this time. | 1061
ERROR_SERVICE_DATABASE_LOCKED | The service database is locked. | 1055
ERROR_SERVICE_DEPENDENCY_DELETED | The dependency service does not exist or has been marked for deletion. | 1075
ERROR_SERVICE_DEPENDENCY_FAIL | The dependency service or group failed to start. | 1068
ERROR_SERVICE_DISABLED | The specified service is disabled and cannot be started. | 1058
ERROR_SERVICE_DOES_NOT_EXIST | The specified service does not exist as an installed service. | 1060
ERROR_SERVICE_EXISTS | The specified service already exists. | 1073
ERROR_SERVICE_LOGON_FAILED | The service did not start due to a logon failure. | 1069
ERROR_SERVICE_MARKED_FOR_DELETE | The specified service has been marked for deletion. | 1072
ERROR_SERVICE_NEVER_STARTED | No attempts to start the service have been made since the last boot. | 1077
ERROR_SERVICE_NO_THREAD | A thread could not be created for the service. | 1054
ERROR_SERVICE_NOT_ACTIVE | The service has not been started. | 1062
ERROR_SERVICE_NOT_FOUND | The specified service does not exist. | 1243
ERROR_SERVICE_REQUEST_TIMEOUT | The service did not respond to the start or control request in a timely fashion. | 1053
ERROR_SERVICE_SPECIFIC_ERROR | The service has returned a service-specific error code. | 1066
ERROR_SERVICE_START_HANG | After starting, the service hung in a start-pending state. | 1070
ERROR_SESSION_CREDENTIAL_CONFLICT | The credentials supplied conflict with an existing set of credentials. | 1219
ERROR_SET_POWER_STATE_FAILED | The basic input/output system (BIOS) failed an attempt to change the system power state. | 1141
ERROR_SET_POWER_STATE_VETOED | An attempt to change the system power state was vetoed by another application or driver. | 1140
ERROR_SETMARK_DETECTED | A tape access reached the end of a set of files. | 1103
ERROR_SHARING_BUFFER_EXCEEDED | Too many files opened for sharing. | 36
ERROR_SHARING_PAUSED | The remote server has been paused or is in the process of being started. | 70
ERROR_SHARING_VIOLATION | The process cannot access the file because it is being used by another process. | 32
ERROR_SHUTDOWN_IN_PROGRESS | A system shutdown is in progress. | 1115
ERROR_SIGNAL_PENDING | A signal is already pending. | 162
ERROR_SIGNAL_REFUSED | The recipient process has refused the signal. | 156
ERROR_SINGLE_INSTANCE_APP | Cannot start more than one instance of the specified program. | 1152
ERROR_SOME_NOT_MAPPED | Some mapping between account names and security IDs was not done. | 1301
ERROR_SPECIAL_ACCOUNT | Cannot perform this operation on built-in accounts. | 1371
ERROR_SPECIAL_GROUP | Cannot perform this operation on this built-in special group. | 1372
ERROR_SPECIAL_USER | Cannot perform this operation on this built-in special user. | 1373
ERROR_SPL_NO_ADDJOB | An AddJob call was not issued. | 3004
ERROR_SPL_NO_STARTDOC | A StartDocPrinter call was not issued. | 3003
ERROR_SPOOL_FILE_NOT_FOUND | The spool file was not found. | 3002
ERROR_STACK_OVERFLOW | Recursion too deep; the stack overflowed. | 1001
ERROR_STATIC_INIT | The importation from the file failed. | 4002
ERROR_SUBST_TO_JOIN | The system tried to SUBST a drive to a directory on a joined drive. | 141
ERROR_SUBST_TO_SUBST | The system tried to substitute a drive to a directory on a substituted drive. | 139
ERROR_SUCCESS | The operation completed successfully. | 0
ERROR_SUCCESS_REBOOT_REQUIRED | The requested operation is successful. Changes will not be effective until the system is rebooted. | 3010
ERROR_SUCCESS_RESTART_REQUIRED | The requested operation is successful. Changes will not be effective until the service is restarted. | 3011
ERROR_SWAPERROR | Error performing inpage operation. | 999
ERROR_SYSTEM_TRACE | System trace information was not specified in your Config.sys file, or tracing is disallowed. | 150
ERROR_THREAD_1_INACTIVE | The signal handler cannot be set. | 210
ERROR_TIMEOUT | This operation returned because the time-out period expired. | 1460
ERROR_TLW_WITH_WSCHILD | Cannot create a top-level child window. | 1406
ERROR_TOKEN_ALREADY_IN_USE | The token is already in use as a primary token. | 1375
ERROR_TOO_MANY_CMDS | The network BIOS command limit has been reached. | 56
ERROR_TOO_MANY_CONTEXT_IDS | During a logon attempt, the user's security context accumulated too many security IDs. | 1384
ERROR_TOO_MANY_LINKS | An attempt was made to create more links on a file than the file system supports. | 1142
ERROR_TOO_MANY_LUIDS_REQUESTED | Too many LUIDs were requested at one time. | 1333
ERROR_TOO_MANY_MODULES | Too many dynamic-link modules are attached to this program or dynamic-link module. | 214
ERROR_TOO_MANY_MUXWAITERS | DosMuxSemWait did not execute; too many semaphores are already set. | 152
ERROR_TOO_MANY_NAMES | The name limit for the local computer network adapter card was exceeded. | 68
ERROR_TOO_MANY_OPEN_FILES | The system cannot open the file. | 4
ERROR_TOO_MANY_POSTS | Too many posts were made to a semaphore. | 298
ERROR_TOO_MANY_SECRETS | The maximum number of secrets that may be stored in a single system has been exceeded. | 1381
ERROR_TOO_MANY_SEM_REQUESTS | The semaphore cannot be set again. | 103
ERROR_TOO_MANY_SEMAPHORES | Cannot create another system semaphore. | 100
ERROR_TOO_MANY_SESS | The network BIOS session limit was exceeded. | 69
ERROR_TOO_MANY_SIDS | Too many security IDs have been specified. | 1389
ERROR_TOO_MANY_TCBS | Cannot create another thread. | 155
ERROR_TRANSFORM_NOT_SUPPORTED | The requested transformation operation is not supported. | 2004
ERROR_TRUST_FAILURE | The network logon failed. | 1790
ERROR_TRUSTED_DOMAIN_FAILURE | The trust relationship between the primary domain and the trusted domain failed. | 1788
ERROR_TRUSTED_RELATIONSHIP_FAILURE | The trust relationship between this workstation and the primary domain failed. | 1789
ERROR_UNABLE_TO_LOCK_MEDIA | Unable to lock the media eject mechanism. | 1108
ERROR_UNABLE_TO_UNLOAD_MEDIA | Unable to unload the media. | 1109
ERROR_UNEXP_NET_ERR | An unexpected network error occurred. | 59
ERROR_UNKNOWN_PORT | The specified port is unknown. | 1796
ERROR_UNKNOWN_PRINT_MONITOR | The specified print monitor is unknown. | 3000
ERROR_UNKNOWN_PRINTER_DRIVER | The printer driver is unknown. | 1797
ERROR_UNKNOWN_PRINTPROCESSOR | The print processor is unknown. | 1798
ERROR_UNKNOWN_REVISION | The revision level is unknown. | 1305
ERROR_UNRECOGNIZED_MEDIA | The disk media is not recognized. It may not be formatted. | 1785
ERROR_UNRECOGNIZED_VOLUME | The volume does not contain a recognized file system. Verify that all required file system drivers are loaded and that the volume is not corrupted. | 1005
ERROR_USER_EXISTS | The specified user already exists. | 1316
ERROR_USER_MAPPED_FILE | The requested operation cannot be performed on a file with a user-mapped section open. | 1224
ERROR_VC_DISCONNECTED | The session was canceled. | 240
ERROR_WAIT_NO_CHILDREN | There are no child processes to wait for. | 128
ERROR_WINDOW_NOT_COMBOBOX | The window is not a combo box. | 1423
ERROR_WINDOW_NOT_DIALOG | The window is not a valid dialog window. | 1420
ERROR_WINDOW_OF_OTHER_THREAD | Invalid window; it belongs to another thread. | 1408
ERROR_WINS_INTERNAL | WINS encountered an error while processing the command. | 4000
ERROR_WORKING_SET_QUOTA | Insufficient quota to complete the requested service. | 1453
ERROR_WRITE_FAULT | The system cannot write to the specified device. | 29
ERROR_WRITE_PROTECT | The media is write protected. | 19
ERROR_WRONG_DISK | The wrong diskette is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1. | 34
ERROR_WRONG_PASSWORD | Unable to update the password. The value provided as the current password is incorrect. | 1323
OR_INVALID_OID | The object specified was not found. | 1911
OR_INVALID_OXID | The object exporter specified was not found. | 1910
OR_INVALID_SET | The object resolver set specified was not found. | 1912
RPC_S_ADDRESS_ERROR | An addressing error occurred in the RPC server. | 1768
RPC_S_ALREADY_LISTENING | The remote procedure call (RPC) server is already listening. | 1713
RPC_S_ALREADY_REGISTERED | The object universally unique identifier (UUID) has already been registered. | 1711
RPC_S_BINDING_HAS_NO_AUTH | The binding does not contain any authentication information. | 1746
RPC_S_BINDING_INCOMPLETE | The binding handle does not contain all required information. | 1819
RPC_S_CALL_CANCELLED | The server was altered while processing this call. | 1818
RPC_S_CALL_FAILED | The remote procedure call failed. | 1726
RPC_S_CALL_FAILED_DNE | The remote procedure call failed and did not execute. | 1727
RPC_S_CALL_IN_PROGRESS | A remote procedure call is already in progress for this thread. | 1791
RPC_S_CANNOT_SUPPORT | The requested operation is not supported. | 1764
RPC_S_CANT_CREATE_ENDPOINT | The endpoint cannot be created. | 1720
RPC_S_COMM_FAILURE | Communications failure. | 1820
RPC_S_DUPLICATE_ENDPOINT | The endpoint is a duplicate. | 1740
RPC_S_ENTRY_ALREADY_EXISTS | The entry already exists. | 1760
RPC_S_ENTRY_NOT_FOUND | The entry is not found. | 1761
RPC_S_FP_DIV_ZERO | A floating-point operation at the RPC server caused a division by zero. | 1769
RPC_S_FP_OVERFLOW | A floating-point overflow occurred at the RPC server. | 1771
RPC_S_FP_UNDERFLOW | A floating-point underflow occurred at the RPC server. | 1770
RPC_S_GROUP_MEMBER_NOT_FOUND | The group member was not found. | 1898
RPC_S_INCOMPLETE_NAME | The entry name is incomplete. | 1755
RPC_S_INTERFACE_NOT_FOUND | The interface was not found. | 1759
RPC_S_INTERNAL_ERROR | An internal error occurred in a remote procedure call (RPC). | 1766
RPC_S_INVALID_AUTH_IDENTITY | The security context is invalid. | 1749
RPC_S_INVALID_BINDING | The binding handle is invalid. | 1702
RPC_S_INVALID_BOUND | The array bounds are invalid. | 1734
RPC_S_INVALID_ENDPOINT_FORMAT | The endpoint format is invalid. | 1706
RPC_S_INVALID_NAF_ID | The network address family is invalid. | 1763
RPC_S_INVALID_NAME_SYNTAX | The name syntax is invalid. | 1736
RPC_S_INVALID_NET_ADDR | The network address is invalid. | 1707
RPC_S_INVALID_NETWORK_OPTIONS | The network options are invalid. | 1724
RPC_S_INVALID_OBJECT | The object UUID is the nil UUID. | 1900
RPC_S_INVALID_RPC_PROTSEQ | The RPC protocol sequence is invalid. | 1704
RPC_S_INVALID_STRING_BINDING | The string binding is invalid. | 1700
RPC_S_INVALID_STRING_UUID | The string universal unique identifier (UUID) is invalid. | 1705
RPC_S_INVALID_TAG | The tag is invalid. | 1733
RPC_S_INVALID_TIMEOUT | The time-out value is invalid. | 1709
RPC_S_INVALID_VERS_OPTION | The version option is invalid. | 1756
RPC_S_MAX_CALLS_TOO_SMALL | The maximum number of calls is too small. | 1742
RPC_S_NAME_SERVICE_UNAVAILABLE | The name service is unavailable. | 1762
RPC_S_NO_BINDINGS | There are no bindings. | 1718
RPC_S_NO_CALL_ACTIVE | There is not a remote procedure call active in this thread. | 1725
RPC_S_NO_CONTEXT_AVAILABLE | No security context is available to allow impersonation. | 1765
RPC_S_NO_ENDPOINT_FOUND | No endpoint was found. | 1708
RPC_S_NO_ENTRY_NAME | The binding does not contain an entry name. | 1735
RPC_S_NO_INTERFACES | No interfaces have been registered. | 1817
RPC_S_NO_MORE_BINDINGS | There are no more bindings. | 1806
RPC_S_NO_MORE_MEMBERS | There are no more members. | 1757
RPC_S_NO_PRINC_NAME | No principal name registered. | 1822
RPC_S_NO_PROTSEQS | There are no protocol sequences. | 1719
RPC_S_NO_PROTSEQS_REGISTERED | No protocol sequences have been registered. | 1714
RPC_S_NOT_ALL_OBJS_UNEXPORTED | There is nothing to unexport. | 1758
RPC_S_NOT_CANCELLED | Thread is not canceled. | 1826
RPC_S_NOT_LISTENING | The RPC server is not listening. | 1715
RPC_S_NOT_RPC_ERROR | The error specified is not a valid Windows NT RPC error value. | 1823
RPC_S_NOTHING_TO_EXPORT | No interfaces have been exported. | 1754
RPC_S_OBJECT_NOT_FOUND | The object universal unique identifier (UUID) was not found. | 1710
RPC_S_OUT_OF_RESOURCES | Not enough resources are available to complete this operation. | 1721
RPC_S_PROCNUM_OUT_OF_RANGE | The procedure number is out of range. | 1745
RPC_S_PROTOCOL_ERROR | A remote procedure call (RPC) protocol error occurred. | 1728
RPC_S_PROTSEQ_NOT_FOUND | The RPC protocol sequence was not found. | 1744
RPC_S_PROTSEQ_NOT_SUPPORTED | The RPC protocol sequence is not supported. | 1703
RPC_S_SEC_PKG_ERROR | A security package specific error occurred. | 1825
RPC_S_SEND_INCOMPLETE | Some data remains to be sent in the request buffer. | 1913
RPC_S_SERVER_TOO_BUSY | The RPC server is too busy to complete this operation. | 1723
RPC_S_SERVER_UNAVAILABLE | The RPC server is unavailable. | 1722
RPC_S_STRING_TOO_LONG | The string is too long. | 1743
RPC_S_TYPE_ALREADY_REGISTERED | The type universal unique identifier (UUID) has already been registered. | 1712
RPC_S_UNKNOWN_AUTHN_LEVEL | The authentication level is unknown. | 1748
RPC_S_UNKNOWN_AUTHN_SERVICE | The authentication service is unknown. | 1747
RPC_S_UNKNOWN_AUTHN_TYPE | The authentication type is unknown. | 1741
RPC_S_UNKNOWN_AUTHZ_SERVICE | The authorization service is unknown. | 1750
RPC_S_UNKNOWN_IF | The interface is unknown. | 1717
RPC_S_UNKNOWN_MGR_TYPE | The manager type is unknown. | 1716
RPC_S_UNSUPPORTED_AUTHN_LEVEL | The requested authentication level is not supported. | 1821
RPC_S_UNSUPPORTED_NAME_SYNTAX | The name syntax is not supported. | 1737
RPC_S_UNSUPPORTED_TRANS_SYN | The transfer syntax is not supported by the RPC server. | 1730
RPC_S_UNSUPPORTED_TYPE | The universal unique identifier (UUID) type is not supported. | 1732
RPC_S_UUID_LOCAL_ONLY | A UUID that is valid only on this computer has been allocated. | 1824
RPC_S_UUID_NO_ADDRESS | No network address is available to use to construct a universal unique identifier (UUID). | 1739
RPC_S_WRONG_KIND_OF_BINDING | The binding handle is not the correct type. | 1701
RPC_S_ZERO_DIVIDE | The RPC server attempted an integer division by zero. | 1767
RPC_X_BAD_STUB_DATA | The stub received bad data. | 1783
RPC_X_BYTE_COUNT_TOO_SMALL | The byte count is too small. | 1782
RPC_X_ENUM_VALUE_OUT_OF_RANGE | The enumeration value is out of range. | 1781
RPC_X_INVALID_ES_ACTION | Invalid operation on the encoding/decoding handle. | 1827
RPC_X_INVALID_PIPE_OBJECT | The idl pipe object is invalid or corrupted. | 1830
RPC_X_INVALID_PIPE_OPERATION | The operation is invalid for a given idl pipe object. | 1831
RPC_X_NO_MORE_ENTRIES | The list of RPC servers available for the binding of auto handles has been exhausted. | 1772
RPC_X_NULL_REF_POINTER | A null reference pointer was passed to the stub. | 1780
RPC_X_SS_CANNOT_GET_CALL_HANDLE | The stub is unable to get the remote procedure call handle. | 1779
RPC_X_SS_CHAR_TRANS_OPEN_FAIL | Unable to open the character translation table file. | 1773
RPC_X_SS_CHAR_TRANS_SHORT_FILE | The file containing the character translation table has fewer than 512 bytes. | 1774
RPC_X_SS_CONTEXT_DAMAGED | The context handle changed during a remote procedure call. | 1777
RPC_X_SS_HANDLES_MISMATCH | The binding handles passed to a remote procedure call do not match. | 1778
RPC_X_SS_IN_NULL_CONTEXT | A null context handle was passed from the client to the host during a remote procedure call. | 1775
RPC_X_WRONG_ES_VERSION | Incompatible version of the serializing package. | 1828
RPC_X_WRONG_PIPE_VERSION | The IDL pipe version is not supported. | 1832
RPC_X_WRONG_STUB_VERSION | Incompatible version of the RPC stub. | 1829


System Errors - Numerical Order

The following table shows possible system error values.

Code
Description
Name
0 | The operation completed successfully. | ERROR_SUCCESS
1 | Incorrect function. | ERROR_INVALID_FUNCTION
2 | The system cannot find the file specified. | ERROR_FILE_NOT_FOUND
3 | The system cannot find the path specified. | ERROR_PATH_NOT_FOUND
4 | The system cannot open the file. | ERROR_TOO_MANY_OPEN_FILES
5 | Access is denied. | ERROR_ACCESS_DENIED
6 | The handle is invalid. | ERROR_INVALID_HANDLE
7 | The storage control blocks were destroyed. | ERROR_ARENA_TRASHED
8 | Not enough storage is available to process this command. | ERROR_NOT_ENOUGH_MEMORY
9 | The storage control block address is invalid. | ERROR_INVALID_BLOCK
10 | The environment is incorrect. | ERROR_BAD_ENVIRONMENT
11 | An attempt was made to load a program with an incorrect format. | ERROR_BAD_FORMAT
12 | The access code is invalid. | ERROR_INVALID_ACCESS
13 | The data is invalid. | ERROR_INVALID_DATA
14 | Not enough storage is available to complete this operation. | ERROR_OUTOFMEMORY
15 | The system cannot find the drive specified. | ERROR_INVALID_DRIVE
16 | The directory cannot be removed. | ERROR_CURRENT_DIRECTORY
17 | The system cannot move the file to a different disk drive. | ERROR_NOT_SAME_DEVICE
18 | There are no more files. | ERROR_NO_MORE_FILES
19 | The media is write protected. | ERROR_WRITE_PROTECT
20 | The system cannot find the specified device. | ERROR_BAD_UNIT
21 | The device is not ready. | ERROR_NOT_READY
22 | The device does not recognize the command. | ERROR_BAD_COMMAND
23 | Data error (cyclic redundancy check). | ERROR_CRC
24 | The program issued a command but the command length is incorrect. | ERROR_BAD_LENGTH
25 | The drive cannot locate a specific area or track on the disk. | ERROR_SEEK
26 | The specified disk or diskette cannot be accessed. | ERROR_NOT_DOS_DISK
27 | The drive cannot find the sector requested. | ERROR_SECTOR_NOT_FOUND
28 | The printer is out of paper. | ERROR_OUT_OF_PAPER
29 | The system cannot write to the specified device. | ERROR_WRITE_FAULT
30 | The system cannot read from the specified device. | ERROR_READ_FAULT
31 | A device attached to the system is not functioning. | ERROR_GEN_FAILURE
32 | The process cannot access the file because it is being used by another process. | ERROR_SHARING_VIOLATION
33 | The process cannot access the file because another process has locked a portion of the file. | ERROR_LOCK_VIOLATION
34 | The wrong diskette is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1. | ERROR_WRONG_DISK
36 | Too many files opened for sharing. | ERROR_SHARING_BUFFER_EXCEEDED
38 | Reached the end of the file. | ERROR_HANDLE_EOF
39 | The disk is full. | ERROR_HANDLE_DISK_FULL
50 | The network request is not supported. | ERROR_NOT_SUPPORTED
51 | The remote computer is not available. | ERROR_REM_NOT_LIST
52 | A duplicate name exists on the network. | ERROR_DUP_NAME
53 | The network path was not found. | ERROR_BAD_NETPATH
54 | The network is busy. | ERROR_NETWORK_BUSY
55 | The specified network resource or device is no longer available. | ERROR_DEV_NOT_EXIST
56 | The network BIOS command limit has been reached. | ERROR_TOO_MANY_CMDS
57 | A network adapter hardware error occurred. | ERROR_ADAP_HDW_ERR
58 | The specified server cannot perform the requested operation. | ERROR_BAD_NET_RESP
59 | An unexpected network error occurred. | ERROR_UNEXP_NET_ERR
60 | The remote adapter is not compatible. | ERROR_BAD_REM_ADAP
61 | The printer queue is full. | ERROR_PRINTQ_FULL
62 | Space to store the file waiting to be printed is not available on the server. | ERROR_NO_SPOOL_SPACE
63 | Your file waiting to be printed was deleted. | ERROR_PRINT_CANCELLED
64 | The specified network name is no longer available. | ERROR_NETNAME_DELETED
65 | Network access is denied. | ERROR_NETWORK_ACCESS_DENIED
66 | The network resource type is not correct. | ERROR_BAD_DEV_TYPE
67 | The network name cannot be found. | ERROR_BAD_NET_NAME
68 | The name limit for the local computer network adapter card was exceeded. | ERROR_TOO_MANY_NAMES
69 | The network BIOS session limit was exceeded. | ERROR_TOO_MANY_SESS
70 | The remote server has been paused or is in the process of being started. | ERROR_SHARING_PAUSED
71 | No more connections can be made to this remote computer at this time because there are already as many connections as the computer can accept. | ERROR_REQ_NOT_ACCEP
72 | The specified printer or disk device has been paused. | ERROR_REDIR_PAUSED
80 | The file exists. | ERROR_FILE_EXISTS
82 | The directory or file cannot be created. | ERROR_CANNOT_MAKE
83 | Fail on INT 24. | ERROR_FAIL_I24
84 | Storage to process this request is not available. | ERROR_OUT_OF_STRUCTURES
85 | The local device name is already in use. | ERROR_ALREADY_ASSIGNED
86 | The specified network password is not correct. | ERROR_INVALID_PASSWORD
87 | The parameter is incorrect. | ERROR_INVALID_PARAMETER
88 | A write fault occurred on the network. | ERROR_NET_WRITE_FAULT
89 | The system cannot start another process at this time. | ERROR_NO_PROC_SLOTS
100 | Cannot create another system semaphore. | ERROR_TOO_MANY_SEMAPHORES
101 | The exclusive semaphore is owned by another process. | ERROR_EXCL_SEM_ALREADY_OWNED
102 | The semaphore is set and cannot be closed. | ERROR_SEM_IS_SET
103 | The semaphore cannot be set again. | ERROR_TOO_MANY_SEM_REQUESTS
104 | Cannot request exclusive semaphores at interrupt time. | ERROR_INVALID_AT_INTERRUPT_TIME
105 | The previous ownership of this semaphore has ended. | ERROR_SEM_OWNER_DIED
106 | Insert the diskette for drive %1. | ERROR_SEM_USER_LIMIT
107 | The program stopped because an alternate diskette was not inserted. | ERROR_DISK_CHANGE
108 | The disk is in use or locked by another process. | ERROR_DRIVE_LOCKED
109 | The pipe has been ended. | ERROR_BROKEN_PIPE
110 | The system cannot open the device or file specified. | ERROR_OPEN_FAILED
111 | The file name is too long. | ERROR_BUFFER_OVERFLOW
112 | There is not enough space on the disk. | ERROR_DISK_FULL
113 | No more internal file identifiers available. | ERROR_NO_MORE_SEARCH_HANDLES
114 | The target internal file identifier is incorrect. | ERROR_INVALID_TARGET_HANDLE
117 | The IOCTL call made by the application program is not correct. | ERROR_INVALID_CATEGORY
118 | The verify-on-write switch parameter value is not correct. | ERROR_INVALID_VERIFY_SWITCH
119 | The system does not support the command requested. | ERROR_BAD_DRIVER_LEVEL
120 | This function is not valid on this platform. | ERROR_CALL_NOT_IMPLEMENTED
121 | The semaphore time-out period has expired. | ERROR_SEM_TIMEOUT
122 | The data area passed to a system call is too small. | ERROR_INSUFFICIENT_BUFFER
123 | The file name, directory name, or volume label syntax is incorrect. | ERROR_INVALID_NAME
124 | The system call level is not correct. | ERROR_INVALID_LEVEL
125 | The disk has no volume label. | ERROR_NO_VOLUME_LABEL
126 | The specified module could not be found. | ERROR_MOD_NOT_FOUND
127 | The specified procedure could not be found. | ERROR_PROC_NOT_FOUND
128 | There are no child processes to wait for. | ERROR_WAIT_NO_CHILDREN
129 | The %1 application cannot be run in Windows NT mode. | ERROR_CHILD_NOT_COMPLETE
130 | Attempt to use a file handle to an open disk partition for an operation other than raw disk I/O. | ERROR_DIRECT_ACCESS_HANDLE
131 | An attempt was made to move the file pointer before the beginning of the file. | ERROR_NEGATIVE_SEEK
132 | The file pointer cannot be set on the specified device or file. | ERROR_SEEK_ON_DEVICE
133 | A JOIN or SUBST command cannot be used for a drive that contains previously joined drives. | ERROR_IS_JOIN_TARGET
134 | An attempt was made to use a JOIN or SUBST command on a drive that has already been joined. | ERROR_IS_JOINED
135 | An attempt was made to use a JOIN or SUBST command on a drive that has already been substituted. | ERROR_IS_SUBSTED
136 | The system tried to delete the JOIN of a drive that is not joined. | ERROR_NOT_JOINED
137 | The system tried to delete the substitution of a drive that is not substituted. | ERROR_NOT_SUBSTED
138 | The system tried to join a drive to a directory on a joined drive. | ERROR_JOIN_TO_JOIN
139 | The system tried to substitute a drive to a directory on a substituted drive. | ERROR_SUBST_TO_SUBST
140 | The system tried to join a drive to a directory on a substituted drive. | ERROR_JOIN_TO_SUBST
141 | The system tried to SUBST a drive to a directory on a joined drive. | ERROR_SUBST_TO_JOIN
142 | The system cannot perform a JOIN or SUBST at this time. | ERROR_BUSY_DRIVE
143 | The system cannot join or substitute a drive to or for a directory on the same drive. | ERROR_SAME_DRIVE
144 | The directory is not a subdirectory of the root directory. | ERROR_DIR_NOT_ROOT
145 | The directory is not empty. | ERROR_DIR_NOT_EMPTY
146 | The path specified is being used in a substitute. | ERROR_IS_SUBST_PATH
147 | Not enough resources are available to process this command. | ERROR_IS_JOIN_PATH
148 | The path specified cannot be used at this time. | ERROR_PATH_BUSY
149 | An attempt was made to join or substitute a drive for which a directory on the drive is the target of a previous substitute. | ERROR_IS_SUBST_TARGET
150 | System trace information was not specified in your Config.sys file, or tracing is disallowed. | ERROR_SYSTEM_TRACE
151 | The number of specified semaphore events for DosMuxSemWait is not correct. | ERROR_INVALID_EVENT_COUNT
152 | DosMuxSemWait did not execute; too many semaphores are already set. | ERROR_TOO_MANY_MUXWAITERS
153 | The DosMuxSemWait list is not correct. | ERROR_INVALID_LIST_FORMAT
154 | The volume label you entered exceeds the label character limit of the target file system. | ERROR_LABEL_TOO_LONG
155 | Cannot create another thread. | ERROR_TOO_MANY_TCBS
156 | The recipient process has refused the signal. | ERROR_SIGNAL_REFUSED
157 | The segment is already discarded and cannot be locked. | ERROR_DISCARDED
158 | The segment is already unlocked. | ERROR_NOT_LOCKED
159 | The address for the thread identifier is not correct. | ERROR_BAD_THREADID_ADDR
160 | The argument string passed to DosExecPgm is not correct. | ERROR_BAD_ARGUMENTS
161 | The specified path is invalid. | ERROR_BAD_PATHNAME
162 | A signal is already pending. | ERROR_SIGNAL_PENDING
164 | No more threads can be created in the system. | ERROR_MAX_THRDS_REACHED
167 | Unable to lock a region of a file. | ERROR_LOCK_FAILED
170 | The requested resource is in use. | ERROR_BUSY
173 | A lock request was not outstanding for the supplied cancel region. | ERROR_CANCEL_VIOLATION
174 | The file system does not support atomic changes to the lock type. | ERROR_ATOMIC_LOCKS_NOT_SUPPORTED
180 | The system detected a segment number that was not correct. | ERROR_INVALID_SEGMENT_NUMBER
182 | The operating system cannot run %1. | ERROR_INVALID_ORDINAL
183 | Cannot create a file when that file already exists. | ERROR_ALREADY_EXISTS
186 | The flag passed is not correct. | ERROR_INVALID_FLAG_NUMBER
187 | The specified system semaphore name was not found. | ERROR_SEM_NOT_FOUND
188 | The operating system cannot run %1. | ERROR_INVALID_STARTING_CODESEG
189 | The operating system cannot run %1. | ERROR_INVALID_STACKSEG
190 | The operating system cannot run %1. | ERROR_INVALID_MODULETYPE
191 | Cannot run %1 in Windows NT mode. | ERROR_INVALID_EXE_SIGNATURE
192 | The operating system cannot run %1. | ERROR_EXE_MARKED_INVALID
193 | Is not a valid application. | ERROR_BAD_EXE_FORMAT
194 | The operating system cannot run %1. | ERROR_ITERATED_DATA_EXCEEDS_64k
195 | The operating system cannot run %1. | ERROR_INVALID_MINALLOCSIZE
196 | The operating system cannot run this application program. | ERROR_DYNLINK_FROM_INVALID_RING
197 | The operating system is not presently configured to run this application. | ERROR_IOPL_NOT_ENABLED
198 | The operating system cannot run %1. | ERROR_INVALID_SEGDPL
199 | The operating system cannot run this application program. | ERROR_AUTODATASEG_EXCEEDS_64k
200 | The code segment cannot be greater than or equal to 64 KB. | ERROR_RING2SEG_MUST_BE_MOVABLE
201 | The operating system cannot run %1. | ERROR_RELOC_CHAIN_XEEDS_SEGLIM
202 | The operating system cannot run %1. | ERROR_INFLOOP_IN_RELOC_CHAIN
203 | The system could not find the environment option that was entered. | ERROR_ENVVAR_NOT_FOUND
205 | No process in the command subtree has a signal handler. | ERROR_NO_SIGNAL_SENT
206 | The file name or extension is too long. | ERROR_FILENAME_EXCED_RANGE
207 | The ring 2 stack is in use. | ERROR_RING2_STACK_IN_USE
208 | The global file name characters, “*” or “?,” are entered incorrectly or too many global file name characters are specified. | ERROR_META_EXPANSION_TOO_LONG
209 | The signal being posted is not correct. | ERROR_INVALID_SIGNAL_NUMBER
210 | The signal handler cannot be set. | ERROR_THREAD_1_INACTIVE
212 | The segment is locked and cannot be reallocated. | ERROR_LOCKED
214 | Too many dynamic-link modules are attached to this program or dynamic-link module. | ERROR_TOO_MANY_MODULES
215 | Cannot nest calls to LoadModule. | ERROR_NESTING_NOT_ALLOWED
216 | The image file %1 is valid, but is for a machine type other than the current machine. | ERROR_EXE_MACHINE_TYPE_MISMATCH
230 | The pipe state is invalid. | ERROR_BAD_PIPE
231 | All pipe instances are busy. | ERROR_PIPE_BUSY
232 | The pipe is being closed. | ERROR_NO_DATA
233 | No process is on the other end of the pipe. | ERROR_PIPE_NOT_CONNECTED
234 | More data is available. | ERROR_MORE_DATA
240 | The session was canceled. | ERROR_VC_DISCONNECTED
254 | The specified extended attribute name was invalid. | ERROR_INVALID_EA_NAME
255 | The extended attributes are inconsistent. | ERROR_EA_LIST_INCONSISTENT
259 | No more data is available. | ERROR_NO_MORE_ITEMS
266 | The copy functions cannot be used. | ERROR_CANNOT_COPY
267 | The directory name is invalid. | ERROR_DIRECTORY
275 | The extended attributes did not fit in the buffer. | ERROR_EAS_DIDNT_FIT
276 | The extended attribute file on the mounted file system is corrupt. | ERROR_EA_FILE_CORRUPT
277 | The extended attribute table file is full. | ERROR_EA_TABLE_FULL
278 | The specified extended attribute handle is invalid. | ERROR_INVALID_EA_HANDLE
282 | The mounted file system does not support extended attributes. | ERROR_EAS_NOT_SUPPORTED
288 | Attempt to release mutex not owned by caller. | ERROR_NOT_OWNER
298 | Too many posts were made to a semaphore. | ERROR_TOO_MANY_POSTS
299 | Only part of a ReadProcessMemory or WriteProcessMemory request was completed. | ERROR_PARTIAL_COPY
317 | The system cannot find message text for message number 0x%1 in the message file for %2. | ERROR_MR_MID_NOT_FOUND
487 | Attempt to access invalid address. | ERROR_INVALID_ADDRESS
534 | Arithmetic result exceeded 32 bits. | ERROR_ARITHMETIC_OVERFLOW
535 | There is a process on other end of the pipe. | ERROR_PIPE_CONNECTED
536 | Waiting for a process to open the other end of the pipe. | ERROR_PIPE_LISTENING
994 | Access to the extended attribute was denied. | ERROR_EA_ACCESS_DENIED
995 | The I/O operation has been aborted because of either a thread exit or an application request. | ERROR_OPERATION_ABORTED
996 | Overlapped I/O event is not in a signaled state. | ERROR_IO_INCOMPLETE
997 | Overlapped I/O operation is in progress. | ERROR_IO_PENDING
998 | Invalid access to memory location. | ERROR_NOACCESS
999 | Error performing inpage operation. | ERROR_SWAPERROR
1001 | Recursion too deep; the stack overflowed. | ERROR_STACK_OVERFLOW
1002 | The window cannot act on the sent message. | ERROR_INVALID_MESSAGE
1003 | Cannot complete this function. | ERROR_CAN_NOT_COMPLETE
1004 | Invalid flags. | ERROR_INVALID_FLAGS
1005 | The volume does not contain a recognized file system. Verify that all required file system drivers are loaded and that the volume is not corrupted. | ERROR_UNRECOGNIZED_VOLUME
1006 | The volume for a file has been externally altered so that the opened file is no longer valid. | ERROR_FILE_INVALID
1007 | The requested operation cannot be performed in full-screen mode. | ERROR_FULLSCREEN_MODE
1008 | An attempt was made to reference a token that does not exist. | ERROR_NO_TOKEN
1009 | The configuration registry database is corrupt. | ERROR_BADDB
1010 | The configuration registry key is invalid. | ERROR_BADKEY
1011 | The configuration registry key could not be opened. | ERROR_CANTOPEN
1012 | The configuration registry key could not be read. | ERROR_CANTREAD
1013 | The configuration registry key could not be written. | ERROR_CANTWRITE
1014 | One of the files in the registry database had to be recovered by use of a log or alternate copy. The recovery was successful. | ERROR_REGISTRY_RECOVERED
1015 | The registry is corrupted. The structure of one of the files that contains registry data is corrupted, or the system's image of the file in memory is corrupted, or the file could not be recovered because the alternate copy or log was absent or corrupted. | ERROR_REGISTRY_CORRUPT
1016 | An I/O operation initiated by the registry failed unrecoverably. The registry could not read in, or write out, or flush, one of the files that contain the system's image of the registry. | ERROR_REGISTRY_IO_FAILED
1017 | The system has attempted to load or restore a file into the registry, but the specified file is not in a registry file format. | ERROR_NOT_REGISTRY_FILE
1018 | Illegal operation attempted on a registry key that has been marked for deletion. | ERROR_KEY_DELETED
1019 | System could not allocate the required space in a registry log. | ERROR_NO_LOG_SPACE
1020 | Cannot create a symbolic link in a registry key that already has subkeys or values. | ERROR_KEY_HAS_CHILDREN
1021 | Cannot create a stable subkey under a volatile parent key. | ERROR_CHILD_MUST_BE_VOLATILE
1022 | A notify change request is being completed and the information is not being returned in the caller's buffer. The caller now needs to enumerate the files to find the changes. | ERROR_NOTIFY_ENUM_DIR
1051 | A stop control has been sent to a service that other running services are dependent on. | ERROR_DEPENDENT_SERVICES_RUNNING
1052 | The requested control is not valid for this service. | ERROR_INVALID_SERVICE_CONTROL
1053 | The service did not respond to the start or control request in a timely fashion. | ERROR_SERVICE_REQUEST_TIMEOUT
1054 | A thread could not be created for the service. | ERROR_SERVICE_NO_THREAD
1055 | The service database is locked. | ERROR_SERVICE_DATABASE_LOCKED
1056 | An instance of the service is already running. | ERROR_SERVICE_ALREADY_RUNNING
1057 | The account name is invalid or does not exist. | ERROR_INVALID_SERVICE_ACCOUNT
1058 | The specified service is disabled and cannot be started. | ERROR_SERVICE_DISABLED
1059 | Circular service dependency was specified. | ERROR_CIRCULAR_DEPENDENCY
1060 | The specified service does not exist as an installed service. | ERROR_SERVICE_DOES_NOT_EXIST
1061 | The service cannot accept control messages at this time. | ERROR_SERVICE_CANNOT_ACCEPT_CTRL
1062 | The service has not been started. | ERROR_SERVICE_NOT_ACTIVE
1063 | The service process could not connect to the service controller. | ERROR_FAILED_SERVICE_CONTROLLER_CONNECT
1064 | An exception occurred in the service when handling the control request. | ERROR_EXCEPTION_IN_SERVICE
1065 | The database specified does not exist. | ERROR_DATABASE_DOES_NOT_EXIST
1066 | The service has returned a service-specific error code. | ERROR_SERVICE_SPECIFIC_ERROR
1067 | The process terminated unexpectedly. | ERROR_PROCESS_ABORTED
1068 | The dependency service or group failed to start. | ERROR_SERVICE_DEPENDENCY_FAIL
1069 | The service did not start due to a logon failure. | ERROR_SERVICE_LOGON_FAILED
1070 | After starting, the service hung in a start-pending state. | ERROR_SERVICE_START_HANG
1071 | The specified service database lock is invalid. | ERROR_INVALID_SERVICE_LOCK
1072 | The specified service has been marked for deletion. | ERROR_SERVICE_MARKED_FOR_DELETE
1073 | The specified service already exists. | ERROR_SERVICE_EXISTS
1074 | The system is currently running with the last-known-good configuration. | ERROR_ALREADY_RUNNING_LKG
1075 | The dependency service does not exist or has been marked for deletion. | ERROR_SERVICE_DEPENDENCY_DELETED
1076 | The current boot has already been accepted for use as the last-known-good control set. | ERROR_BOOT_ALREADY_ACCEPTED
1077 | No attempts to start the service have been made since the last boot. | ERROR_SERVICE_NEVER_STARTED
1078 | The name is already in use as either a service name or a service display name. | ERROR_DUPLICATE_SERVICE_NAME
1079 | The account specified for this service is different from the account specified for other services running in the same process. | ERROR_DIFFERENT_SERVICE_ACCOUNT
1100 | The physical end of the tape has been reached. | ERROR_END_OF_MEDIA
1101 | A tape access reached a filemark. | ERROR_FILEMARK_DETECTED
1102 | The beginning of the tape or partition was encountered. | ERROR_BEGINNING_OF_MEDIA
1103 | A tape access reached the end of a set of files. | ERROR_SETMARK_DETECTED
1104 | No more data is on the tape. | ERROR_NO_DATA_DETECTED
1105 | Tape could not be partitioned. | ERROR_PARTITION_FAILURE
1106 | When accessing a new tape of a multivolume partition, the current block size is incorrect. | ERROR_INVALID_BLOCK_LENGTH
1107 | Tape partition information could not be found when loading a tape. | ERROR_DEVICE_NOT_PARTITIONED
1108 | Unable to lock the media eject mechanism. | ERROR_UNABLE_TO_LOCK_MEDIA
1109 | Unable to unload the media. | ERROR_UNABLE_TO_UNLOAD_MEDIA
1110 | The media in the drive may have changed. | ERROR_MEDIA_CHANGED
1111 | The I/O bus was reset. | ERROR_BUS_RESET
1112 | No media in drive. | ERROR_NO_MEDIA_IN_DRIVE
1113 | No mapping for the Unicode character exists in the target multibyte code page. | ERROR_NO_UNICODE_TRANSLATION
1114 | A dynamic link library (DLL) initialization routine failed. | ERROR_DLL_INIT_FAILED
1115 | A system shutdown is in progress. | ERROR_SHUTDOWN_IN_PROGRESS
1116 | Unable to abort the system shutdown because no shutdown was in progress. | ERROR_NO_SHUTDOWN_IN_PROGRESS
1117 | The request could not be performed because of an I/O device error. | ERROR_IO_DEVICE
1118 | No serial device was successfully initialized. The serial driver will unload. | ERROR_SERIAL_NO_DEVICE
1119 | Unable to open a device that was sharing an interrupt request (IRQ) with other devices. At least one other device that uses that IRQ was already opened. | ERROR_IRQ_BUSY
1120 | A serial I/O operation was completed by another write to the serial port. The IOCTL_SERIAL_XOFF_COUNTER reached zero.) | ERROR_MORE_WRITES
1121 | A serial I/O operation completed because the time-out period expired. In other words, the IOCTL_SERIAL_XOFF_COUNTER did not reach zero. | ERROR_COUNTER_TIMEOUT
1122 | No identifier address mark was found on the floppy disk. | ERROR_FLOPPY_ID_MARK_NOT_FOUND
1123 | Mismatch between the floppy disk sector identifier field and the floppy disk controller track address. | ERROR_FLOPPY_WRONG_CYLINDER
1124 | The floppy disk controller reported an error that is not recognized by the floppy disk driver. | ERROR_FLOPPY_UNKNOWN_ERROR
1125 | The floppy disk controller returned inconsistent results in its registers. | ERROR_FLOPPY_BAD_REGISTERS
1126 | While accessing the hard disk, a recalibrate operation failed, even after retries. | ERROR_DISK_RECALIBRATE_FAILED
1127 | While accessing the hard disk, a disk operation failed even after retries. | ERROR_DISK_OPERATION_FAILED
1128 | While accessing the hard disk, a disk controller reset was needed, but even that failed. | ERROR_DISK_RESET_FAILED
1129 | Physical end of tape encountered. | ERROR_EOM_OVERFLOW
1130 | Not enough server storage is available to process this command. | ERROR_NOT_ENOUGH_SERVER_MEMORY
1131 | A potential deadlock condition has been detected. | ERROR_POSSIBLE_DEADLOCK
1132 | The base address or the file offset specified does not have the proper alignment. | ERROR_MAPPED_ALIGNMENT
1140 | An attempt to change the system power state was vetoed by another application or driver. | ERROR_SET_POWER_STATE_VETOED
1141 | The basic input/output system (BIOS) failed an attempt to change the system power state. | ERROR_SET_POWER_STATE_FAILED
1142 | An attempt was made to create more links on a file than the file system supports. | ERROR_TOO_MANY_LINKS
1150 | The specified program requires a newer version of Windows. | ERROR_OLD_WIN_VERSION
1151 | The specified program is not a Windows or MS-DOS program. | ERROR_APP_WRONG_OS
1152 | Cannot start more than one instance of the specified program. | ERROR_SINGLE_INSTANCE_APP
1153 | The specified program was written for an earlier version of Windows. | ERROR_RMODE_APP
1154 | One of the library files needed to run this application is damaged. | ERROR_INVALID_DLL
1155 | No application is associated with the specified file for this operation. | ERROR_NO_ASSOCIATION
1156 | An error occurred in sending the command to the application. | ERROR_DDE_FAIL
1157 | One of the library files needed to run this application cannot be found. | ERROR_DLL_NOT_FOUND
1200 | The specified device name is invalid. | ERROR_BAD_DEVICE
1201 | The device is not currently connected but it is a remembered connection. | ERROR_CONNECTION_UNAVAIL
1202 | An attempt was made to remember a device that had previously been remembered. | ERROR_DEVICE_ALREADY_REMEMBERED
1203 | No network provider accepted the given network path. | ERROR_NO_NET_OR_BAD_PATH
1204 | The specified network provider name is invalid. | ERROR_BAD_PROVIDER
1205 | Unable to open the network connection profile. | ERROR_CANNOT_OPEN_PROFILE
1206 | The network connection profile is corrupt. | ERROR_BAD_PROFILE
1207 | Cannot enumerate a noncontainer. | ERROR_NOT_CONTAINER
1208 | An extended error has occurred. | ERROR_EXTENDED_ERROR
1209 | The format of the specified group name is invalid. | ERROR_INVALID_GROUPNAME
1210 | The format of the specified computer name is invalid. | ERROR_INVALID_COMPUTERNAME
1211 | The format of the specified event name is invalid. | ERROR_INVALID_EVENTNAME
1212 | The format of the specified domain name is invalid. | ERROR_INVALID_DOMAINNAME
1213 | The format of the specified service name is invalid. | ERROR_INVALID_SERVICENAME
1214 | The format of the specified network name is invalid. | ERROR_INVALID_NETNAME
1215 | The format of the specified share name is invalid. | ERROR_INVALID_SHARENAME
1216 | The format of the specified password is invalid. | ERROR_INVALID_PASSWORDNAME
1217 | The format of the specified message name is invalid. | ERROR_INVALID_MESSAGENAME
1218 | The format of the specified message destination is invalid. | ERROR_INVALID_MESSAGEDEST
1219 | The credentials supplied conflict with an existing set of credentials. | ERROR_SESSION_CREDENTIAL_CONFLICT
1220 | An attempt was made to establish a session to a network server, but there are already too many sessions established to that server. | ERROR_REMOTE_SESSION_LIMIT_EXCEEDED
1221 | The workgroup or domain name is already in use by another computer on the network. | ERROR_DUP_DOMAINNAME
1222 | The network is not present or not started. | ERROR_NO_NETWORK
1223 | The operation was canceled by the user. | ERROR_CANCELLED
1224 | The requested operation cannot be performed on a file with a user-mapped section open. | ERROR_USER_MAPPED_FILE
1225 | The remote system refused the network connection. | ERROR_CONNECTION_REFUSED
1226 | The network connection was gracefully closed. | ERROR_GRACEFUL_DISCONNECT
1227 | The network transport endpoint already has an address associated with it. | ERROR_ADDRESS_ALREADY_ASSOCIATED
1228 | An address has not yet been associated with the network endpoint. | ERROR_ADDRESS_NOT_ASSOCIATED
1229 | An operation was attempted on a nonexistent network connection. | ERROR_CONNECTION_INVALID
1230 | An invalid operation was attempted on an active network connection. | ERROR_CONNECTION_ACTIVE
1231 | The remote network is not reachable by the transport. | ERROR_NETWORK_UNREACHABLE
1232 | The remote system is not reachable by the transport. | ERROR_HOST_UNREACHABLE
1233 | The remote system does not support the transport protocol. | ERROR_PROTOCOL_UNREACHABLE
1234 | No service is operating at the destination network endpoint on the remote system. | ERROR_PORT_UNREACHABLE
1235 | The request was aborted. | ERROR_REQUEST_ABORTED
1236 | The network connection was aborted by the local system. | ERROR_CONNECTION_ABORTED
1237 | The operation could not be completed. A retry should be performed. | ERROR_RETRY
1238 | A connection to the server could not be made because the limit on the number of concurrent connections for this account has been reached. | ERROR_CONNECTION_COUNT_LIMIT
1239 | Attempting to log in during an unauthorized time of day for this account. | ERROR_LOGIN_TIME_RESTRICTION
1240 | The account is not authorized to log in from this station. | ERROR_LOGIN_WKSTA_RESTRICTION
1241 | The network address could not be used for the operation requested. | ERROR_INCORRECT_ADDRESS
1242 | The service is already registered. | ERROR_ALREADY_REGISTERED
1243 | The specified service does not exist. | ERROR_SERVICE_NOT_FOUND
1244 | The operation being requested was not performed because the user has not been authenticated. | ERROR_NOT_AUTHENTICATED
1245 | The operation being requested was not performed because the user has not logged on to the network. The specified service does not exist. | ERROR_NOT_LOGGED_ON
1246 | Caller to continue with work in progress. | ERROR_CONTINUE
1247 | An attempt was made to perform an initialization operation when initialization has already been completed. | ERROR_ALREADY_INITIALIZED
1248 | No more local devices. | ERROR_NO_MORE_DEVICES
1300 | Not all privileges referenced are assigned to the caller. | ERROR_NOT_ALL_ASSIGNED
1301 | Some mapping between account names and security IDs was not done. | ERROR_SOME_NOT_MAPPED
1302 | No system quota limits are specifically set for this account. | ERROR_NO_QUOTAS_FOR_ACCOUNT
1303 | No encryption key is available. A well-known encryption key was returned. | ERROR_LOCAL_USER_SESSION_KEY
1304 | The password is too complex to be converted to a LAN Manager password. The LAN Manager password returned is a null string. | ERROR_NULL_LM_PASSWORD
1305 | The revision level is unknown. | ERROR_UNKNOWN_REVISION
1306 | Indicates two revision levels are incompatible. | ERROR_REVISION_MISMATCH
1307 | This security identifier may not be assigned as the owner of this object. | ERROR_INVALID_OWNER
1308 | This security identifier may not be assigned as the primary group of an object. | ERROR_INVALID_PRIMARY_GROUP
1309 | An attempt has been made to operate on an impersonation token by a thread that is not currently impersonating a client. | ERROR_NO_IMPERSONATION_TOKEN
1310 | The group cannot be disabled. | ERROR_CANT_DISABLE_MANDATORY
1311 | There are currently no logon servers available to service the logon request. | ERROR_NO_LOGON_SERVERS
1312 | A specified logon session does not exist. It may already have been terminated. | ERROR_NO_SUCH_LOGON_SESSION
1313 | A specified privilege does not exist. | ERROR_NO_SUCH_PRIVILEGE
1314 | A required privilege is not held by the client. | ERROR_PRIVILEGE_NOT_HELD
1315 | The name provided is not a properly formed account name. | ERROR_INVALID_ACCOUNT_NAME
1316 | The specified user already exists. | ERROR_USER_EXISTS
1317 | The specified user does not exist. | ERROR_NO_SUCH_USER
1318 | The specified group already exists. | ERROR_GROUP_EXISTS
1319 | The specified group does not exist. | ERROR_NO_SUCH_GROUP
1320 | Either the specified user account is already a member of the specified group, or the specified group cannot be deleted because it contains a member. | ERROR_MEMBER_IN_GROUP
1321 | The specified user account is not a member of the specified group account. | ERROR_MEMBER_NOT_IN_GROUP
1322 | The last remaining administration account cannot be disabled or deleted. | ERROR_LAST_ADMIN
1323 | Unable to update the password. The value provided as the current password is incorrect. | ERROR_WRONG_PASSWORD
1324 | Unable to update the password. The value provided for the new password contains values that are not allowed in passwords. | ERROR_ILL_FORMED_PASSWORD
1325 | Unable to update the password because a password update rule has been violated. | ERROR_PASSWORD_RESTRICTION
1326 | Logon failure—unknown user name or bad password. | ERROR_LOGON_FAILURE
1327 | Logon failure—user account restriction. | ERROR_ACCOUNT_RESTRICTION
1328 | Logon failure—account logon time restriction violation. | ERROR_INVALID_LOGON_HOURS
1329 | Logon failure—user not allowed to log on to this computer. | ERROR_INVALID_WORKSTATION
1330 | Logon failure—the specified account password has expired. | ERROR_PASSWORD_EXPIRED
1331 | Logon failure—account currently disabled. | ERROR_ACCOUNT_DISABLED
1332 | No mapping between account names and security IDs was done. | ERROR_NONE_MAPPED
1333 | Too many LUIDs were requested at one time. | ERROR_TOO_MANY_LUIDS_REQUESTED
1334 | No more LUIDs are available. | ERROR_LUIDS_EXHAUSTED
1335 | The subauthority part of a security identifier is invalid for this particular use. | ERROR_INVALID_SUB_AUTHORITY
1336 | The access control list (ACL) structure is invalid. | ERROR_INVALID_ACL
1337 | The security identifier structure is invalid. | ERROR_INVALID_SID
1338 | The security descriptor structure is invalid. | ERROR_INVALID_SECURITY_DESCR
1340 | The inherited access control list (ACL) or access control entry (ACE) could not be built. | ERROR_BAD_INHERITANCE_ACL
1341 | The server is currently disabled. | ERROR_SERVER_DISABLED
1342 | The server is currently enabled. | ERROR_SERVER_NOT_DISABLED
1343 | The value provided was an invalid value for an identifier authority. | ERROR_INVALID_ID_AUTHORITY
1344 | No more memory is available for security information updates. | ERROR_ALLOTTED_SPACE_EXCEEDED
1345 | The specified attributes are invalid, or incompatible with the attributes for the group as a whole. | ERROR_INVALID_GROUP_ATTRIBUTES
1346 | Either a required impersonation level was not provided, or the provided impersonation level is invalid. | ERROR_BAD_IMPERSONATION_LEVEL
1347 | Cannot open an anonymous level security token. | ERROR_CANT_OPEN_ANONYMOUS
1348 | The validation information class requested was invalid. | ERROR_BAD_VALIDATION_CLASS
1349 | The type of the token is inappropriate for its attempted use. | ERROR_BAD_TOKEN_TYPE
1350 | Unable to perform a security operation on an object that has no associated security. | ERROR_NO_SECURITY_ON_OBJECT
1351 | Indicates that a Windows NT Server could not be contacted or that objects within the domain are protected such that necessary information could not be retrieved. | ERROR_CANT_ACCESS_DOMAIN_INFO
1352 | The security account manager (SAM) or local security authority (LSA) server was in the wrong state to perform the security operation. | ERROR_INVALID_SERVER_STATE
1353 | The domain was in the wrong state to perform the security operation. | ERROR_INVALID_DOMAIN_STATE
1354 | This operation is only allowed for the Primary Domain Controller (PDC) of the domain. | ERROR_INVALID_DOMAIN_ROLE
1355 | The specified domain did not exist. | ERROR_NO_SUCH_DOMAIN
1356 | The specified domain already exists. | ERROR_DOMAIN_EXISTS
1357 | An attempt was made to exceed the limit on the number of domains per server. | ERROR_DOMAIN_LIMIT_EXCEEDED
1358 | Unable to complete the requested operation because of either a catastrophic media failure or a data structure corruption on the disk. | ERROR_INTERNAL_DB_CORRUPTION
1359 | The security account database contains an internal inconsistency. | ERROR_INTERNAL_ERROR
1360 | Generic access types were contained in an access mask that should already be mapped to nongeneric types. | ERROR_GENERIC_NOT_MAPPED
1361 | A security descriptor is not in the right format (absolute or self-relative). | ERROR_BAD_DESCRIPTOR_FORMAT
1362 | The requested action is restricted for use by logon processes only. The calling process has not registered as a logon process. | ERROR_NOT_LOGON_PROCESS
1363 | Cannot start a new logon session with an identifier that is already in use. | ERROR_LOGON_SESSION_EXISTS
1364 | A specified authentication package is unknown. | ERROR_NO_SUCH_PACKAGE
1365 | The logon session is not in a state that is consistent with the requested operation. | ERROR_BAD_LOGON_SESSION_STATE
1366 | The logon session identifier is already in use. | ERROR_LOGON_SESSION_COLLISION
1367 | A logon request contained an invalid logon type value. | ERROR_INVALID_LOGON_TYPE
1368 | Unable to impersonate using a named pipe until data has been read from that pipe. | ERROR_CANNOT_IMPERSONATE
1369 | The transaction state of a registry subtree is incompatible with the requested operation. | ERROR_RXACT_INVALID_STATE
1370 | An internal security database corruption has been encountered. | ERROR_RXACT_COMMIT_FAILURE
1371 | Cannot perform this operation on built-in accounts. | ERROR_SPECIAL_ACCOUNT
1372 | Cannot perform this operation on this built-in special group. | ERROR_SPECIAL_GROUP
1373 | Cannot perform this operation on this built-in special user. | ERROR_SPECIAL_USER
1374 | The user cannot be removed from a group because the group is currently the user's primary group. | ERROR_MEMBERS_PRIMARY_GROUP
1375 | The token is already in use as a primary token. | ERROR_TOKEN_ALREADY_IN_USE
1376 | The specified local group does not exist. | ERROR_NO_SUCH_ALIAS
1377 | The specified account name is not a member of the local group. | ERROR_MEMBER_NOT_IN_ALIAS
1378 | The specified account name is already a member of the local group. | ERROR_MEMBER_IN_ALIAS
1379 | The specified local group already exists. | ERROR_ALIAS_EXISTS
1380 | Logon failure—the user has not been granted the requested logon type at this computer. | ERROR_LOGON_NOT_GRANTED
1381 | The maximum number of secrets that may be stored in a single system has been exceeded. | ERROR_TOO_MANY_SECRETS
1382 | The length of a secret exceeds the maximum length allowed. | ERROR_SECRET_TOO_LONG
1383 | The local security authority database contains an internal inconsistency. | ERROR_INTERNAL_DB_ERROR
1384 | During a logon attempt, the user's security context accumulated too many security IDs. | ERROR_TOO_MANY_CONTEXT_IDS
1385 | Logon failure—the user has not been granted the requested logon type at this computer. | ERROR_LOGON_TYPE_NOT_GRANTED
1386 | A cross-encrypted password is necessary to change a user password. | ERROR_NT_CROSS_ENCRYPTION_REQUIRED
1387 | A new member could not be added to a local group because the member does not exist. | ERROR_NO_SUCH_MEMBER
1388 | A new member could not be added to a local group because the member has the wrong account type. | ERROR_INVALID_MEMBER
1389 | Too many security IDs have been specified. | ERROR_TOO_MANY_SIDS
1390 | A cross-encrypted password is necessary to change this user password. | ERROR_LM_CROSS_ENCRYPTION_REQUIRED
1391 | Indicates an ACL contains no inheritable components. | ERROR_NO_INHERITANCE
1392 | The file or directory is corrupted and non-readable. | ERROR_FILE_CORRUPT
1393 | The disk structure is corrupted and non-readable. | ERROR_DISK_CORRUPT
1394 | There is no user session key for the specified logon session. | ERROR_NO_USER_SESSION_KEY
1395 | The service being accessed is licensed for a particular number of connections. No more connections can be made to the service at this time because there are already as many connections as the service can accept. | ERROR_LICENSE_QUOTA_EXCEEDED
1400 | Invalid window handle. | ERROR_INVALID_WINDOW_HANDLE
1401 | Invalid menu handle. | ERROR_INVALID_MENU_HANDLE
1402 | Invalid cursor handle. | ERROR_INVALID_CURSOR_HANDLE
1403 | Invalid accelerator table handle. | ERROR_INVALID_ACCEL_HANDLE
1404 | Invalid hook handle. | ERROR_INVALID_HOOK_HANDLE
1405 | Invalid handle to a multiple-window position structure. | ERROR_INVALID_DWP_HANDLE
1406 | Cannot create a top-level child window. | ERROR_TLW_WITH_WSCHILD
1407 | Cannot find window class. | ERROR_CANNOT_FIND_WND_CLASS
1408 | Invalid window, it belongs to another thread. | ERROR_WINDOW_OF_OTHER_THREAD
1409 | Hot key is already registered. | ERROR_HOTKEY_ALREADY_REGISTERED
1410 | Class already exists. | ERROR_CLASS_ALREADY_EXISTS
1411 | Class does not exist. | ERROR_CLASS_DOES_NOT_EXIST
1412 | Class still has open windows. | ERROR_CLASS_HAS_WINDOWS
1413 | Invalid index. | ERROR_INVALID_INDEX
1414 | Invalid icon handle. | ERROR_INVALID_ICON_HANDLE
1415 | Using private DIALOG window words. | ERROR_PRIVATE_DIALOG_INDEX
1416 | The list box identifier was not found. | ERROR_LISTBOX_ID_NOT_FOUND
1417 | No wildcards were found. | ERROR_NO_WILDCARD_CHARACTERS
1418 | Thread does not have a clipboard open. | ERROR_CLIPBOARD_NOT_OPEN
1419 | Hot key is not registered. | ERROR_HOTKEY_NOT_REGISTERED
1420 | The window is not a valid dialog window. | ERROR_WINDOW_NOT_DIALOG
1421 | Control identifier not found. | ERROR_CONTROL_ID_NOT_FOUND
1422 | Invalid message for a combo box because it does not have an edit control. | ERROR_INVALID_COMBOBOX_MESSAGE
1423 | The window is not a combo box. | ERROR_WINDOW_NOT_COMBOBOX
1424 | Height must be less than 256. | ERROR_INVALID_EDIT_HEIGHT
1425 | Invalid device context (DC) handle. | ERROR_DC_NOT_FOUND
1426 | Invalid hook procedure type. | ERROR_INVALID_HOOK_FILTER
1427 | Invalid hook procedure. | ERROR_INVALID_FILTER_PROC
1428 | Cannot set nonlocal hook without a module handle. | ERROR_HOOK_NEEDS_HMOD
1429 | This hook procedure can only be set globally. | ERROR_GLOBAL_ONLY_HOOK
1430 | The journal hook procedure is already installed. | ERROR_JOURNAL_HOOK_SET
1431 | The hook procedure is not installed. | ERROR_HOOK_NOT_INSTALLED
1432 | Invalid message for single-selection list box. | ERROR_INVALID_LB_MESSAGE
1434 | This list box does not support tab stops. | ERROR_LB_WITHOUT_TABSTOPS
1435 | Cannot destroy object created by another thread. | ERROR_DESTROY_OBJECT_OF_OTHER_THREAD
1436 | Child windows cannot have menus. | ERROR_CHILD_WINDOW_MENU
1437 | The window does not have a system menu. | ERROR_NO_SYSTEM_MENU
1438 | Invalid message box style. | ERROR_INVALID_MSGBOX_STYLE
1439 | Invalid system-wide (SPI_*) parameter. | ERROR_INVALID_SPI_VALUE
1440 | Screen already locked. | ERROR_SCREEN_ALREADY_LOCKED
1441 | All handles to windows in a multiple-window position structure must have the same parent. | ERROR_HWNDS_HAVE_DIFF_PARENT
1442 | The window is not a child window. | ERROR_NOT_CHILD_WINDOW
1443 | Invalid GW_* command. | ERROR_INVALID_GW_COMMAND
1444 | Invalid thread identifier. | ERROR_INVALID_THREAD_ID
1445 | Cannot process a message from a window that is not a multiple-document interface (MDI) window. | ERROR_NON_MDICHILD_WINDOW
1446 | Pop-up menu already active. | ERROR_POPUP_ALREADY_ACTIVE
1447 | The window does not have scroll bars. | ERROR_NO_SCROLLBARS
1448 | Scroll bar range cannot be greater than 0x7FFF. | ERROR_INVALID_SCROLLBAR_RANGE
1449 | Cannot show or remove the window in the way specified. | ERROR_INVALID_SHOWWIN_COMMAND
1450 | Insufficient system resources exist to complete the requested service. | ERROR_NO_SYSTEM_RESOURCES
1451 | Insufficient system resources exist to complete the requested service. | ERROR_NONPAGED_SYSTEM_RESOURCES
1452 | Insufficient system resources exist to complete the requested service. | ERROR_PAGED_SYSTEM_RESOURCES
1453 | Insufficient quota to complete the requested service. | ERROR_WORKING_SET_QUOTA
1454 | Insufficient quota to complete the requested service. | ERROR_PAGEFILE_QUOTA
1455 | The paging file is too small for this operation to complete. | ERROR_COMMITMENT_LIMIT
1456 | A menu item was not found. | ERROR_MENU_ITEM_NOT_FOUND
1457 | Invalid keyboard layout handle. | ERROR_INVALID_KEYBOARD_HANDLE
1458 | Hook type not allowed. | ERROR_HOOK_TYPE_NOT_ALLOWED
1459 | This operation requires an interactive window station. | ERROR_REQUIRES_INTERACTIVE_WINDOWSTATION
1460 | This operation returned because the time-out period expired. | ERROR_TIMEOUT
1500 | The event log file is corrupted. | ERROR_EVENTLOG_FILE_CORRUPT
1501 | No event log file could be opened, so the event logging service did not start. | ERROR_EVENTLOG_CANT_START
1502 | The event log file is full. | ERROR_LOG_FILE_FULL
1503 | The event log file has changed between read operations. | ERROR_EVENTLOG_FILE_CHANGED
1700 | The string binding is invalid. | RPC_S_INVALID_STRING_BINDING
1701 | The binding handle is not the correct type. | RPC_S_WRONG_KIND_OF_BINDING
1702 | The binding handle is invalid. | RPC_S_INVALID_BINDING
1703 | The RPC protocol sequence is not supported. | RPC_S_PROTSEQ_NOT_SUPPORTED
1704 | The RPC protocol sequence is invalid. | RPC_S_INVALID_RPC_PROTSEQ
1705 | The string universal unique identifier (UUID) is invalid. | RPC_S_INVALID_STRING_UUID
1706 | The endpoint format is invalid. | RPC_S_INVALID_ENDPOINT_FORMAT
1707 | The network address is invalid. | RPC_S_INVALID_NET_ADDR
1708 | No endpoint was found. | RPC_S_NO_ENDPOINT_FOUND
1709 | The time-out value is invalid. | RPC_S_INVALID_TIMEOUT
1710 | The object universal unique identifier (UUID) was not found. | RPC_S_OBJECT_NOT_FOUND
1711 | The object universally unique identifier (UUID) has already been registered. | RPC_S_ALREADY_REGISTERED
1712 | The type UUID has already been registered. | RPC_S_TYPE_ALREADY_REGISTERED
1713 | The remote procedure call (RPC) server is already listening. | RPC_S_ALREADY_LISTENING
1714 | No protocol sequences have been registered. | RPC_S_NO_PROTSEQS_REGISTERED
1715 | The RPC server is not listening. | RPC_S_NOT_LISTENING
1716 | The manager type is unknown. | RPC_S_UNKNOWN_MGR_TYPE
1717 | The interface is unknown. | RPC_S_UNKNOWN_IF
1718 | There are no bindings. | RPC_S_NO_BINDINGS
1719 | There are no protocol sequences. | RPC_S_NO_PROTSEQS
1720 | The endpoint cannot be created. | RPC_S_CANT_CREATE_ENDPOINT
1721 | Not enough resources are available to complete this operation. | RPC_S_OUT_OF_RESOURCES
1722 | The RPC server is unavailable. | RPC_S_SERVER_UNAVAILABLE
1723 | The RPC server is too busy to complete this operation. | RPC_S_SERVER_TOO_BUSY
1724 | The network options are invalid. | RPC_S_INVALID_NETWORK_OPTIONS
1725 | There is not a remote procedure call active in this thread. | RPC_S_NO_CALL_ACTIVE
1726 | The remote procedure call failed. | RPC_S_CALL_FAILED
1727 | The remote procedure call failed and did not execute. | RPC_S_CALL_FAILED_DNE
1728 | A remote procedure call (RPC) protocol error occurred. | RPC_S_PROTOCOL_ERROR
1730 | The transfer syntax is not supported by the RPC server. | RPC_S_UNSUPPORTED_TRANS_SYN
1732 | The universal unique identifier (UUID) type is not supported. | RPC_S_UNSUPPORTED_TYPE
1733 | The tag is invalid. | RPC_S_INVALID_TAG
1734 | The array bounds are invalid. | RPC_S_INVALID_BOUND
1735 | The binding does not contain an entry name. | RPC_S_NO_ENTRY_NAME
1736 | The name syntax is invalid. | RPC_S_INVALID_NAME_SYNTAX
1737 | The name syntax is not supported. | RPC_S_UNSUPPORTED_NAME_SYNTAX
1739 | No network address is available to use to construct a universal unique identifier (UUID). | RPC_S_UUID_NO_ADDRESS
1740 | The endpoint is a duplicate. | RPC_S_DUPLICATE_ENDPOINT
1741 | The authentication type is unknown. | RPC_S_UNKNOWN_AUTHN_TYPE
1742 | The maximum number of calls is too small. | RPC_S_MAX_CALLS_TOO_SMALL
1743 | The string is too long. | RPC_S_STRING_TOO_LONG
1744 | The RPC protocol sequence was not found. | RPC_S_PROTSEQ_NOT_FOUND
1745 | The procedure number is out of range. | RPC_S_PROCNUM_OUT_OF_RANGE
1746 | The binding does not contain any authentication information. | RPC_S_BINDING_HAS_NO_AUTH
1747 | The authentication service is unknown. | RPC_S_UNKNOWN_AUTHN_SERVICE
1748 | The authentication level is unknown. | RPC_S_UNKNOWN_AUTHN_LEVEL
1749 | The security context is invalid. | RPC_S_INVALID_AUTH_IDENTITY
1750 | The authorization service is unknown. | RPC_S_UNKNOWN_AUTHZ_SERVICE
1751 | The entry is invalid. | EPT_S_INVALID_ENTRY
1752 | The server endpoint cannot perform the operation. | EPT_S_CANT_PERFORM_OP
1753 | There are no more endpoints available from the endpoint mapper. | EPT_S_NOT_REGISTERED
1754 | No interfaces have been exported. | RPC_S_NOTHING_TO_EXPORT
1755 | The entry name is incomplete. | RPC_S_INCOMPLETE_NAME
1756 | The version option is invalid. | RPC_S_INVALID_VERS_OPTION
1757 | There are no more members. | RPC_S_NO_MORE_MEMBERS
1758 | There is nothing to unexport. | RPC_S_NOT_ALL_OBJS_UNEXPORTED
1759 | The interface was not found. | RPC_S_INTERFACE_NOT_FOUND
1760 | The entry already exists. | RPC_S_ENTRY_ALREADY_EXISTS
1761 | The entry is not found. | RPC_S_ENTRY_NOT_FOUND
1762 | The name service is unavailable. | RPC_S_NAME_SERVICE_UNAVAILABLE
1763 | The network address family is invalid. | RPC_S_INVALID_NAF_ID
1764 | The requested operation is not supported. | RPC_S_CANNOT_SUPPORT
1765 | No security context is available to allow impersonation. | RPC_S_NO_CONTEXT_AVAILABLE
1766 | An internal error occurred in a remote procedure call (RPC). | RPC_S_INTERNAL_ERROR
1767 | The RPC server attempted an integer division by zero. | RPC_S_ZERO_DIVIDE
1768 | An addressing error occurred in the RPC server. | RPC_S_ADDRESS_ERROR
1769 | A floating-point operation at the RPC server caused a division by zero. | RPC_S_FP_DIV_ZERO
1770 | A floating-point underflow occurred at the RPC server. | RPC_S_FP_UNDERFLOW
1771 | A floating-point overflow occurred at the RPC server. | RPC_S_FP_OVERFLOW
1772 | The list of RPC servers available for the binding of auto handles has been exhausted. | RPC_X_NO_MORE_ENTRIES
1773 | Unable to open the character translation table file. | RPC_X_SS_CHAR_TRANS_OPEN_FAIL
1774 | The file containing the character translation table has fewer than 512 bytes. | RPC_X_SS_CHAR_TRANS_SHORT_FILE
1775 | A null context handle was passed from the client to the host during a remote procedure call. | RPC_X_SS_IN_NULL_CONTEXT
1777 | The context handle changed during a remote procedure call. | RPC_X_SS_CONTEXT_DAMAGED
1778 | The binding handles passed to a remote procedure call do not match. | RPC_X_SS_HANDLES_MISMATCH
1779 | The stub is unable to get the remote procedure call handle. | RPC_X_SS_CANNOT_GET_CALL_HANDLE
1780 | A null reference pointer was passed to the stub. | RPC_X_NULL_REF_POINTER
1781 | The enumeration value is out of range. | RPC_X_ENUM_VALUE_OUT_OF_RANGE
1782 | The byte count is too small. | RPC_X_BYTE_COUNT_TOO_SMALL
1783 | The stub received bad data. | RPC_X_BAD_STUB_DATA
1784 | The supplied user buffer is not valid for the requested operation. | ERROR_INVALID_USER_BUFFER
1785 | The disk media is not recognized. It may not be formatted. | ERROR_UNRECOGNIZED_MEDIA
1786 | The workstation does not have a trust secret. | ERROR_NO_TRUST_LSA_SECRET
1787 | The SAM database on the Windows NT Server does not have a computer account for this workstation trust relationship. | ERROR_NO_TRUST_SAM_ACCOUNT
1788 | The trust relationship between the primary domain and the trusted domain failed. | ERROR_TRUSTED_DOMAIN_FAILURE
1789 | The trust relationship between this workstation and the primary domain failed. | ERROR_TRUSTED_RELATIONSHIP_FAILURE
1790 | The network logon failed. | ERROR_TRUST_FAILURE
1791 | A remote procedure call is already in progress for this thread. | RPC_S_CALL_IN_PROGRESS
1792 | An attempt was made to logon, but the network logon service was not started. | ERROR_NETLOGON_NOT_STARTED
1793 | The user's account has expired. | ERROR_ACCOUNT_EXPIRED
1794 | The redirector is in use and cannot be unloaded. | ERROR_REDIRECTOR_HAS_OPEN_HANDLES
1795 | The specified printer driver is already installed. | ERROR_PRINTER_DRIVER_ALREADY_INSTALLED
1796 | The specified port is unknown. | ERROR_UNKNOWN_PORT
1797 | The printer driver is unknown. | ERROR_UNKNOWN_PRINTER_DRIVER
1798 | The print processor is unknown. | ERROR_UNKNOWN_PRINTPROCESSOR
1799 | The specified separator file is invalid. | ERROR_INVALID_SEPARATOR_FILE
1800 | The specified priority is invalid. | ERROR_INVALID_PRIORITY
1801 | The printer name is invalid. | ERROR_INVALID_PRINTER_NAME
1802 | The printer already exists. | ERROR_PRINTER_ALREADY_EXISTS
1803 | The printer command is invalid. | ERROR_INVALID_PRINTER_COMMAND
1804 | The specified data type is invalid. | ERROR_INVALID_DATATYPE
1805 | The environment specified is invalid. | ERROR_INVALID_ENVIRONMENT
1806 | There are no more bindings. | RPC_S_NO_MORE_BINDINGS
1807 | The account used is an interdomain trust account. Use your global user account or local user account to access this server. | ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT
1808 | The account used is a computer account. Use your global user account or local user account to access this server. | ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT
1809 | The account used is a server trust account. Use your global user account or local user account to access this server. | ERROR_NOLOGON_SERVER_TRUST_ACCOUNT
1810 | The name or security identifier (SID) of the domain specified is inconsistent with the trust information for that domain. | ERROR_DOMAIN_TRUST_INCONSISTENT
1811 | The server is in use and cannot be unloaded. | ERROR_SERVER_HAS_OPEN_HANDLES
1812 | The specified image file did not contain a resource section. | ERROR_RESOURCE_DATA_NOT_FOUND
1813 | The specified resource type cannot be found in the image file. | ERROR_RESOURCE_TYPE_NOT_FOUND
1814 | The specified resource name cannot be found in the image file. | ERROR_RESOURCE_NAME_NOT_FOUND
1815 | The specified resource language identifier cannot be found in the image file. | ERROR_RESOURCE_LANG_NOT_FOUND
1816 | Not enough quota is available to process this command. | ERROR_NOT_ENOUGH_QUOTA
1817 | No interfaces have been registered. | RPC_S_NO_INTERFACES
1818 | The server was altered while processing this call. | RPC_S_CALL_CANCELLED
1819 | The binding handle does not contain all required information. | RPC_S_BINDING_INCOMPLETE
1820 | Communications failure. | RPC_S_COMM_FAILURE
1821 | The requested authentication level is not supported. | RPC_S_UNSUPPORTED_AUTHN_LEVEL
1822 | No principal name registered. | RPC_S_NO_PRINC_NAME
1823 | The error specified is not a valid Windows NT RPC error value. | RPC_S_NOT_RPC_ERROR
1824 | A UUID that is valid only on this computer has been allocated. | RPC_S_UUID_LOCAL_ONLY
1825 | A security package specific error occurred. | RPC_S_SEC_PKG_ERROR
1826 | Thread is not canceled. | RPC_S_NOT_CANCELLED
1827 | Invalid operation on the encoding/decoding handle. | RPC_X_INVALID_ES_ACTION
1828 | Incompatible version of the serializing package. | RPC_X_WRONG_ES_VERSION
1829 | Incompatible version of the RPC stub. | RPC_X_WRONG_STUB_VERSION
1830 | The idl pipe object is invalid or corrupted. | RPC_X_INVALID_PIPE_OBJECT
1831 | The operation is invalid for a given idl pipe object. | RPC_X_INVALID_PIPE_OPERATION
1832 | The IDL pipe version is not supported. | RPC_X_WRONG_PIPE_VERSION
1898 | The group member was not found. | RPC_S_GROUP_MEMBER_NOT_FOUND
1899 | The endpoint mapper database could not be created. | EPT_S_CANT_CREATE
1900 | The object UUID is the nil UUID. | RPC_S_INVALID_OBJECT
1901 | The specified time is invalid. | ERROR_INVALID_TIME
1902 | The specified form name is invalid. | ERROR_INVALID_FORM_NAME
1903 | The specified form size is invalid. | ERROR_INVALID_FORM_SIZE
1904 | The specified printer handle is already being waited on | ERROR_ALREADY_WAITING
1905 | The specified printer has been deleted. | ERROR_PRINTER_DELETED
1906 | The state of the printer is invalid. | ERROR_INVALID_PRINTER_STATE
1907 | The user must change his password before he logs on the first time. | ERROR_PASSWORD_MUST_CHANGE
1908 | Could not find the domain controller for this domain. | ERROR_DOMAIN_CONTROLLER_NOT_FOUND
1909 | The referenced account is currently locked out and may not be logged on to. | ERROR_ACCOUNT_LOCKED_OUT
1910 | The object exporter specified was not found. | OR_INVALID_OXID
1911 | The object specified was not found. | OR_INVALID_OID
1912 | The object resolver set specified was not found. | OR_INVALID_SET
1913 | Some data remains to be sent in the request buffer. | RPC_S_SEND_INCOMPLETE
2000 | The pixel format is invalid. | ERROR_INVALID_PIXEL_FORMAT
2001 | The specified driver is invalid. | ERROR_BAD_DRIVER
2002 | The window style or class attribute is invalid for this operation. | ERROR_INVALID_WINDOW_STYLE
2003 | The requested metafile operation is not supported. | ERROR_METAFILE_NOT_SUPPORTED
2004 | The requested transformation operation is not supported. | ERROR_TRANSFORM_NOT_SUPPORTED
2005 | The requested clipping operation is not supported. | ERROR_CLIPPING_NOT_SUPPORTED
2202 | The specified user name is invalid. | ERROR_BAD_USERNAME
2250 | This network connection does not exist. | ERROR_NOT_CONNECTED
2401 | This network connection has files open or requests pending. | ERROR_OPEN_FILES
2402 | Active connections still exist. | ERROR_ACTIVE_CONNECTIONS
2404 | The device is in use by an active process and cannot be disconnected. | ERROR_DEVICE_IN_USE
3000 | The specified print monitor is unknown. | ERROR_UNKNOWN_PRINT_MONITOR
3001 | The specified printer driver is currently in use. | ERROR_PRINTER_DRIVER_IN_USE
3002 | The spool file was not found. | ERROR_SPOOL_FILE_NOT_FOUND
3003 | A StartDocPrinter call was not issued. | ERROR_SPL_NO_STARTDOC
3004 | An AddJob call was not issued. | ERROR_SPL_NO_ADDJOB
3005 | The specified print processor has already been installed. | ERROR_PRINT_PROCESSOR_ALREADY_INSTALLED
3006 | The specified print monitor has already been installed. | ERROR_PRINT_MONITOR_ALREADY_INSTALLED
3007 | The specified print monitor does not have the required functions. | ERROR_INVALID_PRINT_MONITOR
3008 | The specified print monitor is currently in use. | ERROR_PRINT_MONITOR_IN_USE
3009 | The requested operation is not allowed when there are jobs queued to the printer. | ERROR_PRINTER_HAS_JOBS_QUEUED
3010 | The requested operation is successful. Changes will not be effective until the system is rebooted. | ERROR_SUCCESS_REBOOT_REQUIRED
3011 | The requested operation is successful. Changes will not be effective until the service is restarted. | ERROR_SUCCESS_RESTART_REQUIRED
4000 | WINS encountered an error while processing the command. | ERROR_WINS_INTERNAL
4001 | The local WINS can not be deleted. | ERROR_CAN_NOT_DEL_LOCAL_WINS
4002 | The importation from the file failed. | ERROR_STATIC_INIT
4003 | The backup failed. Was a full backup done before? | ERROR_INC_BACKUP
4004 | The backup failed. Check the directory to which you are backing the database. | ERROR_FULL_BACKUP
4005 | The name does not exist in the WINS database. | ERROR_REC_NON_EXISTENT
4006 | Replication with a nonconfigured partner is not allowed. | ERROR_RPL_NOT_ALLOWED
6118 | The list of servers for this workgroup is not currently available. | ERROR_NO_BROWSER_SERVERS_FOUND


Net Errors - Alphabetical Order

The following table shows possible network error values.

Name
Description
Code
NERR_AccountExpired | This user account has expired. | 2239
NERR_AccountUndefined | This user account is undefined. | 2238
NERR_AcctLimitExceeded | A user's session with this server has been deleted because the user's logon hours are no longer valid. | 2434
NERR_ACFFileIOFail | A disk I/O failure occurred. | 2229
NERR_ACFNoParent | The parent directory could not be located. | 2232
NERR_ACFNoRoom | There are too many names in the user accounts database. | 2228
NERR_ACFNotFound | The security database could not be found. | 2219
NERR_ACFNotLoaded | The security database has not been started. | 2227
NERR_ACFTooManyLists | The limit of 64 entries per resource was exceeded. | 2230
NERR_ActiveConns | Active connections still exist. | 2402
NERR_AddForwarded | This message alias has been added but is still forwarded. | 2275
NERR_AlertExists | The specified client is already registered for the specified event. | 2430
NERR_AlreadyExists | This message alias already exists locally. | 2276
NERR_AlreadyForwarded | This message alias has already been forwarded. | 2274
NERR_AlreadyLoggedOn | This workstation is already logged on to the local-area network. | 2200
NERR_BadAsgType | This asg_type is invalid. | 2251
NERR_BadComponent | This path component is invalid. | 2356
NERR_BadControlRecv | The service control dispatcher pipe read failed. | 2193
NERR_BadDest | The destination path is illegal. | 2382
NERR_BadDev | The requested device is invalid. | 2341
NERR_BadDevString | This list of devices is invalid. | 2340
NERR_BadDosFunction | The program below called an unsupported MS-DOS function. | 2502
NERR_BadDosRetCode | The program below returned an MS-DOS error code. | 2500
NERR_BadEventName | The event name is invalid. | 2143
NERR_BadFileCheckSum | The file below is corrupt. | 2504
NERR_BadPassword | The password parameter is invalid. | 2203
NERR_BadPasswordCore | This share name or password is invalid. | 2403
NERR_BadQueueDevString | This device name list is invalid. | 2334
NERR_BadQueuePriority | The queue priority is invalid. | 2335
NERR_BadReceive | The message was sent but not received. | 2282
NERR_BadRecipient | The alert recipient is invalid. | 2433
NERR_BadServiceName | The service name is invalid. | 2185
NERR_BadServiceProgName | The configuration file contains an invalid service program name. | 2188
NERR_BadSource | The source path is illegal. | 2381
NERR_BadTransactConfig | The server is not configured for transactions. | 2141
NERR_BadUasConfig | The user accounts database is not configured correctly. | 2450
NERR_BadUsername | The user name or group name parameter is invalid. | 2202
NERR_BrowserConfiguredToNotRun | The browser service was configured with MaintainServerList=No. | 2550
NERR_BrowserNotStarted | The requested information is not available. | 2139
NERR_BrowserTableIncomplete | The information in the list of servers may be incorrect. | 2319
NERR_BufTooSmall | The API return buffer is too small. | 2123
NERR_CallingRplSrvr | Connecting to the Remoteboot server. | 2515
NERR_CanNotGrowSegment | Unable to add to the security database session cache segment. | 2233
NERR_CanNotGrowUASFile | Unable to add to the user accounts database. | 2456
NERR_CantConnectRplSrvr | Cannot connect to the Remoteboot server. | 2513
NERR_CantOpenImageFile | Cannot open image file on the Remoteboot server. | 2514
NERR_CantType | Could not determine the type of input. | 2357
NERR_CfgCompNotFound | The specified component could not be found in the configuration information. | 2146
NERR_CfgParamNotFound | The specified parameter could not be found in the configuration information. | 2147
NERR_ClientNameNotFound | A session does not exist with that computer name. | 2312
NERR_CommDevInUse | This device is already in use as a communication device. | 2343
NERR_DatabaseUpToDate | No updates are necessary to this replicant network/local security database. | 2248
NERR_DataTypeInvalid | The data type is not supported by the print processor. | 2167
NERR_DCNotFound | Could not find domain controller for this domain. | 243
NERR_DelComputerName | The computer name could not be deleted. | 2278
NERR_DeleteLater | This message alias will be deleted later. | 2298
NERR_DestExists | The printer destination already exists. | 2153
NERR_DestIdle | This printer destination is idle and cannot accept control operations. | 2158
NERR_DestInvalidOp | This printer destination request contains an invalid control function. | 2159
NERR_DestInvalidState | This operation cannot be performed on the print destination in its current state. | 2162
NERR_DestNoRoom | No more printer destinations can be added. | 2157
NERR_DestNotFound | The printer destination cannot be found. | 2152
NERR_DeviceIsShared | This device is currently being shared. | 2252
NERR_DeviceNotShared | This device is not shared. | 2311
NERR_DeviceShareConflict | This device cannot be shared as both a spooled and a nonspooled resource. | 2318
NERR_DevInUse | The device is being accessed by an active process. | 2404
NERR_DevInvalidOpCode | The operation is invalid for this device. | 2331
NERR_DevNotFound | This device cannot be shared. | 2332
NERR_DevNotOpen | This device was not open. | 2333
NERR_DevNotRedirected | The device is not connected. | 2107
NERR_DfsAlreadyShared | The server share specified is already shared in the Distributed File System (Dfs). | 2664
NERR_DfsBadRenamePath | The specified rename target path is invalid. | 2671
NERR_DfsCantCreateJunctionPoint | Unable to create a junction point. | 2669
NERR_DfsCyclicalName | A cycle in the Dfs name was detected. | 2674
NERR_DfsInternalCorruption | The internal database maintained by the Dfs service is corrupt. | 2660
NERR_DfsInternalError | Dfs internal error. | 2690
NERR_DfsLeafVolume | The operation is not valid on a leaf volume. | 2667
NERR_DfsNoSuchServer | The specified server is not a server for this volume. | 2673
NERR_DfsNoSuchShare | The indicated server share does not support the indicated Dfs volume. | 2665
NERR_DfsNoSuchVolume | There is no volume whose entry path matches the input entry path. | 2662
NERR_DfsNotALeafVolume | The operation is not valid on a non-leaf volume. | 2666
NERR_DfsNotSupportedInServerDfs | The operation is not supported on a server-based Dfs. | 2675
NERR_DfsServerNotDfsAware | The server is not Dfs Aware. | 2670
NERR_DfsVolumeAlreadyExists | A volume with the given name already exists. | 2663
NERR_DfsVolumeDataCorrupt | One of the records in the internal Dfs database is corrupt. | 2661
NERR_DfsVolumeHasMultipleServers | The operation is ambiguous because the volume has multiple servers. | 2668
NERR_DfsVolumeIsOffline | The specified Dfs volume is offline. | 2672
NERR_DifferentServers | The source and destination paths are on different servers. | 2383
NERR_DriverNotFound | The device driver does not exist. | 2166
NERR_DuplicateName | A duplicate message alias exists on the network. | 2297
NERR_DuplicateShare | The name has already been shared. | 2118
NERR_DupNameReboot | The computer name already exists on the network. Change it and restart the computer. | 2144
NERR_ErrCommRunSrv | An error occurred when communicating with a Run server. | 2389
NERR_ErrorExecingGhost | An error occurred when starting a background process. | 2391
NERR_ExecFailure | A failure occurred when executing a remote administration command. | 2315
NERR_FileIdNotFound | There is not an open file with that identification number. | 2314
NERR_GroupExists | The group already exists. | 2223
NERR_GroupNotFound | The group name could not be found. | 2220
NERR_GrpMsgProcessor | An error occurred in the domain message processor. | 2280
NERR_ImageParamErr | Image parameter substitution failed. | 2508
NERR_IncompleteDel | The message alias was not successfully deleted from all networks. | 2299
NERR_InternalError | An internal Windows NT error occurred. | 2140
NERR_InUseBySpooler | This device is already in use by the spooler. | 2342
NERR_InvalidAPI | The requested API is not supported on the remote server. | 2142
NERR_InvalidComputer | This computer name is invalid. | 2351
NERR_InvalidDatabase | The security database is corrupted. | 2247
NERR_InvalidDevice | This is an invalid device name. | 2294
NERR_InvalidLana | The LAN adapter number is invalid. | 2400
NERR_InvalidLogonHours | The user is not allowed to log on at this time. | 2241
NERR_InvalidLogSeek | The log file does not contain the requested record number. | 2440
NERR_InvalidMaxUsers | The Peer service supports only two simultaneous users. | 2122
NERR_InvalidUASOp | This operation is not permitted when the Netlogon service is running. | 2451
NERR_InvalidWorkstation | The user is not allowed to log on from this workstation. | 2240
NERR_IsDfsShare | The share must be removed from the Dfs before it can be deleted. | 2321
NERR_ItemNotFound | The queue is empty. | 2115
NERR_JobInvalidState | This operation cannot be performed on the print job in its current state. | 2164
NERR_JobNoRoom | No more print jobs can be added. | 2156
NERR_JobNotFound | The print job does not exist. | 2151
NERR_LanmanIniError | An error occurred when opening or reading the configuration file. | 2131
NERR_LastAdmin | This operation is not allowed on the last administrative account. | 242
NERR_LineTooLong | A line in the configuration file is too long. | 2149
NERR_LocalDrive | The drive letter is in use locally. | 2405
NERR_LocalForward | Messages cannot be forwarded back to the same workstation. | 2279
NERR_LogFileChanged | This log file has changed between reads. | 2378
NERR_LogFileCorrupt | Log file %1 is corrupt. | 2379
NERR_LogonDomainExists | There is already a logon domain for this computer. | 2216
NERR_LogonNoUserPath | The server is configured without a valid user path. | 2211
NERR_LogonScriptError | An error occurred while loading or running the logon script. | 2212
NERR_LogonServerConflict | A centralized logon-server conflict occurred. | 2210
NERR_LogonServerNotFound | The logon server could not be found. | 2215
NERR_LogonsPaused | Network logons are paused. | 2209
NERR_LogonTrackingError | Could not set logon information for this user. | 2454
NERR_LogOverflow | Log file %1 is full. | 2377
NERR_MaxLenExceeded | The specified string and prefix are too long. | 2354
NERR_MsgAlreadyStarted | The Messenger service is already started. | 2271
NERR_MsgInitFailed | The Messenger service failed to start. | 2272
NERR_MsgNotStarted | The Messenger service has not been started. | 2284
NERR_MultipleNets | This operation is not supported on computers with multiple networks. | 2300
NERR_NameInUse | The message alias is currently in use. Try again later. | 2283
NERR_NameNotForwarded | Messages for this alias are not currently being forwarded. | 2288
NERR_NameNotFound | The message alias could not be found on the network. | 2273
NERR_NetlogonNotStarted | The Netlogon service has not been started. | 2455
NERR_NetNameNotFound | This shared resource does not exist. | 2310
NERR_NetNotStarted | The workstation driver is not installed. | 2102
NERR_NetworkError | A general network error occurred. | 2136
NERR_NoAlternateServers | There are no alternate servers registered on this server. | 2467
NERR_NoCommDevs | There are no shared communication devices. | 2337
NERR_NoComputerName | The computer name could not be added as a message alias. The name may already exist on the network. | 2270
NERR_NoForwardName | The forwarded message alias could not be found on the network. | 2286
NERR_NonDosFloppyUsed | The image was not generated from an MS-DOS diskette formatted with /S. | 2510
NERR_NoNetworkResource | A network resource shortage occurred. | 2155
NERR_NonValidatedLogon | The logon server could not validate the logon. | 2217
NERR_NoRoom | The server is currently out of the requested resource. | 2119
NERR_NoRplBootSystem | No loader is specified in the boot-block definition file. | 2505
NERR_NoSuchAlert | An invalid or nonexistent alert name was raised. | 2432
NERR_NoSuchConnection | The connection identification does not specify a valid connection. | 2462
NERR_NoSuchServer | The server identification does not specify a valid server. | 2460
NERR_NoSuchSession | The session identification does not specify a valid session. | 2461
NERR_NotInCache | This user is not cached in user accounts database session cache. | 2235
NERR_NotInDispatchTbl | The service control dispatcher could not find the service name in the dispatch table. | 2192
NERR_NotLocalDomain | The computer is not active in this domain. | 2320
NERR_NotLocalName | The name is not on the local computer. | 2285
NERR_NotLoggedOn | The workstation is not logged on to the local-area network. | 2201
NERR_NotPrimary | This operation is only allowed on the primary domain controller of the domain. | 2226
NERR_OpenFiles | There are open files on the connection. | 2401
NERR_PasswordCantChange | The password of this user cannot change. | 2243
NERR_PasswordExpired | The password of this user has expired. | 2242
NERR_PasswordHistConflict | This password cannot be used now. | 2244
NERR_PasswordMismatch | A password mismatch has been detected. | 2458
NERR_PasswordTooRecent | The password of this user is too recent to change. | 2246
NERR_PasswordTooShort | The password is shorter than required. | 2245
NERR_PausedRemote | The message was sent | 2281
NERR_ProcNoRespond | The print processor is not responding. | 2160
NERR_ProcNotFound | The print processor is not installed. | 2168
NERR_ProfileCleanup | The system cannot delete current connections to network resources. | 2372
NERR_ProfileFileTooBig | Profile files cannot exceed 64 KB. | 2370
NERR_ProfileLoadErr | An error occurred while loading the profile file. | 2374
NERR_ProfileOffset | The start offset is out of range. | 2371
NERR_ProfileSaveErr | Errors occurred while saving the profile file. The profile was partially saved. | 2375
NERR_ProfileUnknownCmd | The system was unable to parse the command line in this file. | 2373
NERR_ProgNeedsExtraMem | The program below needs more memory. | 2501
NERR_QExists | The printer queue already exists. | 2154
NERR_QInvalidState | This operation cannot be performed on the printer queue in its current state. | 2163
NERR_QNoRoom | No more printers can be added. | 2155
NERR_QNotFound | The printer does not exist. | 2150
NERR_QueueNotFound | The queue you specified does not exist. | 2338
NERR_RedirectedPath | The operation is invalid on a redirected resource. | 2117
NERR_RemoteBootFailed | The workstation failed to boot. | 2503
NERR_RemoteErr | A remote API error occurred. | 2127
NERR_RemoteFull | The message alias table on the remote station is full. | 2287
NERR_RemoteOnly | This operation is not supported on workstations. | 2106
NERR_ResourceExists | The resource permission list already exists. | 2225
NERR_ResourceNotFound | The resource name could not be found. | 2222
NERR_RPL_CONNECTED | A second connection to a Remoteboot resource is not allowed. | 2519
NERR_RplAdapterInfoCorrupted | Adapter id record information has been corrupted. | 2625
NERR_RplAdapterNameUnavailable | Chosen network adapter id is in use by some other workstation. | 2633
NERR_RplAdapterNotFound | Adapter record was not found. | 2637
NERR_RplBackupDatabase | Service failed to backup Remoteboot database. | 2636
NERR_RplBadDatabase | Service failed to start because its database is absent or corrupt. | 262
NERR_RplBadRegistry | Service failed to start due to bad startup information in the registry. | 2611
NERR_RplBootInfoCorrupted | Boot block record information has been corrupted. | 2628
NERR_RplBootInUse | There are workstations. | 2635
NERR_RplBootNameUnavailable | The boot name or vendor identifier is in use by some other boot block record. | 2640
NERR_RplBootNotFound | Boot block record was not found. | 2631
NERR_RplBootRestart | Remote boot will be restarted later. | 2511
NERR_RplBootServiceTerm | Remote boot service was stopped; check the error log for the cause of the problem. | 2517
NERR_RplBootStartFailed | Remote boot startup failed; check the error log for the cause of the problem. | 2518
NERR_RplCannotEnum | Cannot enumerate service records. | 2615
NERR_RplConfigInfoCorrupted | Configuration record information has been corrupted. | 2623
NERR_RplConfigNameUnavailable | Configuration name is in use by some other configuration. | 2641
NERR_RplConfigNotEmpty | There are profiles using this configuration. | 2634
NERR_RplConfigNotFound | Configuration record was not found. | 2624
NERR_RplIncompatibleProfile | Chosen profile is incompatible with this workstation. | 2632
NERR_RplInternal | An internal service error has occurred. | 2626
NERR_RplLoadrDiskErr | A disk I/O error occurred. | 2507
NERR_RplLoadrNetBiosErr | NetBIOS returned an error—the NCB and SMB are dumped above. | 2506
NERR_RplNeedsRPLUSERAcct | The RPLUSER local group could not be found. | 2630
NERR_RplNoAdaptersStarted | Service failed to start since none of the network adapters started with this service. | 2610
NERR_RplNotRplServer | Service failed to start because RPLUSER group is absent. | 2614
NERR_RplProfileInfoCorrupted | Profile record information has been corrupted. | 2619
NERR_RplProfileNameUnavailable | Profile name is in use by some other profile. | 2621
NERR_RplProfileNotEmpty | There are workstations using this profile. | 2622
NERR_RplProfileNotFound | Profile record was not found. | 2620
NERR_RplRplfilesShare | Service failed to start because RPLFILES share is absent. | 2613
NERR_RplSrvrCallFailed | The call to the Remoteboot server failed. | 2512
NERR_RplVendorInfoCorrupted | Vendor id record information has been corrupted. | 2627
NERR_RplVendorNameUnavailable | Vendor name is in use by some other vendor record. | 2639
NERR_RplVendorNotFound | Vendor record was not found. | 2638
NERR_RplWkstaInfoCorrupted | Workstation record information has been corrupted. | 2616
NERR_RplWkstaNameUnavailable | Workstation name is in use by some other workstation. | 2618
NERR_RplWkstaNeedsUserAcct | The user account for this workstation record is missing. | 2629
NERR_RplWkstaNotFound | Workstation record was not found. | 2617
NERR_RunSrvPaused | The Run server you requested is paused. | 2385
NERR_ServerNotStarted | The Server service is not started. | 2114
NERR_ServiceCtlBusy | The service control is busy. | 2187
NERR_ServiceCtlNotValid | The requested pause or stop is not valid for this service. | 2191
NERR_ServiceCtlTimeout | The service is not responding to the control function. | 2186
NERR_ServiceEntryLocked | The service does not respond to control actions. | 2183
NERR_ServiceInstalled | The requested service has already been started. | 2182
NERR_ServiceKillProc | The service ended abnormally. | 2190
NERR_ServiceNotCtrl | The service could not be controlled in its present state. | 2189
NERR_ServiceNotInstalled | The service has not been started. | 2184
NERR_ServiceNotStarting | A thread for the new service could not be created. | 2194
NERR_ServiceTableFull | The service table is full. | 2181
NERR_ServiceTableLocked | The service database is locked. | 2180
NERR_ShareMem | An internal error occurred. The network cannot access a shared memory segment. | 2104
NERR_ShareNotFound | The shared resource you are connected to could not be found. | 2392
NERR_SourceIsDir | The source path cannot be a directory. | 2380
NERR_SpeGroupOp | This operation is not allowed on this special group. | 2234
NERR_SpoolerNotLoaded | The spooler is not running. | 2161
NERR_SpoolNoMemory | A spooler memory allocation failure occurred. | 2165
NERR_StandaloneLogon | The logon server was not specified. Your computer will be logged on as STANDALONE. | 2214
NERR_StartingRplBoot | Connecting to the Remoteboot server. | 2516
NERR_SyncRequired | This replicant database is outdated; synchronization is required. | 2249
NERR_TimeDiffAtDC | This server's clock is not synchronized with the primary domain controller's clock. | 2457
NERR_TmpFile | A failure occurred when opening a remote temporary file. | 2316
NERR_TooManyAlerts | The alert table is full. | 2431
NERR_TooManyConnections | The server has reached the maximum number of connections it supports. | 2465
NERR_TooManyEntries | The buffer for types is not big enough. | 2362
NERR_TooManyFiles | The server cannot open more files because it has reached its maximum number. | 2466
NERR_TooManyImageParams | Too many image parameters cross disk sector boundaries. | 2509
NERR_TooManyItems | Requested addition of items exceeds the maximum allowed. | 2121
NERR_TooManyNames | The maximum number of added message aliases has been exceeded. | 2277
NERR_TooManyServers | There is no space for another entry in the table of available servers. | 2463
NERR_TooManySessions | The server has reached the maximum number of sessions it supports. | 2464
NERR_TooMuchData | The data returned from a remote administration command has been truncated to 64 KB. | 2317
NERR_TruncatedBroadcast | The broadcast message was truncated. | 2289
NERR_TryDownLevel | Try the down-level, or remote admin protocol, version of API instead. | 2470
NERR_UnableToAddName_F | The logon processor did not add the message alias. | 2205
NERR_UnableToAddName_W | The logon processor did not add the message alias. | 2204
NERR_UnableToDelName_F | The logoff processor did not delete the message alias. | 2207
NERR_UnableToDelName_W | The logoff processor did not delete the message alias. | 2206
NERR_UnknownDevDir | The device or directory does not exist. | 2116
NERR_UnknownServer | The server could not be located. | 2103
NERR_UPSDriverNotStarted | The uninterruptible power supply (UPS) driver could not be accessed by the UPS service. | 2480
NERR_UPSInvalidCommPort | The UPS service could not access the specified communications port. | 2482
NERR_UPSInvalidConfig | The UPS service is not configured correctly. | 2481
NERR_UPSShutdownFailed | The UPS service failed to perform a system shut down. | 2484
NERR_UPSSignalAsserted | The UPS indicated a line fail or low battery situation. Service not started. | 2483
NERR_UseNotFound | The network connection could not be found. | 2250
NERR_UserExists | The user account already exists. | 2224
NERR_UserInGroup | The user already belongs to this group. | 2236
NERR_UserLogon | Deleting a user with a session is not allowed. | 2231
NERR_UserNotFound | The user name could not be found. | 2221
NERR_UserNotInGroup | The user does not belong to this group. | 2237
NERR_WkstaInconsistentState | The Workstation service is in an inconsistent state. Restart the computer before restarting the Workstation service. | 2137
NERR_WkstaNotStarted | The Workstation service has not been started. | 2138
NERR_WriteFault | A write fault occurred. | 2295


Net Errors - Numerical Order

The following table shows possible network error values.

Code
Description
Name
2102 | The workstation driver is not installed. | NERR_NetNotStarted
2103 | The server could not be located. | NERR_UnknownServer
2104 | An internal error occurred. The network cannot access a shared memory segment. | NERR_ShareMem
2106 | This operation is not supported on workstations. | NERR_RemoteOnly
2107 | The device is not connected. | NERR_DevNotRedirected
2114 | The Server service is not started. | NERR_ServerNotStarted
2115 | The queue is empty. | NERR_ItemNotFound
2116 | The device or directory does not exist. | NERR_UnknownDevDir
2117 | The operation is invalid on a redirected resource. | NERR_RedirectedPath
2118 | The name has already been shared. | NERR_DuplicateShare
2119 | The server is currently out of the requested resource. | NERR_NoRoom
2121 | Requested addition of items exceeds the maximum allowed. | NERR_TooManyItems
2122 | The Peer service supports only two simultaneous users. | NERR_InvalidMaxUsers
2123 | The API return buffer is too small. | NERR_BufTooSmall
2127 | A remote API error occurred. | NERR_RemoteErr
2131 | An error occurred when opening or reading the configuration file. | NERR_LanmanIniError
2136 | A general network error occurred. | NERR_NetworkError
2137 | The Workstation service is in an inconsistent state. Restart the computer before restarting the Workstation service. | NERR_WkstaInconsistentState
2138 | The Workstation service has not been started. | NERR_WkstaNotStarted
2139 | The requested information is not available. | NERR_BrowserNotStarted
2140 | An internal Windows NT error occurred. | NERR_InternalError
2141 | The server is not configured for transactions. | NERR_BadTransactConfig
2142 | The requested API is not supported on the remote server. | NERR_InvalidAPI
2143 | The event name is invalid. | NERR_BadEventName
2144 | The computer name already exists on the network. Change it and restart the computer. | NERR_DupNameReboot
2146 | The specified component could not be found in the configuration information. | NERR_CfgCompNotFound
2147 | The specified parameter could not be found in the configuration information. | NERR_CfgParamNotFound
2149 | A line in the configuration file is too long. | NERR_LineTooLong
2150 | The printer does not exist. | NERR_QNotFound
2151 | The print job does not exist. | NERR_JobNotFound
2152 | The printer destination cannot be found. | NERR_DestNotFound
2153 | The printer destination already exists. | NERR_DestExists
2154 | The printer queue already exists. | NERR_QExists
2155 | A network resource shortage occurred. | NERR_NoNetworkResource
2155 | No more printers can be added. | NERR_QNoRoom
2156 | No more print jobs can be added. | NERR_JobNoRoom
2157 | No more printer destinations can be added. | NERR_DestNoRoom
2158 | This printer destination is idle and cannot accept control operations. | NERR_DestIdle
2159 | This printer destination request contains an invalid control function. | NERR_DestInvalidOp
2160 | The print processor is not responding. | NERR_ProcNoRespond
2161 | The spooler is not running. | NERR_SpoolerNotLoaded
2162 | This operation cannot be performed on the print destination in its current state. | NERR_DestInvalidState
2163 | This operation cannot be performed on the printer queue in its current state. | NERR_QInvalidState
2164 | This operation cannot be performed on the print job in its current state. | NERR_JobInvalidState
2165 | A spooler memory allocation failure occurred. | NERR_SpoolNoMemory
2166 | The device driver does not exist. | NERR_DriverNotFound
2167 | The data type is not supported by the print processor. | NERR_DataTypeInvalid
2168 | The print processor is not installed. | NERR_ProcNotFound
2180 | The service database is locked. | NERR_ServiceTableLocked
2181 | The service table is full. | NERR_ServiceTableFull
2182 | The requested service has already been started. | NERR_ServiceInstalled
2183 | The service does not respond to control actions. | NERR_ServiceEntryLocked
2184 | The service has not been started. | NERR_ServiceNotInstalled
2185 | The service name is invalid. | NERR_BadServiceName
2186 | The service is not responding to the control function. | NERR_ServiceCtlTimeout
2187 | The service control is busy. | NERR_ServiceCtlBusy
2188 | The configuration file contains an invalid service program name. | NERR_BadServiceProgName
2189 | The service could not be controlled in its present state. | NERR_ServiceNotCtrl
2190 | The service ended abnormally. | NERR_ServiceKillProc
2191 | The requested pause or stop is not valid for this service. | NERR_ServiceCtlNotValid
2192 | The service control dispatcher could not find the service name in the dispatch table. | NERR_NotInDispatchTbl
2193 | The service control dispatcher pipe read failed. | NERR_BadControlRecv
2194 | A thread for the new service could not be created. | NERR_ServiceNotStarting
2200 | This workstation is already logged on to the local-area network. | NERR_AlreadyLoggedOn
2201 | The workstation is not logged on to the local-area network. | NERR_NotLoggedOn
2202 | The user name or group name parameter is invalid. | NERR_BadUsername
2203 | The password parameter is invalid. | NERR_BadPassword
2204 | The logon processor did not add the message alias. | NERR_UnableToAddName_W
2205 | The logon processor did not add the message alias. | NERR_UnableToAddName_F
2206 | The logoff processor did not delete the message alias. | NERR_UnableToDelName_W
2207 | The logoff processor did not delete the message alias. | NERR_UnableToDelName_F
2209 | Network logons are paused. | NERR_LogonsPaused
2210 | A centralized logon-server conflict occurred. | NERR_LogonServerConflict
2211 | The server is configured without a valid user path. | NERR_LogonNoUserPath
2212 | An error occurred while loading or running the logon script. | NERR_LogonScriptError
2214 | The logon server was not specified. Your computer will be logged on as STANDALONE. | NERR_StandaloneLogon
2215 | The logon server could not be found. | NERR_LogonServerNotFound
2216 | There is already a logon domain for this computer. | NERR_LogonDomainExists
2217 | The logon server could not validate the logon. | NERR_NonValidatedLogon
2219 | The security database could not be found. | NERR_ACFNotFound
2220 | The group name could not be found. | NERR_GroupNotFound
2221 | The user name could not be found. | NERR_UserNotFound
2222 | The resource name could not be found. | NERR_ResourceNotFound
2223 | The group already exists. | NERR_GroupExists
2224 | The user account already exists. | NERR_UserExists
2225 | The resource permission list already exists. | NERR_ResourceExists
2226 | This operation is only allowed on the primary domain controller of the domain. | NERR_NotPrimary
2227 | The security database has not been started. | NERR_ACFNotLoaded
2228 | There are too many names in the user accounts database. | NERR_ACFNoRoom
2229 | A disk I/O failure occurred. | NERR_ACFFileIOFail
2230 | The limit of 64 entries per resource was exceeded. | NERR_ACFTooManyLists
2231 | Deleting a user with a session is not allowed. | NERR_UserLogon
2232 | The parent directory could not be located. | NERR_ACFNoParent
2233 | Unable to add to the security database session cache segment. | NERR_CanNotGrowSegment
2234 | This operation is not allowed on this special group. | NERR_SpeGroupOp
2235 | This user is not cached in user accounts database session cache. | NERR_NotInCache
2236 | The user already belongs to this group. | NERR_UserInGroup
2237 | The user does not belong to this group. | NERR_UserNotInGroup
2238 | This user account is undefined. | NERR_AccountUndefined
2239 | This user account has expired. | NERR_AccountExpired
2240 | The user is not allowed to log on from this workstation. | NERR_InvalidWorkstation
2241 | The user is not allowed to log on at this time. | NERR_InvalidLogonHours
2242 | The password of this user has expired. | NERR_PasswordExpired
2243 | The password of this user cannot change. | NERR_PasswordCantChange
2244 | This password cannot be used now. | NERR_PasswordHistConflict
2245 | The password is shorter than required. | NERR_PasswordTooShort
2246 | The password of this user is too recent to change. | NERR_PasswordTooRecent
2247 | The security database is corrupted. | NERR_InvalidDatabase
2248 | No updates are necessary to this replicant network/local security database. | NERR_DatabaseUpToDate
2249 | This replicant database is outdated; synchronization is required. | NERR_SyncRequired
2250 | The network connection could not be found. | NERR_UseNotFound
2251 | This asg_type is invalid. | NERR_BadAsgType
2252 | This device is currently being shared. | NERR_DeviceIsShared
2270 | The computer name could not be added as a message alias. The name may already exist on the network. | NERR_NoComputerName
2271 | The Messenger service is already started. | NERR_MsgAlreadyStarted
2272 | The Messenger service failed to start. | NERR_MsgInitFailed
2273 | The message alias could not be found on the network. | NERR_NameNotFound
2274 | This message alias has already been forwarded. | NERR_AlreadyForwarded
2275 | This message alias has been added but is still forwarded. | NERR_AddForwarded
2276 | This message alias already exists locally. | NERR_AlreadyExists
2277 | The maximum number of added message aliases has been exceeded. | NERR_TooManyNames
2278 | The computer name could not be deleted. | NERR_DelComputerName
2279 | Messages cannot be forwarded back to the same workstation. | NERR_LocalForward
2280 | An error occurred in the domain message processor. | NERR_GrpMsgProcessor
2281 | The message was sent. | NERR_PausedRemote
2282 | The message was sent but not received. | NERR_BadReceive
2283 | The message alias is currently in use. Try again later. | NERR_NameInUse
2284 | The Messenger service has not been started. | NERR_MsgNotStarted
2285 | The name is not on the local computer. | NERR_NotLocalName
2286 | The forwarded message alias could not be found on the network. | NERR_NoForwardName
2287 | The message alias table on the remote station is full. | NERR_RemoteFull
2288 | Messages for this alias are not currently being forwarded. | NERR_NameNotForwarded
2289 | The broadcast message was truncated. | NERR_TruncatedBroadcast
2294 | This is an invalid device name. | NERR_InvalidDevice
2295 | A write fault occurred. | NERR_WriteFault
2297 | A duplicate message alias exists on the network. | NERR_DuplicateName
2298 | This message alias will be deleted later. | NERR_DeleteLater
2299 | The message alias was not successfully deleted from all networks. | NERR_IncompleteDel
2300 | This operation is not supported on computers with multiple networks. | NERR_MultipleNets
2310 | This shared resource does not exist. | NERR_NetNameNotFound
2311 | This device is not shared. | NERR_DeviceNotShared
2312 | A session does not exist with that computer name. | NERR_ClientNameNotFound
2314 | There is not an open file with that identification number. | NERR_FileIdNotFound
2315 | A failure occurred when executing a remote administration command. | NERR_ExecFailure
2316 | A failure occurred when opening a remote temporary file. | NERR_TmpFile
2317 | The data returned from a remote administration command has been truncated to 64 KB. | NERR_TooMuchData
2318 | This device cannot be shared as both a spooled and a nonspooled resource. | NERR_DeviceShareConflict
2319 | The information in the list of servers may be incorrect. | NERR_BrowserTableIncomplete
2320 | The computer is not active in this domain. | NERR_NotLocalDomain
2321 | The share must be removed from the Dfs before it can be deleted. | NERR_IsDfsShare
2331 | The operation is invalid for this device. | NERR_DevInvalidOpCode
2332 | This device cannot be shared. | NERR_DevNotFound
2333 | This device was not open. | NERR_DevNotOpen
2334 | This device name list is invalid. | NERR_BadQueueDevString
2335 | The queue priority is invalid. | NERR_BadQueuePriority
2337 | There are no shared communication devices. | NERR_NoCommDevs
2338 | The queue you specified does not exist. | NERR_QueueNotFound
2340 | This list of devices is invalid. | NERR_BadDevString
2341 | The requested device is invalid. | NERR_BadDev
2342 | This device is already in use by the spooler. | NERR_InUseBySpooler
2343 | This device is already in use as a communication device. | NERR_CommDevInUse
2351 | This computer name is invalid. | NERR_InvalidComputer
2354 | The specified string and prefix are too long. | NERR_MaxLenExceeded
2356 | This path component is invalid. | NERR_BadComponent
2357 | Could not determine the type of input. | NERR_CantType
2362 | The buffer for types is not big enough. | NERR_TooManyEntries
2370 | Profile files cannot exceed 64 KB. | NERR_ProfileFileTooBig
2371 | The start offset is out of range. | NERR_ProfileOffset
2372 | The system cannot delete current connections to network resources. | NERR_ProfileCleanup
2373 | The system was unable to parse the command line in this file. | NERR_ProfileUnknownCmd
2374 | An error occurred while loading the profile file. | NERR_ProfileLoadErr
2375 | Errors occurred while saving the profile file. The profile was partially saved. | NERR_ProfileSaveErr
2377 | Log file %1 is full. | NERR_LogOverflow
2378 | This log file has changed between reads. | NERR_LogFileChanged
2379 | Log file %1 is corrupt. | NERR_LogFileCorrupt
2380 | The source path cannot be a directory. | NERR_SourceIsDir
2381 | The source path is illegal. | NERR_BadSource
2382 | The destination path is illegal. | NERR_BadDest
2383 | The source and destination paths are on different servers. | NERR_DifferentServers
2385 | The Run server you requested is paused. | NERR_RunSrvPaused
2389 | An error occurred when communicating with a Run server. | NERR_ErrCommRunSrv
2391 | An error occurred when starting a background process. | NERR_ErrorExecingGhost
2392 | The shared resource you are connected to could not be found. | NERR_ShareNotFound
2400 | The LAN adapter number is invalid. | NERR_InvalidLana
2401 | There are open files on the connection. | NERR_OpenFiles
2402 | Active connections still exist. | NERR_ActiveConns
2403 | This share name or password is invalid. | NERR_BadPasswordCore
2404 | The device is being accessed by an active process. | NERR_DevInUse
2405 | The drive letter is in use locally. | NERR_LocalDrive
2430 | The specified client is already registered for the specified event. | NERR_AlertExists
2431 | The alert table is full. | NERR_TooManyAlerts
2432 | An invalid or nonexistent alert name was raised. | NERR_NoSuchAlert
2433 | The alert recipient is invalid. | NERR_BadRecipient
2434 | A user's session with this server has been deleted because the user's logon hours are no longer valid. | NERR_AcctLimitExceeded
2440 | The log file does not contain the requested record number. | NERR_InvalidLogSeek
2450 | The user accounts database is not configured correctly. | NERR_BadUasConfig
2451 | This operation is not permitted when the Netlogon service is running. | NERR_InvalidUASOp
2452 | This operation is not allowed on the last administrative account. | NERR_LastAdmin
2453 | Could not find domain controller for this domain. | NERR_DCNotFound
2454 | Could not set logon information for this user. | NERR_LogonTrackingError
2455 | The Netlogon service has not been started. | NERR_NetlogonNotStarted
2456 | Unable to add to the user accounts database. | NERR_CanNotGrowUASFile
2457 | This server's clock is not synchronized with the primary domain controller's clock. | NERR_TimeDiffAtDC
2458 | A password mismatch has been detected. | NERR_PasswordMismatch
2460 | The server identification does not specify a valid server. | NERR_NoSuchServer
2461 | The session identification does not specify a valid session. | NERR_NoSuchSession
2462 | The connection identification does not specify a valid connection. | NERR_NoSuchConnection
2463 | There is no space for another entry in the table of available servers. | NERR_TooManyServers
2464 | The server has reached the maximum number of sessions it supports. | NERR_TooManySessions
2465 | The server has reached the maximum number of connections it supports. | NERR_TooManyConnections
2466 | The server cannot open more files because it has reached its maximum number. | NERR_TooManyFiles
2467 | There are no alternate servers registered on this server. | NERR_NoAlternateServers
2470 | Try the down-level, or remote admin protocol, version of API instead. | NERR_TryDownLevel
2480 | The UPS driver could not be accessed by the UPS service. | NERR_UPSDriverNotStarted
2481 | The UPS service is not configured correctly. | NERR_UPSInvalidConfig
2482 | The UPS service could not access the specified communications port. | NERR_UPSInvalidCommPort
2483 | The UPS indicated a line fail or low battery situation. Service not started. | NERR_UPSSignalAsserted
2484 | The UPS service failed to perform a system shut down. | NERR_UPSShutdownFailed
2500 | The program below returned an MS-DOS error code. | NERR_BadDosRetCode
2501 | The program below needs more memory. | NERR_ProgNeedsExtraMem
2502 | The program below called an unsupported MS-DOS function. | NERR_BadDosFunction
2503 | The workstation failed to boot. | NERR_RemoteBootFailed
2504 | The file below is corrupt. | NERR_BadFileCheckSum
2505 | No loader is specified in the boot-block definition file. | NERR_NoRplBootSystem
2506 | NetBIOS returned an error—the NCB and SMB are dumped above. | NERR_RplLoadrNetBiosErr
2507 | A disk I/O error occurred. | NERR_RplLoadrDiskErr
2508 | Image parameter substitution failed. | NERR_ImageParamErr
2509 | Too many image parameters cross disk sector boundaries. | NERR_TooManyImageParams
2510 | The image was not generated from an MS-DOS diskette formatted with /S. | NERR_NonDosFloppyUsed
2511 | Remote boot will be restarted later. | NERR_RplBootRestart
2512 | The call to the Remoteboot server failed. | NERR_RplSrvrCallFailed
2513 | Cannot connect to the Remoteboot server. | NERR_CantConnectRplSrvr
2514 | Cannot open image file on the Remoteboot server. | NERR_CantOpenImageFile
2515 | Connecting to the Remoteboot server. | NERR_CallingRplSrvr
2516 | Connecting to the Remoteboot server. | NERR_StartingRplBoot
2517 | Remote boot service was stopped; check the error log for the cause of the problem. | NERR_RplBootServiceTerm
2518 | Remote boot startup failed; check the error log for the cause of the problem. | NERR_RplBootStartFailed
2519 | A second connection to a Remoteboot resource is not allowed. | NERR_RPL_CONNECTED
2550 | The browser service was configured with MaintainServerList=No. | NERR_BrowserConfiguredToNotRun
2610 | Service failed to start since none of the network adapters started with this service. | NERR_RplNoAdaptersStarted
2611 | Service failed to start due to bad startup information in the registry. | NERR_RplBadRegistry
2612 | Service failed to start because its database is absent or corrupt. | NERR_RplBadDatabase
2613 | Service failed to start because RPLFILES share is absent. | NERR_RplRplfilesShare
2614 | Service failed to start because RPLUSER group is absent. | NERR_RplNotRplServer
2615 | Cannot enumerate service records. | NERR_RplCannotEnum
2616 | Workstation record information has been corrupted. | NERR_RplWkstaInfoCorrupted
2617 | Workstation record was not found. | NERR_RplWkstaNotFound
2618 | Workstation name is in use by some other workstation. | NERR_RplWkstaNameUnavailable
2619 | Profile record information has been corrupted. | NERR_RplProfileInfoCorrupted
2620 | Profile record was not found. | NERR_RplProfileNotFound
2621 | Profile name is in use by some other profile. | NERR_RplProfileNameUnavailable
2622 | There are workstations using this profile. | NERR_RplProfileNotEmpty
2623 | Configuration record information has been corrupted. | NERR_RplConfigInfoCorrupted
2624 | Configuration record was not found. | NERR_RplConfigNotFound
2625 | Adapter id record information has been corrupted. | NERR_RplAdapterInfoCorrupted
2626 | An internal service error has occurred. | NERR_RplInternal
2627 | Vendor id record information has been corrupted. | NERR_RplVendorInfoCorrupted
2628 | Boot block record information has been corrupted. | NERR_RplBootInfoCorrupted
2629 | The user account for this workstation record is missing. | NERR_RplWkstaNeedsUserAcct
2630 | The RPLUSER local group could not be found. | NERR_RplNeedsRPLUSERAcct
2631 | Boot block record was not found. | NERR_RplBootNotFound
2632 | Chosen profile is incompatible with this workstation. | NERR_RplIncompatibleProfile
2633 | Chosen network adapter id is in use by some other workstation. | NERR_RplAdapterNameUnavailable
2634 | There are profiles using this configuration. | NERR_RplConfigNotEmpty
2635 | There are workstations. | NERR_RplBootInUse
2636 | Service failed to backup Remoteboot database. | NERR_RplBackupDatabase
2637 | Adapter record was not found. | NERR_RplAdapterNotFound
2638 | Vendor record was not found. | NERR_RplVendorNotFound
2639 | Vendor name is in use by some other vendor record. | NERR_RplVendorNameUnavailable
2640 | The boot name or vendor identifier is in use by some other boot block record. | NERR_RplBootNameUnavailable
2641 | Configuration name is in use by some other configuration. | NERR_RplConfigNameUnavailable
2660 | The internal database maintained by the Dfs service is corrupt. | NERR_DfsInternalCorruption
2661 | One of the records in the internal Dfs database is corrupt. | NERR_DfsVolumeDataCorrupt
2662 | There is no volume whose entry path matches the input entry path. | NERR_DfsNoSuchVolume
2663 | A volume with the given name already exists. | NERR_DfsVolumeAlreadyExists
2664 | The server share specified is already shared in the Dfs. | NERR_DfsAlreadyShared
2665 | The indicated server share does not support the indicated Dfs volume. | NERR_DfsNoSuchShare
2666 | The operation is not valid on a non-leaf volume. | NERR_DfsNotALeafVolume
2667 | The operation is not valid on a leaf volume. | NERR_DfsLeafVolume
2668 | The operation is ambiguous because the volume has multiple servers. | NERR_DfsVolumeHasMultipleServers
2669 | Unable to create a junction point. | NERR_DfsCantCreateJunctionPoint
2670 | The server is not Dfs Aware. | NERR_DfsServerNotDfsAware
2671 | The specified rename target path is invalid. | NERR_DfsBadRenamePath
2672 | The specified Dfs volume is offline. | NERR_DfsVolumeIsOffline
2673 | The specified server is not a server for this volume. | NERR_DfsNoSuchServer
2674 | A cycle in the Dfs name was detected. | NERR_DfsCyclicalName
2675 | The operation is not supported on a server-based Dfs. | NERR_DfsNotSupportedInServerDfs
2690 | Dfs internal error. | NERR_DfsInternalError


RAS Error Values

Name
Code
PENDING | RASBASE+0
ERROR_INVALID_PORT_HANDLE | RASBASE+1
ERROR_PORT_ALREADY_OPEN | RASBASE+2
ERROR_BUFFER_TOO_SMALL | RASBASE+3
ERROR_WRONG_INFO_SPECIFIED | RASBASE+4
ERROR_CANNOT_SET_PORT_INFO | RASBASE+5
ERROR_PORT_NOT_CONNECTED | RASBASE+6
ERROR_EVENT_INVALID | RASBASE+7
ERROR_DEVICE_DOES_NOT_EXIST | RASBASE+8
ERROR_DEVICETYPE_DOES_NOT_EXIST | RASBASE+9
ERROR_BUFFER_INVALID | RASBASE+10
ERROR_ROUTE_NOT_AVAILABLE | RASBASE+11
ERROR_ROUTE_NOT_ALLOCATED | RASBASE+12
ERROR_INVALID_COMPRESSION_SPECIFIED | RASBASE+13
ERROR_OUT_OF_BUFFERS | RASBASE+14
ERROR_PORT_NOT_FOUND | RASBASE+15
ERROR_ASYNC_REQUEST_PENDING | RASBASE+16
ERROR_ALREADY_DISCONNECTING | RASBASE+17
ERROR_PORT_NOT_OPEN | RASBASE+18
ERROR_PORT_DISCONNECTED | RASBASE+19
ERROR_NO_ENDPOINTS | RASBASE+20
ERROR_CANNOT_OPEN_PHONEBOOK | RASBASE+21
ERROR_CANNOT_LOAD_PHONEBOOK | RASBASE+22
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | RASBASE+23
ERROR_CANNOT_WRITE_PHONEBOOK | RASBASE+24
ERROR_CORRUPT_PHONEBOOK | RASBASE+25
ERROR_CANNOT_LOAD_STRING | RASBASE+26
ERROR_KEY_NOT_FOUND | RASBASE+27
ERROR_DISCONNECTION | RASBASE+28
ERROR_REMOTE_DISCONNECTION | RASBASE+29
ERROR_HARDWARE_FAILURE | RASBASE+30
ERROR_USER_DISCONNECTION | RASBASE+31
ERROR_INVALID_SIZE | RASBASE+32
ERROR_PORT_NOT_AVAILABLE | RASBASE+33
ERROR_CANNOT_PROJECT_CLIENT | RASBASE+34
ERROR_UNKNOWN | RASBASE+35
ERROR_WRONG_DEVICE_ATTACHED | RASBASE+36
ERROR_BAD_STRING | RASBASE+37
ERROR_REQUEST_TIMEOUT | RASBASE+38
ERROR_CANNOT_GET_LANA | RASBASE+39
ERROR_NETBIOS_ERROR | RASBASE+40
ERROR_SERVER_OUT_OF_RESOURCES | RASBASE+41
ERROR_NAME_EXISTS_ON_NET | RASBASE+42
ERROR_SERVER_GENERAL_NET_FAILURE | RASBASE+43
WARNING_MSG_ALIAS_NOT_ADDED | RASBASE+44
ERROR_AUTH_INTERNAL | RASBASE+45
ERROR_RESTRICTED_LOGON_HOURS | RASBASE+46
ERROR_ACCT_DISABLED | RASBASE+47
ERROR_PASSWD_EXPIRED | RASBASE+48
ERROR_NO_DIALIN_PERMISSION | RASBASE+49
ERROR_SERVER_NOT_RESPONDING | RASBASE+50
ERROR_FROM_DEVICE | RASBASE+51
ERROR_UNRECOGNIZED_RESPONSE | RASBASE+52
ERROR_MACRO_NOT_FOUND | RASBASE+53
ERROR_MACRO_NOT_DEFINED | RASBASE+54
ERROR_MESSAGE_MACRO_NOT_FOUND | RASBASE+55
ERROR_DEFAULTOFF_MACRO_NOT_FOUND | RASBASE+56
ERROR_FILE_COULD_NOT_BE_OPENED | RASBASE+57
ERROR_DEVICENAME_TOO_LONG | RASBASE+58
ERROR_DEVICENAME_NOT_FOUND | RASBASE+59
ERROR_NO_RESPONSES | RASBASE+60
ERROR_NO_COMMAND_FOUND | RASBASE+61
ERROR_WRONG_KEY_SPECIFIED | RASBASE+62
ERROR_UNKNOWN_DEVICE_TYPE | RASBASE+63
ERROR_ALLOCATING_MEMORY | RASBASE+64
ERROR_PORT_NOT_CONFIGURED | RASBASE+65
ERROR_DEVICE_NOT_READY | RASBASE+66
ERROR_READING_INI_FILE | RASBASE+67
ERROR_NO_CONNECTION | RASBASE+68
ERROR_BAD_USAGE_IN_INI_FILE | RASBASE+69
ERROR_READING_SECTIONNAME | RASBASE+70
ERROR_READING_DEVICETYPE | RASBASE+71
ERROR_READING_DEVICENAME | RASBASE+72
ERROR_READING_USAGE | RASBASE+73
ERROR_READING_MAXCONNECTBPS | RASBASE+74
ERROR_READING_MAXCARRIERBPS | RASBASE+75
ERROR_LINE_BUSY | RASBASE+76
ERROR_VOICE_ANSWER | RASBASE+77
ERROR_NO_ANSWER | RASBASE+78
ERROR_NO_CARRIER | RASBASE+79
ERROR_NO_DIALTONE | RASBASE+80
ERROR_IN_COMMAND | RASBASE+81
ERROR_WRITING_SECTIONNAME | RASBASE+82
ERROR_WRITING_DEVICETYPE | RASBASE+83
ERROR_WRITING_DEVICENAME | RASBASE+84
ERROR_WRITING_MAXCONNECTBPS | RASBASE+85
ERROR_WRITING_MAXCARRIERBPS | RASBASE+86
ERROR_WRITING_USAGE | RASBASE+87
ERROR_WRITING_DEFAULTOFF | RASBASE+88
ERROR_READING_DEFAULTOFF | RASBASE+89
ERROR_EMPTY_INI_FILE | RASBASE+90
ERROR_AUTHENTICATION_FAILURE | RASBASE+91
ERROR_PORT_OR_DEVICE | RASBASE+92
ERROR_NOT_BINARY_MACRO | RASBASE+93
ERROR_DCB_NOT_FOUND | RASBASE+94
ERROR_STATE_MACHINES_NOT_STARTED | RASBASE+95
ERROR_STATE_MACHINES_ALREADY_STARTED | RASBASE+96
ERROR_PARTIAL_RESPONSE_LOOPING | RASBASE+97
ERROR_UNKNOWN_RESPONSE_KEY | RASBASE+98
ERROR_RECV_BUF_FULL | RASBASE+99
ERROR_CMD_TOO_LONG | RASBASE+100
ERROR_UNSUPPORTED_BPS | RASBASE+101
ERROR_UNEXPECTED_RESPONSE | RASBASE+102
ERROR_INTERACTIVE_MODE | RASBASE+103
ERROR_BAD_CALLBACK_NUMBER | RASBASE+104
ERROR_INVALID_AUTH_STATE | RASBASE+105
ERROR_WRITING_INITBPS | RASBASE+106
ERROR_X25_DIAGNOSTIC | RASBASE+107
ERROR_ACCT_EXPIRED | RASBASE+108
ERROR_CHANGING_PASSWORD | RASBASE+109
ERROR_OVERRUN | RASBASE+110
ERROR_RASMAN_CANNOT_INITIALIZE | RASBASE+111
ERROR_BIPLEX_PORT_NOT_AVAILABLE | RASBASE+112
ERROR_NO_ACTIVE_ISDN_LINES | RASBASE+113
ERROR_NO_ISDN_CHANNELS_AVAILABLE | RASBASE+114
ERROR_TOO_MANY_LINE_ERRORS | RASBASE+115
ERROR_IP_CONFIGURATION | RASBASE+116
ERROR_NO_IP_ADDRESSES | RASBASE+117
ERROR_PPP_TIMEOUT | RASBASE+118
ERROR_PPP_REMOTE_TERMINATED | RASBASE+119
ERROR_PPP_NO_PROTOCOLS_CONFIGURED | RASBASE+120
ERROR_PPP_NO_RESPONSE | RASBASE+121
ERROR_PPP_INVALID_PACKET | RASBASE+122
ERROR_PHONE_NUMBER_TOO_LONG | RASBASE+123
ERROR_IPXCP_NO_DIALOUT_CONFIGURED | RASBASE+124
ERROR_IPXCP_NO_DIALIN_CONFIGURED | RASBASE+125
ERROR_IPXCP_DIALOUT_ALREADY_ACTIVE | RASBASE+126
ERROR_ACCESSING_TCPCFGDLL | RASBASE+127
ERROR_NO_IP_RAS_ADAPTER | RASBASE+128
ERROR_SLIP_REQUIRES_IP | RASBASE+129
ERROR_PROJECTION_NOT_COMPLETE | RASBASE+130
ERROR_PROTOCOL_NOT_CONFIGURED | RASBASE+131
ERROR_PPP_NOT_CONVERGING | RASBASE+132
ERROR_PPP_CP_REJECTED | RASBASE+133
ERROR_PPP_LCP_TERMINATED | RASBASE+134
ERROR_PPP_REQUIRED_ADDRESS_REJECTED | RASBASE+135
ERROR_PPP_NCP_TERMINATED | RASBASE+136
ERROR_PPP_LOOPBACK_DETECTED | RASBASE+137
ERROR_PPP_NO_ADDRESS_ASSIGNED | RASBASE+138
ERROR_CANNOT_USE_LOGON_CREDENTIALS | RASBASE+139
ERROR_TAPI_CONFIGURATION | RASBASE+140
ERROR_NO_LOCAL_ENCRYPTION | RASBASE+141
ERROR_NO_REMOTE_ENCRYPTION | RASBASE+142
ERROR_REMOTE_REQUIRES_ENCRYPTION | RASBASE+143
ERROR_IPXCP_NET_NUMBER_CONFLICT | RASBASE+144
ERROR_INVALID_SMM | RASBASE+145
ERROR_SMM_UNINITIALIZED | RASBASE+146
ERROR_NO_MAC_FOR_PORT | RASBASE+147
ERROR_SMM_TIMEOUT | RASBASE+148
ERROR_BAD_PHONE_NUMBER | RASBASE+149
ERROR_WRONG_MODULE | RASBASE+150
ERROR_PPP_MAC | RASBASE+151
ERROR_PPP_LCP | RASBASE+152
ERROR_PPP_AUTH | RASBASE+153
ERROR_PPP_NCP | RASBASE+154
ERROR_POWER_OFF | RASBASE+155
ERROR_POWER_OFF_CD | RASBASE+156


Formatting Specifications

Field
Meaning
- Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted, the output is padded to the left, justifying it to the right.
# Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).
0 | Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces.
width | Copy the specified minimum number of characters to the output buffer. The width field is a nonnegative integer. The width specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or if the width field is not present, all characters of the value are printed, subject to the precision specification.
.precision For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument is less than the specified precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is zero or omitted entirely, or if the period (.) appears without a number following it, the precision is set to one (1).

For strings, copy the specified maximum number of characters to the output buffer.
type | Output the corresponding argument as a character, a string, or a number. This field can be any of the character sequences in the following table.

Sequence
Insert
c | A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is interpreted as type WCHAR when the calling application uses the #define UNICODE compile flag and as type CHAR otherwise.
C | A single character. This sequence is interpreted as type CHAR when the calling application uses the #define UNICODE compile flag and as type WCHAR otherwise.
d | A signed decimal integer argument. This sequence is equivalent to the i sequence.
hc, hC | A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type CHAR, even when the calling application uses the #define UNICODE compile flag.
hs, hS | A string. This sequence is always interpreted as type LPSTR, even when the calling application uses the #define UNICODE compile flag.
i | A signed decimal integer. This sequence is equivalent to the d sequence.
lc, lC | A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type WCHAR, even when the calling application does not use the #define UNICODE compile flag.
ld | A long signed decimal integer. This sequence is equivalent to the li sequence.
li | A long signed decimal integer. This sequence is equivalent to the ld sequence.
ls, lS | A string. This sequence is always interpreted as type LPWSTR, even when the calling application does not use the #define UNICODE compile flag. This sequence is equivalent to the ws sequence.
lu | A long unsigned integer.
lx, lX | A long unsigned hexadecimal integer in lowercase or uppercase.
s | A string. This sequence is interpreted as type LPWSTR when the calling application uses the #define UNICODE compile flag and as type LPSTR otherwise.
S | A string. This sequence is interpreted as type LPSTR when the calling application uses the #define UNICODE compile flag and as type LPWSTR otherwise.
u | An unsigned integer argument.
x, X | An unsigned hexadecimal integer in lowercase or uppercase.


Locale Identifiers

This appendix contains detailed information about national language support in Microsoft® Windows®. The information presented here pertains to locale identifiers, LCTYPE constants, country codes, and language identifiers.

A locale identifier (LCID) is a DWORD value containing the language identifier in the lower word and the sorting ID as well as a reserved value in the upper word. The identifier supplied in an LCID is a standard international numeric abbreviation. This LCID has the components necessary to uniquely identify one of the installed system-defined locales.

Applications can use the MAKELCID macro to create LCID values.

There are two predefined LCID values: LOCALE_SYSTEM_DEFAULT is the system default locale, and LOCALE_USER_DEFAULT is the current user’s locale.


LCTYPE Constants

An LCTYPE constant is a constant that specifies a particular piece of locale information.

All values are null-terminated Unicode™ strings. If no maximum length is indicated, the strings may vary in length.

LOCALE_ILANGUAGE
Language identifier indicating the language. The maximum number of characters allowed for this string is 5.
LOCALE_SLANGUAGE
Full localized name of the language.
LOCALE_SENGLANGUAGE
Full English name of the language from the International Organization for Standardization (ISO) Standard 639. This is always restricted to characters mappable into the ASCII 127-character subset.
LOCALE_SABBREVLANGNAME
Abbreviated name of the language, created by taking the 2-letter language abbreviation from the ISO Standard 639 and adding a third letter, as appropriate, to indicate the sublanguage.
LOCALE_SNATIVELANGNAME
Native name of the language.
LOCALE_SSORTNAME
The full localized name of the sort for the specified locale identifier.
LOCALE_ICOUNTRY
Country code, based on international phone codes, also referred to as IBM country codes. The maximum number of characters allowed for this string is 6.
LOCALE_SCOUNTRY
Full localized name of the country.
LOCALE_SENGCOUNTRY
Full English name of the country. This is always restricted to characters mappable into the ASCII 127-character subset.
LOCALE_SABBREVCTRYNAME
Abbreviated name of the country from the ISO Standard 3166.
LOCALE_SNATIVECTRYNAME
Native name of the country.
LOCALE_IDEFAULTLANGUAGE
Language identifier for the principal language spoken in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is 5.
LOCALE_IDEFAULTCOUNTRY
Country code for the principal country in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is 6.
LOCALE_IDEFAULTANSICODEPAGE
American National Standards Institute (ANSI) code page associated with this locale. The maximum number of characters allowed for this string is 6.
LOCALE_IDEFAULTOEMCODEPAGE
Original equipment manufacturer (OEM) code page associated with the locale. The maximum number of characters allowed for this string is 6.
LOCALE_IDEFAULTCODEPAGE
Original equipment manufacturer (OEM) code page associated with the country. The maximum number of characters allowed for this string is 6.
LOCALE_IDEFAULTEBCDICCODEPAGE
Default EBCDIC code page associated with the locale. The maximum number of characters allowed for this string is 6.
LOCALE_SLIST
Character(s) used to separate list items. For example, a comma is used in many locales.
LOCALE_IMEASURE
System of measurement. This value is 0 if the metric system (Systéme International d’Unités, or S.I.) is used and 1 if the U.S. system is used. The maximum number of characters allowed for this string is 2.
LOCALE_SDECIMAL
Character(s) used as the decimal separator.
LOCALE_STHOUSAND
Character(s) used to separate groups of digits to the left of the decimal.
LOCALE_SGROUPING
Sizes for each group of digits to the left of the decimal. An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. To group thousands, specify 3;0, for example.
LOCALE_IDIGITS
Number of fractional digits. The maximum number of characters allowed for this string is 3.
LOCALE_ILZERO
Specification for leading zeros in decimal fields. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | No leading zeros
1 | Leading zeros

LOCALE_INEGNUMBER
Negative number mode. The mode is one of these values:
Value
Description
0 | (1.1)
1 | –1.1
2 | – 1.1
3 | 1.1–
4 | 1.1 –

LOCALE_SNATIVEDIGITS
Native equivalents to ASCII 0 through 9.
LOCALE_SENGCURRNAME
The full English name of the currency associated with the locale.
LOCALE_SNATIVECURRNAME
The native name of the currency associated with the locale.
LOCALE_SCURRENCY
String used as the local monetary symbol.
LOCALE_SINTLSYMBOL
Three characters of the international monetary symbol specified in ISO 4217, “Codes for the Representation of Currencies and Funds,” followed by the character separating this string from the amount.
LOCALE_SMONDECIMALSEP
Character(s) used as the monetary decimal separator.
LOCALE_SMONTHOUSANDSEP
Character(s) used as the monetary separator between groups of digits to the left of the decimal.
LOCALE_SMONGROUPING
Sizes for each group of monetary digits to the left of the decimal. An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. To group thousands, specify 3;0, for example.
LOCALE_ICURRDIGITS
Number of fractional digits for the local monetary format. The maximum number of characters allowed for this string is 3.
LOCALE_IINTLCURRDIGITS
Number of fractional digits for the international monetary format. The maximum number of characters allowed for this string is 3.
LOCALE_ICURRENCY
Positive currency mode. The maximum number of characters allowed for this string is 2. The mode is one of the following values:
Value
Description
0 | Prefix, no separation
1 | Suffix, no separation
2 | Prefix, 1-char. separation
3 | Suffix, 1-char. separation

LOCALE_INEGCURR
Negative currency mode. The maximum number of characters allowed for this string is 3. The mode is one of the following values:
Value
Example
0 | ($1.1)
1 | –$1.1
2 | $–1.1
3 | $1.1–
4 | (1.1$)
5 | –1.1$
6 | 1.1–$
7 | 1.1$–
8 | –1.1 $ (space before $)
9 | –$ 1.1 (space after $)
10 | 1.1 $– (space before $)
11 | $ 1.1– (space after $)
12 | $ –1.1 (space after $)
13 | 1.1– $ (space before $)
14 | ($ 1.1) (space after $)
15 | (1.1 $) (space before $)

LOCALE_SDATE
Character(s) for the date separator.
LOCALE_STIME
Character(s) for the time separator.
LOCALE_STIMEFORMAT
Time formatting strings for this locale. The string can consist of a combination of the hour, minute, and second format pictures defined in the Hour, Minute, and Second Format Pictures table in National Language Support Constants.
LOCALE_SYEARMONTH
The Year/Month formatting string for the locale. This string shows the proper format for a date string that contains only the year and the month.
LOCALE_SSHORTDATE
Short date formatting string for this locale. The string can consist of a combination of day, month, and year format pictures defined in Day, Month, Year, and Era Format Pictures table in National Language Support Constants.
LOCALE_SLONGDATE
Long date formatting string for this locale. The string can consist of a combination of day, month, and year format pictures defined in the Day, Month, Year, and Era Format Pictures table in National Language Support Constants and any string of characters enclosed in single quotes. Characters in single quotes remain as given.
LOCALE_IDATE
Short date format-ordering specification. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | Month-Day-Year
1 | Day-Month-Year
2 | Year-Month-Day

LOCALE_ILDATE
Long date format-ordering specification. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | Month-Day-Year
1 | Day-Month-Year
2 | Year-Month-Day

LOCALE_ITIME
Time format specification. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | AM / PM 12-hour format
1 | 24-hour format

LOCALE_ICENTURY
Specification for full 4-digit century. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | Abbreviated 2-digit century
1 | Full 4-digit century

LOCALE_ITLZERO
Specification for leading zeros in time fields. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | No leading zeros for hours
1 | Leading zeros for hours

LOCALE_IDAYLZERO
Specification for leading zeros in day fields. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | No leading zeros for days
1 | Leading zeros for days

LOCALE_IMONLZERO
Specification for leading zeros in month fields. The maximum number of characters allowed for this string is 2. The specification is one of the following values:
Value
Description
0 | No leading zeros for months
1 | Leading zeros for months

LOCALE_S1159
String for the AM designator.
LOCALE_S2359
String for the PM designator.
LOCALE_ICALENDARTYPE
Current calendar type. This type is one of these values:
Value
Description
1 | Gregorian (as in United States)
2 | Gregorian (English strings always)
3 | Era: Year of the Emperor (Japan)
4 | Era: Year based on the Chinese Calendar
5 | Tangun Era (Korea)

LOCALE_IOPTIONALCALENDAR
Additional calendar types. This is a zero-separated list of one or more of these calendars type values:
Value
Description
0 | No additional types valid
1 | Gregorian (as in United States)
2 | Gregorian (English strings always)
3 | Era: Year of the Emperor (Japan)
4 | Era: Year based on the Chinese Calendar
5 | Tangun Era (Korea)

LOCALE_IFIRSTDAYOFWEEK
Specification for the first day in a week. The specification is one of these values:
Value
Description
0 | LOCALE_SDAYNAME1
1 | LOCALE_SDAYNAME2
2 | LOCALE_SDAYNAME3
3 | LOCALE_SDAYNAME4
4 | LOCALE_SDAYNAME5
5 | LOCALE_SDAYNAME6
6 | LOCALE_SDAYNAME7

LOCALE_IFIRSTWEEKOFYEAR
Specification for the first week of the year. The specification is one of these values:
Value
Description
0 | Week containing 1/1 is the first week of that year.
1 | First full week following 1/1 is the first week of that year.
2 | First week containing at least 4 days is the first week of that year.

LOCALE_SDAYNAME1
Native long name for Monday.
LOCALE_SDAYNAME2
Native long name for Tuesday.
LOCALE_SDAYNAME3
Native long name for Wednesday.
LOCALE_SDAYNAME4
Native long name for Thursday.
LOCALE_SDAYNAME5
Native long name for Friday.
LOCALE_SDAYNAME6
Native long name for Saturday.
LOCALE_SDAYNAME7
Native long name for Sunday.
LOCALE_SABBREVDAYNAME1
Native abbreviated name for Monday.
LOCALE_SABBREVDAYNAME2
Native abbreviated name for Tuesday.
LOCALE_SABBREVDAYNAME3
Native abbreviated name for Wednesday.
LOCALE_SABBREVDAYNAME4
Native abbreviated name for Thursday.
LOCALE_SABBREVDAYNAME5
Native abbreviated name for Friday.
LOCALE_SABBREVDAYNAME6
Native abbreviated name for Saturday.
LOCALE_SABBREVDAYNAME7
Native abbreviated name for Sunday.
LOCALE_SMONTHNAME1
Native long name for January.
LOCALE_SMONTHNAME2
Native long name for February.
LOCALE_SMONTHNAME3
Native long name for March.
LOCALE_SMONTHNAME4
Native long name for April.
LOCALE_SMONTHNAME5
Native long name for May.
LOCALE_SMONTHNAME6
Native long name for June.
LOCALE_SMONTHNAME7
Native long name for July.
LOCALE_SMONTHNAME8
Native long name for August.
LOCALE_SMONTHNAME9
Native long name for September.
LOCALE_SMONTHNAME10
Native long name for October.
LOCALE_SMONTHNAME11
Native long name for November.
LOCALE_SMONTHNAME12
Native long name for December.
LOCALE_SMONTHNAME13
Native name for 13th month, if exists.
LOCALE_SABBREVMONTHNAME1
Native abbreviated name for January.
LOCALE_SABBREVMONTHNAME2
Native abbreviated name for February.
LOCALE_SABBREVMONTHNAME3
Native abbreviated name for March.
LOCALE_SABBREVMONTHNAME4
Native abbreviated name for April.
LOCALE_SABBREVMONTHNAME5
Native abbreviated name for May.
LOCALE_SABBREVMONTHNAME6
Native abbreviated name for June.
LOCALE_SABBREVMONTHNAME7
Native abbreviated name for July.
LOCALE_SABBREVMONTHNAME8
Native abbreviated name for August.
LOCALE_SABBREVMONTHNAME9
Native abbreviated name for September.
LOCALE_SABBREVMONTHNAME10
Native abbreviated name for October.
LOCALE_SABBREVMONTHNAME11
Native abbreviated name for November.
LOCALE_SABBREVMONTHNAME12
Native abbreviated name for December.
LOCALE_SABBREVMONTHNAME13
Native abbreviated name for 13th month, if exists.
LOCALE_SPOSITIVESIGN
String value for the positive sign.
LOCALE_SNEGATIVESIGN
String value for the negative sign.
LOCALE_IPOSSIGNPOSN
Formatting index for positive values. The maximum number of characters allowed for this string is 2. The index is one of the following values:
Value
Description
0 | Parentheses surround the amount and the monetary symbol.
1 | The sign string precedes the amount and the monetary symbol.
2 | The sign string succeeds the amount and the monetary symbol.
3 | The sign string immediately precedes the monetary symbol.
4 | The sign string immediately succeeds the monetary symbol.

LOCALE_INEGSIGNPOSN
Formatting index for negative values. This index uses the same values as LOCALE_IPOSSIGNPOSN. The maximum number of characters allowed for this string is 2.
LOCALE_IPOSSYMPRECEDES
Position of monetary symbol in a positive monetary value. This value is 1 if the monetary symbol precedes the positive amount, 0 if it follows it. The maximum number of characters allowed for this string is 2.
LOCALE_IPOSSEPBYSPACE
Separation of monetary symbol in a positive monetary value. This value is 1 if the monetary symbol is separated by a space from a positive amount, 0 if it is not. The maximum number of characters allowed for this string is 2.
LOCALE_INEGSYMPRECEDES
Position of monetary symbol in a negative monetary value. This value is 1 if the monetary symbol precedes the negative amount, 0 if it follows it. The maximum number of characters allowed for this string is 2.
LOCALE_INEGSEPBYSPACE
Separation of monetary symbol in a negative monetary value. This value is 1 if the monetary symbol is separated by a space from the negative amount, 0 if it is not. The maximum number of characters allowed for this string is 2.
LOCALE_IPAPERSIZE
Default paper size associated with the locale.
LOCALE_NOUSEROVERRIDE
This constant may be OR’ed with any other LCTYPE constant in a call to the GetLocaleInfo function. This always causes the function to bypass any user overrides, and return the system default value for the other LCTYPE specified in the function call, based on the given LCID.


Language Identifiers and Locales

Applications can use the MAKELANGID macro to create a language identifier.

The first release of Windows NT supports 35 sublanguages/locales.

The following 28 sublanguages/locales use the Latin 1 script:

Identifier
Language
Sublanguage/Locale
Language Code
0x0406 | Danish | Danish | DAN
0x0413 | Dutch | Dutch (Standard) | NLD
0x0813 | Dutch | Belgian (Flemish) | NLB
0x0409 | English | American | ENU
0x0809 | English | British | ENG
0x0c09 | English | Australian | ENA
0x1009 | English | Canadian | ENC
0x1409 | English | New Zealand | ENZ
0x1809 | English | Ireland | ENI
0x040b | Finnish | Finnish | FIN
0x040c | French | French (Standard) | FRA
0x080c | French | Belgian | FRB
0x0c0c | French | Canadian | FRC
0x100c | French | Swiss | FRS
0x0407 | German | German (Standard) | DEU
0x0807 | German | Swiss | DES
0x0c07 | German | Austrian | DEA
0x040f | Icelandic | Icelandic | ISL
0x0410 | Italian | Italian (Standard) | ITA
0x0810 | Italian | Swiss | ITS
0x0414 | Norwegian | Norwegian (Bokmal) | NOR
0x0814 | Norwegian | Norwegian (Nynorsk) | NON
0x0416 | Portuguese | Portuguese (Brazilian) | PTB
0x0816 | Portuguese | Portuguese (Standard) | PTG
0x040a | Spanish | Spain (Standard/Traditional Sort) | ESP
0x080a | Spanish | Mexican | ESM
0x0c0a | Spanish | Spain (Modern Sort) | ESN
0x041d | Swedish | Swedish | SVE

The following 5 sublanguages/locales use the Latin 2 script:

Identifier
Sublanguage/Locale
Language Code
0x041f | Turkish | TRK
0x0415 | Polish | PLK
0x0405 | Czech | CSY
0x041b | Slovak | SKY
0x040e | Hungarian | HUN

The following sublanguage/locale uses the Cyrillic script:

Identifier
Sublanguage/Locale
Language Code
0x0419 Russian RUS

The following sublanguage/locale uses an other script:

Identifier
Sublanguage/Locale
Language Code
0x0408 Greek ELL

The following special identifiers are also defined:

Identifier
Sublanguage/Locale
0x0000 | Language-Neutral
0x0400 | Process Default Language


Resource-Definition Statements

Resource-definition statements define the resources that the resource compiler adds to the resource (.res) file. After the .res file is linked to the executable file, the application can load its resources at run time as needed. All resource statements associate an identifying name or number with a specified resource.


ACCELERATORS Resource

This resource-definition statement specifies one or more accelerators for an application. An accelerator is an application-defined keystroke that provides the user with a quick way to perform a task.

The TranslateAccelerator function is used by the application to translate accelerator messages from the application queue into WM_COMMAND or WM_SYSCOMMAND messages.

Syntax

acctablename ACCELERATORS[[optional-statements]]{event, idvalue, [[type]] [[options]]. . .}

Parameters

acctablename
Specifies either a unique name or a 16-bit unsigned integer value that identifies the resource.
optional-statements
Specifies options for accelerators. It can be zero or more of the following statements:
CHARACTERISTICS dword
User-defined information about a resource used by tools that read and write resource files. For more information, see CHARACTERISTICS.
LANGUAGE language, sublanguage
Specifies the language for the resource. For more information, see LANGUAGE.
VERSION dword
User-defined version number for the resource used by tools that read and write resource files. For more information, see VERSION.
event
Specifies the keystroke to be used as an accelerator. It is one of the following character types:
“char”
A single character enclosed in double quotation marks (“). The character can be preceded by a caret (^). This means that the character is a control character—the accelerator is only activated if the CONTROL key is down.
Character
An integer value representing a character. The type parameter must be ASCII.
virtual-key character
An integer value representing a virtual key. The virtual key for alphanumeric keys can be specified by placing the uppercase letter or number in double quotation marks, for example, “9” or “C.” The type parameter must be VIRTKEY.
idvalue
Specifies a 16-bit unsigned integer value that identifies the accelerator.
type
Required only when the event parameter is a character or a virtual-key character. The type parameter specifies either ASCII or VIRTKEY; the integer value of event is interpreted accordingly. When VIRTKEY is specified and event contains a string, the string must be uppercase.
options
Specifies the options that define the accelerator. It can be one or more of the following values:
NOINVERT
Specifies that no top-level menu item is highlighted when the accelerator is used. This is useful when defining accelerators for actions that do not correspond to a menu item—for example, scrolling. If NOINVERT is omitted, a top-level menu item is highlighted when the accelerator is used.
ALT
Causes the accelerator to be activated only if the ALT key is down. Applies only to virtual keys.
SHIFT
Causes the accelerator to be activated only if the SHIFT key is down. Applies only to virtual keys.
CONTROL
Defines the character as a control character. This has the same effect as using a caret (^) before the accelerator character in the event parameter. Applies only to virtual keys.

Example

The following code example shows how to use accelerator keys.

1 ACCELERATORS
{
 "^C", IDDCLEAR ; control C
 "K", IDDCLEAR ; shift K
 "k", IDDELLIPSE, ALT ; alt k
 98, IDDRECT, ASCII ; b
 66, IDDSTAR, ASCII ; B (shift b)
 "g", IDDRECT ; g
 "G", IDDSTAR ; G (shift G)
 VK_F1, IDDCLEAR, VIRTKEY ; F1
 VK_F1, IDDSTAR, CONTROL, VIRTKEY ; control F1
 VK_F1, IDDELLIPSE, SHIFT, VIRTKEY ; shift F1
 VK_F1, IDDRECT, ALT, VIRTKEY ; alt F1
 VK_F2, IDDCLEAR, ALT, SHIFT, VIRTKEY ; alt shift F2
 VK_F2, IDDSTAR, CONTROL, SHIFT, VIRTKEY ; ctrl shift F2
 VK_F2, IDDRECT, ALT, CONTROL, VIRTKEY ; alt control F2
}

See Also

TranslateAccelerator, CHARACTERISTICS, DIALOG, LANGUAGE, MENU, RCDATA, STRINGTABLE, VERSION


AUTO3STATE Control

This resource-definition statement creates an automatic three-state check box control that, when selected, automatically advances between three states: checked, unchecked, and disabled (grayed). The control then sends a message to its parent whenever the user chooses the control.

Syntax

AUTO3STATE text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies styles for the control, which can be a combination of the BS_AUTO3STATE style and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

If you do not specify a style, the default style is BS_AUTO3STATE | WS_TABSTOP.

See Also

AUTOCHECKBOX, CHECKBOX, CONTROL, STATE3


AUTOCHECKBOX Control

This resource-definition statement creates an automatic check box control that displays an X when the user chooses the control. The control then sends a message to its parent window.

Syntax

AUTOCHECKBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies the styles of the control. This value can be a combination of the button class style BS_AUTOCHECKBOX and the WS_TABSTOP and WS_GROUP styles.

If you do not specify a style, the default style is BS_AUTOCHECKBOX | WS_TABSTOP.

Remarks

The AUTOCHECKBOX statement can only be used in the body of a DIALOG or DIALOGEX statement.

See Also

AUTO3STATE, CHECKBOX, CONTROL, STATE3


AUTORADIOBUTTON Control

This resource-definition statement creates an automatic radio button control. When the button is chosen, the control sends a BN_CLICKED message to the application. When an automatic radio button control is placed in the same group as other automatic radio button controls, they become mutually exclusive.

Syntax

AUTORADIOBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

text
Specifies the text that is displayed next to the radio button.
style
Specifies styles for the automatic radio button, which can be a combination of BUTTON class styles and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

If you do not specify a style, the default style is BS_AUTORADIOBUTTON | WS_TABSTOP.

Remarks

For more information about button styles, see Button Control Statements.

See Also

CONTROL, RADIOBUTTON


BITMAP Resource

This resource-definition statement specifies a bitmap that an application uses in its screen display or as an item in a menu or control.

Syntax

nameID BITMAP filename

Parameters

nameID
Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.
filename
Specifies the name of the file that contains the resource. The name must be a valid file name, and it must be a full path if the file is not in the current working directory. The path can either be a quoted or nonquoted string.

Example

The following code example specifies two bitmap resources.

disk1 BITMAP disk.bmp
12 BITMAP diskette.bmp

See Also

LoadBitmap


CAPTION Statement

This resource-definition statement sets the title for a dialog box. The title appears in the box’s caption bar, if one exists.

Syntax

CAPTION “captiontext”

Parameters

captiontext
Specifies a character string that is enclosed in double quotation marks (“).

Remarks

The default caption is empty.

Example

The following code example shows how to use the CAPTION statement.

CAPTION "Error!"


CHARACTERISTICS Statement

This resource-definition statement specifies information about a resource used by tools that read and write resource-definition files. The DWORD value appears with the resource in the compiled .res file. However, the value is not stored in the executable file and has no significance to the system.

The CHARACTERISTICS statement appears before the beginning of the body of an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition. The specified value applies only to that resource.

Syntax

CHARACTERISTICS dword

Parameters

dword
User-defined DWORD value.

See Also

ACCELERATORS, DIALOG, LANGUAGE, MENU, RCDATA, STRINGTABLE


CHECKBOX Control

This resource-definition statement creates a check box control that displays an X when the user selects the control. The control then sends a message to its parent window.

The CHECKBOX statement, which can only be used in a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Syntax

CHECKBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

text
Specifies the text that is displayed to the right of the control.
style
Specifies the control styles. This value can be a combination of the button class style BS_CHECKBOX and the WS_TABSTOP and WS_GROUP styles.

If you do not specify a style, the default style is BS_CHECKBOX | WS_TABSTOP.

Example

The following code example shows how to create a check box control that is labeled Italic.

CHECKBOX "Italic", 3, 10, 10, 40, 10

See Also

AUTOCHECKBOX, AUTO3STATE, GetDialogBaseUnits, STATE3


CLASS Statement

This resource-definition statement sets the class of the dialog box.

Syntax

CLASS class

Parameters

class
Specifies a 16-bit unsigned integer or a string, enclosed in double quotation marks (“), that identifies the class of the dialog box. If the window procedure for the class does not process the message sent to it, the window procedure must call the DefDlgProc function to ensure that all messages are handled properly for the dialog box. A private class can use DefDlgProc as the default window procedure. The class must be registered with the cbWndExtra member of the WNDCLASS structure set to DLGWINDOWEXTRA.

Remarks

The CLASS statement should only be used in special cases, because it overrides the normal processing of a dialog box. The CLASS statement converts a dialog box to a window of the specified class; depending on the class, there could be undesirable results.

Do not use the redefined control class names with this statement.

Example

The following code example shows how to use the CLASS statement.

CLASS "myclass"

See Also

DefDlgProc, DIALOG


COMBOBOX Control

This resource-definition statement creates a combo box control.

Syntax

COMBOBOX id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies the control styles. This value can be a combination of the COMBOBOX class styles and any of the following styles: WS_TABSTOP, WS_GROUP, WS_VSCROLL, and WS_DISABLED.

If you do not specify a style, the default style is CBS_SIMPLE | WS_TABSTOP.

Remarks

For more information about styles, see CONTROL.

Example

The following code example shows how to create a combo-box control with a vertical scroll bar.

COMBOBOX 777, 10, 10, 50, 54, CBS_SIMPLE | WS_VSCROLL | WS_TABSTOP

See Also

CONTROL


CONTROL Control

This resource-definition statement creates a user-defined control.

Syntax

CONTROL text, id, class, style, x, y, width, height [[, extended-style]]

Parameters

class
Specifies a redefined name, character string, or a 16-bit unsigned integer value that defines the class of the control. For more information about possible control classes, see Remarks. If the value is a redefined name supplied by the application, it must be a string enclosed in double quotation marks (“).
style
Specifies a redefined name or integer value that contains the style of the specified control. The exact meaning of style depends on the class value. For more information about possible styles, see Remarks.

Remarks

The six possible control classes are described in the following sections.

Button Control Class

A button control is a small rectangular child window that the user turns on or off when selected. Button controls can be used alone or in groups, and can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.

The following table shows button styles. A button can have only one of the styles, with the exception of BS_LEFTTEXT, which can be combined with check boxes and radio buttons.

Style
Description
BS_3STATE | Creates a check box in which the box can be unavailable (grayed) as well as checked or unchecked. Use the unavailable state to show that the state of the check box is not determined.
BS_AUTO3STATE | Creates a three-state check box in which the state cycles through checked, unavailable, and unchecked each time the user selects the check box.
BS_AUTOCHECKBOX | Creates a check box in which the check state automatically toggles between checked and unchecked each time the user selects the check box.
BS_AUTORADIOBUTTON | Creates a radio button that, when selected by a user, clears all other buttons in the same group.
BS_BOTTOM | Places the text at the bottom of the button rectangle.
BS_CENTER | Centers the text horizontally in the button rectangle.
BS_CHECKBOX | Creates a small, empty check box with a label displayed to the right of it. To display the text to the left of the check box, combine this flag with the BS_RIGHTBUTTON style.
BS_DEFPUSHBUTTON | Creates a push button with a heavy black border. If the button is in a dialog box, the user can select the button by pressing the enter key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely option, or default.
BS_GROUPBOX | Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle’s upper-left corner.
BS_LEFT | Left-aligns the text in the button rectangle when combined with the radio button or check box style.
BS_NOTIFY | Enables a button to send BN_DBLCLK, BN_KILLFOCUS, or BN_SETFOCUS notification messages to its parent window.
BS_OWNERDRAW | Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created, and it receives a WM_DRAWITEM message when a visual aspect of the button has changed. The BS_OWNERDRAW style cannot be combined with any other button styles.
BS_PUSHBUTTON | Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.
BS_RADIOBUTTON | Creates a small circle with a label displayed to the right of it. To display the text to the left of the circle, combine this flag with the BS_RIGHTBUTTON style.
BS_RIGHT | Right-aligns text in the button rectangle.
BS_RIGHTBUTTON | Positions a check box’s square on the right side of the button rectangle.
BS_TOP | Places text at the top of the button rectangle.
BS_VCENTER | Vertically centers text in the button rectangle.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Combo Box Control Class

Combo box controls consist of a selection field similar to an edit control plus a list box. The list box may be displayed at all times or may be dropped down when the user selects the down arrow next to the selection field. Depending on the style of the combo box, the user can or cannot edit the contents of the selection field.

If you specify the CBS_EX_CONSTSTRINGDATA style when the application inserts a string into the list part of a combo box, the combo box stores the pointer passed to it by the application rather than copying the string. This saves RAM resources when you have a large table of strings in ROM that you want to insert into a combo box.

All combo boxes in Windows CE have the LBS_HASSTRINGS style by default.

The following table shows combo box control styles.

Style
Description
CBS_AUTOHSCROLL | Creates a combo box that automatically scrolls the text in the edit control to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is allowed.
CBS_DISABLENOSCROLL | Creates a combo box that displays a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items.
CBS_DROPDOWN | Creates a combo box that displays only the edit control by default. The user can display the list box by selecting an icon next to the edit control.
CBS_DROPDOWNLIST | Creates a combo box that displays a static text field that displays the current selection in the list box.
CBS_LOWERCASE | Converts any uppercase characters typed into the edit control of a combo box to lowercase.
CBS_NOINTERGRALHEIGHT | Specifies that the combo box is exactly the size specified by the application when it created the combo box. Usually, Windows CE sizes a combo box so that it does not display partial items.
CBS_OEMCONVERT | Converts text typed in the combo box edit control from the Windows character set to the OEM character set and then back to the Windows set. This style is most useful for combo boxes that contain file names. It applies only to combo boxes created with the CBS_DROPDOWN style.
CBS_SORT | Creates a combo box that sorts the strings in the list box alphabetically.
CBS_UPPERCASE | Converts any lowercase characters typed into the edit control of a combo box to uppercase.
WS_TABSTOP | Turns the control into a tab stop which allows the user to select the control by tabbing through the controls in a dialog box.

Edit Control Class

An edit control is a rectangular child window in which the user can enter text from the keyboard. The user selects the control and gives it the input focus, by tapping inside it with a stylus or by pressing the TAB key. The user can enter text when the control displays a flashing insertion point.

Edit controls use the fixed-pitch font and display Unicode characters. They expand tab characters into as many space characters as are required to move the cursor to the next tab stop. Tab stops are assumed to be at every eighth character position.

The following table shows edit control styles.

Style
Description
ES_AUTOHSCROLL | Creates an edit control that automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position zero.
ES_AUTOVSCROLL | Creates an edit control that scrolls text up one page when the user presses the ENTER key on the last line.
ES_CENTER | Centers the text. This style is valid in multiline edit controls only.
ES_COMBOBOX | Indicates that the edit control is part of a combo box.
ES_LEFT | Aligns text to the left.
ES_LOWERCASE | Converts all characters to lowercase as they are typed into the edit control.
ES_MULTILINE Creates a multiline edit control. The default is a single-line edit control.

When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the ES_WANTRETURN style.

When the multiline edit control is not in a dialog box and the ES_AUTOVSCROLL style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify ES_AUTOVSCROLL, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed.

If you specify the ES_AUTOHSCROLL style, the multiline edit control automatically scrolls horizontally when the cursor goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify ES_AUTOHSCROLL, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed.

Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window.
ES_NOHIDESEL | Negates the default behavior for an edit control. The default behavior hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. If you specify ES_NOHIDESEL, the selected text is inverted, even if the control does not have the focus.
ES_NUMBER | Allows only digits to be typed into the edit control.
ES_OEMCONVERT | Converts text typed in the edit control from the Windows character set to the OEM character set, and then converts it back to the Windows set. This style is most useful for edit controls that contain file names.
ES_PASSWORD | Displays all characters as an asterisk (*) as they are typed into the edit control. An application can use the EM_SETPASSWORDCHAR message to change the character that is displayed.
ES_READONLY | Prevents the user from typing or editing text in the edit control.
ES_RIGHT | Aligns text to the right. This style is valid in multiline edit controls only.
ES_UPPERCASE | Converts all characters to uppercase as they are typed into the edit control.
ES_WANTRETURN | Specifies that a carriage return be inserted when the user presses the ENTER key while typing text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box’s default push button. This style has no effect on a single-line edit control.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Listbox Control Class

List box controls consist of a list of character strings. The control is used whenever an application needs to present a list of names, such as file names, that the user can view and select. When a string is selected, it is highlighted and a notification message is passed to the parent window. A scroll bar can be used with a list box control to scroll lists that are too long or too wide for the control window.

There are two types of list boxes: single-selection, which is the default, and multiple-selection. In a single-selection list box, the user can select only one item at a time. In a multiple-selection list box, the user can select more than one item at a time. To create a multiple-selection list box, specify the LBS_MULTIPLESEL or the LBS_EXTENDEDSEL style.

Note Windows CE supports the LBS_EX_CONSTSTRINGDATA style which saves RAM resources when you have a large table of strings in ROM that you want to insert into a list box.

All list boxes in Windows CE have the LBS_HASSTRINGS style by default.

The following table shows list box control styles.

Style
Description
LBS_DISABLENOSCROLL | Creates a list box that shows a disabled vertical scroll bar for the list box when the box does not contain enough items to scroll. If this style is not specified, the scroll bar is hidden when the list box does not contain enough items.
LBS_EXTENDEDSEL | Creates a list box that enables the user to select multiple items by using special key combinations.
LBS_MULTICOLUMN | Creates a multicolumn list box that the user scrolls horizontally. Use the LB_SETCOLUMNWIDTH message to set the width of the columns.
LBS_MULTIPLESEL | Creates a list box that turns string selection on or off each time a user selects a string in the list box. A user can select any number of strings simultaneously.
LBS_NOINTEGRALHEIGHT | Specifies that the list box will be exactly the size specified by the application when it created the list box. Usually, Windows sizes a list box so that it does not display partial items.
LBS_NOREDRAW | Create a list box that does not automatically updated its appearance when changes are made. You can change this style by sending a WM_SETREDRAW message.
LBS_NOSEL | Creates a list box in which the user can view list box strings but cannot select them.
LBS_NOTIFY | Notifies the parent window whenever the user selects a string in the list box.
LBS_SORT | Sorts the strings in the list box alphabetically.
LBS_STANDARD | Sorts strings in the list box alphabetically. The parent window receives an input message whenever the user clicks or double-clicks a string. The list box has borders on all sides
LBS_USETABSTOPS | Creates a list box that recognizes and expands tab characters when drawing its strings. The default tab positions are 32 dialog box units. A dialog box unit is equal to one-fourth of the current dialog box base-width unit. Windows CE calculates these units based on the height and width of the current system font.
LBS_WANTKEYBOARDINPUT | Specifies that the owner of the list box receives WM_VKEYTOITEM messages whenever the user presses a key and the list box has the input focus. This enables an application to perform special processing on the keyboard input.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Scroll Bar Control Class

A scroll bar control is a rectangle that contains a scroll thumb and has direction arrows at both ends. The scroll bar sends a notification message to its parent whenever the user selects the control. The parent is responsible for updating the thumb position, if necessary.

Scroll bar controls have the same appearance and function as the scroll bars used in ordinary windows. But unlike scroll bars, scroll bar controls can be positioned anywhere within a window and used whenever needed to provide scrolling input for a window.

The following table shows scroll bar control styles.

Style
Description
SBS_BOTTOMALIGN | Aligns the bottom edge of the scroll bar with the bottom edge of the rectangle defined by the x, y, nWidth, and nHeight parameters of CreateWindowEx function. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.
SBS_HORZ | Creates a horizontal scroll bar. If neither SBS_BOTTOMALIGN nor SBS_TOPALIGN is specified, the scroll bar has the height, width, and position specified in the CreateWindow function.
SBS_LEFTALIGN | Aligns the left edge of the scroll bar with the left edge of the rectangle defined by the x, y, nWidth, and nHeight parameters of CreateWindowEx. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.
SBS_RIGHTALIGN | Aligns the right edge of the scroll bar with the right edge of the rectangle defined by the x, y, nWidth, and nHeight parameters of CreateWindowEx. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.
SBS_TOPALIGN | Aligns the top edge of the scroll bar with the top edge of the rectangle defined by the x, y, nWidth, and nHeight parameters of CreateWindowEx. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.
SBS_VERT | Creates a vertical scroll bar. If neither SBS_RIGHTALIGN nor SBS_LEFTALIGN is specified, the scroll bar has the height, width, and position specified in the CreateWindow function.

Static Control Class

Static controls are simple text fields, boxes, and rectangles that can be used to label, box, or separate other controls. Static controls accept no input and provide no output.

In Windows CE, you can use only the SS_CENTERIMAGE style in conjunction with the SS_BITMAP style. Even if you specify SS_ICON, you cannot set the image by calling:

SendMessage( hStatic, STM_SETIMAGE, IMAGE_ICON, (LPARAM) hIcon );

Instead, you have to use:

SendMessage( hStatic, STM_SETIMAGE, IMAGE_BITMAP, (LPARAM) hBitmap );

If you specify SS_CENTERIMAGE, and do not specify either SS_ICON or SS_BITMAP, the static control will behave as though you had specified the SS_BITMAP style.

Windows CE does not support the SS_SIMPLE static control styles, but you can emulate this style by using the SS_LEFT or SS_LEFTNOWORDWRAP style. Windows CE also does not support the SS_BLACKFRAME, SS_BLACKRECT, SS_GRAYFRAME, SS_GRAYRECT, SS_OWNERDRAW, SS_WHITEFRAME, SS_WHITERECT styles but you can use the WM_PAINT message to achieve the same results.

The following table shows static control styles.

Style
Description
SS_BITMAP | Creates a static control that displays a bitmap. The text is the name of a bitmap defined elsewhere in the resource file, not a file name. The style ignores the nWidth and nHeight parameters; the control automatically sizes itself to accommodate the bitmap.
SS_CENTER | Creates a static control with a simple rectangle and centers the error value text in the rectangle. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next centered line.
SS_CENTERIMAGE | Specifies that the midpoint of a static control with the SS_BITMAP style remains fixed when you resize the control. The four sides are adjusted to accommodate a new bitmap. If the bitmap is smaller than the control’s client area, the rest of the client area is filled with the color of the pixel in the bitmap’s upper-left corner.
SS_ICON | Creates a static control that displays an icon. The text is the name of an icon defined elsewhere in the resource file, not a file name. The style ignores the nWidth and nHeight parameters; the icon automatically sizes itself.
SS_LEFT | Creates a static control with a simple rectangle that displays the specified text flush left. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next left-aligned line.
SS_LEFTNOWORDWRAP | Specifies a rectangle and left-aligns the text in the rectangle. Tabs are expanded but words are not wrapped. Text that extends past the end of a line is clipped.
SS_NOPREFIX Prevents interpretation of any ampersand (&) characters in the control’s text as accelerator prefix characters.

An application can combine SS_NOPREFIX with other styles by using the bitwise OR ( | ) operator. This can be useful when file names or other strings that may contain an ampersand (&) must be displayed within a static control in a dialog box.
SS_NOTIFY | Sends the parent window the STN_CLICKED notification when the user clicks the control.
SS_RIGHT | Creates a static control with a simple rectangle that displays the specified text flush right. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line.


CTEXT Control

This resource-definition statement creates a centered-text control. The control is a simple rectangle that displays the specified text centered in the rectangle. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line.

Syntax

CTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

text
Specifies the text that is displayed in the center of the control.
style
Specifies the control styles. This value can be any combination of the following styles: SS_CENTER, WS_TABSTOP, and WS_GROUP.

If you do not specify a style, the default style is SS_CENTER | WS_GROUP.

Remarks

The CTEXT statement, which you can use only in a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Example

The following code example shows how to create a centered-text control that is labeled Filename.

CTEXT "Filename", 101, 10, 10, 100, 100

See Also

CONTROL, DIALOG, LTEXT, RTEXT


CURSOR Resource

This resource-definition statement specifies a bitmap that defines the shape of either the cursor on the display screen or an animated cursor.

Syntax

nameID CURSOR filename

Parameters

nameID
Specifies either a unique name or a 16-bit unsigned integer identifying the resource.
filename
Specifies the name of the file that contains the resource. The name must be a valid file name, and it must be a full path if the file is not in the current working directory. The path can either be a quoted or nonquoted string.

Remarks

Icon and cursor resources can contain more than one image.

Example

The following code example shows how to specify two cursor resources; the first by name and the second by number.

cursor1 CURSOR bullseye.cur
2 CURSOR "d:\\cursor\\arrow.cur"


DEFPUSHBUTTON Control

This resource-definition statement creates a default push button control. The control is a small rectangle with a bold outline that represents the default response for the user. The specified text is displayed inside the button. The control highlights when the user selects it, then sends a message to its parent window.

Syntax

DEFPUSHBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

text
Specifies the text that is displayed in the center of the control.
style
Specifies the control styles. This value can be a combination of the following styles: BS_DEFPUSHBUTTON, WS_TABSTOP, WS_GROUP, and WS_DISABLED.

If you do not specify a style, the default style is BS_DEFPUSHBUTTON | WS_TABSTOP.

Example

the following code example shows how to create a default push-button control that is labeled Cancel.

DEFPUSHBUTTON "Cancel", 101, 10, 10, 24, 50

See Also

PUSHBUTTON, RADIOBUTTON


DIALOG Resource

This resource-definition statement specifies a window that an application can use to create dialog boxes. The statement defines the position and dimensions of the dialog box on the screen, as well as the dialog box style.

Syntax

nameID DIALOG x, y, width, height [[optional-statements]] { control-statement . . . }

Parameters

nameID
Identifies the dialog box. This is either a unique name or a unique 16-bit unsigned integer value in the range 1 to 65,535.
option-statements
Specifies options for the dialog box. It can be zero or more of the following statements:
CAPTION “text”
Specifies the caption of the dialog box if it has a title bar. For more information, see CAPTION.
CHARACTERISTICS dword
Specifies a user-defined DWORD value for use by resource tools. This value is not used by the system. For more information, see CHARACTERISTICS.
CLASS class
Specifies a 16-bit unsigned integer or a string, enclosed in double quotation marks (“), that identifies the class of the dialog box. For more information, see CLASS.
EXSTYLE=extended-styles
Specifies the extended window style of the dialog box. For more information, see EXSTYLE.
FONT pointsize, typeface
Specifies the point size and typeface for the font. For more information, see FONT.
LANGUAGE language,sublanguage
Specifies the language of the dialog box. For more information, see LANGUAGE.
MENU menuname
Specifies the menu to use. This value is either the name of the menu or its integer identifier.
STYLE styles
Specifies the styles of the dialog box. For more information, see STYLE.
VERSION dword
Specifies a user-defined DWORD value. This statement is intended for use by additional resource tools and is not used by the system. For more information, see VERSION.

Remarks

For more information about the x, y, width, and height parameters, see Common Control Parameters.

The GetDialogBaseUnits function returns the dialog base units in pixels. The exact meaning of the coordinates depends on the style defined by the STYLE option statement. For child-style dialog boxes, the coordinates are relative to the origin of the parent window, unless the dialog box has the style DS_ABSALIGN; in that case, the coordinates are relative to the origin of the display screen.

Do not use the WS_CHILD style with a modal dialog box because the DialogBox function always disables the parent or owner of the newly created dialog box. When a parent window is disabled, its child windows are disabled as well.

If a dialog box has the DS_ABSALIGN style, the coordinates for the upper-left corner of the dialog box are relative to the screen origin instead of to the upper-left corner of the parent window. You would typically use this style when you wanted the dialog box to start in a specific part of the display no matter where the parent window is on the screen.

To create a window with dialog box attributes, specify DIALOG as the class name parameter of the CreateWindow function.

Example

The following code example shows how to use the DIALOG statement.

#include <windows.h>

ErrorDialog DIALOG 10, 10, 300, 110
STYLE WS_POPUP | WS_BORDER
CAPTION "Error!"
{
 CTEXT "Select One:", 1, 10, 10, 280, 12
 PUSHBUTTON "&Retry", 2, 75, 30, 60, 12
 PUSHBUTTON "&Abort", 3, 75, 50, 60, 12
 PUSHBUTTON "&Ignore", 4, 75, 80, 60, 12
}

See Also

CONTROL, CreateDialog, CreateWindow, DialogBox, DIALOGEX, GetDialogBaseUnits, ACCELERATORS, CHARACTERISTICS, LANGUAGE, MENU, RCDATA, STRINGTABLE, VERSION


DIALOGEX Resource

This resource-definition statement is an extension of the DIALOG resource-definition statement that additionally supports the following:

  • Help identifiers on the dialog box itself, as well as on controls within the dialog box.
  • Use of the EXSTYLE statement for the dialog box itself, as well as on controls within the dialog box.
  • Font weight and italic settings for the font to be used in the dialog box.
  • Control-specific data for controls within the dialog box.
  • Use of the BEDIT, IEDIT, and HEDIT predefined system class names.

Syntax

nameID DIALOGEX x, y, width, height [[ , helpID]] [[ optional-statements]] { control-statements }

Parameters

nameID
Identifies the dialog box. This is either a unique name or a unique 16-bit unsigned integer value in the range 1 to 65,535.
x
Specifies, in dialog units, the location on the screen of the left side of the dialog box.
y
Specifies, in dialog units, the location on the screen of the top of the dialog box.
width
Specifies, in dialog units, the width of the dialog box.
height
Specifies, in dialog units, the height of the dialog box.
helpID
Specifies a numeric expression that indicates the identifier of the dialog box during WM_HELP processing.
optional-statements
Specifies options for the dialog box. This can be zero or more of the following statements:
CAPTION “text”
Specifies the caption of the dialog box if it has a title bar. For more information, see CAPTION.
CHARACTERISTICS dword
Specifies a user-defined DWORD value for use by resource tools. This value is not used by the system. For more information, see CHARACTERISTICS.
CLASS class
Specifies a 16-bit unsigned integer or a string, enclosed in double quotation marks (“), that identifies the class of the dialog box. For more information, see CLASS.
EXSTYLE=extended-styles
Specifies the extended window style of the dialog box. For more information, see EXSTYLE.
FONT pointsize, typeface, weight, italic
Specifies the point size and typeface for the font. For weight, use the FW_* values defined in the header file Wingdi.h. For italic, specify TRUE to use an italic font, FALSE otherwise. For more information, see FONT.
LANGUAGE language,sublanguage
Specifies the language of the dialog box. For more information, see LANGUAGE.
MENU menuname
Specifies the menu to use. This value is either the name of the menu or its integer identifier. For more information, see MENU.
STYLE styles
Specifies the styles of the dialog box. For more information, see STYLE.
VERSION dword
Specifies a user-defined DWORD value. This statement is intended for use by additional resource tools and is not used by the system. For more information, see VERSION.
control-statements
The body of the DIALOGEX resource is made up of any number of control statements. There are four families of control statements: generic, static, button, and edit. For more information about these families, see Remarks.

Remarks

The following valid operations can be contained in any of the numeric expressions in the statements of DIALOGEX:

  • Add (‘+’)
  • Subtract (‘-’)
  • Unary minus (‘-’)
  • Unary NOT (‘~’)
  • AND (‘&’)
  • OR (‘|’)

The body of the resource is made up of generic, static, button, and edit control statements. While each of these families of statements uses a different syntax for defining specific features of its controls, they all share a common syntax for defining position, size, extended styles, Help identification number, and control-specific data.

See Also

ACCELERATORS, Button Control Statements, CHARACTERISTICS, CONTROL, CreateDialog, CreateWindow, DialogBox, DIALOGEX, Edit Control Statements, GetDialogBaseUnits, Generic Control Statements, LANGUAGE, MENU, RCDATA, Static Control Statements, STRINGTABLE, VERSION


Generic Control Statements

Syntax

CONTROL controlText, id, className, style

Parameters

controlText
Specifies the window text for the control.
id
Specifies the control identifier.
className
Specifies the name of the class. This may be either a string enclosed in double quotation marks (“) or one of the following predefined system classes: BUTTON, STATIC, EDIT, LISTBOX, SCROLLBAR, or COMBOBOX.
style
Specifies the window styles. Explicit WS_*, BS_*, SS_*, ES_*, LBS_*, SBS_*, and CBS_* style values defined in Winuser.h can be used by adding an include to the .rc file, as follows:
#include "Winuser.h"


Static Control Statements

Syntax

staticClass controlText, id

Parameters

staticClass
Specifies one of the following classes: LTEXT, RTEXT, or CTEXT.
controlText
Specifies the window text for the control.
id
Specifies the control identifier.


Button Control Statements

Syntax

buttonClass controlText, id

Parameters

buttonClass
Specifies one of the following classes: AUTO3STATE, AUTOCHECKBOX, AUTORADIOBUTTON, CHECKBOX, PUSHBOX, PUSHBUTTON, RADIOBUTTON, STATE3, or USERBUTTON.
controlText
Specifies the window text for the control.
id
Specifies the control identifier.


Edit Control Statements

Syntax

editClass id

editClass
Specifies one of the following classes: EDITTEXT, BEDIT, HEDIT, or IEDIT.
id
Specifies the control identifier.


EDITTEXT Control

This resource-definition statement creates an edit control belonging to the EDIT class. It creates a rectangular region in which the user can enter and edit text. The control displays a cursor when the selects it. The user can then use the keyboard to enter text or edit the existing text.

Syntax

EDITTEXT id, x, y, width, height [, style [, extended-style]]

Parameters

style
Specifies the control styles. This value can be a combination of the edit class styles and the following styles: WS_TABSTOP, WS_GROUP, WS_VSCROLL, WS_HSCROLL, and WS_DISABLED. For a complete listing of all supported Windows CE styles, see Window and Control Styles.

If you do not specify a style, the default style is ES_LEFT | WS_BORDER | WS_TABSTOP.

Example

The following code example shows how to use the EDITTEXT statement.

EDITTEXT 3, 10, 10, 100, 10

See Also

CONTROL


EXSTYLE Statement

This resource-definition statement sets extended window styles for a dialog box. In a resource definition, the EXSTYLE statement is placed with the optional statements before the beginning of the body of the resource definition.

Syntax

EXSTYLE extended-style

Parameters

extended-style
Specifies the extended window style for the dialog box or control. It is one of the following values:
WS_EX_ACCEPTFILES
Specifies that a window created with this style accepts drag-and-drop files.
WS_EX_APPWINDOW
Forces a top-level window onto the taskbar when the window is visible.
WS_EX_CLIENTEDGE
Specifies that a window has a border with a sunken edge.
WS_EX_CONTEXTHELP
Includes a question mark in the title bar of the parent window. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a child window, the child receives a WM_HELP message. The child window should pass the message to the parent window procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains Help for the child window.

WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.

WS_EX_DLGMODALFRAME
Creates a window that has a double border; the window can, optionally, be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter.
WS_EX_LEFT
The window has left-aligned properties. This is the default.
WS_EX_LEFTSCROLLBAR
If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the vertical scroll bar—if present—is to the left of the client area. For other languages, the style is ignored and not treated as an error.
WS_EX_LTRREADING
The window text is displayed using left to right reading-order properties. This is the default.
WS_EX_MDICHILD
Creates an multiple-document interface (MDI) child window.
WS_EX_NOPARENTNOTIFY
Specifies that a child window created with this style does not send the WM_PARENTNOTIFY message to its parent window when it is created or destroyed.
WS_EX_OVERLAPPEDWINDOW
Combines the WS_EX_CLIENTEDGE and WS_EX_WINDOWEDGE styles.
WS_EX_PALETTEWINDOW
Combines the WS_EX_WINDOWEDGE, WS_EX_TOOLWINDOW, and WS_EX_TOPMOST styles.
WS_EX_RIGHT
The window has generic right-aligned properties, depending on the window class. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored and not treated as an error.
WS_EX_RIGHTSCROLLBAR
The vertical scroll bar—if present—is to the right of the client area. This is the default.
WS_EX_RTLREADING
If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the window text is displayed using Right to Left reading-order properties. For other languages, the style is ignored and not treated as an error.
WS_EX_STATICEDGE
Creates a window with a three-dimensional border style intended to be used for items that do not accept user input.
WS_EX_TOOLWINDOW
Creates a tool window; that is, a window intended to be used as a floating toolbar. A tool window has a title bar that is shorter than a normal title bar, and the window title is drawn using a smaller font. A tool window does not appear in the taskbar or in the dialog box that appears when the user presses ALT+TAB. If a tool window has a system menu, its icon is not displayed on the title bar. However, you can display the system menu by typing ALT+SPACE.
WS_EX_TOPMOST
Specifies that a window created with this style should be placed above all but the topmost window and should stay above them, even when the window is deactivated. To add or remove this style, use the SetWindowPos function.
WS_EX_TRANSPARENT
Specifies that a window created with this style should not be painted until its siblings have been painted. The window appears transparent because the bits of underlying sibling windows have already been painted.

To achieve transparency without these restrictions, use the SetWindowRgn function.

WS_EX_WINDOWEDGE
Specifies that a window has a border with a raised edge.

Remarks

For controls, extended styles are specified after the style option in the control resource-definition statement. For more information about the extended styles supported in each control, see the resource-definition statement for the individual control.

See also

ACCELERATORS, CONTROL, DIALOG, MENU, POPUP, RCDATA, STRINGTABLE, User-Defined Resource


FONT Resource

This resource-definition statement specifies a file that contains a font a font to be used as a resource.

Syntax

nameID FONT [filename]

Parameters

nameID
Specifies a unique 16-bit unsigned integer value identifying the resource.
filename
Specifies the name of the file that contains the resource. The name must be a valid file name, and it must be a full path if the file is not in the current working directory. The path can either be a quoted or nonquoted string.

Example

The following code example shows how to specify a single font resource.

5 FONT CMROMAN.FNT


FONT Statement

This resource-definition statement sets the font that the system uses to draw text in the dialog box. The font must have been previously loaded, either from the Win.ini file or by calling the LoadResource function.

Syntax

FONT pointsize, “typeface”

Parameters

pointsize
Specifies the size, in points, of the font.
typeface
Specifies the name of the typeface. This name must be identical to the name defined in the [FONTS] section of Win.ini. This parameter must be enclosed in double quotes (“).

Example

The following code example shows how to use the FONT statement.

FONT 12, "MS Shell Dlg"

See Also

DIALOG, LoadResource


GROUPBOX Control

This resource-definition statement creates a group box control. The control is a rectangle that groups other controls together. The controls are grouped by drawing a border around them and displaying the specified text in the upper-left corner.

The GROUPBOX statement, which you can use only in a DIALOG statement, defines the text, identifier, dimensions, and attributes of a control window.

Syntax

GROUPBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies the control styles. This value can be a combination of the button class style BS_GROUPBOX and the WS_TABSTOP and WS_DISABLED styles.

If you do not specify a style, the default style is BS_GROUPBOX.

Remarks

When the style contains WS_TABSTOP or the text specifies an accelerator, tabbing or pressing the accelerator key moves the focus to the first control within the group.

Example

The following code example shows how to create a group box control that is labeled Options.

GROUPBOX "Options", 101, 10, 10, 100, 100

See Also

DIALOG


ICON Resource

This resource-definition statement specifies a bitmap that defines the shape of the icon to be used for either a specified application or an animated icon.

Syntax

nameID ICON filename

Parameters

nameID
Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.
filename
Specifies the name of the file that contains the resource. The name must be a valid file name, and it must be a full path if the file is not in the current working directory. The path can either be a quoted or nonquoted string.

Remarks

Icon and cursor resources can contain more than one image.

Example

The following code example shows how to specify two icon resources.

desk1 ICON desk.ico
11 ICON custom.ico


ICON Control

This resource-definition statement creates an icon control, which consists of an icon displayed in a dialog box. The ICON control statement, which you can use only in a DIALOG statement, defines the icon-resource identifier, icon-control identifier, position, and attributes of a control.

Syntax

ICON text, id, x, y, [[width, height, style [[, extended-style]]]]

Parameters

text
Specifies the name of an icon defined elsewhere in the resource file.
width
Ignored; set to zero.
height
Ignored; set to zero.
style
Specifies the control style. This parameter is optional. The only value that can be specified is the SS_ICON style, which is the default style whether this parameter is specified or not.

Example

The following code example shows how to create an icon control whose icon identifier is 901 and whose name is myicon.

ICON "myicon" 901, 30, 30

See Also

DIALOG, ICON


LANGUAGE Statement

This resource-definition statement specifies the language for all resources up to the next LANGUAGE statement or to the end of the file.

When the LANGUAGE statement appears before the beginning of the body of an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition, the specified language applies only to that resource.

Syntax

LANGUAGE language, sublanguage

Parameters

language
Language identifier. Must be one of the constants described in Primary Language Identifiers.
sublanguage
Sublanguage identifier. Must be one of the constants described in Secondary Language Identifiers.

See Also

ACCELERATORS, CHARACTERISTICS, DIALOG, MENU, RCDATA, STRINGTABLE, VERSION


LISTBOX Control

This resource-definition statement creates a list box for a dialog box or window. The control is a rectangle containing a list of strings, such as file names, from which the user can select.

The LISTBOX statement, which can only be used in a DIALOG or WINDOW statement, defines the identifier, dimensions, and attributes of a control window.

Syntax

LISTBOX id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies the control style. This value can be a combination of the list box class styles and the following styles: WS_BORDER and WS_VSCROLL.

If you do not specify a style, the default style is LBS_NOTIFY | WS_BORDER.

Remarks

For more information about the id, x, y, width, height, style, and extended-style parameters, see Common Control Parameters.

Example

The following code example shows how to create a list box control whose identifier is 101.

LISTBOX 101, 10, 10, 100, 100

See Also

COMBOBOX, DIALOG


LTEXT Control

This resource-definition statement creates a simple rectangle displaying left-aligned text. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. The LTEXT statement, which can be used only in a DIALOG statement, defines the text, identifier, dimensions, and attributes of the control.

Syntax

LTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies the control styles. This value can be any combination of the BS_RADIOBUTTON style and the following styles: SS_LEFT, WS_TABSTOP, and WS_GROUP.

If you do not specify a style, the default style is SS_LEFT | WS_GROUP.

Remarks

For more information about the text, id, x, y, width, height, style, and extended-style parameters, see Common Control Parameters.

Example

The following code example shows how to create a left-aligned text control that is labeled Filename.

LTEXT "Filename", 101, 10, 10, 100, 100

See Also

CONTROL, CTEXT, DIALOG, RTEXT


MENU Resource

This resource-definition statement specifies the contents of a menu resource, which is a collection of information that defines the appearance and function of an application menu. A menu is a special input tool that enables a user to select commands and open submenus from a list of menu items.

Syntax

menuID MENU [[optional-statements]] { item-definitions . . . }

Parameters

menuID
Specifies a number that identifies the menu. This value is either a unique string or a unique 16-bit unsigned integer value in the range of 1 to 65,535.
optional-statements
This parameter can be zero of more of the following statements:
CHARACTERISTICS dword
User-defined information about a resource that can be used by tools that read and write resource files. For more information, see CHARACTERISTICS.
LANGUAGE language, sublanguage
Specifies the language for the resource. For more information, see LANGUAGE.
VERSION dword
User-defined version number for the resource that can be used by tools that read and write resource files. For more information, see VERSION.

Example

The following code example shows a complete MENU statement.

sample MENU
{
 MENUITEM "&Soup", 100
 MENUITEM "S&alad", 101
 POPUP "&Entree"
 {
 MENUITEM "&Fish", 200
 MENUITEM "&Chicken", 201, CHECKED
 POPUP "&Beef"
 {
 MENUITEM "&Steak", 301
 MENUITEM "&Prime Rib", 302
 }
 }
 MENUITEM "&Dessert", 103
}

See Also

MENUEX, MENUITEM, POPUP, ACCELERATORS, CHARACTERISTICS, DIALOG, LANGUAGE, RCDATA, STRINGTABLE, VERSION


MENU Statement

This resource-definition statement sets the menu for a dialog box. If no statement is specified, the dialog box has no menu.

Syntax

MENU menuname

Parameters

menuname
Specifies the menu to use, either by the name or integer value of the menu.

Example

The following code example shows how to use the MENU dialog statement.

MENU errmenu


MENUEX Resource

This resource-definition statement is an extension of the MENU resource-definition statement that additionally supports the following:

  • Help identifiers on menus.
  • Identifiers on menus.
  • Use of the MFT_* type flags and MFS_* state flags. For more information about these flags, see the MENUITEMINFO structure.

Syntax

menuID MENUEX { [{[MENUITEM itemText [, [id] [, [type] [, state]]]] | [POPUP itemText [, [id] [, [type] [, [state] [, helpID]]]] { popupBody }

} ...] }

Parameters

MENUITEM statement
Defines a menu item. This statement consists of the following parameters:
itemText
String containing the text for the menu item. For more information, see MENUITEM.
id
Numeric expression indicating the identifier of the menu item.
type
Numeric expression indicating the type of the menu item To use the predefined MFT_* type values, include the following statement in your .rc file:

#include "Winuser.h"

state
A numeric expression indicating the state of the menu item To use the predefined MFS_* state values, include the following statement in your .rc file:

#include "Winuser.h"

POPUP statement
Defines a menu item that has a submenu associated with it. This statement consists of the same parameters as MENUITEM statement, as well as the following parameter:
helpID
Numeric expression indicating the identifier of the menu that is used during WM_HELP processing.
popupBody
Contains any combination of the MENUITEM and POPUP statements.

Remarks

The following valid operations can be contained in any of the numeric expressions in the statements of MENUEX:

  • Add (‘+’)
  • Subtract (‘-’)
  • Unary minus (‘-’)
  • Unary NOT (‘~’)
  • AND (‘&’)
  • OR (‘|’)

See Also

MENU, MENUITEM, POPUP, ACCELERATORS, CHARACTERISTICS, DIALOG, LANGUAGE, RCDATA, STRINGTABLE, VERSION


MENUITEM Statement

This resource-definition statement creates a menu item.

Syntax

MENUITEM text, result, [[optionlist]] MENUITEM SEPARATOR

Parameters

text
String that indicates the name of the menu item.

The string can contain the escape characters \t and \a. The \t character inserts a tab in the string and is used to align text in columns. Tab characters should be used only in menus, not in menu bars. The \a character aligns all text that follows it flush right to the menu bar or pop-up menu.

For information about menus, see POPUP Resource.

result
Specifies the result generated when the user selects the menu item. This parameter takes and returns an integer value. When the user selects the menu-item name, the result is sent to the window that owns the menu.
optionlist
Specifies the appearance of the menu item. This optional parameter can be one or more of the following redefined menu options, separated by commas or spaces:
CHECKED
Menu item has a check mark next to it.
GRAYED
Menu item is initially inactive and appears on the menu in gray or a lightened shade of the menu text color. This option cannot be used with the INACTIVE option.
HELP
Identifies a Help item.
INACTIVE
Menu item is displayed but it cannot be selected. This option cannot be used with the GRAYED option.
MENUBARBREAK
This option is the same as MENUBREAK except that for pop-up menus, MENUBARBREAK separates the new column from the old column with a vertical line.
MENUBREAK
For static menu bar items, MENUBREAK places the menu item on a new line. For menus, MENUBREAK places the menu item in a new column with no dividing line between the columns.
MENUITEM SEPARATOR
This implementation of the MENUITEM statement creates an inactive menu item that serves as a dividing bar between two active menu items on a menu.

Example

The following code example shows how to use the MENUITEM and MENUITEM SEPARATOR statements.

MENUITEM "&Roman", 206, CHECKED, GRAYED
MENUITEM SEPARATOR
MENUITEM "&Blackletter", 301

See Also

MENU, POPUP


MESSAGETABLE Resource

This resource-definition statement defines the identifier and file of an application’s message table resource. Message tables are special string resources used in event logging and with the FormatMessage function. The file contains a binary message table generated by the message compiler, MC.exe.

The message compiler also generates a resource script file that contains the MESSAGETABLE statements you need to include the message table resources in the compiled resource file. Use the #include directive to include this resource script into your main resource script.

Syntax

nameID MESSAGETABLE filename

Parameters

nameID
Specifies either a unique name or a 16-bit unsigned integer value identifying the resource.
filename
Specifies the name of the file that contains the resource. The name must be a valid file name, and it must be a full path if the file is not in the current working directory. The path can either be a quoted or nonquoted string.

See Also

Creating Message Text Files, STRINGTABLE


POPUP Resource

This resource-definition statement creates a menu item that can contain menu items and submenus.

Syntax

POPUP text, [[optionlist]] { item-definitions . . . }

Parameters

text
String that contains the name of the menu. This string must be enclosed in double quotation marks (“).
optionlist
Specifies the appearance of the menu item. This optional parameter can be one or more of the following redefined menu options, separated by commas or spaces:
CHECKED
Menu item has a check mark next to it. This option is not valid for a top-level menu.
GRAYED
Menu item is initially inactive and appears on the menu in gray or a lightened shade of the menu text color. This option cannot be used with the INACTIVE option.
HELP
Identifies a Help item.
INACTIVE
Menu item is displayed but it cannot be selected. This option cannot be used with the GRAYED option.
MENUBARBREAK
This option is the same as MENUBREAK except that for pop-up menus, MENUBARBREAK separates the new column from the old column with a vertical line.
MENUBREAK
For static menu bar items, MENUBREAK places the menu item on a new line. For menus, MENUBREAK places the menu item in a new column with no dividing line between the columns.

Example

The following code example shows how to use the POPUP statement.

chem MENU
{
 POPUP "&Elements"
 {
 MENUITEM "&Oxygen", 200
 MENUITEM "&Carbon", 201, CHECKED
 MENUITEM "&Hydrogen", 202
 MENUITEM SEPARATOR
 MENUITEM "&Sulfur", 203
 MENUITEM "Ch&lorine", 204
 }
 POPUP "&Compounds"
 {
 POPUP "&Sugars"
 {
 MENUITEM "&Glucose", 301
 MENUITEM "&Sucrose", 302, CHECKED
 MENUITEM "&Lactose", 303, MENUBREAK
 MENUITEM "&Fructose", 304
 }
 POPUP "&Acids"
 {
 "&Hydrochloric", 401
 "&Sulfuric", 402
 }
 }
}

See Also

MENU, MENUITEM


PUSHBOX Control

This resource-definition statement creates a push box control, which is identical to a PUSHBUTTON control except that it does not display a button face or frame; only the text appears.

Syntax

PUSHBOX text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies styles for the pushbox, which can be a combination of the BS_PUSHBOX style and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

If you do not specify a style, the default style is BS_PUSHBOX | WS_TABSTOP.

See Also

PUSHBUTTON


PUSHBUTTON Control

This resource-definition statement creates a push button control. The control is a round-cornered rectangle containing the specified text, whichis centered in the control. The control sends a message to its parent whenever the user selects the control.

Syntax

PUSHBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies styles for the push button, which can be a combination of the BS_PUSHBUTTON style and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

If you do not specify a style, the default style is BS_PUSHBUTTON | WS_TABSTOP.

Example

The following code example shows how to use the PUSHBUTTON statement.

PUSHBUTTON "ON", 7, 10, 10, 20, 10

See Also

GetDialogBaseUnits


RADIOBUTTON Control

This resource-definition statement creates a radio button control. The control is a small circle with the specified text typically positioned to the right of the circle. The control highlights the circle and sends a message to its parent window when the user selects the button. The control removes the highlight and sends a message the next time the button is selected.

Syntax

RADIOBUTTON text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies styles for the radio button, which can be a combination of BUTTON class styles and the following styles: WS_TABSTOP, WS_DISABLED, and WS_GROUP.

If you do not specify a style, the default style is BS_RADIOBUTTON | WS_TABSTOP.

Example

The following code example shows how to use the RADIOBUTTON statement.

RADIOBUTTON "Italic", 100, 10, 10, 40, 10

See Also

GetDialogBaseUnits


RCDATA Resource

This resource-definition statement specifies a raw data resource for an application. Raw data resources permit the inclusion of binary data directly in the executable file.

Syntax

nameID RCDATA [[optional-statements]] { raw-data . . . }

Parameters

nameID
Specifies either a unique name or a 16-bit unsigned integer value that identifies the resource.
optional-statements
Specifies options for an RCDATA resource. It can be zero or more of the following statements:
CHARACTERISTICS dword
User-defined information about a resource that can be used by tools that read and write resource files. For more information, see CHARACTERISTICS.
LANGUAGE language, sublanguage
Specifies the language for the resource. For more information, see LANGUAGE.
VERSION dword
User-defined version number for the resource that can be used by tools that read and write resource files. For more information, see VERSION.
raw-data
Specifies raw data consisting of one or more integers or strings of characters. Integers can be specified in decimal, octal, or hexadecimal format. To be compatible with 16-bit Windows, integers are stored as WORD values. You can store an integer as a DWORD value by qualifying the integer with the L suffix.

Strings are enclosed in quotation marks. The Resource Compiler (RC) does not automatically append a terminating null character to a string. Each string is a sequence of the specified ANSI characters, unless you qualify it as a wide-character string with the L prefix.

The block of data begins on a DWORD boundary and the RC performs no padding or alignment of data within the raw-data block. It is your responsibility to ensure the proper alignment of data within the block.

Example

The following code example shows how to use the RCDATA statement.

resname RCDATA
{
 “Here is an ANSI string\0”, // explicitly null-terminated
 L"Here is a Unicode string\0", // explicitly null-terminated
 1024, // integer, stored as WORD
 7L, // integer, stored as DWORD
 0x029a, // hex integer
 0o733, // octal integer
}

See Also

ACCELERATORS, CHARACTERISTICS, DIALOG, LANGUAGE, MENU, STRINGTABLE, VERSION


RTEXT Control

This resource-definition statement creates a simple rectangle displaying right-aligned text. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line.

Syntax

RTEXT text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies styles for the text control, which can be either WS_TABSTOP or WS_GROUP, or both..

If you do not specify a style, the default style is SS_RIGHT | WS_GROUP.

Example

The following code example shows how to use the RTEXT statement.

RTEXT "Number of Messages", 4, 30, 50, 100, 10

See Also

CONTROL, CTEXT, DIALOG, LTEXT


SCROLLBAR Control

This resource-definition statement creates a scroll bar control. The control is a rectangle that contains a scroll box and has direction arrows at both ends. The scroll bar control sends a notification message to its parent whenever the user selects the control. The parent is responsible for updating the scroll-box position. Scroll bar controls can be positioned anywhere in a window and used whenever needed to provide scrolling input.

Syntax

SCROLLBAR text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

style
Specifies styles for the scroll bar, which can be a combination—or none—of the SCROLLBAR class styles and the following styles: WS_TABSTOP, WS_GROUP, and WS_DISABLED.

If you do not specify a style, the default style is SBS_HORZ.

Example

The following code example shows how to use the SCROLLBAR statement.

SCROLLBAR 999, 25, 30, 10, 100


STATE3 Control

This resource-definition statement defines a three-state check box control. The control is identical to a CHECKBOX, except that it has three states: checked, unchecked, and disabled (grayed).

Syntax

STATE3 text, id, x, y, width, height [[, style [[, extended-style]]]]

Parameters

text
Specifies text that is displayed to the right of the control.
style
Specifies the control styles. This value can be a combination of the button class style BS_3STATE and the WS_TABSTOP and WS_GROUP styles.

If you do not specify a style, the default style is BS_3STATE | WS_TABSTOP.

See Also

AUTOCHECKBOX, CHECKBOX, CONTROL


STRINGTABLE Resource

This resource-definition statement specifies one or more string resources for an application. String resources are null-terminated Unicode strings that can be loaded as needed from the executable file, using the LoadString function.

Syntax

STRINGTABLE [[optional-statements]] { stringID string . . . }

Parameters

optional-statements
Specifies options for a STRINGTABLE resource. It can be zero or more of the following statements:
CHARACTERISTICS dword
User-defined information about a resource that can be used by tools that read and write resource files. For more information, see CHARACTERISTICS.
LANGUAGE language, sublanguage
Specifies the language for the resource. For more information, see LANGUAGE.
VERSION dword
User-defined version number for the resource that can be used by tools that read and write resource files. For more information, see VERSION.
stringID
Specifies an unsigned 16-bit integer that identifies the resource.
string
Specifies one or more strings, enclosed in double quotation marks. The string must be no longer than 4,097 characters and must occupy a single line in the source file. To add a carriage return to the string, use this character sequence: \012. For example, “Line one\012Line two” defines a string that is displayed as follows:
Line one
Line two

Example

The following code example shows how to use the STRINGTABLE statement.

#define IDS_HELLO 1
#define IDS_GOODBYE 2

STRINGTABLE
{
 IDS_HELLO, "Hello"
 IDS_GOODBYE, "Goodbye"
}

See Also

LoadString, ACCELERATORS, CHARACTERISTICS, DIALOG, LANGUAGE, MENU, RCDATA, VERSION


STYLE Statement

This resource-definition statement sets the window style of the dialog box. The window style specifies whether the box is a pop-up or a child window.

Syntax

STYLE style

Parameters

style
Specifies the window style. This parameter takes an integer value or one of the following predefined names:
DS_LOCALEDIT
Specifies that edit controls in the dialog box use memory in the application’s data section. By default, all edit controls in dialog boxes use memory outside the application’s data section. This feature can be suppressed by adding the DS_LOCALEDIT flag to the STYLE command for the dialog box. If this flag is not used, do not use the EM_GETHANDLE and EM_SETHANDLE messages.
DS_MODALFRAME
Creates a dialog box with a modal dialog box frame that can be combined with a title bar and window menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOIDLEMSG
Suppresses WM_ENTERIDLE messages that the system would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_SYSMODAL
Create a dialog box with the WS_EX_TOPMOST flag. This flag cannot be combined with the DS_CONTROL style. This flag is obsolete and is included for compatibility with 16-bit versions of Windows.
WS_BORDER
Creates a window that has a border.
WS_CAPTION
Creates a window that has a title bar, which implies the WS_BORDER style.
WS_CHILD
Creates a child window. It cannot be used with the WS_POPUP style.
WS_CHILDWINDOW
Creates a child window that has the WS_CHILD style.
WS_CLIPCHILDREN
Excludes the area occupied by child windows when drawing within the parent window. Used when creating the parent window.
WS_CLIPSIBLINGS
Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, this style clips all other top-level child windows out of the region of the child window to be updated. When drawing in the client area of a child window, if the WS_CLIPSIBLINGS style is not specified and child windows overlap, it is possible to draw in the client area of a neighboring child window. For use with the WS_CHILD style only.
WS_DISABLED
Creates a window that is initially disabled.
WS_DLGFRAME
Creates a window with a modal dialog box frame but no title.
WS_GROUP
Specifies the first control of a group of controls in which the user can move from one control to the next by using the arrow keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the style group and starts the next group. This style is valid only for controls.
WS_HSCROLL
Creates a window that has a horizontal scroll bar.
WS_ICONIC
Creates a window that is initially iconic. For use with the WS_OVERLAPPED style only.
WS_MAXIMIZE
Creates a window of maximum size.
WS_MAXIMIZEBOX
Creates a window that has a maximize button.
WS_MINIMIZE
Creates a window of minimum size.
WS_MINIMIZEBOX
Creates a window that has a minimize button.
WS_OVERLAPPED
Creates an overlapped window. An overlapped window has a caption and a border.
WS_OVERLAPPEDWINDOW
Creates an overlapped window having the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles.
WS_POPUP
Creates a pop-up window. It cannot be used with the WS_CHILD style.
WS_POPUPWINDOW
Creates a pop-up window that has the WS_POPUP, WS_BORDER, and WS_SYSMENU styles. The WS_CAPTION style must be combined with the WS_POPUPWINDOW style to make the System menu visible.
WS_SIZEBOX
Creates a window that has a size box. Used only for windows with a title bar or with vertical and horizontal scroll bars.
WS_SYSMENU
Creates a window that has a window menu in its title bar. Used only for windows with title bars. If used with a child window, this style creates a Close button instead of a window menu.
WS_TABSTOP
Specifies one of any number of controls through which the user can move by using the TAB key. The TAB key moves the user to the next control specified by the WS_TABSTOP style. This style is valid only for controls.
WS_THICKFRAME
Creates a window with a thick frame that can be used to size the window.
WS_VISIBLE
Creates a window that is initially visible. This applies to overlapping and pop-up windows. For overlapping windows, the y parameter is used as a parameter for the ShowWindow function.
WS_VSCROLL
Creates a window that has a vertical scroll bar.

The default style is WS_POPUP | WS_BORDER | WS_SYSMENU.

Remarks

If the predefined names are used, you must include the header file, Windows.h.


User-Defined Resource

A user-defined resource-definition statement specifies a resource that contains application-specific data. The data can have any format and can be defined either as the content of a file or as a series of numbers and strings.

Syntax

nameID typeID filename

The filename specifies the name of a file containing the binary data of the resource. The contents of the file are included as the resource. The Resource Compiler (RC) does not interpret the binary data in any way. It is your responsibility to ensure that the data is properly aligned for the target computer architecture.

A user-defined resource can also be defined completely in the resource script using the following syntax:

nameID typeID { raw-data }

Parameters

nameID
Specifies either a unique name or a 16-bit unsigned integer that identifies the resource.
typeID
Specifies either a unique name or a 16-bit unsigned integer that identifies the resource type. If a number is specified, it must be greater than 255. The numbers 1 through 255 are reserved for existing and future redefined resource types.
filename
Specifies the name of the file that contains the resource data. The parameter must be a valid file name, and it must be a full path if the file is not in the current working directory.
raw-data
Specifies raw data consisting of one or more integers or strings of characters. Integers can be specified in decimal, octal, or hexadecimal format. To be compatible with 16-bit Windows, integers are stored as WORD values. You can store an integer as a DWORD value by qualifying the integer with the L suffix.

Strings are enclosed in quotation marks. The Resource Compiler (RC) does not automatically append a terminating null character to a string. Each string is a sequence of the specified ANSI characters, unless you qualify it as a wide-character string with the L prefix.

The block of data begins on a DWORD boundary and RC performs no padding or alignment of data within the raw-data block. It is your responsibility to ensure the proper alignment of data within the block.

Example

The following code example shows several user-defined statements.

array MYRES data.res
14 300 custom.res
18 MYRES2
{
 “Here is an ANSI string\0”, // explicitly null-terminated
 L"Here is a Unicode string\0", // explicitly null-terminated
 1024, // integer, stored as WORD
 7L, // integer, stored as DWORD
 0x029a, // hex integer
 0o733, // octal integer
}


VERSION Statement

This resource-definition statement specifies version information about a resource that can be used by tools that read and write resource files.

The VERSION statement appears before the beginning of the body of an ACCELERATORS, DIALOG, MENU, RCDATA, or STRINGTABLE resource definition. The specified value applies only to that resource.

Syntax

VERSION dword

Parameters

dword
User-defined DWORD value.

Remarks

The specified dword value appears with the resource in the compiled .res file. However, the value is not stored in the executable file and has no significance to the system.

See Also

ACCELERATORS, CHARACTERISTICS, DIALOG, LANGUAGE, MENU, RCDATA, STRINGTABLE


VERSIONINFO Resource

This resource-definition statement creates a version-information resource. The resource contains such information about the file as its version number, its intended operating system, and its original file name. The resource is intended to be used with the File Installation library functions.

Syntax

versionID VERSIONINFO fixed-info { block-statement . . . }

Parameters

versionID
Specifies the version-information resource identifier. This value must be 1.
fixed-info
Specifies the version information, such as the file version and the intended operating system. This parameter consists of the following statements:
FILEVERSION version
Specifies the binary version number for the file. The version consists of two 32-bit integers, defined by four 16-bit integers. For example, “FILEVERSION 3,10,0,61” is translated into two doublewords: 0x0003000a and 0x0000003d, in that order. Therefore, if version is defined by the DWORD values dw1 and dw2, they need to appear in the FILEVERSION statement as follows: HIWORD(dw1), LOWORD(dw1), HIWORD(dw2), LOWORD(dw2).
PRODUCTVERSION version
Specifies the binary version number for the product with which the file is distributed. The version parameter is two 32-bit integers, defined by four 16-bit integers.
FILEFLAGSMASK fileflagsmask
Specifies which bits in the FILEFLAGS statement are valid. If a bit is set in FILEFLAGMASK, the corresponding bit in FILEFLAGS is valid.
FILEFLAGS fileflags
Specifies the Boolean attributes of the file. The fileflags parameter must be the combination of all the file flags that are valid at compile time. For possible values, see Remarks.
FILEOS fileos
Specifies the operating system for which this file was designed. The fileos parameter is one of the operating system values listed in Remarks.
FILETYPE filetype
Specifies the general type of file. The filetype parameter can be one of the file type values listed in Remarks.
FILESUBTYPE subtype
Specifies the function of the file. The subtype parameter is zero unless the type parameter in the FILETYPE statement is VFT_DRV, VFT_FONT, or VFT_VXD. For possible file subtype values, see Remarks.
block-statement
Specifies one or more version-information blocks. A block can contain string information or variable information.

Remarks

To use the constants specified with the VERSIONINFO statement. The Winver.h file, included in Windows.h, must be included in the resource-definition file.

The following list describes the parameters used in the VERSIONINFO statement:

fileflags
Specifies a combination of the following values:
VS_FF_DEBUG
File contains debugging information or is compiled with debugging features enabled.
VS_FF_PATCHED
File has been modified and is not identical to the original shipping file of the same version number.
VS_FF_PRERELEASE
File is a development version, not a commercially released product.
VS_FF_PRIVATEBUILD
File was not built using standard release procedures. If this value is specified, the StringFileInfo block must contain a PrivateBuild string.
VS_FF_SPECIALBUILD
File was built by the original company using standard release procedures, but is a variation of the standard file of the same version number. If this value is specified, the StringFileInfo block must contain a SpecialBuild string.
fileos
Specifies one of the following values:
VOS_UNKNOWN
The operating system for which the file was designed is unknown.
VOS_DOS
File was designed for MS-DOS.
VOS_NT
File was designed for Windows NT.
VOS__WINDOWS16
File was designed for 16-bit Windows.
VOS__WINDOWS32
File was designed for 32-bit Windows.
VOS_DOS_WINDOWS16
File was designed for 16-bit Windows running with MS-DOS.
VOS_DOS_WINDOWS32
File was designed for 32-bit Windows running with MS-DOS.
VOS_NT_WINDOWS32
File was designed for 32-bit Windows running with Windows NT.

The values 0x00002L, 0x00003L, 0x20000L and 0x30000L are reserved.

filetype
Specifies one of the following values:
VFT_UNKNOWN
File type is unknown.
VFT_APP
File contains an application.
VFT_DLL
File contains a dynamic-link library (DLL).
VFT_DRV
File contains a device driver. If filetype is VFT_DRV, subtype contains a more specific description of the driver.
VFT_FONT
File contains a font. If filetype is VFT_FONT, subtype contains a more specific description of the font.
VFT_VXD
File contains a virtual device.
VFT_STATIC_LIB
File contains a static-link library.

All other values are reserved for use by Microsoft.

subtype
Specifies additional information about the file type.

If filetype specifies VFT_DRV, this parameter can be one of the following values:

VFT2_UNKNOWN
Driver type is unknown.
VFT2_DRV_COMM
File contains a communications driver.
VFT2_DRV_PRINTER
File contains a printer driver.
VFT2_DRV_KEYBOARD
File contains a keyboard driver.
VFT2_DRV_LANGUAGE
File contains a language driver.
VFT2_DRV_DISPLAY
File contains a display driver.
VFT2_DRV_MOUSE
File contains a mouse driver.
VFT2_DRV_NETWORK
File contains a network driver.
VFT2_DRV_SYSTEM
File contains a system driver.
VFT2_DRV_INSTALLABLE
File contains an installable driver.
VFT2_DRV_SOUND
File contains a sound driver.

If filetype specifies VFT_FONT, this parameter can be one of the following values:

VFT2_UNKNOWN
Font type is unknown.
VFT2_FONT_RASTER
File contains a raster font.
VFT2_FONT_VECTOR
File contains a vector font.
VFT2_FONT_TRUETYPE
File contains a TrueType font.

If filetype specifies VFT_VXD, this parameter must be the virtual-device identifier included in the virtual-device control block.

All subtype values not listed here are reserved for use by Microsoft.

langID
Specifies one of the following language codes:
Code
Language
Code
Language
0x0401 | Arabic | 0x0415 | Polish
0x0402 | Bulgarian | 0x0416 | Brazilian Portuguese
0x0403 | Catalan | 0x0417 | Rhaeto-Romanic
0x0404 | Traditional Chinese | 0x0418 | Romanian
0x0405 | Czech | 0x0419 | Russian
0x0406 | Danish | 0x041A | Croato-Serbian (Latin)
0x0407 | German | 0x041B | Slovak
0x0408 | Greek | 0x041C | Albanian
0x0409 | U.S. English | 0x041D | Swedish
0x040A | Castilian Spanish | 0x041E | Thai
0x040B | Finnish | 0x041F | Turkish
0x040C | French | 0x0420 | Urdu
0x040D | Hebrew | 0x0421 | Bahasa
0x040E | Hungarian | 0x0804 | Simplified Chinese
0x040F | Icelandic | 0x0807 | Swiss German
0x0410 | Italian | 0x0809 | U.K. English
0x0411 | Japanese | 0x080A | Mexican Spanish
0x0412 | Korean | 0x080C | Belgian French
0x0413 | Dutch | 0x0C0C | Canadian French
0x0414 | Norwegian – Bokml | 0x100C | Swiss French
0x0810 | Swiss Italian | 0x0816 | Portuguese
0x0813 | Belgian Dutch | 0x081A | Serbo-Croatian (Cyrillic)
0x0814 | Norwegian – Nynorsk

charsetID
Specifies one of the following character set identifiers:
Identifier
Character Set
0 | 7-bit ASCII
932 | Japan (Shift – JIS X-0208)
949 | Korea (Shift – KSC 5601)
950 | Taiwan (Big5)
1200 | Unicode
1250 | Latin-2 (Eastern European)
1251 | Cyrillic
1252 | Multilingual
1253 | Greek
1254 | Turkish
1255 | Hebrew
1256 | Arabic

string-name
Specifies one of the following predefined names:
Comments
Specifies additional information that should be displayed for diagnostic purposes.
CompanyName
Specifies the company that produced the file—for example, “Microsoft Corporation” or “Standard Microsystems Corporation, Inc.” This string is required.
FileDescription
Specifies a file description to be presented to users. This string may be displayed in a list box when the user is choosing files to install—for example, “Keyboard Driver for AT-Style Keyboards”. This string is required.
FileVersion
Specifies the version number of the file—for example, “3.10” or “5.00.rc2”. This string is required.
InternalName
Specifies the internal name of the file, if one exists—for example, a module name if the file is a DLL. If the file has no internal name, this string should be the original file name, without extension. This string is required.
LegalCopyright
Specifies all copyright notices that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, and so on—for example, “Copyright © Microsoft Corporation 1990–1998”. This string is optional.
LegalTrademarks
Specifies all trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. This string is optional.
OriginalFilename
Specifies the original name of the file, not including a path. This information enables an application to determine whether a file has been renamed by a user. The format of the name depends on the file system for which the file was created. This string is required.
PrivateBuild
Specifies information about a private version of the file—for example, “Built by TESTER1 on \TESTBED”. This string should be present only if VS_FF_PRIVATEBUILD is specified in the fileflags parameter of the root block.
ProductName
Specifies the name of the product with which the file is distributed. This string is required.
ProductVersion
Specifies the version of the product with which the file is distributed—for example, “3.10” or “5.00.rc2”. This string is required.
SpecialBuild
Specifies how this version of the file differs from the standard version. This string should be present only if VS_FF_SPECIALBUILD is specified in the fileflags parameter of the root block.


Common Control Parameters

The following describes the general syntax for a control resource-definition statement, represented by control. Occasionally, a statement uses a parameter differently, or may ignore a parameter. The statement-specific variation is described in the documentation for the statement.

Syntax

control [[text,]] id, x, y, width, height [[, style [[, extended-style]]]][, helpId]

[{ data-element-1 [, data-element-2 [, ... ]] }]

Parameters

text
Specifies text that is displayed with the control. The text is positioned within the control’s specified dimensions or adjacent to the control.

This parameter must contain zero or more characters enclosed in double quotation marks (“). Strings are automatically null-terminated and converted to Unicode in the resulting resource file.

By default, the characters listed between the double quotation marks are ANSI characters, and escape sequences are interpreted as byte escape sequences. If the string is preceded by the L prefix, the string is a wide-character string and escape sequences are interpreted as 2-byte escape sequences that specify Unicode characters. If a double quotation mark is required in the text, you must include the double quotation mark twice.

An ampersand (&) character in the text indicates that the following character is used as a mnemonic character for the control. When the control is displayed, the ampersand is not shown, but the mnemonic character is underlined. The user can choose the control by pressing the key corresponding to the underlined mnemonic character. To use the ampersand as a character in a string, insert two ampersands (&&).

id
Specifies the control identifier. This value must be a 16-bit unsigned integer in the range 0 through 65,535 or a simple arithmetic expression that evaluates to a value in that range.
x
Specifies the x-coordinate of the left side of the control relative to the left side of the dialog box. This value must be a 16-bit unsigned integer in the range 0 through 65,535. The coordinate is in dialog units and is relative to the origin of the dialog box, window, or control containing the specified control.
y
Specifies the y-coordinate of the top side of the control relative to the top of the dialog box. This value must be a 16-bit unsigned integer in the range 0 through 65,535. The coordinate is in dialog units relative to the origin of the dialog box, window, or control containing the specified control.
width
Specifies the width of the control. This value must be a 16-bit unsigned integer in the range 1 through 65,535. The width is in 1/4-character units.
height
Specifies the height of the control. This value must be a 16-bit unsigned integer in the range 1 through 65,535. The height is in 1/8-character units.
style
Specifies the control styles. Use the bitwise OR (|) operator to combine styles.
extended-style
Specifies extended window styles. You must specify style to specify extended-style. For more information about extended styles, see EXSTYLE.
helpID
Specifies a numeric expression indicating the identifier of the control during WM_HELP processing.
controlData
Specifies the control-specific data for the control. When a dialog box is created, if it contains a control that has control-specific data, a pointer to that data is passed into the control’s window procedure by means of the lParam of the WM_CREATE message for that control.

Remarks

Horizontal dialog units are 1/4 of the dialog base width unit. Vertical units are 1/8 of the dialog base height unit. The current dialog base units are computed from the height and width of the current system font. The GetDialogBaseUnits function returns the dialog base units in pixels. The coordinates are relative to the origin of the dialog box.


Common Resource Attributes

The resource-definition statements supported on 16-bit Windows include a load-mem option that specifies the loading and memory characteristics of the resource. The resource statements supported on 32-bit Windows do not use any of these attributes. However, the attributes are permitted in resource scripts for backward compatibility. Win32 resources are loaded when the corresponding module is loaded, and are freed when the module is unloaded. These attributes are ignored.

These attributes are divided into two groups: load attributes and memory attributes.

The load attributes specify when the resource is to be loaded. The following table shows the parameters to use when creating load attributes.

Attribute
Description
PRELOAD | Ignored. In 16-bit Windows, the resource is loaded with the executable file.
LOADONCALL | Ignored. In 16-bit Windows, the resource is loaded when called.

The memory attributes specify whether the resource is fixed or movable, whether it can be discarded, and whether it is pure. The following table shows the supported memory parameters.

Attribute
Description
FIXED | Ignored. In 16-bit Windows, the resource remains at a fixed memory location.
MOVEABLE | Ignored. In 16-bit Windows, the resource can be moved if necessary to compact memory.
DISCARDABLE | Ignored. In 16-bit Windows, the resource can be discarded if no longer needed.
PURE | Ignored. Accepted for compatibility with existing resource scripts.
IMPURE | Ignored. Accepted for compatibility with existing resource scripts.


Sample Resource-Definition File

The following code example shows a script file that defines the resources for an application named Shapes.

#include "shapes.h"

ShapesCursor CURSOR SHAPES.CUR
ShapesIcon ICON SHAPES.ICO

ShapesMenu MENU
{
 POPUP "&Shape"
 {
 MENUITEM "&Clear", ID_CLEAR
 MENUITEM "&Rectangle", ID_RECT
 MENUITEM "&Triangle", ID_TRIANGLE
 MENUITEM "&Star", ID_STAR
 MENUITEM "&Ellipse", ID_ELLIPSE
 }
}

The CURSOR statement names the application’s cursor resource ShapesCursor and specifies the cursor file Shapes.cur, which contains the image for that cursor.

The ICON statement names the application’s icon resource ShapesIcon and specifies the icon file Shapes.ico, which contains the image for that icon.

The MENU statement defines an application menu named ShapesMenu, a pop-up menu with five menu items.

The body of the menu definition, enclosed by the curly braces or the BEGIN and END keywords, specifies each menu item and the menu identifier that is returned when the user selects that item. For example, the first item on the menu, Clear, returns the menu identifier ID_CLEAR when the user selects it. The menu identifiers are defined in the application header file, Shapes.h.


Window and Control Styles

Window and control styles are attributes that are controlled by specific style flags. There are also extended styles that have their own set of flags. This section includes the following styles:

  • Window and Message Box Styles
  • Control Styles


Window and Message Box Styles

The following table shows window styles that are supported by Windows CE.

Basic window styles
 Description
WS_CHILD | Specifies a child window. This should not be changed after the window is created.
WS_CLIPCHILDREN | Excludes the area occupied by child windows when drawing occurs within the parent window. This style is used on the parent window. Windows CE–windows always have the WS_CLIPCHILDREN style.
WS_CLIPSIBLINGS | Excludes the area that is occupied by sibling windows above a window.
WS_DISABLED | Specifies a window that is initially disabled. A disabled window cannot receive input from the user.
WS_EX_NOACTIVATE | Specifies that a window cannot be activated. If a child window has this style, tapping it does not cause its top-level parent to activate. Although a window that has this style will still receive stylus events, neither it nor its child windows can get the focus. This style is supported only by the Windows CE operating system (OS).
WS_EX_NOANIMATION Prevents a window from showing animated exploding and imploding rectangles and from having a button on the taskbar. This style is supported only by
Windows CE.
WS_EX_NODRAG | Specifies a stationary window that cannot be dragged by its title bar. This style is supported only by Windows CE.
WS_EX_TOPMOST | Creates a window that will be placed and remain above all non-topmost windows. To add or remove this style, use the SetWindowPos function.
WS_GROUP | Specifies the first control of a group of controls. This style is used primarily when creating dialog boxes. The group consists of this first control and all controls that are defined after it, up to the next control for which the WS_GROUP style is specified. Because the first control in each group often has the WS_TABSTOP style, a user can move from group to group.
WS_POPUP | Specifies a pop-up window. This style should not be changed after the window is created.
WS_TABSTOP | Specifies a control that can receive the keyboard focus when the user presses the TAB key. This style is used primarily when creating controls in a dialog box. Pressing the TAB key changes the keyboard focus to the next control with the WS_TABSTOP style.
WS_VISIBLE | Specifies a window that is initially visible. This style can be turned on and off to change window visibility.

Non-client area styles
 Description
WS_BORDER | Specifies a window with a thin-line border.
WS_CAPTION | Specifies a window with a title bar and border.
WS_DLGFRAME | Specifies a window with a dialog box border style. A window with this style cannot have a title bar.
WS_EX_CAPTIONOKBTN | Includes an OK button in the title bar.
WS_EX_CLIENTEDGE | Specifies a window with a border that has a sunken edge.
WS_EX_CONTEXTHELP | Includes a Help button (?) in the title bar of the window.
WS_EX_DLGMODALFRAME | Specifies a window with a double border.
WS_EX_OVERLAPPEDWINDOW | Combines the WS_EX_CLIENTEDGE and WS_EX_WINDOWEDGE styles.
WS_EX_STATICEDGE | Specifies a window with a three-dimensional border style. This style should be used for items that do not accept user input.
WS_EX_WINDOWEDGE | Specifies a window border with a raised edge.
WS_HSCROLL | Specifies a window with a horizontal scroll bar.
WS_OVERLAPPED | Specifies a window with the WS_BORDER and WS_CAPTION styles.
WS_SYSMENU | Specifies a window with a window menu on its title bar. Use in conjunction with the WS_CAPTION style. Windows CE does not have a system menu, but you can use the WS_SYSMENU style to add the standard Close (X) button to a window title bar.
WS_VSCROLL | Specifies a window with a vertical scroll bar.

The following table shows message box styles that are supported by Windows CE.

Button styles
 Description
MB_ABORTRETRYIGNORE | Specifies that the message box contains three buttons: Abort, Retry, and Ignore.
MB_DEFBUTTON1 | Specifies that the first button is the default button. The first button is always the default unless you specify MB_DEFBUTTON2.
MB_DEFBUTTON2 | Specifies that the second button is the default button.
MB_DEFBUTTON3 | Specifies that the third button is the default button.
MB_OK | Specifies that the message box contains one button: OK.
MB_OKCANCEL | Specifies that the message box contains two buttons: OK and Cancel.
MB_RETRYCANCEL | Specifies that the message box contains two buttons: Retry and Cancel.
MB_YESNO | Specifies that that the message box contains two buttons: Yes and No.
MB_YESNOCANCEL | Specifies that the message box contains three buttons: Yes, No, and Cancel.

Icon styles
 Description
MB_ICONASTERISK
MB_ICONINFORMATION 		Includes an icon consisting of a lowercase letter i in a circle in the message box.
MB_ICONERROR
MB_ICONHAND
MB_ICONSTOP 		Includes a stop-sign icon in the message box.
MB_ICONEXCLAMATION
MB_ICONWARNING 		Includes an exclamation-point icon in the message box.
MB_ICONQUESTION Includes a question-mark icon in the message box.

Window styles
 Description
MB_APPLMODAL Specifies that the user must respond to the message box before continuing work in the window that is identified by the hWnd parameter. However, the user can move to the windows of other applications and work in those windows.

Depending on the hierarchy of windows in the application, the user might be able to move to other windows within the application. All child windows of the message box’s parent window are automatically disabled, but pop-up windows are not.

MB_APPLMODAL is the default value.
Windows CE does not support either MB_SYSTEMMODAL or MB_TASKMODAL.

MB_SETFOREGROUND | Specifies that the message box becomes the foreground window.
MB_TOPMOST | Creates the message box with the WS_EX_TOPMOST window style.


Control Styles

The following table shows window control styles that are supported by Windows CE.

Check box styles
 Description
BS_3STATE | Creates a check box in which the box can be unavailable as well as selected or cleared. Use the unavailable state to show that the state of the check box is not determined.
BS_AUTO3STATE | Creates a three-state check box in which the state cycles through selected, unavailable, and cleared each time the user selects the check box.
BS_AUTOCHECKBOX | Creates a check box in which the check state switches between selected and cleared each time the user selects the check box.
BS_CHECKBOX | Creates a small, empty check box with a label displayed to the right of it. To display the text to the left of the check box, combine this flag with the BS_RIGHTBUTTON style.
BS_LEFT | Left-aligns the text in the button rectangle on the right side of the check box.
BS_RIGHT | Right-aligns text in the button rectangle on the right side of the check box.
BS_RIGHTBUTTON | Positions a check box square on the right side of the button rectangle.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Combo box styles
 Description
CBS_AUTOHSCROLL | Automatically scrolls the text in an edit control to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is enabled.
CBS_DISABLENOSCROLL | Shows a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items.
CBS_DROPDOWN | Displays only the edit control by default. The user can display the list box by selecting an icon next to the edit control.
CBS_DROPDOWNLIST | Displays a static text field that displays the current selection in the list box.
CBS_LOWERCASE | Converts to lowercase any uppercase characters that are typed into the edit control of a combo box.
CBS_NOINTEGRALHEIGHT | Specifies that the combo box will be exactly the size specified by the application when it created the combo box. Usually, Windows CE sizes a combo box so that it does not display partial items.
CBS_OEMCONVERT | Converts text typed in the combo box edit control from the Windows CE character set to the OEM character set and then back to the Windows CE set. This style is most useful for combo boxes that contain file names. It applies only to combo boxes created with the CBS_DROPDOWN style.
CBS_SORT | Sorts strings that are typed into the list box.
CBS_UPPERCASE | Converts to uppercase any lowercase characters that are typed into the edit control of a combo box.
WS_TABSTOP | Turns control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Edit control styles
 Description
ES_AUTOHSCROLL | Automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to the zero position.
ES_AUTOVSCROLL | Scrolls text up one page when the user presses the ENTER key on the last line.
ES_CENTER | Centers text in a multiline edit control.
ES_COMBOBOX | Indicates that the edit control is part of a combo box
ES_LEFT | Left-aligns text.
ES_LOWERCASE | Converts all characters to lowercase as they are typed into the edit control.
ES_MULTILINE Designates a multiline edit control. The default is a single-line edit control.

When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the ES_WANTRETURN style.

When the multiline edit control is not in a dialog box and the ES_AUTOVSCROLL style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify ES_AUTOVSCROLL, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed.

If you specify the ES_AUTOHSCROLL style, the multiline edit control automatically scrolls horizontally when the caret goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify ES_AUTOHSCROLL, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed.

Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages that are sent by the parent window.
ES_NOHIDESEL | Negates the default behavior for an edit control. The default behavior hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. If you specify ES_NOHIDESEL, the selected text is inverted, even if the control does not have the focus.
ES_NUMBER | Accepts into the edit control only digits to be typed.
ES_OEMCONVERT | Converts text typed in the edit control from the Windows CE character set to the OEM character set and then converts it back to the Windows CE set. This style is most useful for edit controls that contain file names.
ES_PASSWORD | Displays an asterisk (*) for each character that is typed into the edit control. You can use the EM_SETPASSWORDCHAR message to change the displayed character.
ES_READONLY | Prevents the user from typing or editing text in the edit control.
ES_RIGHT | Right-aligns text in a multiline edit control.
ES_UPPERCASE | Converts all characters to uppercase as they are typed into the edit control.
ES_WANTRETURN | Specifies that a carriage return be inserted when the user presses the ENTER key while typing text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box’s default push button. This style has no effect on a single-line edit control.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

List box styles
 Description
LBS_DISABLENOSCROLL | Shows a disabled vertical scroll bar for the list box when the box does not contain enough items to scroll. If you do not specify this style, the scroll bar is hidden when the list box does not contain enough items.
LBS_EXTENDEDSEL | Enables the user to select multiple items by using the SHIFT key and the mouse or hot keys.
LBS_MULTICOLUMN | Specifies a multicolumn list box that the user scrolls through horizontally. You set the width of the columns by using the LB_SETCOLUMNWIDTH message.
LBS_MULTIPLESEL | Turns string selection on or off each time a user taps or double-taps a string in the list box. A user can select any number of strings simultaneously.
LBS_NOINTEGRALHEIGHT | Specifies that the list box will be exactly the size specified by the application when it created the list box. Usually, Windows CE sizes a list box so that it does not display partial items.
LBS_NOREDRAW | Ensures that the list box appearance is not automatically updated when changes are made. You can change this style by sending a WM_SETREDRAW message.
LBS_NOSEL | Specifies that the user can view list box strings but cannot select them.
LBS_NOTIFY | Notifies the parent window when the user taps or double-taps a string in the list box.
LBS_SORT | Sorts strings in the list box alphabetically.
LBS_STANDARD | Sorts strings in the list box alphabetically. The parent window receives an input message when the user taps or double-taps a string. The list box has borders on all sides.
LBS_USETABSTOPS | Enables a list box to recognize and expand tab characters when drawing its strings. The default tab positions are 32 dialog box units. A dialog box unit is equal to one-fourth of the current dialog box base-width unit. Windows CE calculates these units based on the height and width of the current system font.
LBS_WANTKEYBOARDINPUT | Specifies that the owner of the list box receives WM_VKEYTOITEM messages when the user presses a key and the list box has the input focus. This enables an application to perform special processing on the keyboard input.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Push button styles
 Description
BS_BOTTOM | Places the text at the bottom of the button rectangle.
BS_CENTER | Centers the text horizontally in the button rectangle.
BS_DEFPUSHBUTTON | Creates a push button with a heavy black border. If the button is in a dialog box, the user can select the button by pressing the ENTER key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely option, or default.
BS_LEFT | Left-aligns the text in the button rectangle.
BS_NOTIFY | Enables a button to send BN_DBLCLK, BN_KILLFOCUS, and BN_SETFOCUS notification messages to its parent window. Note that the button sends the BN_CLICKED notification message regardless of whether it has this style.
BS_OWNERDRAW | Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created and a WM_DRAWITEM message when a visual aspect of the button has changed.
BS_PUSHBUTTON | Creates a push button that posts a WM_COMMAND message to the owner window when the user clicks the button.
BS_RIGHT | Right-aligns text in the button rectangle.
BS_TOP | Places text at the top of the button rectangle.
BS_VCENTER | Vertically centers text in the button rectangle.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Radio button styles
 Description
BS_AUTORADIOBUTTON | Creates a radio button that, when selected by a user, clears all other buttons in the same group.
BS_LEFT | Left-aligns the text in the button rectangle on the right side of the check box.
BS_RADIOBUTTON | Creates a small circle with a label displayed to the right of it. To display the text to the left of the circle, combine this flag with the BS_RIGHTBUTTON style.
BS_RIGHT | Right-aligns the text in the button rectangle on the right side of the check box.
BS_RIGHTBUTTON | Positions a check box square on the right side of the button rectangle.
WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box.

Scroll bar styles
 Description
SBS_HORZ | Designates a horizontal scroll bar. If you do not specify the SBS_TOPALIGN style, the scroll bar has the height, width, and position specified by the parameters of the CreateWindow function.
SBS_VERT | Designates a vertical scroll bar. If you do not specify the SBS_LEFTALIGN style, the scroll bar has the height, width, and position specified by the parameters of the CreateWindow funtcion.

Static control styles
 Description
SS_BITMAP | Specifies that a bitmap will be displayed in the static control. The text is the name of a bitmap that is defined elsewhere in the resource file, not a file name. The style ignores the nWidth and nHeight parameters; the control automatically sizes itself to accommodate the bitmap.
SS_CENTER | Specifies a simple rectangle and centers the error value text in the rectangle. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next centered line.
SS_CENTERIMAGE | Specifies that the midpoint of a static control with the SS_BITMAP style will remain fixed when you resize the control. The four sides are adjusted to accommodate a new bitmap. If the bitmap is smaller than the control’s client area, the rest of the client area is filled with the color of the pixel in the upper-left corner of the bitmap.
SS_ICON | Specifies that an icon will be displayed in the static control. The text is the name of an icon defined elsewhere in the resource file, not a file name. The style ignores the nWidth and nHeight parameters; the icon automatically sizes itself.
SS_LEFT | Specifies a rectangle and left-aligns the text in the rectangle. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next left-aligned line.
SS_LEFTNOWORDWRAP | Specifies a rectangle and left-aligns the text in the rectangle. Tabs are expanded, but words are not wrapped. Text that extends past the end of a line is clipped.
SS_NOPREFIX Prevents interpretation of any ampersand (&) characters in the control’s text as accelerator prefix characters.

An application can combine SS_NOPREFIX with other styles by using the bitwise OR (|) operator. This can be useful when file names or other strings that might contain an ampersand (&) must be displayed within a static control in a dialog box.
SS_NOTIFY | Sends the parent window the STN_CLICKED notification when the user clicks the control.
SS_RIGHT | Specifies a rectangle and right-aligns the specified text in the rectangle. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next right-aligned line.

The following table shows common control styles that are supported by
Windows CE.

Basic common control styles
 Description
CCS_ADJUSTABLE | Enables a toolbar’s built-in customization features, which enable the user to drag a button to a new position or to remove a button by dragging it off the toolbar. In addition, the user can double-click the toolbar to display the Customize Toolbar dialog box, which enables the user to add, delete, and rearrange toolbar buttons.
CCS_BOTTOM | Causes the control to position itself at the bottom of the parent window’s client area and sets the width of the control to be the same as the parent window’s width. Status windows have this style by default.
CCS_LEFT | Causes the control to display vertically on the left side of the parent window.
CCS_NODIVIDER | Prevents a 2-pixel highlight from being drawn at the top of the control.
CCS_NOMOVEX | Causes the control to resize and move itself vertically, but not horizontally, in response to a WM_SIZE message. This message does not apply if your control has the CCS_NORESIZE style.
CCS_NOMOVEY | Causes the control to resize and move itself horizontally, but not vertically, in response to a WM_SIZE message. Header windows have this style by default. This style does not apply if your control has the CCS_NORESIZE style.
CCS_NOPARENTALIGN | Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent. If the application also uses the CCS_TOP or CCS_BOTTOM styles, it adjusts the height to the default, but does not change the position and width of the control.
CCS_NORESIZE | Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height that is specified in the request for creation or sizing.
CCS_RIGHT | Causes the control to display vertically on the right side of the parent window.
CCS_TOP | Causes the control to position itself at the top of the parent window client area and matches the width of the control to the width of the parent window. Toolbars have this style by default.
CCS_VERT | Causes the control to display vertically.

Date and time picker styles
 Description
DTS_APPCANPARSE | Enables the owner to parse user input. When a date time picker (DTP) control has this style, a user can make changes within the client area of the control by pressing the F2 key. The control sends a DTN_USERSTRING notification message when the user is finished editing.
DTS_LONGDATEFORMAT | Displays the date in long format. The default format string for this style is defined by LOCALE_SLONGDATEFORMAT, which produces output like “Friday, April 19, 1998.”
DTS_SHORTDATEFORMAT | Displays the date in short format. The default format string for this style is defined by LOCALE_SSHORTDATE, which produces output like “4/19/98.”
DTS_SHOWNONE | Enables the control to accept “no date” as a valid selection state. This state can be set with the DTM_SETSYSTEMTIME message or verified with the DTM_GETSYSTEMTIME message.
DTS_TIMEFORMAT | Displays the time. The default format string for this style is defined by LOCALE_STIMEFORMAT, which produces output like “5:31:42 PM.” An up-down control is placed to the right of the DTP control to modify time values.
DTS_UPDOWN | Places an up-down control to the right of a DTP control to modify time values. This style can be used instead of the drop-down month calendar, which is the default style.

Header control styles
 Description
HDS_BUTTONS | Causes each header item to look and behave like a button. This style is useful if an application carries out a task when the user clicks an item in the header control.
HDS_DRAGDROP | Enables drag-and-drop reordering of header items.
HDS_FULLDRAG | Causes the header control to display column contents even while a user resizes a column.
HDS_HIDDEN | Creates a header control that you can hide by setting its height to zero. This style is useful when you use the control as an information container instead of a visual control.
HDS_HORZ | Creates a horizontal header control.

List view styles
 Description
LVS_ALIGNLEFT | Specifies that items are left-aligned in icon view and small icon view.
LVS_ALIGNTOP | Specifies that items are aligned with the top of the list view control in icon view and small icon view.
LVS_AUTOARRANGE | Specifies that icons automatically remain arranged in icon view and small icon view.
LVS_EDITLABELS | Enables item text to be edited in place. The parent window must process the LVN_ENDLABELEDIT notification message.
LVS_EX_CHECKBOXES | Enables items in a list view control to be displayed as check boxes. This style uses item state images to produce the check box effect.
LVS_EX_FULLROWSELECT | Specifies that when an item is selected, the item and all of its subitems are highlighted. This style is available only in conjunction with the LVS_REPORT style.
LVS_EX_GRIDLINES | Displays gridlines around items and subitems. This style is available only in conjunction with the LVS_REPORT style.
LVS_EX_HEADERDRAGDROP | Enables drag-and-drop reordering of columns in a list view control. This style is only available to list view controls that use the LVS_REPORT style.
LVS_EX_SUBITEMIMAGES | Enables images to be displayed for subitems. This style is available only in conjunction with the LVS_REPORT style.
LVS_ICON | Specifies icon view.
LVS_LIST | Specifies list view.
LVS_NOCOLUMNHEADER | Specifies that no column header is displayed in report view, which is the default view.
LVS_NOLABELWRAP | Displays item text on a single line in icon view. By default, item text might wrap in icon view.
LVS_NOSCROLL | Disables scrolling, so all items must be displayed within the client area.
LVS_NOSORTHEADER | Specifies that column headers do not work like buttons. This style is useful if clicking a column header in report view does not carry out any action, such as sorting.
LVS_OWNERDATA | Creates a virtual list view control.
LVS_OWNERDRAWFIXED | Enables the owner window to paint items in report view. The list view control sends a WM_DRAWITEM message to paint each item; it does not send separate messages for each subitem. The itemData member of the DRAWITEMSTRUCT structure contains the item data for the specified list view item.
LVS_REPORT | Specifies report view.
LVS_SHAREIMAGELISTS | Specifies that the control does not destroy the image lists assigned to it when it is destroyed. This style enables the same image lists to be used with multiple list view controls.
LVS_SHOWSELALWAYS | Always shows the selection highlighted, even if the control is not activated.
LVS_SINGLESEL | Enables only one item to be selected at a time. By default, multiple items can be selected.
LVS_SMALLICON | Specifies small icon view.
LVS_SORTASCENDING | Sorts items based on item text in ascending order.
LVS_SORTDESCENDING | Sorts items based on item text in descending order.

Month calendar control styles
Description
MCS_DAYSTATE | Specifies that the month calendar will send MCN_GETDAYSTATE notifications to request information about which days should be displayed in bold.
MCS_MULTISELECT | Enables the user to select a range of dates. By default, the maximum range is one week. You can change the maximum selectable range by using the MCM_SETMAXSELCOUNT message.
MCS_NOTODAY | Creates a month calendar that does not display a Today selection.
MCS_NOTODAYCIRCLE | Creates a month calendar that does not circle the current date.
MCS_WEEKNUMBERS | Displays the week number, from 1 through 52, to the left of each week in the calendar.

Progress Bar Styles
 Description
PBS_SMOOTH | Displays progress status in a smooth scrolling bar instead of the default segmented bar.
PBS_VERTICAL | Displays progress status vertically, from bottom to top.

Rebar styles
 Description
CCS_VERT | Causes the control to appear vertically at the left side of the parent window.
RBBS_NOGRIPPER | Creates a rebar band that displays no gripper. This style applies to individual bands, not to the entire rebar. Windows CE is the only Windows-based OS that supports the RBS_NOGRIPPER style for rebar controls.
RBS_AUTOSIZE | Specifies that the layout of a band will automatically change when the size or position of its control changes. When the layout changes, the control sends an RBN_AUTOSIZE notification.
RBS_BANDBORDERS | Displays narrow lines to separate adjacent bands.
RBS_FIXEDORDER | Displays multiple bands in the same order at all times. A user can move bands to different rows, but the band order is static.
RBS_SMARTLABELS Displays the icon for a band that has an icon only when the band is minimized. If a band has a text label, the label is displayed only when the band is in its restored state or in its maximized state.
Windows CE is the only Windows-based OS that supports the RBS_SMARTLABELS style for rebar controls.
RBS_VARHEIGHT | Displays a band at the minimum required height, when possible. Without this style, the command bands control displays all bands at the same height, using the height of the tallest visible band to determine the height of other bands.
RBS_VERTICALGRIPPER | Displays the size grip vertically, instead of horizontally, in a vertical command bands control. This style is ignored for command bands controls that do not have the CCS_VERT style.

Tab control styles
 Description
TCS_BOTTOM | Displays the tabs at the bottom of the control. If the TCS_VERTICAL style is also specified, this style is interpreted as TCS_RIGHT.
TCS_BUTTONS | Displays all tabs as buttons with no border drawn around the display area.
TCS_FIXEDWIDTH | Specifies that all tabs are the same width. You can not combine this style with the TCS_RIGHTJUSTIFY style.
TCS_FLATBUTTONS | Changes the appearance of a selected tab to indented while other tabs appear to be on the same plane as the background. This style only applies to tab controls that have the TCS_BUTTONS style.
TCS_FLIP | Flips all tabs from top to bottom or left to right.
TCS_FOCUSNEVER | Creates a tab control that never receives the input focus.
TCS_FOCUSONBUTTONDOWN | Specifies that a given tab, when selected, receives the input focus.
TCS_FORCEICONLEFT | Aligns an icon with the left edge of a fixed-width tab. This style can only be used with the TCS_FIXEDWIDTH style.
TCS_FORCELABELLEFT | Aligns a label with the left edge of a fixed-width tab; that is, it displays the label immediately to the right of the icon instead of centering it. This style can only be used with the TCS_FIXEDWIDTH style, and it implies the TCS_FORCEICONLEFT style.
TCS_MULTILINE | Displays multiple rows of tabs, if necessary, so that all tabs are visible at once.
TCS_MULTISELECT | Specifies that multiple tabs can be selected by holding down CTRL when selecting a tab. This style only applies to tabs that have the TCS_BUTTONS style.
TCS_OWNERDRAWFIXED | Specifies that the parent window is responsible for drawing tabs.
TCS_RAGGEDRIGHT | Leaves a ragged right edge by not stretching a row of tabs to fill the entire width of the control. This style is the default.
TCS_RIGHT | Displays multiple tabs vertically on the right side of controls that use the TCS_VERTICAL style. If the TCS_VERTICAL style is not specified, this style is interpreted as TCS_BOTTOM.
TCS_RIGHTJUSTIFY | Increases the width of each tab, if necessary, so that each row of tabs fills the entire width of the tab control. This style is valid only when it is used with the TCS_MULTILINE style.
TCS_SCROLLOPPOSITE | Specifies that unused tabs move to the opposite side of the control when a new tab is selected.
TCS_SINGLELINE | Displays only one row of tabs. The user can scroll to see more tabs, if necessary. This style is the default.
TCS_VERTICAL | Displays multiple tabs vertically on the left side of the control. This style is valid only when it is used with the TCS_MULTILINE style. To make tabs appear on the right side of the control, combine this style with the TCS_RIGHT style.

Toolbar styles
 Description
TBSTYLE_AUTOSIZE | Calculates a button width based on the text of the button, not on the size of the image.
TBSTYLE_BUTTON | Creates a toolbar button that looks like a standard Windows CE push button.
TBSTYLE_CHECK | Creates a button that toggles between the pressed and not pressed states each time the user clicks it. The button has a different background color when it is in the pressed state.
TBSTYLE_CHECKGROUP | Creates a check button that stays pressed until another button in the group is pressed.
TBSTYLE_CUSTOMERASE | Creates a toolbar that generates NM_CUSTOMDRAW notification messages when it processes WM_ERASEBKGND messages.
TBSTYLE_DROPDOWN | Creates a drop-down list button.
TBSTYLE_FLAT | Creates a flat toolbar, in which both the toolbar and the buttons are transparent. Button text appears under button bitmaps.
TBSTYLE_GROUP | Creates a button that stays pressed until another button in the group is pressed.
TBSTYLE_LIST | Places button text to the right of button bitmaps. This style can only be used with the TBSTYLE_FLAT style. In Windows CE, the TBSTYLE_LIST style creates a toolbar with variable width buttons. If you want to use the TBSTYLE_LIST style with fixed width buttons, you can override the default behavior by sending a TB_SETBUTTONSIZE or TB_SETBUTTONWIDTH message.
TBSTYLE_SEP | Creates a separator, which provides a small gap between button groups. A button that has this style does not receive user input.
TBSTYLE_TOOLTIPS | Creates a ToolTip control that an application can use to display descriptive text for the buttons in the toolbar.
TBSTYLE_TRANSPARENT | Creates a transparent toolbar, in which the toolbar is transparent, but the buttons are not. Button text appears under button bitmaps.
TBSTYLE_WRAPABLE | Creates a toolbar that can have multiple rows of buttons. Toolbar buttons can wrap to the next line when the toolbar becomes too narrow to include all buttons on the same line. Wrapping occurs on separation and non-group boundaries.

Tree view styles
Description
TVS_CHECKBOXES | Enables items in a tree view control to be displayed as check boxes. This style uses item state images to produce the check box effect.
TVS_DISABLEDRAGDROP | Prevents the tree view control from sending TVN_BEGINDRAG notification messages.
TVS_EDITLABELS | Enables the user to edit the labels of tree view items.
TVS_HASBUTTONS | Displays plus (+) and minus (-) buttons next to parent items. The user taps the buttons to expand or collapse a parent item’s list of child items. To include buttons with items at the root of the tree view, you must also specify the TVS_LINESATROOT style.
TVS_HASLINES | Uses lines to show the hierarchy of items.
TVS_LINESATROOT | Uses lines to link items at the root of the tree view control. This value is ignored if the TVS_HASLINES control is not also specified.
TVS_SHOWSELALWAYS | Uses the system highlight colors to draw the selected item.
TVS_SINGLESEL | Specifies that when a new tree view item is selected, the selected item will automatically expand and the previously selected item will collapse.

Up-down control styles
Description
UDS_ALIGNLEFT | Positions the up-down control next to the left edge of the buddy window. The buddy window is moved to the right and its width is decreased to accommodate the width of the up-down control.
UDS_ALIGNRIGHT | Positions the up-down control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.
UDS_ARROWKEYS | Causes the up-down control to process the UP ARROW and DOWN ARROW keys on the keyboard.
UDS_AUTOBUDDY | Automatically elects the previous window in the z-order as the up-down control’s buddy window. In Windows CE, the window must be an edit control.
UDS_HORZ | Causes the up-down control’s arrows to point left and right instead of up and down.
UDS_NOTHOUSANDS | Prevents insertion of a thousands separator between every three decimal positions.
UDS_SETBUDDYINT | Causes the up-down control to set the text of the buddy window, using the WM_SETTEXT message, when the position changes. The text consists of the position formatted as a decimal or hexadecimal string.
UDS_WRAP | Causes the position to wrap if it is incremented or decremented beyond the end or beginning of the range.


Windows CE Modules and Components

Because minimizing memory use is a major design goal, Windows CE is built from modules. You can control the size of the system software by selecting only the modules that you need. Several modules are also further divided into components. By selecting the minimum set of needed modules and components, you can minimize the memory needed for your Windows CE operating system.

A module or a component supports a group of related API functions. All defined modules and components are listed here in alphabetical order. The first list contains only the modules. Additional lists show the components for those modules that are divided into components.

These lists are followed by alphabetical reference entries for all modules. For each module that has components, its component entries follow immediately after the module entry. The reference entries include lists of functions that make up the modules and components.


List of Platform Builder Modules

Modules that are divided into components are marked with asterisks. Components are listed later. The following modules are provided by Platform Builder:


Lists of Platform Builder Components

The coredll module contains the following components:

accel_c | fileinfo | serdev
coreimm | fileopen | shcore
coreloc | fmtmsg | shellapis
coremain | fmtres | shexec
coresioa | fpemul | shmisc
coresiow | lmem | shortcut
coresip | locusa | tapilib
corestra | mgdi_c | thunks
corestrw | rectapi | wavelib
cryptapi | rsa32 | wmgr_c

The cplmain module contains the following components:

backlight | keyboard | power
colorscheme | mouse | sip
comm | network | sounds
datetime | owner | stylus
dialing | password | system
display | pointercmn |

The filesys module contains the following components:

fsdbase | fspass | fsysrom
fsheap | fsreg | pmstub
fsmain | fsysram |


Descriptions of Modules and Components

This section includes descriptions of all the Platform Builder modules and components, with lists of the public functions they contain. Components are grouped after the module to which they belong.


The afd Module

AFD protocol manager module.

This module has no components or public functions.


The arp Module

Address regulator protocol (ARP) module.

This module has no components or public functions.


The asform Module

Shell support module.

This module has no components or public functions.


The atadisk Module

ATA disk support module.

This module has no components or public functions.


The cardserv Module

PC card services module.

This module has no components or public functions.


The cegsm Module

CEGSM module.

This module has no components.

Functions

This module includes the following function:

DriverProc


The ceramdrv Module

RAM disk driver module.

This module has no components or public functions.


The ceshell Module

Shell support module.

This module has no components or public functions.


The cmd Module

Command processor module.

This module has no components or public functions.


The commctrl Module

Communications control panel applet module.

This module has no components.

Functions

This module includes the following functions:

CenterWindow
CommandBands_AddAdornments
CommandBands_AddBands
CommandBands_Create
CommandBands_GetCommandBar
CommandBands_GetRestoreInformation
CommandBands_Show
CommandBar_AddAdornments
CommandBar_AddBitmap
CommandBar_AlignAdornments
CommandBar_Create
CommandBar_DrawMenuBar
CommandBar_GetItemWindow
CommandBar_GetMenu
CommandBar_Height
CommandBar_InsertComboBox
CommandBar_InsertControl
CommandBar_InsertMenubar
CommandBar_InsertMenubarEx
CommandBar_Show
CreatePropertySheetPageW
CreateStatusWindowW
CreateToolbar
CreateToolbarEx
CreateUpDownControl
DestroyPropertySheetPage
DPA_Destroy
DPA_GetPtr
DrawStatusTextW
DSA_Create
DSA_DeleteAllItems
DSA_DeleteItem
DSA_Destroy
DSA_GetItem
DSA_GetItemPtr
DSA_InsertItem
DSA_SetItem
InitCommonControls
InitCommonControlsEx
InvertRect
IsCommandBarMessage
PropertySheetW
Str_SetPtrW
StrToIntW


The commdlg Module

Common dialogs module.

This module has no components.

Functions

This module includes the following functions:

ChooseColor
CommDlgExtendedError
PageSetupDlgW
PrintDlg


The console Module

Console module.

This module has no components.

Functions

This module includes the following functions:

CON_Close
CON_Deinit
CON_Init
CON_IOControl
CON_Open
CON_PowerDown
CON_PowerUp
CON_Read
CON_Seek
CON_Write


The control Module

Control panel application module.

This module has no components or public functions.


The coredll Module

Operating system core DLL module. This module is always required, but not all of its components are required.

Components

This module includes the following components:

accel_c
coreimm
coreloc
coremain
coresioa
coresiow
coresip
corestra
corestrw
cryptapi
fileinfo
fileopen
fmtmsg
fmtres
fpemul
lmem
locusa
mgdi_c
rectapi
rsa32
serdev
shcore
shellapis
shexec
shmisc
shortcut
tapilib
thunks
wavelib
wmgr_c


The accel_c Component

This component of the coredll module provides client-side support for user accelerator tables.

Functions

This component includes the following functions:

CreateAcceleratorTable
DestroyAcceleratorTable
LoadAccelerators


The coreimm Component

Input method manager component of the coredll module.

Functions

This component includes the following functions:

DefaultImcGet
DefaultImeWndGet
GetKeyboardLayout
ImmAssociateContext
ImmAssociateContextEx
ImmConfigureIME
ImmCreateContext
ImmCreateIMCC
ImmDestroyContext
ImmDestroyIMCC
ImmEnumRegisterWord
ImmEscape
ImmGenerateMessage
ImmGetCandidateList
ImmGetCandidateListCount
ImmGetCandidateWindow
ImmGetCompositionFont
ImmGetCompositionString
ImmGetCompositionWindow
ImmGetContext
ImmGetConversionList
ImmGetConversionStatus
ImmGetDefaultIMEWnd
ImmGetDescription
ImmGetGuideLine
ImmGetHotKey

ImmDisableIME
ImmGetIMCCLockCount
ImmGetIMCCSize
ImmGetIMCLockCount
ImmGetIMEFileName
ImmGetImeMenuItems
ImmGetOpenStatus
ImmGetProperty
ImmGetRegisterWordStyle
ImmGetStatusWindowPos
ImmGetUIClassName
ImmGetVirtualKey
ImmIsIME
ImmIsUIMessage
ImmLockIMC
ImmLockIMCC
ImmNotifyIME
ImmProcessKey
ImmRegisterWord
ImmReleaseContext
ImmRequestMessage
ImmReSizeIMCC
ImmSetActiveContext
ImmSetCandidateWindow
ImmSetCompositionFont
ImmSetCompositionString
ImmSetCompositionWindow
ImmSetConversionStatus
ImmSetHotKey
ImmSetImeWndIMC
ImmSetOpenStatus
ImmSetStatusWindowPos
ImmSimulateHotKey
ImmSIPanelState
ImmTranslateMessage
ImmUnlockIMC
ImmUnlockIMCC
ImmUnregisterWord


The coreloc Component

Global national language support (NLS) component of the coredll module. This component is always required.

Functions

This component includes the following functions:

_wcsicmp
_wcslwr
_wcsnicmp
_wcsupr
CharLower
CharLowerBuff
CharNext
CharPrev
CharUpper
CharUpperBuff
CompareString
ConvertDefaultLocale
DBCanonicalize
EnumCalendarInfo
EnumDateFormats
EnumSystemCodePages
EnumSystemLocales
EnumTimeFormats
FoldString
GetACP
GetCPInfo
GetCurrencyFormat
GetDateFormat
GetLocaleInfo
GetNumberFormat
GetOEMCP
GetStringType
GetStringTypeEx
GetSystemDefaultLangID
GetSystemDefaultLCID
GetTimeFormat
GetUserDefaultLangID
GetUserDefaultLCID
IsDBCSLeadByte
IsDBCSLeadByteEx
IsValidCodePage
IsValidLocale
iswctype
LCMapString
lstrcmp
lstrcmpi
MultiByteToWideChar
SetACP
SetLocaleInfo
SetOEMCP
SetSystemDefaultLCID
towlower
towupper
WideCharToMultiByte


The coremain Component

This base functionality component of the coredll module is always required. It provides APIs for time, critical sections, and interlock.

Functions

This component includes the following functions:

CompareFileTime
DeleteCriticalSection
EnterCriticalSection
ExitThread
FileTimeToLocalFileTime
FileTimeToSystemTime
GetAPIAddress
GetCRTFlags
GetCRTStorageEx
GetCurrentFT
GetLocalTime
GetSystemTime
GetTimeZoneInformation
GetVersionEx
InitializeCriticalSection
InitLocale
IsAPIReady
IsProcessDying
LeaveCriticalSection
LocalFileTimeToFileTime
MainThreadBaseFunc
memchr
PSLNotify
SetLocalTime
SetSystemTime
SetTimeZoneInformation
SystemMemoryLow
SystemStarted
SystemTimeToFileTime
ThreadBaseFunc
TlsGetValue
TlsSetValue


The coresioa Component

Standard I/O (stdio) component of the coredll module. This is the “A” (ASCII) version of these APIs.

Functions

This component includes the following functions:

_fcloseall
_fileno
_flushall
_getstdfilex
_setmode
_wfdopen
_wfreopen
clearerr
fclose
feof
ferror
fflush
fgetc
fgetpos
fgets
fopen
fprintf
fputc
fputs
fread
fscanf
fseek
fsetpos
ftell
fwrite
getc
getchar
gets
printf
putc
putchar
puts
scanf
ungetc
vfprintf
vprintf


The coresiow Component

Standard I/O (stdio) component of the coredll module. This is the “W” (wide-string) version of these APIs for Unicode support.

Functions

This component includes the following functions:

_fcloseall
_fileno
_flushall
_getstdfilex
_InitStdioLib
_setmode
_wfdopen
_wfreopen
clearerr
fclose
feof
ferror
fflush
fgetc
fgetpos
fgets
fopen
fprintf
fputc
fputs
fread
fscanf
fseek
fsetpos
ftell
fwrite
getchar
gets
printf
putchar
puts
scanf
ungetc
vfprintf
vprintf


The coresip Component

Input panel component of the coredll module.

Functions

This component includes the following functions:

SipEnumIM
SipGetCurrentIM
SipGetInfo
SipRegisterNotification
SipSetCurrentIM
SipSetDefaultRect
SipSetInfo
SipShowIM
SipStatus


The corestra Component

Sprintf-style string handling component of the coredll module. This is the “A” (ASCII) version of these APIs.

Functions

This component includes the following functions:

_snprintf
_vsnprintf
sprintf
sscanf
vsprintf


The corestrw Component

Sscanf-style string handling component of the coredll module. This is the “W” (wide-string) version of this API.

Functions

This component includes the following function:

swscanf


The cryptapi Component

Cryptography component of the coredll module.

Functions

This component includes the following functions:

CryptAcquireContext
CryptContextAddRef
CryptCreateHash
CryptDecrypt
CryptDeriveKey
CryptDestroyHash
CryptDestroyKey
CryptDuplicateHash
CryptDuplicateKey
CryptEncrypt
CryptEnumProviders
CryptEnumProviderTypes
CryptExportKey
CryptGenKey
CryptGenRandom
CryptGetDefaultProvider
CryptGetHashParam
CryptGetKeyParam
CryptGetProvParam
CryptGetUserKey
CryptHashData
CryptHashSessionKey
CryptImportKey
CryptReleaseContext
CryptSetHashParam
CryptSetKeyParam
CryptSetProvider
CryptSetProviderEx
CryptSetProvParam
CryptSignHash
CryptVerifySignature


The fileinfo Component

This shell-related component of the coredll module retrieves information about files and directories.

Functions

This component includes the following functions:

SHGetFileInfo
SHGetSpecialFolderPath


The fileopen Component

This component of the coredll module gets dialog boxes for opening and saving files.

Functions

This component includes the following functions:

GetOpenFileName
GetSaveFileName


The fmtmsg Component

Message formatting component of the coredll module.

Functions

This component includes the following function:

FormatMessage


The fmtres Component

This component of the coredll module provides FormatMessage API resources for the fmtmsg component.

This component has no public functions.


The fpemul Component

Floating point emulation component of the coredll module.

Functions

This component includes the following function:

NPXNPHandler


The lmem Component

This component of the coredll module contains the local heap and memory allocation functions for Coredll.dll and is always required. (This component's name starts with a lowercase L, not with an uppercase I.)

Functions

This component includes the following functions:

CompactAllHeaps
GetHeapSnapshot
GetProcessHeap
HeapAlloc
HeapCreate
HeapDestroy
HeapFree
HeapReAlloc
HeapSize
HeapValidate
LocalAlloc
LocalAllocInProcess
LocalFree
LocalFreeInProcess
LocalReAlloc
LocalSize
LocalSizeInProcess
RemoteLocalAlloc
RemoteLocalFree
RemoteLocalReAlloc
RemoteLocalSize
ThisIsGwes


The locusa Component

USA-specific component of the coredll module.

Functions

This component includes the following functions:

_wcsicmp
_wcslwr
_wcsnicmp
_wcsupr
CharLower
CharLowerBuff
CharNext
CharPrev
CharUpper
CharUpperBuff
CompareString
ConvertDefaultLocale
DBCanonicalize
EnumCalendarInfo
EnumDateFormats
EnumSystemCodePages
EnumSystemLocales
EnumTimeFormats
FoldString
GetACP
GetCPInfo
GetCurrencyFormat
GetDateFormat
GetLocaleInfo
GetNumberFormat
GetOEMCP
GetStringType
GetStringTypeEx
GetSystemDefaultLangID
GetSystemDefaultLCID
GetTimeFormat
GetUserDefaultLangID
GetUserDefaultLCID
IsDBCSLeadByte
IsDBCSLeadByteEx
IsValidCodePage
IsValidLocale
iswctype
LCMapString
lstrcmp
lstrcmpi
MultiByteToWideChar
SetACP
SetLocaleInfo
SetOEMCP
SetSystemDefaultLCID
towlower
towupper
WideCharToMultiByte


The mgdi_c Component

Graphical device interface (GDI) component of the coredll module.

Functions

This component includes the following functions:

CreateDIBSection
EqualRgn


The rectapi Component

GDI rectangle support component of the coredll module.

Functions

This component includes the following functions:

CopyRect
EqualRect
InflateRect
IntersectRect
IsRectEmpty
OffsetRect
PtInRect
SetRect
SetRectEmpty
SubtractRect
UnionRect


The rsa32 Component

RSA encryption component of the coredll module.

This component has no public functions.


The serdev Component

Win32 communication component of the coredll module.

Functions

This component includes the following functions:

ClearCommBreak
ClearCommError
EscapeCommFunction
GetCommMask
GetCommModemStatus
GetCommProperties
GetCommState
GetCommTimeouts
PurgeComm
SetCommBreak
SetCommMask
SetCommState
SetCommTimeouts
SetupComm
TransmitCommChar
WaitCommEvent


The shcore Component

Shell component of the coredll module.

This component has no public functions.


The shellapis Component

Shell API support component of the coredll module.

Functions

This component includes the following functions:

SHAddToRecentDocs
SHCreateExplorerInstance
Shell_NotifyIcon


The shexec Component

Shell API support component of the coredll module.

Functions

This component includes the following function:

ShellExecuteEx


The shmisc Component

Miscellaneous shell API component of the coredll module.

Functions

This component includes the following functions:

SHLoadDIBitmap
SHShowOutOfMemory


The shortcut Component

This component of the coredll module provides shell API support for handling shortcuts.

Functions

This component includes the following functions:

SHCreateShortcut
SHGetShortcutTarget


The tapilib Component

Telephony API (TAPI) component of the coredll module.

This component has no public functions.


The thunks Component

Kernel to Win32 thunk routines component of the coredll module. This component is always required.

This component has no public functions.


The wavelib Component

Wave and ACM audio component of the coredll module.

Functions

This component includes the following functions:

acmDriverAdd
acmDriverClose
acmDriverDetails
acmDriverEnum
acmDriverID
acmDriverMessage
acmDriverOpen
acmDriverPriority
acmDriverRemove
acmFilterChoose
acmFilterDetails
acmFilterEnum
acmFilterTagDetails
acmFilterTagEnum
acmFormatChoose
acmFormatDetails
acmFormatEnum
acmFormatSuggest
acmFormatTagDetails
acmFormatTagEnum
acmGetVersion
acmMetrics
acmStreamClose
acmStreamConvert
acmStreamMessage
acmStreamOpen
acmStreamPrepareHeader
acmStreamReset
acmStreamSize
acmStreamUnprepareHeader
AudioUpdateFromRegistry
PlaySound
sndPlaySound
waveInAddBuffer
waveInClose
waveInGetDevCaps
waveInGetErrorText
waveInGetID
waveInGetNumDevs
waveInGetPosition
waveInMessage
waveInOpen
waveInPrepareHeader
waveInReset
waveInStart
waveInStop
waveInUnprepareHeader
waveOutBreakLoop
waveOutClose
waveOutGetDevCaps
waveOutGetErrorText
waveOutGetID
waveOutGetNumDevs
waveOutGetPitch
waveOutGetPlaybackRate
waveOutGetPosition
waveOutGetVolume
waveOutMessage
waveOutOpen
waveOutPause
waveOutPrepareHeader
waveOutReset
waveOutRestart
waveOutSetPitch
waveOutSetPlaybackRate
waveOutSetVolume
waveOutUnprepareHeader
waveOutWrite


The wmgr_c Component

Window manager component of the coredll module.

Functions

This component includes the following function:

RegisterClassW


The ctlpnl Module

The cplmain Module

Main control panel applet module.

Components

This module includes the following components:

backlight
colorscheme
comm
datetime
dialing
display
keyboard
mouse
network
owner
password
pointercmn
power
sip
sounds
stylus
system


The backlight Component

Backlight control panel applet component of the cplmain module.

This component has no public functions.


The colorscheme Component

Color schemes control panel applet component of the cplmain module.

This component has no public functions.


The comm Component

Communications control panel applet component of the cplmain module.

This component has no public functions.


The datetime Component

Date and time control panel applet component of the cplmain module.

This component has no public functions.


The dialing Component

Dialing control panel applet component of the cplmain module.

This component has no public functions.


The display Component

Display control panel applet component of the cplmain module.

This component has no public functions.


The keyboard Component

Keyboard control panel applet component of the cplmain module.

This component has no public functions.


The mouse Component

Mouse control panel applet component of the cplmain module.

This component has no public functions.


The network Component

Network control panel applet component of the cplmain module.

This component has no public functions.


The owner Component

Owner control panel applet component of the cplmain module.

This component has no public functions.


The password Component

Password control panel applet component of the cplmain module.

This component has no public functions.


The pointercmn Component

This control panel applet component of the cplmain module provides routines that are common to both the mouse and the stylus.

This component has no public functions.


The power Component

Power control panel applet component of the cplmain module.

This component has no public functions.


The sip Component

Soft Input Panel control panel applet component of the cplmain module.

This component has no public functions.


The sounds Component

Sounds control panel applet component of the cplmain module.

This component has no public functions.


The stylus Component

Stylus control panel applet component of the cplmain module.

This component has no public functions.


The system Component

System control panel applet component of the cplmain module.

This component has no public functions.


The ctlpnl Module

Control panel helper process module.

This module has no components or public functions.


The cxport Module

Common transport utilities module.

This module has no components or public functions.


The device Module

Installable device manager module.

This module has no components.

Functions

This module includes the following functions:

EnumDevices
EnumPnplds
GetDeviceKeys


The dhcp Module

Dynamic host configuration module.

This module has no components or public functions.


The dualio Module

PCMCIA client driver module for the Socket Communications Dual Serial I/O.

This module has no components or public functions.


The etcha Module

Sample module for drawing application.

This module has no components or public functions.


The explorer Module

Shell Explorer module for H/PC Pro.

This module has no components or public functions.


The fatfs Module

FAT file system module.

This module has no components.

Functions

This module includes the following functions:

FATFS_Deinit
FATFS_Init
FSD_Deinit
FSD_Init


The filesys Module

File system module.

Components

This module includes the following components:

fsdbase
fsheap
fsmain
fspass
fsreg
fsysram
fsysrom
pmstub


The fsdbase Component

Database component of the filesys module.

Functions

This component includes the following functions:

CeChangeDatabaseLCID
CeClearReplChangeBitsEx
CeCreateDatabase
CeCreateDatabaseEx
CeDeleteDatabase
CeDeleteDatabaseEx
CeDeleteRecord
CeEnumDBVolumes
CeFindFirstDatabase
CeFindFirstDatabaseEx
CeFindNextDatabase
CeFindNextDatabaseEx
CeFlushDBVol
CeGetReplChangeBitsEx
CeGetReplChangeMask
CeGetReplOtherBitsEx
CeMountDBVol
CeOpenDatabase
CeOpenDatabaseEx
CeReadRecordProps
CeReadRecordPropsEx
CeSeekDatabase
CeSetDatabaseInfo
CeSetDatabaseInfoEx
CeSetReplChangeBitsEx
CeSetReplChangeMask
CeSetReplOtherBitsEx
CeUnmountDBVol
CeWriteRecordProps
PegCreateDatabase
PegDeleteDatabase
PegDeleteRecord
PegFindFirstDatabase
PegFindNextDatabase
PegOpenDatabase
PegReadRecordProps
PegSeekDatabase
PegSetDatabaseInfo
PegWriteRecordProps


The fsheap Component

Heap file system component of the filesys module.

This component has no public functions.


The fsmain Component

Windows CE object store component of the filesys module.

Functions

This component includes the following functions:

CeOidGetInfo
CeOidGetInfoEx
PegOidGetInfo


The fspass Component

Password component of the filesys module.

This component has no public functions.


The fsreg Component

Registry component of the filesys module.

This component has no public functions.


The fsysram Component

RAM and ROM file system component of the filesys module.

This component has no public functions.


The fsysrom Component

ROM file system component of the filesys module.

This component has no public functions.


The pmstub Component

The file system support component of the filesys module.

This component has no public functions.

The fsdmgr Module

Installable file system manager module.

This module has no components.

Functions

This module includes the following functions:

FSDMGR_CreateFileHandle
FSDMGR_CreateSearchHandle
FSDMGR_DeinitEx
FSDMGR_DeregisterVolume
FSDMGR_GetDiskInfo
FSDMGR_GetVolumeName
FSDMGR_InitEx
FSDMGR_ReadDisk
FSDMGR_ReadDiskEx
FSDMGR_RegisterVolume
FSDMGR_WriteDisk
FSDMGR_WriteDiskEx

The generic Module

A sample application module.

This module has no components or public functions.


The gwes Module

Graphics, Windowing, and Events Subsystem (GWES) module.

Components

This module includes the following components:

accel
audio
btnctl
calibrui
caret
cascade
cdlctl
clipbd
cmbctl
column
cursor
cursor2
cursor8
defwndproc
dlgmgr
dlgmnem
drawmbar
edctl
foregnd
gcache
getpower
gsetwinlong
gwectrl
gweshare
gwesmain
hotkey
icon
iconcurs
idle
imgctl
immthunk
journal
kbdui
lbctl
loadbmp
loadimg
loadstr
mcursor
mcursor8
menu
menuscrl
mgalias
mgbase
mgbitmap
mgblt
mgblt2
mgdc
mgdibsec
mgdraw
mgdrwtxt
mgdx
mgfe
mgpal
mgpalnat
mgprint
mgrast
mgrast2
mgrgn
mgtci
mgtt
mgwinmgr
mnoover
mnotapui
msgbeep
msgbox
msgbox2
msgbox28
msgque
mtapui
nclient
nled
notifmin
notifpub
notify
oom
oomui
sbcmn
scbctl
startui
startup
stcctl
syscolor
tchui
timer
uibase
winmgr
wmbase


The accel Component

The accelerator key component of the gwes module.

Functions

This component includes the following function:

TranslateAccelerator


The audio Component

The audio component of the gwes module.

This component has no public functions.


The btnctl Component

Button control component of the gwes module.

This component has no public functions.


The calibrui Component

Touch screen calibration user interface component of the gwes module.

This component has no public functions.


The caret Component

The caret component of the gwes module.

Functions

This component includes the following functions:

CreateCaret
DestroyCaret
DisableCaretSystemWide
EnableCaretSystemWide
GetCaretBlinkTime
GetCaretPos
HideCaret
SetCaretBlinkTime
SetCaretPos
ShowCaret


The cascade Component

The cascading menu component of the gwes module.

This component has no public functions.


The cdlctl Component

Candidate list control component of the gwes module.

This component has no public functions.

The clipbd Component

The clipboard component of the gwes module.

Functions

This component includes the following functions:

CloseClipboard
CountClipboardFormats
EmptyClipboard
EnumClipboardFormats
GetClipboardData
GetClipboardDataAlloc
GetClipboardFormatName
GetClipboardOwner
GetOpenClipboardWindow
GetPriorityClipboardFormat
IsClipboardFormatAvailable
OpenClipboard
RegisterClipboardFormat
SetClipboardData


The cmbctl Component

Combo box control component of the gwes module.

This component has no public functions.


The column Component

The multi-column menu component of the gwes module.

This component has no public functions.


The cursor Component

Win32 cursor API component of the gwes module.

Functions

This component includes the following functions:

ClipCursor
GetClipCursor
GetCursor
GetCursorPos
LoadCursor
SetCursor
SetCursorPos
ShowCursor


The cursor2 Component

Win32 cursor API component of the gwes module, for 2-bit color.

This component has no public functions.


The cursor8 Component

Win32 cursor API component of the gwes module, for 8-bit color.

This component has no public functions.


The defwndproc Component

The default window process component of the gwes module.

This component has no public functions.


The dlgmgr Component

Dialog manager component of the gwes module.

Functions

This component includes the following functions:

CheckRadioButton
CreateDialogIndirectParam
DefDlgProc
DialogBoxIndirectParam
EndDialog
GetDialogBaseUnits
GetDlgCtrlID
GetDlgItem
GetDlgItemInt
GetDlgItemText
GetNextDlgGroupItem
GetNextDlgTabItem
IsDialogMessage
MapDialogRect
SendDlgItemMessage
SetDlgItemInt
SetDlgItemText


The dlgmnem Component

Dialog mnemonics component of the gwes module.

This component has no public functions.

The drawmbar Component

The menu bar component of the gwes module.

Functions

This component includes the following function:

DrawMenuBar


The edctl Component

Edit control component of the gwes module.

This component has no public functions.


The foregnd Component

Foreground window, active window, and focus component of the gwes module.

Functions

This component includes the following functions:

GetActiveWindow
GetCapture
GetFocus
GetForegroundInfo
GetForegroundKeyboardTarget
GetForegroundWindow
GetKeyboardTarget
ReleaseCapture
SetActiveWindow
SetCapture
SetFocus
SetForegroundWindow
SetKeyboardTarget
ShellModalEnd

The gcache Component

The window manager cache component of the gwes module.

This component has no public functions.


The getpower Component

Battery power component of the gwes module.

Functions

This component includes the following functions:

BatteryGetLifeTimeInfo
BatteryNotifyOfTimeChange
GetSystemPowerStatusEx
GetSystemPowerStatusEx2


The gsetwinlong Component

Get/SetWindowLong component of the gwes module.

This component has no public functions.


The gwectrl Component

Graphics, Windowing, and Events Subsystem (GWES) base component of the gwes module.

This component has no public functions.


The gweshare Component

GWES shared routines component of the gwes module.

This component has no public functions.


The gwesmain Component

GWES initialization component of the gwes module.

Functions

This component includes the following function:

NotifyWinUserSystem


The hotkey Component

The Win32 hotkey component of the gwes module.

This component has no public functions.


The icon Component

Win32 icon support component of the gwes module.

Functions

This component includes the following functions:

CreateIconIndirect
DestroyIcon
DrawIconEx
LoadIcon


The iconcurs Component

Win32 icon support component of the gwes module.

Functions

This component includes the following functions:

CreateCursor
DestroyCursor


The idle Component

System-idle timer component of the gwes module.

Functions

This component includes the following function:

SystemIdleTimerReset


The imgctl Component

Image control component of the gwes module.

Functions

This component includes the following functions:

ImageList_Add
ImageList_AddMasked
ImageList_BeginDrag
ImageList_Copy
ImageList_CopyDitherImage
ImageList_Create
ImageList_Destroy
ImageList_DragEnter
ImageList_DragLeave
ImageList_DragMove
ImageList_DragShowNolock
ImageList_Draw
ImageList_DrawEx
ImageList_DrawIndirect
ImageList_Duplicate
ImageList_EndDrag
ImageList_GetBkColor
ImageList_GetDragImage
ImageList_GetIcon
ImageList_GetIconSize
ImageList_GetImageCount
ImageList_GetImageInfo
ImageList_LoadImage
ImageList_Merge
ImageList_Remove
ImageList_Replace
ImageList_ReplaceIcon
ImageList_SetBkColor
ImageList_SetDragCursorImage
ImageList_SetIconSize
ImageList_SetImageCount
ImageList_SetOverlayImage


The immthunk Component

IMM thunking component of the gwes module.

This component has no public functions.


The journal Component

The journal component of the gwes module.

Functions

This component includes the following functions:

QASetWindowsJournalHook
QAUnhookWindowsJournalHook


The kbdui Component

Keyboard interface component of the gwes module.

Functions

This component includes the following functions:

CallNextHookEx
EnableHardwareKeyboard
GetAsyncKeyState
GetAsyncShiftFlags
GetKeyboardLayoutName
GetKeyboardStatus
keybd_event
KeybdGetDeviceInfo
KeybdInitStates
KeybdVKeyToUnicode
MapVirtualKey
PostKeybdMessage
SetWindowsHookEx
UnhookWindowsHookEx


The lbctl Component

Listbox component of the gwes module.

This component has no public functions.


The loadbmp Component

The bitmap loading component of the gwes module.

Functions

This component includes the following function:

LoadBitmap


The loadimg Component

The image loading component of the gwes module.

Functions

This component includes the following function:

LoadImage


The loadstr Component

String loading component of the gwes module.

Functions

This component includes the following function:

LoadString


The mcursor Component

Win32 cursor support component of the gwes module.

Functions

This component includes the following functions:

ClipCursor
GetClipCursor
GetCursor
GetCursorPos
LoadCursor
SetCursor
SetCursorPos
ShowCursor


The mcursor8 Component

Eight-bit Win32 cursor support component of the gwes module.

This component has no public functions.


The menu Component

Win32 base menu control component of the gwes module.

Functions

This component includes the following functions:

AppendMenuW
CheckMenuItem
CheckMenuRadioItem
CreateMenu
CreatePopupMenu
DeleteMenu
DestroyMenu
EnableMenuItem
GetMenuItemInfoW
GetSubMenu
InsertMenuW
LoadMenuW
RemoveMenu
SetMenuItemInfoW
TrackPopupMenuEx


The menuscrl Component

The scrolling menu support component of the gwes module.

This component has no public functions.


The mgalias Component

The GDI font alias support component of the gwes module.

This component has no public functions.


The mgbase Component

Graphical Device Interface (GDI) base component of the gwes module.

Functions

This component includes the following functions:

CreateCompatibleDC
DeleteDC
DeleteObject
GetBkColor
GetBkMode
GetCurrentObject
GetDeviceCaps
GetObject
GetObjectType
GetStockObject
GetTextColor
SelectObject
SetBkColor
SetBkMode
SetTextColor
SetViewportOrgEx


The mgbitmap Component

Graphical Device Interface (GDI) bitmap component of the gwes module.

Functions

This component includes the following functions:

CreateBitmap
CreateCompatibleBitmap


The mgblt Component

Bit block transfer component of the gwes module.

Functions

This component includes the following function:

BitBlt


The mgblt2 Component

Bitmap transfer component of the gwes module.

Functions

This component includes the following functions:

MaskBlt
StretchBlt
TransparentImage


The mgdc Component

Device context component of the gwes module.

Functions

This component includes the following functions:

CreateDC
ExtEscape
RestoreDC
SaveDC


The mgdibsec Component

This component of the gwes module creates device-independent bit map sections.

This component has no public functions.


The mgdraw Component

Drawing tool component of the gwes module.

Functions

This component includes the following functions:

CreateDIBPatternBrushPt
CreatePatternBrush
CreatePen
CreatePenIndirect
CreateSolidBrush
DrawEdge
DrawFocusRect
Ellipse
FillRect
FillRgn
GetPixel
GetSysColorBrush
PatBlt
Polygon
Polyline
Rectangle
RoundRect
SetBrushOrgEx
SetPixel
SetROP2


The mgdrwtxt Component

Text drawing component of the gwes module.

Functions

This component includes the following function:

DrawText


The mgdx Component

The DirectDraw bitmap component of the gwes module.

Functions

This component includes the following function:

CreateBitmapFromPointer


The mgfe Component

This component of the gwes module provides Asian word-break support for GDI.

This component has no public functions.


The mgpal Component

Palette support component of the gwes module.

Functions

This component includes the following functions:

CreatePalette
GetNearestColor
GetNearestPaletteIndex
GetPaletteEntries
GetSystemPaletteEntries
RealizePalette
SelectPalette
SetPaletteEntries


The mgpalnat Component

Palette support component of the gwes module.

This component has no public functions.


The mgprint Component

Printing support component of the gwes module.

Functions

This component includes the following functions:

AbortDoc
CloseEnhMetaFile
CreateEnhMetaFile
DeleteEnhMetaFile
EndDoc
EndPage
PlayEnhMetaFile
SetAbortProc
StartDoc
StartPage


The mgrast Component

Raster font engine component of the gwes module.

Functions

This component includes the following functions:

AddFontResource
CeRemoveFontResource
CreateFontIndirect
EnableEUDC
ExtTextOut
GetTextExtentExPoint
GetTextMetrics
PegRemoveFontResource
RemoveFontResource


The mgrast2 Component

Raster font engine component of the gwes module.

Functions

This component includes the following functions:

EnumFontFamilies
EnumFonts
GetTextFace


The mgrgn Component

Drawing region support component of the gwes module.

Functions

This component includes the following functions:

CombineRgn
CreateRectRgn
CreateRectRgnIndirect
ExcludeClipRect
GetClipBox
GetClipRgn
GetRegionData
GetRgnBox
IntersectClipRect
OffsetRgn
PtInRegion
RectInRegion
RectVisible
SelectClipRgn
SetRectRgn

The mgtci Component

The Win32 TranslateCharsetInfo component of the gwes module.

Functions

This component includes the following function:

TranslateCharsetInfo


The mgtt Component

TrueType font component of the gwes module.

Functions

This component includes the following functions:

AddFontResource
CeRemoveFontResource
CreateFontIndirect
EnableEUDC
EnumFontFamilies
EnumFonts
ExtTextOut
GetTextExtentExPoint
GetTextFace
GetTextMetrics
PegRemoveFontResource
RemoveFontResource


The mgwinmgr Component

GDI and user-shared interface component of the gwes module.

Functions

This component includes the following functions:

ScrollDC
SetObjectOwner


The mnoover Component

Win32 menu-control support component of the gwes module.

This component has no public functions.


The mnotapui Component

Win32 menu-control support component of the gwes module.

This component has no public functions.


The msgbeep Component

The Win32 MessageBeep component of the gwes module.

Functions

This component includes the following function:

MessageBeep


The msgbox Component

Primary message box component of the gwes module.

Functions

This component includes the following function:

MessageBox


The msgbox2 Component

Support component of the gwes module for message boxes with 2 bits per pixel.

This component has no public functions.


The msgbox28 Component

Support component of the gwes module for message boxes with 2 bits per pixel or 8 bits per pixel.

This component has no public functions.


The msgque Component

Message queue component of the gwes module.

Functions

This component includes the following functions:

DispatchMessage
GetKeyState
GetMessage
GetMessagePos
GetMessageSource
GetMessageWNoWait
MsgWaitForMultipleObjectsEx
PeekMessage
PostMessage
PostQuitMessage
SendMessage
SendNotifyMessage
TranslateMessage


The mtapui Component

Win32 menu-control support component of the gwes module.

This component has no public functions.


The nclient Component

The non-client area window manager component of the gwes module.

Functions

This component includes the following function:

DrawFrameControl


The nled Component

Notification LED component of the gwes module.

Functions

This component includes the following functions:

NLedGetDeviceInfo
NLedSetDevice


The notifmin Component

This component of the gwes module, along with the notifpub and notify components, supports the Windows CE event notification subsystem.

This component has no public functions.


The notifpub Component

This component of the gwes module, along with the notifmin and notify components, supports the Windows CE event notification subsystem.

This component has no public functions.


The notify Component

This component of the gwes module, along with the notifmin and notifpub components, supports the Windows CE event notification subsystem.

Functions

This component includes the following functions:

CeClearUserNotification
CeGetUserNotification
CeGetUserNotificationHandles
CeGetUserNotificationPreferences
CeHandleAppNotifications
CeRunAppAtEvent
CeRunAppAtTime
CeSetUserNotification
CeSetUserNotificationEx
PegClearUserNotification
PegGetUserNotificationPreferences
PegHandleAppNotifications
PegRunAppAtEvent
PegRunAppAtTime
PegSetUserNotification


The oom Component

Out-of-memory component of the gwes module.

This component has no public functions.


The oomui Component

Out-of-memory user interface component of the gwes module.

This component has no public functions.


The sbcmn Component

The scroll bar control component of the gwes module.

Functions

This component includes the following functions:

GetScrollInfo
SetScrollInfo
SetScrollPos
SetScrollRange


The scbctl Component

Scroll bar control component of the gwes module.

This component has no public functions.


The startui Component

Startup-dialog user interface component of the gwes module.

This component has no public functions.


The startup Component

Startup component of the gwes module.

This component has no public functions.


The stcctl Component

Static control component of the gwes module.

This component has no public functions.


The syscolor Component

The Win32 system color support component of the gwes module.

This component has no public functions.


The tchui Component

Touch-screen user interface component of the gwes module.

Functions

This component includes the following function:

TouchCalibrate


The timer Component

The Win32 timer component of the gwes module.

Functions

This component includes the following functions:

KillTimer
SetTimer


The uibase Component

User-interface base component of the gwes module.

The user input system queue implementation

Functions

This component includes the following functions:

GetMouseMovePoints
mouse_event
SendInput

The winmgr Component

The window manager component of the gwes module.

Functions

This component includes the following functions:

AdjustWindowRectEx
GetDoubleClickTime
GetSysColor
RegisterTaskBar
RegisterWindowMessage
SetSysColors


The wmbase Component

The window manager support component of the gwes module.

Functions

This component includes the following functions:

GetClassInfo
GetClassLong
GetSystemMetrics
IsWindowVisible
RegisterClassWStub
SetClassLong
UnregisterClass

The hello Module

Hello sample application module.

This module has no components or public functions.

The htmlview Module

The HTML help engine control module.

This module has no components or public functions.


The hwxjpn Module

Japanese handwriting module.

This module has no components.

Functions

This module includes the following functions:

HwxALCPriority
HwxALCValid
HwxConfig
HwxCreate
HwxDestroy
HwxEndInput
HwxGetResults
HwxInput
HwxProcess
HwxResultsAvailable
HwxSetAbort
HwxSetContext
HwxSetGuide
HwxSetPartial


The hwxusa Module

English handwriting module.

This module has no components.

Functions

This module includes the following functions:

HwxALCPriority
HwxALCValid
HwxConfig
HwxCreate
HwxDestroy
HwxEndInput
HwxGetResults
HwxInput
HwxProcess
HwxResultsAvailable
HwxSetAbort
HwxSetContext
HwxSetGuide
HwxSetPartial

The iexplore Module

Pocket Internet Explorer module.

This module has no components or public functions.

The imgdecmp Module

Pocket Internet Explorer image decompression module.

This module has no components or public functions.


The intl Module

The intll Module

Regional settings control panel applet module.

This module has no components or public functions.


The ircomm Module

Infrared (IrDA) communications module.

This module has no components or public functions.


The irdastk Module

Stack module for Infrared (IrDA) communications.

This module has no components.

Functions

This module includes the following function:

Register


The jscript Module

JScript® module.

This module has no components.

Functions

This module includes the following function:

DllMain


The kbdmsg Module

Keyboard sample test application module.

This module has no components or public functions.


The mlang Module

This module, along with the mshtml, shdocvw, urlmon, and wininet modules, provides support for Internet Explorer capabilities.

This module has no components.

Functions

This module includes the following functions:

ConvertINetMultiByteToUnicode
ConvertINetReset
ConvertINetString
ConvertINetUnicodeToMultiByte
IsConvertINetStringAvailable
LcidToRfc1766A
LcidToRfc1766W
Rfc1766ToLcidA
Rfc1766ToLcidW


The mqoa Module

This module, along with the msmqapi, msmqd, msmqdm, and msmqrt modules, provides MSMQ support.

This module has no components or public functions.


The msfilter Module

Sample ACM filter module.

This module has no components.

Functions

This module includes the following functions:

ACM_Close
ACM_Deinit
ACM_Init
ACM_IOControl
ACM_Open
ACM_PowerDown
ACM_PowerUp
ACM_Read
ACM_Seek
ACM_Write


The mshtml Module

This module, along with the mlang, shdocvw, urlmon, and wininet modules, provides support for Internet Explorer capabilities.

This module has no components or public functions.


The msim Module

U.S. input method module.

This module has no components or public functions.


The msmqapi Module

This module, along with the mqoa, msmqd, msmqdm, and msmqrt modules, provides MSMQ support.

This module has no components.

Functions

This module includes the following functions:

MQBeginTransaction
MQCloseCursor
MQCloseQueue
MQCreateCursor
MQCreateQueue
MQDeleteQueue
MQFreeClientAPI
MQFreeMemory
MQFreeSecurityContext
MQGetMachineProperties
MQGetQueueProperties
MQGetQueueSecurity
MQGetSecurityContext
MQHandleToFormatName
MQInitClientAPI
MQInstanceToFormatName
MQLocateBegin
MQLocateBeginLocalPrivate
MQLocateBeginRemotePrivate
MQLocateEnd
MQLocateEndPrivate
MQLocateNext
MQLocateNextPrivate
MQMgmtAction
MQMgmtGetInfo
MQOpenQueue
MQPathNameToFormatName
MQReceiveMessage
MQSendMessage
MQSetQueueProperties
MQSetQueueSecurity


The msmqd Module

This module, along with the mqoa, msmqapi, msmqdm, and msmqrt modules, provides MSMQ support.

This module has no components or public functions.


The msmqdm Module

This module, along with the mqoa, msmqapi, msmqd, and msmqrt modules, provides MSMQ support.

This module has no components or public functions.


The msmqrt Module

This module, along with the mqoa, msmqapi, msmqd, and msmqdm modules, provides MSMQ support.

This module has no components or public functions.


The ndis Module

NDIS network module.

This module has no components.

Functions

This module includes the following functions:

EthChangeFilterAddresses
EthCreateFilter
EthDeleteFilter
EthDeleteFilterOpenAdapter
EthFilterAdjust
EthFilterDprIndicateReceive
EthFilterDprIndicateReceiveComplete
EthFilterDprIndicateReceivePacket
EthFilterIndicateReceive
EthFilterIndicateReceiveComplete
EthNoteFilterOpenAdapter
EthNumberOfOpenFilterAddresses
EthQueryGlobalFilterAddresses
EthQueryOpenFilterAddresses
EthShouldAddressLoopBack
NDIS_BUFFER_TO_SPAN_PAGES
NdisAcquireSpinLock
NdisAdjustBufferLength
NdisAllocateBuffer
NdisAllocateBufferPool
NdisAllocateMemory
NdisAllocatePacket
NdisAllocatePacketPool
NdisAllocateSpinLock
NdisAnsiStringToUnicodeString
NdisCloseAdapter
NdisCloseConfiguration
NdisCopyFromPacketToPacket
NdisDeregisterProtocol
NdisDprAcquireSpinLock
NdisDprReleaseSpinLock
NdisEqualString
NdisFlushBuffer
NdisFreeBuffer
NdisFreeBufferPool
NdisFreeMemory
NdisFreePacket
NdisFreePacketPool
NdisFreeSpinLock
NdisIMRevertBack
NdisIMSwitchToMiniport
NdisInitAnsiString
NdisInitializeListHead
NdisInitializeString
NdisInitializeWrapper
NdisInitUnicodeString
NdisInterlockedInsertHeadList
NdisInterlockedInsertTailList
NdisInterlockedRemoveHeadList
NdisMAllocateMapRegisters
NdisMCancelTimer
NdisMDeregisterAdapterShutdownHandler
NdisMDeregisterInterrupt
NdisMDeregisterIoPortRange
NdisMFreeMapRegisters
NdisMIndicateStatus
NdisMIndicateStatusComplete
NdisMInitializeTimer
NdisMMapIoSpace
NdisMPciAssignResources
NdisMQueryInformationComplete
NdisMRegisterAdapterShutdownHandler
NdisMRegisterInterrupt
NdisMRegisterIoPortRange
NdisMRegisterMiniport
NdisMSetAttributes
NdisMSetAttributesEx
NdisMSetInformationComplete
NdisMSetPeriodicTimer
NdisMSleep
NdisMSynchronizeWithInterrupt
NdisMTransferDataComplete
NdisMUnmapIoSpace
NdisOpenAdapter
NdisOpenConfiguration
NdisOpenProtocolConfiguration
NdisQueryBuffer
NdisQueryBufferOffset
NdisQueryMapRegisterCount
NdisReadConfiguration
NdisReadNetworkAddress
NdisReadPciSlotInformation
NdisRegisterProtocol
NdisReleaseSpinLock
NdisReset
NdisReturnPackets
NdisSetTimer
NdisTerminateWrapper
NdisUnchainBufferAtBack
NdisUnchainBufferAtFront
NdisUnicodeStringToAnsiString
NdisWriteConfiguration
NdisWriteErrorLogEntry
NdisWritePciSlotInformation
NDS_Close
NDS_Deinit
NDS_Init
NDS_IOControl
NDS_Open
NDS_PowerDown
NDS_PowerUp
NDS_Read
NDS_Seek
NDS_Write


The ne2000 Module

NE2000 NDIS miniport driver module.

This module has no components.

Functions

This module includes the following functions:

DetectNE2000
DriverEntry
Install_Driver


The netbios Module

Netbios over TCP/IP module.

This module has no components or public functions.


The netdetec Module

Network detect (ping) module.

This module has no components or public functions.


The netui Module

Network user-interface module.

This module has no components.

Functions

This module includes the following functions:

AdapterIPProperties
ConnectionDialog
DisconnectDialog
GetDriverName
GetIPAddress
GetNetString
GetResourcePassword
GetUsernamePassword
LineConfigEdit
LineTranslateDialog
NetMsgBox
RegisterIPClass
UnregisterIPClass


The nk Module

Operating system kernel module. This module is always required.

This module has no components or public functions.


The ntlmssp Module

NT Lan Manager secure socket provider module.

This module has no components.

Functions

This module includes the following function:

InitSecurityInterface


The ole32 Module

OLE support module.

Components

This module includes the following components:

com
docfile
exp
msf
ole232
olemain
stg


The com Component

Component object model (COM) interface component of the ole32 module.

This component has no public functions.


The docfile Component

Win32 docfile component of the ole32 module.

Functions

This component includes the following functions:

StgCreateDocfile
StgCreateDocfileOnILockBytes
StgOpenStorage
StgOpenStorageOnILockBytes


The exp Component

OLE storage services component of the ole32 module.

This component has no public functions.


The msf Component

OLE storage support component of the ole32 module.

This component has no public functions.


The ole232 Component

OLE services support component of the ole32 module.

Functions

This component includes the following functions:

CreateOleAdviseHolder
OleCreate
OleDraw
OleIsRunning
OleRun
OleSave
OleSetContainedObject
OleSetMenuDescriptor
ReadClassStg
ReadClassStm
ReleaseStgMedium
WriteClassStg
WriteClassStm


The olemain Component

OLE main component of the ole32 module.

This component has no public functions.


The stg Component

OLE lightweight storage component of the ole32 module.

Functions

This component includes the following functions:

CreateStreamOnHGlobal
GetHGlobalFromStream
StgCreateDocfile
StgOpenStorage


The oleaut32 Module

OLE automation module.

This module has no components.

Functions

This module includes the following functions:

BstrFromVector
CreateErrorInfo
CreateTypeLib2
DispGetIDsOfNames
DispGetParam
DispInvoke
GetErrorInfo
LoadRegTypeLib
LoadTypeLib
RegisterTypeLib
SafeArrayAccessData
SafeArrayAllocData
SafeArrayAllocDescriptor
SafeArrayCopy
SafeArrayCopyData
SafeArrayCreate
SafeArrayCreateVector
SafeArrayDestroy
SafeArrayDestroyData
SafeArrayDestroyDescriptor
SafeArrayGetDim
SafeArrayGetElement
SafeArrayGetElemsize
SafeArrayGetLBound
SafeArrayGetUBound
SafeArrayLock
SafeArrayPtrOfIndex
SafeArrayPutElement
SafeArrayRedim
SafeArrayUnaccessData
SafeArrayUnlock
SetErrorInfo
SysAllocString
SysAllocStringByteLen
SysAllocStringLen
SysFreeString
SysReAllocString
SysReAllocStringLen
SysStringByteLen
SysStringLen
SystemTimeToVariantTime
VarBoolFromCy
VarBoolFromDate
VarBoolFromDec
VarBoolFromDisp
VarBoolFromI1
VarBoolFromI2
VarBoolFromI4
VarBoolFromR4
VarBoolFromR8
VarBoolFromStr
VarBoolFromUI1
VarBoolFromUI2
VarBoolFromUI4
VarBstrFromBool
VarBstrFromCy
VarBstrFromDate
VarBstrFromDec
VarBstrFromDisp
VarBstrFromI1
VarBstrFromI2
VarBstrFromI4
VarBstrFromR4
VarBstrFromR8
VarBstrFromUI1
VarBstrFromUI2
VarBstrFromUI4
VarCyFromBool
VarCyFromDate
VarCyFromDec
VarCyFromDisp
VarCyFromI1
VarCyFromI2
VarCyFromI4
VarCyFromR4
VarCyFromR8
VarCyFromStr
VarCyFromUI1
VarCyFromUI2
VarCyFromUI4
VarDateFromBool
VarDateFromCy
VarDateFromDec
VarDateFromDisp
VarDateFromI1
VarDateFromI2
VarDateFromI4
VarDateFromR4
VarDateFromR8
VarDateFromStr
VarDateFromUdate
VarDateFromUI1
VarDateFromUI2
VarDateFromUI4
VarDecFromBool
VarDecFromCy
VarDecFromDate
VarDecFromDisp
VarDecFromI1
VarDecFromI2
VarDecFromI4
VarDecFromR4
VarDecFromR8
VarDecFromStr
VarDecFromUI1
VarDecFromUI2
VarDecFromUI4
VarI1FromBool
VarI1FromCy
VarI1FromDate
VarI1FromDec
VarI1FromDisp
VarI1FromI2
VarI1FromI4
VarI1FromR4
VarI1FromR8
VarI1FromStr
VarI1FromUI1
VarI1FromUI2
VarI1FromUI4
VarI2FromBool
VarI2FromCy
VarI2FromDate
VarI2FromDec
VarI2FromDisp
VarI2FromI1
VarI2FromI4
VarI2FromR4
VarI2FromR8
VarI2FromStr
VarI2FromUI1
VarI2FromUI2
VarI2FromUI4
VarI4FromBool
VarI4FromCy
VarI4FromDate
VarI4FromDec
VarI4FromDisp
VarI4FromI1
VarI4FromI2
VarI4FromR4
VarI4FromR8
VarI4FromStr
VarI4FromUI1
VarI4FromUI2
VarI4FromUI4
VariantChangeType
VariantChangeTypeEx
VariantClear
VariantCopy
VariantCopyInd
VariantInit
VariantTimeToSystemTime
VarNumFromParseNum
VarParseNumFromStr
VarR4FromBool
VarR4FromCy
VarR4FromDate
VarR4FromDec
VarR4FromDisp
VarR4FromI1
VarR4FromI2
VarR4FromI4
VarR4FromR8
VarR4FromStr
VarR4FromUI1
VarR4FromUI2
VarR4FromUI4
VarR8FromBool
VarR8FromCy
VarR8FromDate
VarR8FromDec
VarR8FromDisp
VarR8FromI1
VarR8FromI2
VarR8FromI4
VarR8FromR4
VarR8FromStr
VarR8FromUI1
VarR8FromUI2
VarR8FromUI4
VarUdateFromDate
VarUI1FromBool
VarUI1FromCy
VarUI1FromDate
VarUI1FromDec
VarUI1FromDisp
VarUI1FromI1
VarUI1FromI2
VarUI1FromI4
VarUI1FromR4
VarUI1FromR8
VarUI1FromStr
VarUI1FromUI2
VarUI1FromUI4
VarUI2FromBool
VarUI2FromCy
VarUI2FromDate
VarUI2FromDec
VarUI2FromDisp
VarUI2FromI1
VarUI2FromI2
VarUI2FromI4
VarUI2FromR4
VarUI2FromR8
VarUI2FromStr
VarUI2FromUI1
VarUI2FromUI4
VarUI4FromBool
VarUI4FromCy
VarUI4FromDate
VarUI4FromDec
VarUI4FromDisp
VarUI4FromI1
VarUI4FromI2
VarUI4FromI4
VarUI4FromR4
VarUI4FromR8
VarUI4FromStr
VarUI4FromUI1
VarUI4FromUI2
VectorFromBstr


The parallel Module

Parallel port driver module.

This module has no components or public functions.


The pcl Module

PCL printer driver module.

This module has no components or public functions.


The peghelp Module

HTML-based help module.

This module has no components or public functions.


The pegterm Module

Terminal-style application module.

This module has no components or public functions.


The ppp Module

Point-to-point protocol module.

This module has no components.

Functions

This module includes the following functions:

RasDeleteEntry
RasDial
RasEnumConnections
RasEnumEntries
RasGetConnectStatus
RasGetEntryDevConfig
RasGetEntryDialParams
RasGetEntryProperties
RasHangUp
RasHangup
RasIOControl
RasRenameEntry
RasSetEntryDevConfig
RasSetEntryDialParams
RasSetEntryProperties
RasValidateEntryName


The prnerr Module

Printer port error information and dialog module.

This module has no components or public functions.


The prnport Module

Printer transport layer module.

This module has no components or public functions.


The proxim Module

Proxim wireless ethernet module.

This module has no components.

Functions

This module includes the following functions:

DriverEntry
Install_Driver


The ramdisk Module

RAM disk driver module.

This module has no components or public functions.


The rasdemo Module

Remote Access Server (RAS) demo application module.

This module has no components or public functions.


The redir Module

Network redirector module and support for Win32 WNet APIs.

This module has no components.

Functions

This module includes the following functions:

WNetAddConnection3
WNetCancelConnection2
WNetCloseEnum
WNetConnectionDialog1
WNetDisconnectDialog
WNetDisconnectDialog1
WNetEnumResource
WNetGetConnection
WNetGetUniversalName
WNetGetUser
WNetOpenEnum


The remnet Module

Remote network dialing application module.

This module has no components or public functions.


The rnaapp Module

Remote network dialing application support module.

This module has no components or public functions.


The rsabase Module

RSA encryption module.

This module has no components or public functions.


The schannel Module

SSL/PCT secure socket protocol module.

This module has no components.

Functions

This module includes the following functions:

AcceptSecurityContext
AcquireCredentialsHandle
ApplyControlToken
CompleteAuthToken
DeleteSecurityContext
EnumerateSecurityPackages
FreeContextBuffer
FreeCredentialsHandle
ImpersonateSecurityContext
InitializeSecurityContext
InitSecurityInterface
MakeSignature
QueryContextAttributes
QuerySecurityPackageInfo
RevertSecurityContext
SealMessage
SecurityPackageControl
SPReInit
SslCrackCertificate
SslFreeCertificate
SslGenerateKeyPair
SslGenerateRandomBits
SslGetDefaultIssuers
SslGetMaximumKeySize
SslGetProtocols
SslLoadCertificate
SslSetProtocols
UnsealMessage
VerifySignature


The secur32 Module

Security protocol manager module.

This module has no components.

Functions

This module includes the following functions:

AcceptSecurityContext
AcquireCredentialsHandle
ApplyControlToken
DeleteSecurityContext
EnumerateSecurityPackages
FreeContextBuffer
FreeCredentialsHandle
ImpersonateSecurityContext
InitSecurityInterface
InitializeSecurityContext
MakeSignature
QueryContextAttributes
QueryCredentialsAttributes
QuerySecurityPackageInfo
RevertSecurityContext
SealMessage
UnsealMessage
VerifySignature


The shdocvw Module

This module, along with the mlang, mshtml, urlmon, and wininet modules, provides support for Internet Explorer capabilities.

This module has no components.

Functions

This module includes the following functions:

HlinkFindFrame
HlinkFrameNavigate
HlinkFrameNavigateNHL


The shell Module

Debugging shell module.

This module has no components or public functions.


The softkb Module

Soft Input Panel (SIP) device driver module.

This module has no components or public functions.


The spincube Module

Spinning cube sample application module.

This module has no components or public functions.


The splusa Module

U.S. speller module.

This module has no components.

Functions

This module includes the following functions:

SplAddUserDict
SplCheck
SplClrUserDict
SplEnumUserDict
SplInit
SplLimitGet
SplLimitSet
SplOptionGet
SplOptionSet
SplQuit
SplRemUserDict
SplReplace
SplSizeUserDict
SplSuggest


The sramdisk Module

SRAM (PCMCIA) device module.

This module has no components or public functions.


The tapi Module

Telephony API (TAPI) support module.

This module has no components.

Functions

This module includes the following functions:

lineAddProvider
lineClose
lineConfigDialogEdit
lineDeallocateCall
lineDrop
lineGetDevCaps
lineGetDevConfig
lineGetID
lineGetTranslateCaps
lineInitialize
lineMakeCall
lineNegotiateAPIVersion
lineOpen
lineSetCurrentLocation
lineSetDevConfig
lineSetStatusMessages
lineShutdown
lineTranslateAddress
lineTranslateDialog


The taskman Module

Task Manager module.

This module has no components or public functions.


The tcpstk Module

TCP/IP stack module.

This module has no components or public functions.


The termctrl Module

Terminal-style application module.

This module has no components or public functions.


The testime Module

Sample Input Method Editor (IME) application module.

This module has no components or public functions.


The text Module

Sample text application module.

This module has no components or public functions.


The toolhelp Module

Toolhelp debugger support module.

This module has no components.

Functions

This module includes the following functions:

CloseToolhelp32Snapshot
CreateToolhelp32Snapshot
Heap32First
Heap32ListFirst
Heap32ListNext
Heap32Next
Module32First
Module32Next
Process32First
Process32Next
Thread32First
Thread32Next
Toolhelp32ReadProcessMemory


The trueffs Module

TrueFFS block device driver module.

This module has no components or public functions.


The unimodem Module

Unimodem module; TAPI service provider for AT command modems.

This module has no components.

Functions

This module includes the following functions:

TSPI_lineGetProcTable
TSPI_providerInit
TSPI_providerShutdown


The urlmon Module

This module, along with the mlang, mshtml, shdocvw, and wininet modules, provides support for Internet Explorer capabilities.

This module has no components.

Functions

This module includes the following functions:

CoInternetCombineUrl
CoInternetCompareUrl
CoInternetCreateSecurityManager
CoInternetCreateZoneManager
CoInternetGetSecurityUrl
CoInternetGetSession
CoInternetParseUrl
CoInternetQueryInfo
CreateAsyncBindCtxEx
CreateURLMoniker
FindMediaType
FindMediaTypeClass
FindMimeFromData
GetClassFileOrMime
IsAsyncMoniker
MkParseDisplayNameEx
ObtainUserAgentString
RegisterBindStatusCallback
ReleaseBindInfo
RevokeBindStatusCallback
UrlMkBuildVersion


The usbd Module

Universal Serial Bus (USB) module.

This module has no components.

Functions

This module includes the following functions:

GetUSBDVersion
HcdAttach
HcdDetach
HcdDeviceAttached
HcdDeviceDetached
OpenClientRegistryKey
RegisterClientDriverID
RegisterClientSettings
UnRegisterClientDriverID
UnRegisterClientSettings


The usbhid Module

USB HID driver module.

This module has no components.

Functions

This module includes the following functions:

HID_Close
HID_Deinit
HID_Init
HID_IOControl
HID_Open
HID_Read
HID_Seek
HID_Write
USBDeviceAttach
USBInstallDriver


The usbmouse Module

Universal Serial Bus (USB) mouse driver module.

This module has no components or public functions.


The uuid Module

Universally unique identifier (UUID) support module.

This module has no components or public functions.


The waveapi Module

Wave and ACM audio API module.

This module has no components.

Functions

This module includes the following functions:

ACM_Close
ACM_Deinit
ACM_Init
ACM_IOControl
ACM_Open
ACM_PowerDown
ACM_PowerUp
ACM_Read
ACM_Seek
ACM_Write
WAM_Close
WAM_Deinit
WAM_Init
WAM_IOControl
WAM_Open
WAM_PowerDown
WAM_PowerUp
WAM_Read
WAM_Seek
WAM_Write
WaveApiDllEntry


The webview Module

Pocket Internet Explorer HTML module.

This module has no components or public functions.


The wininet Module

Internet support module. This module, along with the mlang, mshtml, shdocvw, and urlmon modules, provides support for Internet Explorer capabilities.

This module has no components.

Functions

This module includes the following functions:

CommitUrlCacheEntry
CreateUrlCacheEntry
CreateUrlCacheGroup
DeleteUrlCacheEntry
DeleteUrlCacheGroup
FindCloseUrlCache
FindFirstUrlCacheEntry
FindFirstUrlCacheEntryEx
FindNextUrlCacheEntry
FindNextUrlCacheEntryEx
FreeUrlCacheSpace
FtpCommand
FtpCreateDirectory
FtpDeleteFile
FtpFindFirstFile
FtpGetCurrentDirectory
FtpGetFile
FtpOpenFile
FtpPutFile
FtpRemoveDirectory
FtpRenameFile
FtpSetCurrentDirectory
GetUrlCacheConfigInfo
GetUrlCacheEntryInfo
GetUrlCacheEntryInfoEx
HttpAddRequestHeaders
HttpEndRequest
HttpOpenRequest
HttpQueryInfo
HttpSendRequest
HttpSendRequestEx
InternetCanonicalizeUrl
InternetCloseHandle
InternetCombineUrl
InternetConnect
InternetCrackUrl
InternetCreateUrl
InternetErrorDlg
InternetFindNextFile
InternetGetConnectedState
InternetGetCookie
InternetGetLastResponseInfo
InternetGoOnline
InternetLockRequestFile
InternetOpen
InternetOpenUrl
InternetQueryDataAvailable
InternetQueryOption
InternetReadFile
InternetSetCookie
InternetSetFilePointer
InternetSetOption
InternetSetStatusCallback
InternetTimeFromSystemTime
InternetTimeToSystemTime
InternetUnlockRequestFile
InternetWriteFile
RetrieveUrlCacheEntryFile
SetUrlCacheConfigInfo
SetUrlCacheEntryGroup
SetUrlCacheEntryInfo
UnlockUrlCacheEntryFile


The winsock Module

Winsock services module.

Components

This module includes the following component:

sslsock

Functions

This module includes the following functions:

__WSAFDIsSet
accept
bind
closesocket
connect
EnumProtocols
gethostbyaddr
gethostbyname
gethostname
getpeername
getsockname
getsockopt
htonl
htons
inet_addr
inet_ntoa
ioctlsocket
listen
ntohl
ntohs
recv
recvfrom
select
send
sendto
sethostname
setsockopt
shutdown
socket
WSACleanup
WSAIoctl
WSAStartup
WsControl


The sslsock Component

SSL Winsock support component of the winsock module.

This component has no public functions.


The xircce2 Module

Xircom Ethernet driver module.

This module has no components.

Functions

This module includes the following functions:

DetectXircomCE2
DriverEntry
Install_Driver


Release Notes for Windows CE SDK Version 2.11

© 1998 Microsoft Corporation

This document contains important information about the Microsoft® Windows® CE SDK Version 2.11.

Contents

Known Issues

Workarounds


Known Issues

Long Device Names for PCMCIA Modems

The dwDeviceName field in the RASENTRY and RASCONNSTATUS structures is limited to 32 characters plus a trailing null character. However, the friendly names of several PCMCIA modems are longer than 32 characters. This could potentially cause problems if a modem was swapped for a different one by the same manufacturer with a similar name.

The WM_GETFONT Message Fails for Some Dialog Boxes

The WM_GETFONT message does not return the font handle used by dialog boxes that are created with one of the following functions:

DialogBox | CreateDialog
DialogBoxParam | CreateDialogParam
DialogBoxIndirectParam | CreateDialogIndirectParam

Remote Access Server (RAS) Callback Functions

After calling the RasDial function, a call is dialed and eventually connects. However, progress notification messages are not received by the window that the lpvNotifier parameter points to.


Workarounds

Determining the Buffer Size for Receiving a Phone Book Entry Using the RasGetEntryProperties Function

The RasGetEntryProperties function fails with a return value of ERROR_BUFFER_TOO_SMALL when the application sets the lpdwDeviceInfoSize and lpbDeviceInfo parameters to NULL to determine the required buffer size. This is the documented behavior.

To determine the required buffer size, call RasGetEntryProperties with lpbDeviceInfo set to NULL and lpdwDeviceInfoSize set to zero. The function returns the required buffer size in lpdwDeviceInfoSize.

The correct required buffer size is returned if lpDeviceInfo points to a big enough buffer. Unimodem currently requires 128 bytes.

Specifying the Default Install Directory of an Application

The device-side default install directory for an application is specified in the Cab Wizard Win32 Setup information (.inf) file. If the path to the default install directory contains more than one subdirectory from an existing directory, then the intermediate subdirectories are stripped out of the install directory.

For example, given the following existing directory and default install directory, Cab Wizard installs an application in the \Program Files\MyApp directory.

Existing directory: | \Program Files
Default install directory: | \Program Files\Microsoft\MyApp
Directory displayed to user: | \Program Files\MyApp

To avoid this problem, do not include intermediate subdirectories, in this case \Microsoft, when specifying the device-side default install directory.


Introduction to the Windows CE Reference

The Windows CE Reference contains documentation for all interfaces, functions, structures, messages, and other application programming interface (API) elements for the following released versions of Windows CE:

  • Windows CE version 1.0
  • Windows CE version 1.01
  • Windows CE version 2.0
  • Windows CE version 2.10
  • Windows CE version 2.11
  • Windows CE version 2.12

Unless otherwise noted, all documented API elements are present in version 2.12.

This document contains Release Notes for Windows CE SDK Version 2.11.

Each reference topic includes a table containing the following information:

At a Glance

Header file: | Header file where the API element is defined.
Component: | Windows CE component that includes this API element.
Platforms: | Targeted platforms.
Windows CE versions: | Windows CE versions that include this API element.

When there is a link to original documentation, comments in the Remarks section are specific to Windows CE.