Método IADs::P utEx (iads.h)

Artículo
08/24/2023

El método IADs::P utEx modifica los valores de un atributo en la caché de atributos ADSI. Por ejemplo, para las propiedades que permiten varios valores, puede anexar valores adicionales a un conjunto de valores existente, modificar los valores del conjunto, quitar valores especificados del conjunto o eliminar valores del conjunto.

Sintaxis

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

Parámetros

[in] lnControlCode

Código de control que indica el modo de modificación: Anexar, Reemplazar, Quitar y Eliminar. Para obtener más información y una lista de valores, vea ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Contiene un BSTR que especifica el nombre de la propiedad.

[in] vProp

Contiene una matriz VARIANT que contiene el nuevo valor o los valores de la propiedad . Una propiedad con un solo valor se representa como una matriz con un solo elemento. Si InControlCode se establece en ADS_PROPERTY_CLEAR, el valor de la propiedad especificada por vProp es irrelevante.

Valor devuelto

Este método admite valores devueltos estándar, así como lo siguiente.

Para obtener más información, consulta Códigos de error adsi.

Comentarios

PutEx se usa normalmente para establecer valores en atributos de varios valores. A diferencia del método IADs::P ut , con PutEx, no es necesario obtener los valores de atributo antes de modificarlos. Sin embargo, dado que PutEx solo realiza cambios en los valores de atributos contenidos en la caché de propiedades ADSI, debe usar IADs::SetInfo después de cada llamada PutEx para confirmar los cambios en el directorio.

PutEx permite anexar valores a un conjunto de valores existente en un atributo de varios valores mediante ADS_PROPERTY_APPEND. Al actualizar, anexar o eliminar valores a un atributo de varios valores, debe usar una matriz.

Active Directory no acepta valores duplicados en un atributo multivalor. Si llama a PutEx para anexar un valor duplicado a un atributo multivalor de un objeto de Active Directory, la llamada PutEx se realiza correctamente, pero se omite el valor duplicado.

Del mismo modo, si usa PutEx para eliminar uno o varios valores de una propiedad multivalor de un objeto de Active Directory, la operación se realiza correctamente, es decir, no producirá un error, incluso si alguno o todos los valores especificados no están establecidos en la propiedad .

Nota El proveedor winNT omite el valor pasado por el argumento InControlCode y realiza el equivalente de una solicitud de ADS_PROPERTY_UPDATE al usar PutEx.

Ejemplos

En el ejemplo de código siguiente se muestra cómo usar el método 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

En el ejemplo de código siguiente se muestra cómo usar el método 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();

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	iads.h
Archivo DLL	Activeds.dll