TcEnumerateFlows function (traffic.h)
The TcEnumerateFlows function enumerates installed flows and their associated filters on an interface.
The process of returning flow enumeration often consists of multiple calls to the TcEnumerateFlows function. The process of receiving flow information from TcEnumerateFlows can be compared to reading through a book in multiple sittings, where a certain number of pages are read at one time, a bookmark is placed where reading stops, reading is resumed at the bookmark, and continues until the book is finished.
The TcEnumerateFlows function fills the Buffer parameter with as many flow enumerations as the buffer can hold, then returns a handle in the pEnumToken parameter that internally bookmarks where the enumeration stopped. Subsequent calls to TcEnumerateFlows must then pass the returned pEnumToken value to instruct traffic control where to resume flow enumeration information. When all flows have been enumerated, pEnumToken will be NULL.
Syntax
ULONG TcEnumerateFlows(
[in] HANDLE IfcHandle,
[in, out] PHANDLE pEnumHandle,
[in, out] PULONG pFlowCount,
[in, out] PULONG pBufSize,
[out] PENUMERATION_BUFFER Buffer
);
Parameters
[in] IfcHandle
Handle associated with the interface on which flows are to be enumerated. This handle is obtained by a previous call to the TcOpenInterface function.
[in, out] pEnumHandle
Pointer to the enumeration token, used internally by traffic control to maintain returned flow information state.
For input of the initial call to TcEnumerateFlows, pEnumToken should be set to NULL. For input on subsequent calls, pEnumToken must be the value returned as the pEnumToken OUT parameter from the immediately preceding call to TcEnumerateFlows.
For output, pEnumToken is the refreshed enumeration token that must be used in the following call to TcEnumerateFlows.
[in, out] pFlowCount
Pointer to the number of requested or returned flows. For input, this parameter designates the number of requested flows or it can be set to 0xFFFF to request all flows. For output, pFlowCount returns the number of flows actually returned in Buffer.
[in, out] pBufSize
Pointer to the size of the client-provided buffer or the number of bytes used by traffic control. For input, points to the size of Buffer, in bytes. For output, points to the actual amount of buffer space, in bytes, written or needed with flow enumerations.
[out] Buffer
Pointer to the buffer containing flow enumerations. See ENUMERATION_BUFFER for more information about flow enumerations.
Return value
Return code | Description |
---|---|
|
The function executed without errors. |
|
Invalid interface handle. |
|
One of the pointers is NULL, or pFlowCount or pBufSize are set to zero. |
|
The buffer is too small to store even a single flow's information and attached filters. |
|
The system is out of memory. |
|
The enumeration token is no longer valid. |
Remarks
Do not request zero flows, or pass a buffer with a size equal to zero or pointer to a NULL.
If an enumeration token pointer has been invalidated by traffic control (due to the deletion of a flow), continuing to enumerate flows is not allowed, and the call will return ERROR_INVALID_DATA. Under this circumstance, the process of enumeration must start over. This circumstance can occur when the next flow to be enumerated is deleted while enumeration is in progress.
To get the total number of flows for a given interface, call TcQueryInterface and specify GUID_QOS_FLOW_COUNT.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 2000 Professional [desktop apps only] |
Minimum supported server | Windows 2000 Server [desktop apps only] |
Target Platform | Windows |
Header | traffic.h |
Library | Traffic.lib |
DLL | Traffic.dll |