TcAddFlow function (traffic.h)
The TcAddFlow function adds a new flow on the specified interface. Note that the successful addition of a flow does not necessarily indicate a change in the way traffic is handled; traffic handling changes are effected by attaching a filter to the added flow, using the TcAddFilter function.
Traffic control clients that have registered an AddFlowComplete handler (a mechanism for allowing traffic control to call the ClAddFlowComplete callback function in order to alert clients of completed flow additions) can expect a return value of ERROR_SIGNAL_PENDING. For more information, see Traffic Control Objects.
Syntax
ULONG TcAddFlow(
[in] HANDLE IfcHandle,
[in] HANDLE ClFlowCtx,
[in] ULONG Flags,
[in] PTC_GEN_FLOW pGenericFlow,
[out] PHANDLE pFlowHandle
);
Parameters
[in] IfcHandle
Handle associated with the interface on which the flow is to be added. This handle is obtained by a previous call to the TcOpenInterface function.
[in] ClFlowCtx
Client provided–flow context handle. Used subsequently by traffic control when referring to the added flow.
[in] Flags
Reserved for future use. Must be set to zero.
[in] pGenericFlow
Pointer to a description of the flow being installed.
[out] pFlowHandle
Pointer to a location into which traffic control will return the flow handle. This flow handle should be used in subsequent calls to traffic control to refer to the installed flow.
Return value
There are many reasons why a request to add a flow might be rejected. Error codes returned by traffic control from calls to TcAddFlow are provided to aid in determining the reason for rejection.
| Return code | Description |
|---|---|
|
The function executed without errors. |
|
The function is being executed asynchronously; the client will be called back through the client-exposed ClAddFlowComplete function when the flow has been added or when the process has been completed. |
|
The interface handle is invalid. |
|
The system is out of memory. |
|
A parameter is invalid. |
|
An unspecified or bad INTSERV service type has been provided. |
|
An unspecified or bad TOKENRATE value has been provided. |
|
The PEAKBANDWIDTH value is invalid. |
|
The SHAPEDISCARDMODE is invalid. |
|
The priority value is invalid. |
|
The traffic class value is invalid. |
|
There are not enough resources to accommodate the requested flow. |
|
Bad length specified for the TC objects. |
|
Applies to Diffserv flows. Indicates that the QOS_DIFFSERV object was passed with an invalid parameter. |
|
Applies to Diffserv flows. Indicates that the QOS_DIFFSERV_RULE specified in TC_GEN_FLOW already applies to an existing flow on the interface. |
|
The QOS_SHAPING_RATE object was passed with an invalid ShapingRate member. |
|
The QOS_DS_CLASS is invalid. |
|
The network cable is not plugged into the adapter. |
Remarks
If the TcAddFlow function returns ERROR_SIGNAL_PENDING, the ClAddFlowComplete function will be called on a different thread than the thread that called the TcAddFlow function.
Only the addition of a filter will affect traffic control. However, the addition of a flow will cause resources to be committed within traffic control components. This enables traffic control to prepare for handling traffic on the added flow.
Traffic control may delete a flow for various reasons, including the inability to accommodate the flow due to bandwidth restrictions, and adjusted policy requirements. Clients are notified of deleted flows through the ClNotifyHandler callback function, with the TC_NOTIFY_FLOW_CLOSE event.
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 |