IAccessible::get_accRole-Methode (oleacc.h)

Artikel
08/25/2023

Die IAccessible::get_accRole-Methode ruft Informationen ab, die die Rolle des angegebenen Objekts beschreiben. Alle -Objekte unterstützen diese Eigenschaft.

Syntax

HRESULT get_accRole(
  [in]          VARIANT varChild,
  [out, retval] VARIANT *pvarRole
);

Parameter

[in] varChild

Typ: VARIANT

Gibt an, ob die abgerufenen Rolleninformationen zum -Objekt oder zu einem der untergeordneten Elemente des Objekts gehören. Dieser Parameter ist entweder CHILDID_SELF (zum Abrufen von Informationen über das Objekt) oder eine untergeordnete ID (zum Abrufen von Informationen über das untergeordnete Element des Objekts). Weitere Informationen zum Initialisieren von VARIANT finden Sie unter Verwenden untergeordneter IDs in Parametern.

[out, retval] pvarRole

Typ: VARIANT*

Adresse eines VARIANT-Objekts , das eine Objektrollenkonstante empfängt. Der vt-Member muss VT_I4 sein. Das lVal-Element empfängt eine Objektrollenkonstante.

Rückgabewert

Typ: HRESULT

Gibt bei Erfolg S_OK zurück.

Wenn dies nicht erfolgreich ist, gibt einen der Werte in der folgenden Tabelle oder einen anderen COM-Standardfehlercode zurück. Server geben diese Werte zurück, aber Clients müssen die Ausgabeparameter immer überprüfen, um sicherzustellen, dass sie gültige Werte enthalten. Weitere Informationen finden Sie unter Überprüfen von IAccessible-Rückgabewerten.

Fehler	BESCHREIBUNG
E_INVALIDARG	Ein Argument ist ungültig.

Hinweise

Clients rufen GetRoleText auf, um eine lokalisierte Zeichenfolge abzurufen, die die Rolle des Objekts beschreibt.

Hinweis für Serverentwickler: Sie müssen die vordefinierten Rollenkonstanten verwenden.

Serverbeispiel

Der folgende Beispielcode ist eine mögliche Implementierung dieser Methode für ein benutzerdefiniertes Listenfeld, das seine eigenen Listenelemente verwaltet.


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

Clientbeispiel

Die folgende Beispielfunktion zeigt die Rolle eines barrierefreien Objekts oder untergeordneten Elements an.


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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	oleacc.h
Bibliothek	Oleacc.lib
DLL	Oleacc.dll
Verteilbare Komponente	Active Accessibility 1.3 RDK unter Windows NT 4.0 mit SP6 und höher und Windows 95