[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
);
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.
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);