Platform SDK: Active Directory, ADSI, and Directory Services

IADs::GetInfoEx

The IADs::GetInfoEx method loads the values of specified properties of the ADSI object from the underlying directory store into the property cache.

HRESULT IADs::GetInfoEx(
  VARIANT vProperties, 
  LONG lnReserved       
);

Parameters

vProperties: [in] Array of BSTR entries that list the properties to load into the Active Directory property cache. Each property name must match one in this object's schema class definition.
lnReserved: [in] Reserved for future use. Must be zero (0).

Return Values

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

S_OK: The current set of property values for this object have been refreshed.
E_ADS_OBJECT_UNBOUND: The specified ADSI object is not bound to the remote resource.

For other return values, see ADSI Error Codes.

Remarks

The IADs::GetInfoEx method overwrites any previously cached values of the specified properties with those in the directory store. Thus, any change made to the cache will be lost if an IADs::SetInfo was not invoked before the call to IADs::GetInfoEx.

Use IADs::GetInfoEx to refresh values of the selected property in the property cache of an ADSI object. Use IADs::GetInfo to refresh all the property values.

For an ADSI container object, IADs::GetInfoEx caches only the property values of the container, but not those of the child objects.

Example Code [Visual Basic]

The following Visual Basic code snippet shows how to use the IADs::GetInfoEx to obtain values of the selected properties, assuming that the desired property values can be found in the directory.

Dim x As IADs
Set x = GetObject("LDAP://CN=JSmith,CN=Users,DC=Fabrikam,DC=com")
 
'Retrieve givenName and sn from the underlying directory storage.
'Cache should have givenName and sn values.
x.GetInfoEx Array("givenName", "sn"), 0 
Debug.Print x.Get("givenName")  ' Property is in the cache
Debug.Print x.Get("sn")         ' Property is in the cache
 
'If the "homePhone" property is not in the cache (in the next line), 
'GetInfo will be called implicitly.
Debug.Print x.Get("homePhone")

Example Code [C++]

The following C++ code snippet shows how to use the IADs::GetInfoEx to obtain values of the selected properties, assuming that the desired property values can be found in the directory. For brevity, error checking has been omitted.

IADs *pADs;
VARIANT var;
HRESULT hr;
 
hr = ADsGetObject(L"WinNT://kding1,computer",
                  IID_IADs,
                  (void**)&pADs);
 
VariantInit(&var);
 
// Fetch "Owner" and "Division" attribute values.
LPWSTR pszAttrs[] = { L"Owner", L"Division" };
DWORD dwNumber = sizeof( pszAttrs ) /sizeof(LPWSTR);
hr = ADsBuildVarArrayStr( pszAttrs, dwNumber, &var );
hr = pADs->GetInfoEx(var, 0);
VariantClear(&var);
 
hr = pADs->Get(L"Division",&var);  
printf("    division   = %S\n", V_BSTR(&var));
VariantClear(&var);
hr = pADs->Get(L"Owner", &var);
printf("    owner      = %S\n", V_BSTR(&var));
VariantClear(&var);

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.