Platform SDK: Active Directory, ADSI, and Directory Services

IADs::SetInfo

The IADs::SetInfo method saves the cached property values of the ADSI object to the underlying directory store.

HRESULT IADs::SetInfo(void);

Return Values

This method supports the standard return values, including S_OK for a successful operation. For other return values, see ADSI Error Codes.

Remarks

It is important to emphasize the differences between the IADs::Put (or IADs::PutEx) and IADs::SetInfo methods. The former sets (or modifies) values of a given property in the property cache whereas the latter propagates the changes from the property cache into the underlying directory store. Thus, any property value changes made through IADs::Put (or IADs::PutEx) will be lost when IADs::GetInfo (or IADs::GetInfoEx) is invoked before IADs::SetInfo is called.

Because IADs::SetInfo sends data across networks, you should try to minimize the usage of this method whenever possible. This helps to reduce the number of trips that a client makes to the server. For example, you should commit all (or most) the changes of the properties from the cache to the persistent store in one batch. You should avoid calling IADs::SetInfo after each call to IADs::Put (or IADs::PutEx). The following code snippets illustrate what is recommended and what is not.

Case 1: Recommended

Dim obj as IADs
 
obj.Put(prop1,val1)
obj.Put(prop2.val2)
obj.Put(prop3.val3)
obj.SetInfo

Case 2: Not recommended

obj.Put(prop1,val1)
obj.SetInfo
obj.Put(prop2.val2)
obj.SetInfo
obj.Put(prop3.val3)
obj.SetInfo

When used with IADs::PutEx, IADs::SetInfo passes the operational requests that are specified by control codes, such as ADS_PROPERTY_UPDATE or ADS_PROPERTY_CLEAR, to the underlying directory store.

Example Code [Visual Basic]

The following Visual Basic code snippet uses the IADs::SetInfo method to save the property value of a user to the underlying directory.

Set x = GetObject("LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com")
'
' update values in cache
'
x.Put "sn", "Smith"
x.Put "givenName", "Jeff"
x.Put "street", "123 Main Street"
x.Put "l", "Bellevue"
x.Put "st", "Washington"
'
' commit changes to the directory.
x.SetInfo

Example Code [C++]

The following C++ code snippet updates property values in the property cache and commits the change to the directory store using IADs::SetInfo. Error checking is omitted.

IADs *pAds;
VARIANT var;
HRESULT hr;
LPWSTR path=L"LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com";
hr = ADsGetObject( path, IID_IADs, (void**) pADs);
 
// update values in cache
V_BSTR(&var) = SysAllocString(L"Smith");
V_VT(&var) = VT_BSTR;
hr = pADs->Put(L"sn", var );
VariantClear(&var);
 
V_BSTR(&var) = SysAllocString(L"Jeff");
V_VT(&var) = VT_BSTR;
hr = pADs->Put(L"givenName", var );
VariantClear(&var);
 
V_BSTR(&var) = SysAllocString(L"123 Main Street");
V_VT(&var) = VT_BSTR;
hr = pADs->Put(L"street", var );
VariantClear(&var);
 
V_BSTR(&var) = SysAllocString(L"Bellevue");
V_VT(&var) = VT_BSTR;
hr = pADs->Put(L"l", var );
VariantClear(&var);
 
V_BSTR(&var) = SysAllocString(L"Washington");
V_VT(&var) = VT_BSTR;
hr = pADs->Put(L"st", var );
VariantClear(&var);
 
// Commit changes to the directory store.
hr = pADs->SetInfo();

Requirements