Metodo IADs::P utEx (iads.h)

Articolo
08/24/2023

Il metodo IADs::P utEx modifica i valori di un attributo nella cache degli attributi ADSI. Ad esempio, per le proprietà che consentono più valori, è possibile aggiungere valori aggiuntivi a un set esistente di valori, modificare i valori nel set, rimuovere i valori specificati dal set o eliminare i valori dal set.

Sintassi

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

Parametri

[in] lnControlCode

Codice di controllo che indica la modalità di modifica: Append, Replace, Remove e Delete. Per altre informazioni e un elenco di valori, vedere ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Contiene un valore BSTR che specifica il nome della proprietà.

[in] vProp

Contiene una matrice VARIANT che contiene il nuovo valore o i nuovi valori della proprietà . Una proprietà a valore singolo è rappresentata come matrice con un singolo elemento. Se InControlCode è impostato su ADS_PROPERTY_CLEAR, il valore della proprietà specificata da vProp è irrilevante.

Valore restituito

Questo metodo supporta i valori restituiti standard, nonché i seguenti.

Per altre informazioni, vedere Codici di errore ADSI.

Commenti

PutEx viene in genere usato per impostare i valori sugli attributi multivalore. A differenza del metodo IADs::P ut , con PutEx non è necessario ottenere i valori dell'attributo prima di modificarli. Tuttavia, poiché PutEx apporta solo modifiche ai valori degli attributi contenuti nella cache delle proprietà ADSI, è necessario usare IADs::SetInfo dopo ogni chiamata PutEx per eseguire il commit delle modifiche nella directory.

PutEx consente di aggiungere valori a un set di valori esistente in un attributo multivalore usando ADS_PROPERTY_APPEND. Quando si aggiornano, aggiungono o eliminano valori a un attributo multivalore, è necessario usare una matrice.

Active Directory non accetta valori duplicati in un attributo multivalore. Se si chiama PutEx per aggiungere un valore duplicato a un attributo multivalore di un oggetto Active Directory, la chiamata PutEx ha esito positivo, ma il valore duplicato viene ignorato.

Analogamente, se si utilizza PutEx per eliminare uno o più valori da una proprietà multivalore di un oggetto Active Directory, l'operazione ha esito positivo, ovvero non genererà un errore, anche se uno o tutti i valori specificati non sono impostati sulla proprietà .

Nota Il provider WinNT ignora il valore passato dall'argomento InControlCode ed esegue l'equivalente di una richiesta di ADS_PROPERTY_UPDATE quando si usa PutEx.

Esempio

Nell'esempio di codice seguente viene illustrato come usare il metodo 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

Nell'esempio di codice seguente viene illustrato come usare il metodo 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();

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	iads.h
DLL	Activeds.dll

Vedi anche

IADs::Get

IADs::GetEx

ID::P ut

Cache delle proprietà