Platform SDK: Active Directory, ADSI, and Directory Services

IADsCollection::get__NewEnum

The IADsCollection::get__NewEnum method gets a dependent enumerator object that implements IEnumVARIANT for this ADSI collection object. Notice that there are two underscore characters in the function name (get__NewEnum).

HRESULT IADsCollection::get__NewEnum(
  IUnknown ** ppEnumerator 
);

Parameters

ppEnumerator: [out] Indirect pointer to the IUnknown interface on the enumerator object for this collection.

Return Values

This method supports the standard return values including S_OK, E_FAIL, or E_NOTIMPL. For other return values, see ADSI Error Codes.

Remarks

When a server supports paged search and the client has specified the page limit greater than the maximum search results allowed on the server, the IADsCollection::get__NewEnum method returns errors in the following ways:

If the server returns an error with no results, the function returns the error only.
If the server returns partial results with or without an error, for example, the maximum search results allowed on the server, the function returns the partial results from the server to the user.
If the server returns all results with or without an error, for example, maximum search results on each page and all results through multiple pages, the function returns all the results from the server to the user.

Example Code [Visual Basic]

In Visual Basic®, the For Each …In … Next statement invokes this method implicitly. For example,

Dim fso as IADsFileServiceOperations 
Set fso = GetObject("WinNT://myComputer/LanmanServer") 
 
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

Example Code [C++]

The following C++ code snippet shows how IADsColection::get__NewEnum is used to enumerate active file service sessions.

HRESULT EnumCollection(IADsCollection *);

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

    // bind to file service operations
    IADsFileServiceOperations *pFso;
    hr = ADsGetObject(adspath,
                      IID_IADsFileServiceOperations,
                      (void**)&pFso);
    if(FAILED(hr)) return hr;

    // get the pointer to the collection
    hr = pFso->Sessions(&pColl);
    if(FAILED(hr)) return hr;
    pFso->Release();

    hr = EnumCollection(pColl);
    if(pColl) pColl->Release();

    return hr;
}

HRESULT EnumCollectioin(IADsCollection *pColl)
{
    IUnknown *pUnk=NULL;
    HRESULT hr;
    // get the Enumerator object on the collection object.
    hr = pColl->get__NewEnum(&pUnk);
    if (FAILED(hr) ) return hr;
    pColl->Release();

    IEnumVARIANT *pEnum;
    hr = pUnk->QueryInterface(IID_IEnumVARIANT,(void**)&pEnum);
    if (FAILED(hr)) return hr;
    pUnk->Release();

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

    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=NULL;
        hr = pEnum->Next(1, &var, &lFetch);
    };
    hr = pEnum->Release();

    return S_OK;

}

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.