Contents
Menus and Other Resources
Libloaderapi.h
ENUMRESNAMEPROCA callback function
ENUMRESNAMEPROCW callback function
EnumResourceLanguagesExA function
EnumResourceLanguagesExW function
EnumResourceNamesExA function
EnumResourceNamesExW function
EnumResourceTypesExA function
EnumResourceTypesExW function
ENUMRESTYPEPROCA callback function
ENUMRESTYPEPROCW callback function
FreeResource function
LoadResource function
LockResource function
SizeofResource function
Resourceindexer.h
CreateResourceIndexer function
DestroyIndexedResults function
DestroyResourceIndexer function
IndexedResourceQualifier structure
IndexFilePath function
Strsafe.h
StringCbCatA function
StringCbCatExA function
StringCbCatExW function
StringCbCatNA function
StringCbCatNExA function
StringCbCatNExW function
StringCbCatNW function
StringCbCatW function
StringCbCopyA function
StringCbCopyExA function
StringCbCopyExW function
StringCbCopyNA function
StringCbCopyNExA function
StringCbCopyNExW function
StringCbCopyNW function
StringCbCopyW function
StringCbGetsA function
StringCbGetsExA function
StringCbGetsExW function
StringCbGetsW function
StringCbLengthA function
StringCbLengthW function
StringCbPrintf_lA function
StringCbPrintf_lExA function
StringCbPrintf_lExW function
StringCbPrintf_lW function
StringCbPrintfA function
StringCbPrintfExA function
StringCbPrintfExW function
StringCbPrintfW function
StringCbVPrintf_lA function
StringCbVPrintf_lExA function
StringCbVPrintf_lExW function
StringCbVPrintf_lW function
StringCbVPrintfA function
StringCbVPrintfExA function
StringCbVPrintfExW function
StringCbVPrintfW function
StringCchCatA function
StringCchCatExA function
StringCchCatExW function
StringCchCatNA function
StringCchCatNExA function
StringCchCatNExW function
StringCchCatNW function
StringCchCatW function
StringCchCopyA function
StringCchCopyExA function
StringCchCopyExW function
StringCchCopyNA function
StringCchCopyNExA function
StringCchCopyNExW function
StringCchCopyNW function
StringCchCopyW function
StringCchGetsA function
StringCchGetsExA function
StringCchGetsExW function
StringCchGetsW function
StringCchLengthA function
StringCchLengthW function
StringCchPrintf_lA function
StringCchPrintf_lExA function
StringCchPrintf_lExW function
StringCchPrintf_lW function
StringCchPrintfA function
StringCchPrintfExA function
StringCchPrintfExW function
StringCchPrintfW function
StringCchVPrintf_lA function
StringCchVPrintf_lExA function
StringCchVPrintf_lExW function
StringCchVPrintf_lW function
StringCchVPrintfA function
StringCchVPrintfExA function
StringCchVPrintfExW function
StringCchVPrintfW function
Verrsrc.h
VS_FIXEDFILEINFO structure
Winbase.h
BeginUpdateResourceA function
BeginUpdateResourceW function
EndUpdateResourceA function
EndUpdateResourceW function
EnumResourceLanguagesA function
EnumResourceLanguagesW function
EnumResourceNamesA function
EnumResourceTypesA function
EnumResourceTypesW function
FindResourceA function
FindResourceExA function
lstrcatA function
lstrcatW function
lstrcmpA function
lstrcmpiA function
lstrcmpiW function
lstrcmpW function
lstrcpyA function
lstrcpynA function
lstrcpynW function
lstrcpyW function
lstrlenA function
lstrlenW function
UpdateResourceA function
UpdateResourceW function
Winnt.h
MESSAGE_RESOURCE_BLOCK structure
MESSAGE_RESOURCE_DATA structure
MESSAGE_RESOURCE_ENTRY structure
Winuser.h
ACCEL structure
AppendMenuA function
AppendMenuW function
CharLowerA function
CharLowerBuffA function
CharLowerBuffW function
CharLowerW function
CharNextA function
CharNextExA function
CharNextW function
CharPrevA function
CharPrevExA function
CharPrevW function
CharToOemA function
CharToOemBuffA function
CharToOemBuffW function
CharToOemW function
CharUpperA function
CharUpperBuffA function
CharUpperBuffW function
CharUpperW function
CheckMenuItem function
CheckMenuRadioItem function
ClipCursor function
CopyAcceleratorTableA function
CopyAcceleratorTableW function
CopyCursor macro
CopyIcon function
CopyImage function
CreateAcceleratorTableA function
CreateAcceleratorTableW function
CreateCaret function
CreateCursor function
CreateIcon function
CreateIconFromResource function
CreateIconFromResourceEx function
CreateIconIndirect function
CreateMenu function
CreatePopupMenu function
CURSORINFO structure
CURSORSHAPE structure
DeleteMenu function
DestroyAcceleratorTable function
DestroyCaret function
DestroyCursor function
DestroyIcon function
DestroyMenu function
DrawIcon function
DrawIconEx function
DrawMenuBar function
EnableMenuItem function
EndMenu function
GetCaretBlinkTime function
GetCaretPos function
GetClipCursor function
GetCursor function
GetCursorInfo function
GetCursorPos function
GetIconInfo function
GetIconInfoExA function
GetIconInfoExW function
GetMenu function
GetMenuBarInfo function
GetMenuCheckMarkDimensions function
GetMenuDefaultItem function
GetMenuInfo function
GetMenuItemCount function
GetMenuItemID function
GetMenuItemInfoA function
GetMenuItemInfoW function
GetMenuItemRect function
GetMenuState function
GetMenuStringA function
GetMenuStringW function
GetPhysicalCursorPos function
GetSubMenu function
GetSystemMenu function
HideCaret function
HiliteMenuItem function
ICONINFO structure
ICONINFOEXA structure
ICONINFOEXW structure
ICONMETRICSA structure
ICONMETRICSW structure
InsertMenuA function
InsertMenuItemA function
InsertMenuItemW function
InsertMenuW function
IS_INTRESOURCE macro
IsCharAlphaA function
IsCharAlphaNumericA function
IsCharAlphaNumericW function
IsCharAlphaW function
IsCharLowerA function
IsCharUpperA function
IsCharUpperW function
IsMenu function
LoadAcceleratorsA function
LoadAcceleratorsW function
LoadCursorA function
LoadCursorFromFileA function
LoadCursorFromFileW function
LoadCursorW function
LoadIconA function
LoadIconW function
LoadImageA function
LoadImageW function
LoadMenuA function
LoadMenuIndirectA function
LoadMenuIndirectW function
LoadMenuW function
LoadStringA function
LoadStringW function
LookupIconIdFromDirectory function
LookupIconIdFromDirectoryEx function
MAKEINTRESOURCEA macro
MAKEINTRESOURCEW macro
MDINEXTMENU structure
MENUBARINFO structure
MENUGETOBJECTINFO structure
MENUINFO structure
MenuItemFromPoint function
MENUITEMINFOA structure
MENUITEMINFOW structure
MENUITEMTEMPLATE structure
MENUITEMTEMPLATEHEADER structure
ModifyMenuA function
ModifyMenuW function
OemToCharA function
OemToCharBuffA function
OemToCharBuffW function
OemToCharW function
PrivateExtractIconsA function
PrivateExtractIconsW function
RemoveMenu function
SetCaretBlinkTime function
SetCaretPos function
SetCursor function
SetCursorPos function
SetMenu function
SetMenuDefaultItem function
SetMenuInfo function
SetMenuItemBitmaps function
SetMenuItemInfoA function
SetMenuItemInfoW function
SetPhysicalCursorPos function
SetSystemCursor function
ShowCaret function
ShowCursor function
TPMPARAMS structure
TrackPopupMenu function
TrackPopupMenuEx function
TranslateAcceleratorA function
TranslateAcceleratorW function
wsprintfA function
wsprintfW function
wvsprintfA function
wvsprintfW function
Winver.h
GetFileVersionInfoA function
GetFileVersionInfoExA function
GetFileVersionInfoExW function
GetFileVersionInfoSizeA function
GetFileVersionInfoSizeExA function
GetFileVersionInfoSizeExW function
GetFileVersionInfoSizeW function
GetFileVersionInfoW function
VerFindFileA function
VerFindFileW function
VerInstallFileA function
VerInstallFileW function
VerLanguageNameA function
VerLanguageNameW function
VerQueryValueA function
VerQueryValueW function
Menus and Other Resources
2/7/2020 • 24 minutes to read • Edit Online
Overview of the Menus and Other Resources technology.
To develop Menus and Other Resources, you need these headers:
resourceindexer.h
strsafe.h
verrsrc.h
winver.h
For programming guidance for this technology, see:
Menus and Other Resources
Functions
T IT L E
DESC RIP T IO N
AppendMenuA
Appends a new item to the end of the specified menu bar,
drop-down menu, submenu, or shortcut menu. You can use
this function to specify the content, appearance, and behavior
of the menu item.
AppendMenuW
Appends a new item to the end of the specified menu bar,
drop-down menu, submenu, or shortcut menu. You can use
this function to specify the content, appearance, and behavior
of the menu item.
BeginUpdateResourceA
Retrieves a handle that can be used by the UpdateResource
function to add, delete, or replace resources in a binary
module.
BeginUpdateResourceW
Retrieves a handle that can be used by the UpdateResource
function to add, delete, or replace resources in a binary
module.
CharLowerA
Converts a character string or a single character to lowercase.
If the operand is a character string, the function converts the
characters in place.
CharLowerBuffA
Converts uppercase characters in a buffer to lowercase
characters. The function converts the characters in place.
CharLowerBuffW
Converts uppercase characters in a buffer to lowercase
characters. The function converts the characters in place.
CharLowerW
Converts a character string or a single character to lowercase.
If the operand is a character string, the function converts the
characters in place.
T IT L E
DESC RIP T IO N
CharNextA
Retrieves a pointer to the next character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharNextExA
Retrieves the pointer to the next character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharNextW
Retrieves a pointer to the next character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharPrevA
Retrieves a pointer to the preceding character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharPrevExA
Retrieves the pointer to the preceding character in a string.
This function can handle strings consisting of either single- or
multi-byte characters.
CharPrevW
Retrieves a pointer to the preceding character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharToOemA
Translates a string into the OEM-defined character
set.Warning Do not use.
CharToOemBuffA
Translates a specified number of characters in a string into the
OEM-defined character set.
CharToOemBuffW
Translates a specified number of characters in a string into the
OEM-defined character set.
CharToOemW
Translates a string into the OEM-defined character
set.Warning Do not use.
CharUpperA
Converts a character string or a single character to uppercase.
If the operand is a character string, the function converts the
characters in place.
CharUpperBuffA
Converts lowercase characters in a buffer to uppercase
characters. The function converts the characters in place.
CharUpperBuffW
Converts lowercase characters in a buffer to uppercase
characters. The function converts the characters in place.
CharUpperW
Converts a character string or a single character to uppercase.
If the operand is a character string, the function converts the
characters in place.
CheckMenuItem
Sets the state of the specified menu item's check-mark
attribute to either selected or clear.
T IT L E
DESC RIP T IO N
CheckMenuRadioItem
Checks a specified menu item and makes it a radio item. At
the same time, the function clears all other menu items in the
associated group and clears the radio-item type flag for those
items.
ClipCursor
Confines the cursor to a rectangular area on the screen.
CopyAcceleratorTableA
Copies the specified accelerator table. This function is used to
obtain the accelerator-table data that corresponds to an
accelerator-table handle, or to determine the size of the
accelerator-table data.
CopyAcceleratorTableW
Copies the specified accelerator table. This function is used to
obtain the accelerator-table data that corresponds to an
accelerator-table handle, or to determine the size of the
accelerator-table data.
CopyCursor
Copies the specified cursor.
CopyIcon
Copies the specified icon from another module to the current
module.
CopyImage
Creates a new image (icon, cursor, or bitmap) and copies the
attributes of the specified image to the new one. If necessary,
the function stretches the bits to fit the desired size of the new
image.
CreateAcceleratorTableA
Creates an accelerator table.
CreateAcceleratorTableW
Creates an accelerator table.
CreateCaret
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, a block, or a bitmap.
CreateCursor
Creates a cursor having the specified size, bit patterns, and hot
spot.
CreateIcon
Creates an icon that has the specified size, colors, and bit
patterns.
CreateIconFromResource
Creates an icon or cursor from resource bits describing the
icon.
CreateIconFromResourceEx
Creates an icon or cursor from resource bits describing the
icon.
CreateIconIndirect
Creates an icon or cursor from an ICONINFO structure.
CreateMenu
Creates a menu. The menu is initially empty, but it can be filled
with menu items by using the InsertMenuItem, AppendMenu,
and InsertMenu functions.
CreatePopupMenu
Creates a drop-down menu, submenu, or shortcut menu.
T IT L E
DESC RIP T IO N
CreateResourceIndexer
Creates a new resource indexer for the specified paths of the
root of the project files and the extension DLL.
DeleteMenu
Deletes an item from the specified menu. If the menu item
opens a menu or submenu, this function destroys the handle
to the menu or submenu and frees the memory used by the
menu or submenu.
DestroyAcceleratorTable
Destroys an accelerator table.
DestroyCaret
Destroys the caret's current shape, frees the caret from the
window, and removes the caret from the screen.
DestroyCursor
Destroys a cursor and frees any memory the cursor occupied.
Do not use this function to destroy a shared cursor.
DestroyIcon
Destroys an icon and frees any memory the icon occupied.
DestroyIndexedResults
Frees the parameters that the IndexFilePath method returned.
DestroyMenu
Destroys the specified menu and frees any memory that the
menu occupies.
DestroyResourceIndexer
Frees the computational resources associated with the
specified resource indexer.
DrawIcon
Draws an icon or cursor into the specified device context.
DrawIconEx
Draws an icon or cursor into the specified device context,
performing the specified raster operations, and stretching or
compressing the icon or cursor as specified.
DrawMenuBar
Redraws the menu bar of the specified window. If the menu
bar changes after the system has created the window, this
function must be called to draw the changed menu bar.
EnableMenuItem
Enables, disables, or grays the specified menu item.
EndMenu
Ends the calling thread's active menu.
EndUpdateResourceA
Commits or discards changes made prior to a call to
UpdateResource.
EndUpdateResourceW
Commits or discards changes made prior to a call to
UpdateResource.
ENUMRESNAMEPROCA
An application-defined callback function used with the
EnumResourceNames and EnumResourceNamesEx functions.
ENUMRESNAMEPROCW
An application-defined callback function used with the
EnumResourceNames and EnumResourceNamesEx functions.
T IT L E
DESC RIP T IO N
EnumResourceLanguagesA
Enumerates language-specific resources, of the specified type
and name, associated with a binary module.
EnumResourceLanguagesExA
Enumerates language-specific resources, of the specified type
and name, associated with a specified binary module. Extends
EnumResourceLanguages by allowing more control over the
enumeration.
EnumResourceLanguagesExW
Enumerates language-specific resources, of the specified type
and name, associated with a specified binary module. Extends
EnumResourceLanguages by allowing more control over the
enumeration.
EnumResourceLanguagesW
Enumerates language-specific resources, of the specified type
and name, associated with a binary module.
EnumResourceNamesA
Enumerates resources of a specified type within a binary
module.
EnumResourceNamesExA
Enumerates resources of a specified type that are associated
with a specified binary module. The search can include both an
LN file and its associated .mui files, or it can be limited in
several ways.
EnumResourceNamesExW
Enumerates resources of a specified type that are associated
with a specified binary module. The search can include both an
LN file and its associated .mui files, or it can be limited in
several ways.
EnumResourceTypesA
Enumerates resource types within a binary module.
EnumResourceTypesExA
Enumerates resource types associated with a specified binary
module.
EnumResourceTypesExW
Enumerates resource types associated with a specified binary
module.
EnumResourceTypesW
Enumerates resource types within a binary module.
ENUMRESTYPEPROCA
An application-defined callback function used with the
EnumResourceTypes and EnumResourceTypesEx functions.
ENUMRESTYPEPROCW
An application-defined callback function used with the
EnumResourceTypes and EnumResourceTypesEx functions.
FindResourceA
Determines the location of a resource with the specified type
and name in the specified module.
FindResourceExA
Determines the location of the resource with the specified
type, name, and language in the specified module.
FreeResource
Decrements (decreases by one) the reference count of a
loaded resource. When the reference count reaches zero, the
memory occupied by the resource is freed.
T IT L E
DESC RIP T IO N
GetCaretBlinkTime
Retrieves the time required to invert the caret's pixels. The user
can set this value.
GetCaretPos
Copies the caret's position to the specified POINT structure.
GetClipCursor
Retrieves the screen coordinates of the rectangular area to
which the cursor is confined.
GetCursor
Retrieves a handle to the current cursor.
GetCursorInfo
Retrieves information about the global cursor.
GetCursorPos
Retrieves the position of the mouse cursor, in screen
coordinates.
GetFileVersionInfoA
Retrieves version information for the specified file.
GetFileVersionInfoExA
Retrieves version information for the specified file.
GetFileVersionInfoExW
Retrieves version information for the specified file.
GetFileVersionInfoSizeA
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSize returns the size, in bytes, of
that information.
GetFileVersionInfoSizeExA
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSizeEx returns the size, in bytes, of
that information.
GetFileVersionInfoSizeExW
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSizeEx returns the size, in bytes, of
that information.
GetFileVersionInfoSizeW
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSize returns the size, in bytes, of
that information.
GetFileVersionInfoW
Retrieves version information for the specified file.
GetIconInfo
Retrieves information about the specified icon or cursor.
GetIconInfoExA
Retrieves information about the specified icon or cursor.
GetIconInfoEx extends GetIconInfo by using the newer
ICONINFOEX structure.
GetIconInfoExW
Retrieves information about the specified icon or cursor.
GetIconInfoEx extends GetIconInfo by using the newer
ICONINFOEX structure.
T IT L E
DESC RIP T IO N
GetMenu
Retrieves a handle to the menu assigned to the specified
window.
GetMenuBarInfo
Retrieves information about the specified menu bar.
GetMenuCheckMarkDimensions
Retrieves the dimensions of the default check-mark bitmap.
GetMenuDefaultItem
Determines the default menu item on the specified menu.
GetMenuInfo
Retrieves information about a specified menu.
GetMenuItemCount
Determines the number of items in the specified menu.
GetMenuItemID
Retrieves the menu item identifier of a menu item located at
the specified position in a menu.
GetMenuItemInfoA
Retrieves information about a menu item.
GetMenuItemInfoW
Retrieves information about a menu item.
GetMenuItemRect
Retrieves the bounding rectangle for the specified menu item.
GetMenuState
Retrieves the menu flags associated with the specified menu
item.
GetMenuStringA
Copies the text string of the specified menu item into the
specified buffer.
GetMenuStringW
Copies the text string of the specified menu item into the
specified buffer.
GetPhysicalCursorPos
Retrieves the position of the cursor in physical coordinates.
GetSubMenu
Retrieves a handle to the drop-down menu or submenu
activated by the specified menu item.
GetSystemMenu
Enables the application to access the window menu (also
known as the system menu or the control menu) for copying
and modifying.
HideCaret
Removes the caret from the screen. Hiding a caret does not
destroy its current shape or invalidate the insertion point.
HiliteMenuItem
Adds or removes highlighting from an item in a menu bar.
IndexFilePath
Indexes a file path for file and folder naming conventions.
InsertMenuA
Inserts a new menu item into a menu, moving other items
down the menu.
InsertMenuItemA
Inserts a new menu item at the specified position in a menu.
T IT L E
DESC RIP T IO N
InsertMenuItemW
Inserts a new menu item at the specified position in a menu.
InsertMenuW
Inserts a new menu item into a menu, moving other items
down the menu.
IS_INTRESOURCE
Determines whether a value is an integer identifier for a
resource.
IsCharAlphaA
Determines whether a character is an alphabetical character.
This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharAlphaNumericA
Determines whether a character is either an alphabetical or a
numeric character. This determination is based on the
semantics of the language selected by the user during setup
or through Control Panel.
IsCharAlphaNumericW
Determines whether a character is either an alphabetical or a
numeric character. This determination is based on the
semantics of the language selected by the user during setup
or through Control Panel.
IsCharAlphaW
Determines whether a character is an alphabetical character.
This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharLowerA
Determines whether a character is lowercase. This
determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharUpperA
Determines whether a character is uppercase. This
determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharUpperW
Determines whether a character is uppercase. This
determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsMenu
Determines whether a handle is a menu handle.
LoadAcceleratorsA
Loads the specified accelerator table.
LoadAcceleratorsW
Loads the specified accelerator table.
LoadCursorA
Loads the specified cursor resource from the executable (.EXE)
file associated with an application instance.
LoadCursorFromFileA
Creates a cursor based on data contained in a file.
LoadCursorFromFileW
Creates a cursor based on data contained in a file.
LoadCursorW
Loads the specified cursor resource from the executable (.EXE)
file associated with an application instance.
T IT L E
DESC RIP T IO N
LoadIconA
Loads the specified icon resource from the executable (.exe) file
associated with an application instance.
LoadIconW
Loads the specified icon resource from the executable (.exe) file
associated with an application instance.
LoadImageA
Loads an icon, cursor, animated cursor, or bitmap.
LoadImageW
Loads an icon, cursor, animated cursor, or bitmap.
LoadMenuA
Loads the specified menu resource from the executable (.exe)
file associated with an application instance.
LoadMenuIndirectA
Loads the specified menu template in memory.
LoadMenuIndirectW
Loads the specified menu template in memory.
LoadMenuW
Loads the specified menu resource from the executable (.exe)
file associated with an application instance.
LoadResource
Retrieves a handle that can be used to obtain a pointer to the
first byte of the specified resource in memory.
LoadStringA
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.
LoadStringW
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.
LockResource
Retrieves a pointer to the specified resource in memory.
LookupIconIdFromDirectory
Searches through icon or cursor data for the icon or cursor
that best fits the current display device.
LookupIconIdFromDirectoryEx
Searches through icon or cursor data for the icon or cursor
that best fits the current display device.
lstrcatA
Appends one string to another.Warning Do not use.
lstrcatW
Appends one string to another.Warning Do not use.
lstrcmpA
Compares two character strings. The comparison is casesensitive.
lstrcmpiA
Compares two character strings. The comparison is not casesensitive.
lstrcmpiW
Compares two character strings. The comparison is not casesensitive.
T IT L E
DESC RIP T IO N
lstrcmpW
Compares two character strings. The comparison is casesensitive.
lstrcpyA
Copies a string to a buffer.
lstrcpynA
Copies a specified number of characters from a source string
into a buffer.Warning Do not use.
lstrcpynW
Copies a specified number of characters from a source string
into a buffer.Warning Do not use.
lstrcpyW
Copies a string to a buffer.
lstrlenA
Determines the length of the specified string (not including
the terminating null character).
lstrlenW
Determines the length of the specified string (not including
the terminating null character).
MAKEINTRESOURCEA
Converts an integer value to a resource type compatible with
the resource-management functions. This macro is used in
place of a string containing the name of the resource.
MAKEINTRESOURCEW
Converts an integer value to a resource type compatible with
the resource-management functions. This macro is used in
place of a string containing the name of the resource.
MenuItemFromPoint
Determines which menu item, if any, is at the specified
location.
ModifyMenuA
Changes an existing menu item.
ModifyMenuW
Changes an existing menu item.
OemToCharA
Translates a string from the OEM-defined character set into
either an ANSI or a wide-character string.Warning Do not use.
OemToCharBuffA
Translates a specified number of characters in a string from the
OEM-defined character set into either an ANSI or a widecharacter string.
OemToCharBuffW
Translates a specified number of characters in a string from the
OEM-defined character set into either an ANSI or a widecharacter string.
OemToCharW
Translates a string from the OEM-defined character set into
either an ANSI or a wide-character string.Warning Do not use.
PrivateExtractIconsA
Creates an array of handles to icons that are extracted from a
specified file.
PrivateExtractIconsW
Creates an array of handles to icons that are extracted from a
specified file.
T IT L E
DESC RIP T IO N
RemoveMenu
Deletes a menu item or detaches a submenu from the
specified menu.
SetCaretBlinkTime
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.
SetCaretPos
Moves the caret to the specified coordinates. If the window
that owns the caret was created with the CS_OWNDC class
style, then the specified coordinates are subject to the
mapping mode of the device context associated with that
window.
SetCursor
Sets the cursor shape.
SetCursorPos
Moves the cursor to the specified screen coordinates.
SetMenu
Assigns a new menu to the specified window.
SetMenuDefaultItem
Sets the default menu item for the specified menu.
SetMenuInfo
Sets information for a specified menu.
SetMenuItemBitmaps
Associates the specified bitmap with a menu item. Whether
the menu item is selected or clear, the system displays the
appropriate bitmap next to the menu item.
SetMenuItemInfoA
Changes information about a menu item.
SetMenuItemInfoW
Changes information about a menu item.
SetPhysicalCursorPos
Sets the position of the cursor in physical coordinates.
SetSystemCursor
Enables an application to customize the system cursors. It
replaces the contents of the system cursor specified by the id
parameter with the contents of the cursor specified by the
hcur parameter and then destroys hcur.
ShowCaret
Makes the caret visible on the screen at the caret's current
position. When the caret becomes visible, it begins flashing
automatically.
ShowCursor
Displays or hides the cursor.
SizeofResource
Retrieves the size, in bytes, of the specified resource.
StringCbCatA
Concatenates one string to another string.
StringCbCatExA
Concatenates one string to another string.
StringCbCatExW
Concatenates one string to another string.
T IT L E
DESC RIP T IO N
StringCbCatNA
Concatenates the specified number of bytes from one string
to another string.
StringCbCatNExA
Concatenates the specified number of bytes from one string
to another string.
StringCbCatNExW
Concatenates the specified number of bytes from one string
to another string.
StringCbCatNW
Concatenates the specified number of bytes from one string
to another string.
StringCbCatW
Concatenates one string to another string.
StringCbCopyA
Copies one string to another.
StringCbCopyExA
Copies one string to another.
StringCbCopyExW
Copies one string to another.
StringCbCopyNA
Copies the specified number of bytes from one string to
another.
StringCbCopyNExA
Copies the specified number of bytes from one string to
another.
StringCbCopyNExW
Copies the specified number of bytes from one string to
another.
StringCbCopyNW
Copies the specified number of bytes from one string to
another.
StringCbCopyW
Copies one string to another.
StringCbGetsA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbGetsExA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbGetsExW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbGetsW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbLengthA
Determines whether a string exceeds the specified length, in
bytes.
StringCbLengthW
Determines whether a string exceeds the specified length, in
bytes.
T IT L E
DESC RIP T IO N
StringCbPrintf_lA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintf_lExA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintf_lExW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintf_lW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintfA
Writes formatted data to the specified string.
StringCbPrintfExA
Writes formatted data to the specified string.
StringCbPrintfExW
Writes formatted data to the specified string.
StringCbPrintfW
Writes formatted data to the specified string.
StringCbVPrintf_lA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintf_lExA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintf_lExW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintf_lW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintfA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCbVPrintfExA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCbVPrintfExW
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCbVPrintfW
Writes formatted data to the specified string using a pointer
to a list of arguments.
T IT L E
DESC RIP T IO N
StringCchCatA
Concatenates one string to another string.
StringCchCatExA
Concatenates one string to another string.
StringCchCatExW
Concatenates one string to another string.
StringCchCatNA
Concatenates the specified number of characters from one
string to another string.
StringCchCatNExA
Concatenates the specified number of characters from one
string to another string.
StringCchCatNExW
Concatenates the specified number of characters from one
string to another string.
StringCchCatNW
Concatenates the specified number of characters from one
string to another string.
StringCchCatW
Concatenates one string to another string.
StringCchCopyA
Copies one string to another.
StringCchCopyExA
Copies one string to another.
StringCchCopyExW
Copies one string to another.
StringCchCopyNA
Copies the specified number of characters from one string to
another.
StringCchCopyNExA
Copies the specified number of characters from one string to
another.
StringCchCopyNExW
Copies the specified number of characters from one string to
another.
StringCchCopyNW
Copies the specified number of characters from one string to
another.
StringCchCopyW
Copies one string to another.
StringCchGetsA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchGetsExA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchGetsExW
Gets one line of text from stdin, up to and including the
newline character ('\n').
T IT L E
DESC RIP T IO N
StringCchGetsW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchLengthA
Determines whether a string exceeds the specified length, in
characters.
StringCchLengthW
Determines whether a string exceeds the specified length, in
characters.
StringCchPrintf_lA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintf_lExA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintf_lExW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintf_lW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintfA
Writes formatted data to the specified string.
StringCchPrintfExA
Writes formatted data to the specified string.
StringCchPrintfExW
Writes formatted data to the specified string.
StringCchPrintfW
Writes formatted data to the specified string.
StringCchVPrintf_lA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintf_lExA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintf_lExW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintf_lW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintfA
Writes formatted data to the specified string using a pointer
to a list of arguments.
T IT L E
DESC RIP T IO N
StringCchVPrintfExA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCchVPrintfExW
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCchVPrintfW
Writes formatted data to the specified string using a pointer
to a list of arguments.
TrackPopupMenu
Displays a shortcut menu at the specified location and tracks
the selection of items on the menu. The shortcut menu can
appear anywhere on the screen.
TrackPopupMenuEx
Displays a shortcut menu at the specified location and tracks
the selection of items on the shortcut menu. The shortcut
menu can appear anywhere on the screen.
TranslateAcceleratorA
Processes accelerator keys for menu commands.
TranslateAcceleratorW
Processes accelerator keys for menu commands.
UpdateResourceA
Adds, deletes, or replaces a resource in a portable executable
(PE) file.
UpdateResourceW
Adds, deletes, or replaces a resource in a portable executable
(PE) file.
VerFindFileA
Determines where to install a file based on whether it locates
another version of the file in the system. The values
VerFindFile returns in the specified buffers are used in a
subsequent call to the VerInstallFile function.
VerFindFileW
Determines where to install a file based on whether it locates
another version of the file in the system. The values
VerFindFile returns in the specified buffers are used in a
subsequent call to the VerInstallFile function.
VerInstallFileA
Installs the specified file based on information returned from
the VerFindFile function. VerInstallFile decompresses the file, if
necessary, assigns a unique filename, and checks for errors,
such as outdated files.
VerInstallFileW
Installs the specified file based on information returned from
the VerFindFile function. VerInstallFile decompresses the file, if
necessary, assigns a unique filename, and checks for errors,
such as outdated files.
VerLanguageNameA
Retrieves a description string for the language associated with
a specified binary Microsoft language identifier.
VerLanguageNameW
Retrieves a description string for the language associated with
a specified binary Microsoft language identifier.
T IT L E
DESC RIP T IO N
VerQueryValueA
Retrieves specified version information from the specified
version-information resource.
VerQueryValueW
Retrieves specified version information from the specified
version-information resource.
wsprintfA
Writes formatted data to the specified buffer.
wsprintfW
Writes formatted data to the specified buffer.
wvsprintfA
Writes formatted data to the specified buffer using a pointer
to a list of arguments.
wvsprintfW
Writes formatted data to the specified buffer using a pointer
to a list of arguments.
Structures
T IT L E
DESC RIP T IO N
ACCEL
Defines an accelerator key used in an accelerator table.
CURSORINFO
Contains global cursor information.
CURSORSHAPE
Contains information about a cursor.
ICONINFO
Contains information about an icon or a cursor.
ICONINFOEXA
Contains information about an icon or a cursor. Extends
ICONINFO. Used by GetIconInfoEx.
ICONINFOEXW
Contains information about an icon or a cursor. Extends
ICONINFO. Used by GetIconInfoEx.
ICONMETRICSA
Contains the scalable metrics associated with icons. This
structure is used with the SystemParametersInfo function
when the SPI_GETICONMETRICS or SPI_SETICONMETRICS
action is specified.
ICONMETRICSW
Contains the scalable metrics associated with icons. This
structure is used with the SystemParametersInfo function
when the SPI_GETICONMETRICS or SPI_SETICONMETRICS
action is specified.
IndexedResourceQualifier
Represents the context under which a resource is appropriate.
MDINEXTMENU
Contains information about the menu to be activated.
MENUBARINFO
Contains menu bar information.
T IT L E
DESC RIP T IO N
MENUGETOBJECTINFO
Contains information about the menu that the mouse cursor
is on.
MENUINFO
Contains information about a menu.
MENUITEMINFOA
Contains information about a menu item.
MENUITEMINFOW
Contains information about a menu item.
MENUITEMTEMPLATE
Defines a menu item in a menu template.
MENUITEMTEMPLATEHEADER
Defines the header for a menu template. A complete menu
template consists of a header and one or more menu item
lists.
MESSAGE_RESOURCE_BLOCK
Contains information about message strings with identifiers in
the range indicated by the LowId and HighId members.
MESSAGE_RESOURCE_DATA
Contains information about formatted text for display as an
error message or in a message box in a message table
resource.
MESSAGE_RESOURCE_ENTRY
Contains the error message or message box display text for a
message table resource.
TPMPARAMS
Contains extended parameters for the TrackPopupMenuEx
function.
VS_FIXEDFILEINFO
Contains version information for a file. This information is
language and code page independent.
minutes to read • Edit Online
This header is used by System Services. For more information, see:
System Services libloaderapi.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
AddDllDirectory
Adds a directory to the process DLL search path.
DisableThreadLibraryCalls
Disables the DLL_THREAD_ATTACH and DLL_THREAD_DETACH
notifications for the specified dynamic-link library (DLL).
EnumResourceLanguagesExA
Enumerates language-specific resources, of the specified type
and name, associated with a specified binary module. Extends
EnumResourceLanguages by allowing more control over the
enumeration.
EnumResourceLanguagesExW
Enumerates language-specific resources, of the specified type
and name, associated with a specified binary module. Extends
EnumResourceLanguages by allowing more control over the
enumeration.
EnumResourceNamesExA
Enumerates resources of a specified type that are associated
with a specified binary module. The search can include both an
LN file and its associated .mui files, or it can be limited in
several ways.
EnumResourceNamesExW
Enumerates resources of a specified type that are associated
with a specified binary module. The search can include both an
LN file and its associated .mui files, or it can be limited in
several ways.
EnumResourceTypesExA
Enumerates resource types associated with a specified binary
module.
EnumResourceTypesExW
Enumerates resource types associated with a specified binary
module.
FindStringOrdinal
Locates a Unicode string (wide characters) in another Unicode
string for a non-linguistic comparison.
FreeLibrary
Frees the loaded dynamic-link library (DLL) module and, if
necessary, decrements its reference count.
FreeLibraryAndExitThread
Decrements the reference count of a loaded dynamic-link
library (DLL) by one, then calls ExitThread to terminate the
calling thread.
T IT L E
DESC RIP T IO N
FreeResource
Decrements (decreases by one) the reference count of a
loaded resource. When the reference count reaches zero, the
memory occupied by the resource is freed.
GetModuleFileNameA
Retrieves the fully qualified path for the file that contains the
specified module. The module must have been loaded by the
current process.
GetModuleFileNameW
Retrieves the fully qualified path for the file that contains the
specified module. The module must have been loaded by the
current process.
GetModuleHandleA
Retrieves a module handle for the specified module. The
module must have been loaded by the calling process.
GetModuleHandleExA
Retrieves a module handle for the specified module and
increments the module's reference count unless
GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT
is specified. The module must have been loaded by the calling
process.
GetModuleHandleExW
Retrieves a module handle for the specified module and
increments the module's reference count unless
GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT
is specified. The module must have been loaded by the calling
process.
GetModuleHandleW
Retrieves a module handle for the specified module. The
module must have been loaded by the calling process.
GetProcAddress
Retrieves the address of an exported function or variable from
the specified dynamic-link library (DLL).
LoadLibraryA
Loads the specified module into the address space of the
calling process.
LoadLibraryExA
Loads the specified module into the address space of the
calling process.
LoadLibraryExW
Loads the specified module into the address space of the
calling process.
LoadLibraryW
Loads the specified module into the address space of the
calling process.
LoadResource
Retrieves a handle that can be used to obtain a pointer to the
first byte of the specified resource in memory.
LockResource
Retrieves a pointer to the specified resource in memory.
RemoveDllDirectory
Removes a directory that was added to the process DLL
search path by using AddDllDirectory.
T IT L E
DESC RIP T IO N
SetDefaultDllDirectories
Specifies a default set of directories to search when the calling
process loads a DLL. This search path is used when
LoadLibraryEx is called with no LOAD_LIBRARY_SEARCH flags.
SizeofResource
Retrieves the size, in bytes, of the specified resource.
Callback functions
T IT L E
DESC RIP T IO N
ENUMRESNAMEPROCA
An application-defined callback function used with the
EnumResourceNames and EnumResourceNamesEx functions.
ENUMRESNAMEPROCW
An application-defined callback function used with the
EnumResourceNames and EnumResourceNamesEx functions.
ENUMRESTYPEPROCA
An application-defined callback function used with the
EnumResourceTypes and EnumResourceTypesEx functions.
ENUMRESTYPEPROCW
An application-defined callback function used with the
EnumResourceTypes and EnumResourceTypesEx functions.
minutes to read • Edit Online
An application-defined callback function used with the EnumResourceNames and EnumResourceNamesEx
functions. It receives the type and name of a resource. The ENUMRESNAMEPROC type defines a pointer to this
callback function. EnumResNameProc is a placeholder for the application-defined function name.
Syntax
ENUMRESNAMEPROCA Enumresnameproca;
BOOL Enumresnameproca(
HMODULE hModule,
LPCSTR lpType,
LPSTR lpName,
LONG_PTR lParam
)
{...}
Parameters
hModule
Type: HMODULE
A handle to the module whose executable file contains the resources that are being enumerated. If this parameter is
NULL , the function enumerates the resource names in the module used to create the current process.
lpType
lpName
lParam
Type: LONG_PTR
An application-defined parameter passed to the EnumResourceNames or EnumResourceNamesEx function. This
parameter can be used in error checking.
Return value
Type: BOOL
Returns TRUE to continue enumeration or FALSE to stop enumeration.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the integer identifier of the resource type. For
example, the string "#258" represents the identifier 258.
Similarly, if IS_INTRESOURCE(lpszName) is TRUE , then lpszName specifies the integer identifier of the given
resource. Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#),
then the remaining characters represent a decimal number that specifies the integer identifier of the resource.
An application must register this function by passing its address to the EnumResourceNames or
EnumResourceNamesEx function.
If the callback function returns FALSE , then EnumResourceNames or EnumResourceNamesEx will stop
enumeration and return FALSE . On Windows XP and earlier the value obtained from GetLastError will be
ERROR_SUCCESS ; starting with Windows Vista, the last error value will be
ERROR_RESOURCE_ENUM_USER_STOP .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
See also
Conceptual
EnumResourceNames
EnumResourceNamesEx
IS_INTRESOURCE
Reference
Resources
minutes to read • Edit Online
An application-defined callback function used with the EnumResourceNames and EnumResourceNamesEx
functions. It receives the type and name of a resource. The ENUMRESNAMEPROC type defines a pointer to this
callback function. EnumResNameProc is a placeholder for the application-defined function name.
Syntax
ENUMRESNAMEPROCW Enumresnameprocw;
BOOL Enumresnameprocw(
HMODULE hModule,
LPCWSTR lpType,
LPWSTR lpName,
LONG_PTR lParam
)
{...}
Parameters
hModule
Type: HMODULE
A handle to the module whose executable file contains the resources that are being enumerated. If this parameter is
NULL , the function enumerates the resource names in the module used to create the current process.
lpType
lpName
lParam
Type: LONG_PTR
An application-defined parameter passed to the EnumResourceNames or EnumResourceNamesEx function. This
parameter can be used in error checking.
Return value
Type: BOOL
Returns TRUE to continue enumeration or FALSE to stop enumeration.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the integer identifier of the resource type. For
example, the string "#258" represents the identifier 258.
Similarly, if IS_INTRESOURCE(lpszName) is TRUE , then lpszName specifies the integer identifier of the given
resource. Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#),
then the remaining characters represent a decimal number that specifies the integer identifier of the resource.
An application must register this function by passing its address to the EnumResourceNames or
EnumResourceNamesEx function.
If the callback function returns FALSE , then EnumResourceNames or EnumResourceNamesEx will stop
enumeration and return FALSE . On Windows XP and earlier the value obtained from GetLastError will be
ERROR_SUCCESS ; starting with Windows Vista, the last error value will be
ERROR_RESOURCE_ENUM_USER_STOP .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
See also
Conceptual
EnumResourceNames
EnumResourceNamesEx
IS_INTRESOURCE
Reference
Resources
minutes to read • Edit Online
Enumerates language-specific resources, of the specified type and name, associated with a specified binary module.
Extends EnumResourceLanguages by allowing more control over the enumeration.
Syntax
BOOL EnumResourceLanguagesExA(
HMODULE
hModule,
LPCSTR
lpType,
LPCSTR
lpName,
ENUMRESLANGPROCA lpEnumFunc,
LONG_PTR
lParam,
DWORD
dwFlags,
LANGID
LangId
);
Parameters
hModule
Type: HMODULE
The handle to a module to search. Typically this is a language-neutral Portable Executable (LN file), and if flag
RESOURCE_ENUM_MUI is set, then appropriate .mui files are included in the search. Alternately, this can be a
handle to an .mui file or other LN file. If this is a specific .mui file, only that file is searched for resources.
If this parameter is NULL , it is equivalent to passing in a handle to the module used to create the current process.
lpType
Type: LPCTSTR
The type of the resource for which the language is being enumerated. Alternately, rather than a pointer, this
parameter can be MAKEINTRESOURCE(ID), where ID is an integer value representing a predefined resource type.
For a list of predefined resource types, see Resource Types. For more
information, see the Remarks section below.
lpName
Type: LPCTSTR
The name of the resource for which the language is being enumerated. Alternately, rather than a pointer, this
parameter can be MAKEINTRESOURCE(ID), where ID is the integer identifier of the resource. For more information,
see the Remarks section below.
lpEnumFunc
Type: ENUMRESL ANGPROC
A pointer to the callback function to be called for each enumerated resource language. For more information, see
EnumResLangProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
dwFlags
Type: DWORD
The type of file to be searched. The following values are supported. Note that if dwFlags is zero, then the
RESOURCE_ENUM_LN and RESOURCE_ENUM_MUI flags are assumed to be specified.
VA L UE
RES
OU
RCE
_EN
UM
_M
UI
0x0
002
RES
OU
RCE
_EN
UM
_LN
0x0
001
RES
OU
RCE
_EN
UM
_M
UI_
SYS
TE
M
0x0
004
RES
OU
RCE
_EN
UM
_VA
LID
ATE
0x0
008
LangId
M EA N IN G
Search for language-specific resources in .mui files associated
with the LN file specified by hModule. Alternately, if LangId is
nonzero, the only .mui file searched will be the one matching
the specified LangId. Typically this flag should be used only if
hModule references an LN file. If hModule references an .mui
file, then that file is actually covered by the RESOURCE_LN
flag, despite the name of the flag. See the Remarks section
below for sequence of search.
Searches the file specified by hModule, regardless of whether
the file is an LN file, another type of LN file, or an .mui file.
Restricts the .mui files search to system-installed MUI
languages.
Performs extra validation on the resource section and its
reference in the PE header while doing the enumeration to
ensure that resources are properly formatted.
Type: L ANGID
The localization language used to filter the search in the .mui file. This parameter is used only when the
RESOURCE_ENUM_MUI flag is set in dwFlags. If zero is specified, then all .mui files are included in the search. If a
nonzero LangId is specified, then the only .mui file searched will be the one matching the specified LangId.
Return value
Type: BOOL
Returns TRUE if the function succeeds or FALSE if the function does not find a resource of the type specified, or if
the function fails for another reason. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpType) is TRUE , then lpType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
Similarly, if IS_INTRESOURCE(lpName) is TRUE , then lpName specifies the integer identifier of the given resource.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource.
Starting with Windows Vista, the binary module is typically an LN file, and the enumeration will also include
resources from the corresponding language-specific resource files (.mui files) that contain localizable language
resources.
For each such resource found, EnumResourceLanguagesEx calls an application-defined callback function
lpEnumFunc, passing to the callback function the language identifier (see Language Identifiers) of the language for
which a resource was found (as well as the various other parameters that were passed to
EnumResourceLanguagesEx ).
The search can include both an LN file and its associated .mui files, or it can be limited either to a single binary
module of any type, or to the .mui files associated with a single LN file. Also, by specifying an LN file for the
hModule parameter and a nonzero LangId parameter, the search can be limited to the unique .mui file associated
with that LN file and language.
The EnumResourceLanguagesEx function continues to enumerate resource languages until the callback function
returns FALSE or all resource languages have been enumerated.
If hModule specifies an LN file, and both flags are selected, the languages enumerated include all languages whose
resources reside either in the LN file or in any .mui files associated with it. If no .mui files are found, only languages
from the LN file are returned.
If dwFlags contains RESOURCE_ENUM_MUI or NULL and LangId is 0, then the enumeration first includes the
languages associated with all system-installed .mui files, using languages retrieved from EnumUILanguages..
Finally, if the RESOURCE_ENUM_LN flag is also set, the file designated by hModule is also searched.
If the LangId is nonzero, then only the .mui file corresponding to that language identifier will be searched. Language
fallbacks will not be used. If an .mui file for that language does not exist, the enumeration will be empty (unless
resources for that language exist in the LN file, and the flag is set to search the LN file as well).
The enumeration never includes duplicates: if resources for a particular language are contained in both the LN file
and in an .mui file, the type will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResLangProc
EnumResourceNamesEx
EnumResourceTypesEx
MAKEINTRESOURCE
Reference
Resources
minutes to read • Edit Online
Enumerates language-specific resources, of the specified type and name, associated with a specified binary module.
Extends EnumResourceLanguages by allowing more control over the enumeration.
Syntax
BOOL EnumResourceLanguagesExW(
HMODULE
hModule,
LPCWSTR
lpType,
LPCWSTR
lpName,
ENUMRESLANGPROCW lpEnumFunc,
LONG_PTR
lParam,
DWORD
dwFlags,
LANGID
LangId
);
Parameters
hModule
Type: HMODULE
The handle to a module to search. Typically this is a language-neutral Portable Executable (LN file), and if flag
RESOURCE_ENUM_MUI is set, then appropriate .mui files are included in the search. Alternately, this can be a
handle to an .mui file or other LN file. If this is a specific .mui file, only that file is searched for resources.
If this parameter is NULL , it is equivalent to passing in a handle to the module used to create the current process.
lpType
Type: LPCTSTR
The type of the resource for which the language is being enumerated. Alternately, rather than a pointer, this
parameter can be MAKEINTRESOURCE(ID), where ID is an integer value representing a predefined resource type.
For a list of predefined resource types, see Resource Types. For more
information, see the Remarks section below.
lpName
Type: LPCTSTR
The name of the resource for which the language is being enumerated. Alternately, rather than a pointer, this
parameter can be MAKEINTRESOURCE(ID), where ID is the integer identifier of the resource. For more information,
see the Remarks section below.
lpEnumFunc
Type: ENUMRESL ANGPROC
A pointer to the callback function to be called for each enumerated resource language. For more information, see
EnumResLangProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
dwFlags
Type: DWORD
The type of file to be searched. The following values are supported. Note that if dwFlags is zero, then the
RESOURCE_ENUM_LN and RESOURCE_ENUM_MUI flags are assumed to be specified.
VA L UE
RES
OU
RCE
_EN
UM
_M
UI
0x0
002
RES
OU
RCE
_EN
UM
_LN
0x0
001
RES
OU
RCE
_EN
UM
_M
UI_
SYS
TE
M
0x0
004
RES
OU
RCE
_EN
UM
_VA
LID
ATE
0x0
008
LangId
M EA N IN G
Search for language-specific resources in .mui files associated
with the LN file specified by hModule. Alternately, if LangId is
nonzero, the only .mui file searched will be the one matching
the specified LangId. Typically this flag should be used only if
hModule references an LN file. If hModule references an .mui
file, then that file is actually covered by the RESOURCE_LN
flag, despite the name of the flag. See the Remarks section
below for sequence of search.
Searches the file specified by hModule, regardless of whether
the file is an LN file, another type of LN file, or an .mui file.
Restricts the .mui files search to system-installed MUI
languages.
Performs extra validation on the resource section and its
reference in the PE header while doing the enumeration to
ensure that resources are properly formatted.
Type: L ANGID
The localization language used to filter the search in the .mui file. This parameter is used only when the
RESOURCE_ENUM_MUI flag is set in dwFlags. If zero is specified, then all .mui files are included in the search. If a
nonzero LangId is specified, then the only .mui file searched will be the one matching the specified LangId.
Return value
Type: BOOL
Returns TRUE if the function succeeds or FALSE if the function does not find a resource of the type specified, or if
the function fails for another reason. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpType) is TRUE , then lpType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
Similarly, if IS_INTRESOURCE(lpName) is TRUE , then lpName specifies the integer identifier of the given resource.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource.
Starting with Windows Vista, the binary module is typically an LN file, and the enumeration will also include
resources from the corresponding language-specific resource files (.mui files) that contain localizable language
resources.
For each such resource found, EnumResourceLanguagesEx calls an application-defined callback function
lpEnumFunc, passing to the callback function the language identifier (see Language Identifiers) of the language for
which a resource was found (as well as the various other parameters that were passed to
EnumResourceLanguagesEx ).
The search can include both an LN file and its associated .mui files, or it can be limited either to a single binary
module of any type, or to the .mui files associated with a single LN file. Also, by specifying an LN file for the
hModule parameter and a nonzero LangId parameter, the search can be limited to the unique .mui file associated
with that LN file and language.
The EnumResourceLanguagesEx function continues to enumerate resource languages until the callback function
returns FALSE or all resource languages have been enumerated.
If hModule specifies an LN file, and both flags are selected, the languages enumerated include all languages whose
resources reside either in the LN file or in any .mui files associated with it. If no .mui files are found, only languages
from the LN file are returned.
If dwFlags contains RESOURCE_ENUM_MUI or NULL and LangId is 0, then the enumeration first includes the
languages associated with all system-installed .mui files, using languages retrieved from EnumUILanguages..
Finally, if the RESOURCE_ENUM_LN flag is also set, the file designated by hModule is also searched.
If the LangId is nonzero, then only the .mui file corresponding to that language identifier will be searched. Language
fallbacks will not be used. If an .mui file for that language does not exist, the enumeration will be empty (unless
resources for that language exist in the LN file, and the flag is set to search the LN file as well).
The enumeration never includes duplicates: if resources for a particular language are contained in both the LN file
and in an .mui file, the type will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResLangProc
EnumResourceNamesEx
EnumResourceTypesEx
MAKEINTRESOURCE
Reference
Resources
minutes to read • Edit Online
Enumerates resources of a specified type that are associated with a specified binary module. The search can include
both an LN file and its associated .mui files, or it can be limited in several ways.
Syntax
BOOL EnumResourceNamesExA(
HMODULE
hModule,
LPCSTR
lpType,
ENUMRESNAMEPROCA lpEnumFunc,
LONG_PTR
lParam,
DWORD
dwFlags,
LANGID
LangId
);
Parameters
hModule
Type: HMODULE
The handle to a module to search. Typically this is an LN file, and if flag RESOURCE_ENUM_MUI is set, then
appropriate .mui files are included in the search. Alternately, this can be a handle to an .mui file or other LN file.
If this parameter is NULL , it is equivalent to passing in a handle to the module used to create the current process.
lpType
TBD
lpEnumFunc
Type: ENUMRESNAMEPROC
A pointer to the callback function to be called for each enumerated resource name. For more information, see
EnumResNameProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
dwFlags
Type: DWORD
The type of file to search. The following values are supported. Note that if dwFlags is zero, then the
RESOURCE_ENUM_LN and RESOURCE_ENUM_MUI flags are assumed to be specified.
VA L UE
M EA N IN G
RES
OU
RCE
_EN
UM
_M
UI
0x0
002
RES
OU
RCE
_EN
UM
_LN
0x0
001
RES
OU
RCE
_EN
UM
_VA
LID
ATE
0x0
008
Search for resources in .mui files associated with the LN file
specified by hModule and with the current language
preferences, following the usual Resource Loader strategy (see
User Interface Language Management). Alternately, if LangId
is nonzero, then only the specified .mui file will be searched.
Typically this flag should be used only if hModule references
an LN file. If hModule references an .mui file, then that file is
actually covered by the RESOURCE_ENUM_LN flag, despite
the name of the flag.
Searches the file specified by hModule, regardless of whether
the file is an LN file, another type of LN file, or an .mui file.
Performs extra validation on the resource section and its
reference in the PE header while doing the enumeration to
ensure that resources are properly formatted. The validation
sets a maximum limit of 260 characters for each name that is
enumerated.
LangId
Type: L ANGID
The localization language used to filter the search in the MUI module. This parameter is used only when the
RESOURCE_ENUM_MUI flag is set in dwFlags. If zero is specified, then all .mui files that match current language
preferences are included in the search, following the usual Resource Loader strategy (see User Interface Language
Management). If a nonzero LangId is specified, then the only .mui file searched will be the one matching the
specified LangId.
Return value
Type: BOOL
The function TRUE if successful, or FALSE if the function does not find a resource of the type specified, or if the
function fails for another reason. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
The enumeration search can include both an LN file and its associated .mui files. It can be limited to a single binary
module of any type. It can also be limited to the .mui files associated with a single LN file. By specifying an LN file
for the hModule parameter and a nonzero LangId parameter, the search can be limited to the unique .mui file
associated with that LN file and language.
For each resource found, EnumResourceNamesEx calls an application-defined callback function lpEnumFunc,
passing the name or the ID of each resource it finds, as well as the various other parameters that were passed to
EnumResourceNamesEx .
If a resource has an ID, the ID is returned to the callback function; otherwise the resource name is returned to the
callback function. For more information, see EnumResNameProc.
The EnumResourceNamesEx function continues to enumerate resource names until the callback function returns
FALSE or all resource names for this type have been enumerated.
If hModule specifies an LN file, and both flags are selected, the names enumerated correspond to resources
residing either in that LN file or the .mui files associated with it. If no .mui files are found, only names from the LN
file are returned. After one appropriate .mui file is found the search will not continue further, because all .mui files
corresponding to a single LN file have the same resource names.
If dwFlags and LangId are both zero, then the function behaves like EnumResourceNames.
If LangId is nonzero, then only the .mui file corresponding to that Language identifier will be searched. Language
fallbacks will not be used. If an .mui file for that language does not exist, the enumeration will be empty (unless
resources for that language exist in the LN file, and the flag is set to search the LN file as well).
The enumeration never includes duplicates: if resources for a particular language are contained in both the LN file
and in an .mui file, the name will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResNameProc
EnumResourceLanguagesEx
EnumResourceNames
EnumResourceTypesEx
Reference
Resources
minutes to read • Edit Online
Enumerates resources of a specified type that are associated with a specified binary module. The search can include
both an LN file and its associated .mui files, or it can be limited in several ways.
Syntax
BOOL EnumResourceNamesExW(
HMODULE
hModule,
LPCWSTR
lpType,
ENUMRESNAMEPROCW lpEnumFunc,
LONG_PTR
lParam,
DWORD
dwFlags,
LANGID
LangId
);
Parameters
hModule
Type: HMODULE
The handle to a module to search. Typically this is an LN file, and if flag RESOURCE_ENUM_MUI is set, then
appropriate .mui files are included in the search. Alternately, this can be a handle to an .mui file or other LN file.
If this parameter is NULL , it is equivalent to passing in a handle to the module used to create the current process.
lpType
TBD
lpEnumFunc
Type: ENUMRESNAMEPROC
A pointer to the callback function to be called for each enumerated resource name. For more information, see
EnumResNameProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
dwFlags
Type: DWORD
The type of file to search. The following values are supported. Note that if dwFlags is zero, then the
RESOURCE_ENUM_LN and RESOURCE_ENUM_MUI flags are assumed to be specified.
VA L UE
M EA N IN G
RES
OU
RCE
_EN
UM
_M
UI
0x0
002
RES
OU
RCE
_EN
UM
_LN
0x0
001
RES
OU
RCE
_EN
UM
_VA
LID
ATE
0x0
008
Search for resources in .mui files associated with the LN file
specified by hModule and with the current language
preferences, following the usual Resource Loader strategy (see
User Interface Language Management). Alternately, if LangId
is nonzero, then only the specified .mui file will be searched.
Typically this flag should be used only if hModule references
an LN file. If hModule references an .mui file, then that file is
actually covered by the RESOURCE_ENUM_LN flag, despite
the name of the flag.
Searches the file specified by hModule, regardless of whether
the file is an LN file, another type of LN file, or an .mui file.
Performs extra validation on the resource section and its
reference in the PE header while doing the enumeration to
ensure that resources are properly formatted. The validation
sets a maximum limit of 260 characters for each name that is
enumerated.
LangId
Type: L ANGID
The localization language used to filter the search in the MUI module. This parameter is used only when the
RESOURCE_ENUM_MUI flag is set in dwFlags. If zero is specified, then all .mui files that match current language
preferences are included in the search, following the usual Resource Loader strategy (see User Interface Language
Management). If a nonzero LangId is specified, then the only .mui file searched will be the one matching the
specified LangId.
Return value
Type: BOOL
The function TRUE if successful, or FALSE if the function does not find a resource of the type specified, or if the
function fails for another reason. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
The enumeration search can include both an LN file and its associated .mui files. It can be limited to a single binary
module of any type. It can also be limited to the .mui files associated with a single LN file. By specifying an LN file
for the hModule parameter and a nonzero LangId parameter, the search can be limited to the unique .mui file
associated with that LN file and language.
For each resource found, EnumResourceNamesEx calls an application-defined callback function lpEnumFunc,
passing the name or the ID of each resource it finds, as well as the various other parameters that were passed to
EnumResourceNamesEx .
If a resource has an ID, the ID is returned to the callback function; otherwise the resource name is returned to the
callback function. For more information, see EnumResNameProc.
The EnumResourceNamesEx function continues to enumerate resource names until the callback function returns
FALSE or all resource names for this type have been enumerated.
If hModule specifies an LN file, and both flags are selected, the names enumerated correspond to resources
residing either in that LN file or the .mui files associated with it. If no .mui files are found, only names from the LN
file are returned. After one appropriate .mui file is found the search will not continue further, because all .mui files
corresponding to a single LN file have the same resource names.
If dwFlags and LangId are both zero, then the function behaves like EnumResourceNames.
If LangId is nonzero, then only the .mui file corresponding to that Language identifier will be searched. Language
fallbacks will not be used. If an .mui file for that language does not exist, the enumeration will be empty (unless
resources for that language exist in the LN file, and the flag is set to search the LN file as well).
The enumeration never includes duplicates: if resources for a particular language are contained in both the LN file
and in an .mui file, the name will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResNameProc
EnumResourceLanguagesEx
EnumResourceNames
EnumResourceTypesEx
Reference
Resources
minutes to read • Edit Online
Enumerates resource types associated with a specified binary module. The search can include both a languageneutral Portable Executable file (LN file) and its associated .mui files. Alternately, it can be limited to a single binary
module of any type, or to the .mui files associated with a single LN file. The search can also be limited to a single
associated .mui file that contains resources for a specific language.
For each resource type found, EnumResourceTypesEx calls an application-defined callback function lpEnumFunc,
passing the resource type it finds, as well as the various other parameters that were passed to
EnumResourceTypesEx .
Syntax
BOOL EnumResourceTypesExA(
HMODULE
hModule,
ENUMRESTYPEPROCA lpEnumFunc,
LONG_PTR
lParam,
DWORD
dwFlags,
LANGID
LangId
);
Parameters
hModule
Type: HMODULE
The handle to a module to be searched. Typically this is an LN file, and if flag RESOURCE_ENUM_MUI is set, then
appropriate .mui files can be included in the search. Alternately, this can be a handle to an .mui file or other LN file.
If this parameter is NULL , it is equivalent to passing in a handle to the module used to create the current process.
lpEnumFunc
Type: ENUMRESTYPEPROC
A pointer to the callback function to be called for each enumerated resource type. For more information, see
EnumResTypeProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function.
dwFlags
Type: DWORD
The type of file to be searched. The following values are supported. Note that if dwFlags is zero, then the
RESOURCE_ENUM_LN and RESOURCE_ENUM_MUI flags are assumed to be specified.
VA L UE
M EA N IN G
RES
OU
RCE
_EN
UM
_M
UI
0x0
002
RES
OU
RCE
_EN
UM
_LN
0x0
001
RES
OU
RCE
_EN
UM
_VA
LID
ATE
0x0
008
Search for resource types in one of the .mui files associated
with the file specified by hModule and with the current
language preferences, following the usual Resource Loader
strategy (see User Interface Language Management).
Alternately, if LangId is nonzero, then only the .mui file of the
language as specified by LangId will be searched. Typically this
flag should be used only if hModule references an LN file. If
hModule references an .mui file, then that file is actually
covered by the RESOURCE_ENUM_LN flag, despite the
name of the flag.
Searches only the file specified by hModule, regardless of
whether the file is an LN file or an .mui file.
Performs extra validation on the resource section and its
reference in the PE header while doing the enumeration to
ensure that resources are properly formatted. The validation
sets a maximum limit of 260 characters for each type that is
enumerated.
LangId
Type: L ANGID
The language used to filter the search in the MUI module. This parameter is used only when the
RESOURCE_ENUM_MUI flag is set in dwFlags. If zero is specified, then all .mui files that match current language
preferences are included in the search, following the usual Resource Loader strategy (see User Interface Language
Management). If a nonzero LangId is specified, then the only .mui file searched will be the one matching the
specified LangId.
Return value
Type: BOOL
Returns TRUE if successful or FALSE if the function does not find a resource of the type specified, or if the function
fails for another reason. To get extended error information, call GetLastError.
Remarks
The EnumResourceTypesEx function continues to enumerate resource types until the callback function returns
FALSE or all resource types have been enumerated.
If hModule specifies an LN file, and both flags are selected, the types enumerated correspond to resources residing
either in the LN file or in the .mui files associated with it. If no .mui files are found, only types from the LN file are
returned. Once one appropriate .mui file is found the search will not continue further, because all .mui files
corresponding to a single LN file have the same resource types.
If dwFlags and LangId are both zero, then the function behaves like EnumResourceTypes.
If LangId is nonzero, then only the .mui file corresponding to that language identifier will be searched. Language
fallbacks will not be used. If an .mui file for that language does not exist, the enumeration will be empty (unless
resources for that language exist in the LN file, and the flag is set to search the LN file as well).
The enumeration never includes duplicates: if resources for a particular language are contained in both the LN file
and in an .mui file, the type will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResTypeProc
EnumResourceLanguagesEx
EnumResourceNamesEx
EnumResourceTypes
Reference
Resources
minutes to read • Edit Online
Enumerates resource types associated with a specified binary module. The search can include both a languageneutral Portable Executable file (LN file) and its associated .mui files. Alternately, it can be limited to a single binary
module of any type, or to the .mui files associated with a single LN file. The search can also be limited to a single
associated .mui file that contains resources for a specific language.
For each resource type found, EnumResourceTypesEx calls an application-defined callback function lpEnumFunc,
passing the resource type it finds, as well as the various other parameters that were passed to
EnumResourceTypesEx .
Syntax
BOOL EnumResourceTypesExW(
HMODULE
hModule,
ENUMRESTYPEPROCW lpEnumFunc,
LONG_PTR
lParam,
DWORD
dwFlags,
LANGID
LangId
);
Parameters
hModule
Type: HMODULE
The handle to a module to be searched. Typically this is an LN file, and if flag RESOURCE_ENUM_MUI is set, then
appropriate .mui files can be included in the search. Alternately, this can be a handle to an .mui file or other LN file.
If this parameter is NULL , it is equivalent to passing in a handle to the module used to create the current process.
lpEnumFunc
Type: ENUMRESTYPEPROC
A pointer to the callback function to be called for each enumerated resource type. For more information, see
EnumResTypeProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function.
dwFlags
Type: DWORD
The type of file to be searched. The following values are supported. Note that if dwFlags is zero, then the
RESOURCE_ENUM_LN and RESOURCE_ENUM_MUI flags are assumed to be specified.
VA L UE
M EA N IN G
RES
OU
RCE
_EN
UM
_M
UI
0x0
002
RES
OU
RCE
_EN
UM
_LN
0x0
001
RES
OU
RCE
_EN
UM
_VA
LID
ATE
0x0
008
Search for resource types in one of the .mui files associated
with the file specified by hModule and with the current
language preferences, following the usual Resource Loader
strategy (see User Interface Language Management).
Alternately, if LangId is nonzero, then only the .mui file of the
language as specified by LangId will be searched. Typically this
flag should be used only if hModule references an LN file. If
hModule references an .mui file, then that file is actually
covered by the RESOURCE_ENUM_LN flag, despite the
name of the flag.
Searches only the file specified by hModule, regardless of
whether the file is an LN file or an .mui file.
Performs extra validation on the resource section and its
reference in the PE header while doing the enumeration to
ensure that resources are properly formatted. The validation
sets a maximum limit of 260 characters for each type that is
enumerated.
LangId
Type: L ANGID
The language used to filter the search in the MUI module. This parameter is used only when the
RESOURCE_ENUM_MUI flag is set in dwFlags. If zero is specified, then all .mui files that match current language
preferences are included in the search, following the usual Resource Loader strategy (see User Interface Language
Management). If a nonzero LangId is specified, then the only .mui file searched will be the one matching the
specified LangId.
Return value
Type: BOOL
Returns TRUE if successful or FALSE if the function does not find a resource of the type specified, or if the function
fails for another reason. To get extended error information, call GetLastError.
Remarks
The EnumResourceTypesEx function continues to enumerate resource types until the callback function returns
FALSE or all resource types have been enumerated.
If hModule specifies an LN file, and both flags are selected, the types enumerated correspond to resources residing
either in the LN file or in the .mui files associated with it. If no .mui files are found, only types from the LN file are
returned. Once one appropriate .mui file is found the search will not continue further, because all .mui files
corresponding to a single LN file have the same resource types.
If dwFlags and LangId are both zero, then the function behaves like EnumResourceTypes.
If LangId is nonzero, then only the .mui file corresponding to that language identifier will be searched. Language
fallbacks will not be used. If an .mui file for that language does not exist, the enumeration will be empty (unless
resources for that language exist in the LN file, and the flag is set to search the LN file as well).
The enumeration never includes duplicates: if resources for a particular language are contained in both the LN file
and in an .mui file, the type will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResTypeProc
EnumResourceLanguagesEx
EnumResourceNamesEx
EnumResourceTypes
Reference
Resources
minutes to read • Edit Online
An application-defined callback function used with the EnumResourceTypes and EnumResourceTypesEx functions. It
receives resource types. The ENUMRESTYPEPROC type defines a pointer to this callback function.
EnumResTypeProc is a placeholder for the application-defined function name.
Syntax
ENUMRESTYPEPROCA Enumrestypeproca;
BOOL Enumrestypeproca(
HMODULE hModule,
LPSTR lpType,
LONG_PTR lParam
)
{...}
Parameters
hModule
Type: HMODULE
A handle to the module whose executable file contains the resources for which the types are to be enumerated. If
this parameter is NULL , the function enumerates the resource types in the module used to create the current
process.
lpType
lParam
Type: LONG_PTR
An application-defined parameter passed to the EnumResourceTypes or EnumResourceTypesEx function. This
parameter can be used in error checking.
Return value
Type: BOOL
Returns TRUE to continue enumeration or FALSE to stop enumeration.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the integer identifier of the resource type. For
example, the string "#258" represents the identifier 258.
An application must register this function by passing its address to the EnumResourceTypes or
EnumResourceTypesEx function.
If the callback function returns FALSE , then EnumResourceTypes or EnumResourceTypesEx will stop enumeration
and return FALSE . On Windows XP and earlier the value obtained from GetLastError will be ERROR_SUCCESS ;
starting with Windows Vista, the last error value will be ERROR_RESOURCE_ENUM_USER_STOP .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
See also
Conceptual
EnumResourceTypes
EnumResourceTypesEx
IS_INTRESOURCE
Reference
Resources
minutes to read • Edit Online
An application-defined callback function used with the EnumResourceTypes and EnumResourceTypesEx functions. It
receives resource types. The ENUMRESTYPEPROC type defines a pointer to this callback function.
EnumResTypeProc is a placeholder for the application-defined function name.
Syntax
ENUMRESTYPEPROCW Enumrestypeprocw;
BOOL Enumrestypeprocw(
HMODULE hModule,
LPWSTR lpType,
LONG_PTR lParam
)
{...}
Parameters
hModule
Type: HMODULE
A handle to the module whose executable file contains the resources for which the types are to be enumerated. If
this parameter is NULL , the function enumerates the resource types in the module used to create the current
process.
lpType
lParam
Type: LONG_PTR
An application-defined parameter passed to the EnumResourceTypes or EnumResourceTypesEx function. This
parameter can be used in error checking.
Return value
Type: BOOL
Returns TRUE to continue enumeration or FALSE to stop enumeration.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the integer identifier of the resource type. For
example, the string "#258" represents the identifier 258.
An application must register this function by passing its address to the EnumResourceTypes or
EnumResourceTypesEx function.
If the callback function returns FALSE , then EnumResourceTypes or EnumResourceTypesEx will stop enumeration
and return FALSE . On Windows XP and earlier the value obtained from GetLastError will be ERROR_SUCCESS ;
starting with Windows Vista, the last error value will be ERROR_RESOURCE_ENUM_USER_STOP .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
See also
Conceptual
EnumResourceTypes
EnumResourceTypesEx
IS_INTRESOURCE
Reference
Resources
minutes to read • Edit Online
[This function is obsolete and is only supported for backward compatibility with 16-bit Windows. For 32-bit
Windows applications, it is not necessary to free the resources loaded using LoadResource. If used on 32 or 64-bit
Windows systems, this function will return FALSE .]
Decrements (decreases by one) the reference count of a loaded resource. When the reference count reaches zero,
the memory occupied by the resource is freed.
Syntax
BOOL FreeResource(
HGLOBAL hResData
);
Parameters
hResData
TBD
Return value
Type: BOOL
If the function succeeds, the return value is zero.
If the function fails, the return value is nonzero, which indicates that the resource has not been freed.
Remarks
For resources loaded with other functions, FreeResource has been replaced by the following functions:
RESO URC E T Y P E
F REERESO URC E REP L A C EM EN T
Accelerator
DestroyAcceleratorTable
Bitmap
DeleteObject
Cursor
DestroyCursor
Icon
DestroyIcon
Menu
DestroyMenu
The reference count for a resource is incremented (increased by one) each time an application calls the
LoadResource function for the resource.
The system automatically deletes these resources when the process that created them terminates. However, calling
the appropriate function saves memory. For more information, see LoadResource.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
DeleteObject
DestroyAcceleratorTable
DestroyCursor
DestroyIcon
DestroyMenu
LoadResource
Other Resources
Reference
minutes to read • Edit Online
Retrieves a handle that can be used to obtain a pointer to the first byte of the specified resource in memory.
Syntax
HGLOBAL LoadResource(
HMODULE hModule,
HRSRC hResInfo
);
Parameters
hModule
Type: HMODULE
A 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.
hResInfo
Type: HRSRC
A handle to the resource to be loaded. This handle is returned by the FindResource or FindResourceEx function.
Return value
Type: HGLOBAL
If the function succeeds, the return value is a handle to the data associated with the resource.
If the function fails, the return value is NULL . 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. Do not pass this handle to the GlobalLock or GlobalFree function. To obtain a
pointer to the first byte of the resource data, call the LockResource function; to obtain the size of the resource, call
SizeofResource.
To use a resource immediately, an application should use the following resource-specific functions to find and load
the resource in one call.
F UN C T IO N
A C T IO N
TO REM O VE RESO URC E
FormatMessage
Loads and formats a message-table
entry
No action needed
LoadAccelerators
Loads an accelerator table
DestroyAcceleratorTable
LoadBitmap
Loads a bitmap resource
DeleteObject
LoadCursor
Loads a cursor resource
DestroyCursor
LoadIcon
Loads an icon resource
DestroyIcon
LoadMenu
Loads a menu resource
DestroyMenu
LoadString
Loads a string resource
No action needed
For example, an application can use the LoadIcon function to load an icon for display on the screen, followed by
DestroyIcon when done.
Examples
For an example see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
FindResource
FindResourceEx
LoadLibrary
LoadModule
LockResource
Other Resources
Reference
Resources
minutes to read • Edit Online
Retrieves a pointer to the specified resource in memory.
Syntax
LPVOID LockResource(
HGLOBAL hResData
);
Parameters
hResData
Type: HGLOBAL
A handle to the resource to be accessed. The LoadResource function returns this handle. Note that this parameter is
listed as an HGLOBAL variable only for backward compatibility. Do not pass any value as a parameter other than a
successful return value from the LoadResource function.
Return value
Type: LPVOID
If the loaded resource is available, the return value is a pointer to the first byte of the resource; otherwise, it is
NULL .
Remarks
The pointer returned by LockResource is valid until the module containing the resource is unloaded. It is not
necessary to unlock resources because the system automatically deletes them when the process that created them
terminates.
Do not try to lock a resource by using the handle returned by the FindResource or FindResourceEx function. Such a
handle points to random data.
Note LockResource does not actually lock memory; it is just used to obtain a pointer to
the memory containing the resource data. The name of the function comes from versions prior to Windows XP, when it was
used to lock a global memory block allocated by LoadResource.
Examples
For an example, see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
FindResource
FindResourceEx
LoadResource
Reference
Resources
minutes to read • Edit Online
Retrieves the size, in bytes, of the specified resource.
Syntax
DWORD SizeofResource(
HMODULE hModule,
HRSRC hResInfo
);
Parameters
hModule
Type: HMODULE
A handle to the module whose executable file contains the resource.
hResInfo
Type: HRSRC
A handle to the resource. This handle must be created by using the FindResource or FindResourceEx function.
Return value
Type: DWORD
If the function succeeds, the return value is the number of bytes in the resource.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
libloaderapi.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
FindResource
FindResourceEx
Reference
Resources
minutes to read • Edit Online
This header is used by Menus and Other Resources. For more information, see:
Menus and Other Resources resourceindexer.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
CreateResourceIndexer
Creates a new resource indexer for the specified paths of the
root of the project files and the extension DLL.
DestroyIndexedResults
Frees the parameters that the IndexFilePath method returned.
DestroyResourceIndexer
Frees the computational resources associated with the
specified resource indexer.
IndexFilePath
Indexes a file path for file and folder naming conventions.
Structures
T IT L E
DESC RIP T IO N
IndexedResourceQualifier
Represents the context under which a resource is appropriate.
minutes to read • Edit Online
Creates a new resource indexer for the specified paths of the root of the project files and the extension DLL.
Syntax
HRESULT CreateResourceIndexer(
PCWSTR projectRoot,
PCWSTR extensionDllPath,
PVOID *ppResourceIndexer
);
Parameters
projectRoot
The path of the root folder to use for the project for the files to be produced, in string form. This path is used to
determine file paths relative to the package that contains them. This path must be an absolute path with the drive
letter specified. Long file paths are not supported.
extensionDllPath
The full path to an extension dynamic-link library (DLL) that is Microsoft-signed and implements the ext-ms-winmrmcorer-environment-l1 API set. This path determines the file path from where the extension DLL for the modern
resource technology (MRT) environment is loaded. This path must be an absolute path with the drive letter
specified. Long file paths are not supported.
ppResourceIndexer
The newly created resource indexer.
Return value
If this function succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.
Requirements
Minimum suppor ted client
Windows 10 [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2016 [desktop apps only]
Target Platform
Windows
Header
resourceindexer.h
Librar y
Mrmsupport.lib
DLL
Mrmsupport.dll
See also
DestroyResourceIndexer
DestroyIndexedResults function
4/3/2020 • 2 minutes to read • Edit Online
Frees the parameters that the IndexFilePath method returned.
Syntax
void DestroyIndexedResults(
PWSTR
resourceUri,
ULONG
qualifierCount,
IndexedResourceQualifier *qualifiers
);
Parameters
resourceUri
A uniform resource indicator (URI) that uses the ms-resource URI scheme and represents the named resource for
the candidate, where the authority of the URI or the resource map is empty. For example, msresource:///Resources/String1 or ms-resource:///Files/images/logo.png.
qualifierCount
The number of indexed resource qualifiers that the list in the ppQualifiers parameter contains.
qualifiers
A list of indexed resource qualifiers that declare the context under which the resources are appropriate.
Return value
None
Requirements
Minimum suppor ted client
Windows 10 [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2016 [desktop apps only]
Target Platform
Windows
Header
resourceindexer.h
Librar y
Mrmsupport.lib
DLL
Mrmsupport.dll
See also
IndexFilePath
IndexedResourceQualifier
DestroyResourceIndexer function
4/3/2020 • 2 minutes to read • Edit Online
Frees the computational resources associated with the specified resource indexer.
Syntax
void DestroyResourceIndexer(
PVOID resourceIndexer
);
Parameters
resourceIndexer
The resource indexer for which you want to free the computational resources.
Return value
None
Requirements
Minimum suppor ted client
Windows 10 [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2016 [desktop apps only]
Target Platform
Windows
Header
resourceindexer.h
Librar y
Mrmsupport.lib
DLL
Mrmsupport.dll
See also
CreateResourceIndexer
minutes to read • Edit Online
Represents the context under which a resource is appropriate.
Syntax
typedef struct {
PWSTR name;
PWSTR value;
} IndexedResourceQualifier;
Members
name
The name of the qualifier, such as "language", "contrast", or "scale".
value
The value of the qualifier. You should preserve the case of the qualifier value from the first instance of the qualifier
discovered during indexing.
The following values are examples of the qualifier values:
"100", "140", or "180" for scale.
"fr-FR" for language.
"high" for contrast.
Requirements
Minimum suppor ted client
Windows 10 [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2016 [desktop apps only]
Header
resourceindexer.h
See also
DestroyIndexedResults
IndexFilePath
minutes to read • Edit Online
Indexes a file path for file and folder naming conventions.
Syntax
HRESULT IndexFilePath(
PVOID
PCWSTR
PWSTR
ULONG
IndexedResourceQualifier
);
resourceIndexer,
filePath,
*ppResourceUri,
*pQualifierCount,
**ppQualifiers
Parameters
resourceIndexer
The resource indexer object that you created by calling the CreateResourceIndexer function.
filePath
The path for the folder that you want to index. The path must be an absolute path with the drive letter specified.
Long file paths are not supported.
ppResourceUri
A uniform resource indicator (URI) that uses the ms-resource URI scheme and represents the named resource for
the candidate, where the authority of the URI or the resource map is empty. For example, msresource:///Resources/String1 or ms-resource:///Files/images/logo.png.
pQualifierCount
The number of indexed resource qualifiers that the list in the ppQualifiers parameter contains.
ppQualifiers
A list of indexed resource qualifiers that declare the context under which the resources are appropriate.
Return value
If this function succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.
Requirements
Minimum suppor ted client
Windows 10 [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2016 [desktop apps only]
Target Platform
Windows
Header
resourceindexer.h
Librar y
Mrmsupport.lib
DLL
Mrmsupport.dll
See also
CreateResourceIndexer
IndexedResourceQualifier
minutes to read • Edit Online
This header is used by Menus and Other Resources. For more information, see:
Menus and Other Resources strsafe.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
StringCbCatA
Concatenates one string to another string.
StringCbCatExA
Concatenates one string to another string.
StringCbCatExW
Concatenates one string to another string.
StringCbCatNA
Concatenates the specified number of bytes from one string
to another string.
StringCbCatNExA
Concatenates the specified number of bytes from one string
to another string.
StringCbCatNExW
Concatenates the specified number of bytes from one string
to another string.
StringCbCatNW
Concatenates the specified number of bytes from one string
to another string.
StringCbCatW
Concatenates one string to another string.
StringCbCopyA
Copies one string to another.
StringCbCopyExA
Copies one string to another.
StringCbCopyExW
Copies one string to another.
StringCbCopyNA
Copies the specified number of bytes from one string to
another.
StringCbCopyNExA
Copies the specified number of bytes from one string to
another.
StringCbCopyNExW
Copies the specified number of bytes from one string to
another.
StringCbCopyNW
Copies the specified number of bytes from one string to
another.
StringCbCopyW
Copies one string to another.
T IT L E
DESC RIP T IO N
StringCbGetsA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbGetsExA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbGetsExW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbGetsW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCbLengthA
Determines whether a string exceeds the specified length, in
bytes.
StringCbLengthW
Determines whether a string exceeds the specified length, in
bytes.
StringCbPrintf_lA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintf_lExA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintf_lExW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintf_lW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCbPrintfA
Writes formatted data to the specified string.
StringCbPrintfExA
Writes formatted data to the specified string.
StringCbPrintfExW
Writes formatted data to the specified string.
StringCbPrintfW
Writes formatted data to the specified string.
StringCbVPrintf_lA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintf_lExA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
T IT L E
DESC RIP T IO N
StringCbVPrintf_lExW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintf_lW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCbVPrintfA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCbVPrintfExA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCbVPrintfExW
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCbVPrintfW
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCchCatA
Concatenates one string to another string.
StringCchCatExA
Concatenates one string to another string.
StringCchCatExW
Concatenates one string to another string.
StringCchCatNA
Concatenates the specified number of characters from one
string to another string.
StringCchCatNExA
Concatenates the specified number of characters from one
string to another string.
StringCchCatNExW
Concatenates the specified number of characters from one
string to another string.
StringCchCatNW
Concatenates the specified number of characters from one
string to another string.
StringCchCatW
Concatenates one string to another string.
StringCchCopyA
Copies one string to another.
StringCchCopyExA
Copies one string to another.
StringCchCopyExW
Copies one string to another.
StringCchCopyNA
Copies the specified number of characters from one string to
another.
StringCchCopyNExA
Copies the specified number of characters from one string to
another.
T IT L E
DESC RIP T IO N
StringCchCopyNExW
Copies the specified number of characters from one string to
another.
StringCchCopyNW
Copies the specified number of characters from one string to
another.
StringCchCopyW
Copies one string to another.
StringCchGetsA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchGetsExA
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchGetsExW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchGetsW
Gets one line of text from stdin, up to and including the
newline character ('\n').
StringCchLengthA
Determines whether a string exceeds the specified length, in
characters.
StringCchLengthW
Determines whether a string exceeds the specified length, in
characters.
StringCchPrintf_lA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintf_lExA
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintf_lExW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintf_lW
Writes formatted data to the specified string. The size of the
destination buffer is provided to the function to ensure that it
does not write past the end of this buffer.
StringCchPrintfA
Writes formatted data to the specified string.
StringCchPrintfExA
Writes formatted data to the specified string.
StringCchPrintfExW
Writes formatted data to the specified string.
StringCchPrintfW
Writes formatted data to the specified string.
StringCchVPrintf_lA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
T IT L E
DESC RIP T IO N
StringCchVPrintf_lExA
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintf_lExW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintf_lW
Writes formatted data to the specified string using a pointer
to a list of arguments. The size of the destination buffer is
provided to the function to ensure that it does not write past
the end of this buffer.
StringCchVPrintfA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCchVPrintfExA
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCchVPrintfExW
Writes formatted data to the specified string using a pointer
to a list of arguments.
StringCchVPrintfW
Writes formatted data to the specified string using a pointer
to a list of arguments.
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbCat is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCbCatA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPCSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The string to which pszSrc is to be concatenated, and that will receive the entire resultant string. The string at pszSrc
is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the length of pszDest
plus the terminating null character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
S_O
K
The value in cbDest is either less than sizeof(TCHAR) or
larger than the maximum allowed value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCat provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. It always null-terminates and never overflows a
valid destination buffer, even if the contents of the source string change during the operation.
StringCbCat can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatA
TCHAR
TEXT("string")
StringCbCat
WCHAR
L"string"
StringCbCatW
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCatEx if you require the handling of null string pointer
values.
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatEx
StringCbCatN
StringCchCat
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbCatEx adds to the functionality of StringCbCat by returning a pointer to the end of the destination string
as well as the number of bytes left unused in that string. Flags may also be passed to the function for additional
control.
StringCbCatEx is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCbCatExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPCSTR pszSrc,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The string to which pszSrc is to be concatenated, and that will receive the entire resultant string. The string at pszSrc
is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the length of pszDest
plus the terminating null character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is concatenated to the end of pszDest. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cbDest is either less than sizeof(TCHAR) or
larger than the maximum allowed value.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCatEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbCatEx always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCatEx can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatExA
TCHAR
TEXT("string")
StringCbCatEx
WCHAR
L"string"
StringCbCatExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCat
StringCbCatNEx
StringCchCatEx
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbCatEx adds to the functionality of StringCbCat by returning a pointer to the end of the destination string
as well as the number of bytes left unused in that string. Flags may also be passed to the function for additional
control.
StringCbCatEx is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCbCatExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPCWSTR pszSrc,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The string to which pszSrc is to be concatenated, and that will receive the entire resultant string. The string at pszSrc
is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the length of pszDest
plus the terminating null character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is concatenated to the end of pszDest. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cbDest is either less than sizeof(TCHAR) or
larger than the maximum allowed value.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCatEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbCatEx always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCatEx can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatExA
TCHAR
TEXT("string")
StringCbCatEx
WCHAR
L"string"
StringCbCatExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCat
StringCbCatNEx
StringCchCatEx
minutes to read • Edit Online
Concatenates the specified number of bytes from one string to another string. The size, in bytes, of the destination
buffer is provided to the function to ensure that it does not write past the end of this buffer.
StringCbCatN is a replacement for the following functions:
strncat
StrNCat
Syntax
STRSAFEAPI StringCbCatNA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZCH pszSrc,
size_t
cbToAppend
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated to pszSrc, and will receive the resultant
string. The string at pszSrc, up to cbMaxAppend bytes, is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus either the length of
pszDest or cbMaxAppend (whichever is smaller) plus the terminating null character. The maximum number of bytes
allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This source string must be null-terminated.
cbToAppend
Type: size_t
The maximum number of bytes to be appended to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cbDest is larger than the maximum allowed value,
or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCatN provides additional processing for proper buffer handling in
your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCatN always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCatNEx if you require the handling of null string pointer
values.
StringCbCatN can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatNA
TCHAR
TEXT("string")
StringCbCatN
WCHAR
L"string"
StringCbCatNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCat
StringCbCatNEx
StringCchCatN
minutes to read • Edit Online
Concatenates the specified number of bytes from one string to another string. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
StringCbCatNEx is a replacement for the following functions:
strncat
StrNCat
StringCbCatNEx adds to the functionality of StringCbCatN by returning a pointer to the end of the destination string
as well as the number of bytes left unused in that string. Flags may also be passed to the function for additional
control.
Syntax
STRSAFEAPI StringCbCatNExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZCH pszSrc,
size_t
cbToAppend,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated with pszSrc, and will receive the entire
resultant string. The string at pszSrc is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the length of pszDest
plus the bytes used for the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
cbToAppend
Type: size_t
The maximum number of bytes to append to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cbDest is larger than
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STRSAFE_MAX_CCH * sizeof(TCHAR) , an invalid flag was
passed, or there are discrepancies between the size of the
pszDest, cbDest, and the amount of material to append in
pszSrc.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCatNEx provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCatNEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCatNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatNExA
TCHAR
TEXT("string")
StringCbCatNEx
WCHAR
L"string"
StringCbCatNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatEx
StringCbCatN
StringCchCatNEx
minutes to read • Edit Online
Concatenates the specified number of bytes from one string to another string. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
StringCbCatNEx is a replacement for the following functions:
strncat
StrNCat
StringCbCatNEx adds to the functionality of StringCbCatN by returning a pointer to the end of the destination string
as well as the number of bytes left unused in that string. Flags may also be passed to the function for additional
control.
Syntax
STRSAFEAPI StringCbCatNExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cbToAppend,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated with pszSrc, and will receive the entire
resultant string. The string at pszSrc is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the length of pszDest
plus the bytes used for the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
cbToAppend
Type: size_t
The maximum number of bytes to append to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cbDest is larger than
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STRSAFE_MAX_CCH * sizeof(TCHAR) , an invalid flag was
passed, or there are discrepancies between the size of the
pszDest, cbDest, and the amount of material to append in
pszSrc.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCatNEx provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCatNEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCatNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatNExA
TCHAR
TEXT("string")
StringCbCatNEx
WCHAR
L"string"
StringCbCatNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatEx
StringCbCatN
StringCchCatNEx
minutes to read • Edit Online
Concatenates the specified number of bytes from one string to another string. The size, in bytes, of the destination
buffer is provided to the function to ensure that it does not write past the end of this buffer.
StringCbCatN is a replacement for the following functions:
strncat
StrNCat
Syntax
STRSAFEAPI StringCbCatNW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cbToAppend
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated to pszSrc, and will receive the resultant
string. The string at pszSrc, up to cbMaxAppend bytes, is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus either the length of
pszDest or cbMaxAppend (whichever is smaller) plus the terminating null character. The maximum number of bytes
allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This source string must be null-terminated.
cbToAppend
Type: size_t
The maximum number of bytes to be appended to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cbDest is larger than the maximum allowed value,
or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCatN provides additional processing for proper buffer handling in
your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCatN always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCatNEx if you require the handling of null string pointer
values.
StringCbCatN can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatNA
TCHAR
TEXT("string")
StringCbCatN
WCHAR
L"string"
StringCbCatNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCat
StringCbCatNEx
StringCchCatN
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbCat is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCbCatW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPCWSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The string to which pszSrc is to be concatenated, and that will receive the entire resultant string. The string at pszSrc
is added to the end of the string at pszDest.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the length of pszDest
plus the terminating null character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
S_O
K
The value in cbDest is either less than sizeof(TCHAR) or
larger than the maximum allowed value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCat provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. It always null-terminates and never overflows a
valid destination buffer, even if the contents of the source string change during the operation.
StringCbCat can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCatA
TCHAR
TEXT("string")
StringCbCat
WCHAR
L"string"
StringCbCatW
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCatEx if you require the handling of null string pointer
values.
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatEx
StringCbCatN
StringCchCat
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of this buffer.
StringCbCopy is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCbCopyA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPCSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the terminating null
character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
A pointer to a buffer containing the source string. This source string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
The value in cbDest is either less than sizeof(TCHAR) or
larger than the maximum allowed value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCopy provides additional processing for proper buffer handling in
your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCopy always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCopyEx if you require the handling of null string pointer
values.
StringCbCopy can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyA
TCHAR
TEXT("string")
StringCbCopy
WCHAR
L"string"
StringCbCopyW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyEx
StringCchCopy
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of this buffer.
StringCbCopyEx adds to the functionality of StringCbCopy by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbCopyEx is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCbCopyExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPCSTR pszSrc,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the terminating null
character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest is NULL when there is source data present to
copy, or an invalid flag was passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCopyEx provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCopyEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCopyEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyExA
TCHAR
TEXT("string")
StringCbCopyEx
WCHAR
L"string"
StringCbCopyExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopy
StringCchCopyEx
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of this buffer.
StringCbCopyEx adds to the functionality of StringCbCopy by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbCopyEx is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCbCopyExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPCWSTR pszSrc,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the terminating null
character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest is NULL when there is source data present to
copy, or an invalid flag was passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCopyEx provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCopyEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCopyEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyExA
TCHAR
TEXT("string")
StringCbCopyEx
WCHAR
L"string"
StringCbCopyExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopy
StringCchCopyEx
minutes to read • Edit Online
Copies the specified number of bytes from one string to another. The size of the destination buffer is provided to
the function to ensure that it does not write past the end of this buffer.
StringCbCopyN is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCbCopyNA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZCH pszSrc,
size_t
cbToCopy
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cbDest
Type: size_t
The size of pszDest, in bytes. This value must be large enough to hold the copied bytes (the size of pszSrc or the
value of cbSrc, whichever is smaller) and also account for the terminating null character. The maximum number of
characters allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
cbToCopy
Type: size_t
The maximum number of bytes to be copied from pszSrc to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the data was copied from pszSrc
without truncation, and the resultant destination buffer is nullterminated.
S_O
K
The value in cbDest is either larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCopyN provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbCopyN always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cbSrc is larger than the
number of bytes in pszSrc, StringCbCopyN —unlike strncpy —does not continue to pad pszDest with null
characters until cbSrc bytes have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCopyNEx if you require the handling of null string
pointer values.
StringCbCopyN can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyNA
TCHAR
TEXT("string")
StringCbCopyN
WCHAR
L"string"
StringCbCopyNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopy
StringCbCopyNEx
StringCchCopyN
minutes to read • Edit Online
Copies the specified number of bytes from one string to another. The size of the destination buffer is provided to
the function to ensure that it does not write past the end of this buffer.
StringCbCopyNEx adds to the functionality of StringCbCopyN by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbCopyNEx is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCbCopyNExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZCH pszSrc,
size_t
cbToCopy,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cbDest
Type: size_t
The size of pszDest, in bytes. This value must be at least large enough to hold the copied bytes (the length of pszSrc
or the value of cbSrc, whichever is smaller) as well as to account for the terminating null character. The maximum
number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
cbToCopy
Type: size_t
The maximum number of bytes to be copied from pszSrc to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest or pszSrc is greater than
STRSAFE_MAX_CCH * sizeof(TCHAR) , pszDest is NULL when
there is source data present to copy, or an invalid flag was
passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCopyNEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbCopyNEx always null-terminates and
never overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cbSrc is larger than the
number of bytes in pszSrc, StringCbCopyNEx —unlike strncpy —does not continue to pad pszDest with null
characters until cbSrc bytes have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCopyNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyNExA
TCHAR
TEXT("string")
StringCbCopyNEx
WCHAR
L"string"
StringCbCopyNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyN
StringCchCopyNEx
minutes to read • Edit Online
Copies the specified number of bytes from one string to another. The size of the destination buffer is provided to
the function to ensure that it does not write past the end of this buffer.
StringCbCopyNEx adds to the functionality of StringCbCopyN by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbCopyNEx is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCbCopyNExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cbToCopy,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cbDest
Type: size_t
The size of pszDest, in bytes. This value must be at least large enough to hold the copied bytes (the length of pszSrc
or the value of cbSrc, whichever is smaller) as well as to account for the terminating null character. The maximum
number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
cbToCopy
Type: size_t
The maximum number of bytes to be copied from pszSrc to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest or pszSrc is greater than
STRSAFE_MAX_CCH * sizeof(TCHAR) , pszDest is NULL when
there is source data present to copy, or an invalid flag was
passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCopyNEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbCopyNEx always null-terminates and
never overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cbSrc is larger than the
number of bytes in pszSrc, StringCbCopyNEx —unlike strncpy —does not continue to pad pszDest with null
characters until cbSrc bytes have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCbCopyNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyNExA
TCHAR
TEXT("string")
StringCbCopyNEx
WCHAR
L"string"
StringCbCopyNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyN
StringCchCopyNEx
minutes to read • Edit Online
Copies the specified number of bytes from one string to another. The size of the destination buffer is provided to
the function to ensure that it does not write past the end of this buffer.
StringCbCopyN is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCbCopyNW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cbToCopy
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cbDest
Type: size_t
The size of pszDest, in bytes. This value must be large enough to hold the copied bytes (the size of pszSrc or the
value of cbSrc, whichever is smaller) and also account for the terminating null character. The maximum number of
characters allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
cbToCopy
Type: size_t
The maximum number of bytes to be copied from pszSrc to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the data was copied from pszSrc
without truncation, and the resultant destination buffer is nullterminated.
S_O
K
The value in cbDest is either larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbCopyN provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbCopyN always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cbSrc is larger than the
number of bytes in pszSrc, StringCbCopyN —unlike strncpy —does not continue to pad pszDest with null
characters until cbSrc bytes have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCopyNEx if you require the handling of null string
pointer values.
StringCbCopyN can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyNA
TCHAR
TEXT("string")
StringCbCopyN
WCHAR
L"string"
StringCbCopyNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopy
StringCbCopyNEx
StringCchCopyN
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of this buffer.
StringCbCopy is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCbCopyW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPCWSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must consider the length of pszSrc plus the terminating null
character. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszSrc
Type: LPCTSTR
A pointer to a buffer containing the source string. This source string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
The value in cbDest is either less than sizeof(TCHAR) or
larger than the maximum allowed value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbCopy provides additional processing for proper buffer handling in
your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbCopy always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCbCopyEx if you require the handling of null string pointer
values.
StringCbCopy can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbCopyA
TCHAR
TEXT("string")
StringCbCopy
WCHAR
L"string"
StringCbCopyW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyEx
StringCchCopy
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCbGets is a replacement for the following functions:
gets, _getws, _getts
StringCbGets is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCbGetsA(
STRSAFE_LPSTR pszDest,
size_t
cbDest
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the input.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be greater than sizeof(TCHAR) for the function to
succeed. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) . If cbDest is too small to hold
the full line of text, the data is truncated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
Data was read from stdin, was copied to the buffer at pszDest,
and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
STR
SAF
E_E
_EN
D_
OF_
FIL
E
The value in cbDest is larger than the maximum allowed value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cbDest is
sizeof(TCHAR)
or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbGets provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbGets always null-terminates a nonzerolength destination buffer.
The value of pszDest should not be NULL . See StringCbGetsEx if you require the handling of null string pointer
values.
StringCbGets can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbGetsA
TCHAR
TEXT("string")
StringCbGets
WCHAR
L"string"
StringCbGetsW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGetsEx
StringCchGets
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCbGetsEx adds to the functionality of StringCbGets by returning a pointer to the end of the destination string as
well as the number of bytes left unused in that string. Flags may also be passed to the function for additional control.
StringCbGetsEx is a replacement for the following functions:
gets, _getws, _getts
StringCbGetsEx is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCbGetsExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which is to receive the input.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be greater than sizeof(TCHAR) for the function to
succeed. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) . If cbDest is too small to hold
the full line of text, the data is truncated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_EN
D_
OF_
FIL
E
DESC RIP T IO N
Data was read from stdin, was copied to the buffer at pszDest,
and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
The value in cbDest is larger than the maximum allowed value
or an invalid flag was passed.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cbDest is 1 or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbGetsEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbGetsEx always null-terminates a nonzerolength destination buffer.
The value of pszDest should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. However, an
error due to insufficient space may still be returned even though NULL values are ignored.
StringCbGetsEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbGetsExA
TCHAR
TEXT("string")
StringCbGetsEx
WCHAR
L"string"
StringCbGetsExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGets
StringCchGetsEx
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCbGetsEx adds to the functionality of StringCbGets by returning a pointer to the end of the destination string as
well as the number of bytes left unused in that string. Flags may also be passed to the function for additional control.
StringCbGetsEx is a replacement for the following functions:
gets, _getws, _getts
StringCbGetsEx is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCbGetsExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which is to receive the input.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be greater than sizeof(TCHAR) for the function to
succeed. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) . If cbDest is too small to hold
the full line of text, the data is truncated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_EN
D_
OF_
FIL
E
DESC RIP T IO N
Data was read from stdin, was copied to the buffer at pszDest,
and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
The value in cbDest is larger than the maximum allowed value
or an invalid flag was passed.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cbDest is 1 or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbGetsEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbGetsEx always null-terminates a nonzerolength destination buffer.
The value of pszDest should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. However, an
error due to insufficient space may still be returned even though NULL values are ignored.
StringCbGetsEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbGetsExA
TCHAR
TEXT("string")
StringCbGetsEx
WCHAR
L"string"
StringCbGetsExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGets
StringCchGetsEx
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCbGets is a replacement for the following functions:
gets, _getws, _getts
StringCbGets is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCbGetsW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the input.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be greater than sizeof(TCHAR) for the function to
succeed. The maximum number of bytes allowed is STRSAFE_MAX_CCH * sizeof(TCHAR) . If cbDest is too small to hold
the full line of text, the data is truncated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
Data was read from stdin, was copied to the buffer at pszDest,
and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
STR
SAF
E_E
_EN
D_
OF_
FIL
E
The value in cbDest is larger than the maximum allowed value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cbDest is
sizeof(TCHAR)
or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbGets provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbGets always null-terminates a nonzerolength destination buffer.
The value of pszDest should not be NULL . See StringCbGetsEx if you require the handling of null string pointer
values.
StringCbGets can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbGetsA
TCHAR
TEXT("string")
StringCbGets
WCHAR
L"string"
StringCbGetsW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGetsEx
StringCchGets
minutes to read • Edit Online
Determines whether a string exceeds the specified length, in bytes.
StringCbLength is a replacement for the following functions:
strlen, wcslen, _tcslen
Syntax
STRSAFEAPI StringCbLengthA(
STRSAFE_PCNZCH psz,
size_t
cbMax,
size_t
*pcbLength
);
Parameters
psz
Type: LPCTSTR
The string whose length is to be checked.
cbMax
Type: size_t
The maximum number of bytes allowed in psz, including those used for the terminating null character. This value
cannot exceed STRSAFE_MAX_CCH * sizeof(TCHAR) .
pcbLength
Type: size_t*
The number of bytes in psz, excluding those used for the terminating null character. This value is valid only if pcb is
not NULL and the function succeeds.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
The string at psz was not NULL , and the length of the string
(including the terminating null character) is less than or equal
to cbMax characters.
The value in psz is NULL , cbMax is larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or psz is longer than
cbMax.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbLength is an additional tool for proper buffer handling in your
code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbLength can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbLengthA
TCHAR
TEXT("string")
StringCbLength
WCHAR
L"string"
StringCbLengthW
UnalignedStringCbLength is an alias for this function.
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
StringCchLength
minutes to read • Edit Online
Determines whether a string exceeds the specified length, in bytes.
StringCbLength is a replacement for the following functions:
strlen, wcslen, _tcslen
Syntax
STRSAFEAPI StringCbLengthW(
STRSAFE_PCNZWCH psz,
size_t
cbMax,
size_t
*pcbLength
);
Parameters
psz
Type: LPCTSTR
The string whose length is to be checked.
cbMax
Type: size_t
The maximum number of bytes allowed in psz, including those used for the terminating null character. This value
cannot exceed STRSAFE_MAX_CCH * sizeof(TCHAR) .
pcbLength
Type: size_t*
The number of bytes in psz, excluding those used for the terminating null character. This value is valid only if pcb is
not NULL and the function succeeds.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
The string at psz was not NULL , and the length of the string
(including the terminating null character) is less than or equal
to cbMax characters.
The value in psz is NULL , cbMax is larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or psz is longer than
cbMax.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbLength is an additional tool for proper buffer handling in your
code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbLength can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbLengthA
TCHAR
TEXT("string")
StringCbLength
WCHAR
L"string"
StringCbLengthW
UnalignedStringCbLength is an alias for this function.
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
StringCchLength
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintf_l is similar to StringCbPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbPrintf_lA(
STRSAFE_LPSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
...
);
pszDest,
cbDest,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintf_lEx is similar to StringCbPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbPrintf_lExA(
STRSAFE_LPSTR
size_t
STRSAFE_LPSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
...
);
pszDest,
cbDest,
*ppszDestEnd,
*pcbRemaining,
dwFlags,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintf_lEx is similar to StringCbPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbPrintf_lExW(
STRSAFE_LPWSTR
size_t
STRSAFE_LPWSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
...
);
pszDest,
cbDest,
*ppszDestEnd,
*pcbRemaining,
dwFlags,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintf_l is similar to StringCbPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbPrintf_lW(
STRSAFE_LPWSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
...
);
pszDest,
cbDest,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintf is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCbPrintfA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPCSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
S_O
K
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbPrintf provides additional processing for proper buffer handling in
your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbPrintf always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbPrintfEx if you require the handling of null string
pointer values.
StringCbPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbPrintfA
TCHAR
TEXT("string")
StringCbPrintf
WCHAR
L"string"
StringCbPrintfW
Examples
The following example shows a basic use of StringCbPrintf , using four arguments.
int const arraysize = 30;
TCHAR pszDest[arraysize];
size_t cbDest = arraysize * sizeof(TCHAR);
LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");
HRESULT hr = StringCbPrintf(pszDest, cbDest, pszFormat, pszTxt, 1, 2, 3);
// The resultant string at pszDest is "The answer is 1 + 2 = 3."
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintfEx
StringCbVPrintf
StringCchPrintf
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintfEx adds to the functionality of StringCbPrintf by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbPrintfEx is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCbPrintfExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags,
STRSAFE_LPCSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbPrintfEx provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbPrintfEx always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCbPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbPrintfExA
TCHAR
TEXT("string")
StringCbPrintfEx
WCHAR
L"string"
StringCbPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbVPrintfEx
StringCchPrintf
StringCchPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintfEx adds to the functionality of StringCbPrintf by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbPrintfEx is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCbPrintfExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags,
STRSAFE_LPCWSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbPrintfEx provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbPrintfEx always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCbPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbPrintfExA
TCHAR
TEXT("string")
StringCbPrintfEx
WCHAR
L"string"
StringCbPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbVPrintfEx
StringCchPrintf
StringCchPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCbPrintf is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCbPrintfW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPCWSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
S_O
K
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCbPrintf provides additional processing for proper buffer handling in
your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCbPrintf always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbPrintfEx if you require the handling of null string
pointer values.
StringCbPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbPrintfA
TCHAR
TEXT("string")
StringCbPrintf
WCHAR
L"string"
StringCbPrintfW
Examples
The following example shows a basic use of StringCbPrintf , using four arguments.
int const arraysize = 30;
TCHAR pszDest[arraysize];
size_t cbDest = arraysize * sizeof(TCHAR);
LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");
HRESULT hr = StringCbPrintf(pszDest, cbDest, pszFormat, pszTxt, 1, 2, 3);
// The resultant string at pszDest is "The answer is 1 + 2 = 3."
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintfEx
StringCbVPrintf
StringCchPrintf
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintf_l is similar to StringCbVPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbVPrintf_lA(
STRSAFE_LPSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
va_list
);
pszDest,
cbDest,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbVPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintf_lEx is similar to StringCbVPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbVPrintf_lExA(
STRSAFE_LPSTR
size_t
STRSAFE_LPSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
va_list
);
pszDest,
cbDest,
*ppszDestEnd,
*pcbRemaining,
dwFlags,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There is sufficient space for the result to be copied to pszDest
without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintf_lEx is similar to StringCbVPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbVPrintf_lExW(
STRSAFE_LPWSTR
size_t
STRSAFE_LPWSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
va_list
);
pszDest,
cbDest,
*ppszDestEnd,
*pcbRemaining,
dwFlags,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There is sufficient space for the result to be copied to pszDest
without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintf_l is similar to StringCbVPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCbVPrintf_lW(
STRSAFE_LPWSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
va_list
);
pszDest,
cbDest,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbVPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintf is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCbVPrintfA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPCSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
S_O
K
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbVPrintf provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbVPrintf always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbVPrintfEx if you require the handling of null string
pointer values.
StringCbVPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbVPrintfA
TCHAR
TEXT("string")
StringCbVPrintf
WCHAR
L"string"
StringCbVPrintfW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintf
StringCbVPrintfEx
StringCchVPrintf
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintfEx adds to the functionality of StringCbVPrintf by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbVPrintfEx is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCbVPrintfExA(
STRSAFE_LPSTR pszDest,
size_t
cbDest,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags,
STRSAFE_LPCSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There is sufficient space for the result to be copied to pszDest
without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbVPrintfEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbVPrintfEx always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCbVPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbVPrintfExA
TCHAR
TEXT("string")
StringCbVPrintfEx
WCHAR
L"string"
StringCbVPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintfEx
StringCbVPrintf
StringCchVPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintfEx adds to the functionality of StringCbVPrintf by returning a pointer to the end of the destination
string as well as the number of bytes left unused in that string. Flags may also be passed to the function for
additional control.
StringCbVPrintfEx is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCbVPrintfExW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcbRemaining,
DWORD
dwFlags,
STRSAFE_LPCWSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcbRemaining
Type: size_t*
The number of unused bytes in pszDest, including those used for the terminating null character. If pcbRemaining is
NULL , the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There is sufficient space for the result to be copied to pszDest
without truncation, and the buffer is null-terminated.
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) , or the destination
buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbVPrintfEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbVPrintfEx always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCbVPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbVPrintfExA
TCHAR
TEXT("string")
StringCbVPrintfEx
WCHAR
L"string"
StringCbVPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintfEx
StringCbVPrintf
StringCchVPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCbVPrintf is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCbVPrintfW(
STRSAFE_LPWSTR pszDest,
size_t
cbDest,
STRSAFE_LPCWSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cbDest
Type: size_t
The size of the destination buffer, in bytes. This value must be sufficiently large to accommodate the final formatted
string plus the terminating null character. The maximum number of bytes allowed is
STRSAFE_MAX_CCH * sizeof(TCHAR) .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
S_O
K
The value in cbDest is either 0 or larger than
STRSAFE_MAX_CCH * sizeof(TCHAR) .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCbVPrintf provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCbVPrintf always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCbVPrintfEx if you require the handling of null string
pointer values.
StringCbVPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCbVPrintfA
TCHAR
TEXT("string")
StringCbVPrintf
WCHAR
L"string"
StringCbVPrintfW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintf
StringCbVPrintfEx
StringCchVPrintf
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that StringCchCat does not write past the end of this buffer.
StringCchCat is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCchCatA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPCSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string to which pszSrc is to be concatenated, and that will receive the
entire resultant string. The string at pszSrc is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be greater than or equal the length of pszSrc plus
the length of pszDest plus 1 to account for both strings and the terminating null character. The maximum number
of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCat provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchCat always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCatEx if you require the handling of null string pointer
values.
StringCchCat can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatA
TCHAR
TEXT("string")
StringCchCat
WCHAR
L"string"
StringCchCatW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCat
StringCchCatEx
StringCchCatN
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchCatEx adds to the functionality of StringCchCat by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to the function for
additional control.
StringCchCatEx is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCchCatExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPCSTR pszSrc,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatened to pszSrc, and that will receive the entire
resultant string. The string at pszSrc is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus the length of
pszDest plus 1 to account for both strings and the terminating null character. The maximum number of characters
allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCatEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchCatEx always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCatEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatExA
TCHAR
TEXT("string")
StringCchCatEx
WCHAR
L"string"
StringCchCatExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatEx
StringCchCat
StringCchCatNEx
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchCatEx adds to the functionality of StringCchCat by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to the function for
additional control.
StringCchCatEx is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCchCatExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPCWSTR pszSrc,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatened to pszSrc, and that will receive the entire
resultant string. The string at pszSrc is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus the length of
pszDest plus 1 to account for both strings and the terminating null character. The maximum number of characters
allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCatEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchCatEx always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCatEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatExA
TCHAR
TEXT("string")
StringCchCatEx
WCHAR
L"string"
StringCchCatExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatEx
StringCchCat
StringCchCatNEx
minutes to read • Edit Online
Concatenates the specified number of characters from one string to another string. The size of the destination
buffer is provided to the function to ensure that it does not write past the end of this buffer.
StringCchCatN is a replacement for the following functions:
strncat
StrNCat
Syntax
STRSAFEAPI StringCchCatNA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZCH pszSrc,
size_t
cchToAppend
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated with pszSrc, and will receive the entire
resultant string. The string at pszSrc, up to cchMaxAppend characters, is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus either the length of
pszDest or cchMaxAppend (whichever is smaller). To this sum add 1 to account for the terminating null character.
The maximum number of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is concatenated to the end of pszDest. This string must be null-terminated.
cchToAppend
Type: size_t
The maximum number of characters to be appended to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cchDest is either larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCatN provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCatN always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCatNEx if you require the handling of null string pointer
values.
StringCchCatN can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatNA
TCHAR
TEXT("string")
StringCchCatN
WCHAR
L"string"
StringCchCatNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatN
StringCchCat
StringCchCatNEx
minutes to read • Edit Online
Concatenates the specified number of characters from one string to another string. The size of the destination
buffer is provided to the function to ensure that it does not write past the end of this buffer.
StringCchCatNEx adds to the functionality of StringCchCatN by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to the function for
additional control.
StringCchCatNEx is a replacement for the following functions:
strncat
StrNCat
Syntax
STRSAFEAPI StringCchCatNExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZCH pszSrc,
size_t
cchToAppend,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated with pszSrc, and will receive the entire
resultant string. The string at pszSrc is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus the length of
pszDest plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is concatenated to the end of pszDest. This string must be null-terminated.
cchToAppend
Type: size_t
The maximum number of characters to be appended to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cchDest is larger than STRSAFE_MAX_CCH , an
invalid flag was passed, or there are discrepancies between the
size of the pszDest, cchDest, and the amount of material to
append in pszSrc.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCatNEx provides additional processing for proper buffer
handling in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCatNEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCatNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatNExA
TCHAR
TEXT("string")
StringCchCatNEx
WCHAR
L"string"
StringCchCatNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatNEx
StringCchCatEx
StringCchCatN
minutes to read • Edit Online
Concatenates the specified number of characters from one string to another string. The size of the destination
buffer is provided to the function to ensure that it does not write past the end of this buffer.
StringCchCatNEx adds to the functionality of StringCchCatN by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to the function for
additional control.
StringCchCatNEx is a replacement for the following functions:
strncat
StrNCat
Syntax
STRSAFEAPI StringCchCatNExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cchToAppend,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated with pszSrc, and will receive the entire
resultant string. The string at pszSrc is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus the length of
pszDest plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is concatenated to the end of pszDest. This string must be null-terminated.
cchToAppend
Type: size_t
The maximum number of characters to be appended to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is appended to the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any pre-existing or truncated string in the destination buffer is
overwritten.
If the function fails, pszDest is untouched. Nothing is added to
the original contents.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cchDest is larger than STRSAFE_MAX_CCH , an
invalid flag was passed, or there are discrepancies between the
size of the pszDest, cchDest, and the amount of material to
append in pszSrc.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCatNEx provides additional processing for proper buffer
handling in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCatNEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCatNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatNExA
TCHAR
TEXT("string")
StringCchCatNEx
WCHAR
L"string"
StringCchCatNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatNEx
StringCchCatEx
StringCchCatN
minutes to read • Edit Online
Concatenates the specified number of characters from one string to another string. The size of the destination
buffer is provided to the function to ensure that it does not write past the end of this buffer.
StringCchCatN is a replacement for the following functions:
strncat
StrNCat
Syntax
STRSAFEAPI StringCchCatNW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cchToAppend
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string that is to be concatenated with pszSrc, and will receive the entire
resultant string. The string at pszSrc, up to cchMaxAppend characters, is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus either the length of
pszDest or cchMaxAppend (whichever is smaller). To this sum add 1 to account for the terminating null character.
The maximum number of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is concatenated to the end of pszDest. This string must be null-terminated.
cchToAppend
Type: size_t
The maximum number of characters to be appended to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
Source data was present, the strings were concatenated
without truncation, and the resultant destination buffer is nullterminated.
The value in cchDest is either larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCatN provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCatN always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCatNEx if you require the handling of null string pointer
values.
StringCchCatN can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatNA
TCHAR
TEXT("string")
StringCchCatN
WCHAR
L"string"
StringCchCatNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCatN
StringCchCat
StringCchCatNEx
minutes to read • Edit Online
Concatenates one string to another string. The size of the destination buffer is provided to the function to ensure
that StringCchCat does not write past the end of this buffer.
StringCchCat is a replacement for the following functions:
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
Syntax
STRSAFEAPI StringCchCatW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPCWSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which contains the string to which pszSrc is to be concatenated, and that will receive the
entire resultant string. The string at pszSrc is added to the end of the string at pszDest.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be greater than or equal the length of pszSrc plus
the length of pszDest plus 1 to account for both strings and the terminating null character. The maximum number
of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string that is to be concatenated to the end of pszDest. This string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the strings were fully concatenated
without truncation, and the resultant destination buffer is nullterminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The concatenation operation failed due to insufficient buffer
space. The destination buffer contains a truncated, nullterminated version of the intended result. In situations where
truncation is acceptable, this may not necessarily be seen as a
failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCat provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchCat always null-terminates and never
overflows a valid destination buffer, even if the contents of the source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCatEx if you require the handling of null string pointer
values.
StringCchCat can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCatA
TCHAR
TEXT("string")
StringCchCat
WCHAR
L"string"
StringCchCatW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCat
StringCchCatEx
StringCchCatN
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of this buffer.
StringCchCopy is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCchCopyA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPCSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus 1 to account for the
copied source string and the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCopy provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCopy always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCopyEx if you require the handling of null string pointer
values.
StringCchCopy can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyA
TCHAR
TEXT("string")
StringCchCopy
WCHAR
L"string"
StringCchCopyW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopy
StringCchCopyEx
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of the buffer.
StringCchCopyEx adds to the functionality of StringCchCopy by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to this function for
additional control.
StringCchCopyEx is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCchCopyExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPCSTR pszSrc,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus 1 to account for the
copied source string and the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
It is strongly recommended that you use the SUCCEEDED and FAILED macros to test the return value of this
function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest is NULL when there is source data present to
copy, or an invalid flag was passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCopyEx provides additional processing for proper buffer
handling in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCopyEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCopyEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyExA
TCHAR
TEXT("string")
StringCchCopyEx
WCHAR
L"string"
StringCchCopyExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyEx
StringCchCopy
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of the buffer.
StringCchCopyEx adds to the functionality of StringCchCopy by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to this function for
additional control.
StringCchCopyEx is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCchCopyExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPCWSTR pszSrc,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus 1 to account for the
copied source string and the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
It is strongly recommended that you use the SUCCEEDED and FAILED macros to test the return value of this
function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest is NULL when there is source data present to
copy, or an invalid flag was passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCopyEx provides additional processing for proper buffer
handling in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCopyEx always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCopyEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyExA
TCHAR
TEXT("string")
StringCchCopyEx
WCHAR
L"string"
StringCchCopyExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyEx
StringCchCopy
minutes to read • Edit Online
Copies the specified number of characters from one string to another. The size of the destination buffer is provided
to the function to ensure that StringCchCopyN does not write past the end of this buffer.
StringCchCopyN is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCchCopyNA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZCH pszSrc,
size_t
cchToCopy
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cchDest
Type: size_t
The size of pszDest, in characters. This value must be large enough to hold the copied characters (the length of
pszSrc or the value of cchSrc, whichever is smaller) plus 1 to account for the terminating null character. The
maximum number of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. This string must be readable up to cchSrc characters or a null terminator, whichever comes first.
cchToCopy
Type: size_t
The maximum number of characters to be copied from pszSrc to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the characters were copied from
pszSrc without truncation, and the resultant destination buffer
is null-terminated.
S_O
K
The value in cchDest is either larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCopyN provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchCopyN always null-terminates and
never overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cchSrc is larger than
the number of characters in pszSrc, StringCchCopyN —unlike strncpy —does not continue to pad pszDest with
null characters until cchSrc characters have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCopyNEx if you require the handling of null string
pointer values.
StringCchCopyN can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyNA
TCHAR
TEXT("string")
StringCchCopyN
WCHAR
L"string"
StringCchCopyNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyN
StringCchCopy
StringCchCopyNEx
minutes to read • Edit Online
Copies the specified number of characters from one string to another. The size of the destination buffer is provided
to the function to ensure that it does not write past the end of this buffer.
StringCchCopyNEx adds to the functionality of StringCchCopyN by returning a pointer to the end of the
destination string as well as the number of characters left unused in that string. Flags may also be passed to the
function for additional control.
StringCchCopyNEx is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCchCopyNExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZCH pszSrc,
size_t
cchToCopy,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cchDest
Type: size_t
The size of pszDest, in characters. This value must be at least large enough to hold the copied characters (the length
of pszSrc or the value of cchSrc, whichever is smaller) plus 1 to account for the terminating null character. The
maximum number of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. TThis string must be readable up to cchSrc characters or a null terminator, whichever comes first.
cchToCopy
Type: size_t
The maximum number of characters to be copied from pszSrc to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest or pszSrc is greater than STRSAFE_MAX_CCH ,
pszDest is NULL when there is source data present to copy, or
an invalid flag was passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCopyNEx provides additional processing for proper buffer handling in your code. Poor buffer handling
is implicated in many security issues that involve buffer overruns. StringCchCopyNEx always null-terminates and
never overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cchSrc is larger than
the number of characters in pszSrc, StringCchCopyNEx —unlike strncpy —does not continue to pad pszDest with
null characters until cchSrc characters have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCopyNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyNExA
TCHAR
TEXT("string")
StringCchCopyNEx
WCHAR
L"string"
StringCchCopyNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyNEx
StringCchCopyN
minutes to read • Edit Online
Copies the specified number of characters from one string to another. The size of the destination buffer is provided
to the function to ensure that it does not write past the end of this buffer.
StringCchCopyNEx adds to the functionality of StringCchCopyN by returning a pointer to the end of the
destination string as well as the number of characters left unused in that string. Flags may also be passed to the
function for additional control.
StringCchCopyNEx is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCchCopyNExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cchToCopy,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cchDest
Type: size_t
The size of pszDest, in characters. This value must be at least large enough to hold the copied characters (the length
of pszSrc or the value of cchSrc, whichever is smaller) plus 1 to account for the terminating null character. The
maximum number of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. TThis string must be readable up to cchSrc characters or a null terminator, whichever comes first.
cchToCopy
Type: size_t
The maximum number of characters to be copied from pszSrc to pszDest.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
Either pszDest or pszSrc is greater than STRSAFE_MAX_CCH ,
pszDest is NULL when there is source data present to copy, or
an invalid flag was passed.
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCopyNEx provides additional processing for proper buffer handling in your code. Poor buffer handling
is implicated in many security issues that involve buffer overruns. StringCchCopyNEx always null-terminates and
never overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cchSrc is larger than
the number of characters in pszSrc, StringCchCopyNEx —unlike strncpy —does not continue to pad pszDest with
null characters until cchSrc characters have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which case
both may be NULL . However, an error due to insufficient space may still be returned even though NULL values are
ignored.
StringCchCopyNEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyNExA
TCHAR
TEXT("string")
StringCchCopyNEx
WCHAR
L"string"
StringCchCopyNExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyNEx
StringCchCopyN
minutes to read • Edit Online
Copies the specified number of characters from one string to another. The size of the destination buffer is provided
to the function to ensure that StringCchCopyN does not write past the end of this buffer.
StringCchCopyN is a replacement for the following functions:
strncpy, wcsncpy, _tcsncpy
Syntax
STRSAFEAPI StringCchCopyNW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_PCNZWCH pszSrc,
size_t
cchToCopy
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cchDest
Type: size_t
The size of pszDest, in characters. This value must be large enough to hold the copied characters (the length of
pszSrc or the value of cchSrc, whichever is smaller) plus 1 to account for the terminating null character. The
maximum number of characters allowed is STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. This string must be readable up to cchSrc characters or a null terminator, whichever comes first.
cchToCopy
Type: size_t
The maximum number of characters to be copied from pszSrc to pszDest.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, the characters were copied from
pszSrc without truncation, and the resultant destination buffer
is null-terminated.
S_O
K
The value in cchDest is either larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchCopyN provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchCopyN always null-terminates and
never overflows a valid destination buffer, even if the contents of the source string change during the operation.
While this routine is meant as a replacement for strncpy, there are differences in behavior. If cchSrc is larger than
the number of characters in pszSrc, StringCchCopyN —unlike strncpy —does not continue to pad pszDest with
null characters until cchSrc characters have been copied.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCopyNEx if you require the handling of null string
pointer values.
StringCchCopyN can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyNA
TCHAR
TEXT("string")
StringCchCopyN
WCHAR
L"string"
StringCchCopyNW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopyN
StringCchCopy
StringCchCopyNEx
minutes to read • Edit Online
Copies one string to another. The size of the destination buffer is provided to the function to ensure that it does not
write past the end of this buffer.
StringCchCopy is a replacement for the following functions:
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
Syntax
STRSAFEAPI StringCchCopyW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPCWSTR pszSrc
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied string.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must equal the length of pszSrc plus 1 to account for the
copied source string and the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszSrc
Type: LPCTSTR
The source string. This string must be null-terminated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
Source data was present, fully copied without truncation, and
the resultant destination buffer is null-terminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchCopy provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchCopy always null-terminates and never overflows a valid destination buffer, even if the contents of the
source string change during the operation.
Behavior is undefined if the strings pointed to by pszSrc and pszDest overlap.
Neither pszSrc nor pszDest should be NULL . See StringCchCopyEx if you require the handling of null string pointer
values.
StringCchCopy can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchCopyA
TCHAR
TEXT("string")
StringCchCopy
WCHAR
L"string"
StringCchCopyW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbCopy
StringCchCopyEx
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCchGets is a replacement for the following functions:
gets, _getws, _getts
StringCchGets is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCchGetsA(
STRSAFE_LPSTR pszDest,
size_t
cchDest
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be at least 2 for the function to succeed. The
maximum number of characters allowed, including the terminating null character, is STRSAFE_MAX_CCH . If
cchDest is too small to hold the full line of text, the data is truncated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
Characters were read from stdin, were copied to the buffer at
pszDest, and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
STR
SAF
E_E
_EN
D_
OF_
FIL
E
The value in cchDest is larger than the maximum allowed
value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cchDest is 1 or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchGets provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchGets always null-terminates a nonzerolength destination buffer.
The value of pszDest should not be NULL . See StringCchGetsEx if you require the handling of null string pointer
values.
StringCchGets can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchGetsA
TCHAR
TEXT("string")
StringCchGets
WCHAR
L"string"
StringCchGetsW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGets
StringCchGetsEx
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCchGetsEx adds to the functionality of StringCchGets by returning a pointer to the end of the destination string
as well as the number of characters left unused in that string. Flags may also be passed to the function for additional
control.
StringCchGetsEx is a replacement for the following functions:
gets, _getws, _getts
StringCchGetsEx is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCchGetsExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be at least 2 for the function to succeed. The
maximum number of characters allowed, including the terminating null character, is STRSAFE_MAX_CCH . If
cchDest is too small to hold the full line of text, the data is truncated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE, if the function
fails, pszDest is set to an empty string (TEXT("")). In the case of
a STRSAFE_E_INSUFFICIENT_BUFFER failure, any truncated
string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_EN
D_
OF_
FIL
E
DESC RIP T IO N
Characters were read from stdin, were copied to the buffer at
pszDest, and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
The value in cchDest is larger than the maximum allowed value
or an invalid flag was passed.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cchDest is 1 or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchGetsEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchGetsEx always null-terminates a
nonzero-length destination buffer.
The value of pszDest should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. However, an
error due to insufficient space may still be returned even though NULL values are ignored.
StringCchGetsEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchGetsExA
TCHAR
TEXT("string")
StringCchGetsEx
WCHAR
L"string"
StringCchGetsExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGetsEx
StringCchGets
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCchGetsEx adds to the functionality of StringCchGets by returning a pointer to the end of the destination string
as well as the number of characters left unused in that string. Flags may also be passed to the function for additional
control.
StringCchGetsEx is a replacement for the following functions:
gets, _getws, _getts
StringCchGetsEx is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCchGetsExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be at least 2 for the function to succeed. The
maximum number of characters allowed, including the terminating null character, is STRSAFE_MAX_CCH . If
cchDest is too small to hold the full line of text, the data is truncated.
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")). This
flag is useful for emulating functions such as lstrcpy.
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE, if the function
fails, pszDest is set to an empty string (TEXT("")). In the case of
a STRSAFE_E_INSUFFICIENT_BUFFER failure, any truncated
string is overwritten.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_EN
D_
OF_
FIL
E
DESC RIP T IO N
Characters were read from stdin, were copied to the buffer at
pszDest, and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
The value in cchDest is larger than the maximum allowed value
or an invalid flag was passed.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cchDest is 1 or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchGetsEx provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchGetsEx always null-terminates a
nonzero-length destination buffer.
The value of pszDest should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. However, an
error due to insufficient space may still be returned even though NULL values are ignored.
StringCchGetsEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchGetsExA
TCHAR
TEXT("string")
StringCchGetsEx
WCHAR
L"string"
StringCchGetsExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGetsEx
StringCchGets
minutes to read • Edit Online
Gets one line of text from stdin, up to and including the newline character ('\n'). The line of text is copied to the
destination buffer, and the newline character is replaced with a null character. The size of the destination buffer is
provided to the function to ensure that it does not write past the end of this buffer.
Note This function can only be used inline.
StringCchGets is a replacement for the following functions:
gets, _getws, _getts
StringCchGets is not a replacement for fgets , which does not replace newline characters with a terminating null
character.
Syntax
STRSAFEAPI StringCchGetsW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the copied characters.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be at least 2 for the function to succeed. The
maximum number of characters allowed, including the terminating null character, is STRSAFE_MAX_CCH . If
cchDest is too small to hold the full line of text, the data is truncated.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
Characters were read from stdin, were copied to the buffer at
pszDest, and the buffer was null-terminated.
Indicates an error or end-of-file condition. Use feof or ferror to
determine which one has occurred.
STR
SAF
E_E
_EN
D_
OF_
FIL
E
The value in cchDest is larger than the maximum allowed
value.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The value in cchDest is 1 or less.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchGets provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchGets always null-terminates a nonzerolength destination buffer.
The value of pszDest should not be NULL . See StringCchGetsEx if you require the handling of null string pointer
values.
StringCchGets can be used in its generic form, or in its more specific forms. The data type of the string determines
the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchGetsA
TCHAR
TEXT("string")
StringCchGets
WCHAR
L"string"
StringCchGetsW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbGets
StringCchGetsEx
minutes to read • Edit Online
Determines whether a string exceeds the specified length, in characters.
StringCchLength is a replacement for the following functions:
strlen, wcslen, _tcslen
Syntax
STRSAFEAPI StringCchLengthA(
STRSAFE_PCNZCH psz,
size_t
cchMax,
size_t
*pcchLength
);
Parameters
psz
Type: LPCTSTR
The string whose length is to be checked.
cchMax
Type: size_t
The maximum number of characters allowed in psz, including the terminating null character. This value cannot
exceed STRSAFE_MAX_CCH .
pcchLength
Type: size_t*
The number of characters in psz, not including the terminating null character. This value is valid only if pcch is not
NULL and the function succeeds.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
The string at psz was not NULL , and the length of the string
(including the terminating null character) is less than or equal
to cchMax characters.
The value in psz is NULL , cchMax is larger than
STRSAFE_MAX_CCH , or psz is longer than cchMax.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchLength is an additional tool for proper buffer handling in your
code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchLength can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchLengthA
TCHAR
TEXT("string")
StringCchLength
WCHAR
L"string"
StringCchLengthW
UnalignedStringCchLength is an alias for this function.
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
StringCbLength
minutes to read • Edit Online
Determines whether a string exceeds the specified length, in characters.
StringCchLength is a replacement for the following functions:
strlen, wcslen, _tcslen
Syntax
STRSAFEAPI StringCchLengthW(
STRSAFE_PCNZWCH psz,
size_t
cchMax,
size_t
*pcchLength
);
Parameters
psz
Type: LPCTSTR
The string whose length is to be checked.
cchMax
Type: size_t
The maximum number of characters allowed in psz, including the terminating null character. This value cannot
exceed STRSAFE_MAX_CCH .
pcchLength
Type: size_t*
The number of characters in psz, not including the terminating null character. This value is valid only if pcch is not
NULL and the function succeeds.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
S_O
K
The string at psz was not NULL , and the length of the string
(including the terminating null character) is less than or equal
to cchMax characters.
The value in psz is NULL , cchMax is larger than
STRSAFE_MAX_CCH , or psz is longer than cchMax.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchLength is an additional tool for proper buffer handling in your
code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchLength can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchLengthA
TCHAR
TEXT("string")
StringCchLength
WCHAR
L"string"
StringCchLengthW
UnalignedStringCchLength is an alias for this function.
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
StringCbLength
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintf_l is similar to StringCchPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchPrintf_lA(
STRSAFE_LPSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
...
);
pszDest,
cchDest,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintf_lEx is similar to StringCchPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchPrintf_lExA(
STRSAFE_LPSTR
size_t
STRSAFE_LPSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
...
);
pszDest,
cchDest,
*ppszDestEnd,
*pcchRemaining,
dwFlags,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The Arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintf_lEx is similar to StringCchPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchPrintf_lExW(
STRSAFE_LPWSTR
size_t
STRSAFE_LPWSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
...
);
pszDest,
cchDest,
*ppszDestEnd,
*pcchRemaining,
dwFlags,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The Arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintf_l is similar to StringCchPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchPrintf_lW(
STRSAFE_LPWSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
...
);
pszDest,
cchDest,
pszFormat,
locale,
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
...
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintf is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCchPrintfA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPCSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchPrintf provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchPrintf always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchPrintfEx if you require the handling of null string
pointer values.
StringCchPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchPrintfA
TCHAR
TEXT("string")
StringCchPrintf
WCHAR
L"string"
StringCchPrintfW
Examples
The following example shows a simple use of StringCchPrintf , using four arguments.
TCHAR pszDest[30];
size_t cchDest = 30;
LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");
HRESULT hr = StringCchPrintf(pszDest, cchDest, pszFormat, pszTxt, 1, 2, 3);
// The resultant string at pszDest is "The answer is 1 + 2 = 3."
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintf
StringCchPrintfEx
StringCchVPrintf
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintfEx adds to the functionality of StringCchPrintf by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to the function for
additional control.
StringCchPrintfEx is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCchPrintfExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags,
STRSAFE_LPCSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The Arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchPrintfEx provides additional processing for proper buffer
handling in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchPrintfEx always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCchPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchPrintfExA
TCHAR
TEXT("string")
StringCchPrintfEx
WCHAR
L"string"
StringCchPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintfEx
StringCchPrintf
StringCchVPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintfEx adds to the functionality of StringCchPrintf by returning a pointer to the end of the destination
string as well as the number of characters left unused in that string. Flags may also be passed to the function for
additional control.
StringCchPrintfEx is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCchPrintfExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags,
STRSAFE_LPCWSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The Arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchPrintfEx provides additional processing for proper buffer
handling in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchPrintfEx always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCchPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchPrintfExA
TCHAR
TEXT("string")
StringCchPrintfEx
WCHAR
L"string"
StringCchPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintfEx
StringCchPrintf
StringCchVPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string. The size of the destination buffer is provided to the function to ensure
that it does not write past the end of this buffer.
StringCchPrintf is a replacement for the following functions:
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
Syntax
STRSAFEAPI StringCchPrintfW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPCWSTR pszFormat,
...
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and its
arguments.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
...
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation, and the buffer is null-terminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
Compared to the functions it replaces, StringCchPrintf provides additional processing for proper buffer handling
in your code. Poor buffer handling is implicated in many security issues that involve buffer overruns.
StringCchPrintf always null-terminates a nonzero-length destination buffer.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchPrintfEx if you require the handling of null string
pointer values.
StringCchPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchPrintfA
TCHAR
TEXT("string")
StringCchPrintf
WCHAR
L"string"
StringCchPrintfW
Examples
The following example shows a simple use of StringCchPrintf , using four arguments.
TCHAR pszDest[30];
size_t cchDest = 30;
LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");
HRESULT hr = StringCchPrintf(pszDest, cchDest, pszFormat, pszTxt, 1, 2, 3);
// The resultant string at pszDest is "The answer is 1 + 2 = 3."
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbPrintf
StringCchPrintfEx
StringCchVPrintf
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintf_l is similar to StringCchVPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchVPrintf_lA(
STRSAFE_LPSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
va_list
);
pszDest,
cchDest,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchVPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintf_lEx is similar to StringCchVPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchVPrintf_lExA(
STRSAFE_LPSTR
size_t
STRSAFE_LPSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCSTR
_locale_t
va_list
);
pszDest,
cchDest,
*ppszDestEnd,
*pcchRemaining,
dwFlags,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintf_lEx is similar to StringCchVPrintfEx but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchVPrintf_lExW(
STRSAFE_LPWSTR
size_t
STRSAFE_LPWSTR
size_t
DWORD
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
va_list
);
pszDest,
cchDest,
*ppszDestEnd,
*pcchRemaining,
dwFlags,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
One or more of the following values.
VA L UE
M EA N IN G
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintf_l is similar to StringCchVPrintf but includes a parameter for locale information.
Syntax
STRSAFEAPI StringCchVPrintf_lW(
STRSAFE_LPWSTR
size_t
_Printf_format_string_params_(2)STRSAFE_LPCWSTR
_locale_t
va_list
);
pszDest,
cchDest,
pszFormat,
locale,
argList
Parameters
pszDest
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
locale
The locale object. For more information, see _create_locale .
argList
The arguments to be inserted into the pszFormat string.
Return value
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
Remarks
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchVPrintf_lEx if you require the handling of null string
pointer values.
In order to use this function, you must define the following macro in your header file, before including StrSafe.h.
#define STRSAFE_LOCALE_FUNCTIONS
Requirements
Minimum suppor ted client
Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintf is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCchVPrintfA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPCSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchVPrintf provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchVPrintf always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchVPrintfEx if you require the handling of null string
pointer values.
StringCchVPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchVPrintfA
TCHAR
TEXT("string")
StringCchVPrintf
WCHAR
L"string"
StringCchVPrintfW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbVPrintf
StringCchPrintf
StringCchVPrintfEx
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintfEx adds to the functionality of StringCchVPrintf by returning a pointer to the end of the
destination string as well as the number of characters left unused in that string. Flags may also be passed to the
function for additional control.
StringCchVPrintfEx is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCchVPrintfExA(
STRSAFE_LPSTR pszDest,
size_t
cchDest,
STRSAFE_LPSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags,
STRSAFE_LPCSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchVPrintfEx provides additional processing for proper buffer handling in your code. Poor buffer handling
is implicated in many security issues that involve buffer overruns. StringCchVPrintfEx always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCchVPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchVPrintfExA
TCHAR
TEXT("string")
StringCchVPrintfEx
WCHAR
L"string"
StringCchVPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbVPrintfEx
StringCchPrintfEx
StringCchVPrintf
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintfEx adds to the functionality of StringCchVPrintf by returning a pointer to the end of the
destination string as well as the number of characters left unused in that string. Flags may also be passed to the
function for additional control.
StringCchVPrintfEx is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCchVPrintfExW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPWSTR *ppszDestEnd,
size_t
*pcchRemaining,
DWORD
dwFlags,
STRSAFE_LPCWSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
ppszDestEnd
Type: LPTSTR*
The address of a pointer to the end of pszDest. If ppszDestEnd is non-NULL and any data is copied into the
destination buffer, this points to the terminating null character at the end of the string.
pcchRemaining
Type: size_t*
The number of unused characters in pszDest, including the terminating null character. If pcchRemaining is NULL ,
the count is not kept or returned.
dwFlags
Type: DWORD
One or more of the following values.
VA L UE
STR
SAF
E_FI
LL_
BEH
IND
_N
ULL
0x0
000
020
0
M EA N IN G
If the function succeeds, the low byte of dwFlags (0) is used to
fill the uninitialized portion of pszDest following the
terminating null character.
Treat NULL string pointers like empty strings (TEXT("")).
STR
SAF
E_I
GN
OR
E_N
ULL
S
0x0
000
010
0
STR
SAF
E_FI
LL_
ON
_FA
ILU
RE
0x0
000
040
0
If the function fails, the low byte of dwFlags (0) is used to fill
the entire pszDest buffer, and the buffer is null-terminated. In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string returned is overwritten.
STR
SAF
E_N
ULL
_O
N_F
AIL
URE
0x0
000
080
0
STR
SAF
E_N
O_T
RU
NC
ATI
ON
0x0
000
100
0
If the function fails, pszDest is set to an empty string (TEXT("")).
In the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
As in the case of STRSAFE_NULL_ON_FAILURE , if the
function fails, pszDest is set to an empty string (TEXT("")). In
the case of a STRSAFE_E_INSUFFICIENT_BUFFER failure,
any truncated string is overwritten.
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
S_O
K
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH , or the destination buffer is already full.
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space.
Depending on the value of dwFlags, the destination buffer
may contain a truncated, null-terminated version of the
intended result. In situations where truncation is acceptable,
this may not necessarily be seen as a failure condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchVPrintfEx provides additional processing for proper buffer handling in your code. Poor buffer handling
is implicated in many security issues that involve buffer overruns. StringCchVPrintfEx always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL unless the STRSAFE_IGNORE_NULLS flag is specified, in which
case both may be NULL . However, an error due to insufficient space may still be returned even though NULL
values are ignored.
StringCchVPrintfEx can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchVPrintfExA
TCHAR
TEXT("string")
StringCchVPrintfEx
WCHAR
L"string"
StringCchVPrintfExW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbVPrintfEx
StringCchPrintfEx
StringCchVPrintf
minutes to read • Edit Online
Writes formatted data to the specified string using a pointer to a list of arguments. The size of the destination buffer
is provided to the function to ensure that it does not write past the end of this buffer.
StringCchVPrintf is a replacement for the following functions:
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
Syntax
STRSAFEAPI StringCchVPrintfW(
STRSAFE_LPWSTR pszDest,
size_t
cchDest,
STRSAFE_LPCWSTR pszFormat,
va_list
argList
);
Parameters
pszDest
Type: LPTSTR
The destination buffer, which receives the formatted, null-terminated string created from pszFormat and argList.
cchDest
Type: size_t
The size of the destination buffer, in characters. This value must be sufficiently large to accommodate the final
formatted string plus 1 to account for the terminating null character. The maximum number of characters allowed is
STRSAFE_MAX_CCH .
pszFormat
Type: LPCTSTR
The format string. This string must be null-terminated. For more information, see Format Specification Syntax.
argList
Type: va_list
The arguments to be inserted into the pszFormat string.
Return value
Type: HRESULT
This function can return one of the following values. It is strongly recommended that you use the SUCCEEDED and
FAILED macros to test the return value of this function.
RET URN C O DE
DESC RIP T IO N
There was sufficient space for the result to be copied to
pszDest without truncation and the buffer is null-terminated.
S_O
K
The value in cchDest is either 0 or larger than
STRSAFE_MAX_CCH .
STR
SAF
E_E
_IN
VAL
ID_
PAR
AM
ETE
R
The copy operation failed due to insufficient buffer space. The
destination buffer contains a truncated, null-terminated
version of the intended result. In situations where truncation is
acceptable, this may not necessarily be seen as a failure
condition.
STR
SAF
E_E
_IN
SUF
FICI
ENT
_BU
FFE
R
Note that this function returns an HRESULT value, unlike the functions that it replaces.
Remarks
StringCchVPrintf provides additional processing for proper buffer handling in your code. Poor buffer handling is
implicated in many security issues that involve buffer overruns. StringCchVPrintf always null-terminates a
nonzero-length destination buffer.
For more information on va_lists, see the conventions defined in Stdarg.h.
Behavior is undefined if the strings pointed to by pszDest, pszFormat, or any argument strings overlap.
Neither pszFormat nor pszDest should be NULL . See StringCchVPrintfEx if you require the handling of null string
pointer values.
StringCchVPrintf can be used in its generic form, or in its more specific forms. The data type of the string
determines the form of this function that you should use, as shown in the following table.
ST RIN G DATA T Y P E
ST RIN G L IT ERA L
F UN C T IO N
char
"string"
StringCchVPrintfA
TCHAR
TEXT("string")
StringCchVPrintf
WCHAR
L"string"
StringCchVPrintfW
Requirements
Minimum suppor ted client
Windows XP with SP2 [desktop apps | UWP apps]
Minimum suppor ted ser ver
Windows Server 2003 with SP1 [desktop apps | UWP apps]
Target Platform
Windows
Header
strsafe.h
See also
Reference
StringCbVPrintf
StringCchPrintf
StringCchVPrintfEx
minutes to read • Edit Online
This header is used by Menus and Other Resources. For more information, see:
Menus and Other Resources verrsrc.h contains the following programming interfaces:
Structures
T IT L E
DESC RIP T IO N
VS_FIXEDFILEINFO
Contains version information for a file. This information is
language and code page independent.
minutes to read • Edit Online
Contains version information for a file. This information is language and code page independent.
Syntax
typedef struct tagVS_FIXEDFILEINFO {
DWORD dwSignature;
DWORD dwStrucVersion;
DWORD dwFileVersionMS;
DWORD dwFileVersionLS;
DWORD dwProductVersionMS;
DWORD dwProductVersionLS;
DWORD dwFileFlagsMask;
DWORD dwFileFlags;
DWORD dwFileOS;
DWORD dwFileType;
DWORD dwFileSubtype;
DWORD dwFileDateMS;
DWORD dwFileDateLS;
} VS_FIXEDFILEINFO;
Members
dwSignature
Type: DWORD
Contains the value 0xFEEF04BD. This is used with the szKey member of the VS_VERSIONINFO structure when
searching a file for the VS_FIXEDFILEINFO structure.
dwStrucVersion
Type: DWORD
The binary version number of this structure. The high-order word of this member contains the major version
number, and the low-order word contains the minor version number.
dwFileVersionMS
Type: DWORD
The most significant 32 bits of the file's binary version number. This member is used with dwFileVersionLS to
form a 64-bit value used for numeric comparisons.
dwFileVersionLS
Type: DWORD
The least significant 32 bits of the file's binary version number. This member is used with dwFileVersionMS to
form a 64-bit value used for numeric comparisons.
dwProductVersionMS
Type: DWORD
The most significant 32 bits of the binary version number of the product with which this file was distributed. This
member is used with dwProductVersionLS to form a 64-bit value used for numeric comparisons.
dwProductVersionLS
Type: DWORD
The least significant 32 bits of the binary version number of the product with which this file was distributed. This
member is used with dwProductVersionMS to form a 64-bit value used for numeric comparisons.
dwFileFlagsMask
Type: DWORD
Contains a bitmask that specifies the valid bits in dwFileFlags . A bit is valid only if it was defined when the file was
created.
dwFileFlags
Type: DWORD
Contains a bitmask that specifies the Boolean attributes of the file. This member can include one or more of the
following values.
VA L UE
VS_
FF_
DEB
UG
0x0
000
000
1L
VS_
FF_I
NF
OIN
FER
RED
0x0
000
001
0L
VS_
FF_
PAT
CH
ED
0x0
000
000
4L
M EA N IN G
The file contains debugging information or is compiled with
debugging features enabled.
The file's version structure was created dynamically; therefore,
some of the members in this structure may be empty or
incorrect. This flag should never be set in a file's
VS_VERSIONINFO data.
The file has been modified and is not identical to the original
shipping file of the same version number.
VS_
FF_
PRE
REL
EAS
E
0x0
000
000
2L
VS_
FF_
PRI
VAT
EBU
ILD
0x0
000
000
8L
VS_
FF_
SPE
CIA
LBU
ILD
0x0
000
002
0L
The file is a development version, not a commercially released
product.
The file was not built using standard release procedures. If this
flag is set, the StringFileInfo structure should contain a
PrivateBuild entry.
The file was built by the original company using standard
release procedures but is a variation of the normal file of the
same version number. If this flag is set, the StringFileInfo
structure should contain a SpecialBuild entry.
dwFileOS
Type: DWORD
The operating system for which this file was designed. This member can be one of the following values.
VA L UE
M EA N IN G
The file was designed for MS-DOS.
VO
S_D
OS
0x0
001
000
0L
The file was designed for Windows NT.
VO
S_N
T
0x0
004
000
0L
The file was designed for 16-bit Windows.
VO
S__
WI
ND
OW
S16
0x0
000
000
1L
The file was designed for 32-bit Windows.
VO
S__
WI
ND
OW
S32
0x0
000
000
4L
The file was designed for 16-bit OS/2.
VO
S_O
S21
6
0x0
002
000
0L
The file was designed for 32-bit OS/2.
VO
S_O
S23
2
0x0
003
000
0L
The file was designed for 16-bit Presentation Manager.
VO
S__
PM
16
0x0
000
000
2L
The file was designed for 32-bit Presentation Manager.
VO
S__
PM
32
0x0
000
000
3L
VO
S_U
NK
NO
WN
0x0
000
000
0L
The operating system for which the file was designed is
unknown to the system.
An application can combine these values to indicate that the file was designed for one operating system running on
another. The following dwFileOS values are examples of this, but are not a complete list.
VA L UE
VO
S_D
OS_
WI
ND
OW
S16
0x0
001
000
1L
M EA N IN G
The file was designed for 16-bit Windows running on MSDOS.
VO
S_D
OS_
WI
ND
OW
S32
0x0
001
000
4L
The file was designed for 32-bit Windows running on MSDOS.
The file was designed for Windows NT.
VO
S_N
T_
WI
ND
OW
S32
0x0
004
000
4L
VO
S_O
S21
6_P
M1
6
0x0
002
000
2L
VO
S_O
S23
2_P
M3
2
0x0
003
000
3L
The file was designed for 16-bit Presentation Manager
running on 16-bit OS/2.
The file was designed for 32-bit Presentation Manager
running on 32-bit OS/2.
dwFileType
Type: DWORD
The general type of file. This member can be one of the following values. All other values are reserved.
VA L UE
M EA N IN G
The file contains an application.
VFT
_AP
P
0x0
000
000
1L
The file contains a DLL.
VFT
_DL
L
0x0
000
000
2L
VFT
_DR
V
0x0
000
000
3L
VFT
_FO
NT
0x0
000
000
4L
The file contains a device driver. If dwFileType is VFT_DRV ,
dwFileSubtype contains a more specific description of the
driver.
The file contains a font. If dwFileType is VFT_FONT ,
dwFileSubtype contains a more specific description of the
font file.
The file contains a static-link library.
VFT
_ST
ATI
C_L
IB
0x0
000
000
7L
The file type is unknown to the system.
VFT
_U
NK
NO
WN
0x0
000
000
0L
The file contains a virtual device.
VFT
_VX
D
0x0
000
000
5L
dwFileSubtype
Type: DWORD
The function of the file. The possible values depend on the value of dwFileType . For all values of dwFileType not
described in the following list, dwFileSubtype is zero.
If dwFileType is VFT_DRV , dwFileSubtype can be one of the following values.
VA L UE
M EA N IN G
The file contains a communications driver.
VFT
2_D
RV_
CO
MM
0x0
000
000
AL
The file contains a display driver.
VFT
2_D
RV_
DIS
PL A
Y
0x0
000
000
4L
The file contains an installable driver.
VFT
2_D
RV_
INS
TAL
L AB
LE
0x0
000
000
8L
The file contains a keyboard driver.
VFT
2_D
RV_
KEY
BO
AR
D
0x0
000
000
2L
The file contains a language driver.
VFT
2_D
RV_
LA
NG
UA
GE
0x0
000
000
3L
The file contains a mouse driver.
VFT
2_D
RV_
MO
USE
0x0
000
000
5L
The file contains a network driver.
VFT
2_D
RV_
NET
WO
RK
0x0
000
000
6L
The file contains a printer driver.
VFT
2_D
RV_
PRI
NTE
R
0x0
000
000
1L
The file contains a sound driver.
VFT
2_D
RV_
SO
UN
D
0x0
000
000
9L
The file contains a system driver.
VFT
2_D
RV_
SYS
TE
M
0x0
000
000
7L
The file contains a versioned printer driver.
VFT
2_D
RV_
VER
SIO
NE
D_P
RIN
TER
0x0
000
000
CL
The driver type is unknown by the system.
VFT
2_U
NK
NO
WN
0x0
000
000
0L
If dwFileType is VFT_FONT , dwFileSubtype can be one of the following values.
VA L UE
M EA N IN G
The file contains a raster font.
VFT
2_F
ON
T_R
AST
ER
0x0
000
000
1L
The file contains a TrueType font.
VFT
2_F
ON
T_T
RUE
TYP
E
0x0
000
000
3L
The file contains a vector font.
VFT
2_F
ON
T_V
ECT
OR
0x0
000
000
2L
The font type is unknown by the system.
VFT
2_U
NK
NO
WN
0x0
000
000
0L
If dwFileType is VFT_VXD , dwFileSubtype contains the virtual device identifier included in the virtual device
control block.
All dwFileSubtype values not listed here are reserved.
dwFileDateMS
Type: DWORD
The most significant 32 bits of the file's 64-bit binary creation date and time stamp.
dwFileDateLS
Type: DWORD
The least significant 32 bits of the file's 64-bit binary creation date and time stamp.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
verrsrc.h (include Windows.h)
See also
Conceptual
Reference
String
StringFileInfo
VS_VERSIONINFO
Version Information
minutes to read • Edit Online
This header is used by Backup. For more information, see:
Backup winbase.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
_lclose
The _lclose function closes the specified file so that it is no
longer available for reading or writing. This function is
provided for compatibility with 16-bit versions of Windows.
Win32-based applications should use the CloseHandle
function.
_lcreat
Creates or opens the specified file.
_llseek
Repositions the file pointer for the specified file.
_lopen
The _lopen function opens an existing file and sets the file
pointer to the beginning of the file. This function is provided
for compatibility with 16-bit versions of Windows. Win32based applications should use the CreateFile function.
_lread
The _lread function reads data from the specified file. This
function is provided for compatibility with 16-bit versions of
Windows. Win32-based applications should use the ReadFile
function.
_lwrite
Writes data to the specified file.
AccessCheckAndAuditAlarmA
Determines whether a security descriptor grants a specified set
of access rights to the client being impersonated by the calling
thread.
AccessCheckByTypeAndAuditAlarmA
Determines whether a security descriptor grants a specified set
of access rights to the client being impersonated by the calling
thread.
AccessCheckByTypeResultListAndAuditAlarmA
Determines whether a security descriptor grants a specified set
of access rights to the client being impersonated by the calling
thread.
AccessCheckByTypeResultListAndAuditAlarmByHandleA
Determines whether a security descriptor grants a specified set
of access rights to the client that the calling thread is
impersonating.
ActivateActCtx
The ActivateActCtx function activates the specified activation
context.
T IT L E
DESC RIP T IO N
AddAtomA
Adds a character string to the local atom table and returns a
unique value (an atom) identifying the string.
AddAtomW
Adds a character string to the local atom table and returns a
unique value (an atom) identifying the string.
AddConditionalAce
Adds a conditional access control entry (ACE) to the specified
access control list (ACL).
AddIntegrityLabelToBoundaryDescriptor
Adds a new required security identifier (SID) to the specified
boundary descriptor.
AddRefActCtx
The AddRefActCtx function increments the reference count of
the specified activation context.
AddSecureMemoryCacheCallback
Registers a callback function to be called when a secured
memory range is freed or its protections are changed.
ApplicationRecoveryFinished
Indicates that the calling application has completed its data
recovery.
ApplicationRecoveryInProgress
Indicates that the calling application is continuing to recover
data.
BackupEventLogA
Saves the specified event log to a backup file.
BackupEventLogW
Saves the specified event log to a backup file.
BackupRead
Back up a file or directory, including the security information.
BackupSeek
Seeks forward in a data stream initially accessed by using the
BackupRead or BackupWrite function.
BackupWrite
Restore a file or directory that was backed up using
BackupRead.
BeginUpdateResourceA
Retrieves a handle that can be used by the UpdateResource
function to add, delete, or replace resources in a binary
module.
BeginUpdateResourceW
Retrieves a handle that can be used by the UpdateResource
function to add, delete, or replace resources in a binary
module.
BindIoCompletionCallback
Associates the I/O completion port owned by the thread pool
with the specified file handle. On completion of an I/O request
involving this file, a non-I/O worker thread will execute the
specified callback function.
BuildCommDCBA
Fills a specified DCB structure with values specified in a devicecontrol string.
T IT L E
DESC RIP T IO N
BuildCommDCBAndTimeoutsA
Translates a device-definition string into appropriate devicecontrol block codes and places them into a device control
block.
BuildCommDCBAndTimeoutsW
Translates a device-definition string into appropriate devicecontrol block codes and places them into a device control
block.
BuildCommDCBW
Fills a specified DCB structure with values specified in a devicecontrol string.
CallNamedPipeA
Connects to a message-type pipe (and waits if an instance of
the pipe is not available), writes to and reads from the pipe,
and then closes the pipe.
CheckNameLegalDOS8Dot3A
Determines whether the specified name can be used to create
a file on a FAT file system.
CheckNameLegalDOS8Dot3W
Determines whether the specified name can be used to create
a file on a FAT file system.
ClearCommBreak
Restores character transmission for a specified
communications device and places the transmission line in a
nonbreak state.
ClearCommError
Retrieves information about a communications error and
reports the current status of a communications device.
ClearEventLogA
Clears the specified event log, and optionally saves the current
copy of the log to a backup file.
ClearEventLogW
Clears the specified event log, and optionally saves the current
copy of the log to a backup file.
CloseEncryptedFileRaw
Closes an encrypted file after a backup or restore operation,
and frees associated system resources.
CloseEventLog
Closes the specified event log.
CommConfigDialogA
Displays a driver-supplied configuration dialog box.
CommConfigDialogW
Displays a driver-supplied configuration dialog box.
ConvertFiberToThread
Converts the current fiber into a thread.
ConvertThreadToFiber
Converts the current thread into a fiber. You must convert a
thread into a fiber before you can schedule other fibers.
ConvertThreadToFiberEx
Converts the current thread into a fiber. You must convert a
thread into a fiber before you can schedule other fibers.
CopyContext
Copies a source context structure (including any XState) onto
an initialized destination context structure.
T IT L E
DESC RIP T IO N
CopyFile
Copies an existing file to a new file.
CopyFile2
Copies an existing file to a new file, notifying the application of
its progress through a callback function.
CopyFileA
Copies an existing file to a new file.
CopyFileExA
Copies an existing file to a new file, notifying the application of
its progress through a callback function.
CopyFileExW
Copies an existing file to a new file, notifying the application of
its progress through a callback function.
CopyFileTransactedA
Copies an existing file to a new file as a transacted operation,
notifying the application of its progress through a callback
function.
CopyFileTransactedW
Copies an existing file to a new file as a transacted operation,
notifying the application of its progress through a callback
function.
CopyFileW
Copies an existing file to a new file.
CreateActCtxA
The CreateActCtx function creates an activation context.
CreateActCtxW
The CreateActCtx function creates an activation context.
CreateBoundaryDescriptorA
Creates a boundary descriptor.
CreateDirectory
Creates a new directory.
CreateDirectoryExA
Creates a new directory with the attributes of a specified
template directory.
CreateDirectoryExW
Creates a new directory with the attributes of a specified
template directory.
CreateDirectoryTransactedA
Creates a new directory as a transacted operation, with the
attributes of a specified template directory.
CreateDirectoryTransactedW
Creates a new directory as a transacted operation, with the
attributes of a specified template directory.
CreateFiber
Allocates a fiber object, assigns it a stack, and sets up
execution to begin at the specified start address, typically the
fiber function. This function does not schedule the fiber.
CreateFiberEx
Allocates a fiber object, assigns it a stack, and sets up
execution to begin at the specified start address, typically the
fiber function. This function does not schedule the fiber.
CreateFileMappingA
Creates or opens a named or unnamed file mapping object for
a specified file.
T IT L E
DESC RIP T IO N
CreateFileMappingNumaA
Creates or opens a named or unnamed file mapping object for
a specified file and specifies the NUMA node for the physical
memory.
CreateFileTransactedA
Creates or opens a file, file stream, or directory as a transacted
operation.
CreateFileTransactedW
Creates or opens a file, file stream, or directory as a transacted
operation.
CreateHardLinkA
Establishes a hard link between an existing file and a new file.
CreateHardLinkTransactedA
Establishes a hard link between an existing file and a new file
as a transacted operation.
CreateHardLinkTransactedW
Establishes a hard link between an existing file and a new file
as a transacted operation.
CreateHardLinkW
Establishes a hard link between an existing file and a new file.
CreateJobObjectA
Creates or opens a job object.
CreateMailslotA
Creates a mailslot with the specified name and returns a
handle that a mailslot server can use to perform operations on
the mailslot.
CreateMailslotW
Creates a mailslot with the specified name and returns a
handle that a mailslot server can use to perform operations on
the mailslot.
CreateNamedPipeA
Creates an instance of a named pipe and returns a handle for
subsequent pipe operations.
CreatePrivateNamespaceA
Creates a private namespace.
CreateProcessWithLogonW
Creates a new process and its primary thread. Then the new
process runs the specified executable file in the security
context of the specified credentials (user, domain, and
password). It can optionally load the user profile for a specified
user.
CreateProcessWithTokenW
Creates a new process and its primary thread. The new
process runs in the security context of the specified token. It
can optionally load the user profile for the specified user.
CreateSemaphoreA
Creates or opens a named or unnamed semaphore object.
CreateSemaphoreExA
Creates or opens a named or unnamed semaphore object and
returns a handle to the object.
CreateSymbolicLinkA
Creates a symbolic link.
CreateSymbolicLinkTransactedA
Creates a symbolic link as a transacted operation.
T IT L E
DESC RIP T IO N
CreateSymbolicLinkTransactedW
Creates a symbolic link as a transacted operation.
CreateSymbolicLinkW
Creates a symbolic link.
CreateTapePartition
Reformats a tape.
CreateUmsCompletionList
Creates a user-mode scheduling (UMS) completion list.
CreateUmsThreadContext
Creates a user-mode scheduling (UMS) thread context to
represent a UMS worker thread.
DeactivateActCtx
The DeactivateActCtx function deactivates the activation
context corresponding to the specified cookie.
DebugBreakProcess
Causes a breakpoint exception to occur in the specified
process. This allows the calling thread to signal the debugger
to handle the exception.
DebugSetProcessKillOnExit
Sets the action to be performed when the calling thread exits.
DecryptFileA
Decrypts an encrypted file or directory.
DecryptFileW
Decrypts an encrypted file or directory.
DefineDosDeviceA
Defines, redefines, or deletes MS-DOS device names.
DeleteAtom
Decrements the reference count of a local string atom. If the
atom's reference count is reduced to zero, DeleteAtom
removes the string associated with the atom from the local
atom table.
DeleteFiber
Deletes an existing fiber.
DeleteFile
Deletes an existing file.
DeleteFileTransactedA
Deletes an existing file as a transacted operation.
DeleteFileTransactedW
Deletes an existing file as a transacted operation.
DeleteTimerQueue
Deletes a timer queue. Any pending timers in the queue are
canceled and deleted.
DeleteUmsCompletionList
Deletes the specified user-mode scheduling (UMS) completion
list. The list must be empty.
DeleteUmsThreadContext
Deletes the specified user-mode scheduling (UMS) thread
context. The thread must be terminated.
DeleteVolumeMountPointA
Deletes a drive letter or mounted folder.
DequeueUmsCompletionListItems
Retrieves user-mode scheduling (UMS) worker threads from
the specified UMS completion list.
T IT L E
DESC RIP T IO N
DeregisterEventSource
Closes the specified event log.
DestroyThreadpoolEnvironment
Deletes the specified callback environment. Call this function
when the callback environment is no longer needed for
creating new thread pool objects.
DisableThreadProfiling
Disables thread profiling.
DnsHostnameToComputerNameA
Converts a DNS-style host name to a NetBIOS-style computer
name.
DnsHostnameToComputerNameW
Converts a DNS-style host name to a NetBIOS-style computer
name.
DosDateTimeToFileTime
Converts MS-DOS date and time values to a file time.
EnableThreadProfiling
Enables thread profiling on the specified thread.
EncryptFileA
Encrypts a file or directory.
EncryptFileW
Encrypts a file or directory.
EndUpdateResourceA
Commits or discards changes made prior to a call to
UpdateResource.
EndUpdateResourceW
Commits or discards changes made prior to a call to
UpdateResource.
EnterUmsSchedulingMode
Converts the calling thread into a user-mode scheduling
(UMS) scheduler thread.
EnumResourceLanguagesA
Enumerates language-specific resources, of the specified type
and name, associated with a binary module.
EnumResourceLanguagesW
Enumerates language-specific resources, of the specified type
and name, associated with a binary module.
EnumResourceNamesA
Enumerates resources of a specified type within a binary
module.
EnumResourceTypesA
Enumerates resource types within a binary module.
EnumResourceTypesW
Enumerates resource types within a binary module.
EraseTape
Erases all or part of a tape.
EscapeCommFunction
Directs the specified communications device to perform an
extended function.
ExecuteUmsThread
Runs the specified UMS worker thread.
T IT L E
DESC RIP T IO N
FatalExit
Transfers execution control to the debugger. The behavior of
the debugger thereafter is specific to the type of debugger
used.
FileEncryptionStatusA
Retrieves the encryption status of the specified file.
FileEncryptionStatusW
Retrieves the encryption status of the specified file.
FileTimeToDosDateTime
Converts a file time to MS-DOS date and time values.
FindActCtxSectionGuid
The FindActCtxSectionGuid function retrieves information on a
specific GUID in the current activation context and returns a
ACTCTX_SECTION_KEYED_DATA structure.
FindActCtxSectionStringA
The FindActCtxSectionString function retrieves information on
a specific string in the current activation context and returns a
ACTCTX_SECTION_KEYED_DATA structure.
FindActCtxSectionStringW
The FindActCtxSectionString function retrieves information on
a specific string in the current activation context and returns a
ACTCTX_SECTION_KEYED_DATA structure.
FindAtomA
Searches the local atom table for the specified character string
and retrieves the atom associated with that string.
FindAtomW
Searches the local atom table for the specified character string
and retrieves the atom associated with that string.
FindFirstFileNameTransactedW
Creates an enumeration of all the hard links to the specified
file as a transacted operation. The function returns a handle to
the enumeration that can be used on subsequent calls to the
FindNextFileNameW function.
FindFirstFileTransactedA
Searches a directory for a file or subdirectory with a name that
matches a specific name as a transacted operation.
FindFirstFileTransactedW
Searches a directory for a file or subdirectory with a name that
matches a specific name as a transacted operation.
FindFirstStreamTransactedW
Enumerates the first stream in the specified file or directory as
a transacted operation.
FindFirstVolumeA
Retrieves the name of a volume on a computer.
FindFirstVolumeMountPointA
Retrieves the name of a mounted folder on the specified
volume.
FindFirstVolumeMountPointW
Retrieves the name of a mounted folder on the specified
volume.
FindNextVolumeA
Continues a volume search started by a call to the
FindFirstVolume function.
T IT L E
DESC RIP T IO N
FindNextVolumeMountPointA
Continues a mounted folder search started by a call to the
FindFirstVolumeMountPoint function.
FindNextVolumeMountPointW
Continues a mounted folder search started by a call to the
FindFirstVolumeMountPoint function.
FindResourceA
Determines the location of a resource with the specified type
and name in the specified module.
FindResourceExA
Determines the location of the resource with the specified
type, name, and language in the specified module.
FindVolumeMountPointClose
Closes the specified mounted folder search handle.
FormatMessage
Formats a message string.
FormatMessageA
Formats a message string.
FormatMessageW
Formats a message string.
GetActiveProcessorCount
Returns the number of active processors in a processor group
or in the system.
GetActiveProcessorGroupCount
Returns the number of active processor groups in the system.
GetApplicationRecoveryCallback
Retrieves a pointer to the callback routine registered for the
specified process. The address returned is in the virtual
address space of the process.
GetApplicationRestartSettings
Retrieves the restart information registered for the specified
process.
GetAtomNameA
Retrieves a copy of the character string associated with the
specified local atom.
GetAtomNameW
Retrieves a copy of the character string associated with the
specified local atom.
GetBinaryTypeA
Determines whether a file is an executable (.exe) file, and if so,
which subsystem runs the executable file.
GetBinaryTypeW
Determines whether a file is an executable (.exe) file, and if so,
which subsystem runs the executable file.
GetCommConfig
Retrieves the current configuration of a communications
device.
GetCommMask
Retrieves the value of the event mask for a specified
communications device.
GetCommModemStatus
Retrieves the modem control-register values.
GetCommPorts
Gets an array that contains the well-formed COM ports.
T IT L E
DESC RIP T IO N
GetCommProperties
Retrieves information about the communications properties
for a specified communications device.
GetCommState
Retrieves the current control settings for a specified
communications device.
GetCommTimeouts
Retrieves the time-out parameters for all read and write
operations on a specified communications device.
GetCompressedFileSizeTransactedA
Retrieves the actual number of bytes of disk storage used to
store a specified file as a transacted operation.
GetCompressedFileSizeTransactedW
Retrieves the actual number of bytes of disk storage used to
store a specified file as a transacted operation.
GetComputerNameA
Retrieves the NetBIOS name of the local computer. This name
is established at system startup, when the system reads it
from the registry.
GetComputerNameW
Retrieves the NetBIOS name of the local computer. This name
is established at system startup, when the system reads it
from the registry.
GetCurrentActCtx
The GetCurrentActCtx function returns the handle to the
active activation context of the calling thread.
GetCurrentDirectory
Retrieves the current directory for the current process.
GetCurrentHwProfileA
Retrieves information about the current hardware profile for
the local computer.
GetCurrentHwProfileW
Retrieves information about the current hardware profile for
the local computer.
GetCurrentUmsThread
Returns the user-mode scheduling (UMS) thread context of
the calling UMS thread.
GetDefaultCommConfigA
Retrieves the default configuration for the specified
communications device.
GetDefaultCommConfigW
Retrieves the default configuration for the specified
communications device.
GetDevicePowerState
Retrieves the current power state of the specified device.
GetDllDirectoryA
Retrieves the application-specific portion of the search path
used to locate DLLs for the application.
GetDllDirectoryW
Retrieves the application-specific portion of the search path
used to locate DLLs for the application.
GetEnabledXStateFeatures
Gets a mask of enabled XState features on x86 or x64
processors.
T IT L E
DESC RIP T IO N
GetEnvironmentVariable
Retrieves the contents of the specified variable from the
environment block of the calling process.
GetEventLogInformation
Retrieves information about the specified event log.
GetFileAttributesTransactedA
Retrieves file system attributes for a specified file or directory
as a transacted operation.
GetFileAttributesTransactedW
Retrieves file system attributes for a specified file or directory
as a transacted operation.
GetFileBandwidthReservation
Retrieves the bandwidth reservation properties of the volume
on which the specified file resides.
GetFileInformationByHandleEx
Retrieves file information for the specified file.
GetFileSecurityA
Obtains specified information about the security of a file or
directory. The information obtained is constrained by the
caller's access rights and privileges.
GetFirmwareEnvironmentVariableA
Retrieves the value of the specified firmware environment
variable.
GetFirmwareEnvironmentVariableExA
Retrieves the value of the specified firmware environment
variable and its attributes.
GetFirmwareEnvironmentVariableExW
Retrieves the value of the specified firmware environment
variable and its attributes.
GetFirmwareEnvironmentVariableW
Retrieves the value of the specified firmware environment
variable.
GetFirmwareType
Retrieves the firmware type of the local computer.
GetFullPathNameTransactedA
Retrieves the full path and file name of the specified file as a
transacted operation.
GetFullPathNameTransactedW
Retrieves the full path and file name of the specified file as a
transacted operation.
GetLogicalDriveStringsA
Fills a buffer with strings that specify valid drives in the system.
GetLongPathNameTransactedA
Converts the specified path to its long form as a transacted
operation.
GetLongPathNameTransactedW
Converts the specified path to its long form as a transacted
operation.
GetMailslotInfo
Retrieves information about the specified mailslot.
GetMaximumProcessorCount
Returns the maximum number of logical processors that a
processor group or the system can have.
T IT L E
DESC RIP T IO N
GetMaximumProcessorGroupCount
Returns the maximum number of processor groups that the
system can have.
GetNamedPipeClientComputerNameA
Retrieves the client computer name for the specified named
pipe.
GetNamedPipeClientProcessId
Retrieves the client process identifier for the specified named
pipe.
GetNamedPipeClientSessionId
Retrieves the client session identifier for the specified named
pipe.
GetNamedPipeHandleStateA
Retrieves information about a specified named pipe.
GetNamedPipeServerProcessId
Retrieves the server process identifier for the specified named
pipe.
GetNamedPipeServerSessionId
Retrieves the server session identifier for the specified named
pipe.
GetNextUmsListItem
Returns the next user-mode scheduling (UMS) thread context
in a list of thread contexts.
GetNumaAvailableMemoryNode
Retrieves the amount of memory available in the specified
node.
GetNumaAvailableMemoryNodeEx
Retrieves the amount of memory that is available in a node
specified as a USHORT value.
GetNumaNodeNumberFromHandle
Retrieves the NUMA node associated with the file or I/O
device represented by the specified file handle.
GetNumaNodeProcessorMask
Retrieves the processor mask for the specified node.
GetNumaProcessorNode
Retrieves the node number for the specified processor.
GetNumaProcessorNodeEx
Retrieves the node number as a USHORT value for the
specified logical processor.
GetNumaProximityNode
Retrieves the NUMA node number that corresponds to the
specified proximity domain identifier.
GetNumberOfEventLogRecords
Retrieves the number of records in the specified event log.
GetOldestEventLogRecord
Retrieves the absolute record number of the oldest record in
the specified event log.
GetPrivateProfileInt
Retrieves an integer associated with a key in the specified
section of an initialization file.
GetPrivateProfileIntA
Retrieves an integer associated with a key in the specified
section of an initialization file.
T IT L E
DESC RIP T IO N
GetPrivateProfileIntW
Retrieves an integer associated with a key in the specified
section of an initialization file.
GetPrivateProfileSection
Retrieves all the keys and values for the specified section of an
initialization file.
GetPrivateProfileSectionA
Retrieves all the keys and values for the specified section of an
initialization file.
GetPrivateProfileSectionNames
Retrieves the names of all sections in an initialization file.
GetPrivateProfileSectionNamesA
Retrieves the names of all sections in an initialization file.
GetPrivateProfileSectionNamesW
Retrieves the names of all sections in an initialization file.
GetPrivateProfileSectionW
Retrieves all the keys and values for the specified section of an
initialization file.
GetPrivateProfileString
Retrieves a string from the specified section in an initialization
file.
GetPrivateProfileStringA
Retrieves a string from the specified section in an initialization
file.
GetPrivateProfileStringW
Retrieves a string from the specified section in an initialization
file.
GetPrivateProfileStruct
Retrieves the data associated with a key in the specified
section of an initialization file.
GetPrivateProfileStructA
Retrieves the data associated with a key in the specified
section of an initialization file.
GetPrivateProfileStructW
Retrieves the data associated with a key in the specified
section of an initialization file.
GetProcessAffinityMask
Retrieves the process affinity mask for the specified process
and the system affinity mask for the system.
GetProcessDEPPolicy
Gets the data execution prevention (DEP) and DEP-ATL thunk
emulation settings for the specified 32-bit
process.Windows XP with SP3: Gets the DEP and DEP-ATL
thunk emulation settings for the current process.
GetProcessIoCounters
Retrieves accounting information for all I/O operations
performed by the specified process.
GetProcessWorkingSetSize
Retrieves the minimum and maximum working set sizes of the
specified process.
GetProfileIntA
Retrieves an integer from a key in the specified section of the
Win.ini file.
T IT L E
DESC RIP T IO N
GetProfileIntW
Retrieves an integer from a key in the specified section of the
Win.ini file.
GetProfileSectionA
Retrieves all the keys and values for the specified section of the
Win.ini file.
GetProfileSectionW
Retrieves all the keys and values for the specified section of the
Win.ini file.
GetProfileStringA
Retrieves the string associated with a key in the specified
section of the Win.ini file.
GetProfileStringW
Retrieves the string associated with a key in the specified
section of the Win.ini file.
GetShortPathNameA
Retrieves the short path form of the specified path.
GetSystemDEPPolicy
Gets the data execution prevention (DEP) policy setting for the
system.
GetSystemPowerStatus
Retrieves the power status of the system. The status indicates
whether the system is running on AC or DC power, whether
the battery is currently charging, how much battery life
remains, and if battery saver is on or off.
GetSystemRegistryQuota
Retrieves the current size of the registry and the maximum
size that the registry is allowed to attain on the system.
GetTapeParameters
Retrieves information that describes the tape or the tape drive.
GetTapePosition
Retrieves the current address of the tape, in logical or absolute
blocks.
GetTapeStatus
Determines whether the tape device is ready to process tape
commands.
GetTempFileName
Creates a name for a temporary file. If a unique file name is
generated, an empty file is created and the handle to it is
released; otherwise, only a file name is generated.
GetThreadSelectorEntry
Retrieves a descriptor table entry for the specified selector and
thread.
GetUmsCompletionListEvent
Retrieves a handle to the event associated with the specified
user-mode scheduling (UMS) completion list.
GetUmsSystemThreadInformation
Queries whether the specified thread is a UMS scheduler
thread, a UMS worker thread, or a non-UMS thread.
GetUserNameA
Retrieves the name of the user associated with the current
thread.
GetUserNameW
Retrieves the name of the user associated with the current
thread.
T IT L E
DESC RIP T IO N
GetVolumeNameForVolumeMountPointA
Retrieves a volume GUID path for the volume that is
associated with the specified volume mount point ( drive letter,
volume GUID path, or mounted folder).
GetVolumePathNameA
Retrieves the volume mount point where the specified path is
mounted.
GetVolumePathNamesForVolumeNameA
Retrieves a list of drive letters and mounted folder paths for
the specified volume.
GetXStateFeaturesMask
Returns the mask of XState features set within a CONTEXT
structure.
GlobalAddAtomA
Adds a character string to the global atom table and returns a
unique value (an atom) identifying the string.
GlobalAddAtomExA
Adds a character string to the global atom table and returns a
unique value (an atom) identifying the string.
GlobalAddAtomExW
Adds a character string to the global atom table and returns a
unique value (an atom) identifying the string.
GlobalAddAtomW
Adds a character string to the global atom table and returns a
unique value (an atom) identifying the string.
GlobalAlloc
Allocates the specified number of bytes from the heap.
GlobalDeleteAtom
Decrements the reference count of a global string atom. If the
atom's reference count reaches zero, GlobalDeleteAtom
removes the string associated with the atom from the global
atom table.
GlobalDiscard
Discards the specified global memory block.
GlobalFindAtomA
Searches the global atom table for the specified character
string and retrieves the global atom associated with that
string.
GlobalFindAtomW
Searches the global atom table for the specified character
string and retrieves the global atom associated with that
string.
GlobalFlags
Retrieves information about the specified global memory
object.
GlobalFree
Frees the specified global memory object and invalidates its
handle.
GlobalGetAtomNameA
Retrieves a copy of the character string associated with the
specified global atom.
GlobalGetAtomNameW
Retrieves a copy of the character string associated with the
specified global atom.
T IT L E
DESC RIP T IO N
GlobalHandle
Retrieves the handle associated with the specified pointer to a
global memory block.
GlobalLock
Locks a global memory object and returns a pointer to the
first byte of the object's memory block.
GlobalMemoryStatus
Retrieves information about the system's current usage of
both physical and virtual memory.
GlobalReAlloc
Changes the size or attributes of a specified global memory
object. The size can increase or decrease.
GlobalSize
Retrieves the current size of the specified global memory
object, in bytes.
GlobalUnlock
Decrements the lock count associated with a memory object
that was allocated with GMEM_MOVEABLE.
HasOverlappedIoCompleted
Provides a high performance test operation that can be used
to poll for the completion of an outstanding I/O operation.
InitAtomTable
Initializes the local atom table and sets the number of hash
buckets to the specified size.
InitializeContext
Initializes a CONTEXT structure inside a buffer with the
necessary size and alignment.
InitializeThreadpoolEnvironment
Initializes a callback environment.
InterlockedExchangeSubtract
Performs an atomic subtraction of two values.
IsBadCodePtr
Determines whether the calling process has read access to the
memory at the specified address.
IsBadReadPtr
Verifies that the calling process has read access to the specified
range of memory.
IsBadStringPtrA
Verifies that the calling process has read access to the specified
range of memory.
IsBadStringPtrW
Verifies that the calling process has read access to the specified
range of memory.
IsBadWritePtr
Verifies that the calling process has write access to the
specified range of memory.
IsNativeVhdBoot
Indicates if the OS was booted from a VHD container.
IsSystemResumeAutomatic
Determines the current state of the computer.
IsTextUnicode
Determines if a buffer is likely to contain a form of Unicode
text.
T IT L E
DESC RIP T IO N
LoadModule
Loads and executes an application or creates a new instance of
an existing application.
LoadPackagedLibrary
Loads the specified packaged module and its dependencies
into the address space of the calling process.
LocalAlloc
Allocates the specified number of bytes from the heap.
LocalFlags
Retrieves information about the specified local memory object.
LocalFree
Frees the specified local memory object and invalidates its
handle.
LocalHandle
Retrieves the handle associated with the specified pointer to a
local memory object.
LocalLock
Locks a local memory object and returns a pointer to the first
byte of the object's memory block.
LocalReAlloc
Changes the size or the attributes of a specified local memory
object. The size can increase or decrease.
LocalSize
Retrieves the current size of the specified local memory object,
in bytes.
LocalUnlock
Decrements the lock count associated with a memory object
that was allocated with LMEM_MOVEABLE.
LocateXStateFeature
Retrieves a pointer to the processor state for an XState feature
within a CONTEXT structure.
LogonUserA
The Win32 LogonUser function attempts to log a user on to
the local computer. LogonUser returns a handle to a user
token that you can use to impersonate user.
LogonUserExA
The LogonUserEx function attempts to log a user on to the
local computer.
LogonUserExW
The LogonUserEx function attempts to log a user on to the
local computer.
LogonUserW
The Win32 LogonUser function attempts to log a user on to
the local computer. LogonUser returns a handle to a user
token that you can use to impersonate user.
LookupAccountNameA
Accepts the name of a system and an account as input. It
retrieves a security identifier (SID) for the account and the
name of the domain on which the account was found.
LookupAccountNameW
Accepts the name of a system and an account as input. It
retrieves a security identifier (SID) for the account and the
name of the domain on which the account was found.
T IT L E
DESC RIP T IO N
LookupAccountSidA
Accepts a security identifier (SID) as input. It retrieves the
name of the account for this SID and the name of the first
domain on which this SID is found.
LookupAccountSidLocalA
Retrieves the name of the account for the specified SID on the
local machine.
LookupAccountSidLocalW
Retrieves the name of the account for the specified SID on the
local machine.
LookupAccountSidW
Accepts a security identifier (SID) as input. It retrieves the
name of the account for this SID and the name of the first
domain on which this SID is found.
LookupPrivilegeDisplayNameA
Retrieves the display name that represents a specified
privilege.
LookupPrivilegeDisplayNameW
Retrieves the display name that represents a specified
privilege.
LookupPrivilegeNameA
Retrieves the name that corresponds to the privilege
represented on a specific system by a specified locally unique
identifier (LUID).
LookupPrivilegeNameW
Retrieves the name that corresponds to the privilege
represented on a specific system by a specified locally unique
identifier (LUID).
LookupPrivilegeValueA
Retrieves the locally unique identifier (LUID) used on a
specified system to locally represent the specified privilege
name.
LookupPrivilegeValueW
Retrieves the locally unique identifier (LUID) used on a
specified system to locally represent the specified privilege
name.
lstrcatA
Appends one string to another.Warning Do not use.
lstrcatW
Appends one string to another.Warning Do not use.
lstrcmpA
Compares two character strings. The comparison is casesensitive.
lstrcmpiA
Compares two character strings. The comparison is not casesensitive.
lstrcmpiW
Compares two character strings. The comparison is not casesensitive.
lstrcmpW
Compares two character strings. The comparison is casesensitive.
lstrcpyA
Copies a string to a buffer.
T IT L E
DESC RIP T IO N
lstrcpynA
Copies a specified number of characters from a source string
into a buffer.Warning Do not use.
lstrcpynW
Copies a specified number of characters from a source string
into a buffer.Warning Do not use.
lstrcpyW
Copies a string to a buffer.
lstrlenA
Determines the length of the specified string (not including
the terminating null character).
lstrlenW
Determines the length of the specified string (not including
the terminating null character).
MAKEINTATOM
Converts the specified atom into a string, so it can be passed
to functions which accept either atoms or strings.
MapUserPhysicalPagesScatter
Maps previously allocated physical memory pages at a
specified address in an Address Windowing Extensions (AWE)
region.
MapViewOfFileExNuma
Maps a view of a file mapping into the address space of a
calling process and specifies the NUMA node for the physical
memory.
MoveFile
Moves an existing file or a directory, including its children.
MoveFileA
Moves an existing file or a directory, including its children.
MoveFileExA
Moves an existing file or directory, including its children, with
various move options.
MoveFileExW
Moves an existing file or directory, including its children, with
various move options.
MoveFileTransactedA
Moves an existing file or a directory, including its children, as a
transacted operation.
MoveFileTransactedW
Moves an existing file or a directory, including its children, as a
transacted operation.
MoveFileW
Moves an existing file or a directory, including its children.
MoveFileWithProgressA
Moves a file or directory, including its children. You can
provide a callback function that receives progress notifications.
MoveFileWithProgressW
Moves a file or directory, including its children. You can
provide a callback function that receives progress notifications.
MulDiv
Multiplies two 32-bit values and then divides the 64-bit result
by a third 32-bit value.
T IT L E
DESC RIP T IO N
NotifyChangeEventLog
Enables an application to receive notification when an event is
written to the specified event log.
ObjectCloseAuditAlarmA
Generates an audit message in the security event log when a
handle to a private object is deleted.
ObjectDeleteAuditAlarmA
Generates audit messages when an object is deleted.
ObjectOpenAuditAlarmA
Generates audit messages when a client application attempts
to gain access to an object or to create a new one.
ObjectPrivilegeAuditAlarmA
Generates an audit message in the security event log.
OpenBackupEventLogA
Opens a handle to a backup event log created by the
BackupEventLog function.
OpenBackupEventLogW
Opens a handle to a backup event log created by the
BackupEventLog function.
OpenCommPort
Attempts to open a communication device.
OpenEncryptedFileRawA
Opens an encrypted file in order to backup (export) or restore
(import) the file.
OpenEncryptedFileRawW
Opens an encrypted file in order to backup (export) or restore
(import) the file.
OpenEventLogA
Opens a handle to the specified event log.
OpenEventLogW
Opens a handle to the specified event log.
OpenFile
Creates, opens, reopens, or deletes a file.
OpenFileById
Opens the file that matches the specified identifier.
OpenFileMappingA
Opens a named file mapping object.
OpenJobObjectA
Opens an existing job object.
OpenPrivateNamespaceA
Opens a private namespace.
OperationEnd
Notifies the system that the application is about to end an
operation.
OperationStart
Notifies the system that the application is about to start an
operation.
PowerClearRequest
Decrements the count of power requests of the specified type
for a power request object.
PowerCreateRequest
Creates a new power request object.
T IT L E
DESC RIP T IO N
PowerSetRequest
Increments the count of power requests of the specified type
for a power request object.
PrepareTape
Prepares the tape to be accessed or removed.
PrivilegedServiceAuditAlarmA
Generates an audit message in the security event log.
PulseEvent
Sets the specified event object to the signaled state and then
resets it to the nonsignaled state after releasing the
appropriate number of waiting threads.
PurgeComm
Discards 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.
QueryActCtxSettingsW
The QueryActCtxSettingsW function specifies the activation
context, and the namespace and name of the attribute that is
to be queried.
QueryActCtxW
The QueryActCtxW function queries the activation context.
QueryDosDeviceA
Retrieves information about MS-DOS device names.
QueryFullProcessImageNameA
Retrieves the full name of the executable image for the
specified process.
QueryFullProcessImageNameW
Retrieves the full name of the executable image for the
specified process.
QueryThreadProfiling
Determines whether thread profiling is enabled for the
specified thread.
QueryUmsThreadInformation
Retrieves information about the specified user-mode
scheduling (UMS) worker thread.
ReadDirectoryChangesExW
Retrieves information that describes the changes within the
specified directory, which can include extended information if
that information type is specified.
ReadDirectoryChangesW
Retrieves information that describes the changes within the
specified directory.
ReadEncryptedFileRaw
Backs up (export) encrypted files.
ReadEventLogA
Reads the specified number of entries from the specified event
log.
ReadEventLogW
Reads the specified number of entries from the specified event
log.
ReadThreadProfilingData
Reads the specified profiling data associated with the thread.
RegisterApplicationRecoveryCallback
Registers the active instance of an application for recovery.
T IT L E
DESC RIP T IO N
RegisterApplicationRestart
Registers the active instance of an application for restart.
RegisterEventSourceA
Retrieves a registered handle to the specified event log.
RegisterEventSourceW
Retrieves a registered handle to the specified event log.
RegisterWaitForSingleObject
Directs a wait thread in the thread pool to wait on the object.
ReleaseActCtx
The ReleaseActCtx function decrements the reference count of
the specified activation context.
RemoveDirectoryTransactedA
Deletes an existing empty directory as a transacted operation.
RemoveDirectoryTransactedW
Deletes an existing empty directory as a transacted operation.
RemoveSecureMemoryCacheCallback
Unregisters a callback function that was previously registered
with the AddSecureMemoryCacheCallback function.
ReOpenFile
Reopens the specified file system object with different access
rights, sharing mode, and flags.
ReplaceFileA
Replaces one file with another file, with the option of creating a
backup copy of the original file.
ReplaceFileW
Replaces one file with another file, with the option of creating a
backup copy of the original file.
ReportEventA
Writes an entry at the end of the specified event log.
ReportEventW
Writes an entry at the end of the specified event log.
RequestWakeupLatency
Has no effect and returns STATUS_NOT_SUPPORTED. This
function is provided only for compatibility with earlier versions
of Windows.Windows Server 2008 and Windows Vista: Has
no effect and always returns success.
SetCommBreak
Suspends character transmission for a specified
communications device and places the transmission line in a
break state until the ClearCommBreak function is called.
SetCommConfig
Sets the current configuration of a communications device.
SetCommMask
Specifies a set of events to be monitored for a
communications device.
SetCommState
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.
SetCommTimeouts
Sets the time-out parameters for all read and write operations
on a specified communications device.
T IT L E
DESC RIP T IO N
SetCurrentDirectory
Changes the current directory for the current process.
SetDefaultCommConfigA
Sets the default configuration for a communications device.
SetDefaultCommConfigW
Sets the default configuration for a communications device.
SetDllDirectoryA
Adds a directory to the search path used to locate DLLs for
the application.
SetDllDirectoryW
Adds a directory to the search path used to locate DLLs for
the application.
SetEnvironmentVariable
Sets the contents of the specified environment variable for the
current process.
SetFileAttributesTransactedA
Sets the attributes for a file or directory as a transacted
operation.
SetFileAttributesTransactedW
Sets the attributes for a file or directory as a transacted
operation.
SetFileBandwidthReservation
Requests that bandwidth for the specified file stream be
reserved. The reservation is specified as a number of bytes in a
period of milliseconds for I/O requests on the specified file
handle.
SetFileCompletionNotificationModes
Sets the notification modes for a file handle, allowing you to
specify how completion notifications work for the specified file.
SetFileSecurityA
Sets the security of a file or directory object.
SetFileShortNameA
Sets the short name for the specified file.
SetFileShortNameW
Sets the short name for the specified file.
SetFirmwareEnvironmentVariableA
Sets the value of the specified firmware environment variable.
SetFirmwareEnvironmentVariableExA
Sets the value of the specified firmware environment variable
as the attributes that indicate how this variable is stored and
maintained.
SetFirmwareEnvironmentVariableExW
Sets the value of the specified firmware environment variable
and the attributes that indicate how this variable is stored and
maintained.
SetFirmwareEnvironmentVariableW
Sets the value of the specified firmware environment variable.
SetHandleCount
SetMailslotInfo
Sets the time-out value used by the specified mailslot for a
read operation.
T IT L E
DESC RIP T IO N
SetProcessAffinityMask
Sets a processor affinity mask for the threads of the specified
process.
SetProcessDEPPolicy
Changes data execution prevention (DEP) and DEP-ATL thunk
emulation settings for a 32-bit process.
SetProcessWorkingSetSize
Sets the minimum and maximum working set sizes for the
specified process.
SetSearchPathMode
Sets the per-process mode that the SearchPath function uses
when locating files.
SetSystemPowerState
Suspends the system by shutting power down. Depending on
the ForceFlag parameter, the function either suspends
operation immediately or requests permission from all
applications and device drivers before doing so.
SetTapeParameters
Specifies the block size of a tape or configures the tape device.
SetTapePosition
Sets the tape position on the specified device.
SetThreadAffinityMask
Sets a processor affinity mask for the specified thread.
SetThreadExecutionState
Enables an application to inform the system that it is in use,
thereby preventing the system from entering sleep or turning
off the display while the application is running.
SetThreadpoolCallbackCleanupGroup
Associates the specified cleanup group with the specified
callback environment.
SetThreadpoolCallbackLibrary
Ensures that the specified DLL remains loaded as long as there
are outstanding callbacks.
SetThreadpoolCallbackPersistent
Specifies that the callback should run on a persistent thread.
SetThreadpoolCallbackPool
Sets the thread pool to be used when generating callbacks.
SetThreadpoolCallbackPriority
Specifies the priority of a callback function relative to other
work items in the same thread pool.
SetThreadpoolCallbackRunsLong
Indicates that callbacks associated with this callback
environment may not return quickly.
SetUmsThreadInformation
Sets application-specific context information for the specified
user-mode scheduling (UMS) worker thread.
SetupComm
Initializes the communications parameters for a specified
communications device.
SetVolumeLabelA
Sets the label of a file system volume.
SetVolumeLabelW
Sets the label of a file system volume.
T IT L E
DESC RIP T IO N
SetVolumeMountPointA
Associates a volume with a drive letter or a directory on
another volume.
SetVolumeMountPointW
Associates a volume with a drive letter or a directory on
another volume.
SetXStateFeaturesMask
Sets the mask of XState features set within a CONTEXT
structure.
SwitchToFiber
Schedules a fiber. The function must be called on a fiber.
TransmitCommChar
Transmits a specified character ahead of any pending data in
the output buffer of the specified communications device.
UmsThreadYield
Yields control to the user-mode scheduling (UMS) scheduler
thread on which the calling UMS worker thread is running.
UnregisterApplicationRecoveryCallback
Removes the active instance of an application from the
recovery list.
UnregisterApplicationRestart
Removes the active instance of an application from the restart
list.
UnregisterWait
Cancels a registered wait operation issued by the
RegisterWaitForSingleObject function.
UpdateResourceA
Adds, deletes, or replaces a resource in a portable executable
(PE) file.
UpdateResourceW
Adds, deletes, or replaces a resource in a portable executable
(PE) file.
VerifyVersionInfoA
Compares a set of operating system version requirements to
the corresponding values for the currently running version of
the system.
VerifyVersionInfoW
Compares a set of operating system version requirements to
the corresponding values for the currently running version of
the system.
WaitCommEvent
Waits for an event to occur for a specified communications
device. The set of events that are monitored by this function is
contained in the event mask associated with the device
handle.
WaitNamedPipeA
Waits until either a time-out interval elapses or an instance of
the specified named pipe is available for connection (that is,
the pipe's server process has a pending ConnectNamedPipe
operation on the pipe).
WinExec
Runs the specified application.
WinMain
The user-provided entry point for a graphical Windows-based
application.
T IT L E
DESC RIP T IO N
Wow64EnableWow64FsRedirection
Enables or disables file system redirection for the calling
thread.
Wow64GetThreadContext
Retrieves the context of the specified WOW64 thread.
Wow64GetThreadSelectorEntry
Retrieves a descriptor table entry for the specified selector and
WOW64 thread.
Wow64SetThreadContext
Sets the context of the specified WOW64 thread.
Wow64SuspendThread
Suspends the specified WOW64 thread.
WriteEncryptedFileRaw
Restores (import) encrypted files.
WritePrivateProfileSectionA
Replaces the keys and values for the specified section in an
initialization file.
WritePrivateProfileSectionW
Replaces the keys and values for the specified section in an
initialization file.
WritePrivateProfileStringA
Copies a string into the specified section of an initialization file.
WritePrivateProfileStringW
Copies a string into the specified section of an initialization file.
WritePrivateProfileStructA
Copies data into a key in the specified section of an
initialization file. As it copies the data, the function calculates a
checksum and appends it to the end of the data.
WritePrivateProfileStructW
Copies data into a key in the specified section of an
initialization file. As it copies the data, the function calculates a
checksum and appends it to the end of the data.
WriteProfileSectionA
Replaces the contents of the specified section in the Win.ini file
with specified keys and values.
WriteProfileSectionW
Replaces the contents of the specified section in the Win.ini file
with specified keys and values.
WriteProfileStringA
Copies a string into the specified section of the Win.ini file.
WriteProfileStringW
Copies a string into the specified section of the Win.ini file.
WriteTapemark
Writes a specified number of filemarks, setmarks, short
filemarks, or long filemarks to a tape device.
WTSGetActiveConsoleSessionId
Retrieves the session identifier of the console session.
ZombifyActCtx
The ZombifyActCtx function deactivates the specified
activation context, but does not deallocate it.
Callback functions
T IT L E
DESC RIP T IO N
LPPROGRESS_ROUTINE
An application-defined callback function used with the
CopyFileEx, MoveFileTransacted, and MoveFileWithProgress
functions.
PCOPYFILE2_PROGRESS_ROUTINE
An application-defined callback function used with the
CopyFile2 function.
PFE_EXPORT_FUNC
An application-defined callback function used with
ReadEncryptedFileRaw.
PFE_IMPORT_FUNC
An application-defined callback function used with
WriteEncryptedFileRaw. The system calls ImportCallback one
or more times, each time to retrieve a portion of a backup file's
data.
PFIBER_START_ROUTINE
An application-defined function used with the CreateFiber
function. It serves as the starting address for a fiber.
Structures
T IT L E
DESC RIP T IO N
ACTCTX_SECTION_KEYED_DATA
The ACTCTX_SECTION_KEYED_DATA structure is used by the
FindActCtxSectionString and FindActCtxSectionGuid functions
to return the activation context information along with either
the GUID or 32-bit integer-tagged activation context section.
ACTCTXA
The ACTCTX structure is used by the CreateActCtx function to
create the activation context.
ACTCTXW
The ACTCTX structure is used by the CreateActCtx function to
create the activation context.
COMMCONFIG
Contains information about the configuration state of a
communications device.
COMMPROP
Contains information about a communications driver.
COMMTIMEOUTS
Contains the time-out parameters for a communications
device.
COMSTAT
Contains information about a communications device.
COPYFILE2_EXTENDED_PARAMETERS
Contains extended parameters for the CopyFile2 function.
COPYFILE2_MESSAGE
Passed to the CopyFile2ProgressRoutine callback function with
information about a pending copy operation.
DCB
Defines the control setting for a serial communications device.
EVENTLOG_FULL_INFORMATION
Indicates whether the event log is full.
T IT L E
DESC RIP T IO N
FILE_ALIGNMENT_INFO
Contains alignment information for a file.
FILE_ALLOCATION_INFO
Contains the total number of bytes that should be allocated
for a file.
FILE_ATTRIBUTE_TAG_INFO
Receives the requested file attribute information. Used for any
handles.
FILE_BASIC_INFO
Contains the basic information for a file. Used for file handles.
FILE_COMPRESSION_INFO
Receives file compression information.
FILE_DISPOSITION_INFO
Indicates whether a file should be deleted. Used for any
handles.
FILE_END_OF_FILE_INFO
Contains the specified value to which the end of the file should
be set.
FILE_FULL_DIR_INFO
Contains directory information for a file.
FILE_ID_BOTH_DIR_INFO
Contains information about files in the specified directory.
FILE_ID_DESCRIPTOR
Specifies the type of ID that is being used.
FILE_ID_EXTD_DIR_INFO
Contains identification information for a file.
FILE_ID_INFO
Contains identification information for a file.
FILE_IO_PRIORITY_HINT_INFO
Specifies the priority hint for a file I/O operation.
FILE_NAME_INFO
Receives the file name.
FILE_REMOTE_PROTOCOL_INFO
Contains file remote protocol information.
FILE_RENAME_INFO
Contains the name to which the file should be renamed.
FILE_STANDARD_INFO
Receives extended information for the file.
FILE_STORAGE_INFO
Contains directory information for a file.
FILE_STREAM_INFO
Receives file stream information for the specified file.
HW_PROFILE_INFOA
Contains information about a hardware profile.
HW_PROFILE_INFOW
Contains information about a hardware profile.
MEMORYSTATUS
Contains information about the current state of both physical
and virtual memory.
OFSTRUCT
Contains information about a file that the OpenFile function
opened or attempted to open.
T IT L E
DESC RIP T IO N
OPERATION_END_PARAMETERS
This structure is used by the OperationEnd function.
OPERATION_START_PARAMETERS
This structure is used by the OperationStart function.
STARTUPINFOEXA
Specifies the window station, desktop, standard handles, and
attributes for a new process. It is used with the CreateProcess
and CreateProcessAsUser functions.
STARTUPINFOEXW
Specifies the window station, desktop, standard handles, and
attributes for a new process. It is used with the CreateProcess
and CreateProcessAsUser functions.
SYSTEM_POWER_STATUS
Contains information about the power status of the system.
UMS_SCHEDULER_STARTUP_INFO
Specifies attributes for a user-mode scheduling (UMS)
scheduler thread.
UMS_SYSTEM_THREAD_INFORMATION
Specifies a UMS scheduler thread, UMS worker thread, or nonUMS thread. The GetUmsSystemThreadInformation function
uses this structure.
WIN32_STREAM_ID
Contains stream data.
Enumerations
T IT L E
DESC RIP T IO N
COPYFILE2_COPY_PHASE
Indicates the phase of a copy at the time of an error.
COPYFILE2_MESSAGE_ACTION
Returned by the CopyFile2ProgressRoutine callback function to
indicate what action should be taken for the pending copy
operation.
COPYFILE2_MESSAGE_TYPE
Indicates the type of message passed in the
COPYFILE2_MESSAGE structure to the
CopyFile2ProgressRoutine callback function.
FILE_ID_TYPE
Discriminator for the union in the FILE_ID_DESCRIPTOR
structure.
PRIORITY_HINT
Defines values that are used with the
FILE_IO_PRIORITY_HINT_INFO structure to specify the priority
hint for a file I/O operation.
minutes to read • Edit Online
Retrieves a handle that can be used by the UpdateResource function to add, delete, or replace resources in a binary
module.
Syntax
HANDLE BeginUpdateResourceA(
LPCSTR pFileName,
BOOL bDeleteExistingResources
);
Parameters
pFileName
Type: LPCTSTR
The binary file in which to update resources. An application must be able to obtain write-access to this file; the file
referenced by pFileName cannot be currently executing. If pFileName does not specify a full path, the system
searches for the file in the current directory.
bDeleteExistingResources
Type: BOOL
Indicates whether to delete the pFileName parameter's existing resources. If this parameter is TRUE , existing
resources are deleted and the updated file includes only resources added with the UpdateResource function. If this
parameter is FALSE , the updated file includes existing resources unless they are explicitly deleted or replaced by
using UpdateResource .
Return value
Type: HANDLE
If the function succeeds, the return value is a handle that can be used by the UpdateResource and
EndUpdateResource functions. The return value is NULL if the specified file is not a PE, the file does not exist, or the
file cannot be opened for writing. To get extended error information, call GetLastError.
Remarks
It is recommended that the resource file is not loaded before this function is called. However, if that file is already
loaded, it will not cause an error to be returned.
There are some restrictions on resource updates in files that contain Resource Configuration(RC Config) data: LN
files and the associated .mui files. Details on which types of resources are allowed to be updated in these files are in
the Remarks section for the UpdateResource function.
This function can update resources within modules that contain both code and resources. As noted above, there are
restrictions on resource updates in LN files and .mui files, both of which contain RC Config data; details of the
restrictions are in the reference for the UpdateResource function.
Examples
For an example see, Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EndUpdateResource
Reference
Resources
UpdateResource
minutes to read • Edit Online
Retrieves a handle that can be used by the UpdateResource function to add, delete, or replace resources in a binary
module.
Syntax
HANDLE BeginUpdateResourceW(
LPCWSTR pFileName,
BOOL
bDeleteExistingResources
);
Parameters
pFileName
Type: LPCTSTR
The binary file in which to update resources. An application must be able to obtain write-access to this file; the file
referenced by pFileName cannot be currently executing. If pFileName does not specify a full path, the system
searches for the file in the current directory.
bDeleteExistingResources
Type: BOOL
Indicates whether to delete the pFileName parameter's existing resources. If this parameter is TRUE , existing
resources are deleted and the updated file includes only resources added with the UpdateResource function. If this
parameter is FALSE , the updated file includes existing resources unless they are explicitly deleted or replaced by
using UpdateResource .
Return value
Type: HANDLE
If the function succeeds, the return value is a handle that can be used by the UpdateResource and
EndUpdateResource functions. The return value is NULL if the specified file is not a PE, the file does not exist, or the
file cannot be opened for writing. To get extended error information, call GetLastError.
Remarks
It is recommended that the resource file is not loaded before this function is called. However, if that file is already
loaded, it will not cause an error to be returned.
There are some restrictions on resource updates in files that contain Resource Configuration(RC Config) data: LN
files and the associated .mui files. Details on which types of resources are allowed to be updated in these files are in
the Remarks section for the UpdateResource function.
This function can update resources within modules that contain both code and resources. As noted above, there are
restrictions on resource updates in LN files and .mui files, both of which contain RC Config data; details of the
restrictions are in the reference for the UpdateResource function.
Examples
For an example see, Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EndUpdateResource
Reference
Resources
UpdateResource
minutes to read • Edit Online
Commits or discards changes made prior to a call to UpdateResource.
Syntax
BOOL EndUpdateResourceA(
HANDLE hUpdate,
BOOL fDiscard
);
Parameters
hUpdate
Type: HANDLE
A module handle returned by the BeginUpdateResource function, and used by UpdateResource, referencing the file
to be updated.
fDiscard
Type: BOOL
Indicates whether to write the resource updates to the file. If this parameter is TRUE , no changes are made. If it is
FALSE , the changes are made: the resource updates will take effect.
Return value
Type: BOOL
Returns TRUE if the function succeeds; FALSE otherwise. If the function succeeds and
fDiscard is TRUE , then no resource updates are made to the file; otherwise all
successful resource updates are made to the file. To get extended error information, call GetLastError.
Remarks
Before you call this function, make sure all file handles other than the one returned by BeginUpdateResource are
closed.
This function can update resources within modules that contain both code and resources. There are restrictions on
resource updates in LN files and .mui files, both of which contain Resource Configuration data; details of the
restrictions are in the reference for the UpdateResource function.
Examples
For an example, see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
BeginUpdateResource
Conceptual
Reference
Resources
UpdateResource
minutes to read • Edit Online
Commits or discards changes made prior to a call to UpdateResource.
Syntax
BOOL EndUpdateResourceW(
HANDLE hUpdate,
BOOL fDiscard
);
Parameters
hUpdate
Type: HANDLE
A module handle returned by the BeginUpdateResource function, and used by UpdateResource, referencing the file
to be updated.
fDiscard
Type: BOOL
Indicates whether to write the resource updates to the file. If this parameter is TRUE , no changes are made. If it is
FALSE , the changes are made: the resource updates will take effect.
Return value
Type: BOOL
Returns TRUE if the function succeeds; FALSE otherwise. If the function succeeds and
fDiscard is TRUE , then no resource updates are made to the file; otherwise all
successful resource updates are made to the file. To get extended error information, call GetLastError.
Remarks
Before you call this function, make sure all file handles other than the one returned by BeginUpdateResource are
closed.
This function can update resources within modules that contain both code and resources. There are restrictions on
resource updates in LN files and .mui files, both of which contain Resource Configuration data; details of the
restrictions are in the reference for the UpdateResource function.
Examples
For an example, see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
BeginUpdateResource
Conceptual
Reference
Resources
UpdateResource
minutes to read • Edit Online
Enumerates language-specific resources, of the specified type and name, associated with a binary module.
Syntax
BOOL EnumResourceLanguagesA(
HMODULE
hModule,
LPCSTR
lpType,
LPCSTR
lpName,
ENUMRESLANGPROCA lpEnumFunc,
LONG_PTR
lParam
);
Parameters
hModule
Type: HMODULE
The handle to a module to be searched. Starting with Windows Vista, if this is a language-neutral Portable
Executable (LN file), then appropriate .mui files (if any exist) are included in the search. If this is a specific .mui file,
only that file is searched for resources.
If this parameter is NULL , that is equivalent to passing in a handle to the module used to create the current
process.
lpType
Type: LPCTSTR
The type of resource for which the language is being enumerated. Alternately, rather than a pointer, this parameter
can be MAKEINTRESOURCE(ID), where ID is an integer value representing a predefined resource type. For a list of
predefined resource types, see Resource Types. For more information, see
the Remarks section below.
lpName
Type: LPCTSTR
The name of the resource for which the language is being enumerated. Alternately, rather than a pointer, this
parameter can be MAKEINTRESOURCE(ID), where ID is the integer identifier of the resource. For more information,
see the Remarks section below.
lpEnumFunc
Type: ENUMRESL ANGPROC
A pointer to the callback function to be called for each enumerated resource language. For more information, see
EnumResLangProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
Return value
Type: BOOL
Returns TRUE if successful or FALSE otherwise. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpType) is TRUE , then lpType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
Similarly, if IS_INTRESOURCE(lpName) is TRUE , then lpName specifies the integer identifier of the given resource.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource.
Starting with Windows Vista, the binary module is typically a language-neutral Portable Executable (LN file), and
the enumeration will also include resources from the corresponding language-specific resource files (.mui files) that
contain localizable language resources.
For each resource found, EnumResourceLanguages calls an application-defined callback function lpEnumFunc,
passing the language identifier (see Language Identifiers) of the language for which a resource was found, as well
as the various other parameters that were passed to EnumResourceLanguages .
Alternately, applications can call EnumResourceLanguagesEx, which provides more precise control of what
resources are enumerated.
The EnumResourceLanguages function continues to enumerate resource languages until the callback function
returns FALSE or all resource languages have been enumerated.
In Windows Vista and later, if hModule specifies an LN file, then the resources enumerated can reside either in the
LN file or in an .mui file associated with it. If no .mui files are found, only resources from the LN file are returned.
Unlike EnumResourceNames and EnumResourceTypes, this search will look at multiple .mui files. The enumeration
begins with .mui files in the folders associated with EnumUILanguages. These are followed by any other .mui files
whose paths conform to the scheme described at MUI Resource Management. Finally, the file designated by
hModule is also searched.
The enumeration never includes duplicates: if a resource with the same name, type, and language is contained in
both the LN file and in an .mui file, the resource will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResLangProc
EnumResourceLanguagesEx
EnumResourceNames
EnumResourceTypes
Reference
Resources
minutes to read • Edit Online
Enumerates language-specific resources, of the specified type and name, associated with a binary module.
Syntax
BOOL EnumResourceLanguagesW(
HMODULE
hModule,
LPCWSTR
lpType,
LPCWSTR
lpName,
ENUMRESLANGPROCW lpEnumFunc,
LONG_PTR
lParam
);
Parameters
hModule
Type: HMODULE
The handle to a module to be searched. Starting with Windows Vista, if this is a language-neutral Portable
Executable (LN file), then appropriate .mui files (if any exist) are included in the search. If this is a specific .mui file,
only that file is searched for resources.
If this parameter is NULL , that is equivalent to passing in a handle to the module used to create the current
process.
lpType
Type: LPCTSTR
The type of resource for which the language is being enumerated. Alternately, rather than a pointer, this parameter
can be MAKEINTRESOURCE(ID), where ID is an integer value representing a predefined resource type. For a list of
predefined resource types, see Resource Types. For more information, see
the Remarks section below.
lpName
Type: LPCTSTR
The name of the resource for which the language is being enumerated. Alternately, rather than a pointer, this
parameter can be MAKEINTRESOURCE(ID), where ID is the integer identifier of the resource. For more information,
see the Remarks section below.
lpEnumFunc
Type: ENUMRESL ANGPROC
A pointer to the callback function to be called for each enumerated resource language. For more information, see
EnumResLangProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
Return value
Type: BOOL
Returns TRUE if successful or FALSE otherwise. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpType) is TRUE , then lpType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
Similarly, if IS_INTRESOURCE(lpName) is TRUE , then lpName specifies the integer identifier of the given resource.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource.
Starting with Windows Vista, the binary module is typically a language-neutral Portable Executable (LN file), and
the enumeration will also include resources from the corresponding language-specific resource files (.mui files) that
contain localizable language resources.
For each resource found, EnumResourceLanguages calls an application-defined callback function lpEnumFunc,
passing the language identifier (see Language Identifiers) of the language for which a resource was found, as well
as the various other parameters that were passed to EnumResourceLanguages .
Alternately, applications can call EnumResourceLanguagesEx, which provides more precise control of what
resources are enumerated.
The EnumResourceLanguages function continues to enumerate resource languages until the callback function
returns FALSE or all resource languages have been enumerated.
In Windows Vista and later, if hModule specifies an LN file, then the resources enumerated can reside either in the
LN file or in an .mui file associated with it. If no .mui files are found, only resources from the LN file are returned.
Unlike EnumResourceNames and EnumResourceTypes, this search will look at multiple .mui files. The enumeration
begins with .mui files in the folders associated with EnumUILanguages. These are followed by any other .mui files
whose paths conform to the scheme described at MUI Resource Management. Finally, the file designated by
hModule is also searched.
The enumeration never includes duplicates: if a resource with the same name, type, and language is contained in
both the LN file and in an .mui file, the resource will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResLangProc
EnumResourceLanguagesEx
EnumResourceNames
EnumResourceTypes
Reference
Resources
minutes to read • Edit Online
Enumerates resources of a specified type within a binary module. For Windows Vista and later, this is typically a
language-neutral Portable Executable (LN file), and the enumeration will also include resources from the
corresponding language-specific resource files (.mui files) that contain localizable language resources. It is also
possible for hModule to specify an .mui file, in which case only that file is searched for resources.
Syntax
BOOL EnumResourceNamesA(
HMODULE
hModule,
LPCSTR
lpType,
ENUMRESNAMEPROCA lpEnumFunc,
LONG_PTR
lParam
);
Parameters
hModule
Type: HMODULE
A handle to a module to be searched. Starting with Windows Vista, if this is an LN file, then appropriate .mui files (if
any exist) are included in the search.
If this parameter is NULL , that is equivalent to passing in a handle to the module used to create the current
process.
lpType
Type: LPCTSTR
The type of the resource for which the name is being enumerated. Alternately, rather than a pointer, this parameter
can be MAKEINTRESOURCE(ID), where ID is an integer value representing a predefined resource type. For a list of
predefined resource types, see Resource Types. For more information, see
the Remarks section below.
lpEnumFunc
Type: ENUMRESNAMEPROC
A pointer to the callback function to be called for each enumerated resource name or ID. For more information, see
EnumResNameProc.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function. This parameter can be used in error checking.
Return value
Type: BOOL
The return value is TRUE if the function succeeds or FALSE if the function does not find a resource of the type
specified, or if the function fails for another reason. To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpszType) is TRUE , then lpszType specifies the integer identifier of the given resource type.
Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the
remaining characters represent a decimal number that specifies the
integer identifier of the resource type. For example, the string "#258" represents the identifier 258.
For each resource found, EnumResourceNames calls an application-defined callback function lpEnumFunc,
passing the name or the ID of each resource it finds, as well as the various other parameters that were passed to
EnumResourceNames .
Alternately, applications can call EnumResourceNamesEx, which provides more precise control of what resources
are enumerated.
If a resource has an ID, the ID is passed to the callback function; otherwise the resource name is passed to the
callback function. For more information, see EnumResNameProc.
The EnumResourceNames function continues to enumerate resources until the callback function returns FALSE
or all resources have been enumerated.
Starting with Windows Vista, if hModule specifies an LN file, then the resources enumerated can reside either in the
LN file or in a .mui file associated with it. If no .mui files are found, only resources from the LN file are returned. The
order in which .mui files are searched is the usual Resource Loader search order; see User Interface Language
Management for details. Once one appropriate .mui file is found, the .mui file search stops. Because all .mui files
that correspond to a single LN file have the same resource types, only the resources in the found .mui file need to
be enumerated.
The enumeration never includes duplicates: if resources with the same name are contained in both the LN file and
in an .mui file, the resource will only be enumerated once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResNameProc
EnumResourceLanguages
EnumResourceNamesEx
EnumResourceTypes
Reference
Resources
minutes to read • Edit Online
Enumerates resource types within a binary module. Starting with Windows Vista, this is typically a languageneutral Portable Executable (LN file), and the enumeration also includes resources from one of the corresponding
language-specific resource files (.mui files)—if one exists—that contain localizable language resources. It is also
possible to use hModule to specify a .mui file, in which case only that file is searched for resource types.
Alternately, applications can call EnumResourceTypesEx, which provides more precise control over which resource
files to enumerate.
Syntax
BOOL EnumResourceTypesA(
HMODULE
hModule,
ENUMRESTYPEPROCA lpEnumFunc,
LONG_PTR
lParam
);
Parameters
hModule
Type: HMODULE
A handle to a module to be searched. This handle must be obtained through LoadLibrary or LoadLibraryEx.
See Remarks for more information.
If this parameter is NULL , that is equivalent to passing in a handle to the module used to create the current
process.
lpEnumFunc
Type: ENUMRESTYPEPROC
A pointer to the callback function to be called for each enumerated resource type. For more information, see the
EnumResTypeProc function.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function.
Return value
Type: BOOL
Returns TRUE if successful; otherwise, FALSE . To get extended error information, call GetLastError.
Remarks
For each resource type found, EnumResourceTypes calls an application-defined callback function lpEnumFunc,
passing each resource type it finds, as well as the various other parameters that were passed to
EnumResourceTypes .
EnumResourceTypes continues to enumerate resource types until the callback function returns FALSE or all
resource types have been enumerated.
Starting with Windows Vista, if hModule specifies an LN file, then the types enumerated correspond to resources
that reside in the LN file and in the .mui file associated with it. If no .mui files are found, only types from the LN file
are returned. The order in which .mui files are searched is the usual Resource Loader search order; see User
Interface Language Management for details. After one appropriate .mui file is found, the search does not continue
further to other .mui files associated with the LN file, because all .mui files that correspond to a single LN file have
the same set of resource types.
The enumeration never includes duplicates: if a given resource type is contained in both the LN file and in an .mui
file, the type is enumerated only once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResTypeProc
EnumResourceLanguages
EnumResourceNames
EnumResourceTypesEx
Reference
Resources
minutes to read • Edit Online
Enumerates resource types within a binary module. Starting with Windows Vista, this is typically a languageneutral Portable Executable (LN file), and the enumeration also includes resources from one of the corresponding
language-specific resource files (.mui files)—if one exists—that contain localizable language resources. It is also
possible to use hModule to specify a .mui file, in which case only that file is searched for resource types.
Alternately, applications can call EnumResourceTypesEx, which provides more precise control over which resource
files to enumerate.
Syntax
BOOL EnumResourceTypesW(
HMODULE
hModule,
ENUMRESTYPEPROCW lpEnumFunc,
LONG_PTR
lParam
);
Parameters
hModule
Type: HMODULE
A handle to a module to be searched. This handle must be obtained through LoadLibrary or LoadLibraryEx.
See Remarks for more information.
If this parameter is NULL , that is equivalent to passing in a handle to the module used to create the current
process.
lpEnumFunc
Type: ENUMRESTYPEPROC
A pointer to the callback function to be called for each enumerated resource type. For more information, see the
EnumResTypeProc function.
lParam
Type: LONG_PTR
An application-defined value passed to the callback function.
Return value
Type: BOOL
Returns TRUE if successful; otherwise, FALSE . To get extended error information, call GetLastError.
Remarks
For each resource type found, EnumResourceTypes calls an application-defined callback function lpEnumFunc,
passing each resource type it finds, as well as the various other parameters that were passed to
EnumResourceTypes .
EnumResourceTypes continues to enumerate resource types until the callback function returns FALSE or all
resource types have been enumerated.
Starting with Windows Vista, if hModule specifies an LN file, then the types enumerated correspond to resources
that reside in the LN file and in the .mui file associated with it. If no .mui files are found, only types from the LN file
are returned. The order in which .mui files are searched is the usual Resource Loader search order; see User
Interface Language Management for details. After one appropriate .mui file is found, the search does not continue
further to other .mui files associated with the LN file, because all .mui files that correspond to a single LN file have
the same set of resource types.
The enumeration never includes duplicates: if a given resource type is contained in both the LN file and in an .mui
file, the type is enumerated only once.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
EnumResTypeProc
EnumResourceLanguages
EnumResourceNames
EnumResourceTypesEx
Reference
Resources
minutes to read • Edit Online
Determines the location of a resource with the specified type and name in the specified module.
To specify a language, use the FindResourceEx function.
Syntax
HRSRC FindResourceA(
HMODULE hModule,
LPCSTR lpName,
LPCSTR lpType
);
Parameters
hModule
Type: HMODULE
A handle to the module whose portable executable file or an accompanying MUI file contains the resource. If this
parameter is NULL , the function searches the module used to create the current process.
lpName
Type: LPCTSTR
The name of the resource. Alternately, rather than a pointer, this parameter can be MAKEINTRESOURCE(ID), where
ID is the integer identifier of the resource. For more information, see the Remarks section below.
lpType
Type: LPCTSTR
The resource type. Alternately, rather than a pointer, this parameter can be MAKEINTRESOURCE(ID), where ID is the
integer identifier of the given
resource type. For standard resource types, see Resource Types. For more information, see the Remarks section
below.
Return value
Type: HRSRC
If the function succeeds, the return value is a handle to the specified resource's information block. To obtain a
handle to the resource, pass this handle to the LoadResource function.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE is TRUE for x = lpName or lpType, x 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.
To reduce the amount of memory required for a resource, an application should refer to it by integer identifier
instead of by name.
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 by making subsequent calls to LoadResource and then to
LockResource.
To use a resource immediately, an application should use one of the following resource-specific functions to find
the resource and convert the data into a more usable form.
F UN C T IO N
A C T IO N
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 necessarily null-terminated) Unicode strings. The LoadString function will extract the
string resource from its corresponding section.
Examples
For an example, see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
See also
Conceptual
FindResourceEx
FormatMessage
IS_INTRESOURCE
LoadAccelerators
LoadBitmap
LoadCursor
LoadIcon
LoadMenu
LoadResource
LoadString
LockResource
Other Resources
Reference
Resources
SizeofResource
Kernel32.dll
minutes to read • Edit Online
Determines the location of the resource with the specified type, name, and language in the specified module.
Syntax
HRSRC FindResourceExA(
HMODULE hModule,
LPCSTR lpType,
LPCSTR lpName,
WORD
wLanguage
);
Parameters
hModule
Type: HMODULE
A handle to the module whose portable executable file or an accompanying MUI file contains the resource. If this
parameter is NULL , the function searches the module used to create the current process.
lpType
Type: LPCTSTR
The resource type. Alternately, rather than a pointer, this parameter can be MAKEINTRESOURCE(ID), where ID is the
integer identifier of the given
resource type. For standard resource types, see Resource Types. For more information, see the Remarks section
below.
lpName
Type: LPCTSTR
The name of the resource. Alternately, rather than a pointer, this parameter can be MAKEINTRESOURCE(ID), where
ID is the integer identifier of the resource. For more information, see the Remarks section below.
wLanguage
Type: WORD
The language of the resource. If this parameter is
associated with the calling thread is used.
MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)
, the current language
To specify a language other than the current language, use the MAKELANGID macro to create this parameter. For
more information, see MAKEL ANGID .
Return value
Type: HRSRC
If the function succeeds, the return value is a handle to the specified resource's information block. To obtain a
handle to the resource, pass this handle to the LoadResource function.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE is TRUE for x = lpType or lpName, x specifies the integer identifier of the type or name 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.
To reduce the amount of memory required for a resource, an application should refer to it by integer identifier
instead of by name.
An application can use FindResourceEx to find any type of resource, but this function should be used only if the
application must access the binary resource data by making subsequent calls to LoadResource and then to
LockResource.
To use a resource immediately, an application should use one of the following resource-specific functions to find
the resource and convert the data into a more usable form.
F UN C T IO N
A C T IO N
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 FindResourceEx 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 necessarily null-terminated) Unicode strings. The LoadString function will extract the
string resource from its corresponding section.
Examples
For an example, see Creating a Resource List.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
FindResource
FormatMessage
IS_INTRESOURCE
LoadAccelerators
LoadBitmap
LoadCursor
LoadIcon
LoadMenu
LoadResource
LoadString
MAKELANGID
Other Resources
Reference
Resources
minutes to read • Edit Online
Appends one string to another.
Warning Do not use. Consider using StringCchCat instead. See Security Considerations.
Syntax
LPSTR lstrcatA(
LPSTR lpString1,
LPCSTR lpString2
);
Parameters
lpString1
Type: LPTSTR
The first null-terminated string. This buffer must be large enough to contain both strings.
lpString2
Type: LPTSTR
The null-terminated string to be appended to the string specified in the lpString1 parameter.
Return value
Type: LPTSTR
If the function succeeds, the return value is a pointer to the buffer.
If the function fails, the return value is NULL and lpString1 may not be null-terminated.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
See also
Conceptual
Reference
StringCbCat
StringCbCatEx
StringCbCatN
StringCbCatNEx
StringCchCat
StringCchCatEx
StringCchCatN
StringCchCatNEx
Strings
lstrcmp
lstrcmpi
lstrlen
Kernel32.dll
minutes to read • Edit Online
Appends one string to another.
Warning Do not use. Consider using StringCchCat instead. See Security Considerations.
Syntax
LPWSTR lstrcatW(
LPWSTR lpString1,
LPCWSTR lpString2
);
Parameters
lpString1
Type: LPTSTR
The first null-terminated string. This buffer must be large enough to contain both strings.
lpString2
Type: LPTSTR
The null-terminated string to be appended to the string specified in the lpString1 parameter.
Return value
Type: LPTSTR
If the function succeeds, the return value is a pointer to the buffer.
If the function fails, the return value is NULL and lpString1 may not be null-terminated.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
See also
Conceptual
Reference
StringCbCat
StringCbCatEx
StringCbCatN
StringCbCatNEx
StringCchCat
StringCchCatEx
StringCchCatN
StringCchCatNEx
Strings
lstrcmp
lstrcmpi
lstrlen
Kernel32.dll
minutes to read • Edit Online
Compares two character strings. The comparison is case-sensitive.
To perform a comparison that is not case-sensitive, use the lstrcmpi function.
Syntax
int lstrcmpA(
LPCSTR lpString1,
LPCSTR lpString2
);
Parameters
lpString1
Type: LPCTSTR
The first null-terminated string to be compared.
lpString2
Type: LPCTSTR
The second null-terminated string to be compared.
Return value
Type: int
If the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative. If the
string pointed to by lpString1 is greater than the string pointed to by lpString2, the return value is positive. If the
strings are equal, the return value is zero.
Remarks
The lstrcmp function compares two strings by checking the first characters against each other, the second
characters against each other, and so on until it finds an inequality or reaches the ends of the strings.
Note that the lpString1 and lpString2 parameters must be null-terminated, otherwise the string comparison can be
incorrect.
The function calls CompareStringEx, using the current thread locale, and subtracts 2 from the result, to maintain the
C run-time conventions for comparing strings.
The language (user locale) selected by the user at setup time, or through Control Panel, determines which string is
greater (or whether the strings are the same). If no language (user locale) is selected, the system performs the
comparison by using default values.
With a double-byte character set (DBCS) version of the system, this function can compare two DBCS strings.
The lstrcmp function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes
differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as "coop" and
"co-op" stay together within a sorted list. For a detailed discussion of word sorts and string sorts, see Handling
Sorting in Your Applications.
Security Remarks
See Security Considerations: International Features for security considerations regarding
choice of comparison functions.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
CompareString
CompareStringEx
CompareStringOrdinal
Conceptual
Other Resources
Reference
Strings
lstrcat
lstrcmpi
lstrcpy
lstrlen
minutes to read • Edit Online
Compares two character strings. The comparison is not case-sensitive.
To perform a comparison that is case-sensitive, use the lstrcmp function.
Syntax
int lstrcmpiA(
LPCSTR lpString1,
LPCSTR lpString2
);
Parameters
lpString1
Type: LPCTSTR
The first null-terminated string to be compared.
lpString2
Type: LPCTSTR
The second null-terminated string to be compared.
Return value
Type: int
If the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative. If the
string pointed to by lpString1 is greater than the string pointed to by lpString2, the return value is positive. If the
strings are equal, the return value is zero.
Remarks
The lstrcmpi function compares two strings by checking the first characters against each other, the second
characters against each other, and so on until it finds an inequality or reaches the ends of the strings.
Note that the lpString1 and lpString2 parameters must be null-terminated, otherwise the string comparison can be
incorrect.
The function calls CompareStringEx, using the current thread locale, and subtracts 2 from the result, to maintain the
C run-time conventions for comparing strings.
For some locales, the lstrcmpi function may be insufficient. If this occurs, use CompareStringEx to ensure proper
comparison. For example, in Japan call with the NORM_IGNORECASE , NORM_IGNOREKANATYPE , and
NORM_IGNOREWIDTH values to achieve the most appropriate non-exact string comparison. The
NORM_IGNOREKANATYPE and NORM_IGNOREWIDTH values are ignored in non-Asian locales, so you can set
these values for all locales and be guaranteed to have a culturally correct "insensitive" sorting regardless of the
locale. Note that specifying these values slows performance, so use them only when necessary.
With a double-byte character set (DBCS) version of the system, this function can compare two DBCS strings.
The lstrcmpi function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes
differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as "coop" and
"co-op" stay together within a sorted list. For a detailed discussion of word sorts and string sorts, see Handling
Sorting in Your Applications.
Security Remarks
See Security Considerations: International Features for security considerations regarding
choice of comparison functions.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
CompareString
CompareStringEx
CompareStringOrdinal
Conceptual
Other Resources
Reference
Strings
lstrcat
lstrcmp
lstrcpy
lstrlen
minutes to read • Edit Online
Compares two character strings. The comparison is not case-sensitive.
To perform a comparison that is case-sensitive, use the lstrcmp function.
Syntax
int lstrcmpiW(
LPCWSTR lpString1,
LPCWSTR lpString2
);
Parameters
lpString1
Type: LPCTSTR
The first null-terminated string to be compared.
lpString2
Type: LPCTSTR
The second null-terminated string to be compared.
Return value
Type: int
If the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative. If the
string pointed to by lpString1 is greater than the string pointed to by lpString2, the return value is positive. If the
strings are equal, the return value is zero.
Remarks
The lstrcmpi function compares two strings by checking the first characters against each other, the second
characters against each other, and so on until it finds an inequality or reaches the ends of the strings.
Note that the lpString1 and lpString2 parameters must be null-terminated, otherwise the string comparison can be
incorrect.
The function calls CompareStringEx, using the current thread locale, and subtracts 2 from the result, to maintain the
C run-time conventions for comparing strings.
For some locales, the lstrcmpi function may be insufficient. If this occurs, use CompareStringEx to ensure proper
comparison. For example, in Japan call with the NORM_IGNORECASE , NORM_IGNOREKANATYPE , and
NORM_IGNOREWIDTH values to achieve the most appropriate non-exact string comparison. The
NORM_IGNOREKANATYPE and NORM_IGNOREWIDTH values are ignored in non-Asian locales, so you can set
these values for all locales and be guaranteed to have a culturally correct "insensitive" sorting regardless of the
locale. Note that specifying these values slows performance, so use them only when necessary.
With a double-byte character set (DBCS) version of the system, this function can compare two DBCS strings.
The lstrcmpi function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes
differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as "coop" and
"co-op" stay together within a sorted list. For a detailed discussion of word sorts and string sorts, see Handling
Sorting in Your Applications.
Security Remarks
See Security Considerations: International Features for security considerations regarding
choice of comparison functions.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
CompareString
CompareStringEx
CompareStringOrdinal
Conceptual
Other Resources
Reference
Strings
lstrcat
lstrcmp
lstrcpy
lstrlen
minutes to read • Edit Online
Compares two character strings. The comparison is case-sensitive.
To perform a comparison that is not case-sensitive, use the lstrcmpi function.
Syntax
int lstrcmpW(
LPCWSTR lpString1,
LPCWSTR lpString2
);
Parameters
lpString1
Type: LPCTSTR
The first null-terminated string to be compared.
lpString2
Type: LPCTSTR
The second null-terminated string to be compared.
Return value
Type: int
If the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative. If the
string pointed to by lpString1 is greater than the string pointed to by lpString2, the return value is positive. If the
strings are equal, the return value is zero.
Remarks
The lstrcmp function compares two strings by checking the first characters against each other, the second
characters against each other, and so on until it finds an inequality or reaches the ends of the strings.
Note that the lpString1 and lpString2 parameters must be null-terminated, otherwise the string comparison can be
incorrect.
The function calls CompareStringEx, using the current thread locale, and subtracts 2 from the result, to maintain the
C run-time conventions for comparing strings.
The language (user locale) selected by the user at setup time, or through Control Panel, determines which string is
greater (or whether the strings are the same). If no language (user locale) is selected, the system performs the
comparison by using default values.
With a double-byte character set (DBCS) version of the system, this function can compare two DBCS strings.
The lstrcmp function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes
differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as "coop" and
"co-op" stay together within a sorted list. For a detailed discussion of word sorts and string sorts, see Handling
Sorting in Your Applications.
Security Remarks
See Security Considerations: International Features for security considerations regarding
choice of comparison functions.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
CompareString
CompareStringEx
CompareStringOrdinal
Conceptual
Other Resources
Reference
Strings
lstrcat
lstrcmpi
lstrcpy
lstrlen
minutes to read • Edit Online
Copies a string to a buffer.
Warning Do not use. Consider using StringCchCopy instead. See Remarks.
Syntax
LPSTR lstrcpyA(
LPSTR lpString1,
LPCSTR lpString2
);
Parameters
lpString1
Type: LPTSTR
A buffer to receive the contents of the string pointed to by the lpString2 parameter. The buffer must be large
enough to contain the string, including the terminating null character.
lpString2
Type: LPTSTR
The null-terminated string to be copied.
Return value
Type: LPTSTR
If the function succeeds, the return value is a pointer to the buffer.
If the function fails, the return value is NULL and lpString1 may not be null-terminated.
Remarks
With a double-byte character set (DBCS) version of the system, this function can be used to copy a DBCS string.
The lstrcpy function has an undefined behavior if source and destination buffers overlap.
Security Remarks
Using this function incorrectly can compromise the security of your application. This function uses structured exception
handling (SEH) to catch access violations and other errors. When this function catches SEH errors, it returns NULL
without null-terminating the string and without notifying the caller of the error. The caller is not safe to assume that
insufficient space is the error condition.
lpString1 must be large enough to hold lpString2 and the closing '\0', otherwise a buffer overrun may occur.
Buffer overflow situations are the cause of many security problems in applications and can cause a denial of service
attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker
to inject executable code into your process, especially if lpString1 is a stack-based buffer.
Consider using StringCchCopy instead; use either StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src); ,
being aware that buffer must not be a pointer or use StringCchCopy(buffer, ARRAYSIZE(buffer), src); , being
aware that, when copying to a pointer, the caller is responsible for passing in the size of the pointed-to memory in
characters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
Reference
StringCbCopy
StringCbCopyEx
StringCbCopyN
StringCbCopyNEx
StringCchCopy
StringCchCopyEx
StringCchCopyN
StringCchCopyNEx
Strings
lstrcmp
lstrcmpi
lstrlen
minutes to read • Edit Online
Copies a specified number of characters from a source string into a buffer.
Warning Do not use. Consider using StringCchCopy instead. See Remarks.
Syntax
LPSTR lstrcpynA(
LPSTR lpString1,
LPCSTR lpString2,
int
iMaxLength
);
Parameters
lpString1
Type: LPTSTR
The destination buffer, which receives the copied characters. The buffer must be large enough to contain the
number of TCHAR values specified by iMaxLength, including room for a terminating null character.
lpString2
Type: LPCTSTR
The source string from which the function is to copy characters.
iMaxLength
Type: int
The number of TCHAR values to be copied from the string pointed to by lpString2 into the buffer pointed to by
lpString1, including a terminating null character.
Return value
Type: LPTSTR
If the function succeeds, the return value is a pointer to the buffer. The function can succeed even if the source
string is greater than iMaxLength characters.
If the function fails, the return value is NULL and lpString1 may not be null-terminated.
Remarks
The buffer pointed to by lpString1 must be large enough to include a terminating null character, and the string
length value specified by iMaxLength includes room for a terminating null character.
The lstrcpyn function has an undefined behavior if source and destination buffers overlap.
Security Warning
Using this function incorrectly can compromise the security of your application. This function uses structured exception
handling (SEH) to catch access violations and other errors. When this function catches SEH errors, it returns NULL
without null-terminating the string and without notifying the caller of the error. The caller is not safe to assume that
insufficient space is the error condition.
If the buffer pointed to by lpString1 is not large enough to contain the copied string, a buffer overrun can occur.
When copying an entire string, note that sizeof returns the number of bytes. For example, if lpString1 points to a
buffer szString1 which is declared as TCHAR szString[100] , then sizeof(szString1) gives the size of the buffer in
bytes rather than WCHAR , which could lead to a buffer overflow for the Unicode version of the function.
Buffer overflow situations are the cause of many security problems in applications and can cause a denial of service
attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker
to inject executable code into your process, especially if lpString1 is a stack-based buffer.
Using
sizeof(szString1)/sizeof(szString1[0])
gives the proper size of the buffer.
Consider using StringCchCopy instead; use either StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src); ,
being aware that buffer must not be a pointer or use StringCchCopy(buffer, ARRAYSIZE(buffer), src); , being
aware that, when copying to a pointer, the caller is responsible for passing in the size of the pointed-to memory in
characters.
Review Security Considerations: Windows User Interface before continuing.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
Reference
StringCbCopy
StringCbCopyEx
StringCbCopyN
StringCbCopyNEx
StringCbLength
StringCchCopy
StringCchCopyEx
StringCchCopyN
StringCchCopyNEx
StringCchLength
Strings
lstrcmp
lstrcmpi
lstrlen
minutes to read • Edit Online
Copies a specified number of characters from a source string into a buffer.
Warning Do not use. Consider using StringCchCopy instead. See Remarks.
Syntax
LPWSTR lstrcpynW(
LPWSTR lpString1,
LPCWSTR lpString2,
int
iMaxLength
);
Parameters
lpString1
Type: LPTSTR
The destination buffer, which receives the copied characters. The buffer must be large enough to contain the
number of TCHAR values specified by iMaxLength, including room for a terminating null character.
lpString2
Type: LPCTSTR
The source string from which the function is to copy characters.
iMaxLength
Type: int
The number of TCHAR values to be copied from the string pointed to by lpString2 into the buffer pointed to by
lpString1, including a terminating null character.
Return value
Type: LPTSTR
If the function succeeds, the return value is a pointer to the buffer. The function can succeed even if the source
string is greater than iMaxLength characters.
If the function fails, the return value is NULL and lpString1 may not be null-terminated.
Remarks
The buffer pointed to by lpString1 must be large enough to include a terminating null character, and the string
length value specified by iMaxLength includes room for a terminating null character.
The lstrcpyn function has an undefined behavior if source and destination buffers overlap.
Security Warning
Using this function incorrectly can compromise the security of your application. This function uses structured exception
handling (SEH) to catch access violations and other errors. When this function catches SEH errors, it returns NULL
without null-terminating the string and without notifying the caller of the error. The caller is not safe to assume that
insufficient space is the error condition.
If the buffer pointed to by lpString1 is not large enough to contain the copied string, a buffer overrun can occur.
When copying an entire string, note that sizeof returns the number of bytes. For example, if lpString1 points to a
buffer szString1 which is declared as TCHAR szString[100] , then sizeof(szString1) gives the size of the buffer in
bytes rather than WCHAR , which could lead to a buffer overflow for the Unicode version of the function.
Buffer overflow situations are the cause of many security problems in applications and can cause a denial of service
attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker
to inject executable code into your process, especially if lpString1 is a stack-based buffer.
Using
sizeof(szString1)/sizeof(szString1[0])
gives the proper size of the buffer.
Consider using StringCchCopy instead; use either StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src); ,
being aware that buffer must not be a pointer or use StringCchCopy(buffer, ARRAYSIZE(buffer), src); , being
aware that, when copying to a pointer, the caller is responsible for passing in the size of the pointed-to memory in
characters.
Review Security Considerations: Windows User Interface before continuing.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
Reference
StringCbCopy
StringCbCopyEx
StringCbCopyN
StringCbCopyNEx
StringCbLength
StringCchCopy
StringCchCopyEx
StringCchCopyN
StringCchCopyNEx
StringCchLength
Strings
lstrcmp
lstrcmpi
lstrlen
minutes to read • Edit Online
Copies a string to a buffer.
Warning Do not use. Consider using StringCchCopy instead. See Remarks.
Syntax
LPWSTR lstrcpyW(
LPWSTR lpString1,
LPCWSTR lpString2
);
Parameters
lpString1
Type: LPTSTR
A buffer to receive the contents of the string pointed to by the lpString2 parameter. The buffer must be large
enough to contain the string, including the terminating null character.
lpString2
Type: LPTSTR
The null-terminated string to be copied.
Return value
Type: LPTSTR
If the function succeeds, the return value is a pointer to the buffer.
If the function fails, the return value is NULL and lpString1 may not be null-terminated.
Remarks
With a double-byte character set (DBCS) version of the system, this function can be used to copy a DBCS string.
The lstrcpy function has an undefined behavior if source and destination buffers overlap.
Security Remarks
Using this function incorrectly can compromise the security of your application. This function uses structured exception
handling (SEH) to catch access violations and other errors. When this function catches SEH errors, it returns NULL
without null-terminating the string and without notifying the caller of the error. The caller is not safe to assume that
insufficient space is the error condition.
lpString1 must be large enough to hold lpString2 and the closing '\0', otherwise a buffer overrun may occur.
Buffer overflow situations are the cause of many security problems in applications and can cause a denial of service
attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker
to inject executable code into your process, especially if lpString1 is a stack-based buffer.
Consider using StringCchCopy instead; use either StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src); ,
being aware that buffer must not be a pointer or use StringCchCopy(buffer, ARRAYSIZE(buffer), src); , being
aware that, when copying to a pointer, the caller is responsible for passing in the size of the pointed-to memory in
characters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
Reference
StringCbCopy
StringCbCopyEx
StringCbCopyN
StringCbCopyNEx
StringCchCopy
StringCchCopyEx
StringCchCopyN
StringCchCopyNEx
Strings
lstrcmp
lstrcmpi
lstrlen
minutes to read • Edit Online
Determines the length of the specified string (not including the terminating null character).
Syntax
int lstrlenA(
LPCSTR lpString
);
Parameters
lpString
Type: LPCTSTR
The null-terminated string to be checked.
Return value
Type: int
The function returns the length of the string, in characters. If lpString is NULL , the function returns 0.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
Reference
StringCbLength
StringCchLength
Strings
lstrcat
lstrcmp
lstrcmpi
lstrcpy
minutes to read • Edit Online
Determines the length of the specified string (not including the terminating null character).
Syntax
int lstrlenW(
LPCWSTR lpString
);
Parameters
lpString
Type: LPCTSTR
The null-terminated string to be checked.
Return value
Type: int
The function returns the length of the string, in characters. If lpString is NULL , the function returns 0.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
Conceptual
Reference
StringCbLength
StringCchLength
Strings
lstrcat
lstrcmp
lstrcmpi
lstrcpy
minutes to read • Edit Online
Adds, deletes, or replaces a resource in a portable executable (PE) file. There are some restrictions on resource
updates in files that contain Resource Configuration (RC Config) data: language-neutral (LN) files and languagespecific resource (.mui) files.
Syntax
BOOL UpdateResourceA(
HANDLE hUpdate,
LPCSTR lpType,
LPCSTR lpName,
WORD wLanguage,
LPVOID lpData,
DWORD cb
);
Parameters
hUpdate
Type: HANDLE
A module handle returned by the BeginUpdateResource function, referencing the file to be updated.
lpType
Type: LPCTSTR
The resource type to be updated. Alternatively, rather than a pointer, this parameter can be MAKEINTRESOURCE(ID),
where ID is an integer value representing a predefined resource type. If the first character of the string is a pound
sign (#), then the remaining characters represent a
decimal number that specifies the integer identifier of the resource type. For example, the string "#258" represents
the identifier 258.
For a list of predefined resource types, see Resource Types.
lpName
Type: LPCTSTR
The name of the resource to be updated. Alternatively, rather than a pointer, this parameter can be
MAKEINTRESOURCE(ID), where ID is a resource ID. When creating a new resource do not use a string that begins
with a '#' character for this parameter.
wLanguage
Type: WORD
The language identifier of the resource to be updated. For a list of the primary language identifiers and
sublanguage identifiers that make up a language identifier, see the MAKELANGID macro.
lpData
Type: LPVOID
The resource data to be inserted into the file indicated by hUpdate. If the resource is one of the predefined types,
the data must be valid and properly aligned. Note that this is the raw binary data to be stored in the file indicated
by hUpdate, not the data provided by LoadIcon, LoadString, or other resource-specific load functions. All data
containing strings or text must be in Unicode format. lpData must not point to ANSI data.
If lpData is NULL and cbData is 0, the specified resource is deleted from the file indicated by hUpdate.
cb
Type: DWORD
The size, in bytes, of the resource data at lpData.
Return value
Type: BOOL
Returns TRUE if successful or FALSE otherwise. To get extended error information, call GetLastError.
Remarks
It is recommended that the resource file is not loaded before this function is called. However, if that file is already
loaded, it will not cause an error to be returned.
An application can use UpdateResource repeatedly to make changes to the resource data. Each call to
UpdateResource contributes to an internal list of additions, deletions, and replacements but does not actually
write the data to the file indicated by hUpdate. The application must use the EndUpdateResource function to write
the accumulated changes to the file.
This function can update resources within modules that contain both code and resources.
Prior to Windows 7: If lpData is NULL and cbData is nonzero, the specified resource is NOT deleted and an
exception is thrown.
Star ting with Windows Vista: As noted above, there are restrictions on resource updates in files that contain RC
Config data: LN files and .mui files. The restrictions are as follows:
A C T IO N
L N F IL E
. M UI F IL E
1. Add a new type that doesn't exist in
the LN or .mui files.
Add type in the LN file and treat as
language-neutral (non-localizable) and
add new type or item in the RC Config
data
The only additions allowed are the
following types: file Version, RC Config
data, Side-by-side Assembly XML
Manifest.
2. Add a new resource item to an
existing type.
Uses the RC Config data to check
whether the type exists in the .mui files
associated with this LN file. If the type
doesn't exist in the .mui files, add the
item and treat new item as unlocalizable. If the type exists in the .mui
files, then adding is not allowed.
Only items of the following types may
be added: File Version, RC Config data,
Side-by-side Assembly XML Manifest.
3. Update a resource item.
Uses the RC Config data to check
whether the type exists in the .mui files
associated with the LN file. If the type
doesn't exist in the .mui files, then this
resource item update is allowed in the
LN file. Otherwise, if the type exists in
the .mui files associated with this LN file,
then this update is not allowed.
The only updates allowed are items of
the following types: file Version, RC
Config data, Side-by-side Assembly
XML Manifest.
4. Add a type/item for a new language.
Not allowed.
Not allowed.
5. Remove an existing type/item.
Works similarly to case 3. Uses the RC
Config data to check whether the type
exists in the .mui files associated with
the LN file. If not, then the removal of
the type/item from the LN file is
allowed. Otherwise, if the type/item
exists in the .mui files associated with
this LN file, then the removal is not
allowed.
The only types allowed to be removed
are: file Version, RC Config data, Sideby-side Assembly XML Manifest; also,
only items of these types may be
removed.
6. Add/delete/update a type not
included in the RC Config data (such as
Version, Side-by-side Assembly XML
Manifest, or RC Config data itself).
Allowed.
Allowed.
7. Other update of non-localizable data,
such as TYPELIB, reginst, and so on.
Update type or item in the LN file, treat
as non-localizable, and add new type or
item in the RC Config data.
Not applicable.
8. Add RC Config data.
Can be done but the integrity of the RC
Config data is not checked.
Can be done but the integrity of the RC
Config data is not checked.
Examples
For an example, see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
BeginUpdateResource
Conceptual
EndUpdateResource
LoadIcon
LoadString
LockResource
MAKEINTRESOURCE
MAKELANGID
Other Resources
Reference
Resources
SizeofResource
minutes to read • Edit Online
Adds, deletes, or replaces a resource in a portable executable (PE) file. There are some restrictions on resource
updates in files that contain Resource Configuration (RC Config) data: language-neutral (LN) files and languagespecific resource (.mui) files.
Syntax
BOOL UpdateResourceW(
HANDLE hUpdate,
LPCWSTR lpType,
LPCWSTR lpName,
WORD
wLanguage,
LPVOID lpData,
DWORD cb
);
Parameters
hUpdate
Type: HANDLE
A module handle returned by the BeginUpdateResource function, referencing the file to be updated.
lpType
Type: LPCTSTR
The resource type to be updated. Alternatively, rather than a pointer, this parameter can be MAKEINTRESOURCE(ID),
where ID is an integer value representing a predefined resource type. If the first character of the string is a pound
sign (#), then the remaining characters represent a
decimal number that specifies the integer identifier of the resource type. For example, the string "#258" represents
the identifier 258.
For a list of predefined resource types, see Resource Types.
lpName
Type: LPCTSTR
The name of the resource to be updated. Alternatively, rather than a pointer, this parameter can be
MAKEINTRESOURCE(ID), where ID is a resource ID. When creating a new resource do not use a string that begins
with a '#' character for this parameter.
wLanguage
Type: WORD
The language identifier of the resource to be updated. For a list of the primary language identifiers and
sublanguage identifiers that make up a language identifier, see the MAKELANGID macro.
lpData
Type: LPVOID
The resource data to be inserted into the file indicated by hUpdate. If the resource is one of the predefined types,
the data must be valid and properly aligned. Note that this is the raw binary data to be stored in the file indicated
by hUpdate, not the data provided by LoadIcon, LoadString, or other resource-specific load functions. All data
containing strings or text must be in Unicode format. lpData must not point to ANSI data.
If lpData is NULL and cbData is 0, the specified resource is deleted from the file indicated by hUpdate.
cb
Type: DWORD
The size, in bytes, of the resource data at lpData.
Return value
Type: BOOL
Returns TRUE if successful or FALSE otherwise. To get extended error information, call GetLastError.
Remarks
It is recommended that the resource file is not loaded before this function is called. However, if that file is already
loaded, it will not cause an error to be returned.
An application can use UpdateResource repeatedly to make changes to the resource data. Each call to
UpdateResource contributes to an internal list of additions, deletions, and replacements but does not actually
write the data to the file indicated by hUpdate. The application must use the EndUpdateResource function to write
the accumulated changes to the file.
This function can update resources within modules that contain both code and resources.
Prior to Windows 7: If lpData is NULL and cbData is nonzero, the specified resource is NOT deleted and an
exception is thrown.
Star ting with Windows Vista: As noted above, there are restrictions on resource updates in files that contain RC
Config data: LN files and .mui files. The restrictions are as follows:
A C T IO N
L N F IL E
. M UI F IL E
1. Add a new type that doesn't exist in
the LN or .mui files.
Add type in the LN file and treat as
language-neutral (non-localizable) and
add new type or item in the RC Config
data
The only additions allowed are the
following types: file Version, RC Config
data, Side-by-side Assembly XML
Manifest.
2. Add a new resource item to an
existing type.
Uses the RC Config data to check
whether the type exists in the .mui files
associated with this LN file. If the type
doesn't exist in the .mui files, add the
item and treat new item as unlocalizable. If the type exists in the .mui
files, then adding is not allowed.
Only items of the following types may
be added: File Version, RC Config data,
Side-by-side Assembly XML Manifest.
3. Update a resource item.
Uses the RC Config data to check
whether the type exists in the .mui files
associated with the LN file. If the type
doesn't exist in the .mui files, then this
resource item update is allowed in the
LN file. Otherwise, if the type exists in
the .mui files associated with this LN file,
then this update is not allowed.
The only updates allowed are items of
the following types: file Version, RC
Config data, Side-by-side Assembly
XML Manifest.
4. Add a type/item for a new language.
Not allowed.
Not allowed.
5. Remove an existing type/item.
Works similarly to case 3. Uses the RC
Config data to check whether the type
exists in the .mui files associated with
the LN file. If not, then the removal of
the type/item from the LN file is
allowed. Otherwise, if the type/item
exists in the .mui files associated with
this LN file, then the removal is not
allowed.
The only types allowed to be removed
are: file Version, RC Config data, Sideby-side Assembly XML Manifest; also,
only items of these types may be
removed.
6. Add/delete/update a type not
included in the RC Config data (such as
Version, Side-by-side Assembly XML
Manifest, or RC Config data itself).
Allowed.
Allowed.
7. Other update of non-localizable data,
such as TYPELIB, reginst, and so on.
Update type or item in the LN file, treat
as non-localizable, and add new type or
item in the RC Config data.
Not applicable.
8. Add RC Config data.
Can be done but the integrity of the RC
Config data is not checked.
Can be done but the integrity of the RC
Config data is not checked.
Examples
For an example, see Updating Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winbase.h (include Windows.h)
Librar y
Kernel32.lib
DLL
Kernel32.dll
See also
BeginUpdateResource
Conceptual
EndUpdateResource
LoadIcon
LoadString
LockResource
MAKEINTRESOURCE
MAKELANGID
Other Resources
Reference
Resources
SizeofResource
minutes to read • Edit Online
This header is used by Backup. For more information, see:
Backup winnt.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
_InlineInterlockedAdd
Performs an atomic addition operation on the specified LONG
values. The operation is performed with acquire memory
ordering semantics.
_InlineInterlockedAdd64
Performs an atomic addition operation on the specified
LONGLONG values.
_interlockedbittestandreset
Tests the specified bit of the specified LONG value and sets it
to 0. The operation is atomic.
_interlockedbittestandreset64
Tests the specified bit of the specified LONG64 value and sets
it to 0. The operation is atomic.
_interlockedbittestandset
Tests the specified bit of the specified LONG value and sets it
to 1. The operation is atomic.
_interlockedbittestandset64
Tests the specified bit of the specified LONG64 value and sets
it to 1. The operation is atomic.
C_ASSERT
Checks assertions at compile time.
FIELD_OFFSET
The FIELD_OFFSET macro returns the byte offset of a named
field in a known structure type.
GetCurrentFiber
Retrieves the address of the current fiber.
GetFiberData
Retrieves the fiber data associated with the current fiber.
Int32x32To64
Multiplies two signed 32-bit integers, returning a signed 64bit integer result.
Int64ShllMod32
Performs a left logical shift operation on an unsigned 64-bit
integer value. The function provides improved shifting code for
left logical shifts where the shift count is in the range 0-31.
Int64ShraMod32
Performs a right arithmetic shift operation on a signed 64-bit
integer value. The function provides improved shifting code for
right arithmetic shifts where the shift count is in the range 031.
T IT L E
DESC RIP T IO N
Int64ShrlMod32
Performs a right logical shift operation on an unsigned 64-bit
integer value. The function provides improved shifting code for
right logical shifts where the shift count is in the range 0-31.
InterlockedAdd
Performs an atomic addition operation on the specified LONG
values.
InterlockedAnd
Performs an atomic AND operation on the specified LONG
values.
InterlockedAnd16
Performs an atomic AND operation on the specified SHORT
values.
InterlockedAnd64
Performs an atomic AND operation on the specified
LONGLONG values.
InterlockedAnd8
Performs an atomic AND operation on the specified char
values.
InterlockedCompareExchange
Performs an atomic compare-and-exchange operation on the
specified values. The function compares two specified 32-bit
values and exchanges with another 32-bit value based on the
outcome of the comparison.
InterlockedCompareExchange128
Performs an atomic compare-and-exchange operation on the
specified values. The function compares two specified 128-bit
values and exchanges with another 128-bit value based on
the outcome of the comparison.
InterlockedCompareExchange16
Performs an atomic compare-and-exchange operation on the
specified values. The function compares two specified 16-bit
values and exchanges with another 16-bit value based on the
outcome of the comparison.
InterlockedCompareExchange64
Performs an atomic compare-and-exchange operation on the
specified values. The function compares two specified 64-bit
values and exchanges with another 64-bit value based on the
outcome of the comparison.
InterlockedCompareExchangePointer
Performs an atomic compare-and-exchange operation on the
specified values. The function compares two specified pointer
values and exchanges with another pointer value based on the
outcome of the comparison.
InterlockedDecrement
Decrements (decreases by one) the value of the specified 32bit variable as an atomic operation.
InterlockedDecrement16
Decrements (decreases by one) the value of the specified 16bit variable as an atomic operation.
InterlockedDecrement64
Decrements (decreases by one) the value of the specified 64bit variable as an atomic operation.
InterlockedExchange
Sets a 32-bit variable to the specified value as an atomic
operation.
T IT L E
DESC RIP T IO N
InterlockedExchange16
Sets a 16-bit variable to the specified value as an atomic
operation.
InterlockedExchange64
Sets a 64-bit variable to the specified value as an atomic
operation.
InterlockedExchange8
Sets an 8-bit variable to the specified value as an atomic
operation.
InterlockedExchangeAdd
Performs an atomic addition of two 32-bit values.
InterlockedExchangeAdd64
Performs an atomic addition of two 64-bit values.
InterlockedExchangePointer
Atomically exchanges a pair of addresses.
InterlockedIncrement
Increments (increases by one) the value of the specified 32-bit
variable as an atomic operation.
InterlockedIncrement16
Increments (increases by one) the value of the specified 16-bit
variable as an atomic operation.
InterlockedIncrement64
Increments (increases by one) the value of the specified 64-bit
variable as an atomic operation.
InterlockedOr
Performs an atomic OR operation on the specified LONG
values.
InterlockedOr16
Performs an atomic OR operation on the specified SHORT
values.
InterlockedOr64
Performs an atomic OR operation on the specified LONGLONG
values.
InterlockedOr8
Performs an atomic OR operation on the specified char values.
InterlockedXor
Performs an atomic XOR operation on the specified LONG
values.
InterlockedXor16
Performs an atomic XOR operation on the specified SHORT
values.
InterlockedXor64
Performs an atomic XOR operation on the specified
LONGLONG values.
InterlockedXor8
Performs an atomic XOR operation on the specified char
values.
IsReparseTagMicrosoft
Determines whether a reparse point tag indicates a Microsoft
reparse point.
IsReparseTagNameSurrogate
Determines whether a tag's associated reparse point is a
surrogate for another named entity (for example, a mounted
folder).
T IT L E
DESC RIP T IO N
LANGIDFROMLCID
Retrieves a language identifier from a locale identifier.
MAKELANGID
Creates a language identifier from a primary language
identifier and a sublanguage identifier.
MAKELCID
Creates a locale identifier from a language identifier and a sort
order identifier.
MAKESORTLCID
Constructs a locale identifier (LCID) from a language identifier,
a sort order identifier, and the sort version.
MemoryBarrier
Creates a hardware memory barrier (fence) that prevents the
CPU from re-ordering read and write operations. It may also
prevent the compiler from re-ordering read and write
operations.
Multiply128
Multiplies two 64-bit integers to produce a 128-bit integer.
MultiplyExtract128
Multiplies two 64-bit integers to produce a 128-bit integer,
shifts the product to the right by the specified number of bits,
and returns the low 64 bits of the result.
MultiplyHigh
Multiplies two 64-bit integers to produce a 128-bit integer
and gets the high 64 bits.
NtCurrentTeb
The NtCurrentTeb routine returns a pointer to the Thread
Environment Block (TEB) of the current thread.
PopulationCount64
Counts the number of one bits (population count) in a 64-bit
unsigned integer.
PreFetchCacheLine
Indicates to the processor that a cache line will be needed in
the near future.
PRIMARYLANGID
Extracts a primary language identifier from a language
identifier.
RtlAddFunctionTable
Adds a dynamic function table to the dynamic function table
list.
RtlAddGrowableFunctionTable
Informs the system of a dynamic function table representing a
region of memory containing code.
RtlCaptureContext
Retrieves a context record in the context of the caller.
RtlCaptureStackBackTrace
The RtlCaptureStackBackTrace routine captures a stack back
trace by walking up the stack and recording the information
for each frame.
RtlDeleteFunctionTable
Removes a dynamic function table from the dynamic function
table list.
RtlDeleteGrowableFunctionTable
Informs the system that a previously reported dynamic
function table is no longer in use.
T IT L E
DESC RIP T IO N
RtlFirstEntrySList
Retrieves the first entry in a singly linked list. Access to the list
is synchronized on a multiprocessor system.
RtlGrowFunctionTable
Reports that a dynamic function table has increased in size.
RtlInitializeSListHead
Initializes the head of a singly linked list.
RtlInstallFunctionTableCallback
Adds a dynamic function table to the dynamic function table
list.
RtlInterlockedFlushSList
Removes all items from a singly linked list. Access to the list is
synchronized on a multiprocessor system.
RtlInterlockedPopEntrySList
Removes an item from the front of a singly linked list. Access
to the list is synchronized on a multiprocessor system.
RtlInterlockedPushEntrySList
Inserts an item at the front of a singly linked list. Access to the
list is synchronized on a multiprocessor system.
RtlLookupFunctionEntry
Searches the active function tables for an entry that
corresponds to the specified PC value.
RtlPcToFileHeader
Retrieves the base address of the image that contains the
specified PC value.
RtlQueryDepthSList
Retrieves the number of entries in the specified singly linked
list.
RtlRestoreContext
Restores the context of the caller to the specified context
record.
RtlUnwind
Initiates an unwind of procedure call frames.
RtlUnwind2
Initiates an unwind of procedure call frames.
RtlUnwindEx
Initiates an unwind of procedure call frames.
RtlVirtualUnwind
Retrieves the invocation context of the function that precedes
the specified function context.
ShiftLeft128
Shifts 128-bit left.
ShiftRight128
Shifts 128-bit right.
SORTIDFROMLCID
Retrieves a sort order identifier from a locale identifier.
SORTVERSIONFROMLCID
Retrieves the sort version from a locale identifier.
SUBLANGID
Extracts a sublanguage identifier from a language identifier.
T IT L E
DESC RIP T IO N
TEXT
Identifies a string as Unicode when UNICODE is defined by a
preprocessor directive during compilation. Otherwise, the
macro identifies a string as an ANSI string.
TpDestroyCallbackEnviron
Deletes the specified callback environment. Call this function
when the callback environment is no longer needed for
creating new thread pool objects.
TpInitializeCallbackEnviron
Initializes a callback environment for the thread pool.
TpSetCallbackActivationContext
Assigns an activation context to the callback environment.
TpSetCallbackCleanupGroup
Associates the specified cleanup group with the specified
callback environment.
TpSetCallbackFinalizationCallback
Indicates a function to call when the callback environment is
finalized.
TpSetCallbackLongFunction
Indicates that callbacks associated with this callback
environment may not return quickly.
TpSetCallbackNoActivationContext
Indicates that the callback environment has no activation
context.
TpSetCallbackPersistent
Specifies that the callback should run on a persistent thread.
TpSetCallbackPriority
Specifies the priority of a callback function relative to other
work items in the same thread pool.
TpSetCallbackRaceWithDll
Ensures that the specified DLL remains loaded as long as there
are outstanding callbacks.
TpSetCallbackThreadpool
Assigns a thread pool to a callback environment.
UInt32x32To64
Multiplies two unsigned 32-bit integers, returning an
unsigned 64-bit integer result.
UnsignedMultiply128
Multiplies two unsigned 64-bit integers to produce an
unsigned 128-bit integer.
UnsignedMultiplyExtract128
Multiplies two unsigned 64-bit integers to produce an
unsigned 128-bit integer, shifts the product to the right by
the specified number of bits, and returns the low 64 bits of the
result.
UnsignedMultiplyHigh
Multiplies two 64-bit integers to produce a 128-bit integer
and gets the high unsigned 64 bits.
VER_SET_CONDITION
Sets the bits of a 64-bit value to indicate the comparison
operator to use for a specified operating system version
attribute. This macro is used to build the dwlConditionMask
parameter of the VerifyVersionInfo function.
T IT L E
DESC RIP T IO N
VerSetConditionMask
Sets the bits of a 64-bit value to indicate the comparison
operator to use for a specified operating system version
attribute. This function is used to build the dwlConditionMask
parameter of the VerifyVersionInfo function.
YieldProcessor
Signals to the processor to give resources to threads that are
waiting for them.
Callback functions
T IT L E
DESC RIP T IO N
PAPCFUNC
An application-defined completion routine. Specify this
address when calling the QueueUserAPC function.
PFLS_CALLBACK_FUNCTION
An application-defined function. If the FLS slot is in use,
FlsCallback is called on fiber deletion, thread exit, and when an
FLS index is freed.
PSECURE_MEMORY_CACHE_CALLBACK
An application-defined function previously registered with the
AddSecureMemoryCacheCallback function that is called when
a secured memory range is freed or its protections are
changed.
PTP_CLEANUP_GROUP_CANCEL_CALLBACK
Applications implement this callback if they call the
SetThreadpoolCallbackCleanupGroup function to specify the
callback to use when CloseThreadpoolCleanupGroup is called.
PVECTORED_EXCEPTION_HANDLER
An application-defined function that serves as a vectored
exception handler.
RTL_UMS_SCHEDULER_ENTRY_POINT
The application-defined user-mode scheduling (UMS)
scheduler entry point function associated with a UMS
completion list.
Structures
T IT L E
DESC RIP T IO N
ACCESS_ALLOWED_ACE
Defines an access control entry (ACE) for the discretionary
access control list (DACL) that controls access to an object. An
access-allowed ACE allows access to an object for a specific
trustee identified by a security identifier (SID).
ACCESS_ALLOWED_CALLBACK_ACE
The ACCESS_ALLOWED_CALLBACK_ACE structure defines an
access control entry for the discretionary access control list
that controls access to an object.
ACCESS_ALLOWED_CALLBACK_OBJECT_ACE
Defines an access control entry (ACE) that controls allowed
access to an object, property set, or property.
ACCESS_ALLOWED_OBJECT_ACE
Defines an access control entry (ACE) that controls allowed
access to an object, a property set, or property.
T IT L E
DESC RIP T IO N
ACCESS_DENIED_ACE
Defines an access control entry (ACE) for the discretionary
access control list (DACL) that controls access to an object. An
access-denied ACE denies access to an object for a specific
trustee identified by a security identifier (SID).
ACCESS_DENIED_CALLBACK_ACE
The ACCESS_DENIED_CALLBACK_ACE structure defines an
access control entry for the discretionary access control list
that controls access to an object.
ACCESS_DENIED_CALLBACK_OBJECT_ACE
The ACCESS_DENIED_CALLBACK_OBJECT_ACE structure
defines an access control entry that controls denied access to
an object, a property set, or property.
ACCESS_DENIED_OBJECT_ACE
Defines an access control entry (ACE) that controls denied
access to an object, a property set, or property.
ACE_HEADER
Defines the type and size of an access control entry (ACE).
ACL
Header of an access control list (ACL).
ACL_REVISION_INFORMATION
Contains revision information about an ACL structure.
ACL_SIZE_INFORMATION
Contains information about the size of an ACL structure.
ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION
The
ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION
structure is used by the QueryActCtxW function.
ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION
The ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION
structure is used by the QueryActCtxW function.
ACTIVATION_CONTEXT_DETAILED_INFORMATION
The ACTIVATION_CONTEXT_DETAILED_INFORMATION
structure is used by the QueryActCtxW function.
ACTIVATION_CONTEXT_QUERY_INDEX
The ACTIVATION_CONTEXT_QUERY_INDEX structure is used
by QueryActCtxW function.
ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION
The ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION
structure is used by the QueryActCtxW function.
ADMINISTRATOR_POWER_POLICY
Represents the administrator override power policy settings.
ARM64_NT_CONTEXT
Contains processor-specific register data. The system uses
CONTEXT structures to perform various internal operations.
ASSEMBLY_FILE_DETAILED_INFORMATION
The ASSEMBLY_FILE_DETAILED_INFORMATION structure is
used by the QueryActCtxW function.
BATTERY_REPORTING_SCALE
Contains the granularity of the battery capacity that is
reported by IOCTL_BATTERY_QUERY_STATUS.
CACHE_DESCRIPTOR
Describes the cache attributes.
T IT L E
DESC RIP T IO N
CACHE_RELATIONSHIP
Describes cache attributes. This structure is used with the
GetLogicalProcessorInformationEx function.
CLAIM_SECURITY_ATTRIBUTE_FQBN_VALUE
Specifies the fully qualified binary name.
CLAIM_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE
Specifies the OCTET_STRING value type of the claim security
attribute.
CLAIM_SECURITY_ATTRIBUTE_RELATIVE_V1
Defines a resource attribute that is defined in continuous
memory for persistence within a serialized security descriptor.
CLAIM_SECURITY_ATTRIBUTE_V1
Defines a security attribute that can be associated with a
token or authorization context.
CLAIM_SECURITY_ATTRIBUTES_INFORMATION
Defines the security attributes for the claim.
COMPATIBILITY_CONTEXT_ELEMENT
The COMPATIBILITY_CONTEXT_ELEMENT structure is used by
the QueryActCtxW function as part of the
ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION
structure.
CONTEXT
Contains processor-specific register data. The system uses
CONTEXT structures to perform various internal operations.
ENCLAVE_CREATE_INFO_SGX
Contains architecture-specific information to use to create an
enclave when the enclave type is ENCLAVE_TYPE_SGX, which
specifies an enclave for the Intel Software Guard Extensions
(SGX) architecture extension.
ENCLAVE_CREATE_INFO_VBS
Contains architecture-specific information to use to create an
enclave when the enclave type is ENCLAVE_TYPE_VBS, which
specifies a virtualization-based security (VBS) enclave.
ENCLAVE_INIT_INFO_SGX
Contains architecture-specific information to use to initialize
an enclave when the enclave type is ENCLAVE_TYPE_SGX,
which specifies an enclave for the Intel Software Guard
Extensions (SGX) architecture extension.
ENCLAVE_INIT_INFO_VBS
Contains architecture-specific information to use to initialize
an enclave when the enclave type is ENCLAVE_TYPE_VBS,
which specifies a virtualization-based security (VBS) enclave.
EVENTLOGRECORD
Contains information about an event record returned by the
ReadEventLog function.
EXCEPTION_POINTERS
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.
EXCEPTION_RECORD
Describes an exception.
EXCEPTION_RECORD64
Describes an exception.
T IT L E
DESC RIP T IO N
FILE_ID_128
Defines a 128-bit file identifier.
FILE_NOTIFY_EXTENDED_INFORMATION
Describes the changes found by the
ReadDirectoryChangesExW function.
FILE_NOTIFY_INFORMATION
Describes the changes found by the ReadDirectoryChangesW
function.
FPO_DATA
Represents the stack frame layout for a function on an x86
computer when frame pointer omission (FPO) optimization is
used. The structure is used to locate the base of the call frame.
GENERIC_MAPPING
Defines the mapping of generic access rights to specific and
standard access rights for an object.
GROUP_AFFINITY
Represents a processor group-specific affinity, such as the
affinity of a thread.
GROUP_RELATIONSHIP
Represents information about processor groups. This structure
is used with the GetLogicalProcessorInformationEx function.
HARDWARE_COUNTER_DATA
Contains the hardware counter value.
HEAP_OPTIMIZE_RESOURCES_INFORMATION
Specifies flags for a HeapOptimizeResources operation initiated
with HeapSetInformation.
IMAGE_COFF_SYMBOLS_HEADER
Represents the COFF symbols header.
IMAGE_DATA_DIRECTORY
Represents the data directory.
IMAGE_DEBUG_DIRECTORY
Represents the debug directory format.
IMAGE_ENCLAVE_CONFIG32
Defines the format of the enclave configuration for systems
running 32-bit Windows.
IMAGE_ENCLAVE_CONFIG64
Defines the format of the enclave configuration for systems
running 32-bit Windows.
IMAGE_ENCLAVE_IMPORT
Defines a entry in the array of images that an enclave can
import.
IMAGE_FILE_HEADER
Represents the COFF header format.
IMAGE_FUNCTION_ENTRY
Represents an entry in the function table.
IMAGE_FUNCTION_ENTRY64
Represents an entry in the function table.
IMAGE_LOAD_CONFIG_DIRECTORY32
Contains the load configuration data of an image.
IMAGE_LOAD_CONFIG_DIRECTORY64
Contains the load configuration data of an image.
IMAGE_NT_HEADERS32
Represents the PE header format.
T IT L E
DESC RIP T IO N
IMAGE_NT_HEADERS64
Represents the PE header format.
IMAGE_OPTIONAL_HEADER32
Represents the optional header format.
IMAGE_OPTIONAL_HEADER64
Represents the optional header format.
IMAGE_SECTION_HEADER
Represents the image section header format.
IO_COUNTERS
Contains I/O accounting information for a process or a job
object.
JOBOBJECT_ASSOCIATE_COMPLETION_PORT
Contains information used to associate a completion port with
a job.
JOBOBJECT_BASIC_ACCOUNTING_INFORMATION
Contains basic accounting information for a job object.
JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION
Contains basic accounting and I/O accounting information for
a job object.
JOBOBJECT_BASIC_LIMIT_INFORMATION
Contains basic limit information for a job object.
JOBOBJECT_BASIC_PROCESS_ID_LIST
Contains the process identifier list for a job object.
JOBOBJECT_BASIC_UI_RESTRICTIONS
Contains basic user-interface restrictions for a job object.
JOBOBJECT_CPU_RATE_CONTROL_INFORMATION
Contains CPU rate control information for a job object. This
structure is used by the SetInformationJobObject and
QueryInformationJobObject functions with the
JobObjectCpuRateControlInformation information class.
JOBOBJECT_END_OF_JOB_TIME_INFORMATION
Specifies the action the system will perform when an end-ofjob time limit is exceeded.
JOBOBJECT_EXTENDED_LIMIT_INFORMATION
Contains basic and extended limit information for a job object.
JOBOBJECT_LIMIT_VIOLATION_INFORMATION
Contains information about resource notification limits that
have been exceeded for a job object. This structure is used
with the QueryInformationJobObject function with the
JobObjectLimitViolationInformation information class.
JOBOBJECT_LIMIT_VIOLATION_INFORMATION_2
Contains extended information about resource notification
limits that have been exceeded for a job object. This structure
is used with the QueryInformationJobObject function with the
JobObjectLimitViolationInformation2 information class.
JOBOBJECT_NET_RATE_CONTROL_INFORMATION
Contains information used to control the network traffic for a
job. This structure is used by the SetInformationJobObject and
QueryInformationJobObject functions with the
JobObjectNetRateControlInformation information class.
JOBOBJECT_NOTIFICATION_LIMIT_INFORMATION
Contains information about notification limits for a job object.
This structure is used by the SetInformationJobObject and
QueryInformationJobObject functions with the
JobObjectNotificationLimitInformation information class.
T IT L E
DESC RIP T IO N
JOBOBJECT_NOTIFICATION_LIMIT_INFORMATION_2
Contains extended information about notification limits for a
job object. This structure is used by the
SetInformationJobObject and QueryInformationJobObject
functions with the JobObjectNotificationLimitInformation2
information class.
JOBOBJECT_SECURITY_LIMIT_INFORMATION
Contains the security limitations for a job object.
LARGE_INTEGER
LDT_ENTRY
Describes an entry in the descriptor table. This structure is
valid only on x86-based systems.
LUID
Describes a local identifier for an adapter.
LUID_AND_ATTRIBUTES
Represents a locally unique identifier (LUID) and its attributes.
MEM_ADDRESS_REQUIREMENTS
Specifies a lowest and highest base address and alignment as
part of an extended parameter to a function that manages
virtual memory.
MEM_EXTENDED_PARAMETER
Represents an extended parameter for a function that
manages virtual memory.
MEMORY_BASIC_INFORMATION
Contains information about a range of pages in the virtual
address space of a process.
MESSAGE_RESOURCE_BLOCK
Contains information about message strings with identifiers in
the range indicated by the LowId and HighId members.
MESSAGE_RESOURCE_DATA
Contains information about formatted text for display as an
error message or in a message box in a message table
resource.
MESSAGE_RESOURCE_ENTRY
Contains the error message or message box display text for a
message table resource.
NUMA_NODE_RELATIONSHIP
Represents information about a NUMA node in a processor
group. This structure is used with the
GetLogicalProcessorInformationEx function.
OBJECT_TYPE_LIST
Identifies an object type element in a hierarchy of object types.
OSVERSIONINFOA
Contains operating system version information.
OSVERSIONINFOEXA
Contains operating system version information. The
information includes major and minor version numbers, a
build number, a platform identifier, and information about
product suites and the latest Service Pack installed on the
system.
T IT L E
DESC RIP T IO N
OSVERSIONINFOEXW
Contains operating system version information. The
information includes major and minor version numbers, a
build number, a platform identifier, and information about
product suites and the latest Service Pack installed on the
system.
OSVERSIONINFOW
Contains operating system version information.
PERFORMANCE_DATA
Contains the thread profiling and hardware counter data that
you requested.
POWER_ACTION_POLICY
Contains information used to set the system power state.
PRIVILEGE_SET
Specifies a set of privileges.
PROCESS_MITIGATION_ASLR_POLICY
Contains process mitigation policy settings for Address Space
Randomization Layout (ASLR).
PROCESS_MITIGATION_BINARY_SIGNATURE_POLICY
Contains process mitigation policy settings for the loading of
images depending on the signatures for the image.
PROCESS_MITIGATION_CONTROL_FLOW_GUARD_POLICY
Contains process mitigation policy settings for Control Flow
Guard (CFG).
PROCESS_MITIGATION_DEP_POLICY
Contains process mitigation policy settings for data execution
prevention (DEP).
PROCESS_MITIGATION_DYNAMIC_CODE_POLICY
Contains process mitigation policy settings for restricting
dynamic code generation and modification.
PROCESS_MITIGATION_EXTENSION_POINT_DISABLE_POLICY
Contains process mitigation policy settings for legacy
extension point DLLs.
PROCESS_MITIGATION_FONT_DISABLE_POLICY
Contains process mitigation policy settings for the loading of
non-system fonts.
PROCESS_MITIGATION_IMAGE_LOAD_POLICY
Contains process mitigation policy settings for the loading of
images from a remote device.
PROCESS_MITIGATION_SIDE_CHANNEL_ISOLATION_POLICY
This data structure provides the status of process policies that
are related to the mitigation of side channels. This can include
side channel attacks involving speculative execution and page
combining.
PROCESS_MITIGATION_STRICT_HANDLE_CHECK_POLICY
Used to impose new behavior on handle references that are
not valid.
PROCESS_MITIGATION_SYSTEM_CALL_DISABLE_POLICY
Used to impose restrictions on what system calls can be
invoked by a process.
PROCESSOR_GROUP_INFO
Represents the number and affinity of processors in a
processor group.
PROCESSOR_NUMBER
Represents a logical processor in a processor group.
T IT L E
DESC RIP T IO N
PROCESSOR_POWER_POLICY
Contains information about processor performance control
and C-states.
PROCESSOR_POWER_POLICY_INFO
Contains information about processor C-state policy settings.
PROCESSOR_RELATIONSHIP
Represents information about affinity within a processor
group. This structure is used with the
GetLogicalProcessorInformationEx function.
QUOTA_LIMITS
Describes the amount of system resources available to a user.
REPARSE_GUID_DATA_BUFFER
Contains information about a reparse point.
RUNTIME_FUNCTION
Represents an entry in the function table on 64-bit Windows.
SECURITY_CAPABILITIES
Defines the security capabilities of the app container.
SECURITY_DESCRIPTOR
Contains the security information associated with an object.
SECURITY_QUALITY_OF_SERVICE
Contains information used to support client impersonation.
SID
Used to uniquely identify users or groups.
SID_AND_ATTRIBUTES
Represents a security identifier (SID) and its attributes.
SID_AND_ATTRIBUTES_HASH
Specifies a hash values for the specified array of security
identifiers (SIDs).
SID_IDENTIFIER_AUTHORITY
Represents the top-level authority of a security identifier (SID).
SINGLE_LIST_ENTRY
Represents an item in a singly linked list.
SLIST_ENTRY
Represents an item in a singly linked list.
SYSTEM_ALARM_ACE
The SYSTEM_ALARM_ACE structure is reserved for future use.
SYSTEM_ALARM_CALLBACK_ACE
The SYSTEM_ALARM_CALLBACK_ACE structure is reserved for
future use.
SYSTEM_ALARM_CALLBACK_OBJECT_ACE
The SYSTEM_ALARM_CALLBACK_OBJECT_ACE structure is
reserved for future use.
SYSTEM_ALARM_OBJECT_ACE
The SYSTEM_ALARM_OBJECT_ACE structure is reserved for
future use.
SYSTEM_AUDIT_ACE
Defines an access control entry (ACE) for the system access
control list (SACL) that specifies what types of access cause
system-level notifications.
SYSTEM_AUDIT_CALLBACK_ACE
The SYSTEM_AUDIT_CALLBACK_ACE structure defines an
access control entry for the system access control list that
specifies what types of access cause system-level notifications.
T IT L E
DESC RIP T IO N
SYSTEM_AUDIT_CALLBACK_OBJECT_ACE
The SYSTEM_AUDIT_CALLBACK_OBJECT_ACE structure defines
an access control entry for a system access control list.
SYSTEM_AUDIT_OBJECT_ACE
Defines an access control entry (ACE) for a system access
control list (SACL).
SYSTEM_BATTERY_STATE
Contains information about the current state of the system
battery.
SYSTEM_CPU_SET_INFORMATION
This structure is returned by GetSystemCpuSetInformation. It
is used to enumerate the CPU Sets on the system and
determine their current state.
SYSTEM_LOGICAL_PROCESSOR_INFORMATION
Describes the relationship between the specified processor set.
This structure is used with the GetLogicalProcessorInformation
function.
SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX
Contains information about the relationships of logical
processors and related hardware. The
GetLogicalProcessorInformationEx function uses this structure.
SYSTEM_MANDATORY_LABEL_ACE
Defines an access control entry (ACE) for the system access
control list (SACL) that specifies the mandatory access level
and policy for a securable object.
SYSTEM_POWER_CAPABILITIES
Contains information about the power capabilities of the
system.
SYSTEM_POWER_LEVEL
Contains information about system battery drain policy
settings.
SYSTEM_POWER_POLICY
Contains information about the current system power policy.
SYSTEM_RESOURCE_ATTRIBUTE_ACE
Defines an access control entry (ACE) for the system access
control list (SACL) that specifies the system resource attributes
for a securable object.
SYSTEM_SCOPED_POLICY_ID_ACE
Defines an access control entry (ACE) for the system access
control list (SACL) that specifies the scoped policy identifier for
a securable object.
TAPE_ERASE
Describes the partition to be erased.
TAPE_GET_DRIVE_PARAMETERS
Describes the tape drive. It is used by the GetTapeParameters
function.
TAPE_GET_MEDIA_PARAMETERS
Describes the tape in the tape drive. It is used by the
GetTapeParametersfunction.
TAPE_GET_POSITION
Describes the position of the tape.
TAPE_PREPARE
Describes how to prepare the tape.
T IT L E
DESC RIP T IO N
TAPE_SET_DRIVE_PARAMETERS
Describes the tape drive. It is used by the
SetTapeParametersfunction.
TAPE_SET_MEDIA_PARAMETERS
Describes the tape in the tape drive. It is used by the
SetTapeParametersfunction.
TAPE_SET_POSITION
Describes how and where to position the tape.
TAPE_WRITE_MARKS
Describes the type and number of tapemarks to write.
TOKEN_ACCESS_INFORMATION
Specifies all the information in a token that is necessary to
perform an access check.
TOKEN_APPCONTAINER_INFORMATION
Specifies all the information in a token that is necessary for an
app container.
TOKEN_AUDIT_POLICY
Specifies the per user audit policy for a token.
TOKEN_CONTROL
Contains information that identifies an access token.
TOKEN_DEFAULT_DACL
Specifies a discretionary access control list (DACL).
TOKEN_DEVICE_CLAIMS
Defines the device claims for the token.
TOKEN_ELEVATION
Indicates whether a token has elevated privileges.
TOKEN_GROUPS
Contains information about the group security identifiers
(SIDs) in an access token.
TOKEN_GROUPS_AND_PRIVILEGES
Contains information about the group security identifiers
(SIDs) and privileges in an access token.
TOKEN_LINKED_TOKEN
Contains a handle to a token. This token is linked to the token
being queried by the GetTokenInformation function or set by
the SetTokenInformation function.
TOKEN_MANDATORY_LABEL
Specifies the mandatory integrity level for a token.
TOKEN_MANDATORY_POLICY
Specifies the mandatory integrity policy for a token.
TOKEN_ORIGIN
Contains information about the origin of the logon session.
TOKEN_OWNER
Contains the default owner security identifier (SID) that will be
applied to newly created objects.
TOKEN_PRIMARY_GROUP
Specifies a group security identifier (SID) for an access token.
TOKEN_PRIVILEGES
Contains information about a set of privileges for an access
token.
TOKEN_SOURCE
Identifies the source of an access token.
T IT L E
DESC RIP T IO N
TOKEN_STATISTICS
Contains information about an access token.
TOKEN_USER
Identifies the user associated with an access token.
TOKEN_USER_CLAIMS
Defines the user claims for the token.
ULARGE_INTEGER
UMS_CREATE_THREAD_ATTRIBUTES
Specifies attributes for a user-mode scheduling (UMS) worker
thread.
WOW64_CONTEXT
Represents a context frame on WOW64.
WOW64_FLOATING_SAVE_AREA
Represents the 80387 save area on WOW64.
WOW64_LDT_ENTRY
Describes an entry in the descriptor table for a 32-bit thread
on a 64-bit system. This structure is valid only on 64-bit
systems.
Enumerations
T IT L E
DESC RIP T IO N
ACL_INFORMATION_CLASS
Contains values that specify the type of information being
assigned to or retrieved from an access control list (ACL).
ACTCTX_COMPATIBILITY_ELEMENT_TYPE
The ACTCTX_COMPATIBILITY_ELEMENT_TYPE enumeration
describes the compatibility element in the application manifest.
ACTCTX_REQUESTED_RUN_LEVEL
The ACTCTX_REQUESTED_RUN_LEVEL enumeration describes
the requested run level of the activation context.
AUDIT_EVENT_TYPE
Defines values that indicate the type of object being audited.
The AccessCheckByTypeAndAuditAlarm and
AccessCheckByTypeResultListAndAuditAlarm functions use
these values.
COMPARTMENT_ID
The COMPARTMENT_ID enumeration indicates the network
routing compartment identifier.
FIRMWARE_TYPE
Specifies a firmware type.
HARDWARE_COUNTER_TYPE
Defines the types of hardware counters being profiled.
HEAP_INFORMATION_CLASS
Specifies the class of heap information to be set or retrieved.
JOB_OBJECT_NET_RATE_CONTROL_FLAGS
Specifies types of scheduling policies for network rate control.
LOGICAL_PROCESSOR_RELATIONSHIP
Represents the relationship between the processor set
identified in the corresponding
SYSTEM_LOGICAL_PROCESSOR_INFORMATION or
SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX structure.
T IT L E
DESC RIP T IO N
MANDATORY_LEVEL
Lists the possible security levels.
MEM_EXTENDED_PARAMETER_TYPE
Defines values for extended parameters used for file mapping
into an address space.
POWER_ACTION
Defines values that are used to specify system power action
types.
POWER_PLATFORM_ROLE
Indicates the OEM's preferred power management profile.
PROCESS_MITIGATION_POLICY
Represents the different process mitigation policies.
PROCESSOR_CACHE_TYPE
Represents the type of processor cache identified in the
corresponding CACHE_DESCRIPTOR structure.
SECURITY_IMPERSONATION_LEVEL
Contains values that specify security impersonation levels.
Security impersonation levels govern the degree to which a
server process can act on behalf of a client process.
SID_NAME_USE
Contains values that specify the type of a security identifier
(SID).
SYSTEM_POWER_CONDITION
Used by the GUID_ACDC_POWER_SOURCE power event to
indicate the current power source.
SYSTEM_POWER_STATE
Defines values that are used to specify system power states.
TOKEN_ELEVATION_TYPE
Indicates the elevation type of token being queried by the
GetTokenInformation function or set by the
SetTokenInformation function.
TOKEN_INFORMATION_CLASS
Contains values that specify the type of information being
assigned to or retrieved from an access token.
TOKEN_TYPE
Contains values that differentiate between a primary token
and an impersonation token.
TRANSACTION_OUTCOME
Defines the outcomes (results) that KTM can assign to a
transaction.
WELL_KNOWN_SID_TYPE
A list of commonly used security identifiers (SIDs). Programs
can pass these values to the CreateWellKnownSid function to
create a SID from this list.
minutes to read • Edit Online
Contains information about message strings with identifiers in the range indicated by the LowId and HighId
members.
Syntax
typedef struct _MESSAGE_RESOURCE_BLOCK {
DWORD LowId;
DWORD HighId;
DWORD OffsetToEntries;
} MESSAGE_RESOURCE_BLOCK, *PMESSAGE_RESOURCE_BLOCK;
Members
LowId
Type: DWORD
The lowest message identifier contained within this structure.
HighId
Type: DWORD
The highest message identifier contained within this structure.
OffsetToEntries
Type: DWORD
The offset, in bytes, from the beginning of the MESSAGE_RESOURCE_DATA structure to the
MESSAGE_RESOURCE_ENTRY structures in this MESSAGE_RESOURCE_BLOCK . The
MESSAGE_RESOURCE_ENTRY structures contain the message strings.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winnt.h (include Windows.h)
See also
Conceptual
MESSAGE_RESOURCE_DATA
MESSAGE_RESOURCE_ENTRY
Reference
Resources
minutes to read • Edit Online
Contains information about formatted text for display as an error message or in a message box in a message table
resource.
Syntax
typedef struct _MESSAGE_RESOURCE_DATA {
DWORD
NumberOfBlocks;
MESSAGE_RESOURCE_BLOCK Blocks[1];
} MESSAGE_RESOURCE_DATA, *PMESSAGE_RESOURCE_DATA;
Members
NumberOfBlocks
Type: DWORD
The number of MESSAGE_RESOURCE_BLOCK structures.
Blocks
Type: MESSAGE_RESOURCE_BLOCK [1]
An array of structures. The array is the size indicated by the NumberOfBlocks member.
Remarks
A MESSAGE_RESOURCE_DATA structure can contain one or more MESSAGE_RESOURCE_BLOCK structures,
which can each contain one or more MESSAGE_RESOURCE_ENTRY structures.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winnt.h (include Windows.h)
See also
Conceptual
MESSAGE_RESOURCE_BLOCK
MESSAGE_RESOURCE_ENTRY
Reference
Resources
minutes to read • Edit Online
Contains the error message or message box display text for a message table resource.
Syntax
typedef struct _MESSAGE_RESOURCE_ENTRY {
WORD Length;
WORD Flags;
BYTE Text[1];
} MESSAGE_RESOURCE_ENTRY, *PMESSAGE_RESOURCE_ENTRY;
Members
Length
Type: WORD
The length, in bytes, of the MESSAGE_RESOURCE_ENTRY structure.
Flags
Type: WORD
Indicates that the string is encoded in Unicode, if equal to the value 0x0001. Indicates that the string is encoded in
ANSI, if equal to the value 0x0000.
Text
Type: BYTE[1]
Pointer to an array that contains the error message or message box display text.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winnt.h (include Windows.h)
See also
Conceptual
MESSAGE_RESOURCE_BLOCK
MESSAGE_RESOURCE_DATA
Reference
Resources
minutes to read • Edit Online
This header is used by Windows Controls. For more information, see:
Windows Controls winuser.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
ActivateKeyboardLayout
Sets the input locale identifier (formerly called the keyboard
layout handle) for the calling thread or the current process.
The input locale identifier specifies a locale as well as the
physical layout of the keyboard.
AddClipboardFormatListener
Places the given window in the system-maintained clipboard
format listener list.
AdjustWindowRect
Calculates the required size of the window rectangle, based on
the desired client-rectangle size. The window rectangle can
then be passed to the CreateWindow function to create a
window whose client area is the desired size.
AdjustWindowRectEx
Calculates the required size of the window rectangle, based on
the desired size of the client rectangle. The window rectangle
can then be passed to the CreateWindowEx function to create
a window whose client area is the desired size.
AdjustWindowRectExForDpi
Calculates the required size of the window rectangle, based on
the desired size of the client rectangle and the provided DPI.
AllowSetForegroundWindow
Enables the specified process to set the foreground window
using the SetForegroundWindow function. The calling process
must already be able to set the foreground window. For more
information, see Remarks later in this topic.
AnimateWindow
Enables you to produce special effects when showing or hiding
windows. There are four types of animation:_roll, slide, collapse
or expand, and alpha-blended fade.
AnyPopup
Indicates whether an owned, visible, top-level pop-up, or
overlapped window exists on the screen. The function searches
the entire screen, not just the calling application's client area.
AppendMenuA
Appends a new item to the end of the specified menu bar,
drop-down menu, submenu, or shortcut menu. You can use
this function to specify the content, appearance, and behavior
of the menu item.
AppendMenuW
Appends a new item to the end of the specified menu bar,
drop-down menu, submenu, or shortcut menu. You can use
this function to specify the content, appearance, and behavior
of the menu item.
T IT L E
DESC RIP T IO N
AreDpiAwarenessContextsEqual
Determines whether two DPI_AWARENESS_CONTEXT values
are identical.
ArrangeIconicWindows
Arranges all the minimized (iconic) child windows of the
specified parent window.
AttachThreadInput
Attaches or detaches the input processing mechanism of one
thread to that of another thread.
BeginDeferWindowPos
Allocates memory for a multiple-window- position structure
and returns the handle to the structure.
BeginPaint
The BeginPaint function prepares the specified window for
painting and fills a PAINTSTRUCT structure with information
about the painting.
BlockInput
Blocks keyboard and mouse input events from reaching
applications.
BringWindowToTop
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.
BroadcastSystemMessage
Sends a message to the specified recipients.
BroadcastSystemMessageExA
Sends a message to the specified recipients.
BroadcastSystemMessageExW
Sends a message to the specified recipients.
BroadcastSystemMessageW
Sends a message to the specified recipients.
CalculatePopupWindowPosition
Calculates an appropriate pop-up window position using the
specified anchor point, pop-up window size, flags, and the
optional exclude rectangle.
CallMsgFilterA
Passes the specified message and hook code to the hook
procedures associated with the WH_SYSMSGFILTER and
WH_MSGFILTER hooks.
CallMsgFilterW
Passes the specified message and hook code to the hook
procedures associated with the WH_SYSMSGFILTER and
WH_MSGFILTER hooks.
CallNextHookEx
Passes the hook information to the next hook procedure in
the current hook chain. A hook procedure can call this
function either before or after processing the hook
information.
CallWindowProcA
Passes message information to the specified window
procedure.
CallWindowProcW
Passes message information to the specified window
procedure.
T IT L E
DESC RIP T IO N
CascadeWindows
Cascades the specified child windows of the specified parent
window.
ChangeClipboardChain
Removes a specified window from the chain of clipboard
viewers.
ChangeDisplaySettingsA
The ChangeDisplaySettings function changes the settings of
the default display device to the specified graphics mode.
ChangeDisplaySettingsExA
The ChangeDisplaySettingsEx function changes the settings of
the specified display device to the specified graphics mode.
ChangeDisplaySettingsExW
The ChangeDisplaySettingsEx function changes the settings of
the specified display device to the specified graphics mode.
ChangeDisplaySettingsW
The ChangeDisplaySettings function changes the settings of
the default display device to the specified graphics mode.
ChangeWindowMessageFilter
Adds or removes a message from the User Interface Privilege
Isolation (UIPI) message filter.
ChangeWindowMessageFilterEx
Modifies the User Interface Privilege Isolation (UIPI) message
filter for a specified window.
CharLowerA
Converts a character string or a single character to lowercase.
If the operand is a character string, the function converts the
characters in place.
CharLowerBuffA
Converts uppercase characters in a buffer to lowercase
characters. The function converts the characters in place.
CharLowerBuffW
Converts uppercase characters in a buffer to lowercase
characters. The function converts the characters in place.
CharLowerW
Converts a character string or a single character to lowercase.
If the operand is a character string, the function converts the
characters in place.
CharNextA
Retrieves a pointer to the next character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharNextExA
Retrieves the pointer to the next character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharNextW
Retrieves a pointer to the next character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharPrevA
Retrieves a pointer to the preceding character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
T IT L E
DESC RIP T IO N
CharPrevExA
Retrieves the pointer to the preceding character in a string.
This function can handle strings consisting of either single- or
multi-byte characters.
CharPrevW
Retrieves a pointer to the preceding character in a string. This
function can handle strings consisting of either single- or
multi-byte characters.
CharToOemA
Translates a string into the OEM-defined character
set.Warning Do not use.
CharToOemBuffA
Translates a specified number of characters in a string into the
OEM-defined character set.
CharToOemBuffW
Translates a specified number of characters in a string into the
OEM-defined character set.
CharToOemW
Translates a string into the OEM-defined character
set.Warning Do not use.
CharUpperA
Converts a character string or a single character to uppercase.
If the operand is a character string, the function converts the
characters in place.
CharUpperBuffA
Converts lowercase characters in a buffer to uppercase
characters. The function converts the characters in place.
CharUpperBuffW
Converts lowercase characters in a buffer to uppercase
characters. The function converts the characters in place.
CharUpperW
Converts a character string or a single character to uppercase.
If the operand is a character string, the function converts the
characters in place.
CheckDlgButton
Changes the check state of a button control.
CheckMenuItem
Sets the state of the specified menu item's check-mark
attribute to either selected or clear.
CheckMenuRadioItem
Checks a specified menu item and makes it a radio item. At
the same time, the function clears all other menu items in the
associated group and clears the radio-item type flag for those
items.
CheckRadioButton
Adds a check mark to (checks) a specified radio button in a
group and removes a check mark from (clears) all other radio
buttons in the group.
ChildWindowFromPoint
Determines which, if any, of the child windows belonging to a
parent window contains the specified point. The search is
restricted to immediate child windows. Grandchildren, and
deeper descendant windows are not searched.
ChildWindowFromPointEx
Determines which, if any, of the child windows belonging to
the specified parent window contains the specified point.
T IT L E
DESC RIP T IO N
ClientToScreen
The ClientToScreen function converts the client-area
coordinates of a specified point to screen coordinates.
ClipCursor
Confines the cursor to a rectangular area on the screen.
CloseClipboard
Closes the clipboard.
CloseDesktop
Closes an open handle to a desktop object.
CloseGestureInfoHandle
Closes resources associated with a gesture information handle.
CloseTouchInputHandle
Closes a touch input handle, frees process memory associated
with it, and invalidates the handle.
CloseWindow
Minimizes (but does not destroy) the specified window.
CloseWindowStation
Closes an open window station handle.
CopyAcceleratorTableA
Copies the specified accelerator table. This function is used to
obtain the accelerator-table data that corresponds to an
accelerator-table handle, or to determine the size of the
accelerator-table data.
CopyAcceleratorTableW
Copies the specified accelerator table. This function is used to
obtain the accelerator-table data that corresponds to an
accelerator-table handle, or to determine the size of the
accelerator-table data.
CopyCursor
Copies the specified cursor.
CopyIcon
Copies the specified icon from another module to the current
module.
CopyImage
Creates a new image (icon, cursor, or bitmap) and copies the
attributes of the specified image to the new one. If necessary,
the function stretches the bits to fit the desired size of the new
image.
CopyRect
The CopyRect function copies the coordinates of one rectangle
to another.
CountClipboardFormats
Retrieves the number of different data formats currently on
the clipboard.
CreateAcceleratorTableA
Creates an accelerator table.
CreateAcceleratorTableW
Creates an accelerator table.
T IT L E
DESC RIP T IO N
CreateCaret
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, a block, or a bitmap.
CreateCursor
Creates a cursor having the specified size, bit patterns, and hot
spot.
CreateDesktopA
Creates a new desktop, associates it with the current window
station of the calling process, and assigns it to the calling
thread.
CreateDesktopExA
Creates a new desktop with the specified heap, associates it
with the current window station of the calling process, and
assigns it to the calling thread.
CreateDesktopExW
Creates a new desktop with the specified heap, associates it
with the current window station of the calling process, and
assigns it to the calling thread.
CreateDesktopW
Creates a new desktop, associates it with the current window
station of the calling process, and assigns it to the calling
thread.
CreateDialogA
Creates a modeless dialog box from a dialog box template
resource. The CreateDialog macro uses the CreateDialogParam
function.
CreateDialogIndirectA
Creates a modeless dialog box from a dialog box template in
memory. The CreateDialogIndirect macro uses the
CreateDialogIndirectParam function.
CreateDialogIndirectParamA
Creates a modeless dialog box from a dialog box template in
memory.
CreateDialogIndirectParamW
Creates a modeless dialog box from a dialog box template in
memory.
CreateDialogIndirectW
Creates a modeless dialog box from a dialog box template in
memory. The CreateDialogIndirect macro uses the
CreateDialogIndirectParam function.
CreateDialogParamA
Creates a modeless dialog box from a dialog box template
resource.
CreateDialogParamW
Creates a modeless dialog box from a dialog box template
resource.
CreateDialogW
Creates a modeless dialog box from a dialog box template
resource. The CreateDialog macro uses the CreateDialogParam
function.
CreateIcon
Creates an icon that has the specified size, colors, and bit
patterns.
T IT L E
DESC RIP T IO N
CreateIconFromResource
Creates an icon or cursor from resource bits describing the
icon.
CreateIconFromResourceEx
Creates an icon or cursor from resource bits describing the
icon.
CreateIconIndirect
Creates an icon or cursor from an ICONINFO structure.
CreateMDIWindowA
Creates a multiple-document interface (MDI) child window.
CreateMDIWindowW
Creates a multiple-document interface (MDI) child window.
CreateMenu
Creates a menu. The menu is initially empty, but it can be filled
with menu items by using the InsertMenuItem, AppendMenu,
and InsertMenu functions.
CreatePopupMenu
Creates a drop-down menu, submenu, or shortcut menu.
CreateSyntheticPointerDevice
Configures the pointer injection device for the calling
application, and initializes the maximum number of
simultaneous pointers that the app can inject.
CreateWindowA
Creates an overlapped, pop-up, or child window.
CreateWindowExA
Creates an overlapped, pop-up, or child window with an
extended window style; otherwise, this function is identical to
the CreateWindow function.
CreateWindowExW
Creates an overlapped, pop-up, or child window with an
extended window style; otherwise, this function is identical to
the CreateWindow function.
CreateWindowStationA
Creates a window station object, associates it with the calling
process, and assigns it to the current session.
CreateWindowStationW
Creates a window station object, associates it with the calling
process, and assigns it to the current session.
CreateWindowW
Creates an overlapped, pop-up, or child window.
DefDlgProcW
Calls the default dialog box window procedure to provide
default processing for any window messages that a dialog box
with a private window class does not process.
DeferWindowPos
Updates the specified multiple-window – position structure for
the specified window.
DefFrameProcA
Provides default processing for any window messages that the
window procedure of a multiple-document interface (MDI)
frame window does not process.
DefFrameProcW
Provides default processing for any window messages that the
window procedure of a multiple-document interface (MDI)
frame window does not process.
T IT L E
DESC RIP T IO N
DefMDIChildProcA
Provides default processing for any window message that the
window procedure of a multiple-document interface (MDI)
child window does not process.
DefMDIChildProcW
Provides default processing for any window message that the
window procedure of a multiple-document interface (MDI)
child window does not process.
DefRawInputProc
Calls the default raw input procedure to provide default
processing for any raw input messages that an application
does not process.
DefWindowProcA
Calls the default window procedure to provide default
processing for any window messages that an application does
not process.
DefWindowProcW
Calls the default window procedure to provide default
processing for any window messages that an application does
not process.
DeleteMenu
Deletes an item from the specified menu. If the menu item
opens a menu or submenu, this function destroys the handle
to the menu or submenu and frees the memory used by the
menu or submenu.
DeregisterShellHookWindow
Unregisters a specified Shell window that is registered to
receive Shell hook messages.
DestroyAcceleratorTable
Destroys an accelerator table.
DestroyCaret
Destroys the caret's current shape, frees the caret from the
window, and removes the caret from the screen.
DestroyCursor
Destroys a cursor and frees any memory the cursor occupied.
Do not use this function to destroy a shared cursor.
DestroyIcon
Destroys an icon and frees any memory the icon occupied.
DestroyMenu
Destroys the specified menu and frees any memory that the
menu occupies.
DestroySyntheticPointerDevice
Destroys the specified pointer injection device.
DestroyWindow
Destroys the specified window.
DialogBoxA
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.
DialogBoxIndirectA
Creates a modal dialog box from a dialog box template in
memory. DialogBoxIndirect does not return control until the
specified callback function terminates the modal dialog box by
calling the EndDialog function.
T IT L E
DESC RIP T IO N
DialogBoxIndirectParamA
Creates a modal dialog box from a dialog box template in
memory.
DialogBoxIndirectParamW
Creates a modal dialog box from a dialog box template in
memory.
DialogBoxIndirectW
Creates a modal dialog box from a dialog box template in
memory. DialogBoxIndirect does not return control until the
specified callback function terminates the modal dialog box by
calling the EndDialog function.
DialogBoxParamA
Creates a modal dialog box from a dialog box template
resource.
DialogBoxParamW
Creates a modal dialog box from a dialog box template
resource.
DialogBoxW
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.
DisableProcessWindowsGhosting
Disables the window ghosting feature for the calling GUI
process. Window ghosting is a Windows Manager feature that
lets the user minimize, move, or close the main window of an
application that is not responding.
DispatchMessage
Dispatches a message to a window procedure. It is typically
used to dispatch a message retrieved by the GetMessage
function.
DispatchMessageA
Dispatches a message to a window procedure. It is typically
used to dispatch a message retrieved by the GetMessage
function.
DispatchMessageW
Dispatches a message to a window procedure. It is typically
used to dispatch a message retrieved by the GetMessage
function.
DisplayConfigGetDeviceInfo
The DisplayConfigGetDeviceInfo function retrieves display
configuration information about the device.
DisplayConfigSetDeviceInfo
The DisplayConfigSetDeviceInfo function sets the properties of
a target.
DlgDirListA
Replaces the contents of a list box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list
can optionally include mapped drives.
DlgDirListComboBoxA
Replaces the contents of a combo box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list of
names can include mapped drive letters.
T IT L E
DESC RIP T IO N
DlgDirListComboBoxW
Replaces the contents of a combo box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list of
names can include mapped drive letters.
DlgDirListW
Replaces the contents of a list box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list
can optionally include mapped drives.
DlgDirSelectComboBoxExA
Retrieves the current selection from a combo box filled by
using the DlgDirListComboBox function. The selection is
interpreted as a drive letter, a file, or a directory name.
DlgDirSelectComboBoxExW
Retrieves the current selection from a combo box filled by
using the DlgDirListComboBox function. The selection is
interpreted as a drive letter, a file, or a directory name.
DlgDirSelectExA
Retrieves the current selection from a single-selection list box.
It assumes that the list box has been filled by the DlgDirList
function and that the selection is a drive letter, filename, or
directory name.
DlgDirSelectExW
Retrieves the current selection from a single-selection list box.
It assumes that the list box has been filled by the DlgDirList
function and that the selection is a drive letter, filename, or
directory name.
DragDetect
Captures the mouse and tracks its movement until the user
releases the left button, presses the ESC key, or moves the
mouse outside the drag rectangle around the specified point.
DrawAnimatedRects
Animates the caption of a window to indicate the opening of
an icon or the minimizing or maximizing of a window.
DrawCaption
The DrawCaption function draws a window caption.
DrawEdge
The DrawEdge function draws one or more edges of rectangle.
DrawFocusRect
The DrawFocusRect function draws a rectangle in the style
used to indicate that the rectangle has the focus.
DrawFrameControl
The DrawFrameControl function draws a frame control of the
specified type and style.
DrawIcon
Draws an icon or cursor into the specified device context.
DrawIconEx
Draws an icon or cursor into the specified device context,
performing the specified raster operations, and stretching or
compressing the icon or cursor as specified.
DrawMenuBar
Redraws the menu bar of the specified window. If the menu
bar changes after the system has created the window, this
function must be called to draw the changed menu bar.
T IT L E
DESC RIP T IO N
DrawStateA
The DrawState function displays an image and applies a visual
effect to indicate a state, such as a disabled or default state.
DrawStateW
The DrawState function displays an image and applies a visual
effect to indicate a state, such as a disabled or default state.
DrawText
The DrawText function draws formatted text in the specified
rectangle. It formats the text according to the specified
method (expanding tabs, justifying characters, breaking lines,
and so forth).
DrawTextA
The DrawText function draws formatted text in the specified
rectangle. It formats the text according to the specified
method (expanding tabs, justifying characters, breaking lines,
and so forth).
DrawTextExA
The DrawTextEx function draws formatted text in the specified
rectangle.
DrawTextExW
The DrawTextEx function draws formatted text in the specified
rectangle.
DrawTextW
The DrawText function draws formatted text in the specified
rectangle. It formats the text according to the specified
method (expanding tabs, justifying characters, breaking lines,
and so forth).
EmptyClipboard
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.
EnableMenuItem
Enables, disables, or grays the specified menu item.
EnableMouseInPointer
Enables the mouse to act as a pointer input device and send
WM_POINTER messages.
EnableNonClientDpiScaling
In high-DPI displays, enables automatic display scaling of the
non-client area portions of the specified top-level window.
Must be called during the initialization of that window.
EnableScrollBar
The EnableScrollBar function enables or disables one or both
scroll bar arrows.
EnableWindow
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.
EndDeferWindowPos
Simultaneously updates the position and size of one or more
windows in a single screen-refreshing cycle.
EndDialog
Destroys a modal dialog box, causing the system to end any
processing for the dialog box.
EndMenu
Ends the calling thread's active menu.
T IT L E
DESC RIP T IO N
EndPaint
The EndPaint 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.
EndTask
Forcibly closes the specified window.
EnumChildWindows
Enumerates the child windows that belong to the specified
parent window by passing the handle to each child window, in
turn, to an application-defined callback function.
EnumClipboardFormats
Enumerates the data formats currently available on the
clipboard.
EnumDesktopsA
Enumerates all desktops associated with the specified window
station of the calling process. The function passes the name of
each desktop, in turn, to an application-defined callback
function.
EnumDesktopsW
Enumerates all desktops associated with the specified window
station of the calling process. The function passes the name of
each desktop, in turn, to an application-defined callback
function.
EnumDesktopWindows
Enumerates all top-level windows associated with the specified
desktop. It passes the handle to each window, in turn, to an
application-defined callback function.
EnumDisplayDevicesA
The EnumDisplayDevices function lets you obtain information
about the display devices in the current session.
EnumDisplayDevicesW
The EnumDisplayDevices function lets you obtain information
about the display devices in the current session.
EnumDisplayMonitors
The EnumDisplayMonitors function enumerates display
monitors (including invisible pseudo-monitors associated with
the mirroring drivers) that intersect a region formed by the
intersection of a specified clipping rectangle and the visible
region of a device context. EnumDisplayMonitors calls an
application-defined MonitorEnumProc callback function once
for each monitor that is enumerated. Note that
GetSystemMetrics (SM_CMONITORS) counts only the display
monitors.
EnumDisplaySettingsA
The EnumDisplaySettings function retrieves information about
one of the graphics modes for a display device. To retrieve
information for all the graphics modes of a display device,
make a series of calls to this function.
EnumDisplaySettingsExA
The EnumDisplaySettingsEx function retrieves information
about one of the graphics modes for a display device. To
retrieve information for all the graphics modes for a display
device, make a series of calls to this function.
T IT L E
DESC RIP T IO N
EnumDisplaySettingsExW
The EnumDisplaySettingsEx function retrieves information
about one of the graphics modes for a display device. To
retrieve information for all the graphics modes for a display
device, make a series of calls to this function.
EnumDisplaySettingsW
The EnumDisplaySettings function retrieves information about
one of the graphics modes for a display device. To retrieve
information for all the graphics modes of a display device,
make a series of calls to this function.
EnumPropsA
Enumerates all entries in the property list of a window by
passing them, one by one, to the specified callback function.
EnumProps continues until the last entry is enumerated or the
callback function returns FALSE.
EnumPropsExA
Enumerates all entries in the property list of a window by
passing them, one by one, to the specified callback function.
EnumPropsEx continues until the last entry is enumerated or
the callback function returns FALSE.
EnumPropsExW
Enumerates all entries in the property list of a window by
passing them, one by one, to the specified callback function.
EnumPropsEx continues until the last entry is enumerated or
the callback function returns FALSE.
EnumPropsW
Enumerates all entries in the property list of a window by
passing them, one by one, to the specified callback function.
EnumProps continues until the last entry is enumerated or the
callback function returns FALSE.
EnumThreadWindows
Enumerates all nonchild windows associated with a thread by
passing the handle to each window, in turn, to an applicationdefined callback function.
EnumWindows
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 toplevel window is enumerated or the callback function returns
FALSE.
EnumWindowStationsA
Enumerates all window stations in the current session. The
function passes the name of each window station, in turn, to
an application-defined callback function.
EnumWindowStationsW
Enumerates all window stations in the current session. The
function passes the name of each window station, in turn, to
an application-defined callback function.
EqualRect
The EqualRect function determines whether the two specified
rectangles are equal by comparing the coordinates of their
upper-left and lower-right corners.
EvaluateProximityToPolygon
Returns the score of a polygon as the probable touch target
(compared to all other polygons that intersect the touch
contact area) and an adjusted touch point within the polygon.
T IT L E
DESC RIP T IO N
EvaluateProximityToRect
Returns the score of a rectangle as the probable touch target,
compared to all other rectangles that intersect the touch
contact area, and an adjusted touch point within the rectangle.
ExcludeUpdateRgn
The ExcludeUpdateRgn function prevents drawing within
invalid areas of a window by excluding an updated region in
the window from a clipping region.
ExitWindows
Calls the ExitWindowsEx function to log off the interactive user.
ExitWindowsEx
Logs off the interactive user, shuts down the system, or shuts
down and restarts the system.
FillRect
The FillRect function fills a rectangle by using the specified
brush. This function includes the left and top borders, but
excludes the right and bottom borders of the rectangle.
FindWindowA
Retrieves a handle to the top-level window whose class name
and window name match the specified strings. This function
does not search child windows. This function does not perform
a case-sensitive search.
FindWindowExA
Retrieves a handle to a window whose class name and window
name match the specified strings. The function searches child
windows, beginning with the one following the specified child
window. This function does not perform a case-sensitive
search.
FindWindowExW
Retrieves a handle to a window whose class name and window
name match the specified strings. The function searches child
windows, beginning with the one following the specified child
window. This function does not perform a case-sensitive
search.
FindWindowW
Retrieves a handle to the top-level window whose class name
and window name match the specified strings. This function
does not search child windows. This function does not perform
a case-sensitive search.
FlashWindow
Flashes the specified window one time. It does not change the
active state of the window.
FlashWindowEx
Flashes the specified window. It does not change the active
state of the window.
FrameRect
The FrameRect function draws a border around the specified
rectangle by using the specified brush. The width and height
of the border are always one logical unit.
GET_APPCOMMAND_LPARAM
Retrieves the application command from the specified LPARAM
value.
GET_DEVICE_LPARAM
Retrieves the input device type from the specified LPARAM
value.
T IT L E
DESC RIP T IO N
GET_FLAGS_LPARAM
Retrieves the state of certain virtual keys from the specified
LPARAM value.
GET_KEYSTATE_LPARAM
Retrieves the state of certain virtual keys from the specified
LPARAM value.
GET_KEYSTATE_WPARAM
Retrieves the state of certain virtual keys from the specified
WPARAM value.
GET_NCHITTEST_WPARAM
Retrieves the hit-test value from the specified WPARAM value.
GET_POINTERID_WPARAM
Retrieves the pointer ID using the specified value.
GET_RAWINPUT_CODE_WPARAM
Retrieves the input code from wParam in WM_INPUT.
GET_WHEEL_DELTA_WPARAM
Retrieves the wheel-delta value from the specified WPARAM
value.
GET_XBUTTON_WPARAM
Retrieves the state of certain buttons from the specified
WPARAM value.
GetActiveWindow
Retrieves the window handle to the active window attached to
the calling thread's message queue.
GetAltTabInfoA
Retrieves status information for the specified window if it is the
application-switching (ALT+TAB) window.
GetAltTabInfoW
Retrieves status information for the specified window if it is the
application-switching (ALT+TAB) window.
GetAncestor
Retrieves the handle to the ancestor of the specified window.
GetAsyncKeyState
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.
GetAutoRotationState
Retrieves an AR_STATE value containing the state of screen
auto-rotation for the system, for example whether autorotation is supported, and whether it is enabled by the user.
GetAwarenessFromDpiAwarenessContext
Retrieves the DPI_AWARENESS value from a
DPI_AWARENESS_CONTEXT.
GetCapture
Retrieves a handle to the window (if any) that has captured the
mouse. Only one window at a time can capture the mouse;
this window receives mouse input whether or not the cursor is
within its borders.
GetCaretBlinkTime
Retrieves the time required to invert the caret's pixels. The user
can set this value.
GetCaretPos
Copies the caret's position to the specified POINT structure.
T IT L E
DESC RIP T IO N
GetCIMSSM
Retrieves the source of the input message
(GetCurrentInputMessageSourceInSendMessage).
GetClassInfoA
Retrieves information about a window class.
GetClassInfoExA
Retrieves information about a window class, including a handle
to the small icon associated with the window class. The
GetClassInfo function does not retrieve a handle to the small
icon.
GetClassInfoExW
Retrieves information about a window class, including a handle
to the small icon associated with the window class. The
GetClassInfo function does not retrieve a handle to the small
icon.
GetClassInfoW
Retrieves information about a window class.
GetClassLongA
Retrieves the specified 32-bit (DWORD) value from the
WNDCLASSEX structure associated with the specified window.
GetClassLongPtrA
Retrieves the specified value from the WNDCLASSEX structure
associated with the specified window.
GetClassLongPtrW
Retrieves the specified value from the WNDCLASSEX structure
associated with the specified window.
GetClassLongW
Retrieves the specified 32-bit (DWORD) value from the
WNDCLASSEX structure associated with the specified window.
GetClassName
Retrieves the name of the class to which the specified window
belongs.
GetClassNameA
Retrieves the name of the class to which the specified window
belongs.
GetClassNameW
Retrieves the name of the class to which the specified window
belongs.
GetClassWord
Retrieves the 16-bit (WORD) value at the specified offset into
the extra class memory for the window class to which the
specified window belongs.
GetClientRect
Retrieves the coordinates of a window's client area.
GetClipboardData
Retrieves data from the clipboard in a specified format. The
clipboard must have been opened previously.
GetClipboardFormatNameA
Retrieves from the clipboard the name of the specified
registered format. The function copies the name to the
specified buffer.
GetClipboardFormatNameW
Retrieves from the clipboard the name of the specified
registered format. The function copies the name to the
specified buffer.
T IT L E
DESC RIP T IO N
GetClipboardOwner
Retrieves the window handle of the current owner of the
clipboard.
GetClipboardSequenceNumber
Retrieves the clipboard sequence number for the current
window station.
GetClipboardViewer
Retrieves the handle to the first window in the clipboard
viewer chain.
GetClipCursor
Retrieves the screen coordinates of the rectangular area to
which the cursor is confined.
GetComboBoxInfo
Retrieves information about the specified combo box.
GetCurrentInputMessageSource
Retrieves the source of the input message.
GetCursor
Retrieves a handle to the current cursor.
GetCursorInfo
Retrieves information about the global cursor.
GetCursorPos
Retrieves the position of the mouse cursor, in screen
coordinates.
GetDC
The GetDC function retrieves a handle to a device context (DC)
for the client area of a specified window or for the entire
screen.
GetDCEx
The GetDCEx function retrieves a handle to a device context
(DC) for the client area of a specified window or for the entire
screen.
GetDesktopWindow
Retrieves a handle to the desktop window. The desktop
window covers the entire screen. The desktop window is the
area on top of which other windows are painted.
GetDialogBaseUnits
Retrieves the system's dialog base units, which are the average
width and height of characters in the system font.
GetDialogControlDpiChangeBehavior
Retrieves and per-monitor DPI scaling behavior overrides of a
child window in a dialog.
GetDialogDpiChangeBehavior
Returns the flags that might have been set on a given dialog
by an earlier call to SetDialogDpiChangeBehavior.
GetDisplayAutoRotationPreferences
Retrieves the screen auto-rotation preferences for the current
process.
GetDisplayAutoRotationPreferencesByProcessId
Retrieves the screen auto-rotation preferences for the process
indicated by the dwProcessId parameter.
GetDisplayConfigBufferSizes
The GetDisplayConfigBufferSizes function retrieves the size of
the buffers that are required to call the QueryDisplayConfig
function.
T IT L E
DESC RIP T IO N
GetDlgCtrlID
Retrieves the identifier of the specified control.
GetDlgItem
Retrieves a handle to a control in the specified dialog box.
GetDlgItemInt
Translates the text of a specified control in a dialog box into an
integer value.
GetDlgItemTextA
Retrieves the title or text associated with a control in a dialog
box.
GetDlgItemTextW
Retrieves the title or text associated with a control in a dialog
box.
GetDoubleClickTime
Retrieves the current double-click time for the mouse.
GetDpiForSystem
Returns the system DPI.
GetDpiForWindow
Returns the dots per inch (dpi) value for the associated
window.
GetDpiFromDpiAwarenessContext
Retrieves the DPI from a given DPI_AWARENESS_CONTEXT
handle. This enables you to determine the DPI of a thread
without needed to examine a window created within that
thread.
GetFocus
Retrieves the handle to the window that has the keyboard
focus, if the window is attached to the calling thread's message
queue.
GetForegroundWindow
Retrieves a handle to the foreground window (the window
with which the user is currently working). The system assigns a
slightly higher priority to the thread that creates the
foreground window than it does to other threads.
GetGestureConfig
Retrieves the configuration for which Windows Touch gesture
messages are sent from a window.
GetGestureExtraArgs
Retrieves additional information about a gesture from its
GESTUREINFO handle.
GetGestureInfo
Retrieves a GESTUREINFO structure given a handle to the
gesture information.
GetGuiResources
Retrieves the count of handles to graphical user interface (GUI)
objects in use by the specified process.
GetGUIThreadInfo
Retrieves information about the active window or a specified
GUI thread.
GetIconInfo
Retrieves information about the specified icon or cursor.
GetIconInfoExA
Retrieves information about the specified icon or cursor.
GetIconInfoEx extends GetIconInfo by using the newer
ICONINFOEX structure.
T IT L E
DESC RIP T IO N
GetIconInfoExW
Retrieves information about the specified icon or cursor.
GetIconInfoEx extends GetIconInfo by using the newer
ICONINFOEX structure.
GetInputState
Determines whether there are mouse-button or keyboard
messages in the calling thread's message queue.
GetKBCodePage
Retrieves the current code page.
GetKeyboardLayout
Retrieves the active input locale identifier (formerly called the
keyboard layout).
GetKeyboardLayoutList
Retrieves the input locale identifiers (formerly called keyboard
layout handles) corresponding to the current set of input
locales in the system. The function copies the identifiers to the
specified buffer.
GetKeyboardLayoutNameA
Retrieves the name of the active input locale identifier
(formerly called the keyboard layout) for the system.
GetKeyboardLayoutNameW
Retrieves the name of the active input locale identifier
(formerly called the keyboard layout) for the system.
GetKeyboardState
Copies the status of the 256 virtual keys to the specified
buffer.
GetKeyboardType
Retrieves information about the current keyboard.
GetKeyNameTextA
Retrieves a string that represents the name of a key.
GetKeyNameTextW
Retrieves a string that represents the name of a key.
GetKeyState
Retrieves the status of the specified virtual key. The status
specifies whether the key is up, down, or toggled (on, off—
alternating each time the key is pressed).
GetLastActivePopup
Determines which pop-up window owned by the specified
window was most recently active.
GetLastInputInfo
Retrieves the time of the last input event.
GetLayeredWindowAttributes
Retrieves the opacity and transparency color key of a layered
window.
GetListBoxInfo
Retrieves the number of items per column in a specified list
box.
GetMenu
Retrieves a handle to the menu assigned to the specified
window.
GetMenuBarInfo
Retrieves information about the specified menu bar.
GetMenuCheckMarkDimensions
Retrieves the dimensions of the default check-mark bitmap.
T IT L E
DESC RIP T IO N
GetMenuContextHelpId
Retrieves the Help context identifier associated with the
specified menu.
GetMenuDefaultItem
Determines the default menu item on the specified menu.
GetMenuInfo
Retrieves information about a specified menu.
GetMenuItemCount
Determines the number of items in the specified menu.
GetMenuItemID
Retrieves the menu item identifier of a menu item located at
the specified position in a menu.
GetMenuItemInfoA
Retrieves information about a menu item.
GetMenuItemInfoW
Retrieves information about a menu item.
GetMenuItemRect
Retrieves the bounding rectangle for the specified menu item.
GetMenuState
Retrieves the menu flags associated with the specified menu
item.
GetMenuStringA
Copies the text string of the specified menu item into the
specified buffer.
GetMenuStringW
Copies the text string of the specified menu item into the
specified buffer.
GetMessage
Retrieves a message from the calling thread's message queue.
The function dispatches incoming sent messages until a
posted message is available for retrieval.
GetMessageA
Retrieves a message from the calling thread's message queue.
The function dispatches incoming sent messages until a
posted message is available for retrieval.
GetMessageExtraInfo
Retrieves the extra message information for the current
thread. Extra message information is an application- or driverdefined value associated with the current thread's message
queue.
GetMessagePos
Retrieves the cursor position for the last message retrieved by
the GetMessage function.
GetMessageTime
Retrieves the message time for the last message retrieved by
the GetMessage function.
GetMessageW
Retrieves a message from the calling thread's message queue.
The function dispatches incoming sent messages until a
posted message is available for retrieval.
GetMonitorInfoA
The GetMonitorInfo function retrieves information about a
display monitor.
T IT L E
DESC RIP T IO N
GetMonitorInfoW
The GetMonitorInfo function retrieves information about a
display monitor.
GetMouseMovePointsEx
Retrieves a history of up to 64 previous coordinates of the
mouse or pen.
GetNextDlgGroupItem
Retrieves a handle to the first control in a group of controls
that precedes (or follows) the specified control in a dialog box.
GetNextDlgTabItem
Retrieves a handle to the first control that has the
WS_TABSTOP style that precedes (or follows) the specified
control.
GetNextWindow
Retrieves a handle to the next or previous window in the ZOrder. The next window is below the specified window; the
previous window is above.
GetOpenClipboardWindow
Retrieves the handle to the window that currently has the
clipboard open.
GetParent
Retrieves a handle to the specified window's parent or owner.
GetPhysicalCursorPos
Retrieves the position of the cursor in physical coordinates.
GetPointerCursorId
Retrieves the cursor identifier associated with the specified
pointer.
GetPointerDevice
Gets information about the pointer device.
GetPointerDeviceCursors
Gets the cursor IDs that are mapped to the cursors associated
with a pointer device.
GetPointerDeviceProperties
Gets device properties that aren't included in the
POINTER_DEVICE_INFO structure.
GetPointerDeviceRects
Gets the x and y range for the pointer device (in himetric) and
the x and y range (current resolution) for the display that the
pointer device is mapped to.
GetPointerDevices
Gets information about the pointer devices attached to the
system.
GetPointerFrameInfo
Gets the entire frame of information for the specified pointers
associated with the current message.
GetPointerFrameInfoHistory
Gets the entire frame of information (including coalesced input
frames) for the specified pointers associated with the current
message.
GetPointerFramePenInfo
Gets the entire frame of pen-based information for the
specified pointers (of type PT_PEN) associated with the current
message.
T IT L E
DESC RIP T IO N
GetPointerFramePenInfoHistory
Gets the entire frame of pen-based information (including
coalesced input frames) for the specified pointers (of type
PT_PEN) associated with the current message.
GetPointerFrameTouchInfo
Gets the entire frame of touch-based information for the
specified pointers (of type PT_TOUCH) associated with the
current message.
GetPointerFrameTouchInfoHistory
Gets the entire frame of touch-based information (including
coalesced input frames) for the specified pointers (of type
PT_TOUCH) associated with the current message.
GetPointerInfo
Gets the information for the specified pointer associated with
the current message.
GetPointerInfoHistory
Gets the information associated with the individual inputs, if
any, that were coalesced into the current message for the
specified pointer.
GetPointerInputTransform
Gets one or more transforms for the pointer information
coordinates associated with the current message.
GetPointerPenInfo
Gets the pen-based information for the specified pointer (of
type PT_PEN) associated with the current message.
GetPointerPenInfoHistory
Gets the pen-based information associated with the individual
inputs, if any, that were coalesced into the current message for
the specified pointer (of type PT_PEN).
GetPointerTouchInfo
Gets the touch-based information for the specified pointer (of
type PT_TOUCH) associated with the current message.
GetPointerTouchInfoHistory
Gets the touch-based information associated with the
individual inputs, if any, that were coalesced into the current
message for the specified pointer (of type PT_TOUCH).
GetPointerType
Retrieves the pointer type for a specified pointer.
GetPriorityClipboardFormat
Retrieves the first available clipboard format in the specified
list.
GetProcessDefaultLayout
Retrieves the default layout that is used when windows are
created with no parent or owner.
GetProcessWindowStation
Retrieves a handle to the current window station for the calling
process.
GetPropA
Retrieves a data handle from the property list of the specified
window. The character string identifies the handle to be
retrieved. The string and handle must have been added to the
property list by a previous call to the SetProp function.
T IT L E
DESC RIP T IO N
GetPropW
Retrieves a data handle from the property list of the specified
window. The character string identifies the handle to be
retrieved. The string and handle must have been added to the
property list by a previous call to the SetProp function.
GetQueueStatus
Retrieves the type of messages found in the calling thread's
message queue.
GetRawInputBuffer
Performs a buffered read of the raw input data.
GetRawInputData
Retrieves the raw input from the specified device.
GetRawInputDeviceInfoA
Retrieves information about the raw input device.
GetRawInputDeviceInfoW
Retrieves information about the raw input device.
GetRawInputDeviceList
Enumerates the raw input devices attached to the system.
GetRawPointerDeviceData
Gets the raw input data from the pointer device.
GetRegisteredRawInputDevices
Retrieves the information about the raw input devices for the
current application.
GetScrollBarInfo
The GetScrollBarInfo function retrieves information about the
specified scroll bar.
GetScrollInfo
The GetScrollInfo 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).
GetScrollPos
The GetScrollPos function retrieves the current position of the
scroll box (thumb) in the specified scroll bar.
GetScrollRange
The GetScrollRange function retrieves the current minimum
and maximum scroll box (thumb) positions for the specified
scroll bar.
GetShellWindow
Retrieves a handle to the Shell's desktop window.
GetSubMenu
Retrieves a handle to the drop-down menu or submenu
activated by the specified menu item.
GetSysColor
Retrieves the current color of the specified display element.
GetSysColorBrush
The GetSysColorBrush function retrieves a handle identifying a
logical brush that corresponds to the specified color index.
GetSystemDpiForProcess
Retrieves the system DPI associated with a given process. This
is useful for avoiding compatibility issues that arise from
sharing DPI-sensitive information between multiple systemaware processes with different system DPI values.
T IT L E
DESC RIP T IO N
GetSystemMenu
Enables the application to access the window menu (also
known as the system menu or the control menu) for copying
and modifying.
GetSystemMetrics
Retrieves the specified system metric or system configuration
setting.
GetSystemMetricsForDpi
Retrieves the specified system metric or system configuration
setting taking into account a provided DPI.
GetTabbedTextExtentA
The GetTabbedTextExtent function computes the width and
height of a character string.
GetTabbedTextExtentW
The GetTabbedTextExtent function computes the width and
height of a character string.
GetThreadDesktop
Retrieves a handle to the desktop assigned to the specified
thread.
GetThreadDpiAwarenessContext
Gets the DPI_AWARENESS_CONTEXT for the current thread.
GetThreadDpiHostingBehavior
Retrieves the DPI_HOSTING_BEHAVIOR from the current
thread.
GetTitleBarInfo
Retrieves information about the specified title bar.
GetTopWindow
Examines the Z order of the child windows associated with the
specified parent window and retrieves a handle to the child
window at the top of the Z order.
GetTouchInputInfo
Retrieves detailed information about touch inputs associated
with a particular touch input handle.
GetUnpredictedMessagePos
Gets pointer data before it has gone through touch prediction
processing.
GetUpdatedClipboardFormats
Retrieves the currently supported clipboard formats.
GetUpdateRect
The GetUpdateRect function retrieves the coordinates of the
smallest rectangle that completely encloses the update region
of the specified window.
GetUpdateRgn
The GetUpdateRgn 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).
GetUserObjectInformationA
Retrieves information about the specified window station or
desktop object.
GetUserObjectInformationW
Retrieves information about the specified window station or
desktop object.
GetUserObjectSecurity
Retrieves security information for the specified user object.
T IT L E
DESC RIP T IO N
GetWindow
Retrieves a handle to a window that has the specified
relationship (Z-Order or owner) to the specified window.
GetWindowContextHelpId
Retrieves the Help context identifier, if any, associated with the
specified window.
GetWindowDC
The GetWindowDC function retrieves the device context (DC)
for the entire window, including title bar, menus, and scroll
bars.
GetWindowDisplayAffinity
Retrieves the current display affinity setting, from any process,
for a given window.
GetWindowDpiAwarenessContext
Returns the DPI_AWARENESS_CONTEXT associated with a
window.
GetWindowDpiHostingBehavior
Returns the DPI_HOSTING_BEHAVIOR of the specified window.
GetWindowFeedbackSetting
Retrieves the feedback configuration for a window.
GetWindowInfo
Retrieves information about the specified window.
GetWindowLongA
Retrieves information about the specified window.
GetWindowLongPtrA
Retrieves information about the specified window. The function
also retrieves the value at a specified offset into the extra
window memory.
GetWindowLongPtrW
Retrieves information about the specified window. The function
also retrieves the value at a specified offset into the extra
window memory.
GetWindowLongW
Retrieves information about the specified window.
GetWindowModuleFileNameA
Retrieves the full path and file name of the module associated
with the specified window handle.
GetWindowModuleFileNameW
Retrieves the full path and file name of the module associated
with the specified window handle.
GetWindowPlacement
Retrieves the show state and the restored, minimized, and
maximized positions of the specified window.
GetWindowRect
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.
GetWindowRgn
The GetWindowRgn function obtains a copy of the window
region of a window.
GetWindowRgnBox
The GetWindowRgnBox function retrieves the dimensions of
the tightest bounding rectangle for the window region of a
window.
T IT L E
DESC RIP T IO N
GetWindowTextA
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. However, GetWindowText cannot retrieve
the text of a control in another application.
GetWindowTextLengthA
Retrieves the length, in characters, of the specified window's
title bar text (if the window has a title bar).
GetWindowTextLengthW
Retrieves the length, in characters, of the specified window's
title bar text (if the window has a title bar).
GetWindowTextW
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. However, GetWindowText cannot retrieve
the text of a control in another application.
GetWindowThreadProcessId
Retrieves the identifier of the thread that created the specified
window and, optionally, the identifier of the process that
created the window.
GID_ROTATE_ANGLE_FROM_ARGUMENT
The GID_ROTATE_ANGLE_FROM_ARGUMENT macro is used to
interpret the GID_ROTATE ullArgument value when receiving
the value in the WM_GESTURE structure.
GID_ROTATE_ANGLE_TO_ARGUMENT
Converts a radian value to an argument for rotation gesture
messages.
GrayStringA
The GrayString function draws gray text at the specified
location.
GrayStringW
The GrayString function draws gray text at the specified
location.
HAS_POINTER_CONFIDENCE_WPARAM
Checks whether the specified pointer message is considered
intentional rather than accidental.
HideCaret
Removes the caret from the screen. Hiding a caret does not
destroy its current shape or invalidate the insertion point.
HiliteMenuItem
Adds or removes highlighting from an item in a menu bar.
InflateRect
The InflateRect function increases or decreases the width and
height of the specified rectangle.
InitializeTouchInjection
Configures the touch injection context for the calling
application and initializes the maximum number of
simultaneous contacts that the app can inject.
InjectSyntheticPointerInput
Simulates pointer input (pen or touch).
InjectTouchInput
Simulates touch input.
T IT L E
DESC RIP T IO N
InSendMessage
Determines whether the current window procedure is
processing a message that was sent from another thread (in
the same process or a different process) by a call to the
SendMessage function.
InSendMessageEx
Determines whether the current window procedure is
processing a message that was sent from another thread (in
the same process or a different process).
InsertMenuA
Inserts a new menu item into a menu, moving other items
down the menu.
InsertMenuItemA
Inserts a new menu item at the specified position in a menu.
InsertMenuItemW
Inserts a new menu item at the specified position in a menu.
InsertMenuW
Inserts a new menu item into a menu, moving other items
down the menu.
InternalGetWindowText
Copies the text of the specified window's title bar (if it has one)
into a buffer.
IntersectRect
The IntersectRect function calculates the intersection of two
source rectangles and places the coordinates of the
intersection rectangle into the destination rectangle.
InvalidateRect
The InvalidateRect 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.
InvalidateRgn
The InvalidateRgn function invalidates the client area within
the specified region by adding it to the current update region
of a window.
InvertRect
The InvertRect function inverts a rectangle in a window by
performing a logical NOT operation on the color values for
each pixel in the rectangle's interior.
IS_INTRESOURCE
Determines whether a value is an integer identifier for a
resource.
IS_POINTER_CANCELED_WPARAM
Checks whether the specified pointer input ended abruptly, or
was invalid, indicating the interaction was not completed.
IS_POINTER_FIFTHBUTTON_WPARAM
Checks whether the specified pointer took fifth action.
IS_POINTER_FIRSTBUTTON_WPARAM
Checks whether the specified pointer took first action.
IS_POINTER_FLAG_SET_WPARAM
Checks whether a pointer macro sets the specified flag.
IS_POINTER_FOURTHBUTTON_WPARAM
Checks whether the specified pointer took fourth action.
IS_POINTER_INCONTACT_WPARAM
Checks whether the specified pointer is in contact.
T IT L E
DESC RIP T IO N
IS_POINTER_INRANGE_WPARAM
Checks whether the specified pointer is in range.
IS_POINTER_NEW_WPARAM
Checks whether the specified pointer is a new pointer.
IS_POINTER_SECONDBUTTON_WPARAM
Checks whether the specified pointer took second action.
IS_POINTER_THIRDBUTTON_WPARAM
Checks whether the specified pointer took third action.
IsCharAlphaA
Determines whether a character is an alphabetical character.
This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharAlphaNumericA
Determines whether a character is either an alphabetical or a
numeric character. This determination is based on the
semantics of the language selected by the user during setup
or through Control Panel.
IsCharAlphaNumericW
Determines whether a character is either an alphabetical or a
numeric character. This determination is based on the
semantics of the language selected by the user during setup
or through Control Panel.
IsCharAlphaW
Determines whether a character is an alphabetical character.
This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharLowerA
Determines whether a character is lowercase. This
determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharLowerW
IsCharUpperA
Determines whether a character is uppercase. This
determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsCharUpperW
Determines whether a character is uppercase. This
determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
IsChild
Determines whether a window is a child window or
descendant window of a specified parent window.
IsClipboardFormatAvailable
Determines whether the clipboard contains data in the
specified format.
IsDialogMessageA
Determines whether a message is intended for the specified
dialog box and, if it is, processes the message.
IsDialogMessageW
Determines whether a message is intended for the specified
dialog box and, if it is, processes the message.
T IT L E
DESC RIP T IO N
IsDlgButtonChecked
The IsDlgButtonChecked function determines whether a
button control is checked or whether a three-state button
control is checked, unchecked, or indeterminate.
IsGUIThread
Determines whether the calling thread is already a GUI thread.
It can also optionally convert the thread to a GUI thread.
IsHungAppWindow
Determines whether the system considers that a specified
application is not responding.
IsIconic
Determines whether the specified window is minimized (iconic).
IsImmersiveProcess
Determines whether the process belongs to a Windows Store
app.
IsMenu
Determines whether a handle is a menu handle.
IsMouseInPointerEnabled
Indicates whether EnableMouseInPointer is set for the mouse
to act as a pointer input device and send WM_POINTER
messages.
IsProcessDPIAware
IsProcessDPIAware may be altered or unavailable. Instead, use
GetProcessDPIAwareness.
IsRectEmpty
The IsRectEmpty function determines whether the specified
rectangle is empty.
IsTouchWindow
Checks whether a specified window is touch-capable and,
optionally, retrieves the modifier flags set for the window's
touch capability.
IsValidDpiAwarenessContext
Determines if a specified DPI_AWARENESS_CONTEXT is valid
and supported by the current system.
IsWindow
Determines whether the specified window handle identifies an
existing window.
IsWindowEnabled
Determines whether the specified window is enabled for
mouse and keyboard input.
IsWindowUnicode
Determines whether the specified window is a native Unicode
window.
IsWindowVisible
Determines the visibility state of the specified window.
IsWinEventHookInstalled
Determines whether there is an installed WinEvent hook that
might be notified of a specified event.
IsWow64Message
Determines whether the last message read from the current
thread's queue originated from a WOW64 process.
IsZoomed
Determines whether a window is maximized.
T IT L E
DESC RIP T IO N
keybd_event
Synthesizes a keystroke.
KillTimer
Destroys the specified timer.
LoadAcceleratorsA
Loads the specified accelerator table.
LoadAcceleratorsW
Loads the specified accelerator table.
LoadBitmapA
The LoadBitmap function loads the specified bitmap resource
from a module's executable file.
LoadBitmapW
The LoadBitmap function loads the specified bitmap resource
from a module's executable file.
LoadCursorA
Loads the specified cursor resource from the executable (.EXE)
file associated with an application instance.
LoadCursorFromFileA
Creates a cursor based on data contained in a file.
LoadCursorFromFileW
Creates a cursor based on data contained in a file.
LoadCursorW
Loads the specified cursor resource from the executable (.EXE)
file associated with an application instance.
LoadIconA
Loads the specified icon resource from the executable (.exe) file
associated with an application instance.
LoadIconW
Loads the specified icon resource from the executable (.exe) file
associated with an application instance.
LoadImageA
Loads an icon, cursor, animated cursor, or bitmap.
LoadImageW
Loads an icon, cursor, animated cursor, or bitmap.
LoadKeyboardLayoutA
Loads a new input locale identifier (formerly called the
keyboard layout) into the system.
LoadKeyboardLayoutW
Loads a new input locale identifier (formerly called the
keyboard layout) into the system.
LoadMenuA
Loads the specified menu resource from the executable (.exe)
file associated with an application instance.
LoadMenuIndirectA
Loads the specified menu template in memory.
LoadMenuIndirectW
Loads the specified menu template in memory.
LoadMenuW
Loads the specified menu resource from the executable (.exe)
file associated with an application instance.
T IT L E
DESC RIP T IO N
LoadStringA
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.
LoadStringW
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.
LockSetForegroundWindow
The foreground process can call the
LockSetForegroundWindow function to disable calls to the
SetForegroundWindow function.
LockWindowUpdate
The LockWindowUpdate function disables or enables drawing
in the specified window. Only one window can be locked at a
time.
LockWorkStation
Locks the workstation's display.
LogicalToPhysicalPoint
Converts the logical coordinates of a point in a window to
physical coordinates.
LogicalToPhysicalPointForPerMonitorDPI
Converts a point in a window from logical coordinates into
physical coordinates, regardless of the dots per inch (dpi)
awareness of the caller.
LookupIconIdFromDirectory
Searches through icon or cursor data for the icon or cursor
that best fits the current display device.
LookupIconIdFromDirectoryEx
Searches through icon or cursor data for the icon or cursor
that best fits the current display device.
MAKEINTRESOURCEA
Converts an integer value to a resource type compatible with
the resource-management functions. This macro is used in
place of a string containing the name of the resource.
MAKEINTRESOURCEW
Converts an integer value to a resource type compatible with
the resource-management functions. This macro is used in
place of a string containing the name of the resource.
MAKELPARAM
Creates a value for use as an lParam parameter in a message.
The macro concatenates the specified values.
MAKELRESULT
Creates a value for use as a return value from a window
procedure. The macro concatenates the specified values.
MAKEWPARAM
Creates a value for use as a wParam parameter in a message.
The macro concatenates the specified values.
MapDialogRect
Converts the specified dialog box units to screen units (pixels).
MapVirtualKeyA
Translates (maps) a virtual-key code into a scan code or
character value, or translates a scan code into a virtual-key
code.
T IT L E
DESC RIP T IO N
MapVirtualKeyExA
Translates (maps) a virtual-key code into a scan code or
character value, or translates a scan code into a virtual-key
code. The function translates the codes using the input
language and an input locale identifier.
MapVirtualKeyExW
Translates (maps) a virtual-key code into a scan code or
character value, or translates a scan code into a virtual-key
code. The function translates the codes using the input
language and an input locale identifier.
MapVirtualKeyW
Translates (maps) a virtual-key code into a scan code or
character value, or translates a scan code into a virtual-key
code.
MapWindowPoints
The MapWindowPoints function converts (maps) a set of
points from a coordinate space relative to one window to a
coordinate space relative to another window.
MenuItemFromPoint
Determines which menu item, if any, is at the specified
location.
MessageBeep
Plays a waveform sound. The waveform sound for each sound
type is identified by an entry in the registry.
MessageBox
Displays a modal dialog box that contains a system icon, a set
of buttons, and a brief application-specific message, such as
status or error information. The message box returns an
integer value that indicates which button the user clicked.
MessageBoxA
Displays a modal dialog box that contains a system icon, a set
of buttons, and a brief application-specific message, such as
status or error information. The message box returns an
integer value that indicates which button the user clicked.
MessageBoxExA
Creates, displays, and operates a message box.
MessageBoxExW
Creates, displays, and operates a message box.
MessageBoxIndirectA
Creates, displays, and operates a message box. The message
box contains application-defined message text and title, any
icon, and any combination of predefined push buttons.
MessageBoxIndirectW
Creates, displays, and operates a message box. The message
box contains application-defined message text and title, any
icon, and any combination of predefined push buttons.
MessageBoxW
Displays a modal dialog box that contains a system icon, a set
of buttons, and a brief application-specific message, such as
status or error information. The message box returns an
integer value that indicates which button the user clicked.
ModifyMenuA
Changes an existing menu item.
ModifyMenuW
Changes an existing menu item.
T IT L E
DESC RIP T IO N
MonitorFromPoint
The MonitorFromPoint function retrieves a handle to the
display monitor that contains a specified point.
MonitorFromRect
The MonitorFromRect function retrieves a handle to the
display monitor that has the largest area of intersection with a
specified rectangle.
MonitorFromWindow
The MonitorFromWindow function retrieves a handle to the
display monitor that has the largest area of intersection with
the bounding rectangle of a specified window.
mouse_event
The mouse_event function synthesizes mouse motion and
button clicks.
MoveWindow
Changes the position and dimensions of the specified window.
MsgWaitForMultipleObjects
Waits until one or all of the specified objects are in the
signaled state or the time-out interval elapses. The objects can
include input event objects.
MsgWaitForMultipleObjectsEx
Waits until 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. The array of objects can include input event
objects.
NEXTRAWINPUTBLOCK
Retrieves the location of the next structure in an array of
RAWINPUT structures.
NotifyWinEvent
Signals the system that a predefined event occurred. If any
client applications have registered a hook function for the
event, the system calls the client's hook function.
OemKeyScan
Maps OEMASCII codes 0 through 0x0FF into the OEM scan
codes and shift states. The function provides information that
allows a program to send OEM text to another program by
simulating keyboard input.
OemToCharA
Translates a string from the OEM-defined character set into
either an ANSI or a wide-character string.Warning Do not use.
OemToCharBuffA
Translates a specified number of characters in a string from the
OEM-defined character set into either an ANSI or a widecharacter string.
OemToCharBuffW
Translates a specified number of characters in a string from the
OEM-defined character set into either an ANSI or a widecharacter string.
OemToCharW
Translates a string from the OEM-defined character set into
either an ANSI or a wide-character string.Warning Do not use.
OffsetRect
The OffsetRect function moves the specified rectangle by the
specified offsets.
T IT L E
DESC RIP T IO N
OpenClipboard
Opens the clipboard for examination and prevents other
applications from modifying the clipboard content.
OpenDesktopA
Opens the specified desktop object.
OpenDesktopW
Opens the specified desktop object.
OpenIcon
Restores a minimized (iconic) window to its previous size and
position; it then activates the window.
OpenInputDesktop
Opens the desktop that receives user input.
OpenWindowStationA
Opens the specified window station.
OpenWindowStationW
Opens the specified window station.
PackTouchHitTestingProximityEvaluation
Returns the proximity evaluation score and the adjusted
touch-point coordinates as a packed value for the
WM_TOUCHHITTESTING callback.
PaintDesktop
The PaintDesktop function fills the clipping region in the
specified device context with the desktop pattern or wallpaper.
The function is provided primarily for shell desktops.
PeekMessageA
Dispatches incoming sent messages, checks the thread
message queue for a posted message, and retrieves the
message (if any exist).
PeekMessageW
Dispatches incoming sent messages, checks the thread
message queue for a posted message, and retrieves the
message (if any exist).
PhysicalToLogicalPoint
Converts the physical coordinates of a point in a window to
logical coordinates.
PhysicalToLogicalPointForPerMonitorDPI
Converts a point in a window from logical coordinates into
physical coordinates, regardless of the dots per inch (dpi)
awareness of the caller.
POINTSTOPOINT
The POINTSTOPOINT macro copies the contents of a POINTS
structure into a POINT structure.
POINTTOPOINTS
The POINTTOPOINTS macro converts a POINT structure to a
POINTS structure.
PostMessageA
Places (posts) a message in the message queue associated
with the thread that created the specified window and returns
without waiting for the thread to process the message.
PostMessageW
Places (posts) a message in the message queue associated
with the thread that created the specified window and returns
without waiting for the thread to process the message.
T IT L E
DESC RIP T IO N
PostQuitMessage
Indicates to the system that a thread has made a request to
terminate (quit). It is typically used in response to a
WM_DESTROY message.
PostThreadMessageA
Posts a message to the message queue of the specified thread.
It returns without waiting for the thread to process the
message.
PostThreadMessageW
Posts a message to the message queue of the specified thread.
It returns without waiting for the thread to process the
message.
PrintWindow
The PrintWindow function copies a visual window into the
specified device context (DC), typically a printer DC.
PrivateExtractIconsA
Creates an array of handles to icons that are extracted from a
specified file.
PrivateExtractIconsW
Creates an array of handles to icons that are extracted from a
specified file.
PtInRect
The PtInRect function determines whether the specified point
lies within the specified rectangle.
QueryDisplayConfig
The QueryDisplayConfig function retrieves information about
all possible display paths for all display devices, or views, in the
current setting.
RealChildWindowFromPoint
Retrieves a handle to the child window at the specified point.
The search is restricted to immediate child windows;
grandchildren and deeper descendant windows are not
searched.
RealGetWindowClassW
Retrieves a string that specifies the window type.
RedrawWindow
The RedrawWindow function updates the specified rectangle
or region in a window's client area.
RegisterClassA
Registers a window class for subsequent use in calls to the
CreateWindow or CreateWindowEx function.
RegisterClassExA
Registers a window class for subsequent use in calls to the
CreateWindow or CreateWindowEx function.
RegisterClassExW
Registers a window class for subsequent use in calls to the
CreateWindow or CreateWindowEx function.
RegisterClassW
Registers a window class for subsequent use in calls to the
CreateWindow or CreateWindowEx function.
RegisterClipboardFormatA
Registers a new clipboard format. This format can then be
used as a valid clipboard format.
T IT L E
DESC RIP T IO N
RegisterClipboardFormatW
Registers a new clipboard format. This format can then be
used as a valid clipboard format.
RegisterDeviceNotificationA
Registers the device or type of device for which a window will
receive notifications.
RegisterDeviceNotificationW
Registers the device or type of device for which a window will
receive notifications.
RegisterHotKey
Defines a system-wide hot key.
RegisterPointerDeviceNotifications
Registers a window to process the
WM_POINTERDEVICECHANGE,
WM_POINTERDEVICEINRANGE, and
WM_POINTERDEVICEOUTOFRANGE pointer device
notifications.
RegisterPointerInputTarget
Allows the caller to register a target window to which all
pointer input of the specified type is redirected.
RegisterPointerInputTargetEx
RegisterPointerInputTargetEx may be altered or unavailable.
Instead, use RegisterPointerInputTarget.
RegisterPowerSettingNotification
Registers the application to receive power setting notifications
for the specific power setting event.
RegisterRawInputDevices
Registers the devices that supply the raw input data.
RegisterShellHookWindow
Registers a specified Shell window to receive certain messages
for events or notifications that are useful to Shell applications.
RegisterSuspendResumeNotification
Registers to receive notification when the system is suspended
or resumed. Similar to
PowerRegisterSuspendResumeNotification, but operates in
user mode and can take a window handle.
RegisterTouchHitTestingWindow
Registers a window to process the WM_TOUCHHITTESTING
notification.
RegisterTouchWindow
Registers a window as being touch-capable.
RegisterWindowMessageA
Defines a new window message that is guaranteed to be
unique throughout the system. The message value can be
used when sending or posting messages.
RegisterWindowMessageW
Defines a new window message that is guaranteed to be
unique throughout the system. The message value can be
used when sending or posting messages.
ReleaseCapture
Releases the mouse capture from a window in the current
thread and restores normal mouse input processing.
T IT L E
DESC RIP T IO N
ReleaseDC
The ReleaseDC function releases a device context (DC), freeing
it for use by other applications. The effect of the ReleaseDC
function depends on the type of DC. It frees only common
and window DCs. It has no effect on class or private DCs.
RemoveClipboardFormatListener
Removes the given window from the system-maintained
clipboard format listener list.
RemoveMenu
Deletes a menu item or detaches a submenu from the
specified menu.
RemovePropA
Removes an entry from the property list of the specified
window. The specified character string identifies the entry to
be removed.
RemovePropW
Removes an entry from the property list of the specified
window. The specified character string identifies the entry to
be removed.
ReplyMessage
Replies to a message sent from another thread by the
SendMessage function.
ScreenToClient
The ScreenToClient function converts the screen coordinates of
a specified point on the screen to client-area coordinates.
ScrollDC
The ScrollDC function scrolls a rectangle of bits horizontally
and vertically.
ScrollWindow
The ScrollWindow function scrolls the contents of the specified
window's client area.
ScrollWindowEx
The ScrollWindowEx function scrolls the contents of the
specified window's client area.
SendDlgItemMessageA
Sends a message to the specified control in a dialog box.
SendDlgItemMessageW
Sends a message to the specified control in a dialog box.
SendInput
Synthesizes keystrokes, mouse motions, and button clicks.
SendMessage
Sends the specified message to a window or windows. The
SendMessage function calls the window procedure for the
specified window and does not return until the window
procedure has processed the message.
SendMessageA
Sends the specified message to a window or windows. The
SendMessage function calls the window procedure for the
specified window and does not return until the window
procedure has processed the message.
SendMessageCallbackA
Sends the specified message to a window or windows.
SendMessageCallbackW
Sends the specified message to a window or windows.
T IT L E
DESC RIP T IO N
SendMessageTimeoutA
Sends the specified message to one or more windows.
SendMessageTimeoutW
Sends the specified message to one or more windows.
SendMessageW
Sends the specified message to a window or windows. The
SendMessage function calls the window procedure for the
specified window and does not return until the window
procedure has processed the message.
SendNotifyMessageA
Sends the specified message to a window or windows.
SendNotifyMessageW
Sends the specified message to a window or windows.
SetActiveWindow
Activates a window. The window must be attached to the
calling thread's message queue.
SetCapture
Sets the mouse capture to the specified window belonging to
the current thread.
SetCaretBlinkTime
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.
SetCaretPos
Moves the caret to the specified coordinates. If the window
that owns the caret was created with the CS_OWNDC class
style, then the specified coordinates are subject to the
mapping mode of the device context associated with that
window.
SetClassLongA
Replaces the specified 32-bit (long) value at the specified offset
into the extra class memory or the WNDCLASSEX structure for
the class to which the specified window belongs.
SetClassLongPtrA
Replaces the specified value at the specified offset in the extra
class memory or the WNDCLASSEX structure for the class to
which the specified window belongs.
SetClassLongPtrW
Replaces the specified value at the specified offset in the extra
class memory or the WNDCLASSEX structure for the class to
which the specified window belongs.
SetClassLongW
Replaces the specified 32-bit (long) value at the specified offset
into the extra class memory or the WNDCLASSEX structure for
the class to which the specified window belongs.
SetClassWord
Replaces the 16-bit (WORD) value at the specified offset into
the extra class memory for the window class to which the
specified window belongs.
SetClipboardData
Places data on the clipboard in a specified clipboard format.
T IT L E
DESC RIP T IO N
SetClipboardViewer
Adds the specified window to the chain of clipboard viewers.
Clipboard viewer windows receive a WM_DRAWCLIPBOARD
message whenever the content of the clipboard changes. This
function is used for backward compatibility with earlier
versions of Windows.
SetCoalescableTimer
Creates a timer with the specified time-out value and
coalescing tolerance delay.
SetCursor
Sets the cursor shape.
SetCursorPos
Moves the cursor to the specified screen coordinates.
SetDialogControlDpiChangeBehavior
Overrides the default per-monitor DPI scaling behavior of a
child window in a dialog.
SetDialogDpiChangeBehavior
Dialogs in Per-Monitor v2 contexts are automatically DPI
scaled. This method lets you customize their DPI change
behavior.
SetDisplayAutoRotationPreferences
Sets the screen auto-rotation preferences for the current
process.
SetDisplayConfig
The SetDisplayConfig function modifies the display topology,
source, and target modes by exclusively enabling the specified
paths in the current session.
SetDlgItemInt
Sets the text of a control in a dialog box to the string
representation of a specified integer value.
SetDlgItemTextA
Sets the title or text of a control in a dialog box.
SetDlgItemTextW
Sets the title or text of a control in a dialog box.
SetDoubleClickTime
Sets the double-click time for the mouse.
SetFocus
Sets the keyboard focus to the specified window. The window
must be attached to the calling thread's message queue.
SetForegroundWindow
Brings the thread that created the specified window into the
foreground and activates the window.
SetGestureConfig
Configures the messages that are sent from a window for
Windows Touch gestures.
SetKeyboardState
Copies an array of keyboard key states into the calling thread's
keyboard input-state table. This is the same table accessed by
the GetKeyboardState and GetKeyState functions. Changes
made to this table do not affect keyboard input to any other
thread.
SetLastErrorEx
Sets the last-error code.
T IT L E
DESC RIP T IO N
SetLayeredWindowAttributes
Sets the opacity and transparency color key of a layered
window.
SetMenu
Assigns a new menu to the specified window.
SetMenuContextHelpId
Associates a Help context identifier with a menu.
SetMenuDefaultItem
Sets the default menu item for the specified menu.
SetMenuInfo
Sets information for a specified menu.
SetMenuItemBitmaps
Associates the specified bitmap with a menu item. Whether
the menu item is selected or clear, the system displays the
appropriate bitmap next to the menu item.
SetMenuItemInfoA
Changes information about a menu item.
SetMenuItemInfoW
Changes information about a menu item.
SetMessageExtraInfo
Sets the extra message information for the current thread.
SetParent
Changes the parent window of the specified child window.
SetPhysicalCursorPos
Sets the position of the cursor in physical coordinates.
SetProcessDefaultLayout
Changes the default layout when windows are created with no
parent or owner only for the currently running process.
SetProcessDPIAware
SetProcessDPIAware may be altered or unavailable. Instead,
use SetProcessDPIAwareness.
SetProcessDpiAwarenessContext
Sets the current process to a specified dots per inch (dpi)
awareness context. The DPI awareness contexts are from the
DPI_AWARENESS_CONTEXT value.
SetProcessRestrictionExemption
Exempts the calling process from restrictions preventing
desktop processes from interacting with the Windows Store
app environment. This function is used by development and
debugging tools.
SetProcessWindowStation
Assigns the specified window station to the calling process.
SetPropA
Adds a new entry or changes an existing entry in the property
list of the specified window.
SetPropW
Adds a new entry or changes an existing entry in the property
list of the specified window.
SetRect
The SetRect 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.
T IT L E
DESC RIP T IO N
SetRectEmpty
The SetRectEmpty function creates an empty rectangle in
which all coordinates are set to zero.
SetScrollInfo
The SetScrollInfo 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). The
function also redraws the scroll bar, if requested.
SetScrollPos
The SetScrollPos 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.
SetScrollRange
The SetScrollRange function sets the minimum and maximum
scroll box positions for the specified scroll bar.
SetSysColors
Sets the colors for the specified display elements.
SetSystemCursor
Enables an application to customize the system cursors. It
replaces the contents of the system cursor specified by the id
parameter with the contents of the cursor specified by the
hcur parameter and then destroys hcur.
SetThreadDesktop
Assigns the specified desktop to the calling thread. All
subsequent operations on the desktop use the access rights
granted to the desktop.
SetThreadDpiAwarenessContext
Set the DPI awareness for the current thread to the provided
value.
SetThreadDpiHostingBehavior
Sets the thread's DPI_HOSTING_BEHAVIOR. This behavior
allows windows created in the thread to host child windows
with a different DPI_AWARENESS_CONTEXT.
SetTimer
Creates a timer with the specified time-out value.
SetUserObjectInformationA
Sets information about the specified window station or
desktop object.
SetUserObjectInformationW
Sets information about the specified window station or
desktop object.
SetUserObjectSecurity
Sets the security of a user object. This can be, for example, a
window or a DDE conversation.
SetWindowContextHelpId
Associates a Help context identifier with the specified window.
SetWindowDisplayAffinity
Stores the display affinity setting in kernel mode on the hWnd
associated with the window.
SetWindowFeedbackSetting
Sets the feedback configuration for a window.
SetWindowLongA
Changes an attribute of the specified window. The function
also sets the 32-bit (long) value at the specified offset into the
extra window memory.
T IT L E
DESC RIP T IO N
SetWindowLongPtrA
Changes an attribute of the specified window.
SetWindowLongPtrW
Changes an attribute of the specified window.
SetWindowLongW
Changes an attribute of the specified window. The function
also sets the 32-bit (long) value at the specified offset into the
extra window memory.
SetWindowPlacement
Sets the show state and the restored, minimized, and
maximized positions of the specified window.
SetWindowPos
Changes the size, position, and Z order of a child, pop-up, or
top-level window. These 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.
SetWindowRgn
The SetWindowRgn function sets the window region of a
window.
SetWindowsHookExA
Installs an application-defined hook procedure into a hook
chain.
SetWindowsHookExW
Installs an application-defined hook procedure into a hook
chain.
SetWindowTextA
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. However, SetWindowText cannot change
the text of a control in another application.
SetWindowTextW
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. However, SetWindowText cannot change
the text of a control in another application.
SetWinEventHook
Sets an event hook function for a range of events.
ShowCaret
Makes the caret visible on the screen at the caret's current
position. When the caret becomes visible, it begins flashing
automatically.
ShowCursor
Displays or hides the cursor.
ShowOwnedPopups
Shows or hides all pop-up windows owned by the specified
window.
ShowScrollBar
The ShowScrollBar function shows or hides the specified scroll
bar.
ShowWindow
Sets the specified window's show state.
ShowWindowAsync
Sets the show state of a window without waiting for the
operation to complete.
T IT L E
DESC RIP T IO N
ShutdownBlockReasonCreate
Indicates that the system cannot be shut down and sets a
reason string to be displayed to the user if system shutdown
is initiated.
ShutdownBlockReasonDestroy
Indicates that the system can be shut down and frees the
reason string.
ShutdownBlockReasonQuery
Retrieves the reason string set by the
ShutdownBlockReasonCreate function.
SkipPointerFrameMessages
Determines which pointer input frame generated the most
recently retrieved message for the specified pointer and
discards any queued (unretrieved) pointer input messages
generated from the same pointer input frame.
SoundSentry
Triggers a visual signal to indicate that a sound is playing.
SubtractRect
The SubtractRect function determines the coordinates of a
rectangle formed by subtracting one rectangle from another.
SwapMouseButton
Reverses or restores the meaning of the left and right mouse
buttons.
SwitchDesktop
Makes the specified desktop visible and activates it. This
enables the desktop to receive input from the user.
SwitchToThisWindow
Switches focus to the specified window and brings it to the
foreground.
SystemParametersInfoA
Retrieves or sets the value of one of the system-wide
parameters.
SystemParametersInfoForDpi
Retrieves the value of one of the system-wide parameters,
taking into account the provided DPI value.
SystemParametersInfoW
Retrieves or sets the value of one of the system-wide
parameters.
TabbedTextOutA
The TabbedTextOut function writes a character string at a
specified location, expanding tabs to the values specified in an
array of tab-stop positions. Text is written in the currently
selected font, background color, and text color.
TabbedTextOutW
The TabbedTextOut function writes a character string at a
specified location, expanding tabs to the values specified in an
array of tab-stop positions. Text is written in the currently
selected font, background color, and text color.
TileWindows
Tiles the specified child windows of the specified parent
window.
ToAscii
Translates the specified virtual-key code and keyboard state to
the corresponding character or characters.
T IT L E
DESC RIP T IO N
ToAsciiEx
Translates the specified virtual-key code and keyboard state to
the corresponding character or characters. The function
translates the code using the input language and physical
keyboard layout identified by the input locale identifier.
TOUCH_COORD_TO_PIXEL
Converts touch coordinates to pixels.
ToUnicode
Translates the specified virtual-key code and keyboard state to
the corresponding Unicode character or characters.
ToUnicodeEx
Translates the specified virtual-key code and keyboard state to
the corresponding Unicode character or characters.
TrackMouseEvent
Posts messages when the mouse pointer leaves a window or
hovers over a window for a specified amount of time.
TrackPopupMenu
Displays a shortcut menu at the specified location and tracks
the selection of items on the menu. The shortcut menu can
appear anywhere on the screen.
TrackPopupMenuEx
Displays a shortcut menu at the specified location and tracks
the selection of items on the shortcut menu. The shortcut
menu can appear anywhere on the screen.
TranslateAcceleratorA
Processes accelerator keys for menu commands.
TranslateAcceleratorW
Processes accelerator keys for menu commands.
TranslateMDISysAccel
Processes accelerator keystrokes for window menu commands
of the multiple-document interface (MDI) child windows
associated with the specified MDI client window.
TranslateMessage
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.
UnhookWindowsHookEx
Removes a hook procedure installed in a hook chain by the
SetWindowsHookEx function.
UnhookWinEvent
Removes an event hook function created by a previous call to
SetWinEventHook.
UnionRect
The UnionRect function creates the union of two rectangles.
The union is the smallest rectangle that contains both source
rectangles.
UnloadKeyboardLayout
Unloads an input locale identifier (formerly called a keyboard
layout).
UnregisterClassA
Unregisters a window class, freeing the memory required for
the class.
T IT L E
DESC RIP T IO N
UnregisterClassW
Unregisters a window class, freeing the memory required for
the class.
UnregisterDeviceNotification
Closes the specified device notification handle.
UnregisterHotKey
Frees a hot key previously registered by the calling thread.
UnregisterPointerInputTarget
Allows the caller to unregister a target window to which all
pointer input of the specified type is redirected.
UnregisterPointerInputTargetEx
UnregisterPointerInputTargetEx may be altered or unavailable.
Instead, use UnregisterPointerInputTarget.
UnregisterPowerSettingNotification
Unregisters the power setting notification.
UnregisterSuspendResumeNotification
Cancels a registration to receive notification when the system
is suspended or resumed. Similar to
PowerUnregisterSuspendResumeNotification but operates in
user mode.
UnregisterTouchWindow
Registers a window as no longer being touch-capable.
UpdateLayeredWindow
Updates the position, size, shape, content, and translucency of
a layered window.
UpdateWindow
The UpdateWindow 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.
UserHandleGrantAccess
Grants or denies access to a handle to a User object to a job
that has a user-interface restriction.
ValidateRect
The ValidateRect function validates the client area within a
rectangle by removing the rectangle from the update region
of the specified window.
ValidateRgn
The ValidateRgn function validates the client area within a
region by removing the region from the current update region
of the specified window.
VkKeyScanA
Translates a character to the corresponding virtual-key code
and shift state for the current keyboard.
VkKeyScanExA
Translates a character to the corresponding virtual-key code
and shift state. The function translates the character using the
input language and physical keyboard layout identified by the
input locale identifier.
VkKeyScanExW
Translates a character to the corresponding virtual-key code
and shift state. The function translates the character using the
input language and physical keyboard layout identified by the
input locale identifier.
T IT L E
DESC RIP T IO N
VkKeyScanW
Translates a character to the corresponding virtual-key code
and shift state for the current keyboard.
WaitForInputIdle
Waits until the specified process has finished processing its
initial input and is waiting for user input with no input
pending, or until the time-out interval has elapsed.
WaitMessage
Yields control to other threads when a thread has no other
messages in its message queue. The WaitMessage function
suspends the thread and does not return until a new message
is placed in the thread's message queue.
WindowFromDC
The WindowFromDC function returns a handle to the window
associated with the specified display device context (DC).
Output functions that use the specified device context draw
into this window.
WindowFromPhysicalPoint
Retrieves a handle to the window that contains the specified
physical point.
WindowFromPoint
Retrieves a handle to the window that contains the specified
point.
WinHelpA
Launches Windows Help (Winhelp.exe) and passes additional
data that indicates the nature of the help requested by the
application.
WinHelpW
Launches Windows Help (Winhelp.exe) and passes additional
data that indicates the nature of the help requested by the
application.
wsprintfA
Writes formatted data to the specified buffer.
wsprintfW
Writes formatted data to the specified buffer.
wvsprintfA
Writes formatted data to the specified buffer using a pointer
to a list of arguments.
wvsprintfW
Writes formatted data to the specified buffer using a pointer
to a list of arguments.
Callback functions
T IT L E
DESC RIP T IO N
DLGPROC
Application-defined callback function used with the
CreateDialog and DialogBox families of functions.
DRAWSTATEPROC
The DrawStateProc function is an application-defined callback
function that renders a complex image for the DrawState
function.
T IT L E
DESC RIP T IO N
EDITWORDBREAKPROCA
An application-defined callback function used with the
EM_SETWORDBREAKPROC message.
EDITWORDBREAKPROCW
An application-defined callback function used with the
EM_SETWORDBREAKPROC message.
GRAYSTRINGPROC
The OutputProc function is an application-defined callback
function used with the GrayString function.
HOOKPROC
An application-defined or library-defined callback function
used with the SetWindowsHookEx function. The system calls
this function after the SendMessage function is called. The
hook procedure can examine the message; it cannot modify it.
MONITORENUMPROC
A MonitorEnumProc function is an application-defined callback
function that is called by the EnumDisplayMonitors function.
PROPENUMPROCA
An application-defined callback function used with the
EnumProps function.
PROPENUMPROCEXA
Application-defined callback function used with the
EnumPropsEx function.
PROPENUMPROCEXW
Application-defined callback function used with the
EnumPropsEx function.
PROPENUMPROCW
An application-defined callback function used with the
EnumProps function.
SENDASYNCPROC
An application-defined callback function used with the
SendMessageCallback function.
TIMERPROC
An application-defined callback function that processes
WM_TIMER messages. The TIMERPROC type defines a pointer
to this callback function. TimerProc is a placeholder for the
application-defined function name.
WINEVENTPROC
An application-defined callback (or hook) function that the
system calls in response to events generated by an accessible
object.
Structures
T IT L E
DESC RIP T IO N
ACCEL
Defines an accelerator key used in an accelerator table.
ACCESSTIMEOUT
Contains information about the time-out period associated
with the accessibility features.
ALTTABINFO
Contains status information for the application-switching
(ALT+TAB) window.
T IT L E
DESC RIP T IO N
ANIMATIONINFO
Describes the animation effects associated with user actions.
AUDIODESCRIPTION
Contains information associated with audio descriptions. This
structure is used with the SystemParametersInfo function
when the SPI_GETAUDIODESCRIPTION or
SPI_SETAUDIODESCRIPTION action value is specified.
BSMINFO
Contains information about a window that denied a request
from BroadcastSystemMessageEx.
CBT_CREATEWNDA
Contains information passed to a WH_CBT hook procedure,
CBTProc, before a window is created.
CBT_CREATEWNDW
Contains information passed to a WH_CBT hook procedure,
CBTProc, before a window is created.
CBTACTIVATESTRUCT
Contains information passed to a WH_CBT hook procedure,
CBTProc, before a window is activated.
CHANGEFILTERSTRUCT
Contains extended result information obtained by calling the
ChangeWindowMessageFilterEx function.
CLIENTCREATESTRUCT
Contains information about the menu and first multipledocument interface (MDI) child window of an MDI client
window.
COMBOBOXINFO
Contains combo box status information.
COMPAREITEMSTRUCT
Supplies the identifiers and application-supplied data for two
items in a sorted, owner-drawn list box or combo box.
COPYDATASTRUCT
Contains data to be passed to another application by the
WM_COPYDATA message.
CREATESTRUCTA
Defines the initialization parameters passed to the window
procedure of an application. These members are identical to
the parameters of the CreateWindowEx function.
CREATESTRUCTW
Defines the initialization parameters passed to the window
procedure of an application. These members are identical to
the parameters of the CreateWindowEx function.
CURSORINFO
Contains global cursor information.
CURSORSHAPE
Contains information about a cursor.
CWPRETSTRUCT
Defines the message parameters passed to a
WH_CALLWNDPROCRET hook procedure, CallWndRetProc.
CWPSTRUCT
Defines the message parameters passed to a
WH_CALLWNDPROC hook procedure, CallWndProc.
DEBUGHOOKINFO
Contains debugging information passed to a WH_DEBUG
hook procedure, DebugProc.
T IT L E
DESC RIP T IO N
DELETEITEMSTRUCT
Describes a deleted list box or combo box item.
DLGITEMTEMPLATE
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 standard template for a
dialog box.
DLGTEMPLATE
Defines the dimensions and style of a dialog box.
DRAWITEMSTRUCT
Provides information that the owner window uses to
determine how to paint an owner-drawn control or menu
item.
DRAWTEXTPARAMS
The DRAWTEXTPARAMS structure contains extended
formatting options for the DrawTextEx function.
EVENTMSG
Contains information about a hardware message sent to the
system message queue. This structure is used to store
message information for the JournalPlaybackProc callback
function.
FILTERKEYS
Contains information about the FilterKeys accessibility feature,
which enables a user with disabilities to set the keyboard
repeat rate (RepeatKeys), acceptance delay (SlowKeys), and
bounce rate (BounceKeys).
FLASHWINFO
Contains the flash status for a window and the number of
times the system should flash the window.
GESTURECONFIG
Gets and sets the configuration for enabling gesture messages
and the type of this configuration.
GESTUREINFO
Stores information about a gesture.
GESTURENOTIFYSTRUCT
When transmitted with WM_GESTURENOTIFY messages,
passes information about a gesture.
GUITHREADINFO
Contains information about a GUI thread.
HARDWAREINPUT
Contains information about a simulated message generated
by an input device other than a keyboard or mouse.
HELPINFO
Contains information about an item for which contextsensitive Help has been requested.
HELPWININFOA
Contains the size and position of either a primary or
secondary Help window. An application can set this
information by calling the WinHelp function with the
HELP_SETWINPOS value.
HELPWININFOW
Contains the size and position of either a primary or
secondary Help window. An application can set this
information by calling the WinHelp function with the
HELP_SETWINPOS value.
T IT L E
DESC RIP T IO N
HIGHCONTRASTA
Contains information about the high contrast accessibility
feature.
HIGHCONTRASTW
Contains information about the high contrast accessibility
feature.
ICONINFO
Contains information about an icon or a cursor.
ICONINFOEXA
Contains information about an icon or a cursor. Extends
ICONINFO. Used by GetIconInfoEx.
ICONINFOEXW
Contains information about an icon or a cursor. Extends
ICONINFO. Used by GetIconInfoEx.
ICONMETRICSA
Contains the scalable metrics associated with icons. This
structure is used with the SystemParametersInfo function
when the SPI_GETICONMETRICS or SPI_SETICONMETRICS
action is specified.
ICONMETRICSW
Contains the scalable metrics associated with icons. This
structure is used with the SystemParametersInfo function
when the SPI_GETICONMETRICS or SPI_SETICONMETRICS
action is specified.
INPUT
Used by SendInput to store information for synthesizing input
events such as keystrokes, mouse movement, and mouse
clicks.
INPUT_INJECTION_VALUE
Contains the input injection details.
INPUT_MESSAGE_SOURCE
Contains information about the source of the input message.
INPUT_TRANSFORM
Defines the matrix that represents a transform on a message
consumer.
KBDLLHOOKSTRUCT
Contains information about a low-level keyboard input event.
KEYBDINPUT
Contains information about a simulated keyboard event.
LASTINPUTINFO
Contains the time of the last input.
MDICREATESTRUCTA
Contains information about the class, title, owner, location,
and size of a multiple-document interface (MDI) child window.
MDICREATESTRUCTW
Contains information about the class, title, owner, location,
and size of a multiple-document interface (MDI) child window.
MDINEXTMENU
Contains information about the menu to be activated.
MEASUREITEMSTRUCT
Informs the system of the dimensions of an owner-drawn
control or menu item. This allows the system to process user
interaction with the control correctly.
T IT L E
DESC RIP T IO N
MENUBARINFO
Contains menu bar information.
MENUGETOBJECTINFO
Contains information about the menu that the mouse cursor
is on.
MENUINFO
Contains information about a menu.
MENUITEMINFOA
Contains information about a menu item.
MENUITEMINFOW
Contains information about a menu item.
MENUITEMTEMPLATE
Defines a menu item in a menu template.
MENUITEMTEMPLATEHEADER
Defines the header for a menu template. A complete menu
template consists of a header and one or more menu item
lists.
MINIMIZEDMETRICS
Contains the scalable metrics associated with minimized
windows.
MINMAXINFO
Contains information about a window's maximized size and
position and its minimum and maximum tracking size.
MONITORINFO
The MONITORINFO structure contains information about a
display monitor.The GetMonitorInfo function stores
information in a MONITORINFO structure or a
MONITORINFOEX structure.The MONITORINFO structure is a
subset of the MONITORINFOEX structure.
MONITORINFOEXA
The MONITORINFOEX structure contains information about a
display monitor.The GetMonitorInfo function stores
information into a MONITORINFOEX structure or a
MONITORINFO structure.The MONITORINFOEX structure is a
superset of the MONITORINFO structure.
MONITORINFOEXW
The MONITORINFOEX structure contains information about a
display monitor.The GetMonitorInfo function stores
information into a MONITORINFOEX structure or a
MONITORINFO structure.The MONITORINFOEX structure is a
superset of the MONITORINFO structure.
MOUSEHOOKSTRUCT
Contains information about a mouse event passed to a
WH_MOUSE hook procedure, MouseProc.
MOUSEHOOKSTRUCTEX
Contains information about a mouse event passed to a
WH_MOUSE hook procedure, MouseProc. This is an extension
of the MOUSEHOOKSTRUCT structure that includes
information about wheel movement or the use of the X
button.
MOUSEINPUT
Contains information about a simulated mouse event.
MOUSEKEYS
Contains information about the MouseKeys accessibility
feature.
T IT L E
DESC RIP T IO N
MOUSEMOVEPOINT
Contains information about the mouse's location in screen
coordinates.
MSG
Contains message information from a thread's message
queue.
MSGBOXPARAMSA
Contains information used to display a message box. The
MessageBoxIndirect function uses this structure.
MSGBOXPARAMSW
Contains information used to display a message box. The
MessageBoxIndirect function uses this structure.
MSLLHOOKSTRUCT
Contains information about a low-level mouse input event.
MULTIKEYHELPA
Specifies a keyword to search for and the keyword table to be
searched by Windows Help.
MULTIKEYHELPW
Specifies a keyword to search for and the keyword table to be
searched by Windows Help.
NCCALCSIZE_PARAMS
Contains information that an application can use while
processing the WM_NCCALCSIZE message to calculate the
size, position, and valid contents of the client area of a window.
NMHDR
Contains information about a notification message.
NONCLIENTMETRICSA
Contains the scalable metrics associated with the nonclient
area of a nonminimized window.
NONCLIENTMETRICSW
Contains the scalable metrics associated with the nonclient
area of a nonminimized window.
PAINTSTRUCT
The PAINTSTRUCT structure contains information for an
application. This information can be used to paint the client
area of a window owned by that application.
POINTER_DEVICE_CURSOR_INFO
Contains cursor ID mappings for pointer devices.
POINTER_DEVICE_INFO
Contains information about a pointer device. An array of these
structures is returned from the GetPointerDevices function. A
single structure is returned from a call to the GetPointerDevice
function.
POINTER_DEVICE_PROPERTY
Contains pointer-based device properties (Human Interface
Device (HID) global items that correspond to HID usages).
POINTER_INFO
Contains basic pointer information common to all pointer
types. Applications can retrieve this information using the
GetPointerInfo, GetPointerFrameInfo, GetPointerInfoHistory
and GetPointerFrameInfoHistory functions.
POINTER_PEN_INFO
Defines basic pen information common to all pointer types.
POINTER_TOUCH_INFO
Defines basic touch information common to all pointer types.
T IT L E
DESC RIP T IO N
POINTER_TYPE_INFO
Contains information about the pointer input type.
POWERBROADCAST_SETTING
Sent with a power setting event and contains data about the
specific change.
RAWHID
Describes the format of the raw input from a Human Interface
Device (HID).
RAWINPUT
Contains the raw input from a device.
RAWINPUTDEVICE
Defines information for the raw input devices.
RAWINPUTDEVICELIST
Contains information about a raw input device.
RAWINPUTHEADER
Contains the header information that is part of the raw input
data.
RAWKEYBOARD
Contains information about the state of the keyboard.
RAWMOUSE
Contains information about the state of the mouse.
RID_DEVICE_INFO
Defines the raw input data coming from any device.
RID_DEVICE_INFO_HID
Defines the raw input data coming from the specified Human
Interface Device (HID).
RID_DEVICE_INFO_KEYBOARD
Defines the raw input data coming from the specified
keyboard.
RID_DEVICE_INFO_MOUSE
Defines the raw input data coming from the specified mouse.
SCROLLBARINFO
The SCROLLBARINFO structure contains scroll bar information.
SCROLLINFO
The SCROLLINFO structure contains scroll bar parameters to
be set by the SetScrollInfo function (or SBM_SETSCROLLINFO
message), or retrieved by the GetScrollInfo function (or
SBM_GETSCROLLINFO message).
SERIALKEYSA
Contains information about the SerialKeys accessibility feature,
which interprets data from a communication aid attached to a
serial port as commands causing the system to simulate
keyboard and mouse input.
SERIALKEYSW
Contains information about the SerialKeys accessibility feature,
which interprets data from a communication aid attached to a
serial port as commands causing the system to simulate
keyboard and mouse input.
SOUNDSENTRYA
Contains information about the SoundSentry accessibility
feature. When the SoundSentry feature is on, the computer
displays a visual indication only when a sound is generated.
T IT L E
DESC RIP T IO N
SOUNDSENTRYW
Contains information about the SoundSentry accessibility
feature. When the SoundSentry feature is on, the computer
displays a visual indication only when a sound is generated.
STICKYKEYS
Contains information about the StickyKeys accessibility feature.
STYLESTRUCT
Contains the styles for a window.
TITLEBARINFO
Contains title bar information.
TITLEBARINFOEX
Expands on the information described in the TITLEBARINFO
structure by including the coordinates of each element of the
title bar.
TOGGLEKEYS
Contains information about the ToggleKeys accessibility
feature.
TOUCH_HIT_TESTING_INPUT
Contains information about the touch contact area reported
by the touch digitizer.
TOUCH_HIT_TESTING_PROXIMITY_EVALUATION
Contains the hit test score that indicates whether the object is
the likely target of the touch contact area, relative to other
objects that intersect the touch contact area.
TOUCHINPUT
Encapsulates data for touch input.
TOUCHPREDICTIONPARAMETERS
Contains hardware input details that can be used to predict
touch targets and help compensate for hardware latency when
processing touch and gesture input that contains distance and
velocity data.
TPMPARAMS
Contains extended parameters for the TrackPopupMenuEx
function.
TRACKMOUSEEVENT
Used by the TrackMouseEvent function to track when the
mouse pointer leaves a window or hovers over a window for a
specified amount of time.
UPDATELAYEREDWINDOWINFO
Used by UpdateLayeredWindowIndirect to provide position,
size, shape, content, and translucency information for a
layered window.
USAGE_PROPERTIES
Contains device properties (Human Interface Device (HID)
global items that correspond to HID usages) for any type of
HID input device.
USEROBJECTFLAGS
Contains information about a window station or desktop
handle.
WINDOWINFO
Contains window information.
WINDOWPLACEMENT
Contains information about the placement of a window on the
screen.
T IT L E
DESC RIP T IO N
WINDOWPOS
Contains information about the size and position of a window.
WNDCLASSA
Contains the window class attributes that are registered by
the RegisterClass function.
WNDCLASSEXA
Contains window class information.
WNDCLASSEXW
Contains window class information.
WNDCLASSW
Contains the window class attributes that are registered by
the RegisterClass function.
WTSSESSION_NOTIFICATION
Provides information about the session change notification. A
service receives this structure in its HandlerEx function in
response to a session change event.
Enumerations
T IT L E
DESC RIP T IO N
AR_STATE
Indicates the state of screen auto-rotation for the system. For
example, whether auto-rotation is supported, and whether it
is enabled by the user.
DIALOG_CONTROL_DPI_CHANGE_BEHAVIORS
Describes per-monitor DPI scaling behavior overrides for child
windows within dialogs. The values in this enumeration are
bitfields and can be combined.
DIALOG_DPI_CHANGE_BEHAVIORS
In Per Monitor v2 contexts, dialogs will automatically respond
to DPI changes by resizing themselves and re-computing the
positions of their child windows (here referred to as relayouting).
FEEDBACK_TYPE
Specifies the visual feedback associated with an event.
INPUT_MESSAGE_DEVICE_TYPE
The type of device that sent the input message.
INPUT_MESSAGE_ORIGIN_ID
The ID of the input message source.
ORIENTATION_PREFERENCE
Indicates the screen orientation preference for a desktop app
process.
POINTER_BUTTON_CHANGE_TYPE
Identifies a change in the state of a button associated with a
pointer.
POINTER_DEVICE_CURSOR_TYPE
Identifies the pointer device cursor types.
POINTER_DEVICE_TYPE
Identifies the pointer device types.
POINTER_FEEDBACK_MODE
Identifies the visual feedback behaviors available to
CreateSyntheticPointerDevice.
T IT L E
DESC RIP T IO N
tagPOINTER_INPUT_TYPE
Identifies the pointer input types.
minutes to read • Edit Online
Defines an accelerator key used in an accelerator table.
Syntax
typedef struct tagACCEL {
#if ...
BYTE fVirt;
#if ...
WORD key;
#if ...
WORD cmd;
#else
WORD fVirt;
#endif
#else
WORD key;
#endif
#else
DWORD cmd;
#endif
} ACCEL, *LPACCEL;
Members
fVirt
Type: BYTE
The accelerator behavior. This member can be one or more of the following values.
VA L UE
FAL
T
0x1
0
FC
ON
TR
OL
0x0
8
M EA N IN G
The ALT key must be held down when the accelerator key is
pressed.
The CTRL key must be held down when the accelerator key is
pressed.
FN
OIN
VER
T
0x0
2
FSH
IFT
0x0
4
FVI
RTK
EY
TRU
E
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. This
attribute is obsolete and retained only for backward
compatibility with resource files designed for 16-bit Windows.
The SHIFT key must be held down when the accelerator key is
pressed.
The key member specifies a virtual-key code. If this flag is not
specified, key is assumed to specify a character code.
key
Type: WORD
The accelerator key. This member can be either a virtual-key code or a character code.
cmd
Type: WORD
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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
Keyboard Accelerators
Reference
WM_COMMAND
WM_SYSCOMMAND
minutes to read • Edit Online
Appends a new item to the end of the specified menu bar, drop-down menu, submenu, or shortcut menu. You can
use this function to specify the content, appearance, and behavior of the menu item.
Syntax
BOOL AppendMenuA(
HMENU
hMenu,
UINT
uFlags,
UINT_PTR uIDNewItem,
LPCSTR lpNewItem
);
Parameters
hMenu
Type: HMENU
A handle to the menu bar, drop-down menu, submenu, or shortcut menu to be changed.
uFlags
Type: UINT
Controls the appearance and behavior of the new menu item. This parameter can be a combination of the following
values.
VA L UE
MF
_BI
TM
AP
0x0
000
000
4L
MF
_CH
ECK
ED
0x0
000
000
8L
M EA N IN G
Uses a bitmap as the menu item. The lpNewItem parameter
contains a handle to the bitmap.
Places a check mark next to the menu item. If the application
provides check-mark bitmaps (see SetMenuItemBitmaps, this
flag displays the check-mark bitmap next to the menu item.
MF
_DI
SAB
LED
0x0
000
000
2L
MF
_EN
ABL
ED
0x0
000
000
0L
MF
_GR
AYE
D
0x0
000
000
1L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
Disables the menu item so that it cannot be selected, but the
flag does not gray it.
Enables the menu item so that it can be selected, and restores
it from its grayed state.
Disables the menu item and grays it so that it cannot be
selected.
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.
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.
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
MF
_PO
PU
P
0x0
000
001
0L
MF
_SE
PAR
ATO
R
0x0
000
080
0L
MF
_ST
RIN
G
0x0
000
000
0L
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
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.
Specifies that the menu item opens a drop-down menu or
submenu. The uIDNewItem parameter specifies a 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.
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.
Specifies that the menu item is a text string; the lpNewItem
parameter is a pointer to the string.
Does not place a check mark next to the item (default). If the
application supplies check-mark bitmaps (see
SetMenuItemBitmaps), this flag displays the clear bitmap next
to the menu item.
uIDNewItem
Type: UINT_PTR
The identifier of the new menu item or, if the uFlags parameter is set to MF_POPUP , a handle to the drop-down
menu or submenu.
lpNewItem
Type: LPCTSTR
The content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter
includes the following values.
VA L UE
M EA N IN G
Contains a bitmap handle.
MF
_BI
TM
AP
0x0
000
000
4L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Contains an application-supplied value 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 is created or
its appearance is updated.
Contains a pointer to a null-terminated string.
MF
_ST
RIN
G
0x0
000
000
0L
Return value
Type: BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended
error information, call GetLastError.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether 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. For more information, see Owner-Drawn Menus and the WM_MENUCHAR
Message.
The following groups of flags cannot be used together:
MF_BITMAP , MF_STRING , and MF_OWNERDRAW
MF_CHECKED and MF_UNCHECKED
MF_DISABLED , MF_ENABLED , and MF_GRAYED
MF_MENUBARBREAK and MF_MENUBREAK
Examples
For an example, see Adding Lines and Graphs to a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateMenu
DeleteMenu
DestroyMenu
DrawMenuBar
InsertMenu
InsertMenuItem
Menus
ModifyMenu
Reference
RemoveMenu
SetMenuItemBitmaps
minutes to read • Edit Online
Appends a new item to the end of the specified menu bar, drop-down menu, submenu, or shortcut menu. You can
use this function to specify the content, appearance, and behavior of the menu item.
Syntax
BOOL AppendMenuW(
HMENU
hMenu,
UINT
uFlags,
UINT_PTR uIDNewItem,
LPCWSTR lpNewItem
);
Parameters
hMenu
Type: HMENU
A handle to the menu bar, drop-down menu, submenu, or shortcut menu to be changed.
uFlags
Type: UINT
Controls the appearance and behavior of the new menu item. This parameter can be a combination of the following
values.
VA L UE
MF
_BI
TM
AP
0x0
000
000
4L
MF
_CH
ECK
ED
0x0
000
000
8L
M EA N IN G
Uses a bitmap as the menu item. The lpNewItem parameter
contains a handle to the bitmap.
Places a check mark next to the menu item. If the application
provides check-mark bitmaps (see SetMenuItemBitmaps, this
flag displays the check-mark bitmap next to the menu item.
MF
_DI
SAB
LED
0x0
000
000
2L
MF
_EN
ABL
ED
0x0
000
000
0L
MF
_GR
AYE
D
0x0
000
000
1L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
Disables the menu item so that it cannot be selected, but the
flag does not gray it.
Enables the menu item so that it can be selected, and restores
it from its grayed state.
Disables the menu item and grays it so that it cannot be
selected.
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.
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.
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
MF
_PO
PU
P
0x0
000
001
0L
MF
_SE
PAR
ATO
R
0x0
000
080
0L
MF
_ST
RIN
G
0x0
000
000
0L
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
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.
Specifies that the menu item opens a drop-down menu or
submenu. The uIDNewItem parameter specifies a 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.
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.
Specifies that the menu item is a text string; the lpNewItem
parameter is a pointer to the string.
Does not place a check mark next to the item (default). If the
application supplies check-mark bitmaps (see
SetMenuItemBitmaps), this flag displays the clear bitmap next
to the menu item.
uIDNewItem
Type: UINT_PTR
The identifier of the new menu item or, if the uFlags parameter is set to MF_POPUP , a handle to the drop-down
menu or submenu.
lpNewItem
Type: LPCTSTR
The content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter
includes the following values.
VA L UE
M EA N IN G
Contains a bitmap handle.
MF
_BI
TM
AP
0x0
000
000
4L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Contains an application-supplied value 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 is created or
its appearance is updated.
Contains a pointer to a null-terminated string.
MF
_ST
RIN
G
0x0
000
000
0L
Return value
Type: BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended
error information, call GetLastError.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether 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. For more information, see Owner-Drawn Menus and the WM_MENUCHAR
Message.
The following groups of flags cannot be used together:
MF_BITMAP , MF_STRING , and MF_OWNERDRAW
MF_CHECKED and MF_UNCHECKED
MF_DISABLED , MF_ENABLED , and MF_GRAYED
MF_MENUBARBREAK and MF_MENUBREAK
Examples
For an example, see Adding Lines and Graphs to a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateMenu
DeleteMenu
DestroyMenu
DrawMenuBar
InsertMenu
InsertMenuItem
Menus
ModifyMenu
Reference
RemoveMenu
SetMenuItemBitmaps
minutes to read • Edit Online
Converts a character string or a single character to lowercase. If the operand is a character string, the function
converts the characters in place.
Syntax
LPSTR CharLowerA(
LPSTR lpsz
);
Parameters
lpsz
Type: LPTSTR
A null-terminated string, or specifies a single character. If the high-order word of this parameter is zero, the loworder word must contain a single character to be converted.
Return value
Type: LPTSTR
If the operand is a character string, the function returns a pointer to the converted string. Because the string is
converted in place, the return value is equal to lpsz.
If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order
word contains the converted 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
Note that CharLower always maps uppercase I to lowercase I ("i"), even when the current language is Turkish or
Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapString.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLowerBuff
CharUpper
CharUpperBuff
Conceptual
Reference
Strings
minutes to read • Edit Online
Converts uppercase characters in a buffer to lowercase characters. The function converts the characters in place.
Syntax
DWORD CharLowerBuffA(
LPSTR lpsz,
DWORD cchLength
);
Parameters
lpsz
Type: LPTSTR
A buffer containing one or more characters to be processed.
cchLength
Type: DWORD
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 characters indicated by
cchLength, even if one or more characters are null characters.
Return value
Type: DWORD
The return value is the number of characters processed. For example, if CharLowerBuff ("Acme of Operating
Systems", 10) succeeds, the return value is 10.
Remarks
Note that CharLowerBuff always maps uppercase I to lowercase I ("i"), even when the current language is Turkish
or Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapSting.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Examples
For an example, see "Creating a Spell Dialog Box" in Using Combo Boxes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLower
CharUpper
CharUpperBuff
Conceptual
Reference
Strings
minutes to read • Edit Online
Converts uppercase characters in a buffer to lowercase characters. The function converts the characters in place.
Syntax
DWORD CharLowerBuffW(
LPWSTR lpsz,
DWORD cchLength
);
Parameters
lpsz
Type: LPTSTR
A buffer containing one or more characters to be processed.
cchLength
Type: DWORD
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 characters indicated by
cchLength, even if one or more characters are null characters.
Return value
Type: DWORD
The return value is the number of characters processed. For example, if CharLowerBuff ("Acme of Operating
Systems", 10) succeeds, the return value is 10.
Remarks
Note that CharLowerBuff always maps uppercase I to lowercase I ("i"), even when the current language is Turkish
or Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapSting.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Examples
For an example, see "Creating a Spell Dialog Box" in Using Combo Boxes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLower
CharUpper
CharUpperBuff
Conceptual
Reference
Strings
minutes to read • Edit Online
Converts a character string or a single character to lowercase. If the operand is a character string, the function
converts the characters in place.
Syntax
LPWSTR CharLowerW(
LPWSTR lpsz
);
Parameters
lpsz
Type: LPTSTR
A null-terminated string, or specifies a single character. If the high-order word of this parameter is zero, the loworder word must contain a single character to be converted.
Return value
Type: LPTSTR
If the operand is a character string, the function returns a pointer to the converted string. Because the string is
converted in place, the return value is equal to lpsz.
If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order
word contains the converted 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
Note that CharLower always maps uppercase I to lowercase I ("i"), even when the current language is Turkish or
Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapString.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLowerBuff
CharUpper
CharUpperBuff
Conceptual
Reference
Strings
minutes to read • Edit Online
Retrieves a pointer to the next character in a string. This function can handle strings consisting of either single- or
multi-byte characters.
Syntax
LPSTR CharNextA(
LPCSTR lpsz
);
Parameters
lpsz
Type: LPCTSTR
A character in a null-terminated string.
Return value
Type: LPTSTR
The return value is a pointer to the next character in the string, or to the terminating null character if at the end of
the string.
If lpsz points to the terminating null character, the return value is equal to lpsz.
Remarks
When called as an ANSI function, CharNext uses the system default code-page, whereas CharNextExA specifies a
code-page to use.
This function works with default "user" expectations of characters when dealing with diacritics. For example: A
string that contains U+0061 U+030a "LATIN SMALL LETTER A" + COMBINING RING ABOVE" — which looks like
"å", will advance two code points, not one. A string that contains U+0061 U+0301 U+0302 U+0303 U+0304 —
which looks like "a´^~¯", will advance five code points, not one, and so on.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharNextExA
CharPrev
Conceptual
Reference
Strings
minutes to read • Edit Online
Retrieves the pointer to the next character in a string. This function can handle strings consisting of either single- or
multi-byte characters.
Syntax
LPSTR CharNextExA(
WORD CodePage,
LPCSTR lpCurrentChar,
DWORD dwFlags
);
Parameters
CodePage
Type: WORD
The identifier of the code page to use to check lead-byte ranges. Can be one of the code-page values provided in
Code Page Identifiers, or one of the following predefined values.
VA L UE
M EA N IN G
Use system default ANSI code page.
CP_
AC
P
0
Use the system default Macintosh code page.
CP_
MA
CCP
2
Use system default OEM code page.
CP_
OE
MC
P
1
lpCurrentChar
Type: LPCSTR
A character in a null-terminated string.
dwFlags
Type: DWORD
This parameter is reserved and must be 0.
Return value
Type: LPSTR
The return value is a pointer to the next character in the string, or to the terminating null character if at the end of
the string.
If lpCurrentChar points to the terminating null character, the return value is equal to lpCurrentChar.
Remarks
CharNextExA specifies a code-page to use, whereas CharNext (if called as an ANSI function) uses the system
default code-page.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharNext
CharPrevExA
Conceptual
Reference
Strings
minutes to read • Edit Online
Retrieves a pointer to the next character in a string. This function can handle strings consisting of either single- or
multi-byte characters.
Syntax
LPWSTR CharNextW(
LPCWSTR lpsz
);
Parameters
lpsz
Type: LPCTSTR
A character in a null-terminated string.
Return value
Type: LPTSTR
The return value is a pointer to the next character in the string, or to the terminating null character if at the end of
the string.
If lpsz points to the terminating null character, the return value is equal to lpsz.
Remarks
When called as an ANSI function, CharNext uses the system default code-page, whereas CharNextExA specifies a
code-page to use.
This function works with default "user" expectations of characters when dealing with diacritics. For example: A
string that contains U+0061 U+030a "LATIN SMALL LETTER A" + COMBINING RING ABOVE" — which looks like
"å", will advance two code points, not one. A string that contains U+0061 U+0301 U+0302 U+0303 U+0304 —
which looks like "a´^~¯", will advance five code points, not one, and so on.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharNextExA
CharPrev
Conceptual
Reference
Strings
minutes to read • Edit Online
Retrieves a pointer to the preceding character in a string. This function can handle strings consisting of either
single- or multi-byte characters.
Syntax
LPSTR CharPrevA(
LPCSTR lpszStart,
LPCSTR lpszCurrent
);
Parameters
lpszStart
Type: LPCTSTR
The beginning of the string.
lpszCurrent
Type: LPCTSTR
A character in a null-terminated string.
Return value
Type: LPTSTR
The return value is 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.
Remarks
When called as an ANSI function, CharPrev uses the system default code-page, whereas CharPrevExA specifies a
code-page to use.
This function works with default "user" expectations of characters when dealing with diacritics. For example: A
string that contains U+0061 U+030a "LATIN SMALL LETTER A" + COMBINING RING ABOVE" — which looks like
"å", will advance two code points, not one. A string that contains U+0061 U+0301 U+0302 U+0303 U+0304 —
which looks like "a´^~¯", will advance five code points, not one, and so on.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharNext
CharNextExA
CharPrevExA
Conceptual
Reference
Strings
minutes to read • Edit Online
Retrieves the pointer to the preceding character in a string. This function can handle strings consisting of either
single- or multi-byte characters.
Syntax
LPSTR CharPrevExA(
WORD CodePage,
LPCSTR lpStart,
LPCSTR lpCurrentChar,
DWORD dwFlags
);
Parameters
CodePage
Type: WORD
The identifier of the code page to use to check lead-byte ranges. Can be one of the code-page values provided in
Code Page Identifiers, or one of the following predefined values.
VA L UE
M EA N IN G
Use system default ANSI code page.
CP_
AC
P
0
Use the system default Macintosh code page.
CP_
MA
CCP
2
Use system default OEM code page.
CP_
OE
MC
P
1
lpStart
Type: LPCSTR
The beginning of the string.
lpCurrentChar
Type: LPCSTR
A character in a null-terminated string.
dwFlags
Type: DWORD
This parameter is reserved and must be zero.
Return value
Type: LPSTR
The return value is a pointer to the preceding character in the string, or to the first character in the string if the
lpCurrentChar parameter equals the lpStart parameter.
Remarks
CharPrevExA specifies a code-page to use, whereas CharPrev (if called as an ANSI function) uses the system
default code-page.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharNextExA
CharPrev
Conceptual
Reference
Strings
minutes to read • Edit Online
Retrieves a pointer to the preceding character in a string. This function can handle strings consisting of either
single- or multi-byte characters.
Syntax
LPWSTR CharPrevW(
LPCWSTR lpszStart,
LPCWSTR lpszCurrent
);
Parameters
lpszStart
Type: LPCTSTR
The beginning of the string.
lpszCurrent
Type: LPCTSTR
A character in a null-terminated string.
Return value
Type: LPTSTR
The return value is 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.
Remarks
When called as an ANSI function, CharPrev uses the system default code-page, whereas CharPrevExA specifies a
code-page to use.
This function works with default "user" expectations of characters when dealing with diacritics. For example: A
string that contains U+0061 U+030a "LATIN SMALL LETTER A" + COMBINING RING ABOVE" — which looks like
"å", will advance two code points, not one. A string that contains U+0061 U+0301 U+0302 U+0303 U+0304 —
which looks like "a´^~¯", will advance five code points, not one, and so on.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharNext
CharNextExA
CharPrevExA
Conceptual
Reference
Strings
minutes to read • Edit Online
Translates a string into the OEM-defined character set.
Warning Do not use. See Security Considerations.
Syntax
BOOL CharToOemA(
LPCSTR pSrc,
LPSTR pDst
);
Parameters
pSrc
Type: LPCTSTR
The null-terminated string to be translated.
pDst
Type: LPSTR
The destination buffer, which receives the translated string. If the CharToOem function is being used as an ANSI
function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc
parameter. This cannot be done if CharToOem is being used as a wide-character function.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOemBuff
Conceptual
OemToChar
OemToCharBuff
Reference
Strings
minutes to read • Edit Online
Translates a specified number of characters in a string into the OEM-defined character set.
Syntax
BOOL CharToOemBuffA(
LPCSTR lpszSrc,
LPSTR lpszDst,
DWORD cchDstLength
);
Parameters
lpszSrc
Type: LPCTSTR
The null-terminated string to be translated.
lpszDst
Type: LPSTR
The buffer for the translated string. If the CharToOemBuff function is being used as an ANSI function, the string
can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This
cannot be done if CharToOemBuff is being used as a wide-character function.
cchDstLength
Type: DWORD
The number of characters to translate in the string identified by the lpszSrc parameter.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Remarks
Unlike the CharToOem function, the CharToOemBuff function does not stop converting characters when it
encounters a null character in the buffer pointed to by lpszSrc. The CharToOemBuff function converts all
cchDstLength characters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOem
Conceptual
OemToChar
OemToCharBuff
Reference
Strings
minutes to read • Edit Online
Translates a specified number of characters in a string into the OEM-defined character set.
Syntax
BOOL CharToOemBuffW(
LPCWSTR lpszSrc,
LPSTR lpszDst,
DWORD cchDstLength
);
Parameters
lpszSrc
Type: LPCTSTR
The null-terminated string to be translated.
lpszDst
Type: LPSTR
The buffer for the translated string. If the CharToOemBuff function is being used as an ANSI function, the string
can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This
cannot be done if CharToOemBuff is being used as a wide-character function.
cchDstLength
Type: DWORD
The number of characters to translate in the string identified by the lpszSrc parameter.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Remarks
Unlike the CharToOem function, the CharToOemBuff function does not stop converting characters when it
encounters a null character in the buffer pointed to by lpszSrc. The CharToOemBuff function converts all
cchDstLength characters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOem
Conceptual
OemToChar
OemToCharBuff
Reference
Strings
minutes to read • Edit Online
Translates a string into the OEM-defined character set.
Warning Do not use. See Security Considerations.
Syntax
BOOL CharToOemW(
LPCWSTR pSrc,
LPSTR pDst
);
Parameters
pSrc
Type: LPCTSTR
The null-terminated string to be translated.
pDst
Type: LPSTR
The destination buffer, which receives the translated string. If the CharToOem function is being used as an ANSI
function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc
parameter. This cannot be done if CharToOem is being used as a wide-character function.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOemBuff
Conceptual
OemToChar
OemToCharBuff
Reference
Strings
minutes to read • Edit Online
Converts a character string or a single character to uppercase. If the operand is a character string, the function
converts the characters in place.
Syntax
LPSTR CharUpperA(
LPSTR lpsz
);
Parameters
lpsz
Type: LPTSTR
A null-terminated string, or 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 value
Type: LPTSTR
If the operand is a character string, the function returns a pointer to the converted string. Because the string is
converted in place, the return value is equal to lpsz.
If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order
word contains the converted 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
Note that CharUpper always maps lowercase I ("i") to uppercase I, even when the current language is Turkish or
Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapString.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLower
CharLowerBuff
CharUpperBuff
Conceptual
Reference
Strings
minutes to read • Edit Online
Converts lowercase characters in a buffer to uppercase characters. The function converts the characters in place.
Syntax
DWORD CharUpperBuffA(
LPSTR lpsz,
DWORD cchLength
);
Parameters
lpsz
Type: LPTSTR
A buffer containing one or more characters to be processed.
cchLength
Type: DWORD
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 value
Type: DWORD
The return value is the number of characters processed.
For example, if CharUpperBuff ("Zenith of API Sets", 10) succeeds, the return value is 10.
Remarks
Note that CharUpperBuff always maps lowercase I ("i") to uppercase I, even when the current language is Turkish
or Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapString.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Examples
For an example, see Creating and Using a Temporary File.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLower
CharLowerBuff
CharUpper
Conceptual
Reference
Strings
minutes to read • Edit Online
Converts lowercase characters in a buffer to uppercase characters. The function converts the characters in place.
Syntax
DWORD CharUpperBuffW(
LPWSTR lpsz,
DWORD cchLength
);
Parameters
lpsz
Type: LPTSTR
A buffer containing one or more characters to be processed.
cchLength
Type: DWORD
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 value
Type: DWORD
The return value is the number of characters processed.
For example, if CharUpperBuff ("Zenith of API Sets", 10) succeeds, the return value is 10.
Remarks
Note that CharUpperBuff always maps lowercase I ("i") to uppercase I, even when the current language is Turkish
or Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapString.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Examples
For an example, see Creating and Using a Temporary File.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLower
CharLowerBuff
CharUpper
Conceptual
Reference
Strings
minutes to read • Edit Online
Converts a character string or a single character to uppercase. If the operand is a character string, the function
converts the characters in place.
Syntax
LPWSTR CharUpperW(
LPWSTR lpsz
);
Parameters
lpsz
Type: LPTSTR
A null-terminated string, or 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 value
Type: LPTSTR
If the operand is a character string, the function returns a pointer to the converted string. Because the string is
converted in place, the return value is equal to lpsz.
If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order
word contains the converted 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
Note that CharUpper always maps lowercase I ("i") to uppercase I, even when the current language is Turkish or
Azerbaijani. If you need a function that is linguistically sensitive in this respect, call LCMapString.
Conversion to Unicode in the ANSI version of the function is done with the system default locale in all cases.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharLower
CharLowerBuff
CharUpperBuff
Conceptual
Reference
Strings
minutes to read • Edit Online
[CheckMenuItem is available for use in the operating systems specified in the Requirements section. It may be
altered or unavailable in subsequent versions. Instead, use SetMenuItemInfo. ]
Sets the state of the specified menu item's check-mark attribute to either selected or clear.
Syntax
DWORD CheckMenuItem(
HMENU hMenu,
UINT uIDCheckItem,
UINT uCheck
);
Parameters
hMenu
Type: HMENU
A handle to the menu of interest.
uIDCheckItem
Type: UINT
The menu item whose check-mark attribute is to be set, as determined by the uCheck parameter.
uCheck
Type: UINT
The flags that control the interpretation of the uIDCheckItem parameter and the state of the menu item's checkmark attribute. This parameter can be a combination of either MF_BYCOMMAND , or MF_BYPOSITION and
MF_CHECKED or MF_UNCHECKED .
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
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
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that the uIDCheckItem parameter gives the zerobased relative position of the menu item.
Sets the check-mark attribute to the selected state.
MF
_CH
ECK
ED
0x0
000
000
8L
Sets the check-mark attribute to the clear state.
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
Return value
Type: DWORD
The return value specifies the previous state of the menu item (either MF_CHECKED or MF_UNCHECKED ). If the
menu item does not exist, the return value is –1.
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.
Examples
For an example, see Simulating Check Boxes in a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
EnableMenuItem
GetMenuItemID
Menus
Reference
SetMenuItemBitmaps
SetMenuItemInfo
minutes to read • Edit Online
Checks a specified menu item and makes it a radio item. At the same time, the function clears all other menu items
in the associated group and clears the radio-item type flag for those items.
Syntax
BOOL CheckMenuRadioItem(
HMENU hmenu,
UINT first,
UINT last,
UINT check,
UINT flags
);
Parameters
hmenu
Type: HMENU
A handle to the menu that contains the group of menu items.
first
Type: UINT
The identifier or position of the first menu item in the group.
last
Type: UINT
The identifier or position of the last menu item in the group.
check
Type: UINT
The identifier or position of the menu item to check.
flags
Type: UINT
Indicates 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 value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
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 selected 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.
Examples
For an example, see Example of Example of Using Custom Checkmark Bitmaps.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
MENUITEMINFO
Menus
Reference
minutes to read • Edit Online
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, the system automatically adjusts the position to keep the cursor
inside the rectangular area.
Syntax
BOOL ClipCursor(
const RECT *lpRect
);
Parameters
lpRect
Type: const RECT *
A pointer to the 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 value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
Examples
For an example, see Confining a Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
GetClipCursor
GetCursorPos
Other Resources
RECT
Reference
SetCursorPos
minutes to read • Edit Online
Copies the specified accelerator table. This function is used to obtain the accelerator-table data that corresponds to
an accelerator-table handle, or to determine the size of the accelerator-table data.
Syntax
int CopyAcceleratorTableA(
HACCEL hAccelSrc,
LPACCEL lpAccelDst,
int
cAccelEntries
);
Parameters
hAccelSrc
Type: HACCEL
A handle to the accelerator table to copy.
lpAccelDst
Type: LPACCEL
An array of ACCEL structures that receives the accelerator-table information.
cAccelEntries
Type: int
The number of ACCEL structures to copy to the buffer pointed to by the lpAccelDst parameter.
Return value
Type: int
If lpAccelDst is NULL , the return value specifies the number of accelerator-table entries in the original table.
Otherwise, it specifies the number of accelerator-table entries that were copied.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ACCEL
Conceptual
CreateAcceleratorTable
DestroyAcceleratorTable
Keyboard Accelerators
LoadAccelerators
Reference
TranslateAccelerator
minutes to read • Edit Online
Copies the specified accelerator table. This function is used to obtain the accelerator-table data that corresponds to
an accelerator-table handle, or to determine the size of the accelerator-table data.
Syntax
int CopyAcceleratorTableW(
HACCEL hAccelSrc,
LPACCEL lpAccelDst,
int
cAccelEntries
);
Parameters
hAccelSrc
Type: HACCEL
A handle to the accelerator table to copy.
lpAccelDst
Type: LPACCEL
An array of ACCEL structures that receives the accelerator-table information.
cAccelEntries
Type: int
The number of ACCEL structures to copy to the buffer pointed to by the lpAccelDst parameter.
Return value
Type: int
If lpAccelDst is NULL , the return value specifies the number of accelerator-table entries in the original table.
Otherwise, it specifies the number of accelerator-table entries that were copied.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ACCEL
Conceptual
CreateAcceleratorTable
DestroyAcceleratorTable
Keyboard Accelerators
LoadAccelerators
Reference
TranslateAccelerator
minutes to read • Edit Online
Copies the specified cursor.
Syntax
void CopyCursor(
pcur
);
Parameters
pcur
Type: HCURSOR
A handle to the cursor to be copied.
Return value
None
Remarks
CopyCursor enables an application or DLL to obtain the handle to a cursor shape owned by another module. Then
if the other module is freed, the application is still able to use the cursor shape.
Before closing, an application must call the DestroyCursor function to free any system resources associated with
the cursor.
Do not use the CopyCursor function for animated cursors. Instead, use the CopyImage function.
CopyCursor is implemented as a call to the CopyIcon function.
#define CopyCursor(pcur) ((HCURSOR)CopyIcon((HICON)(pcur)))
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
See also
Conceptual
CopyIcon
CopyImage
Cursors
DestroyCursor
GetCursor
Reference
SetCursor
ShowCursor
minutes to read • Edit Online
Copies the specified icon from another module to the current module.
Syntax
HICON CopyIcon(
HICON hIcon
);
Parameters
hIcon
Type: HICON
A handle to the icon to be copied.
Return value
Type: HICON
If the function succeeds, the return value is a handle to the duplicate icon.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
The CopyIcon function enables an application or DLL to get its own handle to an icon owned by another module. If
the other module is freed, the application icon will still be able to use the icon.
Before closing, an application must call the DestroyIcon function to free any system resources associated with the
icon.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyCursor
DestroyIcon
DrawIcon
DrawIconEx
Icons
Reference
minutes to read • Edit Online
Creates a new image (icon, cursor, or bitmap) and copies the attributes of the specified image to the new one. If
necessary, the function stretches the bits to fit the desired size of the new image.
Syntax
HANDLE CopyImage(
HANDLE h,
UINT type,
int
cx,
int
cy,
UINT flags
);
Parameters
h
Type: HANDLE
A handle to the image to be copied.
type
Type: UINT
The type of image to be copied. This parameter can be one of the following values.
VA L UE
M EA N IN G
Copies a bitmap.
IM
AG
E_B
ITM
AP
0
Copies a cursor.
IM
AG
E_C
URS
OR
2
Copies an icon.
IM
AG
E_I
CO
N
1
cx
Type: int
The desired width, in pixels, of the image. If this is zero, then the returned image will have the same width as the
original hImage.
cy
Type: int
The desired height, in pixels, of the image. If this is zero, then the returned image will have the same height as the
original hImage.
flags
Type: UINT
This parameter can be one or more of the following values.
VA L UE
M EA N IN G
Deletes the original image after creating the copy.
LR_
CO
PY
DEL
ETE
OR
G
0x0
000
000
8
LR_
CO
PYF
RO
MR
ESO
UR
CE
0x0
000
400
0
Tries to reload an icon or cursor resource from the original
resource file rather than simply copying the current image.
This is useful for creating a different-sized copy when the
resource file contains multiple sizes of the resource. Without
this flag, CopyImage stretches the original image to the new
size. If this flag is set, CopyImage uses the size in the
resource file closest to the desired size. This will succeed only if
hImage was loaded by LoadIcon or LoadCursor, or by
LoadImage with the LR_SHARED flag.
LR_
CO
PYR
ETU
RN
OR
G
0x0
000
000
4
LR_
CRE
ATE
DIB
SEC
TIO
N
0x0
000
200
0
LR_
DEF
AU
LTSI
ZE
0x0
000
004
0
Returns the original hImage if it satisfies the criteria for the
copy—that is, correct dimensions and color depth—in which
case the LR_COPYDELETEORG flag is ignored. If this flag is
not specified, a new object is always created.
If this is set and a new bitmap is created, the bitmap is created
as a DIB section. Otherwise, the bitmap image is created as a
device-dependent bitmap. This flag is only valid if uType is
IMAGE_BITMAP .
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 this flag is not specified and cxDesired and
cyDesired are set to zero, the function uses the actual resource
size. If the resource contains multiple images, the function
uses the size of the first image.
Creates a new monochrome image.
LR_
MO
NO
CH
RO
ME
0x0
000
000
1
Return value
Type: HANDLE
If the function succeeds, the return value is the handle to the newly created image.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
When you are finished using the resource, you can release its associated memory by calling one of the functions in
the following table.
RESO URC E
REL EA SE F UN C T IO N
Bitmap
DeleteObject
Cursor
DestroyCursor
Icon
DestroyIcon
The system automatically deletes the resource when its process terminates, however, calling the appropriate
function saves memory and decreases the size of the process's working set.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
LoadImage
Reference
Resources
minutes to read • Edit Online
Creates an accelerator table.
Syntax
HACCEL CreateAcceleratorTableA(
LPACCEL paccel,
int
cAccel
);
Parameters
paccel
Type: LPACCEL
An array of ACCEL structures that describes the accelerator table.
cAccel
Type: int
The number of ACCEL structures in the array. This must be within the range 1 to 32767 or the function will fail.
Return value
Type: HACCEL
If the function succeeds, the return value is the handle to the created accelerator table; otherwise, it is NULL . To get
extended error information, call GetLastError.
Remarks
Before an application closes, it can use the DestroyAcceleratorTable function to destroy any accelerator tables that it
created by using the CreateAcceleratorTable function.
Examples
For an example, see Creating User Editable Accelerators.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ACCEL
Conceptual
CopyAcceleratorTable
DestroyAcceleratorTable
Keyboard Accelerators
LoadAccelerators
Reference
TranslateAccelerator
minutes to read • Edit Online
Creates an accelerator table.
Syntax
HACCEL CreateAcceleratorTableW(
LPACCEL paccel,
int
cAccel
);
Parameters
paccel
Type: LPACCEL
An array of ACCEL structures that describes the accelerator table.
cAccel
Type: int
The number of ACCEL structures in the array. This must be within the range 1 to 32767 or the function will fail.
Return value
Type: HACCEL
If the function succeeds, the return value is the handle to the created accelerator table; otherwise, it is NULL . To get
extended error information, call GetLastError.
Remarks
Before an application closes, it can use the DestroyAcceleratorTable function to destroy any accelerator tables that it
created by using the CreateAcceleratorTable function.
Examples
For an example, see Creating User Editable Accelerators.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ACCEL
Conceptual
CopyAcceleratorTable
DestroyAcceleratorTable
Keyboard Accelerators
LoadAccelerators
Reference
TranslateAccelerator
minutes to read • Edit Online
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, a block, or a bitmap.
Syntax
BOOL CreateCaret(
HWND
hWnd,
HBITMAP hBitmap,
int
nWidth,
int
nHeight
);
Parameters
hWnd
Type: HWND
A handle to the window that owns the caret.
hBitmap
Type: HBITMAP
A handle to the bitmap that defines the caret shape. If this parameter is NULL , the caret is solid. If this parameter is
(HBITMAP) 1 , the caret is gray. If this parameter is a bitmap handle, the caret is the specified bitmap. The bitmap
handle must have been created by the CreateBitmap, CreateDIBitmap, or LoadBitmap function.
If hBitmap is a bitmap handle, CreateCaret ignores the nWidth and nHeight parameters; the bitmap defines its
own width and height.
nWidth
Type: int
The width of the caret, in logical units. If this parameter is zero, the width is set to the system-defined window
border width. If hBitmap is a bitmap handle, CreateCaret ignores this parameter.
nHeight
Type: int
The height of the caret, in logical units. If this parameter is zero, the height is set to the system-defined window
border height. If hBitmap is a bitmap handle, CreateCaret ignores this parameter.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
DPI Virtualization
This API does not participate in DPI virtualization. The width and height parameters are interpreted as logical sizes in
terms of the window in question. The calling thread is not taken into consideration.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
CreateBitmap
CreateDIBitmap
DestroyCaret
GetSystemMetrics
HideCaret
LoadBitmap
Other Resources
Reference
ShowCaret
minutes to read • Edit Online
Creates a cursor having the specified size, bit patterns, and hot spot.
Syntax
HCURSOR CreateCursor(
HINSTANCE hInst,
int
xHotSpot,
int
yHotSpot,
int
nWidth,
int
nHeight,
const VOID *pvANDPlane,
const VOID *pvXORPlane
);
Parameters
hInst
Type: HINSTANCE
A handle to the current instance of the application creating the cursor.
xHotSpot
Type: int
The horizontal position of the cursor's hot spot.
yHotSpot
Type: int
The vertical position of the cursor's hot spot.
nWidth
Type: int
The width of the cursor, in pixels.
nHeight
Type: int
The height of the cursor, in pixels.
pvANDPlane
Type: const VOID*
An array of bytes that contains the bit values for the AND mask of the cursor, as in a device-dependent
monochrome bitmap.
pvXORPlane
Type: const VOID*
An array of bytes that contains the bit values for the XOR mask of the cursor, as in a device-dependent
monochrome bitmap.
Return value
Type: HCURSOR
If the function succeeds, the return value is a handle to the cursor.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
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.
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is in terms of physical coordinates, and is not
affected by the DPI of the calling thread. Note that the cursor created may still be scaled to match the DPI of any given
window it is drawn into.
Examples
For an example, see Creating a Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
Cursors
DestroyCursor
GetModuleHandle
GetSystemMetrics
Other Resources
Reference
SetCursor
minutes to read • Edit Online
Creates an icon that has the specified size, colors, and bit patterns.
Syntax
HICON CreateIcon(
HINSTANCE hInstance,
int
nWidth,
int
nHeight,
BYTE
cPlanes,
BYTE
cBitsPixel,
const BYTE *lpbANDbits,
const BYTE *lpbXORbits
);
Parameters
hInstance
Type: HINSTANCE
A handle to the instance of the module creating the icon.
nWidth
Type: int
The width, in pixels, of the icon.
nHeight
Type: int
The height, in pixels, of the icon.
cPlanes
Type: BYTE
The number of planes in the XOR bitmask of the icon.
cBitsPixel
Type: BYTE
The number of bits-per-pixel in the XOR bitmask of the icon.
lpbANDbits
Type: const BYTE*
An array of bytes that contains the bit values for the AND bitmask of the icon. This bitmask describes a
monochrome bitmap.
lpbXORbits
Type: const BYTE*
An array of bytes that contains the bit values for the XOR bitmask of the icon. This bitmask describes a
monochrome or device-dependent color bitmap.
Return value
Type: HICON
If the function succeeds, the return value is a handle to an icon.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
The nWidth and nHeight parameters must specify a width and height supported by the current display driver,
because the system cannot create icons of other sizes. To determine the width and height supported by the display
driver, use the GetSystemMetrics function, specifying the SM_CXICON or SM_CYICON value.
CreateIcon applies the following truth table to the AND and XOR bitmasks.
A N D B IT M A SK
XO R B IT M A SK
DISP L AY
0
0
Black
0
1
White
1
0
Screen
1
1
Reverse screen
When you are finished using the icon, destroy it using the DestroyIcon function.
Examples
For an example, see Creating an Icon.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetSystemMetrics
Icons
Other Resources
minutes to read • Edit Online
Creates an icon or cursor from resource bits describing the icon.
To specify a desired height or width, use the CreateIconFromResourceEx function.
Syntax
HICON CreateIconFromResource(
PBYTE presbits,
DWORD dwResSize,
BOOL fIcon,
DWORD dwVer
);
Parameters
presbits
Type: PBYTE
The buffer containing the icon or cursor resource bits. These bits are typically loaded by calls to the
LookupIconIdFromDirectory, LookupIconIdFromDirectoryEx, and LoadResource functions.
dwResSize
Type: DWORD
The size, in bytes, of the set of bits pointed to by the presbits parameter.
fIcon
Type: BOOL
Indicates whether an icon or a cursor is to be created. If this parameter is TRUE , an icon is to be created. If it is
FALSE , a cursor is to be created.
dwVer
Type: DWORD
The version number of the icon or cursor format for the resource bits pointed to by the presbits parameter. The
value must be greater than or equal to 0x00020000 and less than or equal to 0x00030000. This parameter is
generally set to 0x00030000.
Return value
Type: HICON
If the function succeeds, the return value is a handle to the icon or cursor.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
The CreateIconFromResource , CreateIconFromResourceEx, CreateIconIndirect, GetIconInfo,
LookupIconIdFromDirectory, and LookupIconIdFromDirectoryEx functions allow shell applications and icon
browsers to examine and use resources throughout the system.
The CreateIconFromResource function calls CreateIconFromResourceEx passing
flags.
LR_DEFAULTSIZE|LR_SHARED
When you are finished using the icon, destroy it using the DestroyIcon function.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIconFromResourceEx
CreateIconIndirect
GetIconInfo
Icons
LoadResource
LookupIconIdFromDirectory
LookupIconIdFromDirectoryEx
Reference
as
minutes to read • Edit Online
Creates an icon or cursor from resource bits describing the icon.
Syntax
HICON CreateIconFromResourceEx(
PBYTE presbits,
DWORD dwResSize,
BOOL fIcon,
DWORD dwVer,
int cxDesired,
int cyDesired,
UINT Flags
);
Parameters
presbits
Type: PBYTE
The icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectoryEx and
LoadResource functions.
dwResSize
Type: DWORD
The size, in bytes, of the set of bits pointed to by the pbIconBits parameter.
fIcon
Type: BOOL
Indicates whether an icon or a cursor is to be created. If this parameter is TRUE , an icon is to be created. If it is
FALSE , a cursor is to be created.
dwVer
Type: DWORD
The version number of the icon or cursor format for the resource bits pointed to by the pbIconBits parameter. The
value must be greater than or equal to 0x00020000 and less than or equal to 0x00030000. This parameter is
generally set to 0x00030000.
cxDesired
Type: int
The desired 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.
cyDesired
Type: int
The desired 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.
Flags
Type: UINT
A combination of the following values.
VA L UE
M EA N IN G
Uses the default color format.
LR_
DEF
AU
LTC
OL
OR
0x0
000
000
0
LR_
DEF
AU
LTSI
ZE
0x0
000
004
0
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 this flag is not specified and cxDesired and
cyDesired are set to zero, the function uses the actual resource
size. If the resource contains multiple images, the function
uses the size of the first image.
Creates a monochrome icon or cursor.
LR_
MO
NO
CH
RO
ME
0x0
000
000
1
LR_
SH
ARE
D
0x0
000
800
0
Shares the icon or cursor handle if the icon or cursor is created
multiple times. If LR_SHARED is not set, a second call to
CreateIconFromResourceEx for the same resource will
create the icon or cursor again and return a different handle.
When you use this flag, the system will destroy the
resource when it is no longer needed.
Do not use LR_SHARED for icons or cursors that have
non-standard sizes, that may change after loading, or that
are loaded from a file.
When loading a system icon or cursor, you must use
LR_SHARED or the function will fail to load the resource.
Return value
Type: HICON
If the function succeeds, the return value is a handle to the icon or cursor.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
The CreateIconFromResource, CreateIconFromResourceEx , CreateIconIndirect, GetIconInfo, and
LookupIconIdFromDirectoryEx functions allow shell applications and icon browsers to examine and use resources
throughout the system.
You should call DestroyIcon for icons created with CreateIconFromResourceEx .
Examples
For an example, see Sharing Icon Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
BITMAPINFOHEADER
Conceptual
CreateIconFromResource
CreateIconIndirect
DestroyIcon
GetIconInfo
Icons
LoadResource
LookupIconIdFromDirectoryEx
Other Resources
Reference
minutes to read • Edit Online
Creates an icon or cursor from an ICONINFO structure.
Syntax
HICON CreateIconIndirect(
PICONINFO piconinfo
);
Parameters
piconinfo
Type: PICONINFO
A pointer to an ICONINFO structure the function uses to create the icon or cursor.
Return value
Type: HICON
If the function succeeds, the return value is a handle to the icon or cursor that is created.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
The system copies the bitmaps in the ICONINFO structure before creating the icon or cursor. 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 you are finished using the icon, destroy it using the DestroyIcon function.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
See also
Conceptual
DestroyIcon
ICONINFO
Icons
Reference
User32.dll
minutes to read • Edit Online
Creates a menu. The menu is initially empty, but it can be filled with menu items by using the InsertMenuItem,
AppendMenu, and InsertMenu functions.
Syntax
HMENU CreateMenu();
Parameters
This function has no parameters.
Return value
Type: HMENU
If the function succeeds, the return value is a handle to the newly created menu.
If the function fails, the return value is NULL . 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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
AppendMenu
Conceptual
CreatePopupMenu
DestroyMenu
InsertMenu
InsertMenuItem
Menus
Reference
SetMenu
minutes to read • Edit Online
Creates a drop-down menu, submenu, or shortcut menu. The menu is initially empty. You can insert or append
menu items by using the InsertMenuItem function. You can also use the InsertMenu function to insert menu items
and the AppendMenu function to append menu items.
Syntax
HMENU CreatePopupMenu();
Parameters
This function has no parameters.
Return value
Type: HMENU
If the function succeeds, the return value is a handle to the newly created menu.
If the function fails, the return value is NULL . 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.
Examples
For an example, see Adding Lines and Graphs to a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
AppendMenu
Conceptual
CreateMenu
DestroyMenu
InsertMenu
InsertMenuItem
Menus
Reference
SetMenu
TrackPopupMenu
TrackPopupMenuEx
minutes to read • Edit Online
Contains global cursor information.
Syntax
typedef struct tagCURSORINFO {
DWORD cbSize;
DWORD flags;
HCURSOR hCursor;
POINT ptScreenPos;
} CURSORINFO, *PCURSORINFO, *LPCURSORINFO;
Members
cbSize
Type: DWORD
The size of the structure, in bytes. The caller must set this to
sizeof(CURSORINFO)
.
flags
Type: DWORD
The cursor state. This parameter can be one of the following values.
VA L UE
M EA N IN G
The cursor is hidden.
0
The cursor is showing.
CU
RS
OR_
SH
OW
ING
0x0
000
000
1
CU
RS
OR_
SUP
PRE
SSE
D
0x0
000
000
2
Windows 8 : The cursor is suppressed. This flag indicates that
the system is not drawing the cursor because the user is
providing input through touch or pen instead of the mouse.
hCursor
Type: HCURSOR
A handle to the cursor.
ptScreenPos
Type: POINT
A structure that receives the screen coordinates of the cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
Cursors
GetCursorInfo
POINT
Reference
minutes to read • Edit Online
Contains information about a cursor.
Syntax
typedef struct tagCURSORSHAPE {
int xHotSpot;
int yHotSpot;
int cx;
int cy;
int cbWidth;
BYTE Planes;
BYTE BitsPixel;
} CURSORSHAPE, *LPCURSORSHAPE;
Members
xHotSpot
Type: int
The horizontal position of the hot spot, relative to the upper-left corner of the cursor bitmap.
yHotSpot
Type: int
The vertical position of the hot spot, relative to the upper-left corner of the cursor bitmap.
cx
Type: int
The width, in pixels, of the cursor.
cy
Type: int
The height, in pixels, of the cursor.
cbWidth
Type: int
The width, in bytes, of the cursor bitmap.
Planes
Type: BYTE
The number of color planes.
BitsPixel
Type: BYTE
The number of bits used to indicate the color of a single pixel in the cursor.
Remarks
When an application passes a cursor handle to the LockResourcefunction, the function returns a pointer to a buffer
containing information about the cursor. An application can use the CURSORSHAPE structure to access the
information.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
LockResource
Reference
Resources
minutes to read • Edit Online
Deletes an item from the specified menu. If the menu item opens a menu or submenu, this function destroys the
handle to the menu or submenu and frees the memory used by the menu or submenu.
Syntax
BOOL DeleteMenu(
HMENU hMenu,
UINT uPosition,
UINT uFlags
);
Parameters
hMenu
Type: HMENU
A handle to the menu to be changed.
uPosition
Type: UINT
The menu item to be deleted, as determined by the uFlags parameter.
uFlags
Type: UINT
Indicates how the uPosition parameter is interpreted. This parameter must be one of the following values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
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
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that uPosition gives the zero-based relative position
of the menu item.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
Examples
For an example, see Example of a Clipboard Viewer.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DrawMenuBar
Menus
Reference
RemoveMenu
minutes to read • Edit Online
Destroys an accelerator table.
Syntax
BOOL DestroyAcceleratorTable(
HACCEL hAccel
);
Parameters
hAccel
Type: HACCEL
A handle to the accelerator table to be destroyed. This handle must have been created by a call to the
CreateAcceleratorTable or LoadAccelerators function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero. However, if the table has been loaded more than one call to
LoadAccelerators, the function will return a nonzero value only when DestroyAcceleratorTable has been called
an equal number of times.
If the function fails, the return value is zero.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyAcceleratorTable
CreateAcceleratorTable
Keyboard Accelerators
LoadAccelerators
Reference
TranslateAccelerator
minutes to read • Edit Online
Destroys the caret's current shape, frees the caret from the window, and removes the caret from the screen.
Syntax
BOOL DestroyCaret();
Parameters
This function has no parameters.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
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.
For an example, see Destroying a Caret
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
CreateCaret
HideCaret
Reference
ShowCaret
minutes to read • Edit Online
Destroys a cursor and frees any memory the cursor occupied. Do not use this function to destroy a shared cursor.
Syntax
BOOL DestroyCursor(
HCURSOR hCursor
);
Parameters
hCursor
Type: HCURSOR
A handle to the cursor to be destroyed. The cursor must not be in use.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The DestroyCursor function destroys a nonshared 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)
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyCursor
CopyImage
CreateCursor
Cursors
LoadCursor
LoadCursorFromFile
LoadImage
Reference
minutes to read • Edit Online
Destroys an icon and frees any memory the icon occupied.
Syntax
BOOL DestroyIcon(
HICON hIcon
);
Parameters
hIcon
Type: HICON
A handle to the icon to be destroyed. The icon must not be in use.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
It is only necessary to call DestroyIcon for icons and cursors created with the following functions:
CreateIconFromResourceEx (if called without the LR_SHARED flag), CreateIconIndirect, and CopyIcon. Do not use
this function to destroy a shared icon. A shared icon is valid as long as the module from which it was loaded
remains in memory. The following functions obtain a shared icon.
LoadIcon
LoadImage (if you use the LR_SHARED flag)
CopyImage (if you use the LR_COPYRETURNORG flag and the hImage parameter is a shared icon)
CreateIconFromResource
CreateIconFromResourceEx (if you use the LR_SHARED flag)
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyIcon
CreateIconFromResource
CreateIconFromResourceEx
CreateIconIndirect
Icons
Reference
minutes to read • Edit Online
Destroys the specified menu and frees any memory that the menu occupies.
Syntax
BOOL DestroyMenu(
HMENU hMenu
);
Parameters
hMenu
Type: HMENU
A handle to the menu to be destroyed.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
DestroyMenu is recursive, that is, it will destroy the menu and all its submenus.
Examples
For an example, see Displaying a Shortcut Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
See also
Conceptual
CreateMenu
DeleteMenu
Menus
Reference
RemoveMenu
SetMenuItemInfo
User32.dll
minutes to read • Edit Online
Draws an icon or cursor into the specified device context.
To specify additional drawing options, use the DrawIconEx function.
Syntax
BOOL DrawIcon(
HDC hDC,
int X,
int Y,
HICON hIcon
);
Parameters
hDC
Type: HDC
A handle to the device context into which the icon or cursor will be drawn.
X
Type: int
The logical x-coordinate of the upper-left corner of the icon.
Y
Type: int
The logical y-coordinate of the upper-left corner of the icon.
hIcon
Type: HICON
A handle to the icon to be drawn.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
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.
DrawIcon draws the icon or cursor using the width and height specified by the system metric values for icons; for
more information, see GetSystemMetrics.
Examples
For an example, see Displaying an Icon.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
DrawIconEx
Icons
LoadIcon
Reference
minutes to read • Edit Online
Draws an icon or cursor into the specified device context, performing the specified raster operations, and stretching
or compressing the icon or cursor as specified.
Syntax
BOOL DrawIconEx(
HDC
hdc,
int
xLeft,
int
yTop,
HICON hIcon,
int
cxWidth,
int
cyWidth,
UINT istepIfAniCur,
HBRUSH hbrFlickerFreeDraw,
UINT diFlags
);
Parameters
hdc
Type: HDC
A handle to the device context into which the icon or cursor will be drawn.
xLeft
Type: int
The logical x-coordinate of the upper-left corner of the icon or cursor.
yTop
Type: int
The logical y-coordinate of the upper-left corner of the icon or cursor.
hIcon
Type: HICON
A handle to the icon or cursor to be drawn. This parameter can identify an animated cursor.
cxWidth
Type: int
The logical width of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE , the
function uses the SM_CXICON system metric value to set the width. If this parameter is zero and
DI_DEFAULTSIZE is not used, the function uses the actual resource width.
cyWidth
Type: int
The logical height of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE , the
function uses the SM_CYICON system metric value to set the width. If this parameter is zero and
DI_DEFAULTSIZE is not used, the function uses the actual resource height.
istepIfAniCur
Type: UINT
The index of the frame to draw, if hIcon identifies an animated cursor. This parameter is ignored if hIcon does not
identify an animated cursor.
hbrFlickerFreeDraw
Type: HBRUSH
A handle to a brush that the system uses for flicker-free drawing. If hbrFlickerFreeDraw is a valid brush handle, the
system creates an offscreen bitmap using the specified brush for the background color, draws the icon or cursor
into the bitmap, and then copies the bitmap into the device context identified by hdc. If hbrFlickerFreeDraw is
NULL , the system draws the icon or cursor directly into the device context.
diFlags
Type: UINT
The drawing flags. This parameter can be one of the following values.
VA L UE
M EA N IN G
This flag is ignored.
DI_
CO
MP
AT
0x0
004
DI_
DEF
AU
LTSI
ZE
0x0
008
Draws the icon or cursor using the width and height specified
by the system metric values for icons, if the cxWidth and
cyWidth parameters are set to zero. If this flag is not specified
and cxWidth and cyWidth are set to zero, the function uses
the actual resource size.
Draws the icon or cursor using the image.
DI_I
MA
GE
0x0
002
Draws the icon or cursor using the mask.
DI_
MA
SK
0x0
001
Draws the icon as an unmirrored icon. By default, the icon is
drawn as a mirrored icon if hdc is mirrored.
DI_
NO
MIR
RO
R
0x0
010
Combination of DI_IMAGE and DI_MASK .
DI_
NO
RM
AL
0x0
003
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
To duplicate
DrawIcon (hDC, X, Y, hIcon)
, call DrawIconEx as follows:
DrawIconEx (hDC, X, Y, hIcon, 0, 0, 0, NULL, DI_NORMAL | DI_COMPAT | DI_DEFAULTSIZE);
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyImage
DrawIcon
Icons
LoadImage
Reference
minutes to read • Edit Online
Redraws the menu bar of the specified window. If the menu bar changes after the system has created the window,
this function must be called to draw the changed menu bar.
Syntax
BOOL DrawMenuBar(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window whose menu bar is to be redrawn.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DeleteMenu
InsertMenuItem
Menus
Reference
RemoveMenu
SetMenuItemInfo
minutes to read • Edit Online
Enables, disables, or grays the specified menu item.
Syntax
BOOL EnableMenuItem(
HMENU hMenu,
UINT uIDEnableItem,
UINT uEnable
);
Parameters
hMenu
Type: HMENU
A handle to the menu.
uIDEnableItem
Type: UINT
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
Type: UINT
Controls the interpretation of the uIDEnableItem parameter and indicate whether the menu item is enabled,
disabled, or grayed. This parameter must be a combination of the following values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
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
_BY
PO
SITI
ON
0x0
000
040
0L
MF
_DI
SAB
LED
0x0
000
000
2L
MF
_EN
ABL
ED
0x0
000
000
0L
MF
_GR
AYE
D
0x0
000
000
1L
Indicates that uIDEnableItem gives the zero-based relative
position of the menu item.
Indicates that the menu item is disabled, but not grayed, so it
cannot be selected.
Indicates that the menu item is enabled and restored from a
grayed state so that it can be selected.
Indicates that the menu item is disabled and grayed so that it
cannot be selected.
Return value
Type: BOOL
The return value specifies the previous state of the menu item (it is either MF_DISABLED , MF_ENABLED , or
MF_GRAYED ). If the menu item does not exist, the return value is -1.
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 a 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, disabled, or grayed) of a menu item.
When you change a window menu, the menu bar is not immediately updated. To force the update, call
DrawMenuBar.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DrawMenuBar
GetMenuItemID
InsertMenu
InsertMenuItem
LoadMenuIndirect
Menus
ModifyMenu
Reference
SetMenuItemInfo
WM_SYSCOMMAND
minutes to read • Edit Online
Ends the calling thread's active menu.
Syntax
BOOL EndMenu();
Parameters
This function has no parameters.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If a platform does not support EndMenu , send the owner of the active menu a WM_CANCELMODE message.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Menus
Reference
WM_CANCELMODE
minutes to read • Edit Online
Retrieves the time required to invert the caret's pixels. The user can set this value.
Syntax
UINT GetCaretBlinkTime();
Parameters
This function has no parameters.
Return value
Type: UINT
If the function succeeds, the return value is the blink time, in milliseconds.
A return value of INFINITE indicates that the caret does not blink.
A return value is zero indicates that the function has failed. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
Reference
SetCaretBlinkTime
minutes to read • Edit Online
Copies the caret's position to the specified POINT structure.
Syntax
BOOL GetCaretPos(
LPPOINT lpPoint
);
Parameters
lpPoint
Type: LPPOINT
A pointer to the POINT structure that is to receive the client coordinates of the caret.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
DPI Virtualization
This API does not participate in DPI virtualization. The returned values are interpreted as logical sizes in terms of the
window in question. The calling thread is not taken into consideration.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
Other Resources
POINT
Reference
SetCaretPos
minutes to read • Edit Online
Retrieves the screen coordinates of the rectangular area to which the cursor is confined.
Syntax
BOOL GetClipCursor(
LPRECT lpRect
);
Parameters
lpRect
Type: LPRECT
A 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 value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
Examples
For an example, see Confining a Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
See also
ClipCursor
Conceptual
Cursors
GetCursorPos
Other Resources
RECT
Reference
User32.dll
minutes to read • Edit Online
Retrieves a handle to the current cursor.
To get information on the global cursor, even if it is not owned by the current thread, use GetCursorInfo.
Syntax
HCURSOR GetCursor();
Parameters
This function has no parameters.
Return value
Type: HCURSOR
The return value is the handle to the current cursor. If there is no cursor, the return value is NULL .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
GetCursorInfo
Reference
SetCursor
minutes to read • Edit Online
Retrieves information about the global cursor.
Syntax
BOOL GetCursorInfo(
PCURSORINFO pci
);
Parameters
pci
Type: PCURSORINFO
A pointer to a CURSORINFO structure that receives the information. Note that you must set the cbSize member to
sizeof(CURSORINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CURSORINFO
Conceptual
Cursors
GetGUIThreadInfo
Reference
minutes to read • Edit Online
Retrieves the position of the mouse cursor, in screen coordinates.
Syntax
BOOL GetCursorPos(
LPPOINT lpPoint
);
Parameters
lpPoint
Type: LPPOINT
A pointer to a POINT structure that receives the screen coordinates of the cursor.
Return value
Type: BOOL
Returns nonzero if successful or zero otherwise. To get extended error information, call GetLastError.
Remarks
The cursor position is always specified 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.
The input desktop must be the current desktop when you call GetCursorPos . Call OpenInputDesktop to determine
whether the current desktop is the input desktop. If it is not, call SetThreadDesktop with the HDESK returned by
OpenInputDesktop to switch to that desktop.
Examples
For an example, see Using the Keyboard to Move the Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ClipCursor
Conceptual
Cursors
GetCursorInfo
GetMessagePos
Other Resources
POINT
Reference
SetCursor
SetCursorPos
ShowCursor
minutes to read • Edit Online
Retrieves information about the specified icon or cursor.
Syntax
BOOL GetIconInfo(
HICON
hIcon,
PICONINFO piconinfo
);
Parameters
hIcon
Type: HICON
A handle to the icon or cursor. To retrieve information about a standard icon or cursor, specify one of the following
values.
VA L UE
M EA N IN G
Standard arrow and small hourglass cursor.
IDC
_AP
PST
ART
ING
MA
KEI
NTR
ESO
URC
E(32
650)
Standard arrow cursor.
IDC
_AR
RO
W
MA
KEI
NTR
ESO
URC
E(32
512)
Crosshair cursor.
IDC
_CR
OSS
MA
KEI
NTR
ESO
URC
E(32
515)
Hand cursor.
IDC
_HA
ND
MA
KEI
NTR
ESO
URC
E(32
649)
Arrow and question mark cursor.
IDC
_HE
LP
MA
KEI
NTR
ESO
URC
E(32
651)
I-beam cursor.
IDC
_IB
EA
M
MA
KEI
NTR
ESO
URC
E(32
513)
Slashed circle cursor.
IDC
_N
O
MA
KEI
NTR
ESO
URC
E(32
648)
IDC
_SI
ZEA
LL
MA
KEI
NTR
ESO
URC
E(32
646)
IDC
_SI
ZEN
ES
W
MA
KEI
NTR
ESO
URC
E(32
643)
Four-pointed arrow cursor pointing north, south, east, and
west.
Double-pointed arrow cursor pointing northeast and
southwest.
Double-pointed arrow cursor pointing north and south.
IDC
_SI
ZEN
S
MA
KEI
NTR
ESO
URC
E(32
645)
IDC
_SI
ZEN
WS
E
MA
KEI
NTR
ESO
URC
E(32
642)
Double-pointed arrow cursor pointing northwest and
southeast.
Double-pointed arrow cursor pointing west and east.
IDC
_SI
ZE
WE
MA
KEI
NTR
ESO
URC
E(32
644)
Vertical arrow cursor.
IDC
_UP
ARR
OW
MA
KEI
NTR
ESO
URC
E(32
516)
Hourglass cursor.
IDC
_W
AIT
MA
KEI
NTR
ESO
URC
E(32
514)
Application icon.
IDI_
APP
LIC
ATI
ON
MA
KEI
NTR
ESO
URC
E(32
512)
Asterisk icon.
IDI_
AST
ERI
SK
MA
KEI
NTR
ESO
URC
E(32
516)
Exclamation point icon.
IDI_
EXC
LA
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
515)
Stop sign icon.
IDI_
HA
ND
MA
KEI
NTR
ESO
URC
E(32
513)
Question-mark icon.
IDI_
QU
EST
ION
MA
KEI
NTR
ESO
URC
E(32
514)
IDI_
WI
NL
OG
O
MA
KEI
NTR
ESO
URC
E(32
517)
Application icon.
Windows 2000: Windows logo icon.
piconinfo
Type: PICONINFO
A pointer to an ICONINFO structure. The function fills in the structure's members.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero and the function fills in the members of the specified
ICONINFO structure.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
GetIconInfo creates bitmaps for the hbmMask and hbmCol or members of ICONINFO. The calling application
must manage these bitmaps and delete them when they are no longer necessary.
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
CreateIconFromResource
CreateIconIndirect
DestroyIcon
DrawIcon
DrawIconEx
ICONINFO
Icons
LoadIcon
LookupIconIdFromDirectory
Reference
minutes to read • Edit Online
Retrieves information about the specified icon or cursor. GetIconInfoEx extends GetIconInfo by using the newer
ICONINFOEX structure.
Syntax
BOOL GetIconInfoExA(
HICON
hicon,
PICONINFOEXA piconinfo
);
Parameters
hicon
Type: HICON
A handle to the icon or cursor. To retrieve information about a standard icon or cursor, specify one of the following
values.
VA L UE
M EA N IN G
Standard arrow and small hourglass cursor.
IDC
_AP
PST
ART
ING
MA
KEI
NTR
ESO
URC
E(32
650)
Standard arrow cursor.
IDC
_AR
RO
W
MA
KEI
NTR
ESO
URC
E(32
512)
Crosshair cursor.
IDC
_CR
OSS
MA
KEI
NTR
ESO
URC
E(32
515)
Hand cursor.
IDC
_HA
ND
MA
KEI
NTR
ESO
URC
E(32
649)
Arrow and question mark cursor.
IDC
_HE
LP
MA
KEI
NTR
ESO
URC
E(32
651)
I-beam cursor.
IDC
_IB
EA
M
MA
KEI
NTR
ESO
URC
E(32
513)
Slashed circle cursor.
IDC
_N
O
MA
KEI
NTR
ESO
URC
E(32
648)
IDC
_SI
ZEA
LL
MA
KEI
NTR
ESO
URC
E(32
646)
IDC
_SI
ZEN
ES
W
MA
KEI
NTR
ESO
URC
E(32
643)
Four-pointed arrow cursor pointing north, south, east, and
west.
Double-pointed arrow cursor pointing northeast and
southwest.
Double-pointed arrow cursor pointing north and south.
IDC
_SI
ZEN
S
MA
KEI
NTR
ESO
URC
E(32
645)
IDC
_SI
ZEN
WS
E
MA
KEI
NTR
ESO
URC
E(32
642)
Double-pointed arrow cursor pointing northwest and
southeast.
Double-pointed arrow cursor pointing west and east.
IDC
_SI
ZE
WE
MA
KEI
NTR
ESO
URC
E(32
644)
Vertical arrow cursor.
IDC
_UP
ARR
OW
MA
KEI
NTR
ESO
URC
E(32
516)
Hourglass cursor.
IDC
_W
AIT
MA
KEI
NTR
ESO
URC
E(32
514)
Application icon.
IDI_
APP
LIC
ATI
ON
MA
KEI
NTR
ESO
URC
E(32
512)
Asterisk icon.
IDI_
AST
ERI
SK
MA
KEI
NTR
ESO
URC
E(32
516)
Exclamation point icon.
IDI_
EXC
LA
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
515)
Stop sign icon.
IDI_
HA
ND
MA
KEI
NTR
ESO
URC
E(32
513)
Question-mark icon.
IDI_
QU
EST
ION
MA
KEI
NTR
ESO
URC
E(32
514)
IDI_
WI
NL
OG
O
MA
KEI
NTR
ESO
URC
E(32
517)
Application icon.
Windows 2000: Windows logo icon.
piconinfo
Type: PICONINFOEX
When this method returns, contains a pointer to an ICONINFOEX structure. The function fills in the structure's
members.
Return value
Type: BOOL
TRUE indicates success, FALSE indicates failure.
Remarks
GetIconInfoEx creates bitmaps for the hbmMask and hbmCol or members of ICONINFOEX. The calling
application must manage these bitmaps and delete them when they are no longer necessary.
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
CreateIconFromResource
CreateIconIndirect
DestroyIcon
DrawIcon
DrawIconEx
ICONINFO
Icons
LoadIcon
LookupIconIdFromDirectory
Reference
minutes to read • Edit Online
Retrieves information about the specified icon or cursor. GetIconInfoEx extends GetIconInfo by using the newer
ICONINFOEX structure.
Syntax
BOOL GetIconInfoExW(
HICON
hicon,
PICONINFOEXW piconinfo
);
Parameters
hicon
Type: HICON
A handle to the icon or cursor. To retrieve information about a standard icon or cursor, specify one of the following
values.
VA L UE
M EA N IN G
Standard arrow and small hourglass cursor.
IDC
_AP
PST
ART
ING
MA
KEI
NTR
ESO
URC
E(32
650)
Standard arrow cursor.
IDC
_AR
RO
W
MA
KEI
NTR
ESO
URC
E(32
512)
Crosshair cursor.
IDC
_CR
OSS
MA
KEI
NTR
ESO
URC
E(32
515)
Hand cursor.
IDC
_HA
ND
MA
KEI
NTR
ESO
URC
E(32
649)
Arrow and question mark cursor.
IDC
_HE
LP
MA
KEI
NTR
ESO
URC
E(32
651)
I-beam cursor.
IDC
_IB
EA
M
MA
KEI
NTR
ESO
URC
E(32
513)
Slashed circle cursor.
IDC
_N
O
MA
KEI
NTR
ESO
URC
E(32
648)
IDC
_SI
ZEA
LL
MA
KEI
NTR
ESO
URC
E(32
646)
IDC
_SI
ZEN
ES
W
MA
KEI
NTR
ESO
URC
E(32
643)
Four-pointed arrow cursor pointing north, south, east, and
west.
Double-pointed arrow cursor pointing northeast and
southwest.
Double-pointed arrow cursor pointing north and south.
IDC
_SI
ZEN
S
MA
KEI
NTR
ESO
URC
E(32
645)
IDC
_SI
ZEN
WS
E
MA
KEI
NTR
ESO
URC
E(32
642)
Double-pointed arrow cursor pointing northwest and
southeast.
Double-pointed arrow cursor pointing west and east.
IDC
_SI
ZE
WE
MA
KEI
NTR
ESO
URC
E(32
644)
Vertical arrow cursor.
IDC
_UP
ARR
OW
MA
KEI
NTR
ESO
URC
E(32
516)
Hourglass cursor.
IDC
_W
AIT
MA
KEI
NTR
ESO
URC
E(32
514)
Application icon.
IDI_
APP
LIC
ATI
ON
MA
KEI
NTR
ESO
URC
E(32
512)
Asterisk icon.
IDI_
AST
ERI
SK
MA
KEI
NTR
ESO
URC
E(32
516)
Exclamation point icon.
IDI_
EXC
LA
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
515)
Stop sign icon.
IDI_
HA
ND
MA
KEI
NTR
ESO
URC
E(32
513)
Question-mark icon.
IDI_
QU
EST
ION
MA
KEI
NTR
ESO
URC
E(32
514)
IDI_
WI
NL
OG
O
MA
KEI
NTR
ESO
URC
E(32
517)
Application icon.
Windows 2000: Windows logo icon.
piconinfo
Type: PICONINFOEX
When this method returns, contains a pointer to an ICONINFOEX structure. The function fills in the structure's
members.
Return value
Type: BOOL
TRUE indicates success, FALSE indicates failure.
Remarks
GetIconInfoEx creates bitmaps for the hbmMask and hbmCol or members of ICONINFOEX. The calling
application must manage these bitmaps and delete them when they are no longer necessary.
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
CreateIconFromResource
CreateIconIndirect
DestroyIcon
DrawIcon
DrawIconEx
ICONINFO
Icons
LoadIcon
LookupIconIdFromDirectory
Reference
minutes to read • Edit Online
Retrieves a handle to the menu assigned to the specified window.
Syntax
HMENU GetMenu(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window whose menu handle is to be retrieved.
Return value
Type: HMENU
The return value is a handle to the menu. If the specified window has no menu, the return value is NULL . If the
window is a child window, the return value is undefined.
Remarks
GetMenu does not work on floating menu bars. Floating menu bars are custom controls that mimic standard
menus; they are not menus. To get the handle on a floating menu bar, use the Active Accessibility APIs.
Examples
For an example, see Adding Lines and Graphs to a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetSubMenu
Menus
Reference
SetMenu
minutes to read • Edit Online
Retrieves information about the specified menu bar.
Syntax
BOOL GetMenuBarInfo(
HWND
hwnd,
LONG
idObject,
LONG
idItem,
PMENUBARINFO pmbi
);
Parameters
hwnd
Type: HWND
A handle to the window (menu bar) whose information is to be retrieved.
idObject
Type: LONG
The menu object. This parameter can be one of the following values.
VA L UE
M EA N IN G
The popup menu associated with the window.
OBJ
ID_
CLI
ENT
((LO
NG)
0xFF
FFFF
FC)
OBJ
ID_
ME
NU
((LO
NG)
0xFF
FFFF
FD)
The menu bar associated with the window (see the GetMenu
function).
OBJ
ID_
SYS
ME
NU
((LO
NG)
0xFF
FFFF
FF)
The system menu associated with the window (see the
GetSystemMenu function).
idItem
Type: LONG
The item for which to retrieve information. If this parameter is zero, the function retrieves information about the
menu itself. If this parameter is 1, the function retrieves information about the first item on the menu, and so on.
pmbi
Type: PMENUBARINFO
A pointer to a MENUBARINFO structure that receives the information. Note that you must set the cbSize member
to sizeof(MENUBARINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenu
GetSystemMenu
MENUBARINFO
Menus
Reference
minutes to read • Edit Online
Retrieves the dimensions of the default check-mark bitmap. The system displays this bitmap next to selected menu
items. Before calling the SetMenuItemBitmaps function to replace the default check-mark bitmap for a menu item,
an application must determine the correct bitmap size by calling GetMenuCheckMarkDimensions .
Note The GetMenuCheckMarkDimensions function is included only for compatibility with 16-bit versions of Windows.
Applications should use the GetSystemMetrics function with the CXMENUCHECK and CYMENUCHECK values to retrieve the
bitmap dimensions.
Syntax
LONG GetMenuCheckMarkDimensions();
Parameters
This function has no parameters.
Return value
Type: LONG
The return value specifies the height and width, in pixels, of the default check-mark bitmap. The high-order word
contains the height; the low-order word contains the width.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Menus
Reference
SetMenuItemBitmaps
minutes to read • Edit Online
Determines the default menu item on the specified menu.
Syntax
UINT GetMenuDefaultItem(
HMENU hMenu,
UINT fByPos,
UINT gmdiFlags
);
Parameters
hMenu
Type: HMENU
A handle to the menu for which to retrieve the default menu item.
fByPos
Type: UINT
Indicates whether to retrieve the menu item's identifier or its position. If this parameter is FALSE , the identifier is
returned. Otherwise, the position is returned.
gmdiFlags
Type: UINT
Indicates how the function should search for menu items. This parameter can be zero or more of the following
values.
VA L UE
GM
DI_
GOI
NT
OP
OP
UPS
0x0
002
L
M EA N IN G
If the default item is one that opens a submenu, the function
is to search recursively in the corresponding submenu. If the
submenu has no default item, the return value identifies the
item that opens the submenu. By default, the function returns
the first default item on the specified menu, regardless of
whether it is an item that opens a submenu.
GM
DI_
USE
DIS
ABL
ED
0x0
001
L
The function is to return a default item, even if it is disabled.
By default, the function skips disabled or grayed items.
Return value
Type: UINT
If the function succeeds, the return value is the identifier or position of the menu item.
If the function fails, the return value is -1. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Menus
Reference
SetMenuDefaultItem
minutes to read • Edit Online
Retrieves information about a specified menu.
Syntax
BOOL GetMenuInfo(
HMENU
,
LPMENUINFO
);
Parameters
arg1
Type: HMENU
A handle on a menu.
arg2
Type: LPMENUINFO
A pointer to a MENUINFO structure containing information for the menu. Note that you must set the cbSize
member to sizeof(MENUINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Menus
minutes to read • Edit Online
Determines the number of items in the specified menu.
Syntax
int GetMenuItemCount(
HMENU hMenu
);
Parameters
hMenu
Type: HMENU
A handle to the menu to be examined.
Return value
Type: int
If the function succeeds, the return value specifies the number of items in the menu.
If the function fails, the return value is -1. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenuItemID
Menus
Reference
minutes to read • Edit Online
Retrieves the menu item identifier of a menu item located at the specified position in a menu.
Syntax
UINT GetMenuItemID(
HMENU hMenu,
int nPos
);
Parameters
hMenu
Type: HMENU
A handle to the menu that contains the item whose identifier is to be retrieved.
nPos
Type: int
The zero-based relative position of the menu item whose identifier is to be retrieved.
Return value
Type: UINT
The return value is the identifier of the specified menu item. If the menu item identifier is NULL or if the specified
item opens a submenu, the return value is -1.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenuItemCount
Menus
Reference
minutes to read • Edit Online
Retrieves information about a menu item.
Syntax
BOOL GetMenuItemInfoA(
HMENU
hmenu,
UINT
item,
BOOL
fByPosition,
LPMENUITEMINFOA lpmii
);
Parameters
hmenu
Type: HMENU
A handle to the menu that contains the menu item.
item
Type: UINT
The identifier or position of the menu item to get information about. The meaning of this parameter depends on
the value of fByPosition.
fByPosition
Type: BOOL
The meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu item
position. See Accessing Menu Items Programmatically for more information.
lpmii
Type: LPMENUITEMINFO
A pointer to a MENUITEMINFO structure that specifies the information to retrieve and receives information about
the menu item. Note that you must set the cbSize member to sizeof(MENUITEMINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
To retrieve a menu item of type MFT_STRING , first find the size of the string by setting the dwTypeData member
of MENUITEMINFO to NULL and then calling GetMenuItemInfo . The value of cch +1 is the size needed. Then
allocate a buffer of this size, place the pointer to the buffer in dwTypeData , increment cch by one, and then call
GetMenuItemInfo once again to fill the buffer with the string.
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 fType member and sets cch to 0.
Examples
For an example, see Example of Owner-Drawn Menu Items.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Menus
Reference
SetMenuItemInfo
minutes to read • Edit Online
Retrieves information about a menu item.
Syntax
BOOL GetMenuItemInfoW(
HMENU
hmenu,
UINT
item,
BOOL
fByPosition,
LPMENUITEMINFOW lpmii
);
Parameters
hmenu
Type: HMENU
A handle to the menu that contains the menu item.
item
Type: UINT
The identifier or position of the menu item to get information about. The meaning of this parameter depends on
the value of fByPosition.
fByPosition
Type: BOOL
The meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu item
position. See Accessing Menu Items Programmatically for more information.
lpmii
Type: LPMENUITEMINFO
A pointer to a MENUITEMINFO structure that specifies the information to retrieve and receives information about
the menu item. Note that you must set the cbSize member to sizeof(MENUITEMINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
To retrieve a menu item of type MFT_STRING , first find the size of the string by setting the dwTypeData member
of MENUITEMINFO to NULL and then calling GetMenuItemInfo . The value of cch +1 is the size needed. Then
allocate a buffer of this size, place the pointer to the buffer in dwTypeData , increment cch by one, and then call
GetMenuItemInfo once again to fill the buffer with the string.
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 fType member and sets cch to 0.
Examples
For an example, see Example of Owner-Drawn Menu Items.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Menus
Reference
SetMenuItemInfo
minutes to read • Edit Online
Retrieves the bounding rectangle for the specified menu item.
Syntax
BOOL GetMenuItemRect(
HWND hWnd,
HMENU hMenu,
UINT uItem,
LPRECT lprcItem
);
Parameters
hWnd
Type: HWND
A handle to the window containing the menu.
If this value is NULL and the hMenu parameter represents a popup menu, the function will find the menu window.
hMenu
Type: HMENU
A handle to a menu.
uItem
Type: UINT
The zero-based position of the menu item.
lprcItem
Type: LPRECT
A pointer to a RECT structure that receives the bounding rectangle of the specified menu item expressed in screen
coordinates.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
In order for the returned rectangle to be meaningful, the menu must be popped up if a popup menu or attached to
a window if a menu bar. Menu item positions are not determined until the menu is displayed.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Menus
minutes to read • Edit Online
Retrieves the menu flags associated with the specified menu item. If the menu item opens a submenu, this function
also returns the number of items in the submenu.
Note The GetMenuState function has been superseded by the GetMenuItemInfo. You can still use GetMenuState , however, if
you do not need any of the extended features of GetMenuItemInfo .
Syntax
UINT GetMenuState(
HMENU hMenu,
UINT uId,
UINT uFlags
);
Parameters
hMenu
Type: HMENU
A handle to the menu that contains the menu item whose flags are to be retrieved.
uId
Type: UINT
The menu item for which the menu flags are to be retrieved, as determined by the uFlags parameter.
uFlags
Type: UINT
Indicates how the uId parameter is interpreted. This parameter can be one of the following values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
Indicates that the uId 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
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that the uId parameter gives the zero-based relative
position of the menu item.
Return value
Type: UINT
If the specified item does not exist, the return value is -1.
If the menu item opens a submenu, the low-order byte of the return value contains the menu flags associated with
the item, and the high-order byte contains the number of items in the submenu opened by the item.
Otherwise, the return value is a mask (Bitwise OR) of the menu flags. Following are the menu flags associated with
the menu item.
RET URN C O DE/ VA L UE
MF
_CH
ECK
ED
0x0
000
000
8L
DESC RIP T IO N
A check mark is placed next to the item (for drop-down
menus, submenus, and shortcut menus only).
The item is disabled.
MF
_DI
SAB
LED
0x0
000
000
2L
The item is disabled and grayed.
MF
_GR
AYE
D
0x0
000
000
1L
The item is highlighted.
MF
_HI
LIT
E
0x0
000
008
0L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
This is the same as the MF_MENUBREAK flag, except for
drop-down menus, submenus, and shortcut menus, where the
new column is separated from the old column by a vertical
line.
The item is placed on a new line (for menu bars) or in a new
column (for drop-down menus, submenus, and shortcut
menus) without separating columns.
The item is owner-drawn.
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Menu item is a submenu.
MF
_PO
PU
P
0x0
000
001
0L
MF
_SE
PAR
ATO
R
0x0
000
080
0L
There is a horizontal dividing line (for drop-down menus,
submenus, and shortcut menus only).
Remarks
It is possible to test an item for a flag value of MF_ENABLED , MF_STRING , MF_UNCHECKED , or MF_UNHILITE .
However, since these values equate to zero you must use an expression to test for them.
FLAG
EXP RESSIO N TO T EST F O R T H E F L A G
MF_ENABLED
! (Flag&(MF_DISABLED | MF_GRAYED))
MF_STRING
! (Flag&(MF_BITMAP | MF_OWNERDRAW))
MF_UNCHECKED
! (Flag&MF_CHECKED)
MF_UNHILITE
! (Flag&HILITE)
Examples
For an example, see Simulating Check Boxes in a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenu
GetMenuItemCount
GetMenuItemID
GetMenuItemInfo
Menus
Reference
minutes to read • Edit Online
Copies the text string of the specified menu item into the specified buffer.
Note The GetMenuString function has been superseded. Use the GetMenuItemInfo function to retrieve the menu item text.
Syntax
int GetMenuStringA(
HMENU hMenu,
UINT uIDItem,
LPSTR lpString,
int cchMax,
UINT flags
);
Parameters
hMenu
Type: HMENU
A handle to the menu.
uIDItem
Type: UINT
The menu item to be changed, as determined by the uFlag parameter.
lpString
Type: LPTSTR
The buffer that receives the null-terminated string. If the string is as long or longer than lpString, the string is
truncated and the terminating null character is added. If lpString is NULL , the function returns the length of the
menu string.
cchMax
Type: int
The maximum length, in characters, of the string to be copied. If the string is longer than the maximum specified in
the nMaxCount parameter, the extra characters are truncated. If nMaxCount is 0, the function returns the length of
the menu string.
flags
Type: UINT
Indicates how the uIDItem parameter is interpreted. This parameter must be one of the following values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
MF
_BY
PO
SITI
ON
0x0
000
040
0L
M EA N IN G
Indicates that uIDItem 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.
Indicates that uIDItem gives the zero-based relative position
of the menu item.
Return value
Type: int
If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the
terminating null character.
If the function fails, the return value is zero.
If the specified item is not of type MIIM_STRING or MFT_STRING , then the return value is zero.
Remarks
The nMaxCount parameter must be one larger than the number of characters in the text string to accommodate the
terminating null character.
If nMaxCount is 0, the function returns the length of the menu string.
Security Warning
The lpString parameter is a TCHAR buffer, and nMaxCount is the length of the menu string in characters. Sizing these
parameters incorrectly can cause truncation of the string, leading to possible loss of data.
Examples
For an example, see Creating User Editable Accelerators.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenuItemID
Menus
Reference
minutes to read • Edit Online
Copies the text string of the specified menu item into the specified buffer.
Note The GetMenuString function has been superseded. Use the GetMenuItemInfo function to retrieve the menu item text.
Syntax
int GetMenuStringW(
HMENU hMenu,
UINT uIDItem,
LPWSTR lpString,
int
cchMax,
UINT flags
);
Parameters
hMenu
Type: HMENU
A handle to the menu.
uIDItem
Type: UINT
The menu item to be changed, as determined by the uFlag parameter.
lpString
Type: LPTSTR
The buffer that receives the null-terminated string. If the string is as long or longer than lpString, the string is
truncated and the terminating null character is added. If lpString is NULL , the function returns the length of the
menu string.
cchMax
Type: int
The maximum length, in characters, of the string to be copied. If the string is longer than the maximum specified in
the nMaxCount parameter, the extra characters are truncated. If nMaxCount is 0, the function returns the length of
the menu string.
flags
Type: UINT
Indicates how the uIDItem parameter is interpreted. This parameter must be one of the following values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
MF
_BY
PO
SITI
ON
0x0
000
040
0L
M EA N IN G
Indicates that uIDItem 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.
Indicates that uIDItem gives the zero-based relative position
of the menu item.
Return value
Type: int
If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the
terminating null character.
If the function fails, the return value is zero.
If the specified item is not of type MIIM_STRING or MFT_STRING , then the return value is zero.
Remarks
The nMaxCount parameter must be one larger than the number of characters in the text string to accommodate the
terminating null character.
If nMaxCount is 0, the function returns the length of the menu string.
Security Warning
The lpString parameter is a TCHAR buffer, and nMaxCount is the length of the menu string in characters. Sizing these
parameters incorrectly can cause truncation of the string, leading to possible loss of data.
Examples
For an example, see Creating User Editable Accelerators.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenuItemID
Menus
Reference
minutes to read • Edit Online
Retrieves the position of the cursor in physical coordinates.
Syntax
BOOL GetPhysicalCursorPos(
LPPOINT lpPoint
);
Parameters
lpPoint
Type: LPPOINT
The position of the cursor, in physical coordinates.
Return value
Type: BOOL
TRUE if successful; otherwise FALSE .
GetLastError can be called to get more information about any error that is generated.
Remarks
For a description of the difference between logicial coordinates and physical coordinates, see
PhysicalToLogicalPoint.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ClipCursor
Conceptual
Cursors
GetCursorPos
Reference
SetCaretPos
SetCursor
SetCursorPos
SetPhysicalCursorPos
ShowCursor
minutes to read • Edit Online
Retrieves a handle to the drop-down menu or submenu activated by the specified menu item.
Syntax
HMENU GetSubMenu(
HMENU hMenu,
int nPos
);
Parameters
hMenu
Type: HMENU
A handle to the menu.
nPos
Type: int
The zero-based relative position in the specified menu of an item that activates a drop-down menu or submenu.
Return value
Type: HMENU
If the function succeeds, the return value is a handle to the drop-down menu or submenu activated by the menu
item. If the menu item does not activate a drop-down menu or submenu, the return value is NULL .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreatePopupMenu
GetMenu
Menus
Reference
minutes to read • Edit Online
Enables the application to access the window menu (also known as the system menu or the control menu) for
copying and modifying.
Syntax
HMENU GetSystemMenu(
HWND hWnd,
BOOL bRevert
);
Parameters
hWnd
Type: HWND
A handle to the window that will own a copy of the window menu.
bRevert
Type: BOOL
The action to be taken. If this parameter is FALSE , GetSystemMenu returns a 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 value
Type: HMENU
If the bRevert parameter is FALSE , the return value is a handle to a copy of the window menu. If the bRevert
parameter is TRUE , the return value is NULL .
Remarks
Any window that does not use the GetSystemMenu function to make its own copy of the window menu receives
the standard window menu.
The window menu initially contains items with various identifier values, such as SC_CLOSE , SC_MOVE , and
SC_SIZE .
Menu items on the window menu send WM_SYSCOMMAND messages.
All predefined window menu items have identifier numbers greater than 0xF000. If an application adds commands
to the window menu, it should use identifier numbers less than 0xF000.
The system automatically grays items on the standard window menu, depending on the situation. The application
can perform its own checking or graying by responding to the WM_INITMENU message that is sent before any
menu is displayed.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenu
InsertMenuItem
Menus
Reference
SetMenuItemInfo
WM_INITMENU
WM_SYSCOMMAND
minutes to read • Edit Online
Removes the caret from the screen. Hiding a caret does not destroy its current shape or invalidate the insertion
point.
Syntax
BOOL HideCaret(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A 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 value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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.
For an example, see Hiding a Caret.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
CreateCaret
DestroyCaret
GetCaretPos
Reference
SetCaretPos
ShowCaret
minutes to read • Edit Online
Adds or removes highlighting from an item in a menu bar.
Syntax
BOOL HiliteMenuItem(
HWND hWnd,
HMENU hMenu,
UINT uIDHiliteItem,
UINT uHilite
);
Parameters
hWnd
Type: HWND
A handle to the window that contains the menu.
hMenu
Type: HMENU
A handle to the menu bar that contains the item.
uIDHiliteItem
Type: UINT
The menu item. This parameter is either the identifier of the menu item or the offset of the menu item in the menu
bar, depending on the value of the uHilite parameter.
uHilite
Type: UINT
Controls the interpretation of the uItemHilite parameter and indicates whether the menu item is highlighted. This
parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_HILITE or
MF_UNHILITE .
VA L UE
M EA N IN G
Indicates that uItemHilite gives the identifier of the menu item.
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
MF
_BY
PO
SITI
ON
0x0
000
040
0L
MF
_HI
LIT
E
0x0
000
008
0L
Indicates that uItemHilite gives the zero-based relative
position of the menu item.
Highlights the menu item. If this flag is not specified, the
highlighting is removed from the item.
Removes highlighting from the menu item.
MF
_U
NHI
LIT
E
0x0
000
000
0L
Return value
Type: BOOL
If the menu item is set to the specified highlight state, the return value is nonzero.
If the menu item is not set to the specified highlight state, the return value is zero.
Remarks
The MF_HILITE and MF_UNHILITE flags can be used only with the HiliteMenuItem function; they cannot be
used with the ModifyMenu function.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Menus
ModifyMenu
Reference
minutes to read • Edit Online
Contains information about an icon or a cursor.
Syntax
typedef struct _ICONINFO {
BOOL
fIcon;
DWORD xHotspot;
DWORD yHotspot;
HBITMAP hbmMask;
HBITMAP hbmColor;
} ICONINFO;
Members
fIcon
Type: BOOL
Specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; FALSE specifies a
cursor.
xHotspot
Type: DWORD
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
Type: DWORD
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
Type: HBITMAP
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
Type: HBITMAP
A 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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
CreateIconIndirect
GetIconInfo
Icons
Reference
minutes to read • Edit Online
Contains information about an icon or a cursor. Extends ICONINFO. Used by GetIconInfoEx.
Syntax
typedef struct _ICONINFOEXA {
DWORD cbSize;
BOOL
fIcon;
DWORD xHotspot;
DWORD yHotspot;
HBITMAP hbmMask;
HBITMAP hbmColor;
WORD
wResID;
CHAR
szModName[MAX_PATH];
CHAR
szResName[MAX_PATH];
} ICONINFOEXA, *PICONINFOEXA;
Members
cbSize
Type: DWORD
The size, in bytes, of this structure.
fIcon
Type: BOOL
Specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; FALSE specifies a
cursor.
xHotspot
Type: DWORD
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
Type: DWORD
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
Type: HBITMAP
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
Type: HBITMAP
A 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.
wResID
Type: WORD
The icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectoryEx and
LoadResource functions.
szModName
Type: TCHAR[MAX_PATH]
The fully qualified path of the module.
szResName
Type: TCHAR[MAX_PATH]
The fully qualified path of the resource.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
CreateIconIndirect
GetIconInfo
Icons
Reference
minutes to read • Edit Online
Contains information about an icon or a cursor. Extends ICONINFO. Used by GetIconInfoEx.
Syntax
typedef struct _ICONINFOEXW {
DWORD cbSize;
BOOL
fIcon;
DWORD xHotspot;
DWORD yHotspot;
HBITMAP hbmMask;
HBITMAP hbmColor;
WORD
wResID;
WCHAR szModName[MAX_PATH];
WCHAR szResName[MAX_PATH];
} ICONINFOEXW, *PICONINFOEXW;
Members
cbSize
Type: DWORD
The size, in bytes, of this structure.
fIcon
Type: BOOL
Specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; FALSE specifies a
cursor.
xHotspot
Type: DWORD
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
Type: DWORD
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
Type: HBITMAP
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
Type: HBITMAP
A 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.
wResID
Type: WORD
The icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectoryEx and
LoadResource functions.
szModName
Type: TCHAR[MAX_PATH]
The fully qualified path of the module.
szResName
Type: TCHAR[MAX_PATH]
The fully qualified path of the resource.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
CreateIconIndirect
GetIconInfo
Icons
Reference
minutes to read • Edit Online
Contains the scalable metrics associated with icons. This structure is used with the SystemParametersInfo function
when the SPI_GETICONMETRICS or SPI_SETICONMETRICS action is specified.
Syntax
typedef struct tagICONMETRICSA {
UINT
cbSize;
int
iHorzSpacing;
int
iVertSpacing;
int
iTitleWrap;
LOGFONTA lfFont;
} ICONMETRICSA, *PICONMETRICSA, *LPICONMETRICSA;
Members
cbSize
Type: UINT
The size of the structure, in bytes.
iHorzSpacing
Type: int
The horizontal space, in pixels, for each arranged icon.
iVertSpacing
Type: int
The vertical space, in pixels, for each arranged icon.
iTitleWrap
Type: int
If this member is nonzero, icon titles wrap to a new line. If this member is zero, titles do not wrap.
lfFont
Type: LOGFONT
The font to use for icon titles.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
See also
Conceptual
Icons
Other Resources
SystemParametersInfo
winuser.h (include Windows.h)
minutes to read • Edit Online
Contains the scalable metrics associated with icons. This structure is used with the SystemParametersInfo function
when the SPI_GETICONMETRICS or SPI_SETICONMETRICS action is specified.
Syntax
typedef struct tagICONMETRICSW {
UINT
cbSize;
int
iHorzSpacing;
int
iVertSpacing;
int
iTitleWrap;
LOGFONTW lfFont;
} ICONMETRICSW, *PICONMETRICSW, *LPICONMETRICSW;
Members
cbSize
Type: UINT
The size of the structure, in bytes.
iHorzSpacing
Type: int
The horizontal space, in pixels, for each arranged icon.
iVertSpacing
Type: int
The vertical space, in pixels, for each arranged icon.
iTitleWrap
Type: int
If this member is nonzero, icon titles wrap to a new line. If this member is zero, titles do not wrap.
lfFont
Type: LOGFONT
The font to use for icon titles.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
See also
Conceptual
Icons
Other Resources
SystemParametersInfo
winuser.h (include Windows.h)
minutes to read • Edit Online
Inserts a new menu item into a menu, moving other items down the menu.
Note The Inser tMenu function has been superseded by the InsertMenuItem function. You can still use Inser tMenu , however,
if you do not need any of the extended features of Inser tMenuItem .
Syntax
BOOL InsertMenuA(
HMENU
hMenu,
UINT
uPosition,
UINT
uFlags,
UINT_PTR uIDNewItem,
LPCSTR lpNewItem
);
Parameters
hMenu
Type: HMENU
A handle to the menu to be changed.
uPosition
Type: UINT
The menu item before which the new menu item is to be inserted, as determined by the uFlags parameter.
uFlags
Type: UINT
Controls the interpretation of the uPosition parameter and the content, appearance, and behavior of the new menu
item. This parameter must include one of the following required values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
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
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that the uPosition parameter gives the zero-based
relative position of the new menu item. If uPosition is -1, the
new menu item is appended to the end of the menu.
The parameter must also include at least one of the following values.
VA L UE
MF
_BI
TM
AP
0x0
000
000
4L
MF
_CH
ECK
ED
0x0
000
000
8L
MF
_DI
SAB
LED
0x0
000
000
2L
MF
_EN
ABL
ED
0x0
000
000
0L
M EA N IN G
Uses a bitmap as the menu item. The lpNewItem parameter
contains a handle to the bitmap.
Places a check mark next to the menu item. If the application
provides check-mark bitmaps (see SetMenuItemBitmaps), this
flag displays the check-mark bitmap next to the menu item.
Disables the menu item so that it cannot be selected, but does
not gray it.
Enables the menu item so that it can be selected and restores
it from its grayed state.
Disables the menu item and grays it so it cannot be selected.
MF
_GR
AYE
D
0x0
000
000
1L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
MF
_PO
PU
P
0x0
000
001
0L
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.
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.
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.
Specifies that the menu item opens a drop-down menu or
submenu. The uIDNewItem parameter specifies a 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.
MF
_SE
PAR
ATO
R
0x0
000
080
0L
MF
_ST
RIN
G
0x0
000
000
0L
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
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.
Specifies that the menu item is a text string; the lpNewItem
parameter is a pointer to the string.
Does not place a check mark next to the menu item (default).
If the application supplies check-mark bitmaps (see the
SetMenuItemBitmaps function), this flag displays the clear
bitmap next to the menu item.
uIDNewItem
Type: UINT_PTR
The identifier of the new menu item or, if the uFlags parameter has the MF_POPUP flag set, a handle to the dropdown menu or submenu.
lpNewItem
Type: LPCTSTR
The content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter
includes the MF_BITMAP , MF_OWNERDRAW , or MF_STRING flag, as follows.
VA L UE
M EA N IN G
Contains a bitmap handle.
MF
_BI
TM
AP
0x0
000
000
4L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Contains an application-supplied value 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.
Contains a pointer to a null-terminated string (the default).
MF
_ST
RIN
G
0x0
000
000
0L
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
The following groups of flags cannot be used together:
MF_BYCOMMAND and MF_BYPOSITION
MF_DISABLED , MF_ENABLED , and MF_GRAYED
MF_BITMAP , MF_STRING , MF_OWNERDRAW , and MF_SEPARATOR
MF_MENUBARBREAK and MF_MENUBREAK
MF_CHECKED and MF_UNCHECKED
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
See also
AppendMenu
Conceptual
DeleteMenu
DrawMenuBar
InsertMenuItem
Menus
ModifyMenu
Other Resources
Reference
RemoveMenu
SetMenuItemBitmaps
WM_DRAWITEM
WM_MEASUREITEM
User32.dll
minutes to read • Edit Online
Inserts a new menu item at the specified position in a menu.
Syntax
BOOL InsertMenuItemA(
HMENU
hmenu,
UINT
item,
BOOL
fByPosition,
LPCMENUITEMINFOA lpmi
);
Parameters
hmenu
Type: HMENU
A handle to the menu in which the new menu item is inserted.
item
Type: UINT
The identifier or position of the menu item before which to insert the new item. The meaning of this parameter
depends on the value of fByPosition.
fByPosition
Type: BOOL
Controls the meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu
item position. See Accessing Menu Items Programmatically for more information.
lpmi
Type: LPCMENUITEMINFO
A pointer to a MENUITEMINFO structure that contains information about the new menu item.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
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. See Owner-Drawn Menus and the WM_MENUCHAR Message for more
information.
Examples
For an example, see Example of Menu-Item Bitmaps.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DrawMenuBar
MENUITEMINFO
Menus
Reference
minutes to read • Edit Online
Inserts a new menu item at the specified position in a menu.
Syntax
BOOL InsertMenuItemW(
HMENU
hmenu,
UINT
item,
BOOL
fByPosition,
LPCMENUITEMINFOW lpmi
);
Parameters
hmenu
Type: HMENU
A handle to the menu in which the new menu item is inserted.
item
Type: UINT
The identifier or position of the menu item before which to insert the new item. The meaning of this parameter
depends on the value of fByPosition.
fByPosition
Type: BOOL
Controls the meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu
item position. See Accessing Menu Items Programmatically for more information.
lpmi
Type: LPCMENUITEMINFO
A pointer to a MENUITEMINFO structure that contains information about the new menu item.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
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. See Owner-Drawn Menus and the WM_MENUCHAR Message for more
information.
Examples
For an example, see Example of Menu-Item Bitmaps.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DrawMenuBar
MENUITEMINFO
Menus
Reference
minutes to read • Edit Online
Inserts a new menu item into a menu, moving other items down the menu.
Note The Inser tMenu function has been superseded by the InsertMenuItem function. You can still use Inser tMenu , however,
if you do not need any of the extended features of Inser tMenuItem .
Syntax
BOOL InsertMenuW(
HMENU
hMenu,
UINT
uPosition,
UINT
uFlags,
UINT_PTR uIDNewItem,
LPCWSTR lpNewItem
);
Parameters
hMenu
Type: HMENU
A handle to the menu to be changed.
uPosition
Type: UINT
The menu item before which the new menu item is to be inserted, as determined by the uFlags parameter.
uFlags
Type: UINT
Controls the interpretation of the uPosition parameter and the content, appearance, and behavior of the new menu
item. This parameter must include one of the following required values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
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
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that the uPosition parameter gives the zero-based
relative position of the new menu item. If uPosition is -1, the
new menu item is appended to the end of the menu.
The parameter must also include at least one of the following values.
VA L UE
MF
_BI
TM
AP
0x0
000
000
4L
MF
_CH
ECK
ED
0x0
000
000
8L
MF
_DI
SAB
LED
0x0
000
000
2L
MF
_EN
ABL
ED
0x0
000
000
0L
M EA N IN G
Uses a bitmap as the menu item. The lpNewItem parameter
contains a handle to the bitmap.
Places a check mark next to the menu item. If the application
provides check-mark bitmaps (see SetMenuItemBitmaps), this
flag displays the check-mark bitmap next to the menu item.
Disables the menu item so that it cannot be selected, but does
not gray it.
Enables the menu item so that it can be selected and restores
it from its grayed state.
Disables the menu item and grays it so it cannot be selected.
MF
_GR
AYE
D
0x0
000
000
1L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
MF
_PO
PU
P
0x0
000
001
0L
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.
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.
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.
Specifies that the menu item opens a drop-down menu or
submenu. The uIDNewItem parameter specifies a 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.
MF
_SE
PAR
ATO
R
0x0
000
080
0L
MF
_ST
RIN
G
0x0
000
000
0L
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
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.
Specifies that the menu item is a text string; the lpNewItem
parameter is a pointer to the string.
Does not place a check mark next to the menu item (default).
If the application supplies check-mark bitmaps (see the
SetMenuItemBitmaps function), this flag displays the clear
bitmap next to the menu item.
uIDNewItem
Type: UINT_PTR
The identifier of the new menu item or, if the uFlags parameter has the MF_POPUP flag set, a handle to the dropdown menu or submenu.
lpNewItem
Type: LPCTSTR
The content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter
includes the MF_BITMAP , MF_OWNERDRAW , or MF_STRING flag, as follows.
VA L UE
M EA N IN G
Contains a bitmap handle.
MF
_BI
TM
AP
0x0
000
000
4L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Contains an application-supplied value 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.
Contains a pointer to a null-terminated string (the default).
MF
_ST
RIN
G
0x0
000
000
0L
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
The following groups of flags cannot be used together:
MF_BYCOMMAND and MF_BYPOSITION
MF_DISABLED , MF_ENABLED , and MF_GRAYED
MF_BITMAP , MF_STRING , MF_OWNERDRAW , and MF_SEPARATOR
MF_MENUBARBREAK and MF_MENUBREAK
MF_CHECKED and MF_UNCHECKED
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
See also
AppendMenu
Conceptual
DeleteMenu
DrawMenuBar
InsertMenuItem
Menus
ModifyMenu
Other Resources
Reference
RemoveMenu
SetMenuItemBitmaps
WM_DRAWITEM
WM_MEASUREITEM
User32.dll
minutes to read • Edit Online
Determines whether a value is an integer identifier for a resource.
Syntax
void IS_INTRESOURCE(
_r
);
Parameters
_r
The pointer to be tested whether it contains an integer resource identifier.
Return value
None
Remarks
This macro checks whether all bits except the least 16 bits are zero. When true, p is an integer identifier for a
resource. Otherwise it is typically a pointer to a string.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
See also
Resources Overview
minutes to read • Edit Online
Determines whether a character is an alphabetical character. This determination is based on the semantics of the
language selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharAlphaA(
CHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is alphabetical, the return value is nonzero.
If the character is not alphabetical, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharAlphaNumeric
Reference
Strings
minutes to read • Edit Online
Determines whether a character is either an alphabetical or a numeric character. This determination is based on the
semantics of the language selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharAlphaNumericA(
CHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is alphanumeric, the return value is nonzero.
If the character is not alphanumeric, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharAlpha
Reference
Strings
minutes to read • Edit Online
Determines whether a character is either an alphabetical or a numeric character. This determination is based on the
semantics of the language selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharAlphaNumericW(
WCHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is alphanumeric, the return value is nonzero.
If the character is not alphanumeric, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharAlpha
Reference
Strings
minutes to read • Edit Online
Determines whether a character is an alphabetical character. This determination is based on the semantics of the
language selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharAlphaW(
WCHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is alphabetical, the return value is nonzero.
If the character is not alphabetical, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharAlphaNumeric
Reference
Strings
minutes to read • Edit Online
Determines whether a character is lowercase. This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharLowerA(
CHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is lowercase, the return value is nonzero.
If the character is not lowercase, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharUpper
Reference
Strings
minutes to read • Edit Online
Determines whether a character is uppercase. This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharUpperA(
CHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is uppercase, the return value is nonzero.
If the character is not uppercase, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharLower
Reference
Strings
minutes to read • Edit Online
Determines whether a character is uppercase. This determination is based on the semantics of the language
selected by the user during setup or through Control Panel.
Syntax
BOOL IsCharUpperW(
WCHAR ch
);
Parameters
ch
Type: TCHAR
The character to be tested.
Return value
Type: BOOL
If the character is uppercase, the return value is nonzero.
If the character is not uppercase, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
IsCharLower
Reference
Strings
minutes to read • Edit Online
Determines whether a handle is a menu handle.
Syntax
BOOL IsMenu(
HMENU hMenu
);
Parameters
hMenu
Type: HMENU
A handle to be tested.
Return value
Type: BOOL
If the handle is a menu handle, the return value is nonzero.
If the handle is not a menu handle, the return value is zero.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Menus
minutes to read • Edit Online
Loads the specified accelerator table.
Syntax
HACCEL LoadAcceleratorsA(
HINSTANCE hInstance,
LPCSTR
lpTableName
);
Parameters
hInstance
Type: HINSTANCE
A handle to the module whose executable file contains the accelerator table to be loaded.
lpTableName
Type: LPCTSTR
The name of the accelerator table to be loaded. 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. To create this value, use the
MAKEINTRESOURCE macro.
Return value
Type: HACCEL
If the function succeeds, the return value is a handle to the loaded accelerator table.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
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.
Examples
For an example, see Creating Accelerators for Font Attributes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyAcceleratorTable
CreateAcceleratorTable
DestroyAcceleratorTable
Keyboard Accelerators
MAKEINTRESOURCE
Reference
minutes to read • Edit Online
Loads the specified accelerator table.
Syntax
HACCEL LoadAcceleratorsW(
HINSTANCE hInstance,
LPCWSTR lpTableName
);
Parameters
hInstance
Type: HINSTANCE
A handle to the module whose executable file contains the accelerator table to be loaded.
lpTableName
Type: LPCTSTR
The name of the accelerator table to be loaded. 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. To create this value, use the
MAKEINTRESOURCE macro.
Return value
Type: HACCEL
If the function succeeds, the return value is a handle to the loaded accelerator table.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
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.
Examples
For an example, see Creating Accelerators for Font Attributes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyAcceleratorTable
CreateAcceleratorTable
DestroyAcceleratorTable
Keyboard Accelerators
MAKEINTRESOURCE
Reference
minutes to read • Edit Online
Loads the specified cursor resource from the executable (.EXE) file associated with an application instance.
Note This function has been superseded by the LoadImage function.
Syntax
HCURSOR LoadCursorA(
HINSTANCE hInstance,
LPCSTR
lpCursorName
);
Parameters
hInstance
Type: HINSTANCE
A handle to an instance of the module whose executable file contains the cursor to be loaded.
lpCursorName
Type: LPCTSTR
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 predefined cursors, the application must set the hInstance parameter to NULL and the
lpCursorName parameter to one the following values.
VA L UE
M EA N IN G
Standard arrow and small hourglass
IDC
_AP
PST
ART
ING
MA
KEI
NTR
ESO
URC
E(32
650)
Standard arrow
IDC
_AR
RO
W
MA
KEI
NTR
ESO
URC
E(32
512)
Crosshair
IDC
_CR
OSS
MA
KEI
NTR
ESO
URC
E(32
515)
Hand
IDC
_HA
ND
MA
KEI
NTR
ESO
URC
E(32
649)
Arrow and question mark
IDC
_HE
LP
MA
KEI
NTR
ESO
URC
E(32
651)
I-beam
IDC
_IB
EA
M
MA
KEI
NTR
ESO
URC
E(32
513)
Obsolete for applications marked version 4.0 or later.
IDC
_IC
ON
MA
KEI
NTR
ESO
URC
E(32
641)
Slashed circle
IDC
_N
O
MA
KEI
NTR
ESO
URC
E(32
648)
IDC
_SI
ZE
MA
KEI
NTR
ESO
URC
E(32
640)
Obsolete for applications marked version 4.0 or later. Use
IDC_SIZEALL .
Four-pointed arrow pointing north, south, east, and west
IDC
_SI
ZEA
LL
MA
KEI
NTR
ESO
URC
E(32
646)
Double-pointed arrow pointing northeast and southwest
IDC
_SI
ZEN
ES
W
MA
KEI
NTR
ESO
URC
E(32
643)
Double-pointed arrow pointing north and south
IDC
_SI
ZEN
S
MA
KEI
NTR
ESO
URC
E(32
645)
Double-pointed arrow pointing northwest and southeast
IDC
_SI
ZEN
WS
E
MA
KEI
NTR
ESO
URC
E(32
642)
Double-pointed arrow pointing west and east
IDC
_SI
ZE
WE
MA
KEI
NTR
ESO
URC
E(32
644)
Vertical arrow
IDC
_UP
ARR
OW
MA
KEI
NTR
ESO
URC
E(32
516)
Hourglass
IDC
_W
AIT
MA
KEI
NTR
ESO
URC
E(32
514)
Return value
Type: HCURSOR
If the function succeeds, the return value is the handle to the newly loaded cursor.
If the function fails, the return value is NULL . 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 is a pointer
to a cursor resource. If lpCursorName is a pointer 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.
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Examples
For an example, see Creating a Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
LoadImage
MAKEINTRESOURCE
Reference
SetCursor
SetCursorPos
ShowCursor
minutes to read • Edit Online
Creates a cursor based on data contained in a file.
Syntax
HCURSOR LoadCursorFromFileA(
LPCSTR lpFileName
);
Parameters
lpFileName
Type: LPCTSTR
The source of the file data to be used to create the cursor. The data in the file must be in either .CUR or .ANI format.
If the high-order word of lpFileName is nonzero, it is a pointer to a string that is a fully qualified name of a file
containing cursor data.
Return value
Type: HCURSOR
If the function is successful, the return value is a handle to the new cursor.
If the function fails, the return value is NULL . To get extended error information, call GetLastError. GetLastError
may return the following value.
RET URN C O DE
DESC RIP T IO N
The specified file cannot be found.
ERR
OR_
FIL
E_N
OT_
FO
UN
D
Remarks
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
LoadCursor
Reference
SetCursor
SetSystemCursor
minutes to read • Edit Online
Creates a cursor based on data contained in a file.
Syntax
HCURSOR LoadCursorFromFileW(
LPCWSTR lpFileName
);
Parameters
lpFileName
Type: LPCTSTR
The source of the file data to be used to create the cursor. The data in the file must be in either .CUR or .ANI format.
If the high-order word of lpFileName is nonzero, it is a pointer to a string that is a fully qualified name of a file
containing cursor data.
Return value
Type: HCURSOR
If the function is successful, the return value is a handle to the new cursor.
If the function fails, the return value is NULL . To get extended error information, call GetLastError. GetLastError
may return the following value.
RET URN C O DE
DESC RIP T IO N
The specified file cannot be found.
ERR
OR_
FIL
E_N
OT_
FO
UN
D
Remarks
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
LoadCursor
Reference
SetCursor
SetSystemCursor
minutes to read • Edit Online
Loads the specified cursor resource from the executable (.EXE) file associated with an application instance.
Note This function has been superseded by the LoadImage function.
Syntax
HCURSOR LoadCursorW(
HINSTANCE hInstance,
LPCWSTR lpCursorName
);
Parameters
hInstance
Type: HINSTANCE
A handle to an instance of the module whose executable file contains the cursor to be loaded.
lpCursorName
Type: LPCTSTR
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 predefined cursors, the application must set the hInstance parameter to NULL and the
lpCursorName parameter to one the following values.
VA L UE
M EA N IN G
Standard arrow and small hourglass
IDC
_AP
PST
ART
ING
MA
KEI
NTR
ESO
URC
E(32
650)
Standard arrow
IDC
_AR
RO
W
MA
KEI
NTR
ESO
URC
E(32
512)
Crosshair
IDC
_CR
OSS
MA
KEI
NTR
ESO
URC
E(32
515)
Hand
IDC
_HA
ND
MA
KEI
NTR
ESO
URC
E(32
649)
Arrow and question mark
IDC
_HE
LP
MA
KEI
NTR
ESO
URC
E(32
651)
I-beam
IDC
_IB
EA
M
MA
KEI
NTR
ESO
URC
E(32
513)
Obsolete for applications marked version 4.0 or later.
IDC
_IC
ON
MA
KEI
NTR
ESO
URC
E(32
641)
Slashed circle
IDC
_N
O
MA
KEI
NTR
ESO
URC
E(32
648)
IDC
_SI
ZE
MA
KEI
NTR
ESO
URC
E(32
640)
Obsolete for applications marked version 4.0 or later. Use
IDC_SIZEALL .
Four-pointed arrow pointing north, south, east, and west
IDC
_SI
ZEA
LL
MA
KEI
NTR
ESO
URC
E(32
646)
Double-pointed arrow pointing northeast and southwest
IDC
_SI
ZEN
ES
W
MA
KEI
NTR
ESO
URC
E(32
643)
Double-pointed arrow pointing north and south
IDC
_SI
ZEN
S
MA
KEI
NTR
ESO
URC
E(32
645)
Double-pointed arrow pointing northwest and southeast
IDC
_SI
ZEN
WS
E
MA
KEI
NTR
ESO
URC
E(32
642)
Double-pointed arrow pointing west and east
IDC
_SI
ZE
WE
MA
KEI
NTR
ESO
URC
E(32
644)
Vertical arrow
IDC
_UP
ARR
OW
MA
KEI
NTR
ESO
URC
E(32
516)
Hourglass
IDC
_W
AIT
MA
KEI
NTR
ESO
URC
E(32
514)
Return value
Type: HCURSOR
If the function succeeds, the return value is the handle to the newly loaded cursor.
If the function fails, the return value is NULL . 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 is a pointer
to a cursor resource. If lpCursorName is a pointer 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.
DPI Virtualization
This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.
Examples
For an example, see Creating a Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
LoadImage
MAKEINTRESOURCE
Reference
SetCursor
SetCursorPos
ShowCursor
minutes to read • Edit Online
Loads the specified icon resource from the executable (.exe) file associated with an application instance.
Note This function has been superseded by the LoadImage function.
Syntax
HICON LoadIconA(
HINSTANCE hInstance,
LPCSTR
lpIconName
);
Parameters
hInstance
Type: HINSTANCE
A 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
Type: LPCTSTR
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.
To use one of the predefined icons, set the hInstance parameter to NULL and the lpIconName parameter to one of
the following values.
VA L UE
M EA N IN G
Default application icon.
IDI_
APP
LIC
ATI
ON
MA
KEI
NTR
ESO
URC
E(32
512)
Asterisk icon. Same as IDI_INFORMATION.
IDI_
AST
ERI
SK
MA
KEI
NTR
ESO
URC
E(32
516)
Hand-shaped icon.
IDI_
ERR
OR
MA
KEI
NTR
ESO
URC
E(32
513)
Exclamation point icon. Same as IDI_WARNING .
IDI_
EXC
LA
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
515)
Hand-shaped icon. Same as IDI_ERROR.
IDI_
HA
ND
MA
KEI
NTR
ESO
URC
E(32
513)
Asterisk icon.
IDI_
INF
OR
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
516)
Question mark icon.
IDI_
QU
EST
ION
MA
KEI
NTR
ESO
URC
E(32
514)
Security Shield icon.
IDI_
SHI
ELD
MA
KEI
NTR
ESO
URC
E(32
518)
Exclamation point icon.
IDI_
WA
RNI
NG
MA
KEI
NTR
ESO
URC
E(32
515)
IDI_
WI
NL
OG
O
MA
KEI
NTR
ESO
URC
E(32
517)
Default application icon.
Windows 2000: Windows logo icon.
Return value
Type: HICON
If the function succeeds, the return value is a handle to the newly loaded icon.
If the function fails, the return value is NULL . 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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
Icons
LoadImage
MAKEINTRESOURCE
Reference
minutes to read • Edit Online
Loads the specified icon resource from the executable (.exe) file associated with an application instance.
Note This function has been superseded by the LoadImage function.
Syntax
HICON LoadIconW(
HINSTANCE hInstance,
LPCWSTR lpIconName
);
Parameters
hInstance
Type: HINSTANCE
A 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
Type: LPCTSTR
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.
To use one of the predefined icons, set the hInstance parameter to NULL and the lpIconName parameter to one of
the following values.
VA L UE
M EA N IN G
Default application icon.
IDI_
APP
LIC
ATI
ON
MA
KEI
NTR
ESO
URC
E(32
512)
Asterisk icon. Same as IDI_INFORMATION.
IDI_
AST
ERI
SK
MA
KEI
NTR
ESO
URC
E(32
516)
Hand-shaped icon.
IDI_
ERR
OR
MA
KEI
NTR
ESO
URC
E(32
513)
Exclamation point icon. Same as IDI_WARNING .
IDI_
EXC
LA
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
515)
Hand-shaped icon. Same as IDI_ERROR.
IDI_
HA
ND
MA
KEI
NTR
ESO
URC
E(32
513)
Asterisk icon.
IDI_
INF
OR
MA
TIO
N
MA
KEI
NTR
ESO
URC
E(32
516)
Question mark icon.
IDI_
QU
EST
ION
MA
KEI
NTR
ESO
URC
E(32
514)
Security Shield icon.
IDI_
SHI
ELD
MA
KEI
NTR
ESO
URC
E(32
518)
Exclamation point icon.
IDI_
WA
RNI
NG
MA
KEI
NTR
ESO
URC
E(32
515)
IDI_
WI
NL
OG
O
MA
KEI
NTR
ESO
URC
E(32
517)
Default application icon.
Windows 2000: Windows logo icon.
Return value
Type: HICON
If the function succeeds, the return value is a handle to the newly loaded icon.
If the function fails, the return value is NULL . 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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIcon
Icons
LoadImage
MAKEINTRESOURCE
Reference
minutes to read • Edit Online
Loads an icon, cursor, animated cursor, or bitmap.
Syntax
HANDLE LoadImageA(
HINSTANCE hInst,
LPCSTR
name,
UINT
type,
int
cx,
int
cy,
UINT
fuLoad
);
Parameters
hInst
Type: HINSTANCE
A handle to the module of either a DLL or executable (.exe) that contains the image to be loaded. For more
information, see GetModuleHandle. Note that as of 32-bit Windows, an instance handle (HINSTANCE ), such as the
application instance handle exposed by system function call of WinMain, and a module handle (HMODULE ) are the
same thing.
To load an OEM image, set this parameter to NULL .
To load a stand-alone resource (icon, cursor, or bitmap file)—for example, c:\myimage.bmp—set this parameter to
NULL .
name
Type: LPCTSTR
The image to be loaded. If the hinst parameter is non-NULL and the fuLoad parameter omits
LR_LOADFROMFILE , lpszName specifies the image resource in the hinst module. If the image resource is to be
loaded by name from the module, the lpszName parameter is a pointer to a null-terminated string that contains the
name of the image resource. If the image resource is to be loaded by ordinal from the module, use the
MAKEINTRESOURCE macro to convert the image ordinal into a form that can be passed to the LoadImage
function.
For more information, see the Remarks section below.
If the hinst parameter is NULL and the fuLoad parameter omits the LR_LOADFROMFILE value, the lpszName
specifies the OEM image to load. The OEM image identifiers are defined in Winuser.h and have the following
prefixes.
P REF IX
M EA N IN G
OBM_
OEM bitmaps
OIC_
OEM icons
OCR_
OEM cursors
To pass these constants to the LoadImage function, use the MAKEINTRESOURCE macro. For example, to load the
OCR_NORMAL cursor, pass MAKEINTRESOURCE(OCR_NORMAL) as the lpszName parameter, NULL as the hinst
parameter, and LR_SHARED as one of the flags to the fuLoad parameter.
If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName is the name of the file that contains the
stand-alone resource (icon, cursor, or bitmap file). Therefore, set hinst to NULL .
type
Type: UINT
The type of image to be loaded. This parameter can be one of the following values.
VA L UE
M EA N IN G
Loads a bitmap.
IM
AG
E_B
ITM
AP
0
Loads a cursor.
IM
AG
E_C
URS
OR
2
Loads an icon.
IM
AG
E_I
CO
N
1
cx
Type: int
The width, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE ,
the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If this parameter is
zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.
cy
Type: int
The height, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE ,
the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height. If this parameter is
zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.
fuLoad
Type: UINT
This parameter can be one or more of the following values.
VA L UE
LR_
CRE
ATE
DIB
SEC
TIO
N
0x0
000
200
0
LR_
DEF
AU
LTC
OL
OR
0x0
000
000
0
LR_
DEF
AU
LTSI
ZE
0x0
000
004
0
LR_
LO
AD
FR
OM
FIL
E
0x0
000
001
0
M EA N IN G
When the uType parameter specifies IMAGE_BITMAP , causes
the function to return a DIB section bitmap rather than a
compatible bitmap. This flag is useful for loading a bitmap
without mapping it to the colors of the display device.
The default flag; it does nothing. All it means is "not
LR_MONOCHROME ".
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 this flag is not specified and cxDesired and
cyDesired are set to zero, the function uses the actual resource
size. If the resource contains multiple images, the function
uses the size of the first image.
Loads the stand-alone image from the file specified by
lpszName (icon, cursor, or bitmap file).
LR_
LO
AD
MA
P3
DC
OL
OR
S
0x0
000
100
0
LR_
LO
ADT
RA
NSP
ARE
NT
0x0
000
002
0
Searches the color table for the image and replaces the
following shades of gray with the corresponding 3-D color.
Dk Gray, RGB(128,128,128) with
COLOR_3DSHADOW
Gray, RGB(192,192,192) with COLOR_3DFACE
Lt Gray, RGB(223,223,223) with COLOR_3DLIGHT
Do not use this option if you are loading a bitmap with a color
depth greater than 8bpp.
Retrieves the color value of the first pixel in the image and
replaces the corresponding entry in the color table with the
default window color (COLOR_WINDOW ). All pixels in the
image that use that entry become the default window color.
This value applies only to images that have corresponding
color tables.
Do not use this option if you are loading a bitmap with a
color depth greater than 8bpp.
If fuLoad includes both the LR_LOADTRANSPARENT and
LR_LOADMAP3DCOLORS values,
LR_LOADTRANSPARENT takes precedence. However,
the color table entry is replaced with COLOR_3DFACE
rather than COLOR_WINDOW .
Loads the image in black and white.
LR_
MO
NO
CH
RO
ME
0x0
000
000
1
LR_
SH
ARE
D
0x0
000
800
0
Shares the image handle if the image is loaded multiple times.
If LR_SHARED is not set, a second call to LoadImage for the
same resource will load the image again and return a different
handle.
When you use this flag, the system will destroy the
resource when it is no longer needed.
Do not use LR_SHARED for images that have nonstandard sizes, that may change after loading, or that are
loaded from a file.
When loading a system icon or cursor, you must use
LR_SHARED or the function will fail to load the resource.
This function finds the first image in the cache with the
requested resource name, regardless of the size requested.
Uses true VGA colors.
LR_
VG
AC
OL
OR
0x0
000
008
0
Return value
Type: HANDLE
If the function succeeds, the return value is the handle of the newly loaded image.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpszName) is TRUE , then lpszName specifies the integer identifier of the given resource.
Otherwise, it is a pointer to a nullterminated string. If the first character of the string is a pound sign (#), then the remaining characters represent a
decimal number that specifies the
integer identifier of the resource. For example, the string "#258" represents the identifier 258.
When you are finished using a bitmap, cursor, or icon you loaded without specifying the LR_SHARED flag, you can
release its associated memory by calling one of the functions in the following table.
RESO URC E
REL EA SE F UN C T IO N
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.
Examples
For an example, see Using Window Classes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyImage
GetSystemMetrics
LoadBitmap
LoadCursor
LoadIcon
Other Resources
Reference
Resources
minutes to read • Edit Online
Loads an icon, cursor, animated cursor, or bitmap.
Syntax
HANDLE LoadImageW(
HINSTANCE hInst,
LPCWSTR name,
UINT
type,
int
cx,
int
cy,
UINT
fuLoad
);
Parameters
hInst
Type: HINSTANCE
A handle to the module of either a DLL or executable (.exe) that contains the image to be loaded. For more
information, see GetModuleHandle. Note that as of 32-bit Windows, an instance handle (HINSTANCE ), such as the
application instance handle exposed by system function call of WinMain, and a module handle (HMODULE ) are the
same thing.
To load an OEM image, set this parameter to NULL .
To load a stand-alone resource (icon, cursor, or bitmap file)—for example, c:\myimage.bmp—set this parameter to
NULL .
name
Type: LPCTSTR
The image to be loaded. If the hinst parameter is non-NULL and the fuLoad parameter omits
LR_LOADFROMFILE , lpszName specifies the image resource in the hinst module. If the image resource is to be
loaded by name from the module, the lpszName parameter is a pointer to a null-terminated string that contains the
name of the image resource. If the image resource is to be loaded by ordinal from the module, use the
MAKEINTRESOURCE macro to convert the image ordinal into a form that can be passed to the LoadImage
function.
For more information, see the Remarks section below.
If the hinst parameter is NULL and the fuLoad parameter omits the LR_LOADFROMFILE value, the lpszName
specifies the OEM image to load. The OEM image identifiers are defined in Winuser.h and have the following
prefixes.
P REF IX
M EA N IN G
OBM_
OEM bitmaps
OIC_
OEM icons
OCR_
OEM cursors
To pass these constants to the LoadImage function, use the MAKEINTRESOURCE macro. For example, to load the
OCR_NORMAL cursor, pass MAKEINTRESOURCE(OCR_NORMAL) as the lpszName parameter, NULL as the hinst
parameter, and LR_SHARED as one of the flags to the fuLoad parameter.
If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName is the name of the file that contains the
stand-alone resource (icon, cursor, or bitmap file). Therefore, set hinst to NULL .
type
Type: UINT
The type of image to be loaded. This parameter can be one of the following values.
VA L UE
M EA N IN G
Loads a bitmap.
IM
AG
E_B
ITM
AP
0
Loads a cursor.
IM
AG
E_C
URS
OR
2
Loads an icon.
IM
AG
E_I
CO
N
1
cx
Type: int
The width, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE ,
the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If this parameter is
zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.
cy
Type: int
The height, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE ,
the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height. If this parameter is
zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.
fuLoad
Type: UINT
This parameter can be one or more of the following values.
VA L UE
LR_
CRE
ATE
DIB
SEC
TIO
N
0x0
000
200
0
LR_
DEF
AU
LTC
OL
OR
0x0
000
000
0
LR_
DEF
AU
LTSI
ZE
0x0
000
004
0
LR_
LO
AD
FR
OM
FIL
E
0x0
000
001
0
M EA N IN G
When the uType parameter specifies IMAGE_BITMAP , causes
the function to return a DIB section bitmap rather than a
compatible bitmap. This flag is useful for loading a bitmap
without mapping it to the colors of the display device.
The default flag; it does nothing. All it means is "not
LR_MONOCHROME ".
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 this flag is not specified and cxDesired and
cyDesired are set to zero, the function uses the actual resource
size. If the resource contains multiple images, the function
uses the size of the first image.
Loads the stand-alone image from the file specified by
lpszName (icon, cursor, or bitmap file).
LR_
LO
AD
MA
P3
DC
OL
OR
S
0x0
000
100
0
LR_
LO
ADT
RA
NSP
ARE
NT
0x0
000
002
0
Searches the color table for the image and replaces the
following shades of gray with the corresponding 3-D color.
Dk Gray, RGB(128,128,128) with
COLOR_3DSHADOW
Gray, RGB(192,192,192) with COLOR_3DFACE
Lt Gray, RGB(223,223,223) with COLOR_3DLIGHT
Do not use this option if you are loading a bitmap with a color
depth greater than 8bpp.
Retrieves the color value of the first pixel in the image and
replaces the corresponding entry in the color table with the
default window color (COLOR_WINDOW ). All pixels in the
image that use that entry become the default window color.
This value applies only to images that have corresponding
color tables.
Do not use this option if you are loading a bitmap with a
color depth greater than 8bpp.
If fuLoad includes both the LR_LOADTRANSPARENT and
LR_LOADMAP3DCOLORS values,
LR_LOADTRANSPARENT takes precedence. However,
the color table entry is replaced with COLOR_3DFACE
rather than COLOR_WINDOW .
Loads the image in black and white.
LR_
MO
NO
CH
RO
ME
0x0
000
000
1
LR_
SH
ARE
D
0x0
000
800
0
Shares the image handle if the image is loaded multiple times.
If LR_SHARED is not set, a second call to LoadImage for the
same resource will load the image again and return a different
handle.
When you use this flag, the system will destroy the
resource when it is no longer needed.
Do not use LR_SHARED for images that have nonstandard sizes, that may change after loading, or that are
loaded from a file.
When loading a system icon or cursor, you must use
LR_SHARED or the function will fail to load the resource.
This function finds the first image in the cache with the
requested resource name, regardless of the size requested.
Uses true VGA colors.
LR_
VG
AC
OL
OR
0x0
000
008
0
Return value
Type: HANDLE
If the function succeeds, the return value is the handle of the newly loaded image.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
If IS_INTRESOURCE(lpszName) is TRUE , then lpszName specifies the integer identifier of the given resource.
Otherwise, it is a pointer to a nullterminated string. If the first character of the string is a pound sign (#), then the remaining characters represent a
decimal number that specifies the
integer identifier of the resource. For example, the string "#258" represents the identifier 258.
When you are finished using a bitmap, cursor, or icon you loaded without specifying the LR_SHARED flag, you can
release its associated memory by calling one of the functions in the following table.
RESO URC E
REL EA SE F UN C T IO N
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.
Examples
For an example, see Using Window Classes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CopyImage
GetSystemMetrics
LoadBitmap
LoadCursor
LoadIcon
Other Resources
Reference
Resources
minutes to read • Edit Online
Loads the specified menu resource from the executable (.exe) file associated with an application instance.
Syntax
HMENU LoadMenuA(
HINSTANCE hInstance,
LPCSTR
lpMenuName
);
Parameters
hInstance
Type: HINSTANCE
A handle to the module containing the menu resource to be loaded.
lpMenuName
Type: LPCTSTR
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 value
Type: HMENU
If the function succeeds, the return value is a handle to the menu resource.
If the function fails, the return value is NULL . 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.
Examples
For an example, see Displaying a Shortcut Menu
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
LoadMenuIndirect
MAKEINTRESOURCE
Menus
Reference
minutes to read • Edit Online
Loads the specified menu template in memory.
Syntax
HMENU LoadMenuIndirectA(
const MENUTEMPLATEA *lpMenuTemplate
);
Parameters
lpMenuTemplate
Type: const MENUTEMPL ATE*
A pointer to a menu template or an extended menu template. A menu template consists of a
MENUITEMTEMPLATEHEADER structure followed by one or more contiguous MENUITEMTEMPLATE structures. An
extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous
MENUEX_TEMPLATE_ITEM structures.
Return value
Type: HMENU
If the function succeeds, the return value is a handle to the menu.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
For both the ANSI and the Unicode version of this function, the strings in the MENUITEMTEMPLATE structure must
be Unicode strings.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
LoadMenu
MENUEX_TEMPLATE_HEADER
MENUEX_TEMPLATE_ITEM
MENUITEMTEMPLATE
MENUITEMTEMPLATEHEADER
Menus
Reference
minutes to read • Edit Online
Loads the specified menu template in memory.
Syntax
HMENU LoadMenuIndirectW(
const MENUTEMPLATEW *lpMenuTemplate
);
Parameters
lpMenuTemplate
Type: const MENUTEMPL ATE*
A pointer to a menu template or an extended menu template. A menu template consists of a
MENUITEMTEMPLATEHEADER structure followed by one or more contiguous MENUITEMTEMPLATE structures. An
extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous
MENUEX_TEMPLATE_ITEM structures.
Return value
Type: HMENU
If the function succeeds, the return value is a handle to the menu.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
For both the ANSI and the Unicode version of this function, the strings in the MENUITEMTEMPLATE structure must
be Unicode strings.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
LoadMenu
MENUEX_TEMPLATE_HEADER
MENUEX_TEMPLATE_ITEM
MENUITEMTEMPLATE
MENUITEMTEMPLATEHEADER
Menus
Reference
minutes to read • Edit Online
Loads the specified menu resource from the executable (.exe) file associated with an application instance.
Syntax
HMENU LoadMenuW(
HINSTANCE hInstance,
LPCWSTR lpMenuName
);
Parameters
hInstance
Type: HINSTANCE
A handle to the module containing the menu resource to be loaded.
lpMenuName
Type: LPCTSTR
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 value
Type: HMENU
If the function succeeds, the return value is a handle to the menu resource.
If the function fails, the return value is NULL . 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.
Examples
For an example, see Displaying a Shortcut Menu
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
LoadMenuIndirect
MAKEINTRESOURCE
Menus
Reference
minutes to read • Edit Online
Loads a string resource from the executable file associated with a specified module and either copies the string into
a buffer with a terminating null character or returns a read-only pointer to the string resource itself.
Syntax
int LoadStringA(
HINSTANCE hInstance,
UINT
uID,
LPSTR
lpBuffer,
int
cchBufferMax
);
Parameters
hInstance
Type: HINSTANCE
A handle to an instance of the module whose executable file contains the string resource. To get the handle to the
application itself, call the GetModuleHandle function with NULL .
uID
Type: UINT
The identifier of the string to be loaded.
lpBuffer
Type: LPTSTR
The buffer to receive the string (if cchBufferMax is non-zero) or a read-only pointer to the string resource itself (if
cchBufferMax is zero). Must be of sufficient length to hold a pointer (8 bytes).
cchBufferMax
Type: int
The size of the buffer, in characters. The string is truncated and null-terminated if it is longer than the number of
characters specified. If this parameter is 0, then lpBuffer receives a read-only pointer to the string resource itself.
Return value
Type: int
If the function succeeds, the return value is one of the following:
The number of characters copied into the buffer (if cchBufferMax is non-zero), not including the terminating null
character.
The number of characters in the string resource that lpBuffer points to (if cchBufferMax is zero). The string
resource is not guaranteed to be null-terminated in the module's resource table, and you can use this value to
determine where the string resource ends.
Zero if the string resource does not exist.
To get extended error information, call GetLastError.
Remarks
If you pass 0 to cchBufferMax to return a read-only pointer to the string resource in the lpBuffer parameter, use the
number of characters in the return value to determine the length of the string resource. String resources are not
guaranteed to be null-terminated in the module's resource table. However, resource tables can contain null
characters. String resources are stored in blocks of 16 strings, and any empty slots within a block are indicated by
null characters.
Security Remarks
Using this function incorrectly can compromise the security of your application. Incorrect use includes specifying the
wrong size in the nBufferMax parameter. For example, if lpBuffer points to a buffer szBuffer which is declared as
TCHAR szBuffer[100] , then sizeof(szBuffer) gives the size of the buffer in bytes, which could lead to a buffer overflow
for the Unicode version of the function. Buffer overflow situations are the cause of many security problems in
applications. In this case, using sizeof(szBuffer)/sizeof(TCHAR) or sizeof(szBuffer)/sizeof(szBuffer[0]) would give
the proper size of the buffer.
Examples
For an example, see Creating a Child Window
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
FormatMessage
LoadAccelerators
LoadBitmap
LoadCursor
LoadIcon
LoadMenu
LoadMenuIndirect
Other Resources
Reference
Strings
minutes to read • Edit Online
Loads a string resource from the executable file associated with a specified module and either copies the string into
a buffer with a terminating null character or returns a read-only pointer to the string resource itself.
Syntax
int LoadStringW(
HINSTANCE hInstance,
UINT
uID,
LPWSTR
lpBuffer,
int
cchBufferMax
);
Parameters
hInstance
Type: HINSTANCE
A handle to an instance of the module whose executable file contains the string resource. To get the handle to the
application itself, call the GetModuleHandle function with NULL .
uID
Type: UINT
The identifier of the string to be loaded.
lpBuffer
Type: LPTSTR
The buffer to receive the string (if cchBufferMax is non-zero) or a read-only pointer to the string resource itself (if
cchBufferMax is zero). Must be of sufficient length to hold a pointer (8 bytes).
cchBufferMax
Type: int
The size of the buffer, in characters. The string is truncated and null-terminated if it is longer than the number of
characters specified. If this parameter is 0, then lpBuffer receives a read-only pointer to the string resource itself.
Return value
Type: int
If the function succeeds, the return value is one of the following:
The number of characters copied into the buffer (if cchBufferMax is non-zero), not including the terminating null
character.
The number of characters in the string resource that lpBuffer points to (if cchBufferMax is zero). The string
resource is not guaranteed to be null-terminated in the module's resource table, and you can use this value to
determine where the string resource ends.
Zero if the string resource does not exist.
To get extended error information, call GetLastError.
Remarks
If you pass 0 to cchBufferMax to return a read-only pointer to the string resource in the lpBuffer parameter, use the
number of characters in the return value to determine the length of the string resource. String resources are not
guaranteed to be null-terminated in the module's resource table. However, resource tables can contain null
characters. String resources are stored in blocks of 16 strings, and any empty slots within a block are indicated by
null characters.
Security Remarks
Using this function incorrectly can compromise the security of your application. Incorrect use includes specifying the
wrong size in the nBufferMax parameter. For example, if lpBuffer points to a buffer szBuffer which is declared as
TCHAR szBuffer[100] , then sizeof(szBuffer) gives the size of the buffer in bytes, which could lead to a buffer overflow
for the Unicode version of the function. Buffer overflow situations are the cause of many security problems in
applications. In this case, using sizeof(szBuffer)/sizeof(TCHAR) or sizeof(szBuffer)/sizeof(szBuffer[0]) would give
the proper size of the buffer.
Examples
For an example, see Creating a Child Window
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
FormatMessage
LoadAccelerators
LoadBitmap
LoadCursor
LoadIcon
LoadMenu
LoadMenuIndirect
Other Resources
Reference
Strings
minutes to read • Edit Online
Searches through icon or cursor data for the icon or cursor that best fits the current display device.
To specify a desired height or width, use the LookupIconIdFromDirectoryEx function.
Syntax
int LookupIconIdFromDirectory(
PBYTE presbits,
BOOL fIcon
);
Parameters
presbits
Type: PBYTE
The icon or cursor directory data. Because this function does not validate the resource data, it causes a general
protection (GP) fault or returns an undefined value if presbits is not pointing to valid resource data.
fIcon
Type: BOOL
Indicates whether an icon or a cursor is sought. If this parameter is TRUE , the function is searching for an icon; if
the parameter is FALSE , the function is searching for a cursor.
Return value
Type: int
If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the
current display device.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
A resource file of type RT_GROUP_ICON (RT_GROUP_CURSOR indicates cursors) contains icon (or cursor) data
in several device-dependent and device-independent formats. LookupIconIdFromDirector y searches the
resource file for the icon (or cursor) that best fits the current display device and returns its integer identifier. The
FindResource and FindResourceEx functions use the MAKEINTRESOURCE macro with this identifier to locate the
resource in the module.
The icon directory is loaded from a resource file with resource type RT_GROUP_ICON (or RT_GROUP_CURSOR
for cursors), and an integer resource name for the specific icon to be loaded. LookupIconIdFromDirector y
returns an integer identifier that is the resource name of the icon that best fits the current display device.
The LoadIcon, LoadCursor, and LoadImage functions use this function to search the specified resource data for the
icon or cursor that best fits the current display device.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIconFromResource
CreateIconIndirect
FindResource
FindResourceEx
GetIconInfo
Icons
LoadCursor
LoadIcon
LoadImage
LookupIconIdFromDirectoryEx
MAKEINTRESOURCE
Reference
minutes to read • Edit Online
Searches through icon or cursor data for the icon or cursor that best fits the current display device.
Syntax
int LookupIconIdFromDirectoryEx(
PBYTE presbits,
BOOL fIcon,
int cxDesired,
int cyDesired,
UINT Flags
);
Parameters
presbits
Type: PBYTE
The icon or cursor directory data. Because this function does not validate the resource data, it causes a general
protection (GP) fault or returns an undefined value if presbits is not pointing to valid resource data.
fIcon
Type: BOOL
Indicates whether an icon or a cursor is sought. If this parameter is TRUE , the function is searching for an icon; if
the parameter is FALSE , the function is searching for a cursor.
cxDesired
Type: int
The desired width, in pixels, of the icon. If this parameter is zero, the function uses the SM_CXICON or
SM_CXCURSOR system metric value.
cyDesired
Type: int
The desired height, in pixels, of the icon. If this parameter is zero, the function uses the SM_CYICON or
SM_CYCURSOR system metric value.
Flags
Type: UINT
A combination of the following values.
VA L UE
M EA N IN G
Uses the default color format.
LR_
DEF
AU
LTC
OL
OR
0x0
000
000
0
Creates a monochrome icon or cursor.
LR_
MO
NO
CH
RO
ME
0x0
000
000
1
Return value
Type: int
If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the
current display device.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
A resource file of type RT_GROUP_ICON (RT_GROUP_CURSOR indicates cursors) contains icon (or cursor) data
in several device-dependent and device-independent formats. LookupIconIdFromDirector yEx searches the
resource file for the icon (or cursor) that best fits the current display device and returns its integer identifier. The
FindResource and FindResourceEx functions use the MAKEINTRESOURCE macro with this identifier to locate the
resource in the module.
The icon directory is loaded from a resource file with resource type RT_GROUP_ICON (or RT_GROUP_CURSOR
for cursors), and an integer resource name for the specific icon to be loaded. LookupIconIdFromDirector yEx
returns an integer identifier that is the resource name of the icon that best fits the current display device.
The LoadIcon, LoadImage, and LoadCursor functions use this function to search the specified resource data for the
icon or cursor that best fits the current display device.
Examples
For an example, see Sharing Icon Resources.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateIconFromResourceEx
CreateIconIndirect
FindResource
FindResourceEx
GetIconInfo
Icons
LoadCursor
LoadIcon
LoadImage
LookupIconIdFromDirectory
MAKEINTRESOURCE
Reference
minutes to read • Edit Online
Converts an integer value to a resource type compatible with the resource-management functions. This macro is
used in place of a string containing the name of the resource.
Syntax
void MAKEINTRESOURCEA(
i
);
Parameters
i
The integer value to be converted.
Return value
None
Remarks
The return value should be passed only to functions which explicitly indicate that they accept
MAKEINTRESOURCE as a parameter. For example, the resource management functions allow the return value of
MAKEINTRESOURCE to be passed as the lpType or lpName parameters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
See also
Resources Overview
minutes to read • Edit Online
Converts an integer value to a resource type compatible with the resource-management functions. This macro is
used in place of a string containing the name of the resource.
Syntax
void MAKEINTRESOURCEW(
i
);
Parameters
i
The integer value to be converted.
Return value
None
Remarks
The return value should be passed only to functions which explicitly indicate that they accept
MAKEINTRESOURCE as a parameter. For example, the resource management functions allow the return value of
MAKEINTRESOURCE to be passed as the lpType or lpName parameters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
See also
Resources Overview
minutes to read • Edit Online
Contains information about the menu to be activated.
Syntax
typedef struct tagMDINEXTMENU {
HMENU hmenuIn;
HMENU hmenuNext;
HWND hwndNext;
} MDINEXTMENU, *PMDINEXTMENU, *LPMDINEXTMENU;
Members
hmenuIn
Type: HMENU
A handle to the current menu.
hmenuNext
Type: HMENU
A handle to the menu to be activated.
hwndNext
Type: HWND
A handle to the window to receive the menu notification messages.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
Menus
Reference
WM_NEXTMENU
minutes to read • Edit Online
Contains menu bar information.
Syntax
typedef struct tagMENUBARINFO {
DWORD cbSize;
RECT rcBar;
HMENU hMenu;
HWND hwndMenu;
BOOL fBarFocused : 1;
BOOL fFocused : 1;
} MENUBARINFO, *PMENUBARINFO, *LPMENUBARINFO;
Members
cbSize
Type: DWORD
The size of the structure, in bytes. The caller must set this to
sizeof(MENUBARINFO)
.
rcBar
Type: RECT
The coordinates of the menu bar, popup menu, or menu item.
hMenu
Type: HMENU
A handle to the menu bar or popup menu.
hwndMenu
Type: HWND
A handle to the submenu.
fBarFocused
Type: BOOL
If the menu bar or popup menu has the focus, this member is TRUE . Otherwise, the member is FALSE .
fFocused
Type: BOOL
If the menu item has the focus, this member is TRUE . Otherwise, the member is FALSE .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
GetMenuBarInfo
Menus
RECT
Reference
minutes to read • Edit Online
Contains information about the menu that the mouse cursor is on.
Syntax
typedef struct tagMENUGETOBJECTINFO {
DWORD dwFlags;
UINT uPos;
HMENU hmenu;
PVOID riid;
PVOID pvObj;
} MENUGETOBJECTINFO, *PMENUGETOBJECTINFO;
Members
dwFlags
Type: DWORD
The position of the mouse cursor with respect to the item indicated by uPos . It is a bitmask of the following values:
VA L UE
M EA N IN G
The mouse is on the bottom of the item indicated by uPos .
MN
GO
F_B
OTT
OM
GA
P
0x0
000
000
2
The mouse is on the top of the item indicated by uPos .
MN
GO
F_T
OP
GA
P
0x0
000
000
1
If neither MNGOF_BOTTOMGAP nor MNGOF_TOPGAP is set, then the mouse is directly on the item indicated by
uPos .
uPos
Type: UINT
The position of the item the mouse cursor is on.
hmenu
Type: HMENU
A handle to the menu the mouse cursor is on.
riid
Type: PVOID
The identifier of the requested interface. Currently it can only be IDropTarget.
pvObj
Type: PVOID
A pointer to the interface corresponding to the riid member. This pointer is to be returned by the application when
processing the message.
Remarks
The MENUGETOBJECTINFO structure is used only in drag-and-drop menus. When the WM_MENUGETOBJECT
message is sent, lParam is a pointer to this structure.
To create a drag-and-drop menu, call SetMenuInfo with MNS_DRAGDROP set.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
Menus
Reference
SetMenuInfo
minutes to read • Edit Online
Contains information about a menu.
Syntax
typedef struct tagMENUINFO {
DWORD
cbSize;
DWORD
fMask;
DWORD
dwStyle;
UINT
cyMax;
HBRUSH
hbrBack;
DWORD
dwContextHelpID;
ULONG_PTR dwMenuData;
} MENUINFO, *LPMENUINFO;
Members
cbSize
Type: DWORD
The size of the structure, in bytes. The caller must set this member to
sizeof(MENUINFO)
.
fMask
Type: DWORD
Indicates the members to be retrieved or set (except for MIM_APPLYTOSUBMENUS ). This member can be one or
more of the following values.
VA L UE
MI
M_
APP
LYT
OS
UB
ME
NU
S
0x8
000
000
0
M EA N IN G
Settings apply to the menu and all of its submenus.
SetMenuInfo uses this flag and GetMenuInfo ignores this flag
Retrieves or sets the hbrBack member.
MI
M_
BA
CK
GR
OU
ND
0x0
000
000
2
Retrieves or sets the dwContextHelpID member.
MI
M_
HEL
PID
0x0
000
000
4
Retrieves or sets the cyMax member.
MI
M_
MA
XHE
IGH
T
0x0
000
000
1
Retrieves or sets the dwMenuData member.
MI
M_
ME
NU
DAT
A
0x0
000
000
8
Retrieves or sets the dwStyle member.
MI
M_
STY
LE
0x0
000
001
0
dwStyle
Type: DWORD
The menu style. This member can be one or more of the following values.
VA L UE
MN
S_A
UT
ODI
SMI
SS
0x1
000
000
0
MN
S_C
HE
CK
OR
BM
P
0x0
400
000
0
MN
S_D
RA
GD
RO
P
0x2
000
000
0
MN
S_
MO
DEL
ESS
0x4
000
000
0
M EA N IN G
Menu automatically ends when mouse is outside the menu for
approximately 10 seconds.
The same space is reserved for the check mark and the
bitmap. If the check mark is drawn, the bitmap is not. All
checkmarks and bitmaps are aligned. Used for menus where
some items use checkmarks and some use bitmaps.
Menu items are OLE drop targets or drag sources. Menu
owner receives WM_MENUDRAG and WM_MENUGETOBJECT
messages.
Menu is modeless; that is, there is no menu modal message
loop while the menu is active.
MN
S_N
OC
HE
CK
0x8
000
000
0
MN
S_N
OTI
FYB
YP
OS
0x0
800
000
0
No space is reserved to the left of an item for a check mark.
The item can still be selected, but the check mark will not
appear next to the item.
Menu owner receives a WM_MENUCOMMAND message
instead of a WM_COMMAND message when the user makes
a selection. MNS_NOTIFYBYPOS is a menu header style and
has no effect when applied to individual sub menus.
cyMax
Type: UINT
The maximum height of the menu in pixels. When the menu items exceed the space available, scroll bars are
automatically used. The default (0) is the screen height.
hbrBack
Type: HBRUSH
A handle to the brush to be used for the menu's background.
dwContextHelpID
Type: DWORD
The context help identifier. This is the same value used in the GetMenuContextHelpId and SetMenuContextHelpId
functions.
dwMenuData
Type: ULONG_PTR
An application-defined value.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Menus Overview
minutes to read • Edit Online
Determines which menu item, if any, is at the specified location.
Syntax
int MenuItemFromPoint(
HWND hWnd,
HMENU hMenu,
POINT ptScreen
);
Parameters
hWnd
Type: HWND
A handle to the window containing the menu. If this value is NULL and the hMenu parameter represents a popup
menu, the function will find the menu window.
hMenu
Type: HMENU
A handle to the menu containing the menu items to hit test.
ptScreen
Type: POINT
A structure that specifies the location to test. If hMenu specifies a menu bar, this parameter is in window
coordinates. Otherwise, it is in client coordinates.
Return value
Type: int
Returns the zero-based position of the menu item at the specified location or -1 if no menu item is at the specified
location.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Menus
minutes to read • Edit Online
Contains information about a menu item.
Syntax
typedef struct tagMENUITEMINFOA {
UINT
cbSize;
UINT
fMask;
UINT
fType;
UINT
fState;
UINT
wID;
HMENU
hSubMenu;
HBITMAP hbmpChecked;
HBITMAP hbmpUnchecked;
ULONG_PTR dwItemData;
LPSTR
dwTypeData;
UINT
cch;
HBITMAP hbmpItem;
} MENUITEMINFOA, *LPMENUITEMINFOA;
Members
cbSize
Type: UINT
The size of the structure, in bytes. The caller must set this member to
sizeof(MENUITEMINFO)
.
fMask
Type: UINT
Indicates the members to be retrieved or set. This member can be one or more of the following values.
VA L UE
M EA N IN G
Retrieves or sets the hbmpItem member.
MII
M_
BIT
MA
P
0x0
000
008
0
MII
M_
CH
ECK
MA
RKS
0x0
000
000
8
Retrieves or sets the hbmpChecked and hbmpUnchecked
members.
Retrieves or sets the dwItemData member.
MII
M_
DAT
A
0x0
000
002
0
Retrieves or sets the fType member.
MII
M_
FTY
PE
0x0
000
010
0
Retrieves or sets the wID member.
MII
M_I
D
0x0
000
000
2
Retrieves or sets the fState member.
MII
M_
STA
TE
0x0
000
000
1
Retrieves or sets the dwTypeData member.
MII
M_
STR
ING
0x0
000
004
0
Retrieves or sets the hSubMenu member.
MII
M_
SUB
ME
NU
0x0
000
000
4
MII
M_
TYP
E
0x0
000
001
0
Retrieves or sets the fType and dwTypeData members.
MIIM_TYPE is replaced by MIIM_BITMAP ,
MIIM_FTYPE , and MIIM_STRING .
fType
Type: UINT
The menu item type. This member can be one or more of the following values.
The MFT_BITMAP , MFT_SEPARATOR , and MFT_STRING values cannot be combined with one another. Set
fMask to MIIM_TYPE to use fType .
fType is used only if fMask has a value of MIIM_FTYPE .
VA L UE
MF
T_B
ITM
AP
0x0
000
000
4L
M EA N IN G
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_BITMAP is replaced by MIIM_BITMAP and
hbmpItem .
MF
T_
ME
NU
BAR
BRE
AK
0x0
000
002
0L
MF
T_
ME
NU
BRE
AK
0x0
000
004
0L
MF
T_O
WN
ERD
RA
W
0x0
000
010
0L
MF
T_R
ADI
OC
HE
CK
0x0
000
020
0L
MF
T_R
IGH
TJU
STI
FY
0x0
000
400
0L
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.
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.
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 applicationdefined value.
Displays selected menu items using a radio-button mark
instead of a check mark if the hbmpChecked member is
NULL .
Right-justifies the menu item and any subsequent items. This
value is valid only if the menu item is in a menu bar.
MF
T_R
IGH
TOR
DER
0x0
000
200
0L
MF
T_S
EPA
RAT
OR
0x0
000
080
0L
MF
T_S
TRI
NG
0x0
000
000
0L
Specifies that menus cascade right-to-left (the default is leftto-right). This is used to support right-to-left languages, such
as Arabic and Hebrew.
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.
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.
MFT_STRING is replaced by MIIM_STRING .
fState
Type: UINT
The menu item state. This member can be one or more of these values. Set fMask to MIIM_STATE to use fState .
VA L UE
MF
S_C
HE
CKE
D
0x0
000
000
8L
M EA N IN G
Checks the menu item. For more information about selected
menu items, see the hbmpChecked member.
MF
S_D
EFA
ULT
0x0
000
100
0L
MF
S_D
ISA
BLE
D
0x0
000
000
3L
MF
S_E
NA
BLE
D
0x0
000
000
0L
MF
S_G
RAY
ED
0x0
000
000
3L
Specifies that the menu item is the default. A menu can
contain only one default menu item, which is displayed in bold.
Disables the menu item and grays it so that it cannot be
selected. This is equivalent to MFS_GRAYED .
Enables the menu item so that it can be selected. This is the
default state.
Disables the menu item and grays it so that it cannot be
selected. This is equivalent to MFS_DISABLED .
Highlights the menu item.
MF
S_H
ILIT
E
0x0
000
008
0L
MF
S_U
NC
HE
CKE
D
0x0
000
000
0L
MF
S_U
NHI
LIT
E
0x0
000
000
0L
Unchecks the menu item. For more information about clear
menu items, see the hbmpChecked member.
Removes the highlight from the menu item. This is the default
state.
wID
Type: UINT
An application-defined value that identifies the menu item. Set fMask to MIIM_ID to use wID .
hSubMenu
Type: HMENU
A 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 . Set fMask to MIIM_SUBMENU to use hSubMenu .
hbmpChecked
Type: HBITMAP
A handle to the bitmap to display next to the item if it is selected. 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. Set
fMask to MIIM_CHECKMARKS to use hbmpChecked .
hbmpUnchecked
Type: HBITMAP
A handle to the bitmap to display next to the item if it is not selected. If this member is NULL , no bitmap is used.
Set fMask to MIIM_CHECKMARKS to use hbmpUnchecked .
dwItemData
Type: ULONG_PTR
An application-defined value associated with the menu item. Set fMask to MIIM_DATA to use dwItemData .
dwTypeData
Type: LPTSTR
The contents of the menu item. The meaning of this member depends on the value of fType and is used only if the
MIIM_TYPE flag is set in the fMask member.
To retrieve a menu item of type MFT_STRING , first find the size of the string by setting the dwTypeData member
of MENUITEMINFO to NULL and then calling GetMenuItemInfo. The value of cch +1 is the size needed. Then
allocate a buffer of this size, place the pointer to the buffer in dwTypeData , increment cch , and call
GetMenuItemInfo once again to fill the buffer with the string. 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 contain a value whose type is specified by the
fType member.
dwTypeData is used only if the MIIM_STRING flag is set in the fMask member
cch
Type: UINT
The length of the menu item text, in characters, when information is received about a menu item of the
MFT_STRING type. However, cch is used only if the MIIM_TYPE flag is set in the fMask member and is zero
otherwise. Also, cch is ignored when the content of a menu item is set by calling SetMenuItemInfo.
Note that, before calling GetMenuItemInfo, the application must set cch 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 changes cch to the length of the menu item text. If the retrieved menu item is of some
other type, GetMenuItemInfo sets the cch field to zero.
The cch member is used when the MIIM_STRING flag is set in the fMask member.
hbmpItem
Type: HBITMAP
A handle to the bitmap to be displayed, or it can be one of the values in the following table. It is used when the
MIIM_BITMAP flag is set in the fMask member.
VA L UE
HB
MM
EN
U_C
ALL
BA
CK
((HB
ITM
AP)
-1)
M EA N IN G
A bitmap that is drawn by the window that owns the menu.
The application must process the WM_MEASUREITEM and
WM_DRAWITEM messages.
Close button for the menu bar.
HB
MM
EN
U_
MB
AR_
CL
OSE
((HB
ITM
AP)
5)
Disabled close button for the menu bar.
HB
MM
EN
U_
MB
AR_
CL
OSE
_D
((HB
ITM
AP)
6)
Minimize button for the menu bar.
HB
MM
EN
U_
MB
AR_
MI
NI
MIZ
E
((HB
ITM
AP)
3)
Disabled minimize button for the menu bar.
HB
MM
EN
U_
MB
AR_
MI
NI
MIZ
E_D
((HB
ITM
AP)
7)
Restore button for the menu bar.
HB
MM
EN
U_
MB
AR_
RES
TOR
E
((HB
ITM
AP)
2)
Close button for the submenu.
HB
MM
EN
U_P
OP
UP_
CL
OSE
((HB
ITM
AP)
8)
Maximize button for the submenu.
HB
MM
EN
U_P
OP
UP_
MA
XIM
IZE
((HB
ITM
AP)
10)
Minimize button for the submenu.
HB
MM
EN
U_P
OP
UP_
MI
NI
MIZ
E
((HB
ITM
AP)
11)
Restore button for the submenu.
HB
MM
EN
U_P
OP
UP_
RES
TOR
E
((HB
ITM
AP)
9)
HB
MM
EN
U_S
YST
EM
((HB
ITM
AP)
1)
Windows icon or the icon of the window specified in
dwItemData .
Remarks
The MENUITEMINFO structure is used with the GetMenuItemInfo, InsertMenuItem, and SetMenuItemInfo
functions.
The menu can display items using text, bitmaps, or both.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
GetMenuItemInfo
InsertMenuItem
Menus
Reference
SetMenuItemInfo
WM_DRAWITEM
WM_MEASUREITEM
minutes to read • Edit Online
Contains information about a menu item.
Syntax
typedef struct tagMENUITEMINFOW {
UINT
cbSize;
UINT
fMask;
UINT
fType;
UINT
fState;
UINT
wID;
HMENU
hSubMenu;
HBITMAP hbmpChecked;
HBITMAP hbmpUnchecked;
ULONG_PTR dwItemData;
LPWSTR
dwTypeData;
UINT
cch;
HBITMAP hbmpItem;
} MENUITEMINFOW, *LPMENUITEMINFOW;
Members
cbSize
Type: UINT
The size of the structure, in bytes. The caller must set this member to
sizeof(MENUITEMINFO)
.
fMask
Type: UINT
Indicates the members to be retrieved or set. This member can be one or more of the following values.
VA L UE
M EA N IN G
Retrieves or sets the hbmpItem member.
MII
M_
BIT
MA
P
0x0
000
008
0
MII
M_
CH
ECK
MA
RKS
0x0
000
000
8
Retrieves or sets the hbmpChecked and hbmpUnchecked
members.
Retrieves or sets the dwItemData member.
MII
M_
DAT
A
0x0
000
002
0
Retrieves or sets the fType member.
MII
M_
FTY
PE
0x0
000
010
0
Retrieves or sets the wID member.
MII
M_I
D
0x0
000
000
2
Retrieves or sets the fState member.
MII
M_
STA
TE
0x0
000
000
1
Retrieves or sets the dwTypeData member.
MII
M_
STR
ING
0x0
000
004
0
Retrieves or sets the hSubMenu member.
MII
M_
SUB
ME
NU
0x0
000
000
4
MII
M_
TYP
E
0x0
000
001
0
Retrieves or sets the fType and dwTypeData members.
MIIM_TYPE is replaced by MIIM_BITMAP ,
MIIM_FTYPE , and MIIM_STRING .
fType
Type: UINT
The menu item type. This member can be one or more of the following values.
The MFT_BITMAP , MFT_SEPARATOR , and MFT_STRING values cannot be combined with one another. Set
fMask to MIIM_TYPE to use fType .
fType is used only if fMask has a value of MIIM_FTYPE .
VA L UE
MF
T_B
ITM
AP
0x0
000
000
4L
M EA N IN G
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_BITMAP is replaced by MIIM_BITMAP and
hbmpItem .
MF
T_
ME
NU
BAR
BRE
AK
0x0
000
002
0L
MF
T_
ME
NU
BRE
AK
0x0
000
004
0L
MF
T_O
WN
ERD
RA
W
0x0
000
010
0L
MF
T_R
ADI
OC
HE
CK
0x0
000
020
0L
MF
T_R
IGH
TJU
STI
FY
0x0
000
400
0L
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.
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.
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 applicationdefined value.
Displays selected menu items using a radio-button mark
instead of a check mark if the hbmpChecked member is
NULL .
Right-justifies the menu item and any subsequent items. This
value is valid only if the menu item is in a menu bar.
MF
T_R
IGH
TOR
DER
0x0
000
200
0L
MF
T_S
EPA
RAT
OR
0x0
000
080
0L
MF
T_S
TRI
NG
0x0
000
000
0L
Specifies that menus cascade right-to-left (the default is leftto-right). This is used to support right-to-left languages, such
as Arabic and Hebrew.
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.
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.
MFT_STRING is replaced by MIIM_STRING .
fState
Type: UINT
The menu item state. This member can be one or more of these values. Set fMask to MIIM_STATE to use fState .
VA L UE
MF
S_C
HE
CKE
D
0x0
000
000
8L
M EA N IN G
Checks the menu item. For more information about selected
menu items, see the hbmpChecked member.
MF
S_D
EFA
ULT
0x0
000
100
0L
MF
S_D
ISA
BLE
D
0x0
000
000
3L
MF
S_E
NA
BLE
D
0x0
000
000
0L
MF
S_G
RAY
ED
0x0
000
000
3L
Specifies that the menu item is the default. A menu can
contain only one default menu item, which is displayed in bold.
Disables the menu item and grays it so that it cannot be
selected. This is equivalent to MFS_GRAYED .
Enables the menu item so that it can be selected. This is the
default state.
Disables the menu item and grays it so that it cannot be
selected. This is equivalent to MFS_DISABLED .
Highlights the menu item.
MF
S_H
ILIT
E
0x0
000
008
0L
MF
S_U
NC
HE
CKE
D
0x0
000
000
0L
MF
S_U
NHI
LIT
E
0x0
000
000
0L
Unchecks the menu item. For more information about clear
menu items, see the hbmpChecked member.
Removes the highlight from the menu item. This is the default
state.
wID
Type: UINT
An application-defined value that identifies the menu item. Set fMask to MIIM_ID to use wID .
hSubMenu
Type: HMENU
A 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 . Set fMask to MIIM_SUBMENU to use hSubMenu .
hbmpChecked
Type: HBITMAP
A handle to the bitmap to display next to the item if it is selected. 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. Set
fMask to MIIM_CHECKMARKS to use hbmpChecked .
hbmpUnchecked
Type: HBITMAP
A handle to the bitmap to display next to the item if it is not selected. If this member is NULL , no bitmap is used.
Set fMask to MIIM_CHECKMARKS to use hbmpUnchecked .
dwItemData
Type: ULONG_PTR
An application-defined value associated with the menu item. Set fMask to MIIM_DATA to use dwItemData .
dwTypeData
Type: LPTSTR
The contents of the menu item. The meaning of this member depends on the value of fType and is used only if the
MIIM_TYPE flag is set in the fMask member.
To retrieve a menu item of type MFT_STRING , first find the size of the string by setting the dwTypeData member
of MENUITEMINFO to NULL and then calling GetMenuItemInfo. The value of cch +1 is the size needed. Then
allocate a buffer of this size, place the pointer to the buffer in dwTypeData , increment cch , and call
GetMenuItemInfo once again to fill the buffer with the string. 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 contain a value whose type is specified by the
fType member.
dwTypeData is used only if the MIIM_STRING flag is set in the fMask member
cch
Type: UINT
The length of the menu item text, in characters, when information is received about a menu item of the
MFT_STRING type. However, cch is used only if the MIIM_TYPE flag is set in the fMask member and is zero
otherwise. Also, cch is ignored when the content of a menu item is set by calling SetMenuItemInfo.
Note that, before calling GetMenuItemInfo, the application must set cch 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 changes cch to the length of the menu item text. If the retrieved menu item is of some
other type, GetMenuItemInfo sets the cch field to zero.
The cch member is used when the MIIM_STRING flag is set in the fMask member.
hbmpItem
Type: HBITMAP
A handle to the bitmap to be displayed, or it can be one of the values in the following table. It is used when the
MIIM_BITMAP flag is set in the fMask member.
VA L UE
HB
MM
EN
U_C
ALL
BA
CK
((HB
ITM
AP)
-1)
M EA N IN G
A bitmap that is drawn by the window that owns the menu.
The application must process the WM_MEASUREITEM and
WM_DRAWITEM messages.
Close button for the menu bar.
HB
MM
EN
U_
MB
AR_
CL
OSE
((HB
ITM
AP)
5)
Disabled close button for the menu bar.
HB
MM
EN
U_
MB
AR_
CL
OSE
_D
((HB
ITM
AP)
6)
Minimize button for the menu bar.
HB
MM
EN
U_
MB
AR_
MI
NI
MIZ
E
((HB
ITM
AP)
3)
Disabled minimize button for the menu bar.
HB
MM
EN
U_
MB
AR_
MI
NI
MIZ
E_D
((HB
ITM
AP)
7)
Restore button for the menu bar.
HB
MM
EN
U_
MB
AR_
RES
TOR
E
((HB
ITM
AP)
2)
Close button for the submenu.
HB
MM
EN
U_P
OP
UP_
CL
OSE
((HB
ITM
AP)
8)
Maximize button for the submenu.
HB
MM
EN
U_P
OP
UP_
MA
XIM
IZE
((HB
ITM
AP)
10)
Minimize button for the submenu.
HB
MM
EN
U_P
OP
UP_
MI
NI
MIZ
E
((HB
ITM
AP)
11)
Restore button for the submenu.
HB
MM
EN
U_P
OP
UP_
RES
TOR
E
((HB
ITM
AP)
9)
HB
MM
EN
U_S
YST
EM
((HB
ITM
AP)
1)
Windows icon or the icon of the window specified in
dwItemData .
Remarks
The MENUITEMINFO structure is used with the GetMenuItemInfo, InsertMenuItem, and SetMenuItemInfo
functions.
The menu can display items using text, bitmaps, or both.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
GetMenuItemInfo
InsertMenuItem
Menus
Reference
SetMenuItemInfo
WM_DRAWITEM
WM_MEASUREITEM
minutes to read • Edit Online
Defines a menu item in a menu template.
Syntax
typedef struct {
WORD mtOption;
WORD mtID;
WCHAR mtString[1];
} MENUITEMTEMPLATE, *PMENUITEMTEMPLATE;
Members
mtOption
Type: WORD
One or more of the following predefined menu options that control the appearance of the menu item as shown in
the following table.
VA L UE
M EA N IN G
Indicates that the menu item has a check mark next to it.
MF
_CH
ECK
ED
0x0
000
000
8L
MF
_GR
AYE
D
0x0
000
000
1L
MF
_HE
LP
0x0
000
400
0L
Indicates that the menu item is initially inactive and drawn
with a gray effect.
Indicates that the menu item has a vertical separator to its
left.
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
Indicates that the menu item is placed in a new column. The
old and new columns are separated by a bar.
Indicates that the menu item is placed in a new column.
MF
_M
EN
UB
REA
K
0x0
000
004
0L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
MF
_PO
PU
P
0x0
000
001
0L
Indicates that the owner window of the menu is responsible
for drawing all visual aspects of the menu item, including
highlighted, selected, and inactive states. This option is not
valid for an item in a menu bar.
Indicates that the item is one that opens a drop-down menu
or submenu.
mtID
Type: WORD
The menu item identifier of a command item; a command item sends a command message to its owner window.
The MENUITEMTEMPL ATE structure for an item that opens a drop-down menu or submenu does not contain the
mtID member.
mtString
Type: WCHAR[1]
The menu item.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
LoadMenuIndirect
MENUITEMTEMPLATEHEADER
Menus
Reference
minutes to read • Edit Online
Defines the header for a menu template. A complete menu template consists of a header and one or more menu
item lists.
Syntax
typedef struct {
WORD versionNumber;
WORD offset;
} MENUITEMTEMPLATEHEADER, *PMENUITEMTEMPLATEHEADER;
Members
versionNumber
Type: WORD
The version number. This member must be zero.
offset
Type: WORD
The offset, in bytes, from the end of the header. The menu item list begins at this offset. Usually, this member is
zero, and the menu item list follows immediately after the header.
Remarks
One or more MENUITEMTEMPLATE structures are combined to form the menu item list.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
LoadMenuIndirect
MENUITEMTEMPLATE
Menus
Reference
minutes to read • Edit Online
Changes an existing menu item. This function is used to specify the content, appearance, and behavior of the menu
item.
Note The ModifyMenu function has been superseded by the SetMenuItemInfo function. You can still use ModifyMenu ,
however, if you do not need any of the extended features of SetMenuItemInfo .
Syntax
BOOL ModifyMenuA(
HMENU
hMnu,
UINT
uPosition,
UINT
uFlags,
UINT_PTR uIDNewItem,
LPCSTR lpNewItem
);
Parameters
hMnu
Type: HMENU
A handle to the menu to be changed.
uPosition
Type: UINT
The menu item to be changed, as determined by the uFlags parameter.
uFlags
Type: UINT
Controls the interpretation of the uPosition parameter and the content, appearance, and behavior of the menu item.
This parameter must include one of the following required values.
VA L UE
M EA N IN G
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
MF
_BY
PO
SITI
ON
0x0
000
040
0L
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.
Indicates that the uPosition parameter gives the zero-based
relative position of the menu item.
The parameter must also include at least one of the following values.
VA L UE
MF
_BI
TM
AP
0x0
000
000
4L
MF
_CH
ECK
ED
0x0
000
000
8L
MF
_DI
SAB
LED
0x0
000
000
2L
M EA N IN G
Uses a bitmap as the menu item. The lpNewItem parameter
contains a handle to the bitmap.
Places a check mark next to the item. If your application
provides check-mark bitmaps (see the SetMenuItemBitmaps
function), this flag displays a selected bitmap next to the menu
item.
Disables the menu item so that it cannot be selected, but this
flag does not gray it.
MF
_EN
ABL
ED
0x0
000
000
0L
MF
_GR
AYE
D
0x0
000
000
1L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Enables the menu item so that it can be selected and restores
it from its grayed state.
Disables the menu item and grays it so that it cannot be
selected.
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.
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.
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
_PO
PU
P
0x0
000
001
0L
MF
_SE
PAR
ATO
R
0x0
000
080
0L
MF
_ST
RIN
G
0x0
000
000
0L
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
Specifies that the menu item opens a drop-down menu or
submenu. The uIDNewItem parameter specifies a 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.
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.
Specifies that the menu item is a text string; the lpNewItem
parameter is a pointer to the string.
Does not place a check mark next to the item (the default). If
your application supplies check-mark bitmaps (see the
SetMenuItemBitmaps function), this flag displays a clear
bitmap next to the menu item.
uIDNewItem
Type: UINT_PTR
The identifier of the modified menu item or, if the uFlags parameter has the MF_POPUP flag set, a handle to the
drop-down menu or submenu.
lpNewItem
Type: LPCTSTR
The contents of the changed menu item. The interpretation of this parameter depends on whether the uFlags
parameter includes the MF_BITMAP , MF_OWNERDRAW , or MF_STRING flag.
VA L UE
M EA N IN G
A bitmap handle.
MF
_BI
TM
AP
0x0
000
000
4L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
A value supplied by an application that is 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
messages sent when the menu item is created or its
appearance is updated.
A pointer to a null-terminated string (the default).
MF
_ST
RIN
G
0x0
000
000
0L
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If ModifyMenu replaces a menu item that opens a drop-down menu or submenu, the function destroys the old
drop-down menu or submenu and frees the memory used by it.
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. See Owner-Drawn Menus and the WM_MENUCHAR Message for more
information.
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window. To change the attributes of existing menu items, it is much faster to use the CheckMenuItem and
EnableMenuItem functions.
The following groups of flags cannot be used together:
MF_BYCOMMAND and MF_BYPOSITION
MF_DISABLED , MF_ENABLED , and MF_GRAYED
MF_BITMAP , MF_STRING , MF_OWNERDRAW , and MF_SEPARATOR
MF_MENUBARBREAK and MF_MENUBREAK
MF_CHECKED and MF_UNCHECKED
Examples
For an example, see Setting Fonts for Menu-Item Text Strings.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
AppendMenu
CheckMenuItem
Conceptual
DrawMenuBar
EnableMenuItem
Menus
Reference
SetMenuItemBitmaps
SetMenuItemInfo
minutes to read • Edit Online
Changes an existing menu item. This function is used to specify the content, appearance, and behavior of the menu
item.
Note The ModifyMenu function has been superseded by the SetMenuItemInfo function. You can still use ModifyMenu ,
however, if you do not need any of the extended features of SetMenuItemInfo .
Syntax
BOOL ModifyMenuW(
HMENU
hMnu,
UINT
uPosition,
UINT
uFlags,
UINT_PTR uIDNewItem,
LPCWSTR lpNewItem
);
Parameters
hMnu
Type: HMENU
A handle to the menu to be changed.
uPosition
Type: UINT
The menu item to be changed, as determined by the uFlags parameter.
uFlags
Type: UINT
Controls the interpretation of the uPosition parameter and the content, appearance, and behavior of the menu item.
This parameter must include one of the following required values.
VA L UE
M EA N IN G
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
MF
_BY
PO
SITI
ON
0x0
000
040
0L
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.
Indicates that the uPosition parameter gives the zero-based
relative position of the menu item.
The parameter must also include at least one of the following values.
VA L UE
MF
_BI
TM
AP
0x0
000
000
4L
MF
_CH
ECK
ED
0x0
000
000
8L
MF
_DI
SAB
LED
0x0
000
000
2L
M EA N IN G
Uses a bitmap as the menu item. The lpNewItem parameter
contains a handle to the bitmap.
Places a check mark next to the item. If your application
provides check-mark bitmaps (see the SetMenuItemBitmaps
function), this flag displays a selected bitmap next to the menu
item.
Disables the menu item so that it cannot be selected, but this
flag does not gray it.
MF
_EN
ABL
ED
0x0
000
000
0L
MF
_GR
AYE
D
0x0
000
000
1L
MF
_M
EN
UB
ARB
REA
K
0x0
000
002
0L
MF
_M
EN
UB
REA
K
0x0
000
004
0L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
Enables the menu item so that it can be selected and restores
it from its grayed state.
Disables the menu item and grays it so that it cannot be
selected.
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.
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.
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
_PO
PU
P
0x0
000
001
0L
MF
_SE
PAR
ATO
R
0x0
000
080
0L
MF
_ST
RIN
G
0x0
000
000
0L
MF
_U
NC
HE
CKE
D
0x0
000
000
0L
Specifies that the menu item opens a drop-down menu or
submenu. The uIDNewItem parameter specifies a 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.
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.
Specifies that the menu item is a text string; the lpNewItem
parameter is a pointer to the string.
Does not place a check mark next to the item (the default). If
your application supplies check-mark bitmaps (see the
SetMenuItemBitmaps function), this flag displays a clear
bitmap next to the menu item.
uIDNewItem
Type: UINT_PTR
The identifier of the modified menu item or, if the uFlags parameter has the MF_POPUP flag set, a handle to the
drop-down menu or submenu.
lpNewItem
Type: LPCTSTR
The contents of the changed menu item. The interpretation of this parameter depends on whether the uFlags
parameter includes the MF_BITMAP , MF_OWNERDRAW , or MF_STRING flag.
VA L UE
M EA N IN G
A bitmap handle.
MF
_BI
TM
AP
0x0
000
000
4L
MF
_O
WN
ERD
RA
W
0x0
000
010
0L
A value supplied by an application that is 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
messages sent when the menu item is created or its
appearance is updated.
A pointer to a null-terminated string (the default).
MF
_ST
RIN
G
0x0
000
000
0L
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If ModifyMenu replaces a menu item that opens a drop-down menu or submenu, the function destroys the old
drop-down menu or submenu and frees the memory used by it.
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. See Owner-Drawn Menus and the WM_MENUCHAR Message for more
information.
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window. To change the attributes of existing menu items, it is much faster to use the CheckMenuItem and
EnableMenuItem functions.
The following groups of flags cannot be used together:
MF_BYCOMMAND and MF_BYPOSITION
MF_DISABLED , MF_ENABLED , and MF_GRAYED
MF_BITMAP , MF_STRING , MF_OWNERDRAW , and MF_SEPARATOR
MF_MENUBARBREAK and MF_MENUBREAK
MF_CHECKED and MF_UNCHECKED
Examples
For an example, see Setting Fonts for Menu-Item Text Strings.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
AppendMenu
CheckMenuItem
Conceptual
DrawMenuBar
EnableMenuItem
Menus
Reference
SetMenuItemBitmaps
SetMenuItemInfo
minutes to read • Edit Online
Translates a string from the OEM-defined character set into either an ANSI or a wide-character string.
Warning Do not use. See Security Considerations.
Syntax
BOOL OemToCharA(
LPCSTR pSrc,
LPSTR pDst
);
Parameters
pSrc
Type: LPCSTR
A null-terminated string of characters from the OEM-defined character set.
pDst
Type: LPTSTR
The destination buffer, which receives the translated string. If the OemToChar function is being used as an ANSI
function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc
parameter. This cannot be done if OemToChar is being used as a wide-character function.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOem
CharToOemBuff
Conceptual
OemToCharBuff
Reference
Strings
minutes to read • Edit Online
Translates a specified number of characters in a string from the OEM-defined character set into either an ANSI or a
wide-character string.
Syntax
BOOL OemToCharBuffA(
LPCSTR lpszSrc,
LPSTR lpszDst,
DWORD cchDstLength
);
Parameters
lpszSrc
Type: LPCSTR
One or more characters from the OEM-defined character set.
lpszDst
Type: LPTSTR
The destination buffer, which receives the translated string. If the OemToCharBuff function is being used as an
ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the
lpszSrc parameter. This cannot be done if the OemToCharBuff function is being used as a wide-character function.
cchDstLength
Type: DWORD
The number of characters to be translated in the buffer identified by the lpszSrc parameter.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Remarks
Unlike the OemToChar function, the OemToCharBuff function does not stop converting characters when it
encounters a null character in the buffer pointed to by lpszSrc. The OemToCharBuff function converts all
cchDstLength characters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOem
CharToOemBuff
Conceptual
OemToChar
Reference
Strings
minutes to read • Edit Online
Translates a specified number of characters in a string from the OEM-defined character set into either an ANSI or a
wide-character string.
Syntax
BOOL OemToCharBuffW(
LPCSTR lpszSrc,
LPWSTR lpszDst,
DWORD cchDstLength
);
Parameters
lpszSrc
Type: LPCSTR
One or more characters from the OEM-defined character set.
lpszDst
Type: LPTSTR
The destination buffer, which receives the translated string. If the OemToCharBuff function is being used as an
ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the
lpszSrc parameter. This cannot be done if the OemToCharBuff function is being used as a wide-character function.
cchDstLength
Type: DWORD
The number of characters to be translated in the buffer identified by the lpszSrc parameter.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Remarks
Unlike the OemToChar function, the OemToCharBuff function does not stop converting characters when it
encounters a null character in the buffer pointed to by lpszSrc. The OemToCharBuff function converts all
cchDstLength characters.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOem
CharToOemBuff
Conceptual
OemToChar
Reference
Strings
minutes to read • Edit Online
Translates a string from the OEM-defined character set into either an ANSI or a wide-character string.
Warning Do not use. See Security Considerations.
Syntax
BOOL OemToCharW(
LPCSTR pSrc,
LPWSTR pDst
);
Parameters
pSrc
Type: LPCSTR
A null-terminated string of characters from the OEM-defined character set.
pDst
Type: LPTSTR
The destination buffer, which receives the translated string. If the OemToChar function is being used as an ANSI
function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc
parameter. This cannot be done if OemToChar is being used as a wide-character function.
Return value
Type: BOOL
The return value is always nonzero except when you pass the same address to lpszSrc and lpszDst in the widecharacter version of the function. In this case the function returns zero and GetLastError returns
ERROR_INVALID_ADDRESS .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
CharToOem
CharToOemBuff
Conceptual
OemToCharBuff
Reference
Strings
minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of Windows.]
Creates an array of handles to icons that are extracted from a specified file.
Syntax
UINT PrivateExtractIconsA(
LPCSTR szFileName,
int
nIconIndex,
int
cxIcon,
int
cyIcon,
HICON *phicon,
UINT *piconid,
UINT nIcons,
UINT flags
);
Parameters
szFileName
Type: LPCTSTR
The path and name of the file from which the icon(s) are to be extracted.
nIconIndex
Type: int
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.
cxIcon
Type: int
The horizontal icon size wanted. See Remarks.
cyIcon
Type: int
The vertical icon size wanted. See Remarks.
phicon
Type: HICON*
A pointer to the returned array of icon handles.
piconid
Type: UINT*
A pointer to a returned resource identifier for the icon that best fits the current display device. The returned
identifier is 0xFFFFFFFF if the identifier is not available for this format. The returned identifier is 0 if the identifier
cannot otherwise be obtained.
nIcons
Type: UINT
The number of icons to extract from the file. This parameter is only valid when extracting from .exe and .dll files.
flags
Type: UINT
Specifies flags that control this function. These flags are the LR_* flags used by the LoadImage function.
Return value
Type: UINT
If the phiconparameter is NULL and this function succeeds, then the return value is the number of icons in the file.
If the function fails then the return value is 0.
If the phicon parameter is not NULL and the function succeeds, then the return value is the number of icons
extracted. Otherwise, the return value is 0xFFFFFFFF if the file is not found.
Remarks
This function extracts from executable (.exe), DLL (.dll), icon (.ico), cursor (.cur), animated cursor (.ani), and bitmap
(.bmp) files. Extractions from Windows 3.x 16-bit executables (.exe or .dll) are also supported.
The cxIcon and cyIcon parameters specify the size of the icons to extract. Two sizes can be extracted by putting the
first size in the LOWORD of the parameter and the second size in the HIWORD. For example, MAKELONG(24, 48) for
both the cxIcon and cyIcon parameters would extract both 24 and 48 size icons.
You must destroy all icons extracted by PrivateExtractIcons by calling the DestroyIcon function.
This function was not included in the SDK headers and libraries until Windows XP Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the function
using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DestroyIcon
ExtractIcon
ExtractIconEx
Icons
Reference
minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of Windows.]
Creates an array of handles to icons that are extracted from a specified file.
Syntax
UINT PrivateExtractIconsW(
LPCWSTR szFileName,
int
nIconIndex,
int
cxIcon,
int
cyIcon,
HICON *phicon,
UINT
*piconid,
UINT
nIcons,
UINT
flags
);
Parameters
szFileName
Type: LPCTSTR
The path and name of the file from which the icon(s) are to be extracted.
nIconIndex
Type: int
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.
cxIcon
Type: int
The horizontal icon size wanted. See Remarks.
cyIcon
Type: int
The vertical icon size wanted. See Remarks.
phicon
Type: HICON*
A pointer to the returned array of icon handles.
piconid
Type: UINT*
A pointer to a returned resource identifier for the icon that best fits the current display device. The returned
identifier is 0xFFFFFFFF if the identifier is not available for this format. The returned identifier is 0 if the identifier
cannot otherwise be obtained.
nIcons
Type: UINT
The number of icons to extract from the file. This parameter is only valid when extracting from .exe and .dll files.
flags
Type: UINT
Specifies flags that control this function. These flags are the LR_* flags used by the LoadImage function.
Return value
Type: UINT
If the phiconparameter is NULL and this function succeeds, then the return value is the number of icons in the file.
If the function fails then the return value is 0.
If the phicon parameter is not NULL and the function succeeds, then the return value is the number of icons
extracted. Otherwise, the return value is 0xFFFFFFFF if the file is not found.
Remarks
This function extracts from executable (.exe), DLL (.dll), icon (.ico), cursor (.cur), animated cursor (.ani), and bitmap
(.bmp) files. Extractions from Windows 3.x 16-bit executables (.exe or .dll) are also supported.
The cxIcon and cyIcon parameters specify the size of the icons to extract. Two sizes can be extracted by putting the
first size in the LOWORD of the parameter and the second size in the HIWORD. For example, MAKELONG(24, 48) for
both the cxIcon and cyIcon parameters would extract both 24 and 48 size icons.
You must destroy all icons extracted by PrivateExtractIcons by calling the DestroyIcon function.
This function was not included in the SDK headers and libraries until Windows XP Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the function
using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DestroyIcon
ExtractIcon
ExtractIconEx
Icons
Reference
minutes to read • Edit Online
Deletes a menu item or detaches a submenu from the specified menu. If the menu item opens a drop-down menu
or submenu, RemoveMenu does not destroy the menu or its handle, allowing the menu to be reused. Before this
function is called, the GetSubMenu function should retrieve a handle to the drop-down menu or submenu.
Syntax
BOOL RemoveMenu(
HMENU hMenu,
UINT uPosition,
UINT uFlags
);
Parameters
hMenu
Type: HMENU
A handle to the menu to be changed.
uPosition
Type: UINT
The menu item to be deleted, as determined by the uFlags parameter.
uFlags
Type: UINT
Indicates how the uPosition parameter is interpreted. This parameter must be one of the following values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
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
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that uPosition gives the zero-based relative position
of the menu item.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreatePopupMenu
DeleteMenu
DrawMenuBar
GetSubMenu
Menus
Reference
minutes to read • Edit Online
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.
Syntax
BOOL SetCaretBlinkTime(
UINT uMSeconds
);
Parameters
uMSeconds
Type: UINT
The new blink time, in milliseconds.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. 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 application that allow the user to set the blink
time, such as a Control Panel applet.
If you change the blink time, subsequently activated applications will use the modified blink time, even if you
restore the previous blink time when you lose the keyboard focus or become inactive. This is due to the
multithreaded environment, where deactivation of your application is not synchronized with the activation of
another application. This feature allows the system to activate another application even if the current application is
not responding.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
GetCaretBlinkTime
Reference
minutes to read • Edit Online
Moves the caret to the specified coordinates. If the window that owns the caret was created with the CS_OWNDC
class style, then the specified coordinates are subject to the mapping mode of the device context associated with
that window.
Syntax
BOOL SetCaretPos(
int X,
int Y
);
Parameters
X
Type: int
The new x-coordinate of the caret.
Y
Type: int
The new y-coordinate of the caret.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
SetCaretPos moves the caret whether 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.
DPI Virtualization
This API does not participate in DPI virtualization. The provided position is interpreted as logical coordinates in terms
of the window associated with the caret. The calling thread is not taken into consideration.
Examples
For an example, see Creating and Displaying a Caret.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
GetCaretPos
HideCaret
Reference
ShowCaret
minutes to read • Edit Online
Sets the cursor shape.
Syntax
HCURSOR SetCursor(
HCURSOR hCursor
);
Parameters
hCursor
Type: HCURSOR
A handle to the cursor. The cursor must have been created by the CreateCursor function or loaded by the
LoadCursor or LoadImage function. If this parameter is NULL , the cursor is removed from the screen.
Return value
Type: HCURSOR
The return value is the handle to the previous cursor, if there was one.
If there was no previous cursor, the return value is NULL .
Remarks
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.
Examples
For an example, see Displaying a Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateCursor
Cursors
GetCursor
GetSystemMetrics
LoadCursor
LoadImage
Other Resources
Reference
SetCursorPos
ShowCursor
minutes to read • Edit Online
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 call, the system automatically adjusts the coordinates so that the cursor
stays within the rectangle.
Syntax
BOOL SetCursorPos(
int X,
int Y
);
Parameters
X
Type: int
The new x-coordinate of the cursor, in screen coordinates.
Y
Type: int
The new y-coordinate of the cursor, in screen coordinates.
Return value
Type: BOOL
Returns nonzero if successful or zero otherwise. 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 the window's client
area.
The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.
The input desktop must be the current desktop when you call SetCursorPos . Call OpenInputDesktop to determine
whether the current desktop is the input desktop. If it is not, call SetThreadDesktop with the HDESK returned by
OpenInputDesktop to switch to that desktop.
Examples
For an example, see Using the Keyboard to Move the Cursor.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ClipCursor
Conceptual
Cursors
GetCursorPos
Reference
SetCaretPos
SetCursor
ShowCursor
minutes to read • Edit Online
Assigns a new menu to the specified window.
Syntax
BOOL SetMenu(
HWND hWnd,
HMENU hMenu
);
Parameters
hWnd
Type: HWND
A handle to the window to which the menu is to be assigned.
hMenu
Type: HMENU
A handle to the new menu. If this parameter is NULL , the window's current menu is removed.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The window is redrawn to reflect the menu change. A menu can be assigned to any window that is not a child
window.
The SetMenu function replaces the previous menu, if any, but it does not destroy it. An application should call the
DestroyMenu function to accomplish this task.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DestroyMenu
GetMenu
Menus
Reference
minutes to read • Edit Online
Sets the default menu item for the specified menu.
Syntax
BOOL SetMenuDefaultItem(
HMENU hMenu,
UINT uItem,
UINT fByPos
);
Parameters
hMenu
Type: HMENU
A handle to the menu to set the default item for.
uItem
Type: UINT
The identifier or position of the new default menu item or -1 for no default item. The meaning of this parameter
depends on the value of fByPos.
fByPos
Type: UINT
The meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu item
position. See About Menus for more information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
GetMenuDefaultItem
Menus
Reference
minutes to read • Edit Online
Sets information for a specified menu.
Syntax
BOOL SetMenuInfo(
HMENU
,
LPCMENUINFO
);
Parameters
arg1
Type: HMENU
A handle to a menu.
arg2
Type: LPCMENUINFO
A pointer to a MENUINFO structure for the menu.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Menus
minutes to read • Edit Online
Associates the specified bitmap with a menu item. Whether the menu item is selected or clear, the system displays
the appropriate bitmap next to the menu item.
Syntax
BOOL SetMenuItemBitmaps(
HMENU hMenu,
UINT
uPosition,
UINT
uFlags,
HBITMAP hBitmapUnchecked,
HBITMAP hBitmapChecked
);
Parameters
hMenu
Type: HMENU
A handle to the menu containing the item to receive new check-mark bitmaps.
uPosition
Type: UINT
The menu item to be changed, as determined by the uFlags parameter.
uFlags
Type: UINT
Specifies how the uPosition parameter is to be interpreted. The uFlags parameter must be one of the following
values.
VA L UE
MF
_BY
CO
MM
AN
D
0x0
000
000
0L
M EA N IN G
Indicates that uPosition gives the identifier of the menu item.
If neither MF_BYCOMMAND nor MF_BYPOSITION is
specified, MF_BYCOMMAND is the default flag.
MF
_BY
PO
SITI
ON
0x0
000
040
0L
Indicates that uPosition gives the zero-based relative position
of the menu item.
hBitmapUnchecked
Type: HBITMAP
A handle to the bitmap displayed when the menu item is not selected.
hBitmapChecked
Type: HBITMAP
A handle to the bitmap displayed when the menu item is selected.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If either the hBitmapUnchecked or hBitmapChecked parameter is NULL , the system displays nothing next to the
menu item for the corresponding check state. If both parameters are NULL , the system displays the default checkmark bitmap when the item is selected, and removes the bitmap when the item is not selected.
When the menu is destroyed, these bitmaps are not destroyed; it is up to the application to destroy them.
The selected and clear bitmaps should be monochrome. The system uses the Boolean AND operator to combine
bitmaps with the menu so that the white part becomes transparent and the black part becomes the menu-item
color. If you use color bitmaps, the results may be undesirable.
Use the GetSystemMetrics function with the CXMENUCHECK and CYMENUCHECK values to retrieve the bitmap
dimensions.
Examples
For an example, see Simulating Check Boxes in a Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Menus
minutes to read • Edit Online
Changes information about a menu item.
Syntax
BOOL SetMenuItemInfoA(
HMENU
hmenu,
UINT
item,
BOOL
fByPositon,
LPCMENUITEMINFOA lpmii
);
Parameters
hmenu
Type: HMENU
A handle to the menu that contains the menu item.
item
Type: UINT
The identifier or position of the menu item to change. The meaning of this parameter depends on the value of
fByPosition.
fByPositon
Type: BOOL
The meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu item
position. See About Menus for more information.
lpmii
Type: LPMENUITEMINFO
A pointer to a MENUITEMINFO structure that contains information about the menu item and specifies which menu
item attributes to change.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
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. See Owner-Drawn Menus and the WM_MENUCHAR Message for more
information.
Examples
For an example, see Example of Owner-Drawn Menu Items.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DrawMenuBar
GetMenuItemInfo
MENUITEMINFO
Menus
Reference
minutes to read • Edit Online
Changes information about a menu item.
Syntax
BOOL SetMenuItemInfoW(
HMENU
hmenu,
UINT
item,
BOOL
fByPositon,
LPCMENUITEMINFOW lpmii
);
Parameters
hmenu
Type: HMENU
A handle to the menu that contains the menu item.
item
Type: UINT
The identifier or position of the menu item to change. The meaning of this parameter depends on the value of
fByPosition.
fByPositon
Type: BOOL
The meaning of uItem. If this parameter is FALSE , uItem is a menu item identifier. Otherwise, it is a menu item
position. See About Menus for more information.
lpmii
Type: LPMENUITEMINFO
A pointer to a MENUITEMINFO structure that contains information about the menu item and specifies which menu
item attributes to change.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, use the GetLastError function.
Remarks
The application must call the DrawMenuBar function whenever a menu changes, whether the menu is in a
displayed window.
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. See Owner-Drawn Menus and the WM_MENUCHAR Message for more
information.
Examples
For an example, see Example of Owner-Drawn Menu Items.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
DrawMenuBar
GetMenuItemInfo
MENUITEMINFO
Menus
Reference
minutes to read • Edit Online
Sets the position of the cursor in physical coordinates.
Syntax
BOOL SetPhysicalCursorPos(
int X,
int Y
);
Parameters
X
Type: int
The new x-coordinate of the cursor, in physical coordinates.
Y
Type: int
The new y-coordinate of the cursor, in physical coordinates.
Return value
Type: BOOL
TRUE if successful; otherwise FALSE .
Remarks
For a description of the difference between logicial coordinates and physical coordinates, see
PhysicalToLogicalPoint.
GetLastError can be called to get more information about any error that is generated.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ClipCursor
Conceptual
Cursors
GetCursorPos
GetPhysicalCursorPos
Reference
SetCaretPos
SetCursor
SetCursorPos
ShowCursor
minutes to read • Edit Online
Enables an application to customize the system cursors. It replaces the contents of the system cursor specified by
the id parameter with the contents of the cursor specified by the hcur parameter and then destroys hcur.
Syntax
BOOL SetSystemCursor(
HCURSOR hcur,
DWORD id
);
Parameters
hcur
Type: HCURSOR
A handle to the cursor. The function replaces the contents of the system cursor specified by id with the contents of
the cursor handled by hcur.
The system destroys hcur by calling the DestroyCursor function. Therefore, hcur cannot be a cursor loaded using
the LoadCursor function. To specify a cursor loaded from a resource, copy the cursor using the CopyCursor
function, then pass the copy to SetSystemCursor .
id
Type: DWORD
The system cursor to replace with the contents of hcur. This parameter can be one of the following values.
VA L UE
M EA N IN G
Standard arrow and small hourglass
OC
R_A
PPS
TAR
TIN
G
326
50
Standard arrow
OC
R_N
OR
MA
L
325
12
Crosshair
OC
R_C
RO
SS
325
15
Hand
OC
R_H
AN
D
326
49
Arrow and question mark
OC
R_H
ELP
326
51
I-beam
OC
R_I
BEA
M
325
13
Slashed circle
OC
R_N
O
326
48
Four-pointed arrow pointing north, south, east, and west
OC
R_S
IZE
ALL
326
46
Double-pointed arrow pointing northeast and southwest
OC
R_S
IZE
NES
W
326
43
Double-pointed arrow pointing north and south
OC
R_S
IZE
NS
326
45
Double-pointed arrow pointing northwest and southeast
OC
R_S
IZE
NW
SE
326
42
Double-pointed arrow pointing west and east
OC
R_S
IZE
WE
326
44
Vertical arrow
OC
R_U
P
325
16
Hourglass
OC
R_
WAI
T
325
14
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
For an application to use any of the OCR_ constants, the constant OEMRESOURCE must be defined before the
Windows.h header file is included.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Cursors
DestroyCursor
LoadCursor
LoadCursorFromFile
Reference
SetCursor
minutes to read • Edit Online
Makes the caret visible on the screen at the caret's current position. When the caret becomes visible, it begins
flashing automatically.
Syntax
BOOL ShowCaret(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A 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 value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
ShowCaret shows the caret only if the specified window owns the caret, the caret has a shape, and the caret has
not been hidden two or more times in a row. If one or more of these conditions is not met, ShowCaret 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 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.
Examples
For an example, see Creating and Displaying a Caret.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Carets
Conceptual
CreateCaret
DestroyCaret
GetCaretPos
HideCaret
Reference
SetCaretPos
minutes to read • Edit Online
Displays or hides the cursor.
Syntax
int ShowCursor(
BOOL bShow
);
Parameters
bShow
Type: BOOL
If bShow is TRUE , the display count is incremented by one. If bShow is FALSE , the display count is decremented by
one.
Return value
Type: int
The return value specifies the new display counter.
Remarks
Windows 8 : Call GetCursorInfo to determine the cursor visibility.
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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
ClipCursor
Conceptual
Cursors
GetCursorPos
Reference
SetCursor
SetCursorPos
minutes to read • Edit Online
Contains extended parameters for the TrackPopupMenuEx function.
Syntax
typedef struct tagTPMPARAMS {
UINT cbSize;
RECT rcExclude;
} TPMPARAMS;
Members
cbSize
Type: UINT
The size of structure, in bytes.
rcExclude
Type: RECT
The rectangle to be excluded when positioning the window, in screen coordinates.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Header
winuser.h (include Windows.h)
See also
Conceptual
Menus
Reference
TrackPopupMenuEx
minutes to read • Edit Online
Displays a shortcut menu at the specified location and tracks the selection of items on the menu. The shortcut
menu can appear anywhere on the screen.
Syntax
BOOL TrackPopupMenu(
HMENU
hMenu,
UINT
uFlags,
int
x,
int
y,
int
nReserved,
HWND
hWnd,
const RECT *prcRect
);
Parameters
hMenu
Type: HMENU
A 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 a handle to a submenu associated with an existing menu
item.
uFlags
Type: UINT
Use zero of more of these flags to specify function options.
Use one of the following flags to specify how the function positions the shortcut menu horizontally.
VA L UE
TP
M_
CE
NTE
RAL
IGN
0x0
004
L
M EA N IN G
Centers the shortcut menu horizontally relative to the
coordinate specified by the x parameter.
TP
M_
LEF
TAL
IGN
0x0
000
L
TP
M_
RIG
HTA
LIG
N
0x0
008
L
Positions the shortcut menu so that its left side is aligned with
the coordinate specified by the x parameter.
Positions the shortcut menu so that its right side is aligned
with the coordinate specified by the x parameter.
Use one of the following flags to specify how the function positions the shortcut menu vertically.
VA L UE
TP
M_
BOT
TO
MA
LIG
N
0x0
020
L
TP
M_
TOP
ALI
GN
0x0
000
L
TP
M_
VCE
NTE
RAL
IGN
0x0
010
L
M EA N IN G
Positions the shortcut menu so that its bottom side is aligned
with the coordinate specified by the y parameter.
Positions the shortcut menu so that its top side is aligned with
the coordinate specified by the y parameter.
Centers the shortcut menu vertically relative to the coordinate
specified by the y parameter.
Use the following flags to control discovery of the user selection without having to set up a parent window for the
menu.
VA L UE
TP
M_
NO
NO
TIF
Y
0x0
080
L
TP
M_
RET
UR
NC
MD
0x0
100
L
M EA N IN G
The function does not send notification messages when the
user clicks a menu item.
The function returns the menu item identifier of the user's
selection in the return value.
Use one of the following flags to specify which mouse button the shortcut menu tracks.
VA L UE
TP
M_
LEF
TBU
TTO
N
0x0
000
L
TP
M_
RIG
HTB
UTT
ON
0x0
002
L
M EA N IN G
The user can select menu items with only the left mouse
button.
The user can select menu items with both the left and right
mouse buttons.
Use any reasonable combination of the following flags to modify the animation of a menu. For example, by
selecting a horizontal and a vertical flag, you can achieve diagonal animation.
VA L UE
M EA N IN G
Animates the menu from right to left.
TP
M_
HO
RNE
GA
NI
MA
TIO
N
0x0
800
L
Animates the menu from left to right.
TP
M_
HO
RP
OS
ANI
MA
TIO
N
0x0
400
L
Displays menu without animation.
TP
M_
NO
ANI
MA
TIO
N
0x4
000
L
Animates the menu from bottom to top.
TP
M_
VER
NE
GA
NI
MA
TIO
N
0x2
000
L
Animates the menu from top to bottom.
TP
M_
VER
PO
SA
NI
MA
TIO
N
0x1
000
L
For any animation to occur, the SystemParametersInfo function must set SPI_SETMENUANIMATION . Also, all the
TPM_*ANIMATION flags, except TPM_NOANIMATION , are ignored if menu fade animation is on. For more
information, see the SPI_GETMENUFADE flag in SystemParametersInfo .
Use the TPM_RECURSE flag to display a menu when another menu is already displayed. This is intended to
support context menus within a menu.
For right-to-left text layout, use TPM_L AYOUTRTL . By default, the text layout is left-to-right.
x
Type: int
The horizontal location of the shortcut menu, in screen coordinates.
y
Type: int
The vertical location of the shortcut menu, in screen coordinates.
nReserved
Type: int
Reserved; must be zero.
hWnd
Type: HWND
A 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
Type: const RECT*
Ignored.
Return value
Type: BOOL
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, 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
Call GetSystemMetrics with SM_MENUDROPALIGNMENT to determine the correct horizontal alignment flag
(TPM_LEFTALIGN or TPM_RIGHTALIGN ) and/or horizontal animation direction flag
(TPM_HORPOSANIMATION or TPM_HORNEGANIMATION ) to pass to TrackPopupMenu or
TrackPopupMenuEx. This is essential for creating an optimal user experience, especially when developing Microsoft
Tablet PC applications.
To specify an area of the screen that the menu should not overlap, use the TrackPopupMenuEx function
To display a context menu for a notification icon, the current window must be the foreground window before the
application calls TrackPopupMenu or TrackPopupMenuEx. Otherwise, the menu will not disappear when the user
clicks outside of the menu or the window that created the menu (if it is visible). If the current window is a child
window, you must set the (top-level) parent window as the foreground window.
However, when the current window is the foreground window, the second time this menu is displayed, it appears
and then immediately disappears. To correct this, you must force a task switch to the application that called
TrackPopupMenu . This is done by posting a benign message to the window or thread, as shown in the following
code sample:
SetForegroundWindow(hDlg);
// Display the menu
TrackPopupMenu( hSubMenu,
TPM_RIGHTBUTTON,
pt.x,
pt.y,
0,
hDlg,
NULL);
PostMessage(hDlg, WM_NULL, 0, 0);
Examples
For an example, see Displaying a Shortcut Menu.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreatePopupMenu
GetSubMenu
Menus
Reference
TrackPopupMenuEx
WM_COMMAND
minutes to read • Edit Online
Displays a shortcut menu at the specified location and tracks the selection of items on the shortcut menu. The
shortcut menu can appear anywhere on the screen.
Syntax
BOOL TrackPopupMenuEx(
HMENU
hMenu,
UINT
uFlags,
int
x,
int
y,
HWND
hwnd,
LPTPMPARAMS lptpm
);
Parameters
hMenu
Type: HMENU
A 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 a handle to a submenu
associated with an existing menu item.
uFlags
Type: UINT
Specifies function options.
Use one of the following flags to specify how the function positions the shortcut menu horizontally.
VA L UE
TP
M_
CE
NTE
RAL
IGN
0x0
004
L
M EA N IN G
Centers the shortcut menu horizontally relative to the
coordinate specified by the x parameter.
TP
M_
LEF
TAL
IGN
0x0
000
L
TP
M_
RIG
HTA
LIG
N
0x0
008
L
Positions the shortcut menu so that its left side is aligned with
the coordinate specified by the x parameter.
Positions the shortcut menu so that its right side is aligned
with the coordinate specified by the x parameter.
Use one of the following flags to specify how the function positions the shortcut menu vertically.
VA L UE
TP
M_
BOT
TO
MA
LIG
N
0x0
020
L
TP
M_
TOP
ALI
GN
0x0
000
L
TP
M_
VCE
NTE
RAL
IGN
0x0
010
L
M EA N IN G
Positions the shortcut menu so that its bottom side is aligned
with the coordinate specified by the y parameter.
Positions the shortcut menu so that its top side is aligned with
the coordinate specified by the y parameter.
Centers the shortcut menu vertically relative to the coordinate
specified by the y parameter.
Use the following flags to control discovery of the user selection without having to set up a parent window for the
menu.
VA L UE
TP
M_
NO
NO
TIF
Y
0x0
080
L
TP
M_
RET
UR
NC
MD
0x0
100
L
M EA N IN G
The function does not send notification messages when the
user clicks a menu item.
The function returns the menu item identifier of the user's
selection in the return value.
Use one of the following flags to specify which mouse button the shortcut menu tracks.
VA L UE
TP
M_
LEF
TBU
TTO
N
0x0
000
L
TP
M_
RIG
HTB
UTT
ON
0x0
002
L
M EA N IN G
The user can select menu items with only the left mouse
button.
The user can select menu items with both the left and right
mouse buttons.
Use any reasonable combination of the following flags to modify the animation of a menu. For example, by
selecting a horizontal and a vertical flag, you can achieve diagonal animation.
VA L UE
M EA N IN G
Animates the menu from right to left.
TP
M_
HO
RNE
GA
NI
MA
TIO
N
0x0
800
L
Animates the menu from left to right.
TP
M_
HO
RP
OS
ANI
MA
TIO
N
0x0
400
L
Displays menu without animation.
TP
M_
NO
ANI
MA
TIO
N
0x4
000
L
Animates the menu from bottom to top.
TP
M_
VER
NE
GA
NI
MA
TIO
N
0x2
000
L
Animates the menu from top to bottom.
TP
M_
VER
PO
SA
NI
MA
TIO
N
0x1
000
L
For any animation to occur, the SystemParametersInfo function must set SPI_SETMENUANIMATION . Also, all the
TPM_*ANIMATION flags, except TPM_NOANIMATION , are ignored if menu fade animation is on. For more
information, see the SPI_GETMENUFADE flag in SystemParametersInfo .
Use the TPM_RECURSE flag to display a menu when another menu is already displayed. This is intended to
support context menus within a menu.
Use one of the following flags to specify whether to accommodate horizontal or vertical alignment.
VA L UE
TP
M_
HO
RIZ
ON
TAL
0x0
000
L
TP
M_
VER
TIC
AL
0x0
040
L
M EA N IN G
If the menu cannot be shown at the specified location without
overlapping the excluded rectangle, the system tries to
accommodate the requested horizontal alignment before the
requested vertical alignment.
If the menu cannot be shown at the specified location without
overlapping the excluded rectangle, the system tries to
accommodate the requested vertical alignment before the
requested horizontal alignment.
The excluded rectangle is a portion of the screen that the menu should not overlap; it is specified by the lptpm
parameter.
For right-to-left text layout, use TPM_L AYOUTRTL . By default, the text layout is left-to-right.
x
Type: int
The horizontal location of the shortcut menu, in screen coordinates.
y
Type: int
The vertical location of the shortcut menu, in screen coordinates.
hwnd
Type: HWND
A 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 fuFlags 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.
lptpm
Type: LPTPMPARAMS
A pointer to a TPMPARAMS structure that specifies an area of the screen the menu should not overlap. This
parameter can be NULL .
Return value
Type: BOOL
If you specify TPM_RETURNCMD in the fuFlags 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, the return
value is zero.
If you do not specify TPM_RETURNCMD in the fuFlags parameter, the return value is nonzero if the function
succeeds and zero if it fails. To get extended error information, call GetLastError.
Remarks
Call GetSystemMetrics with SM_MENUDROPALIGNMENT to determine the correct horizontal alignment flag
(TPM_LEFTALIGN or TPM_RIGHTALIGN ) and/or horizontal animation direction flag
(TPM_HORPOSANIMATION or TPM_HORNEGANIMATION ) to pass to TrackPopupMenu or
TrackPopupMenuEx . This is essential for creating an optimal user experience, especially when developing
Microsoft Tablet PC applications.
To display a context menu for a notification icon, the current window must be the foreground window before the
application calls TrackPopupMenu or TrackPopupMenuEx . Otherwise, the menu will not disappear when the user
clicks outside of the menu or the window that created the menu (if it is visible). If the current window is a child
window, you must set the (top-level) parent window as the foreground window.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreatePopupMenu
GetSubMenu
Menus
Reference
TPMPARAMS
WM_COMMAND
minutes to read • Edit Online
Processes accelerator keys for menu commands. The function translates a WM_KEYDOWN or WM_SYSKEYDOWN
message to a WM_COMMAND or WM_SYSCOMMAND message (if there is an entry for the key in the specified
accelerator table) and then sends the WM_COMMAND or WM_SYSCOMMAND message directly to the
specified window procedure. TranslateAccelerator does not return until the window procedure has processed the
message.
Syntax
int TranslateAcceleratorA(
HWND hWnd,
HACCEL hAccTable,
LPMSG lpMsg
);
Parameters
hWnd
Type: HWND
A handle to the window whose messages are to be translated.
hAccTable
Type: HACCEL
A handle to the 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
Type: LPMSG
A pointer to an MSG structure that contains message information retrieved from the calling thread's message
queue using the GetMessage or PeekMessage function.
Return value
Type: int
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
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 WM_INITMENU and
WM_INITMENUPOPUP messages, 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 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.
Examples
For an example, see Creating Accelerators for Font Attributes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateAcceleratorTable
GetMessage
Keyboard Accelerators
LoadAccelerators
MSG
PeekMessage
Reference
SetCapture
TranslateMessage
WM_COMMAND
WM_INITMENU
WM_INITMENUPOPUP
WM_KEYDOWN
WM_SYSCOMMAND
WM_SYSKEYDOWN
minutes to read • Edit Online
Processes accelerator keys for menu commands. The function translates a WM_KEYDOWN or WM_SYSKEYDOWN
message to a WM_COMMAND or WM_SYSCOMMAND message (if there is an entry for the key in the specified
accelerator table) and then sends the WM_COMMAND or WM_SYSCOMMAND message directly to the
specified window procedure. TranslateAccelerator does not return until the window procedure has processed the
message.
Syntax
int TranslateAcceleratorW(
HWND hWnd,
HACCEL hAccTable,
LPMSG lpMsg
);
Parameters
hWnd
Type: HWND
A handle to the window whose messages are to be translated.
hAccTable
Type: HACCEL
A handle to the 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
Type: LPMSG
A pointer to an MSG structure that contains message information retrieved from the calling thread's message
queue using the GetMessage or PeekMessage function.
Return value
Type: int
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
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 WM_INITMENU and
WM_INITMENUPOPUP messages, 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 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.
Examples
For an example, see Creating Accelerators for Font Attributes.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
CreateAcceleratorTable
GetMessage
Keyboard Accelerators
LoadAccelerators
MSG
PeekMessage
Reference
SetCapture
TranslateMessage
WM_COMMAND
WM_INITMENU
WM_INITMENUPOPUP
WM_KEYDOWN
WM_SYSCOMMAND
WM_SYSKEYDOWN
minutes to read • Edit Online
Writes formatted data to the specified buffer. Any arguments are converted and copied to the output buffer
according to the corresponding format specification in the format 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.
Note Do not use. Consider using one of the following functions instead: StringCbPrintf, StringCbPrintfEx, StringCchPrintf, or
StringCchPrintfEx. See Security Considerations.
Syntax
int WINAPIV wsprintfA(
LPSTR ,
LPCSTR ,
...
);
Parameters
arg1
Type: LPTSTR
The buffer that is to receive the formatted output. The maximum size of the buffer is 1,024 bytes.
arg2
Type: LPCTSTR
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.
...
One or more optional arguments. The number and type of argument parameters depend on the corresponding
format-control specifications in the lpFmt parameter.
Return value
Type: int
If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the
terminating null character.
If the function fails, the return value is less than the length of the expected output. To get extended error
information, call GetLastError.
Remarks
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.
F IEL D
M EA N IN G
-
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 values.
c
Single character. This value is interpreted as type
WCHAR if the calling application defines Unicode and
as type __wchar_t otherwise.
C
Single character. This value is interpreted as type
__wchar_t if the calling application defines Unicode and
as type WCHAR otherwise.
d
Signed decimal integer. This value is equivalent to
i
.
hc
,
hC
hd
Single character. The wsprintf function ignores
character arguments with a numeric value of zero. This
value is always interpreted as type __wchar_t , even
when the calling application defines Unicode.
Signed short integer argument.
hs
,
hS
hu
String. This value is always interpreted as type LPSTR,
even when the calling application defines Unicode.
Unsigned short integer.
i
Signed decimal integer. This value is equivalent to
d
.
Ix
,
IX
64-bit unsigned hexadecimal integer in lowercase or
uppercase on 64-bit platforms, 32-bit unsigned
hexadecimal integer in lowercase or uppercase on 32-bit
platforms.
lc
,
lC
Single character. The wsprintf function ignores
character arguments with a numeric value of zero. This
value is always interpreted as type WCHAR, even when
the calling application does not define Unicode.
ld
Long signed integer. This value is equivalent to
li
.
Long signed integer. This value is equivalent to
ld
.
li
ls
,
lS
lu
String. This value is always interpreted as type LPWSTR,
even when the calling application does not define
Unicode. This value is equivalent to ws .
Long unsigned integer.
lx
,
lX
p
Long unsigned hexadecimal integer in lowercase or
uppercase.
Pointer. The address is printed using hexadecimal.
s
String. This value is interpreted as type LPWSTR when
the calling application defines Unicode and as type
LPSTR otherwise.
S
u
String. This value is interpreted as type LPSTR when the
calling application defines Unicode and as type LPWSTR
otherwise.
Unsigned integer argument.
x
,
X
Unsigned hexadecimal integer in lowercase or
uppercase.
Note It is important to note that wsprintf uses the C calling convention (_cdecl), rather than the standard call (_stdcall) 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.
To use buffers larger than 1024 bytes, use _snwprintf . For more information, see the documentation for the C runtime library.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Reference
StringCbPrintf
StringCbPrintfEx
StringCbVPrintf
StringCbVPrintfEx
StringCchPrintf
StringCchPrintfEx
StringCchVPrintf
StringCchVPrintfEx
Strings
wvsprintf
minutes to read • Edit Online
Writes formatted data to the specified buffer. Any arguments are converted and copied to the output buffer
according to the corresponding format specification in the format 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.
Note Do not use. Consider using one of the following functions instead: StringCbPrintf, StringCbPrintfEx, StringCchPrintf, or
StringCchPrintfEx. See Security Considerations.
Syntax
int WINAPIV wsprintfW(
LPWSTR ,
LPCWSTR ,
...
);
Parameters
arg1
Type: LPTSTR
The buffer that is to receive the formatted output. The maximum size of the buffer is 1,024 bytes.
arg2
Type: LPCTSTR
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.
...
One or more optional arguments. The number and type of argument parameters depend on the corresponding
format-control specifications in the lpFmt parameter.
Return value
Type: int
If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the
terminating null character.
If the function fails, the return value is less than the length of the expected output. To get extended error
information, call GetLastError.
Remarks
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.
F IEL D
M EA N IN G
-
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 values.
c
Single character. This value is interpreted as type
WCHAR if the calling application defines Unicode and
as type __wchar_t otherwise.
C
Single character. This value is interpreted as type
__wchar_t if the calling application defines Unicode and
as type WCHAR otherwise.
d
Signed decimal integer. This value is equivalent to
i
.
hc
,
hC
hd
Single character. The wsprintf function ignores
character arguments with a numeric value of zero. This
value is always interpreted as type __wchar_t , even
when the calling application defines Unicode.
Signed short integer argument.
hs
,
hS
hu
String. This value is always interpreted as type LPSTR,
even when the calling application defines Unicode.
Unsigned short integer.
i
Signed decimal integer. This value is equivalent to
d
.
Ix
,
IX
64-bit unsigned hexadecimal integer in lowercase or
uppercase on 64-bit platforms, 32-bit unsigned
hexadecimal integer in lowercase or uppercase on 32-bit
platforms.
lc
,
lC
Single character. The wsprintf function ignores
character arguments with a numeric value of zero. This
value is always interpreted as type WCHAR, even when
the calling application does not define Unicode.
ld
Long signed integer. This value is equivalent to
li
.
Long signed integer. This value is equivalent to
ld
.
li
ls
,
lS
lu
String. This value is always interpreted as type LPWSTR,
even when the calling application does not define
Unicode. This value is equivalent to ws .
Long unsigned integer.
lx
,
lX
p
Long unsigned hexadecimal integer in lowercase or
uppercase.
Pointer. The address is printed using hexadecimal.
s
String. This value is interpreted as type LPWSTR when
the calling application defines Unicode and as type
LPSTR otherwise.
S
u
String. This value is interpreted as type LPSTR when the
calling application defines Unicode and as type LPWSTR
otherwise.
Unsigned integer argument.
x
,
X
Unsigned hexadecimal integer in lowercase or
uppercase.
Note It is important to note that wsprintf uses the C calling convention (_cdecl), rather than the standard call (_stdcall) 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.
To use buffers larger than 1024 bytes, use _snwprintf . For more information, see the documentation for the C runtime library.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Reference
StringCbPrintf
StringCbPrintfEx
StringCbVPrintf
StringCbVPrintfEx
StringCchPrintf
StringCchPrintfEx
StringCchVPrintf
StringCchVPrintfEx
Strings
wvsprintf
minutes to read • Edit Online
Writes formatted data to the specified buffer using a pointer to a list of arguments. 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.
Warning Do not use. Consider using one of the following functions instead: StringCbVPrintf, StringCbVPrintfEx, StringCchVPrintf,
or StringCchVPrintfEx. See Security Considerations.
Syntax
int wvsprintfA(
LPSTR ,
LPCSTR ,
va_list arglist
);
Parameters
arg1
Type: LPTSTR
The buffer that is to receive the formatted output. The maximum size of the buffer is 1,024 bytes.
arg2
Type: LPCTSTR
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 wsprintf function.
arglist
Type: va_list
Each element of this 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 value
Type: int
If the function succeeds, the return value is the number of characters stored in the buffer, not counting the
terminating null character.
If the function fails, the return value is less than the length of the expected output. To get extended error
information, call GetLastError.
Remarks
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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Reference
StringCbPrintf
StringCbPrintfEx
StringCbVPrintf
StringCbVPrintfEx
StringCchPrintf
StringCchPrintfEx
StringCchVPrintf
StringCchVPrintfEx
Strings
wsprintf
minutes to read • Edit Online
Writes formatted data to the specified buffer using a pointer to a list of arguments. 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.
Warning Do not use. Consider using one of the following functions instead: StringCbVPrintf, StringCbVPrintfEx, StringCchVPrintf,
or StringCchVPrintfEx. See Security Considerations.
Syntax
int wvsprintfW(
LPWSTR ,
LPCWSTR ,
va_list arglist
);
Parameters
arg1
Type: LPTSTR
The buffer that is to receive the formatted output. The maximum size of the buffer is 1,024 bytes.
arg2
Type: LPCTSTR
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 wsprintf function.
arglist
Type: va_list
Each element of this 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 value
Type: int
If the function succeeds, the return value is the number of characters stored in the buffer, not counting the
terminating null character.
If the function fails, the return value is less than the length of the expected output. To get extended error
information, call GetLastError.
Remarks
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.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winuser.h (include Windows.h)
Librar y
User32.lib
DLL
User32.dll
See also
Conceptual
Reference
StringCbPrintf
StringCbPrintfEx
StringCbVPrintf
StringCbVPrintfEx
StringCchPrintf
StringCchPrintfEx
StringCchVPrintf
StringCchVPrintfEx
Strings
wsprintf
minutes to read • Edit Online
This header is used by Menus and Other Resources. For more information, see:
Menus and Other Resources winver.h contains the following programming interfaces:
Functions
T IT L E
DESC RIP T IO N
GetFileVersionInfoA
Retrieves version information for the specified file.
GetFileVersionInfoExA
Retrieves version information for the specified file.
GetFileVersionInfoExW
Retrieves version information for the specified file.
GetFileVersionInfoSizeA
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSize returns the size, in bytes, of
that information.
GetFileVersionInfoSizeExA
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSizeEx returns the size, in bytes, of
that information.
GetFileVersionInfoSizeExW
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSizeEx returns the size, in bytes, of
that information.
GetFileVersionInfoSizeW
Determines whether the operating system can retrieve version
information for a specified file. If version information is
available, GetFileVersionInfoSize returns the size, in bytes, of
that information.
GetFileVersionInfoW
Retrieves version information for the specified file.
VerFindFileA
Determines where to install a file based on whether it locates
another version of the file in the system. The values
VerFindFile returns in the specified buffers are used in a
subsequent call to the VerInstallFile function.
VerFindFileW
Determines where to install a file based on whether it locates
another version of the file in the system. The values
VerFindFile returns in the specified buffers are used in a
subsequent call to the VerInstallFile function.
VerInstallFileA
Installs the specified file based on information returned from
the VerFindFile function. VerInstallFile decompresses the file, if
necessary, assigns a unique filename, and checks for errors,
such as outdated files.
T IT L E
DESC RIP T IO N
VerInstallFileW
Installs the specified file based on information returned from
the VerFindFile function. VerInstallFile decompresses the file, if
necessary, assigns a unique filename, and checks for errors,
such as outdated files.
VerLanguageNameA
Retrieves a description string for the language associated with
a specified binary Microsoft language identifier.
VerLanguageNameW
Retrieves a description string for the language associated with
a specified binary Microsoft language identifier.
VerQueryValueA
Retrieves specified version information from the specified
version-information resource.
VerQueryValueW
Retrieves specified version information from the specified
version-information resource.
minutes to read • Edit Online
Retrieves version information for the specified file.
Syntax
BOOL GetFileVersionInfoA(
LPCSTR lptstrFilename,
DWORD dwHandle,
DWORD dwLen,
LPVOID lpData
);
Parameters
lptstrFilename
Type: LPCTSTR
The name of the file. If a full path is not specified, the function uses the search sequence specified by the
LoadLibrary function.
dwHandle
Type: DWORD
This parameter is ignored.
dwLen
Type: DWORD
The size, in bytes, of the buffer pointed to by the lpData parameter.
Call the GetFileVersionInfoSize function first to determine the size, in bytes, of a file's version information. The
dwLen member should be equal to or greater than that value.
If the buffer pointed to by lpData is not large enough, the function truncates the file's version information to the size
of the buffer.
lpData
Type: LPVOID
Pointer to a buffer that receives the file-version information.
You can use this value in a subsequent call to the VerQueryValue function to retrieve data from the buffer.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
File version info has fixed and non-fixed part. The fixed part contains information like version number. The nonfixed part contains things like strings. In the past GetFileVersionInfo was taking version information from the
binary (exe/dll). Currently, it is querying fixed version from language neutral file (exe/dll) and the non-fixed part
from mui file, merges them and returns to the user. If the given binary does not have a mui file then behavior is as
in previous version.
Call the GetFileVersionInfoSize function before calling the GetFileVersionInfo function. To retrieve information
from the file-version information buffer, use the VerQueryValue function.
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winver.h (include Windows.h)
Librar y
Version.lib
DLL
Api-ms-win-core-version-l1-1-0.dll
See also
Conceptual
GetFileVersionInfoSize
Reference
VS_VERSIONINFO
VerQueryValue
Version Information
minutes to read • Edit Online
Retrieves version information for the specified file.
Syntax
BOOL GetFileVersionInfoExA(
DWORD dwFlags,
LPCSTR lpwstrFilename,
DWORD dwHandle,
DWORD dwLen,
LPVOID lpData
);
Parameters
dwFlags
Type: DWORD
Controls the MUI DLLs (if any) from which the version resource is extracted. The value of this flag must match the
flags passed to the corresponding GetFileVersionInfoSizeEx call, which was used to determine the buffer size that is
passed in the dwLen parameter. Zero or more of the following flags.
VA L UE
FIL
E_V
ER_
GET
_LO
CAL
ISE
D
0x0
1
FIL
E_V
ER_
GET
_NE
UTR
AL
0x0
2
M EA N IN G
Loads the entire version resource (both strings and binary
version information) from the corresponding MUI file, if
available.
Loads the version resource strings from the corresponding
MUI file, if available, and loads the binary version information
(VS_FIXEDFILEINFO ) from the corresponding languageneutral file, if available.
FIL
E_V
ER_
GET
_PR
EFE
TCH
ED
0x0
4
Indicates a preference for version.dll to attempt to preload the
image outside of the loader lock to avoid contention. This flag
does not change the behavior or semantics of the function.
lpwstrFilename
Type: LPCTSTR
The name of the file. If a full path is not specified, the function uses the search sequence specified by the
LoadLibrary function.
dwHandle
Type: DWORD
This parameter is ignored.
dwLen
Type: DWORD
The size, in bytes, of the buffer pointed to by the lpData parameter.
Call the GetFileVersionInfoSizeEx function first to determine the size, in bytes, of a file's version information. The
dwLen parameter should be equal to or greater than that value.
If the buffer pointed to by lpData is not large enough, the function truncates the file's version information to the size
of the buffer.
lpData
Type: LPVOID
When this function returns, contains a pointer to a buffer that contains the file-version information.
You can use this value in a subsequent call to the VerQueryValue function to retrieve data from the buffer.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Call the GetFileVersionInfoSizeEx function before calling the GetFileVersionInfoEx function. To retrieve
information from the file-version information buffer, use the VerQueryValue function.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
winver.h (include Windows.h)
Librar y
Version.lib
DLL
Api-ms-win-core-version-l1-1-0.dll
See also
Conceptual
GetFileVersionInfo
GetFileVersionInfoSizeEx
Reference
VS_VERSIONINFO
VerQueryValue
Version Information
minutes to read • Edit Online
Retrieves version information for the specified file.
Syntax
BOOL GetFileVersionInfoExW(
DWORD dwFlags,
LPCWSTR lpwstrFilename,
DWORD dwHandle,
DWORD dwLen,
LPVOID lpData
);
Parameters
dwFlags
Type: DWORD
Controls the MUI DLLs (if any) from which the version resource is extracted. The value of this flag must match the
flags passed to the corresponding GetFileVersionInfoSizeEx call, which was used to determine the buffer size that is
passed in the dwLen parameter. Zero or more of the following flags.
VA L UE
FIL
E_V
ER_
GET
_LO
CAL
ISE
D
0x0
1
FIL
E_V
ER_
GET
_NE
UTR
AL
0x0
2
M EA N IN G
Loads the entire version resource (both strings and binary
version information) from the corresponding MUI file, if
available.
Loads the version resource strings from the corresponding
MUI file, if available, and loads the binary version information
(VS_FIXEDFILEINFO ) from the corresponding languageneutral file, if available.
FIL
E_V
ER_
GET
_PR
EFE
TCH
ED
0x0
4
Indicates a preference for version.dll to attempt to preload the
image outside of the loader lock to avoid contention. This flag
does not change the behavior or semantics of the function.
lpwstrFilename
Type: LPCTSTR
The name of the file. If a full path is not specified, the function uses the search sequence specified by the
LoadLibrary function.
dwHandle
Type: DWORD
This parameter is ignored.
dwLen
Type: DWORD
The size, in bytes, of the buffer pointed to by the lpData parameter.
Call the GetFileVersionInfoSizeEx function first to determine the size, in bytes, of a file's version information. The
dwLen parameter should be equal to or greater than that value.
If the buffer pointed to by lpData is not large enough, the function truncates the file's version information to the size
of the buffer.
lpData
Type: LPVOID
When this function returns, contains a pointer to a buffer that contains the file-version information.
You can use this value in a subsequent call to the VerQueryValue function to retrieve data from the buffer.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Call the GetFileVersionInfoSizeEx function before calling the GetFileVersionInfoEx function. To retrieve
information from the file-version information buffer, use the VerQueryValue function.
Requirements
Minimum suppor ted client
Windows Vista [desktop apps only]
Minimum suppor ted ser ver
Windows Server 2008 [desktop apps only]
Target Platform
Windows
Header
winver.h (include Windows.h)
Librar y
Version.lib
DLL
Api-ms-win-core-version-l1-1-0.dll
See also
Conceptual
GetFileVersionInfo
GetFileVersionInfoSizeEx
Reference
VS_VERSIONINFO
VerQueryValue
Version Information
minutes to read • Edit Online
Determines whether the operating system can retrieve version information for a specified file. If version
information is available, GetFileVersionInfoSize returns the size, in bytes, of that information.
Syntax
DWORD GetFileVersionInfoSizeA(
LPCSTR lptstrFilename,
LPDWORD lpdwHandle
);
Parameters
lptstrFilename
Type: LPCTSTR
The name of the file of interest. The function uses the search sequence specified by the LoadLibrary function.
lpdwHandle
Type: LPDWORD
A pointer to a variable that the function sets to zero.
Return value
Type: DWORD
If the function succeeds, the return value is the size, in bytes, of the file's version information.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Call the GetFileVersionInfoSize function before calling the GetFileVersionInfo function. The size returned by
GetFileVersionInfoSize indicates the buffer size required for the version information returned by
GetFileVersionInfo .
Requirements
Minimum suppor ted client
Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver
Windows 2000 Server [desktop apps only]
Target Platform
Windows
Header
winver.h (include Windows.h)
Librar y
Version.lib
DLL
Api-ms-win-core-version-l1-1-0.dll
See also
Conceptual
GetFileVersionInfo
Reference
VS_VERSIONINFO
VerQueryValue
Version Information
minutes to read • Edit Online
Determines whether the operating system can retrieve version information for a specified file. If version
information is available, GetFileVersionInfoSizeEx returns the size, in bytes, of that information.
Syntax
DWORD GetFileVersionInfoSizeExA(
DWORD dwFlags,
LPCSTR lpwstrFilename,
LPDWORD lpdwHandle
);
Parameters
dwFlags
Type: DWORD
Controls which MUI DLLs (if any) from which the v