IAccessible::get_accRole method

The IAccessible::get_accRole method retrieves information that describes the role of the specified object. All objects support this property.

Syntax

HRESULT get_accRole(
  VARIANT varChild,
  VARIANT *pvarRole
);

Parameters

varChild

pvarRole

Type: VARIANT*

Address of a VARIANT that receives an object role constant. The vt member must be VT_I4. The lVal member receives an object role constant.

Return Value

Type: HRESULT

If successful, returns S_OK.

If not successful, returns one of the values in the table that follows, or another standard COM error code. Servers return these values, but clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error Description
E_INVALIDARG
An argument is not valid.

Remarks

Clients call GetRoleText to retrieve a localized string that describes the object's role.

Note to server developers:  You must use the predefined role constants.

Server Example

The following example code is a possible implementation of this method for a custom list box that maintains its own list items.
C++
HRESULT STDMETHODCALLTYPE AccServer::get_accRole( 
    VARIANT varChild,
    VARIANT *pvarRole)
{
    if (varChild.vt != VT_I4)
    {
        pvarRole->vt = VT_EMPTY;
        return E_INVALIDARG;
    }
pvarRole->vt = VT_I4;

if (varChild.lVal == CHILDID_SELF)
{
    pvarRole->lVal = ROLE_SYSTEM_LIST;
}
else
{
    pvarRole->lVal = ROLE_SYSTEM_LISTITEM;
}
return S_OK;

};

Client Example

The following example function displays the role of an accessible object or child element.
C++
HRESULT PrintRole(IAccessible* pAcc, long childId)
{
    DWORD roleId;
    if (pAcc == NULL)
    {
        return E_INVALIDARG;    
    }
    VARIANT varChild;
    varChild.vt = VT_I4;
    varChild.lVal = childId;
    VARIANT varResult;
    HRESULT hr = pAcc->get_accRole(varChild, &varResult);
    if ((hr == S_OK) && (varResult.vt == VT_I4))
    {
        roleId = varResult.lVal;
        UINT   roleLength;
        LPTSTR lpszRoleString;
    // Get the length of the string. 
    roleLength = GetRoleText(roleId, NULL, 0);

    // Allocate memory for the string. Add one character to 
    // the length you got in the previous call to make room 
    // for the null character. 
    lpszRoleString = (LPTSTR)malloc((roleLength+1) * sizeof(TCHAR));
    if (lpszRoleString != NULL)
    {
        // Get the string. 
        GetRoleText(roleId, lpszRoleString, roleLength + 1);

#ifdef UNICODE printf("Role: %S\n", lpszRoleString); #else printf(("Role: %s\n", lpszRoleString); #endif // Free the allocated memory free(lpszRoleString); } else { return E_OUTOFMEMORY; } } return S_OK; }

Requirements

   
Windows version Windows 2000 Professional [desktop apps only] Windows Server 2003 [desktop apps only]
Target Platform Windows
Header oleacc.h
Library Oleacc.lib
DLL Oleacc.dll

See Also

GetRoleText

IAccessible

Role Property

VARIANT