jmuehlner commented on a change in pull request #243: GUACAMOLE-249: Migrate to FreeRDP 2.x URL: https://github.com/apache/guacamole-server/pull/243#discussion_r364076478
########## File path: src/protocols/rdp/doc/svc-example/README.md ########## @@ -0,0 +1,169 @@ +Static Virtual Channel example +============================== + +Guacamole supports use of static virtual channels (SVCs) for transmission of +arbitrary data between the JavaScript client and applications running within +RDP sessions. This example is intended to demonstrate how bidirectional +communication between the Guacamole client and applications within the RDP +server can be accomplished. + +Arbitrary SVCs are enabled on RDP connections by specfying their names as the +value of [the `static-channels` +parameter](http://guacamole.apache.org/doc/gug/configuring-guacamole.html#rdp-device-redirection). +Each name is limited to a maximum of 7 characters. Multiple names may be listed +by separating those names with commas. + +This example consists of a single file, [`svc-example.c`](svc-example.c), which +leverages the terminal server API exposed by Windows to: + + 1. Open a channel called "EXAMPLE" + 2. Wait for blocks of data to be received + 3. Send each received block of data back, unmodified. + +Building the example +-------------------- + +A `Makefile` is provided which uses MinGW to build the `svc-example.exe` +executable, and thus can be used to produce the example application on Linux. +The `Makefile` is not platform-independent, and changes may be needed for +`make` to succeed with your installation of MinGW. If not using MinGW, the C +source itself is standard and should compile with other tools. + +To build on Linux using `make`: + +```console +$ make +i686-w64-mingw32-gcc svc-example.c -lwtsapi32 \ + -D_WIN32_WINNT=0x600 \ + -DWINVER=0x600 -o svc-example.exe +$ +``` + +You can then copy the resulting `svc-example.exe` to the remote desktop that +you wish to test and run it within a command prompt within the remote desktop +session. + +Using the example (and SVCs in general) +--------------------------------------- + +On the remote desktop server side (within the Windows application leveraging +SVCs to communicate with Guacamole), the following functions are used +specifically for reading/writing to the SVC: + + * [`WTSVirtualChannelOpenEx()`](https://docs.microsoft.com/en-us/windows/win32/api/wtsapi32/nf-wtsapi32-wtsvirtualchannelopenex) + * [`WTSVirtualChannelRead()`](https://docs.microsoft.com/en-us/windows/win32/api/wtsapi32/nf-wtsapi32-wtsvirtualchannelread) + * [`WTSVirtualChannelWrite()`](https://docs.microsoft.com/en-us/windows/win32/api/wtsapi32/nf-wtsapi32-wtsvirtualchannelwrite) + * [`WTSVirtualChannelClose()`](https://docs.microsoft.com/en-us/windows/win32/api/wtsapi32/nf-wtsapi32-wtsvirtualchannelclose) + +On the Guacamole side, bidirectional communication is established using: + + * The `static-channels` connection parameter (in the case of the example, this should be set to `EXAMPLE`). + * An [`onpipe`](http://guacamole.apache.org/doc/guacamole-common-js/Guacamole.Client.html#event:onpipe) + handler which handles inbound (server-to-client) pipe streams named identically + to the SVC. The inbound pipe stream will be received upon establishing the RDP + connection and is used to transmit any data sent along the SVC **from** within Review comment: Why is just the word `from` emphasized here? ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
