channels.h (8598B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef GUAC_RDP_PLUGINS_CHANNELS_H 21#define GUAC_RDP_PLUGINS_CHANNELS_H 22 23#include <freerdp/channels/channels.h> 24#include <freerdp/freerdp.h> 25#include <freerdp/settings.h> 26#include <guacamole/client.h> 27#include <winpr/wtsapi.h> 28 29/** 30 * The maximum number of static channels supported by Guacamole's RDP support. 31 * This value should be given a value which is at least the value of FreeRDP's 32 * CHANNEL_MAX_COUNT. 33 * 34 * NOTE: The value of this macro must be specified statically (not as a 35 * reference to CHANNEL_MAX_COUNT), as its value is extracted and used by the 36 * entry point wrapper code generator (generate-entry-wrappers.pl). 37 */ 38#define GUAC_RDP_MAX_CHANNELS 64 39 40/* Validate GUAC_RDP_MAX_CHANNELS is sane at compile time */ 41#if GUAC_RDP_MAX_CHANNELS < CHANNEL_MAX_COUNT 42#error "GUAC_RDP_MAX_CHANNELS must not be less than CHANNEL_MAX_COUNT" 43#endif 44 45/** Loads the FreeRDP plugin having the given name. With the exception that 46 * this function requires the rdpContext rather than rdpChannels and 47 * rdpSettings, this function is essentially a drop-in replacement for 48 * freerdp_channels_load_plugin() which additionally loads plugins implementing 49 * the PVIRTUALCHANNELENTRYEX version of the channel plugin entry point. The 50 * freerdp_channels_load_plugin() function which is part of FreeRDP can load 51 * only plugins which implement the PVIRTUALCHANNELENTRY version of the entry 52 * point. 53 * 54 * This MUST be called within the PreConnect callback of the freerdp instance 55 * for the referenced plugin to be loaded correctly. 56 * 57 * @param context 58 * The rdpContext associated with the active RDP session. 59 * 60 * @param name 61 * The name of the plugin to load. If the plugin is not statically built 62 * into FreeRDP, this name will determine the filename of the library to be 63 * loaded dynamically. For a plugin named "NAME", the library called 64 * "libNAME-client" will be loaded from the "freerdp2" subdirectory of the 65 * main directory containing the FreeRDP libraries. 66 * 67 * @param data 68 * Arbitrary data to be passed to the plugin entry point. For most plugins 69 * which are built into FreeRDP, this will be another reference to the 70 * rdpSettings struct. The source of the relevant plugin must be consulted 71 * to determine the proper value to pass here. 72 * 73 * @return 74 * Zero if the plugin was loaded successfully, non-zero if the plugin could 75 * not be loaded. 76 */ 77int guac_freerdp_channels_load_plugin(rdpContext* context, 78 const char* name, void* data); 79 80/** 81 * Schedules loading of the FreeRDP dynamic virtual channel plugin having the 82 * given name. This function is essentially a wrapper for 83 * freerdp_dynamic_channel_collection_add() which additionally takes care of 84 * housekeeping tasks which would otherwise need to be performed manually: 85 * 86 * - The ADDIN_ARGV structure used to pass arguments to dynamic virtual 87 * channel plugins is automatically allocated and populated with any given 88 * arguments. 89 * - The SupportDynamicChannels member of the rdpSettings structure is 90 * automatically set to TRUE. 91 * 92 * The "drdynvc" plugin must still eventually be loaded for this function to 93 * have any effect, as it is the "drdynvc" plugin which processes the 94 * collection this function manipulates. 95 * 96 * This MUST be called within the PreConnect callback of the freerdp instance 97 * and the "drdynvc" plugin MUST be loaded at some point after this function is 98 * called for the referenced dynamic channel plugin to be loaded correctly. 99 * 100 * @param settings 101 * The rdpSettings structure associated with the FreeRDP instance, already 102 * populated with any settings applicable to the plugin being loaded. 103 * 104 * @param name 105 * The name of the plugin to load. If the plugin is not statically built 106 * into FreeRDP, this name will determine the filename of the library to be 107 * loaded dynamically. For a plugin named "NAME", the library called 108 * "libNAME-client" will be loaded from the "freerdp2" subdirectory of the 109 * main directory containing the FreeRDP libraries. 110 * 111 * @param ... 112 * Arbitrary arguments to be passed to the plugin entry point. For most 113 * plugins which are built into FreeRDP, this will be another reference to 114 * the rdpSettings struct or NULL. The source of the relevant plugin must 115 * be consulted to determine the proper value(s) to pass here. 116 */ 117void guac_freerdp_dynamic_channel_collection_add(rdpSettings* settings, 118 const char* name, ...); 119 120/** 121 * The number of wrapped channel entry points currently stored within 122 * guac_rdp_wrapped_entry_ex. 123 */ 124extern int guac_rdp_wrapped_entry_ex_count; 125 126/** 127 * All currently wrapped entry points that use the PVIRTUALCHANNELENTRYEX 128 * variant. 129 */ 130extern PVIRTUALCHANNELENTRYEX guac_rdp_wrapped_entry_ex[GUAC_RDP_MAX_CHANNELS]; 131 132/** 133 * Lookup table of wrapper functions for PVIRTUALCHANNELENTRYEX entry points. 134 * Each function within this array is generated at compile time by the entry 135 * point wrapper code generator (generate-entry-wrappers.pl) and automatically 136 * invokes the corresponding wrapped entry point stored within 137 * guac_rdp_wrapped_entry_ex. 138 */ 139extern PVIRTUALCHANNELENTRYEX guac_rdp_entry_ex_wrappers[GUAC_RDP_MAX_CHANNELS]; 140 141/** 142 * Wraps the provided entry point function, returning a different entry point 143 * which simply invokes the original. As long as this function is not invoked 144 * more than GUAC_RDP_MAX_CHANNELS times, each returned entry point will be 145 * unique, even if the provided entry point is not. As FreeRDP will refuse to 146 * load a plugin if its entry point is already loaded, this allows a single 147 * FreeRDP plugin to be loaded multiple times. 148 * 149 * @param client 150 * The guac_client associated with the relevant RDP session. 151 * 152 * @param entry_ex 153 * The entry point function to wrap. 154 * 155 * @return 156 * A wrapped version of the provided entry point, or the unwrapped entry 157 * point if there is insufficient space remaining within 158 * guac_rdp_entry_ex_wrappers to wrap the entry point. 159 */ 160PVIRTUALCHANNELENTRYEX guac_rdp_plugin_wrap_entry_ex(guac_client* client, 161 PVIRTUALCHANNELENTRYEX entry_ex); 162 163/** 164 * The number of wrapped channel entry points currently stored within 165 * guac_rdp_wrapped_entry. 166 */ 167extern int guac_rdp_wrapped_entry_count; 168 169/** 170 * All currently wrapped entry points that use the PVIRTUALCHANNELENTRY 171 * variant. 172 */ 173extern PVIRTUALCHANNELENTRY guac_rdp_wrapped_entry[GUAC_RDP_MAX_CHANNELS]; 174 175/** 176 * Lookup table of wrapper functions for PVIRTUALCHANNELENTRY entry points. 177 * Each function within this array is generated at compile time by the entry 178 * point wrapper code generator (generate-entry-wrappers.pl) and automatically 179 * invokes the corresponding wrapped entry point stored within 180 * guac_rdp_wrapped_entry. 181 */ 182extern PVIRTUALCHANNELENTRY guac_rdp_entry_wrappers[GUAC_RDP_MAX_CHANNELS]; 183 184/** 185 * Wraps the provided entry point function, returning a different entry point 186 * which simply invokes the original. As long as this function is not invoked 187 * more than GUAC_RDP_MAX_CHANNELS times, each returned entry point will be 188 * unique, even if the provided entry point is not. As FreeRDP will refuse to 189 * load a plugin if its entry point is already loaded, this allows a single 190 * FreeRDP plugin to be loaded multiple times. 191 * 192 * @param client 193 * The guac_client associated with the relevant RDP session. 194 * 195 * @param entry 196 * The entry point function to wrap. 197 * 198 * @return 199 * A wrapped version of the provided entry point, or the unwrapped entry 200 * point if there is insufficient space remaining within 201 * guac_rdp_entry_wrappers to wrap the entry point. 202 */ 203PVIRTUALCHANNELENTRY guac_rdp_plugin_wrap_entry(guac_client* client, 204 PVIRTUALCHANNELENTRY entry); 205 206#endif 207