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.