VirtualChannelInitEvent function pointer

An application-defined callback function that Remote Desktop Services calls to notify the client DLL of virtual channel events.

The PCHANNEL_INIT_EVENT_FN type defines a pointer to this callback function. VirtualChannelInitEvent is a placeholder for the application-defined or library-defined function name.

Syntax

typedef VOID ( VCAPITYPE *VirtualChannelInitEvent)(
  _In_  LPVOID pInitHandle,
  _In_  UINT event,
  _In_  LPVOID pData,
  _In_  UINT dataLength
);

Parameters

pInitHandle [in]

Handle to the client connection. This is the handle returned in the ppInitHandle parameter of the VirtualChannelInit function.

event [in]

Indicates the event that caused the notification. This parameter can be one of the following values.

Value	Meaning
CHANNEL_EVENT_CONNECTED	A connection has been established with an RD Session Host server that supports virtual channels. The pData parameter is a pointer to a null-terminated string with the name of the server.
CHANNEL_EVENT_DISCONNECTED	The connection to the RD Session Host server has been disconnected. The pData parameter is NULL.
CHANNEL_EVENT_INITIALIZED	The Remote Desktop Connection (RDC) client initialization has been completed. The pDataparameter is NULL.
CHANNEL_EVENT_TERMINATED	The client has been terminated. The pData parameter is NULL.
CHANNEL_EVENT_V1_CONNECTED	A connection has been established with an RD Session Host server that does not support virtual channels. The pData parameter is NULL.
CHANNEL_EVENT_REMOTE_CONTROL_START	A remote control operation has been started. The pData parameter is NULL.
CHANNEL_EVENT_REMOTE_CONTROL_STOP	A remote control operation has been terminated. The pData parameter is a pointer to a null-terminated string containing the name of the server.

 

pData [in]

Pointer to additional data for the event. The type of data depends on the event, as described previously in the event descriptions.

dataLength [in]

Specifies the size, in bytes, of the data in the pData buffer.

Return value

This function does not return a value.

Remarks

The client DLL uses the VirtualChannelInit function to register its VirtualChannelInitEvent function with Remote Desktop Services.

This function is reentrant on a per-handle basis. The function may be called while it is executing, but not on the same handle more than once.

This function is called only after VirtualChannelEntry has completed.

CHANNEL_EVENT_CONNECTED and CHANNEL_EVENT_DISCONNECTED event notifications will not be sent if the connection is transferred to another session. However, the server-side plug-in that is administering the session to which the connection is transferred will receive a reconnection notification. A server-side tool such as Tscon.exe can be used to transfer connections. Refer to Monitoring Session Connections and Disconnections for more information on reconnection notifications.

If the user-mode plug-in must be notified that it has been reconnected (for example, if it must reset its state), the server-side plug-in should send a notification message to the client. This notification should use the protocol that the plug-ins use to communicate with each other.

Requirements

See also

VirtualChannelInit

Send comments about this topic to Microsoft

Build date: 10/26/2012