VirtualChannelInitEx (Windows CE 5.0)
This function registers the names of the virtual channels that it wants to access. It reserves the names for use by an application, but does not open the channels. This function is a virtual extension that can be used to protect per-session data in the virtual channel client DLL. This function must be called before the client connects to the server. Therefore, the DLL's initialization procedure should call this function.
typedef UINT VCAPITYPE VIRTUALCHANNELINITEX(LPVOID lpUserParam,LPVOID pInitHandle,PCHANNEL_DEF pChannel,INT channelCount,ULONG versionRequested,PCHANNEL_INIT_EVENT_EX_FN pChannelInitEventProcEx);
Parameters
- lpUserParam
[in] Pointer to a user-defined value that is passed in callbacks. - ppInitHandle
[in] Pointer to a variable that receives a handle identifying the client connection. Use this handle to identify the client in subsequent calls to the VirtualChannelOpenEx 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 opens. The VirtualChannelInitEx function call does not open these virtual channels; it only reserves the names for use by this application. - channelCount
[in] Specifies the number of channels that are registered. This is the number of CHANNEL_DEF structures in the pChannel parameter. - versionRequested
[in] Specifies the level of virtual channel support that is requested. Set this parameter to VIRTUAL_CHANNEL_VERSION_WIN2000. - pChannelInitEventProcEx
[in] Pointer to an application-defined VirtualChannelInitEventEx function.
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 | VirtualChannelInitEx was not called from within your VirtualChannelEntryEx 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 VirtualChannelInitEx function in the CHANNEL_ENTRY_POINTS_EX structure passed to your VirtualChannelEntry entry point.
You can call VirtualChannelInitEx only from your VirtualChannelEntryEx function. Calls to VirtualChannelInitEx at any other time fail.
When VirtualChannelInitEx 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 VirtualChannelInitEventEx 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 VirtualChannelInitEx 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.
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 5.0 and later.
Header: Cchannel.h.
Link Library: Developer implemented.
See Also
Send Feedback on this topic to the authors