IADs::GetEx method

The IADs::GetEx method retrieves, from the property cache, property values of a given attribute. The returned property values can be single-valued or multi-valued. Unlike the IADs::Get method, the property values are returned as a variant array of VARIANT, or a variant array of bytes for binary data. A single-valued property is then represented as an array of a single element.

Syntax


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

Parameters

bstrName [in]

Contains a BSTR that specifies the property name.

pvProp [out]

Pointer to a VARIANT that receives the value, or values, of the property.

Return value

This method supports the standard return values as well as the return values listed in the following table.

For more information, see ADSI Error Codes.

Return codeDescription
S_OK

The property value was retrieved successfully.

E_ADS_PROPERTY_NOT_FOUND

The property was not found in the property cache. The property may not have attributes, or is an invalid property.

E_FAIL

The operation failed.

 

Remarks

The IADs::Get and IADs::GetEx methods return a different variant structure for a single-valued property value. If the property is a string, IADs::Get returns a variant of string (VT_BSTR), whereas IADs::GetEx returns a variant array of a VARIANT type string with a single element. Thus, if you are not sure that a multi-valued attribute will return a single value or multiple values, use IADs::GetEx. As it does not require you to validate the result's data structures, you may want to use IADs::GetEx to retrieve a property when you are not sure whether it has single or multiple values. The following table compares the two methods.

IADs::Get versionIADs::GetEx version

Dim x as IADs

otherNumbers = x.Get("otherHomePhone")
If VarType(otherNumbers) = vbString Then
  Debug.Print otherNumbers
Else
  For Each homeNum In otherNumbers
    Debug.Print homeNum
  Next
End If


Dim x as IADs

otherNumbers = x.GetEx("otherHomePhone")
For Each homeNum In otherNumbers
  Debug.Print homeNum
Next

 

Like the IADs::Get method, IADs::GetEx implicitly calls IADs::GetInfo against an uninitialized property cache. For more information about implicit and explicit calls to IADs::GetInfo, see IADs::GetInfo.

Examples

The following code example shows how to use IADs::GetEx to retrieve object properties.


Dim x As IADs
On Error GoTo ErrTest:
 
Set x = GetObject("LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com")
 
' Single value property.
Debug.Print "Home Phone Number is: " 
phoneNumber = x.GetEx(""homePhone")
For Each homeNum in phoneNumber
    Debug.Print homeNum
Next
 
' Multiple value property.
Debug.Print "Other Phone Numbers are: "
otherNumbers = x.GetEx("otherHomePhone")
For Each homeNum In otherNumbers
    Debug.Print homeNum
Next
Exit Sub
 
ErrTest:
    Debug.Print Hex(Err.Number)
    Set x = Nothing


The following code example shows how to retrieve values of the optional properties of an object using the IADs::Get method.


<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 the optional property values for this object.
Set cls = GetObject(x.Schema)
For Each op In cls.OptionalProperties
   vals = obj.GetEx(op)
   if err.Number = 0 then
       Response.Write "Optional Property: & op & "=" 
       for each v in vals 
          Response.Write v & " "
       next
       Response.Write "<br>"
   end if
Next
%>

</body>
</html>

The following code example retrieves the "homePhone" property values using IADs::GetEx.


IADs *pADs = NULL;
 
hr = ADsGetObject(L"LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=Com", IID_IADs, (void**) &pADs );
if ( !SUCCEEDED(hr) ) { return hr;}
 
hr = pADs->GetEx(CComBSTR("homePhone"), &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 Home Phone using IADs::Get.\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 ( pADs )
{
    pADs->Release();
}

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Iads.h

DLL

Activeds.dll

IID

IID_IADs is defined as FD8256D0-FD15-11CE-ABC4-02608C9E7553

See also

Property Cache Interfaces
IADs
IADs::Get
IADs::GetInfo
IADs::Put
IADs::PutEx

 

 

Show:
© 2014 Microsoft