Share via

VirtualChannelInit

  • Article

This function initializes a client DLL's access to Terminal Services virtual channels. The client calls VirtualChannelInit to register the names of its virtual channels.

UINT VCAPITYPE VirtualChannelInit(
  LPVOID* ppInitHandle,
  PCHANNEL_DEF pChannel,
  INT channelCount,
  ULONG versionRequested,
  PCHANNEL_INIT_EVENT_FN pChannelInitEventProc
);

Parameters

  • ppInitHandle
    [in] Pointer to a variable that receives a handle that identifies the client connection. Use this handle to identify the client in subsequent calls to the VirtualChannelOpen function.
  • pChannel
    [in, out] Pointer to an array of CHANNEL_DEF structures. Each structure contains the name and initialization options of a virtual channel that the client DLL will open. Note that the VirtualChannelInit function call does not open these virtual channels; it only reserves the names for use by this application.
  • channelCount
    [in] Specifies the number of CHANNEL_DEF structures in the pChannel parameter.
  • versionRequested
    [in] Specifies the level of virtual channel support. Set this parameter to VIRTUAL_CHANNEL_VERSION_WIN2000.
  • pChannelInitEventProc
    [in] Pointer to an application-defined VirtualChannelInitEvent function that Terminal Services calls to notify the client DLL of virtual channel events.

Return Values

The following table shows the return values for this function.

Value Description
CHANNEL_RC_OK Function succeeded.
CHANNEL_RC_ALREADY_CONNECTED The client is already connected to a terminal server.
CHANNEL_RC_BAD_CHANNEL The pChannel parameter is incorrect or one of the channel names is syntactically incorrect.
CHANNEL_RC_BAD_INIT_HANDLE The ppInitHandle parameter is incorrect.
CHANNEL_RC_BAD_PROC The pChannelInitEventProc parameter is incorrect.
CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY VirtualChannelInit was not called from within your VirtualChannelEntry function.
CHANNEL_RC_TOO_MANY_CHANNELS The pChannel parameter has more channels than can be registered. Therefore, none of the channels were registered. The maximum number of channels allowed per client is CHANNEL_MAX_COUNT.

Remarks

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

You can call VirtualChannelInit only from your VirtualChannelEntry function. Calls to VirtualChannelInit at any other time fail.

When VirtualChannelInit returns successfully, Terminal Services has registered the requested channels. However, Terminal Services might not have completed other initializations. When the initialization process has completed, Terminal Services calls your VirtualChannelInitEvent callback function with the CHANNEL_EVENT_INITIALIZED event.

Do not make assumptions about the number of available virtual channels before calling this function, because the system and other plug-ins may have reserved virtual channels. You should always check for the CHANNEL_RC_TOO_MANY_CHANNELS return code after calling this function.

When VirtualChannelInit returns, the options member of each CHANNEL_DEF structure includes CHANNEL_OPTION_INITIALIZED if the channel was successfully initialized.

The maximum number of channels per client session is CHANNEL_MAX_COUNT.

RDP Clients (version 5.1 and later) A client plug-in can declare a channel as remote control persistent. This is done by specifying CHANNEL_OPTION_REMOTE_CONTROL_PERSISTENT in a CHANNEL_DEF structure pointed to by the pChannel parameter. For more information, see Remote-Control Persistent Virtual Channels.

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.