| Platform SDK: Active Directory, ADSI, and Directory Services |
The IADs::GetInfo method loads into the property cache values of the supported properties of this ADSI object from the underlying directory store.
HRESULT IADs::GetInfo(void);
This method supports the standard return values, as well as the following:
For other return values, see ADSI Error Codes.
The IADs::GetInfo function is called, implicitly or explicitly, to initialize or refresh the property cache. This amounts to fetching those property values of supported properties from the underlying directory store. An uninitialized property cache is not necessarily empty. In fact, you can call IADs::Put or IADs::PutEx to put a value into the property cache for any supported property and the cache remains uninitialized. An explicit call to IADs::GetInfo will load or reload the entire property cache, overwriting all the cached property values. But an implicit call will load only those properties that have not been set in the cache. Thus, you should always call IADs::GetInfo explicitly if you want to obtain the most up-to-date property values of the ADSI object. The following code snippet illustrates such subtleties.
Because an explicit call to IADs::GetInfo overwrites all the values in the property cache, any change made to the cache will be lost if an IADs::SetInfo was not invoked before IADs::GetInfo.
For an ADSI container object, IADs::GetInfo caches only the property values of the container, but not those of the child objects.
It is important to emphasize the differences between the IADs::Get and IADs::GetInfo methods. The former returns values of a given property from the property cache whereas the latter loads all the supported property values into the property cache from the underlying directory store. The following Visual Basic code snippet illustrates these differences.
Set x = GetObject("LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com")
'The first IADs::Get will call
'GetInfo implicitly
Debug.Print x.Get("homePhone") 'assume value is '999-9999'
x.Put "homePhone", "868-4449" 'Put with no commit(SetInfo)
Debug.Print x.Get("homePhone") 'Value='868-4449' from the cache
x.GetInfo 'Refresh the cache, get the data
'from the directory
Debug.Print x.Get("homePhone") 'value will be '999-9999'
For performance enhancement, you can make explicit calls to IADs::GetInfoEx to refresh specific properties. This function always overwrites any previously cached values of the specified properties.
The following Visual Basic code snippet makes use of a computer object served by the WinNT provider. The supported properties include Owner ("Owner"), OperatingSystem ("Windows NT"), OperatingSystemVersion ("4.0"), Division ("Fabrikam"), ProcessorCount ("Uniprococessor Free"), Processor ("x86 Family 6 Model 5 Stepping 1"). The default values are shown in parentheses for the purpose of illustration.
Dim pList As IADsPropertyList
Dim pEntry As IADsPropertyEntry
Dim pValue As IADsPropertyValue
Set pList = GetObject("WinNT://localhost,computer")
' pList now represents an uninitialized empty property cache
pList.Put "Owner" "buddy" ' property cache remain uninitialized
' but with one property value.
count = pList.PropertyCount ' count = 1.
MsgBox "Number of property found in the property cache: " & count
v = pList.Get("Division") ' pList.GetInfo is called implicitly
ShowPropertyCache ' This will display "buddy" for Owner,
"Fabrikam" for Division,
"Windows NT" for OperatingSystem,
and so on.
pList.GetInfo ' refreshes the entire cache, overwriting
" "buddy" for the Owner property.
ShowPropertyCache ' This will display "Owner" for Owner,
"Fabrikam" for Division,
"Windows NT" for OperatingSystem,
and so on.
Private Sub ShowPropertyCache()
For I = 0 To pList.PropertyCount-1
Set pEntry = pList.Item(I)
Debug.Print pEntry.Name
For Each v In pEntry.Values
Set pValue = v
Debug.Print " " & pvalue.CaseIgnoreString
Next
Next
End Sub
The following VBScript code snippet is a client-side script illustrating the effect of IADs::GetInfo method. The supported properties include Owner ("Owner"), OperatingSystem ("Windows NT"), OperatingSystemVersion ("4.0"), Division ("Fabrikam"), ProcessorCount ("Uniprococessor Free"), Processor ("x86 Family 6 Model 5 Stepping 1"). The default values are shown in parentheses for the purpose of illustration.
<html>
<body>
<table>
<tr>
<td>Owner:</td>
<td><input type=text name=txtOwner></td>
</tr>
<tr>
<td>Operating System:</td>
<td><input type=text name=txtOS></td>
</tr>
<tr>
<td>Operating System Version:</td>
<td><input type=text name=txtOSV></td>
</tr>
<tr>
<td>Division:</td>
<td><input type=text name=txtDiv></td>
</tr>
</table>
<input type=button onClick = "showGetInfo()">
</body>
<script lanugage="vbscript">
Dim pList
sub showGetInfo()
Set oFac = CreateObject("ADsFactory")
path = "WinNT://Fabrikam"
user = "Administrator"
pass = "adminPass"
ADS_SECURE_AUTH = 1
Set pList=oFac.OpernDSObject(path,user,pass,ADS_SECURE_AUTH)
' pList now represents an uninitialized empty property cache
pList.Put "Owner" "buddy" ' property cache remain uninitialized
' but with one property value.
v = pList.Get("Division") ' pList.GetInfo is called implicitly
ShowPropertyCache ' This will display "buddy" for Owner,
"Fabrikam" for Division,
"Windows NT" for OperatingSystem,
and so on
pList.GetInfo 'refreshes entire cache, overwriting
' "buddy" for the Owner property.
ShowPropertyCache ' This will display "Owner" for Owner,
"Fabrikam" for Division,
"Windows NT" for OperatingSystem,
and so on
end sub
sub ShowPropertyCache()
txtOwner.value = pList.Get("Owner")
txtDiv.value = pList.Get("Division")
txtOS.Value = pList.Get("OperatingSystem")
txtOSV.value = pList.Get("OperatingSystemVersion")
end sub
</script>
</html>
The following C++ code snippet highlights the effect of Get and GetInfo. For brevity error checking is omitted.
IADs *pADs;
IADsPropertyList *pList;
BSTR bstr;
VARIANT var;
HRESULT hr;
hr = ADsGetObject(L"WinNT://kding1,computer",
IID_IADsPropertyList,
(void**)&pList);
// get the number of property entries, should be zero.
long pCount;
hr = pList->get_PropertyCount(&pCount);
printf(" prop count = %d\n",pCount); // 0 for empty cache.
hr = pList->QueryInterface(IID_IADs, (void**)&pADs);
VariantInit(&var);
// Set "Owner=Buddy" in the property cache.
V_BSTR(&var) = SysAllocString(L"Buddy");
V_VT(&var) = VT_BSTR;
hr = pADs->Put(L"Owner",var);
VariantClear(&var);
//This time the number of property entries should read one (1).
hr = pList->get_PropertyCount(&pCount);
printf(" prop count = %d\n",pCount); // 1 for what we have set.
// The following Get will invoke GetInfo implicitly, but
// whatever is already in the cache (that is, "Owner=Buddy") will
// remain intact.
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)); // Owner = Buddy
VariantClear(&var);
// The following GetInfo call refreshes the entire prop cache.
// Now Owner is no longer "Buddy", but the value stored in the
// persistent store, for example, "Bob".
hr = pADs->GetInfo();
hr = pADs->Get(L"Owner", &var);
printf(" owner = %S\n", V_BSTR(&var)); // Owner = Bob
VariantClear(&var);
// ...
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.
IADs, IADs::Get, IADs::GetEx, IADs::GetInfoEx, Property Cache