IADs::P utEx-Methode (iads.h)

Artikel
02/29/2024

Die IADs::P utEx-Methode ändert die Werte eines Attributs im ADSI-Attributcache. Für Eigenschaften, die mehrere Werte zulassen, können Sie z. B. zusätzliche Werte an einen vorhandenen Satz von Werten anfügen, die Werte im Satz ändern, angegebene Werte aus dem Satz entfernen oder Werte aus der Menge löschen.

Syntax

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

Parameter

[in] lnControlCode

Steuerungscode, der den Änderungsmodus angibt: Anfügen, Ersetzen, Entfernen und Löschen. Weitere Informationen und eine Liste der Werte finden Sie unter ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Enthält einen BSTR , der den Eigenschaftennamen angibt.

[in] vProp

Enthält ein VARIANT-Array , das den neuen Wert oder die neuen Werte der Eigenschaft enthält. Eine einwertige Eigenschaft wird als Array mit einem einzelnen Element dargestellt. Wenn InControlCode auf ADS_PROPERTY_CLEAR festgelegt ist, ist der Wert der von vProp angegebenen Eigenschaft irrelevant.

Rückgabewert

Diese Methode unterstützt standardmäßige Rückgabewerte sowie folgendes.

Weitere Informationen finden Sie unter ADSI-Fehlercodes.

Hinweise

PutEx wird in der Regel verwendet, um Werte für mehrwertige Attribute festzulegen. Im Gegensatz zur IADs::P ut-Methode müssen Sie bei PutEx die Attributwerte nicht abrufen, bevor Sie sie ändern. Da PutEx jedoch nur Änderungen an Attributwerten vornimmt, die im ADSI-Eigenschaftencache enthalten sind, müssen Sie IADs::SetInfo nach jedem PutEx-Aufruf verwenden, um Änderungen an das Verzeichnis zu committen.

Mit PutEx können Sie Werte an einen vorhandenen Satz von Werten in einem mehrwertigen Attribut mithilfe von ADS_PROPERTY_APPEND anfügen. Wenn Sie Werte an ein Attribut mit mehreren Werten aktualisieren, anfügen oder löschen, müssen Sie ein Array verwenden.

Active Directory akzeptiert keine doppelten Werte für ein mehrwertiges Attribut. Wenn Sie PutEx aufrufen, um einen doppelten Wert an ein mehrwertiges Attribut eines Active Directory-Objekts anzufügen, ist der PutEx-Aufruf erfolgreich, aber der doppelte Wert wird ignoriert.

Wenn Sie PutEx verwenden, um einen oder mehrere Werte aus einer mehrwertigen Eigenschaft eines Active Directory-Objekts zu löschen, ist der Vorgang ebenfalls erfolgreich. Das heißt, er erzeugt keinen Fehler, selbst wenn keine oder alle der angegebenen Werte für die -Eigenschaft festgelegt sind.

Hinweis Der WinNT-Anbieter ignoriert den vom InControlCode-Argument übergebenen Wert und führt bei Verwendung von PutEx das Äquivalent einer ADS_PROPERTY_UPDATE-Anforderung aus.

Beispiele

Im folgenden Codebeispiel wird die Verwendung der IADs.PutEx-Methode veranschaulicht.

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

Im folgenden Codebeispiel wird die Verwendung der IADs::P utEx-Methode veranschaulicht.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	iads.h
DLL	Activeds.dll