GetRoleText

[This is preliminary documentation and subject to change.]

Retrieves the localized string based on a specified standard role value.

UINT GetRoleText(
  DWORD dwRole,
  LPTSTR lpszRole,
  UINT cchRoleMax
);
 

Parameters

dwRole

Object role value for which the appropriate string will be retrieved. This value must be one of the object role constants.

lpszRole

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

cchRoleMax

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

Return Values

Returns a UINT value that represents the number of characters copied to the string. If lpszRole is NULL, then the return value represents the string's length, not including the null character.

Remarks

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 lpszRole set to NULL is analogous to querying for the length of the role 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   iRoleLength;
LPTSTR lpszRoleString;

// Find out how long the role text string is.
iRoleLength = GetRoleText(ROLE_SYSTEM_MENUITEM, 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.
lpszRoleString = GlobalAllocPtr(GMEM_FIXED, iRoleLength+1);

// Get the string.
GetRoleText(ROLE_SYSTEM_MENUITEM, 
            lpszRoleString, iRoleLength +1);