Метод IADs::P utEx (iads.h)

Статья
08/24/2023

Метод IADs::P utEx изменяет значения атрибута в кэше атрибутов ADSI. Например, для свойств, которые допускают несколько значений, можно добавить дополнительные значения к существующему набору значений, изменить значения в наборе, удалить указанные значения из набора или удалить значения из набора.

Синтаксис

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

Параметры

[in] lnControlCode

Управляющий код, указывающий режим изменения: Append, Replace, Remove и Delete. Дополнительные сведения и список значений см. в разделе ADS_PROPERTY_OPERATION_ENUM.

[in] bstrName

Содержит BSTR , указывающий имя свойства.

[in] vProp

Содержит массив VARIANT , содержащий новое значение или значения свойства . Однозначное свойство представляется в виде массива с одним элементом. Если inControlCode имеет значение ADS_PROPERTY_CLEAR, значение свойства, указанного в vProp , не имеет значения.

Возвращаемое значение

Этот метод поддерживает стандартные возвращаемые значения, а также следующие.

Дополнительные сведения см. в разделе Коды ошибок ADSI.

PutEx обычно используется для задания значений для атрибутов с несколькими значениями. В отличие от метода IADs::P ut , с PutEx вам не требуется получать значения атрибутов перед их изменением. Однако, поскольку PutEx вносит изменения только в значения атрибутов, содержащиеся в кэше свойств ADSI, необходимо использовать IADs::SetInfo после каждого вызова PutEx , чтобы зафиксировать изменения в каталоге.

PutEx позволяет добавлять значения к существующему набору значений в атрибуте с несколькими значениями с помощью ADS_PROPERTY_APPEND. При обновлении, добавлении или удалении значений в атрибуте с несколькими значениями необходимо использовать массив.

Active Directory не принимает повторяющиеся значения для многозначного атрибута. При вызове Метода PutEx для добавления повторяющегося значения к атрибуту с несколькими значениями объекта Active Directory вызов PutEx будет выполнен успешно, но повторяющееся значение игнорируется.

Аналогичным образом, если вы используете PutEx для удаления одного или нескольких значений из свойства с несколькими значениями объекта Active Directory, операция завершается успешно, т. е. не приведет к ошибке, даже если для свойства не заданы какие-либо или все указанные значения.

Примечание Поставщик WinNT игнорирует значение, переданное аргументом InControlCode , и выполняет эквивалент запроса ADS_PROPERTY_UPDATE при использовании PutEx.

Примеры

В следующем примере кода показано, как использовать метод 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

В следующем примере кода показано, как использовать метод 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();

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Целевая платформа	Windows
Header	iads.h
DLL	Activeds.dll