Programming reference for virtual channels
To allow all virtual channels to be opened inside an ICA session, you must disable the ‘Virtual Channel Allow list’ policy on DDC. For more information, see Virtual channel allow list policy settings documentation.
WFVirtualChannelOpen
This function opens a handle to a specific virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelOpen (
IN HANDLE hServer,
IN DWORD SessionId,
IN LPSTR pVirtual Name * ANSI name *
);
Parameters
| Parameter | Description |
|---|---|
| hServer | A handle to a server. Use the WFOpenServer() function to obtain a handle for a particular server, or specify WF_CURRENT_SERVER_HANDLE to use the current server. |
| SessionId | The session ID of the target session. Use WF_CURRENT_SESSION to specify the current session. |
| pVirtualName | A pointer to the virtual channel name. This is a seven-character ANSI string (even when Unicode is defined), padded with trailing spaces if necessary. |
The first three characters represent the OEM ID (CTX for Citrix Systems,Inc.). The next four characters represent the virtual channel name.
Some of the currently-defined virtual channels are:
| Defined name | ANSI string Description |
|---|---|
| VIRTUAL_CDM | “CTXCDM “ Client drive mapping |
| VIRTUAL_THINWIRE | “CTXTW “ Remote window data |
Note: The virtual channel name must be a string exactly 8 bytes long. The number of visible characters is 7. The last byte is 0, which is used to terminate the string. Note the padding spaces in each name.
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
Remarks
This function can be used only with existing virtual channels. To develop virtual channel drivers, use this SDK and the Citrix Virtual Channel SDK. On WS VDAs, there is only one session, use WF_CURRENT_SESSION to specify the target session.
WFVirtualChannelClose
This function closes an open virtual channel handle.
C calling convention
BOOL WINAPI WFVirutalChannelClose (
IN HANDLE hChannelHandle
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFVirtualChannelPurgeInput
This function purges all queued input data sent from the client to the server on a specified virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelPurgeInput(
IN HANDLE hChannelHandle
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFVirtualChannelPurgeOutput
This function purges all queued output data sent from the server to the client on a specified virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelPurgeOutput(
IN HANDLE hChannelHandle
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFVirtualChannelQuery
This function retrieves data that is related to a specified virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelQuery(
IN HANDLE hChannelHandle,
IN WF_VIRTUAL_CLASS VirtualClass,
OUT PVOID *ppBuffer,
OUT DWORD *pBytesReturned
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
| VirtualClass | The type of information that is requested. Currently, the only defined value is WFVirtualClientData, which returns virtual channel client module data. |
| ppBuffer | A pointer to the address of a variable that receives the data. The buffer is allocated within this function and is de-allocated using the WFFreeMemory() function. |
| pBytesReturned | A pointer to a variable that receives the number of bytes read. |
WFVirtualChannelRead
This function reads data from a specified virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelRead(
IN HANDLE hChannelHandle,
IN ULONG TimeOut,
OUT PCHAR Buffer,
IN ULONG BufferSize,
OUT PULONG pBytesRead
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
| TimeOut | The time-out value in milliseconds. If this value is zero (0), the function returns immediately because there is no data to be read. If the value is INFINITE (or -1), the function continues to wait until there is data to be read. (INFINITE is defined in the Winbase.h file; for more information, see the Microsoft programming documentation.) |
| Buffer | The buffer that receives the data that is read from the virtual channel. |
| BufferSize | The length, in bytes, of the receive buffer. |
| pBytes | A pointer to a variable that receives the number of bytes read. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFVirtualChannelReadEx
This function reads data from a specified virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelReadEx(
IN HANDLE hChannelHandle,
IN HANDLE hCancelEvent,
OUT PCHAR Buffer,
IN ULONG BufferSize,
OUT PULONG pBytesRead
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
| hCancelEvent | A handle to an event upon which the function will wait to cancel the read when it is signaled. The event must exist before this function is issued. |
| Buffer | The buffer that receives the data that is read from the virtual channel. |
| BufferSize | The length, in bytes, of the receive buffer. |
| pBytes | A pointer to a variable that will receive the number of bytes read. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.
WFVirtualChannelWrite
This function writes data to a specified virtual channel.
C calling convention
BOOL WINAPI WFVirutalChannelWrite(
IN HANDLE hChannelHandle,
IN PCHAR Buffer,
IN ULONG Length,
OUT PULONG pBytesWritten
);
Parameters
| Parameter | Description |
|---|---|
| hChannelHandle | A handle to a previously-opened virtual channel. Use the WFVirtualChannelOpen() function to obtain a handle for a specific channel. |
| Buffer | The buffer that contains the data to be written to the virtual channel. |
| Length | The length, in bytes, of the data to be written. |
| pBytesWritten | A pointer to a variable that receives the number of bytes written. |
Returns
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Use the GetLastError() function to get the extended error status.