Método IADs::Get (iads.h)

Artigo
08/24/2023

O método IADs::Get recupera uma propriedade de um determinado nome do cache de propriedades. A propriedade pode ser com valor único ou com valores múltiplos. O valor da propriedade é representado como uma variante para uma propriedade de valor único ou uma matriz variante (de VARIANT ou bytes) para uma propriedade que permite vários valores.

Sintaxe

HRESULT Get(
  [in]  BSTR    bstrName,
  [out] VARIANT *pvProp
);

Parâmetros

[in] bstrName

Contém um BSTR que especifica o nome da propriedade.

[out] pvProp

Ponteiro para um VARIANT que recebe o valor da propriedade . Para uma propriedade com vários valores, pvProp é uma matriz variante de VARIANT, a menos que a propriedade seja um tipo binário. Neste último caso, pvProp é uma matriz variante de bytes (VT_U1 ou VT_ARRAY). Para a propriedade que se refere a um objeto , pvProp é um ponteiro VT_DISPATCH para o objeto referido.

Valor retornado

Esse método dá suporte a valores retornados padrão, bem como os seguintes.

Para obter mais informações, consulte Códigos de erro ADSI.

Comentários

O método IADs::Get exige que o chamador manipule os valores de propriedade de valor único e múltiplo de maneira diferente. Portanto, se você souber que a propriedade de interesse é única ou com vários valores, use o método IADs::Get para recuperar o valor da propriedade. O exemplo de código a seguir mostra como você, como um chamador, pode lidar com propriedades de valores únicos e múltiplos ao chamar esse método.

Quando uma propriedade é não inicializada, chamar esse método invoca uma chamada implícita para o método IADs::GetInfo . Isso é carregado do diretório subjacente que armazena os valores das propriedades com suporte que não foram definidas no cache. Todas as chamadas subsequentes para IADs::Get lidam com valores de propriedade somente no cache. Para obter mais informações sobre o comportamento de chamadas implícitas e explícitas para IADs::GetInfo, consulte IADs::GetInfo.

Você também pode usar IADs::GetEx para recuperar valores de propriedade do cache de propriedades. No entanto, os valores são retornados como uma matriz variante de VARIANTs, independentemente de serem de valor único ou de vários valores. Ou seja, ADSI tenta empacotar os valores de propriedade retornados em formatos de dados consistentes. Isso salva você, como um chamador, o esforço de validar os tipos de dados quando não tem certeza de que os dados retornados têm valores únicos ou múltiplos.

Exemplos

O exemplo de código a seguir recupera o descritor de segurança de um objeto usando IADs::Get.

Dim x As IADs
Dim Desc As IADsSecurityDescriptor
On Error GoTo ErrTest:
 
Set x = GetObject("LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com")
 
' Single-valued properties.
Debug.Print "Home Phone Number is: " & x.Get("homePhone")
 
' Some property values represents other ADSI objects. 
' Consult your provider documentation.
Set Desc = x.Get("ntSecurityDescriptor")
 
' Multi-valued property, assuming that multiple values were
' assigned to the "otherHomePhone" properties. Caller must 
' enumerate all the available values.
Debug.Print "Other Phone Numbers are: "
otherNumbers = x.Get("otherHomePhone")
For Each homeNum In otherNumbers
  Debug.Print homeNum
Next
 
Exit Sub
 
ErrTest:
  Debug.Print Hex(Err.Number)
  Set x = Nothing
  Set Desc = Nothing

O exemplo de código a seguir mostra como trabalhar com valores de propriedade de dados binários usando IADs::Get e IADs::P ut.

Dim oTarget As IADs
Dim Octet(5) As Byte
Dim MultiOctet(2) As Variant
Dim i As Integer, j As Integer

On Error GoTo Cleanup
 
' Set up MultiOctetString.
For i = 0 To 2
    For j = 0 To 5
        Octet(j) = CByte(i * j)
    Next j
    MultiOctet(i) = Octet
Next i
 
' Bind to the object and set MultiOctetString.
Set oTarget=GetObject("LDAP://CN=SomeUser,CN=Users,DC=Fabrikam, DC=COM")
oTarget.Put "multiOctetString", MultiOctet
oTarget.SetInfo
 
Dim GetOctet As Variant
Dim Temp As Variant
 
' Read back and print MultiOctetString.
GetOctet = oTarget.Get("multiOctetString")
For i = LBound(GetOctet) To UBound(GetOctet)
    Temp = GetOctet(i)
    For j = LBound(Temp) To UBound(Temp)
        Debug.Print Temp(j)
    Next j
    Debug.Print "----"
Next i

Exit Sub

Cleanup:
   MsgBox("An error has occurred. " & Err.Number)
   Set oTarget = Nothing

O exemplo de código a seguir mostra como recuperar valores das propriedades opcionais de um objeto usando IADs::Get.

<HTML>
<head><title></title></head>

<body>
<%
Dim x 
 
On error resume next
Set x = GetObject("WinNT://Fabrikam/Administrator")
Response.Write "Object Name: " & x.Name & "<br>"
Response.Write "Object Class: " & x.Class & "<br>"
 
' Get optional property values of this object.
Set cls = GetObject(x.Schema)

For Each op In cls.OptionalProperties
   v = obj.Get(op)
   if err.Number = 0 then
       Response.Write "Optional Property: " & op & "=" & v & "<br>"
   end if
Next
%>

</body>
</html>

O exemplo de código a seguir lê atributos com valores únicos e múltiplos usando IADs::Get.

HRESULT hr;
IADs *pUsr=NULL;
 
CoInitialize(NULL);
 
///////////////////////////////
// Bind to a directory object.
///////////////////////////////
hr = ADsGetObject(L"WinNT://Fabrikam/Administrator,user", IID_IADs, (void**) &pUsr );
if ( !SUCCEEDED(hr) ) { return hr; }
 
//////////////////////////////////
// Get a single-valued attribute.
//////////////////////////////////
VARIANT var;
VariantInit(&var);
 
hr = pUsr->Get(CComBSTR("FullName"), &var );
if ( SUCCEEDED(hr) )
{
    printf("FullName: %S\n", V_BSTR(&var) );
    VariantClear(&var);
}
 
if ( pUsr )
{
    pUsr->Release();
}
 
///////////////////////////////////////////////////////
// Get a multi-valued attribute from a service object.
///////////////////////////////////////////////////////
IADs *pSvc = NULL;
 
hr = ADsGetObject(L"WinNT://Fabrikam/Account/Browser,service", IID_IADs, (void**) &pSvc );
if ( !SUCCEEDED(hr) )
{
    return hr;
}
 
hr = pSvc->Get(CComBSTR("Dependencies"), &var );
if ( SUCCEEDED(hr) )
{
    LONG lstart, lend;
    SAFEARRAY *sa = V_ARRAY( &var );
    VARIANT varItem;
 
    // Get the lower and upper bound.
    hr = SafeArrayGetLBound( sa, 1, &lstart );
    hr = SafeArrayGetUBound( sa, 1, &lend );
 
    // Iterate and print the content.
    VariantInit(&varItem);
    printf("Getting service dependencies using IADs :\n");
    for ( long idx=lstart; idx <= lend; idx++ )
    {
        hr = SafeArrayGetElement( sa, &idx, &varItem );
        printf("%S ", V_BSTR(&varItem));
        VariantClear(&varItem);
    }
    printf("\n");
 
    VariantClear(&var);
}
 
// Cleanup.
if ( pSvc )
{
    pSvc->Release();
}

Requisitos


Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	iads.h
DLL	Activeds.dll