IAccessible：：get_accRole 方法 (oleacc.h)

發行項
02/29/2024

IAccessible：：get_accRole 方法會擷取描述指定物件角色的資訊。所有物件都支援這個屬性。

語法

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

參數

[in] varChild

類型： VARIANT

指定擷取的角色資訊是否屬於物件或其中一個物件的子專案。這個參數CHILDID_SELF (取得对象) 或子標識碼 (，以取得對象子專案的相關信息) 。如需初始化 VARIANT 的詳細資訊，請參閱參數中使用子標識碼的方式。

[out, retval] pvarRole

類型： VARIANT*

接收物件角色常數之 VARIANT 的位址。 vt 成員必須VT_I4。 lVal 成員會收到物件角色常數。

傳回值

類型： HRESULT

如果成功，則傳回 S_OK。

如果未成功，則傳回下表中的其中一個值，或另一個標準 COM 錯誤碼。伺服器會傳回這些值，但客戶端必須一律檢查輸出參數，以確保它們包含有效的值。如需詳細資訊，請參閱檢查 IAccessible 傳回值。

錯誤	Description
E_INVALIDARG	引數無效。

備註

用戶端會呼叫 GetRoleText 來擷取描述物件角色的當地語系化字串。

伺服器開發人員的注意事項： 您必須使用預先定義的角色常數。

伺服器範例

下列範例程式代碼是自定義清單框的可能實作，可維護自己的清單專案。


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

用戶端範例

下列範例函式會顯示可存取物件或子專案的角色。


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

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	oleacc.h
程式庫	Oleacc.lib
Dll	Oleacc.dll
可轉散發套件	sp6 和更新版本和 Windows 95 Windows NT 4.0 上的 Active Accessibility 1.3 RDK