IEnumConnections::Next

HRESULT IEnumConnections::Next([in] ULONG cConnections, [out, max_is(cConnections)] CONNECTDATA *rgpcd, [out] ULONG *pcFetched);

Enumerates the next cConnections elements in the enumerator's list, returning them in rgpcd along with the actual number of enumerated elements in pcFetched. The caller is responsible for calling IUnknown::Release through each pUnk pointer returned in the structure elements of rgpcd.

Argument

Type

Description

cConnections

ULONG

[in] Specifies the number of CONNECTDATA structures to return in the array pointed to by rgpcd. This argument must be 1 if pcFetched is NULL.

rgpcd

CONNECTDATA *

[out] A pointer to a caller-allocated CONNECTDATA array of size cConnections in which to return the enumerated connections. The caller is responsible for calling CONNECTDATA.pUnk->Release for each element in the array once this method returns successfully. If cConnections is greater than one the caller must also pass a non-NULL pointer passed to pcFetched to know how many pointers to release.

pcFetched

ULONG

[out] A pointer to the variable to receive the actual number of connections enumerated in rgpcd. This argument can be NULL in which case the cConnections argument must be 1.


Return Value

Meaning

S_OK

The requested number of elements has been returned and *pcFetched (if non-NULL) is set to cConnections if.

S_FALSE

The enumerator returned fewer elements than cConnections because there were not that many elements left in the list. In this case, unused elements in rgpcd in the enumeration are not set to NULL and *pcFetched holds the number of valid entries, even if zero is returned.

E_POINTER

The address in rgpcd is not valid (such as NULL).

E_INVALIDARG

The value of cConnections is not 1 when pcFetched is NULL; or the value of cConnections is zero.

E_UNEXPECTED

An unknown error occurred.

E_OUTOFMEMORY

There is not enough memory to enumerate the elements.


Comments E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpcn array are valid on exit and require no release.