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 GetEx( 
  BSTR bstrName,
  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 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.

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

Example Code [VBScript]

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>

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

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.