Platform SDK: Active Directory, ADSI, and Directory Services

IADs::GetEx

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

HRESULT IADs::GetEx(
  BSTR bstrName,
  VARIANT * pvProp
);

Parameters

bstrName: [in] Name of the property, for example, "homeNumber".
pvProp: [out, retval] Pointer to a location to receive the value(s) of the property.

Return Values

This method supports the standard return values, as well as the following:

S_OK: The property value was retrieved successfully.
E_ADS_PROPERTY_NOT_FOUND: The property is not found in the property cache. The property may not have attributes, or is an invalid property.
E_FAIL: The operation failed.

For other return values, see ADSI Error Codes.

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 will return a variant of string (VT_BSTR), whereas IADs::GetEx will return 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, you should 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 difference in calling the two methods.

IADs::Get version	IADs::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

IADs::Get version

IADs::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 makes an implicit call to IADs::GetInfo against an uninitialized property cache. For more information on implicit and explicit calls to IADs::GetInfo, see the IADs::GetInfo topic in this document.

Example Code [Visual Basic]

The following Visual Basic code example shows how to use IADs::GetEx to retrieve properties from an object.

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)

Example Code [VBScript]

The following VBScript/ASP code snippet illustrates 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 optional property values of 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>

Example Code [C++]

The following C++ code snippet 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(L"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 );
 
    // Now 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);
}
 
// Clean-up
if ( pADs )
{
    pADs->Release();
}

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.