VirtualChannelOpen

  • Article

This function opens the client end of a virtual channel.

UINT VCAPITYPE VirtualChannelOpen(
  LPVOID pInitHandle,
  LPDWORD pOpenHandle,
  PCHAR pChannelName,
  PCHANNEL_OPEN_EVENT_FN pChannelOpenEventProc
);

Parameters

  • pInitHandle
    [in] Handle to the client connection. This is the handle returned in the ppInitHandle parameter of the VirtualChannelInit function.
  • pOpenHandle
    [out] Pointer to a variable that receives a handle identifying the open virtual channel in subsequent calls to the VirtualChannelWrite and VirtualChannelClose functions.
  • pChannelName
    [in] Pointer to a null-terminated string containing the name of the virtual channel to open. The name must have been registered when the client called VirtualChannelInit.
  • pChannelOpenEventProc
    [in] Pointer to an application-defined VirtualChannelOpenEvent function that Terminal Services calls to notify the client DLL of events for this virtual channel. The following table shows possible values for this parameter.
    Value Description
    CHANNEL_EVENT_CONNECTED A connection has been established with a terminal server that supports virtual channels. pData points to a null-terminated string with the name of the server.
    CHANNEL_EVENT_DISCONNECTED The connection to the terminal server has been disconnected. pData is NULL.
    CHANNEL_EVENT_INITIALIZED The Remote Desktop client initialization has been completed. pData is NULL.
    CHANNEL_EVENT_TERMINATED The client has been terminated. pData is NULL.
    CHANNEL_EVENT_V1_CONNECTED A connection has been established with a terminal server that does not support virtual channels. pData is NULL.

Return Values

The following table shows the return values for this function.

Value Description
CHANNEL_RC_OK Function succeeded.
CHANNEL_RC_ALREADY_OPEN The channel is already open.
CHANNEL_RC_BAD_CHANNEL_HANDLE The pOpenHandle parameter is not valid.
CHANNEL_RC_BAD_INIT_HANDLE The pInitHandle parameter is not valid.
CHANNEL_RC_BAD_PROC The pChannelOpenEventProc parameter is not valid.
CHANNEL_RC_NOT_CONNECTED The client has not connected to a terminal server.
CHANNEL_RC_UNKNOWN_CHANNEL_NAME The channel name specified by the pChannelName parameter is not registered by the client DLL or is otherwise invalid.

Remarks

Terminal Services provides a pointer to a VirtualChannelOpen function in the CHANNEL_ENTRY_POINTS structure passed to your VirtualChannelEntry entry point.

The client DLL cannot call this function until the client has established a connection with a terminal server. Your VirtualChannelInitEvent function receives a CHANNEL_EVENT_CONNECTED notification when a Terminal Server connection is established.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Cchannel.h.
Link Library: Developer implemented.

See Also

RDP Functions

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.