Directory Services


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.

  BSTR bstrName,
  VARIANT* pvProp


[in] Contains a BSTR that specifies the property name.
[out] Pointer to a VARIANT that receives the value, or values, of the property.

Return Values

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 Code Description
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.


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 version IADs::GetEx version
Dim x as IADs
otherNumbers = x.Get("otherHomePhone")
If VarType(otherNumbers) = vbString Then
  Debug.Print otherNumbers
  For Each homeNum In otherNumbers
	Debug.Print homeNum
End If
Dim x as IADs
otherNumbers = x.GetEx("otherHomePhone")
For Each homeNum In otherNumbers
  Debug.Print homeNum

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.

Example Code [Visual Basic]

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
' Multiple value property.
Debug.Print "Other Phone Numbers are: "
otherNumbers = x.GetEx("otherHomePhone")
For Each homeNum In otherNumbers
	Debug.Print homeNum
Exit Sub
	Debug.Print Hex(Err.Number)
	Set x = Nothing

Example Code [VBScript]

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


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 & " "
	 Response.Write "<br>"
   end if


Example Code [C++]

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.
	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));
// Cleanup.
if ( pADs )


Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.

See Also

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