Platform SDK: Active Directory, ADSI, and Directory Services

IADsPropertyList::PutPropertyItem

The IADsPropertyList::PutPropertyItem method updates the values for an item in the property list.

HRESULT PutPropertyItem(
  VARIANT VarData
);

Parameters

VarData: [in] New property values to be put in the property cache.

Return Values

This method supports the standard HRESULT return values, including S_OK. For other return values, see ADSI Error Codes.

Remarks

You must call IADs::SetInfo to persist any changes in the directory store. The property values are not committed until the IADs::SetInfo method is called.

Example Code [Visual Basic]

The following Visual Basic code snippet shows how to add a new entry to a property list using PutPropertyItem.

Dim propList As IADsPropertyList
Set propList = GetObject("LDAP://DC=Microsoft,DC=com")
Set propVal = New PropertyValue
 
'--- Property Value-----
propVal.CaseIgnoreString = "Fabrikam, Inc - Seattle, WA"
propVal.ADsType = ADSTYPE_CASE_IGNORE_STRING
 
'--- Property Entry ----
Set propEntry = New PropertyEntry
propEntry.Name = "adminDescription"
propEntry.Values = Array(propVal)
propEntry.ControlCode = ADS_PROPERTY_UPDATE
propEntry.ADsType = ADSTYPE_CASE_IGNORE_STRING
 
' --- Property List----
propList.PutPropertyItem (propEntry)
 
' query the IADs interface on the propList object
Dim IADsObj As IADs
Set IADsObj=propList
 
' Commit changes of the property list to the directory store.
IADsObj.SetInfo

Example Code [C++]

The following C++ code snippet adds a new entry to a property list using IADsPropertyList::PutPropertyItem.

// forward declaration of a helper function
HRESULT ADsBuildVarArrayDisp(IDispatch ** ppObjs,
                             DWORD      dwObjs,
                             VARIANT * pVar
                             )

int main()
{
   HRESULT hr = CoInitialize(NULL);

   IADsPropertyList *pList;
   hr = ADsOpenObject(L"LDAP://dc=Microsoft, dc=com",
                      L"Administrator",
                      L"",
                      ADS_SECURE_AUTHENTICATION,
                      IID_IADsPropertyList,
                      (void**)&pList);

// create a property value object
   IADsPropertyValue *pVal;
   hr = CoCreateInstance(CLSID_PropertyValue,
                         NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_IADsPropertyValue,
                         (void**)&pVal);
   hr = pVal->put_CaseIgnoreString(L"Fabrikam, Inc - Seattle, WA");

   hr = pVal->put_ADsType(ADSTYPE_CASE_IGNORE_STRING);

   // stuff the propertyValue object into a variant array for 
   // assigment to a propertyEntry object
   IDispatch *pDisp;
   hr = pVal->QueryInterface(IID_IDispatch,(void**)&pDisp);
   hr = pVal->Release();

   VARIANT vVals;
   VariantInit(&vVals);
   hr = ADsBuildVarArrayDisp(&pDisp,1,&vVals);  //code given below.
   pDisp->Release();  

   // Create a propertyEntry object
   IADsPropertyEntry *pEntry;
   hr = CoCreateInstance(CLSID_PropertyEntry,
                         NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_IADsPropertyEntry,
                         (void**)&pEntry);

   hr = pEntry->put_Name(L"adminDescription"); 
   hr = pEntry->put_ControlCode(ADS_PROPERTY_UPDATE);
   hr = pEntry->put_ADsType(ADSTYPE_CASE_IGNORE_STRING);
   hr = pEntry->put_Values(vVals);
   VariantClear(&vVals);

   // Convert pEntry to pDisp for use in pList.PutPropertyItem
   hr = pEntry->QueryInterface(IID_IDispatch,(void**)&pDisp);
   pEntry->Release();

   VARIANT vEntry;
   VariantInit(&vEntry);
   V_DISPATCH(&vEntry)=pDisp;
   V_VT(&vEntry)=  VT_DISPATCH;
   hr = pList->PutPropertyItem(vEntry);  
   VariantClear(&vEntry);

   IADs *pObj;
   hr = pList->QueryInterface(IID_IADs,(void**)&pObj);
   pObj->SetInfo();
   pObj->Release();

   pList->Release();

   CoUninitialize();
   return 0;
}

////////////////
// Helper function to build a variant array of IDispatch objects.
///////////////
HRESULT ADsBuildVarArrayDisp(
    IDispatch ** ppObjs,
    DWORD      dwObjs,
    VARIANT * pVar
    )
{

    VARIANT v;
    SAFEARRAYBOUND sabNewArray;
    DWORD i;
    SAFEARRAY *psa = NULL;
    HRESULT hr = E_FAIL;

    sabNewArray.cElements = dwObjs;
    sabNewArray.lLbound = 0;
    psa = SafeArrayCreate(VT_VARIANT, 1, &sabNewArray);

    if (!pVar) {
        hr = E_ADS_BAD_PARAMETER;
        goto Fail;
    }
    VariantInit(pVar);

    if (!psa) {
        goto Fail;
    }

    for (i = 0; i < dwObjs; i++) {
        VariantInit(&v);
        V_VT(&v) = VT_DISPATCH;
        V_DISPATCH(&v) = *(ppObjs + i);
        hr = SafeArrayPutElement(psa,
                                 (long FAR *)&i,
                                 &v
                                 );
        if (FAILED(hr))  {
            goto Fail;
        }
    }

    V_VT(pVar) = VT_VARIANT | VT_ARRAY;
    V_ARRAY(pVar) = psa;

    return(ResultFromScode(S_OK));

Fail:
    if (psa) {
        SafeArrayDestroy(psa);
    }

    return(E_FAIL);
}

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.