nf-oleacc-iaccessible-get_accrole.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:oleacc.IAccessible.get_accRole	IAccessible::get_accRole (oleacc.h)	The IAccessible::get_accRole method retrieves information that describes the role of the specified object. All objects support this property.	IAccessible interface [Windows Accessibility] get_accRole method IAccessible.get_accRole IAccessible::get_accRole _msaa_IAccessible_get_accRole get_accRole get_accRole method [Windows Accessibility] get_accRole method [Windows Accessibility] IAccessible interface msaa.iaccessible_iaccessible__get_accrole oleacc/IAccessible::get_accRole winauto.iaccessible_iaccessible__get_accrole	winauto\iaccessible_iaccessible__get_accrole.htm	WinAuto	38800c5e-12a5-4825-a4c4-825a159c67f1	12/05/2018	IAccessible interface [Windows Accessibility],get_accRole method, IAccessible.get_accRole, IAccessible::get_accRole, _msaa_IAccessible_get_accRole, get_accRole, get_accRole method [Windows Accessibility], get_accRole method [Windows Accessibility],IAccessible interface, msaa.iaccessible_iaccessible__get_accrole, oleacc/IAccessible::get_accRole, winauto.iaccessible_iaccessible__get_accrole	oleacc.h		Windows	Windows 2000 Professional [desktop apps only]	Windows Server 2003 [desktop apps only]										Oleacc.lib	Oleacc.dll		Windows		Active Accessibility 1.3 RDK on Windows NT 4.0 with SP6 and later and Windows 95	19H1	IAccessible::get_accRole oleacc/IAccessible::get_accRole	c++	APIRef kbSyntax	COM	Oleacc.dll	IAccessible.get_accRole

IAccessible::get_accRole

-description

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

-parameters

-param varChild [in]

Type: VARIANT

Specifies whether the retrieved role information belongs to the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT, see How Child IDs Are Used in Parameters.

-param pvarRole [out, retval]

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.

-returns

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.

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.

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;
}

-see-also

GetRoleText

IAccessible

Role Property

VARIANT