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 配列を格納します。単一値プロパティは、1 つの要素を持つ配列として表されます。 InControlCode がADS_PROPERTY_CLEARに設定されている場合、vProp で指定されたプロパティの値は関係ありません。

戻り値

このメソッドは、標準の戻り値と、次の値をサポートしています。

詳細については、「 ADSI エラーコード」を参照してください。

注釈

PutEx は通常、複数値属性に値を設定するために使用されます。 IADs::P ut メソッドとは異なり、PutEx では、属性値を変更する前に取得する必要はありません。ただし、PutEx は ADSI プロパティキャッシュに含まれる属性値のみを変更するため、ディレクトリに変更をコミットするには、PutEx 呼び出しのたびに IADs::SetInfo を使用する必要があります。

PutEx を使用すると、 ADS_PROPERTY_APPENDを使用して、複数値属性の既存の値セットに値を追加できます。複数値属性に値を更新、追加、または削除する場合は、配列を使用する必要があります。

Active Directory では、複数値の属性で重複する値を受け入れられません。 PutEx を呼び出して Active Directory オブジェクトの複数値属性に重複する値を追加すると、PutEx 呼び出しは成功しますが、重複する値は無視されます。

同様に、 PutEx を使用して Active Directory オブジェクトの複数値プロパティから 1 つ以上の値を削除した場合、操作は成功します。つまり、指定した値の一部またはすべてがプロパティに設定されていない場合でも、エラーは発生しません。

メモWinNT プロバイダーは、InControlCode 引数で渡された値を無視し、PutEx の使用時にADS_PROPERTY_UPDATE要求と同等の値を実行します。

例

次のコード例は、 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
ヘッダー	iads.h
[DLL]	Activeds.dll