WTSVirtualChannelOpen function (wtsapi32.h)

Opens a handle to the server end of a specified virtual channel.

This function is obsolete. Instead, use the WTSVirtualChannelOpenEx function.

Syntax

HANDLE WTSVirtualChannelOpen(
  [in] HANDLE hServer,
  [in] DWORD  SessionId,
  [in] LPSTR  pVirtualName
);

Parameters

[in] hServer

This parameter must be WTS_CURRENT_SERVER_HANDLE.

[in] SessionId

A Remote Desktop Services session identifier. To indicate the current session, specify WTS_CURRENT_SESSION. You can use the WTSEnumerateSessions function to retrieve the identifiers of all sessions on a specified RD Session Host server.

To open a virtual channel on another user's session, you need to have permission from the Virtual Channel. For more information, see Remote Desktop Services Permissions. To modify permissions on a session, use the Remote Desktop Services Configuration administrative tool.

[in] pVirtualName

A pointer to a null-terminated string containing the virtual channel name. Note that this is an ANSI string even when UNICODE is defined. The virtual channel name consists of one to CHANNEL_NAME_LEN characters, not including the terminating null.

Return value

If the function succeeds, the return value is a handle to the specified virtual channel.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When you have finished using the handle, release it by calling the WTSVirtualChannelClose function.

For an example that shows how to gain access to a virtual channel file handle that can be used for asynchronous I/O, see WTSVirtualChannelQuery.

If you try to use this function to open the same virtual channel multiple times, it can cause a 10-second delay and disrupt the established channel.

Requirements

See also

WTSEnumerateSessions

WTSOpenServer

WTSVirtualChannelClose