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

Artigo
08/24/2023

O método IADs::P utEx modifica os valores de um atributo no cache de atributos ADSI. Por exemplo, para propriedades que permitem vários valores, você pode acrescentar valores adicionais a um conjunto de valores existente, modificar os valores no conjunto, remover valores especificados do conjunto ou excluir valores do conjunto.

Sintaxe

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

Parâmetros

[in] lnControlCode

Código de controle que indica o modo de modificação: Acrescentar, Substituir, Remover e Excluir. Para obter mais informações e uma lista de valores, consulte ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Contém um BSTR que especifica o nome da propriedade.

[in] vProp

Contém uma matriz VARIANT que contém o novo valor ou valores da propriedade . Uma propriedade de valor único é representada como uma matriz com um único elemento. Se InControlCode for definido como ADS_PROPERTY_CLEAR, o valor da propriedade especificada por vProp será irrelevante.

Retornar valor

Esse método dá suporte a valores retornados padrão, bem como aos seguintes.

Para obter mais informações, consulte Códigos de erro ADSI.

Comentários

PutEx geralmente é usado para definir valores em atributos de vários valores. Ao contrário do método IADs::P ut , com PutEx, você não precisa obter os valores de atributo antes de modificá-los. No entanto, como PutEx faz alterações apenas em valores de atributos contidos no cache de propriedades ADSI, você deve usar IADs::SetInfo após cada chamada PutEx para confirmar as alterações no diretório.

PutEx permite que você acrescente valores a um conjunto existente de valores em um atributo de vários valores usando ADS_PROPERTY_APPEND. Ao atualizar, acrescentar ou excluir valores a um atributo de vários valores, você deve usar uma matriz.

O Active Directory não aceita valores duplicados em um atributo de vários valores. Se você chamar PutEx para acrescentar um valor duplicado a um atributo de vários valores de um objeto do Active Directory, a chamada PutEx terá êxito, mas o valor duplicado será ignorado.

Da mesma forma, se você usar PutEx para excluir um ou mais valores de uma propriedade de vários valores de um objeto do Active Directory, a operação terá êxito, ou seja, não produzirá um erro, mesmo que qualquer um ou todos os valores especificados não estejam definidos na propriedade .

Nota O provedor WinNT ignora o valor passado pelo argumento InControlCode e executa o equivalente a uma solicitação de ADS_PROPERTY_UPDATE ao usar PutEx.

Exemplos

O exemplo de código a seguir mostra como usar o 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

O exemplo de código a seguir mostra como usar o 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	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	iads.h
DLL	Activeds.dll