IEnumConnections Interface

The IEnumConnections interface provides the standard methods for enumerating connections.


                    interface DECLSPEC_UUID("72AD0C90-28BD-11d0-9597-00C04FD91890")
IEnumConnections : public IUnknown
{
public:
    virtual HRESULT STDMETHODCALLTYPE Next( 
        ULONG cConnections,
        CONNECTDATA *rgConnections,
        ULONG *pcFetched) = 0;
    
    virtual HRESULT STDMETHODCALLTYPE Skip( 
        ULONG cConnections) = 0;
    
    virtual HRESULT STDMETHODCALLTYPE Reset( void) = 0;
    
    virtual HRESULT STDMETHODCALLTYPE Clone( 
        IEnumConnections **ppEnum) = 0;
    
};

Methods

Next Retrieves a specified number of elements in the enumeration state.
Skip Skips over the next specified element in the enumeration.
Reset Resets the enumeration sequence to the beginning.
Clone Creates a new enumerator that contains the same enumeration state as the current one.

Retrieves a specified number of elements in the enumeration state.

Syntax

HRESULT Next( 
    ULONG cConnections,
    CONNECTDATA *rgConnections,
    ULONG *pcFetched
);

Parameters

cConnections [in] - The number of elements to be retrieved.
rgConnections [out] - A pointer to an array of CONNECTDATA structures. Each structure contains connection information.
pcFetched [out] - A pointer to the number of elements actually retrieved.

Return Value

Returns one of the following values:

S_OK: The method successfully retrieved the requested number of elements.
S_FALSE: The method did not retrieve all the requested elements, but it did retrieve at least one.
E_POINTER: The rgConnections or pcFetched parameter is NULL.
Other COM error codes.

Remarks

This method is used to iterate through the available connections.
The caller is responsible for freeing the memory allocated for the CONNECTDATA structures when they are no longer needed.

Skip

Skips over the next specified element in the enumeration.

Syntax

HRESULT Skip( 
    ULONG cConnections
);

Parameters

cConnections [in] - The number of elements to skip.

Return Value

S_OK: The method successfully skipped the requested number of elements.
S_FALSE: The method did not skip all the requested elements, meaning the end of the enumeration was reached.
Other COM error codes.

Reset

Resets the enumeration sequence to the beginning.

Syntax

HRESULT Reset( void);

Return Value

S_OK: The method successfully reset the enumeration.
Other COM error codes.

Clone

Creates a new enumerator that contains the same enumeration state as the current one.

Syntax

HRESULT Clone( 
    IEnumConnections **ppEnum
);

Parameters

ppEnum [out] - A pointer to a pointer to the newly created enumerator object.

Return Value

S_OK: The method successfully created a clone of the enumerator.
E_OUTOFMEMORY: Not enough memory is available to create the new enumerator.
Other COM error codes.

Remarks

The new enumerator will be positioned at the same element as the current enumerator.
Subsequent modifications to either enumerator will not affect the other.