GetStateText

[This is preliminary documentation and subject to change.]

Retrieves the localized standard adjective string for a single standard state bit.

UINT GetStateText(
  DWORD dwStateBit,
  LPTSTR lpszStateBit,
  UINT cchStateBitMax
);
 

Parameters

dwStateBit

Object state value for which the appropriate state text will be retrieved. This value must be only one of the object state constants.

lpszStateBit

Address of a buffer that will contain the state text string. If this parameter is NULL, the function retrieves the role string's length, not including the null character.

cchStateBitMax

Size of the buffer at the address specified by the lpszStateBit parameter. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

Return Values

Returns the number of characters copied to the string. If the lpszStateBit parameter is NULL, then the return value is the string's length, not including the null character.

Remarks

This function accepts only one bit at a time, not a bitmask.

If the lpszRole parameter is not a valid pointer, the function returns zero and sets an ERROR_INVALID_PARAMETER error value. Applications can retrieve this error value with the GetLastError Win32 function.

Calling this function with lpszStateBit set to NULL is analogous to querying for the length of the state text string. You can use the return value from such a call to dynamically allocate the memory needed to hold the string. The following code fragment illustrates this concept.

UINT   iLength;
LPTSTR lpszString;

// Find out how long the string is.
iLength = GetStateText(STATE_SYSTEM_FOCUSED, NULL, 0);

// Allocate memory for the string. Add one byte to
// length we got in the previous call to make room
// for the null character.
lpszString = GlobalAllocPtr(GMEM_FIXED, iLength + 1);

// Get the string.
GetStateText(STATE_SYSTEM_FOCUSED, lpszString, iLength + 1);