共用方式為


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

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();

規格需求

需求
最低支援的用戶端 Windows Vista
最低支援的伺服器 Windows Server 2008
目標平台 Windows
標頭 iads.h
Dll Activeds.dll

另請參閱

IAD

IADs::Get

IADs::GetEx

IADs::P ut

屬性快取