IADs：:P utEx 方法 (iads.h)

项目
02/29/2024

IADs：:P utEx 方法修改 ADSI 属性缓存中属性的值。例如，对于允许多个值的属性，可以将其他值追加到现有值集、修改集中的值、从集中删除指定值，或者从集中删除值。

语法

HRESULT PutEx(
  [in] long    lnControlCode,
  [in] BSTR    bstrName,
  [in] VARIANT vProp
);

参数

[in] lnControlCode

指示修改模式的控制代码：追加、替换、删除和删除。有关详细信息和值列表，请参阅 ADS_PROPERTY_OPERATION_ENUM。

[in] bstrName

包含指定属性名称的 BSTR 。

[in] vProp

包含一个 VARIANT 数组，该数组包含属性的新值。单值属性表示为具有单个元素的数组。如果 InControlCode 设置为 ADS_PROPERTY_CLEAR，则 vProp 指定的属性值无关紧要。

返回值

此方法支持标准返回值以及以下值。

有关详细信息，请参阅 ADSI 错误代码。

注解

PutEx 通常用于设置多值属性的值。与 IADs：:P ut 方法不同，使用 PutEx 时，无需在修改属性值之前获取属性值。但是，由于 PutEx 仅更改 ADSI 属性缓存中包含的属性值，因此必须在每次 PutEx 调用后使用 IADs：：SetInfo 才能将更改提交到目录。

通过 PutEx ，可以使用 ADS_PROPERTY_APPEND 将值追加到多值属性中的一组现有值。更新、追加或删除多值属性的值时，必须使用数组。

Active Directory 不接受多值属性上的重复值。如果调用 PutEx 将重复值追加到 Active Directory 对象的多值属性， 则 PutEx 调用成功，但重复值将被忽略。

同样，如果使用 PutEx 从 Active Directory 对象的多值属性中删除一个或多个值，则操作会成功，也就是说，即使未在该属性上设置任何或所有指定值，也不会产生错误。

注意WinNT 提供程序忽略 InControlCode 参数传递的值，并在使用 PutEx 时执行ADS_PROPERTY_UPDATE请求的等效项。

示例

下面的代码示例演示如何使用 IADs.PutEx 方法。

Dim x As IADs

On Error GoTo Cleanup

Set x = GetObject("LDAP://CN=JeffSmith,CN=Users,DC=Fabrikam,DC=com")
'----------------------------------------------------------
' Assume the otherHomePhone has the values
' 425-707-9790, 425-707-9791
'----------------------------------------------------------
 
' Adding a value
x.PutEx ADS_PROPERTY_APPEND, "otherhomePhone", Array("425-707-9792")  
x.SetInfo              ' Now the values are 425-707-9790,425-707-9791,425-707-9792. 
deleting two values
x.PutEx ADS_PROPERTY_DELETE, "otherHomePhone", Array("425-707-9790", "425-707-9791")
x.SetInfo              ' Now the values are 425-707-9792.
 
' Changing the remaining value
x.PutEx ADS_PROPERTY_UPDATE, "otherHomePhone", Array("425-707-9793", "425-707-9794")
x.SetInfo              ' Now the values are 425-707-9793,425-707-9794.
 
' Deleting the value
x.PutEx ADS_PROPERTY_CLEAR, "otherHomePhone",  vbNullString
x.SetInfo              ' Now the property has no value.

Cleanup:
    If(Err.Number<>0) Then
        MsgBox("An error has occurred. " & Err.Number)
    End If
    Set x = Nothing

下面的代码示例演示如何使用 IADs：:P utEx 方法。

HRESULT hr;
IADs *pADs=NULL;
LPWSTR pszADsPath = L"LDAP://CN=JeffSmith,CN=Users,DC=Fabrikam,DC=com";
 
CoInitialize(NULL);
 
hr = ADsGetObject(pszADsPath, IID_IADs, (void**) &pADs);

if(SUCCEEDED(hr)) 
{
    VARIANT var;
    VariantInit(&var);
     
    LPWSTR pszPhones[] = { L"425-707-9790", L"425-707-9791" };
    DWORD dwNumber = sizeof(pszPhones)/sizeof(LPWSTR);
    hr = ADsBuildVarArrayStr(pszPhones, dwNumber, &var);
    hr = pADs->Put(CComBSTR("otherHomePhone"), var); 
    VariantClear(&var);
    hr = pADs->SetInfo();   // The phone list is now 425-707-9790, 425-707-9791.
     
    // Append another number to the list.
    LPWSTR pszAddPhones[]={L"425-707-9792"};
    hr = ADsBuildVarArrayStr(pszAddPhones, 1, &var);
    hr = pADs->PutEx(ADS_PROPERTY_APPEND, CComBSTR("otherHomePhone"), var);
    hr = pADs->SetInfo();   // The list becomes 
                            // 425-707-9790, 425-707-9791, 425-707-9792.
    VariantClear(&var);
     
    hr = ADsBuildVarArrayStr(pszPhones, dwNumber, &var);
    hr = pADs->PutEx(ADS_PROPERTY_DELETE, CComBSTR("otherHomePhone"), var);
    hr = pADs->SetInfo();  // The list becomes 425-707-9792.
     
    pszPhones[0] = L"425-707-9793";
    pszPhones[1] = L"425-707-9794";
    hr = ADsBuildVarArrayStr(pszPhones, dwNumber, &var);
    hr = pADs->PutEx(ADS_PROPERTY_UPDATE, CComBSTR("otherHomePhone"), var);
    hr = pADs->SetInfo();  // The list becomes 425-707-9793, 425-707-9794.
     
    VariantClear(&var);
    V_VT(&var)=VT_NULL;
    hr = pADs->PutEx(ADS_PROPERTY_CLEAR, CComBSTR("otherHomePhone"), var);
    hr = pADs->SetInfo();  // The list is empty.

    VariantClear(&var);
    pADs->Release();
}

hr = CoUninitialize();