Platform SDK: Quality of Service

ClNotifyHandler

The ClNotifyHandler function is used by traffic control to notify the client of various traffic control–specific events, including the deletion of flows, changes in filter parameters, or the closing of an interface.

The ClNotifyHandler callback function should be exposed by all clients using traffic control services.

VOID ClNotifyHandler(
  HANDLE ClRegCtx,
  HANDLE ClIfcCtx,
  ULONG Event,
  ULONG SubCode,
  ULONG BufSize,
  PVOID Buffer
);

Parameters

ClRegCtx: [in] Client registration context, provided to traffic control by the client with the client's call to the TcRegisterClient function.
ClIfcCtx: [in] Client interface context, provided to traffic control by the client with the client's call to the TcOpenInterface function. Note that during a TC_NOTIFY_IFC_UP event, ClIfcCtx is not available and will be set to NULL.
Event: [in] Describes the notification event. See the Remarks section for a list of notification events.
SubCode: [in] Value used to further qualify a notification event. See Note below for Win64 programming issues.
BufSize: [in] Size of the buffer included with the notification event.
Buffer: [in] Buffer containing the detailed event information associated with Event and SubCode.

Remarks

Notification events may require the traffic control client to take particular action or respond appropriately, for example, removing filters or enumerating flows for affected interfaces.

The following table describes the various notification events.

Event	SubCode	Buffer contents	Remarks
TC_NOTIFY_ IFC_UP	None	InterfaceName of the new interface	A new traffic control interface is coming up, and the list of addresses is indicated.
TC_NOTIFY_ IFC_CLOSE	Reason for close	InterfaceName of the closed interface	Indicates an interface that was opened by the client is being closed by the system. Note that the interface and its supported flows and filters are closed by the system upon return from the notification handler. The client does not need to close the interface, delete flows, or delete filters.
TC_NOTIFY_ IFC_CHANGE	None	New parameter value	Used to notify clients that have registered for interface change notification through the NotifyChange parameter of the TcQueryInterface function.
TC_NOTIFY_ PARAM_CHANGED	Pointer to the GUID for a traffic control parameter queried using the TcQueryInterface function.	New parameter value	This event is notified as a result of a change in a parameter previously queried with the NotifyChange flag set.
TC_NOTIFY_ FLOW_CLOSE	ClFlowCtx		Indicates system closure of a client-created flow. The system deletes all associated filters.

Note for Win64 In order to enable proper behavior of the ClNotifyHandler function in Win64 versions of Windows, you must modify the ClNotifyHandler function prototype in traffic.h and recompile as follows:

typedef
VOID (CALLBACK * TCI_NOTIFY_HANDLER)(
    IN HANDLE    ClRegCtx,
    IN HANDLE    ClIfcCtx,
    IN ULONG     Event,
    IN HANDLE    SubCode,
    IN ULONG     BufSize,
    IN PVOID     Buffer
    );

The change is required due to the interaction of SubCode and the TC_NOTIFY_PARAM_CHANGED event. The TC_NOTIFY_PARAM_CHANGED event contains a pointer to the GUID for a traffic control parameter. The ClNotifyHandler function operates properly on current (Win32) systems because pointers and ULONGs are the same size. On Win64 systems, however, this results in an access violation because the 64 bit pointer is truncated to a 32 bit ULONG. Modifying the ClNotifyHandler function prototype in traffic.h (per the revised ClNotifyHandler definition provided in the previous paragraph) and recompiling results in proper operation.

Note Use of the ClNotifyHandler function requires administrative privilege.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.