IADs ::P utEx, méthode (iads.h)

Article
02/26/2024

La méthode IADs ::P utEx modifie les valeurs d’un attribut dans le cache d’attributs ADSI. Par exemple, pour les propriétés qui autorisent plusieurs valeurs, vous pouvez ajouter des valeurs supplémentaires à un ensemble de valeurs existant, modifier les valeurs du jeu, supprimer les valeurs spécifiées du jeu ou supprimer des valeurs de l’ensemble.

Syntaxe

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

Paramètres

[in] lnControlCode

Code de contrôle qui indique le mode de modification : Ajouter, Remplacer, Supprimer et Supprimer. Pour plus d’informations et une liste de valeurs, consultez ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Contient un BSTR qui spécifie le nom de la propriété.

[in] vProp

Contient un tableau VARIANT qui contient la ou les nouvelles valeurs de la propriété. Une propriété à valeur unique est représentée sous la forme d’un tableau avec un élément unique. Si InControlCode a la valeur ADS_PROPERTY_CLEAR, la valeur de la propriété spécifiée par vProp n’est pas pertinente.

Valeur retournée

Cette méthode prend en charge les valeurs de retour standard, ainsi que les éléments suivants.

Pour plus d’informations, consultez Codes d’erreur ADSI.

Remarques

PutEx est généralement utilisé pour définir des valeurs sur des attributs à valeurs multiples. Contrairement à la méthode IADs ::P ut , avec PutEx, vous n’êtes pas obligé d’obtenir les valeurs d’attribut avant de les modifier. Toutefois, étant donné que PutEx apporte uniquement des modifications aux valeurs d’attribut contenues dans le cache de propriétés ADSI, vous devez utiliser IADs ::SetInfo après chaque appel PutEx afin de valider les modifications apportées au répertoire.

PutEx vous permet d’ajouter des valeurs à un ensemble de valeurs existant dans un attribut à valeurs multiples à l’aide de ADS_PROPERTY_APPEND. Lorsque vous mettez à jour, ajoutez ou supprimez des valeurs à un attribut à valeurs multiples, vous devez utiliser un tableau.

Active Directory n’accepte pas de valeurs en double sur un attribut à valeurs multiples. Si vous appelez PutEx pour ajouter une valeur en double à un attribut à valeurs multiples d’un objet Active Directory, l’appel PutEx réussit, mais la valeur dupliquée est ignorée.

De même, si vous utilisez PutEx pour supprimer une ou plusieurs valeurs d’une propriété à valeurs multiples d’un objet Active Directory, l’opération réussit, c’est-à-dire qu’elle ne génère pas d’erreur, même si l’une ou l’ensemble des valeurs spécifiées ne sont pas définies sur la propriété.

Note Le fournisseur WinNT ignore la valeur transmise par l’argument InControlCode et exécute l’équivalent d’une demande de ADS_PROPERTY_UPDATE lors de l’utilisation de PutEx.

Exemples

L’exemple de code suivant montre comment utiliser la méthode 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

L’exemple de code suivant montre comment utiliser la méthode 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();

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	iads.h
DLL	Activeds.dll