IADsCollection

IADsCollection インターフェイスは、ホストとなる ADSI オブジェクトが、ディレクトリサービス用の名前付きデータ要素の任意の集合を定義および管理できるようにするデュアルインターフェイスです。

ADSI システムプロバイダーのうち、このインターフェイスをサポートしているのは WinNT プロバイダーのみで、アクティブなファイルサービスのセッション、リソース、印刷ジョブを処理します。

IADsCollection::get__NewEnum メソッドは、この ADSI コレクションオブジェクトに対して IEnumVARIANT を実装する従属列挙子オブジェクトを取得します。関数名にはアンダースコアが 2 つ含まれている点に注意してください (get__NewEnum)。

このメソッドは、S_OK、E_FAIL、E_NOTIMPL を含む標準的な戻り値をサポートします。詳細およびその他の戻り値については、ADSI エラーコードを参照してください。

サーバーがページ検索をサポートしており、クライアントがサーバーで許可されている最大検索結果数を超えるページ制限を指定した場合、IADsCollection::get__NewEnum メソッドは次のような方法でエラーを返します:

• サーバーが結果を返さずにエラーを返した場合、この関数はエラーのみを返します。
• サーバーがエラーの有無にかかわらず部分的な結果 (たとえばサーバーで許可されている最大検索結果数) を返した場合、この関数はサーバーからの部分的な結果をユーザーに返します。
• サーバーがエラーの有無にかかわらずすべての結果 (たとえば各ページの最大検索結果数と複数ページにわたるすべての結果) を返した場合、この関数はサーバーからのすべての結果をユーザーに返します。

例

次の Visual Basic コード例の For Each…In…Next ステートメントは、get__NewEnum メソッドを暗黙的に呼び出します。

Dim fso As IADsFileServiceOperations 
On Error GoTo Cleanup

Set fso = GetObject("WinNT://myComputer/Fabrikam01") 
 
Dim coll As IADsCollection
Set coll = fso.Sessions
 
' The following statement invokes IADsCollection::get__NewEnum.
For Each session In coll 
   MsgBox "Session name: " & session.Name
Next session

Cleanup:
    If (Err.Number<>0) Then
        MsgBox("An error has occurred... " & Err.Number)
    End If
    Set fso = Nothing

次の C++ コード例は、IADsCollection::get__NewEnum を使用してアクティブなファイルサービスセッションを列挙する方法を示しています。

HRESULT EnumCollection(IADsCollection *);

HRESULT GetACollectionOfSessions()
{
    LPWSTR adspath = L"WinNT://myComputer/LanmanServer";
    HRESULT hr = S_OK;
    IADsCollection *pColl = NULL;

    // Bind to file service operations.
    IADsFileServiceOperations *pFso = NULL;
    hr = ADsGetObject(adspath,
                      IID_IADsFileServiceOperations,
                      (void**)&pFso);
    if(FAILED(hr)) {goto Cleanup;}

    // Get the pointer to the collection.
    hr = pFso->Sessions(&pColl);
    if(FAILED(hr)) {goto Cleanup;}

    hr = EnumCollection(pColl);

Cleanup:
    if(pColl) pColl->Release();
    if(pFso) pFso->Release();

    return hr;
}

HRESULT EnumCollection(IADsCollection *pColl)
{
    IUnknown *pUnk=NULL;
    HRESULT hr = S_OK;
    // Get the Enumerator object on the collection object.
    hr = pColl->get__NewEnum(&pUnk);
    if(FAILED(hr)) {goto Cleanup;}

    IEnumVARIANT *pEnum;
    hr = pUnk->QueryInterface(IID_IEnumVARIANT,(void**)&pEnum);
    if(FAILED(hr)) {goto Cleanup;}

    // Enumerate the collection.
    BSTR bstr = NULL;
    VARIANT var;
    IADs *pADs = NULL;
    ULONG lFetch;
    IDispatch *pDisp = NULL;

    VariantInit(&var);
    hr = pEnum->Next(1, &var, &lFetch);
    while(hr == S_OK)
    {
        if (lFetch == 1)    
        {
             pDisp = V_DISPATCH(&var);
             pDisp->QueryInterface(IID_IADs, (void**)&pADs);
             pADs->get_Name(&bstr);
             printf("Session name: %S\n",bstr);
             SysFreeString(bstr);
             pADs->Release();
        }
        VariantClear(&var);
        pDisp->Release();
        pDisp = NULL;
        hr = pEnum->Next(1, &var, &lFetch);
    };
    

Cleanup:
    if(pDisp) pDisp->Release();
    if(pUnk) pUnk->Release();
    if(pColl) pColl->Release();
    if(pEnum) pEnum->Release();
    return hr;
}

名前付きの項目をコレクションに追加します。

このメソッドは、標準的な戻り値に加えて、以下の値をサポートします。

詳細およびその他の戻り値については、ADSI エラーコードを参照してください。

ディレクトリサービスのコレクションは、変更不可能なオブジェクトの集合で構成される場合もあります。

このメソッドは、ADSI システムプロバイダーのいずれでもサポートされていません。

IADsCollection::Remove メソッドは、名前付きの項目をこの ADSI コレクションオブジェクトから削除します。

このメソッドは、S_OK を含む標準的な戻り値をサポートします。詳細およびその他の戻り値については、ADSI エラーコードを参照してください。

ディレクトリサービスのコレクションは、変更不可能なオブジェクトの集合で構成される場合もあります。

項目の直接の削除をサポートしないコレクションは、E_NOTIMPL を返す必要があります。

例

次の Visual Basic コード例は、アクティブなファイルサービスセッションのコレクションから、名前付きのセッションオブジェクトを削除する方法を示しています。

Dim fso As IADsFileServiceOperations 
Dim ses As IADsSession
Dim coll As IADsCollection
Dim mySessionName As String

On Error GoTo Cleanup

Set fso = GetObject("WinNT://myComputer/FabrikamServer") 
Set coll = fso.Sessions

' Insert code to set mySessionName to the name of the mySession 
' session object.
 
' The following statement invokes IADsCollection::Remove.
coll.Remove mySessionName

Cleanup:
    If (Err.Number<>0) Then
        MsgBox("An error has occurred. " & Err.Number)
    End If
    Set fso = Nothing
    Set ses = Nothing
    Set coll = Nothing

次の C++ コード例は、アクティブなファイルサービスセッションのコレクションから、名前付きのセッションオブジェクトを削除する方法を示しています。

HRESULT RemoveASessionObjectFromCollection()
{
    LPWSTR adspath = L"WinNT://myComputer/FabrikamServer";
    HRESULT hr = S_OK;
    IADsCollection *pColl = NULL;
    IADsFileServiceOperations *pFso = NULL;

    hr = ADsGetObject(adspath,IID_IADsFileServiceOperations,(void**)&pFso);
    if(FAILED(hr)) {goto Cleanup;}

    hr = pFso->Sessions(&pColl);
    if(FAILED(hr)) {goto Cleanup;}

    hr = pColl->Remove(CComBSTR("MySession"));

Cleanup
    if(pFso) pFso->Release();
    if(pColl) pColl->Release();

    return hr;
}

コレクションの項目を取得します。

このメソッドは、S_OK を含む標準的な戻り値をサポートします。詳細およびその他の戻り値については、ADSI エラーコードを参照してください。

Sessions コレクション内のセッションの名前がわかっている場合は、IADsCollection::GetObject メソッドを明示的に呼び出してセッションオブジェクトを取得します。

例

次の Visual Basic コード例は、アクティブなファイルサービスセッションのコレクションから、名前付きのセッションオブジェクトを取得する方法を示しています。

Dim fso As IADsFileServiceOperations 
Dim ses As IADsSession
Dim coll As IADsCollection
Dim mySessionName As String

Set fso = GetObject("WinNT://myComputer/FabrikamServer") 
Set coll = fso.Sessions

' Insert code to set mySessionName to the name of mySession.
 
' The following statement invokes IADsCollection::GetObject.
Set ses = coll.GetObject(mySessionName)

次の C++ コード例は、アクティブなファイルサービスセッションのコレクションから、名前付きのセッションオブジェクトを取得する方法を示しています。

HRESULT GetASessionObjectFromCollection(BSTR mySession)
{
    LPWSTR adspath = L"WinNT://myComputer/FabrikamServer";
    IUnknown *pUnk=NULL;
    HRESULT hr = S_OK;
    IADsCollection *pColl = NULL;
    IADsFileServiceOperations *pFso = NULL;
    IADs *pADsObj = NULL;
    VARIANT varObj;
    BSTR bstrObj = NULL;

    VariantInit(&varObj);
    hr = ADsGetObject(adspath, 
                      IID_IADsFileServiceOperations,
                      (void**)&pFso);
    if(FAILED(hr)) {goto Cleanup;}

    hr = pFso->Sessions(&pColl);
    if(FAILED(hr)) {goto Cleanup;}

    hr = pColl->GetObject(mySession, &varObj);
    V_DISPATCH(&varObj)->QueryInterface(IID_IADs,(void**)&pADsObj);
    hr = pADsObj->get_Class(&bstrObj);
    printf("Class of the object obtained from GetObject: %S\n",
             bstrObj);

Cleanup:
    if(bstrObj) SysFreeString(bstrObj);
    if(pFso) pFso->Release();
    VariantClear(&varObj);
    if(pADsObj) pADsObj->Release();
    if(pColl) pColl->Release();

    return hr;
}