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

發行項
02/26/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();