IADs::P utEx method (iads.h)

Artikel
08/24/2023

Metode IADs::P utEx memodifikasi nilai atribut dalam cache atribut ADSI. Misalnya, untuk properti yang mengizinkan beberapa nilai, Anda dapat menambahkan nilai tambahan ke sekumpulan nilai yang ada, memodifikasi nilai dalam set, menghapus nilai yang ditentukan dari set, atau menghapus nilai dari set.

Sintaks

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

Parameter

[in] lnControlCode

Kode kontrol yang menunjukkan mode modifikasi: Tambahkan, Ganti, Hapus, dan Hapus. Untuk informasi selengkapnya dan daftar nilai, lihat ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Berisi BSTR yang menentukan nama properti.

[in] vProp

Berisi array VARIAN yang berisi nilai atau nilai baru properti. Properti bernilai tunggal direpresentasikan sebagai array dengan satu elemen. Jika InControlCode diatur ke ADS_PROPERTY_CLEAR, nilai properti yang ditentukan oleh vProp tidak relevan.

Nilai kembali

Metode ini mendukung nilai pengembalian standar, serta yang berikut ini.

Untuk informasi selengkapnya, lihat Kode Kesalahan ADSI.

Keterangan

PutEx biasanya digunakan untuk mengatur nilai pada atribut multinilai. Tidak seperti metode IADs::P ut , dengan PutEx, Anda tidak diharuskan untuk mendapatkan nilai atribut sebelum memodifikasinya. Namun, karena PutEx hanya membuat perubahan pada nilai atribut yang terkandung dalam cache properti ADSI, Anda harus menggunakan IAD::SetInfo setelah setiap panggilan PutEx untuk melakukan perubahan pada direktori.

PutEx memungkinkan Anda menambahkan nilai ke sekumpulan nilai yang ada dalam atribut multinilai menggunakan ADS_PROPERTY_APPEND. Saat memperbarui, menambahkan, atau menghapus nilai ke atribut multinilai, Anda harus menggunakan array.

Direktori Aktif tidak menerima nilai duplikat pada atribut multinilai. Jika Anda memanggil PutEx untuk menambahkan nilai duplikat ke atribut multinilai dari objek Direktori Aktif, panggilan PutEx berhasil, tetapi nilai duplikat diabaikan.

Demikian pula, jika Anda menggunakan PutEx untuk menghapus satu atau beberapa nilai dari properti multinilai dari objek Direktori Aktif, operasi berhasil, artinya, itu tidak akan menghasilkan kesalahan, bahkan jika salah satu atau semua nilai yang ditentukan tidak diatur pada properti .

Catatan Penyedia WinNT mengabaikan nilai yang diteruskan oleh argumen InControlCode dan melakukan permintaan ADS_PROPERTY_UPDATE yang setara saat menggunakan PutEx.

Contoh

Contoh kode berikut menunjukkan cara menggunakan metode 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

Contoh kode berikut menunjukkan cara menggunakan metode 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();

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Server minimum yang didukung	Windows Server 2008
Target Platform	Windows
Header	iads.h
DLL	Activeds.dll