Platform SDK: Active Directory, ADSI, and Directory Services

IADs::PutEx

The IADs::PutEx method is used to modify cached values of a specified property with a greater degree of control. For example, you can append a value to the existing ones of a multi-valued property, change all the values at once, remove the specified values from the set, or delete all the values at once.

HRESULT IADs::PutEx(
  LONG lnControlCode,  
  BSTR bstrName,       
  VARIANT vProp       
);

Parameters

lnControlCode: [in] Control code to indicate the mode of modification: Append, Replace, Remove, and Delete. The values are specified in ADS_PROPERTY_OPERATION_ENUM.
bstrName: [in] Name of the property for example "FullName".
vProp: [in] Value or values of the property. The property value(s) is (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

Return Values

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

S_OK: The property values have been set successfully.
E_ADS_BAD_PARAMETER: The supplied dwControlCode parameter is invalid.
E_ADS_CANT_CONVERT_DATATYPE: The ADSI data type cannot be converted to or from the native data type of the underlying directory.

For other return values, see ADSI Error Codes.

Remarks

After calling IADs::PutEx, you must call IADs::SetInfo to commit the changes in the cache to the underlying directory store , if you wish to make the changes persistent.

Example Code [Visual Basic]

The following Visual Basic code snippet shows how to use IADs::PutEx with the control code to modify values of a named property.

Dim x As IADs
Set x = GetObject("LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com")
'----------------------------------------------
' Assume the otherHomePhoneNumber has the following values:
' 111-1111, 222-2222
'----------------------------------------------
 
' Adding a value
x.PutEx ADS_PROPERTY_APPEND, "OtherhomePhone", Array("333-3333")  
x.SetInfo              'Now the values are 111-1111,222-222,333-3333
 
' deleting two values
x.PutEx ADS_PROPERTY_DELETE, "OtherHomePhone", Array("111-1111", "222-2222")
x.SetInfo              'Now the values are 333-3333
 
' changing the remaining value
x.PutEx ADS_PROPERTY_UPDATE, "OtherHomePhone", Array("888-8888", "999-9999")
x.SetInfo              'Now the values are 888-8888,999-9999
 
'Deleting the value.
x.PutEx ADS_PROPERTY_CLEAR, "OtherHomePhone",  vbNullString
x.SetInfo              'Now the property has no value

Example Code [C++]

The following C++ code snippet uses IADs::PutEx to set some user attributes. For brevity, error checking is omitted.

HRESULT hr;
IADs *pADs=NULL;
LPWSTR pszADsPath = L"LDAP://CN=Administrator, CN=Users, DC=Fabrikam, DC=com";
 
CoInitialize(NULL);
 
hr = ADsGetObject(pszADsPath, IID_IADs, (void**) &pADs );
 
VARIANT var;
VariantInit(&var);
 
LPWSTR pszPhones[] = { L"111-1111", L"222-2222" };
DWORD dwNumber = sizeof( pszPhones ) /sizeof(LPWSTR);
hr = ADsBuildVarArrayStr( pszPhones, dwNumber, &var );
hr = pADs->Put( L"OtherHomePhone", var ); 
VariantClear(&var);
hr = pADs->SetInfo();   // now the phone list is (111-1111, 222-2222)
 
// Append another number to the list.
LPWSTR pszAddPhones[]={L"333-3333"};
hr = ADsBuildVarArrayStr( pszAddPhones, 1, &var);
hr = pADs->PutEx( ADS_PROPERTY_APPEND, L"OtherHomePhone", var );
hr = pADs->SetInfo();   //the list becomes 
                        // (111-1111, 222-2222, 333-3333)
VariantClear(&var);
 
hr = ADsBuildVarArrayStr( pszPhones, dwNumber, &var);
hr = pADs->PutEx( ADS_PROPERTY_DELETE, L"OtherHomePhone", var);
hr = pADs->SetInfo();  // the list becomes (333-3333)
 
pszPhones[0] = L"888-8888";
pszPhones[1] = L"999-9999";
hr = ADsBuildVarArrayStr( pszPhones, dwNumber, &var);
hr = pADs->PutEx( ADS_PROPERTY_UPDATE, L"OtherHomePhone", var);
hr = pADs->SetInfo();  // the list becomes (888-8888, 999-9999)
 
VariantClear(&var);
V_VT(&var)=VT_NULL;
hr = pADs->PutEx( ADS_PROPERTY_CLEAR, L"OtherHomePhone", var);
hr = pADs->SetInfo();  // the list is now empty
 
hr = CoUninitialize();

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.