disp.h (6773B)
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_CHANNELS_DISP_H 21#define GUAC_RDP_CHANNELS_DISP_H 22 23#include "settings.h" 24 25#include <freerdp/client/disp.h> 26#include <freerdp/freerdp.h> 27#include <guacamole/client.h> 28#include <guacamole/timestamp.h> 29 30/** 31 * The minimum value for width or height, in pixels. 32 */ 33#define GUAC_RDP_DISP_MIN_SIZE 200 34 35/** 36 * The maximum value for width or height, in pixels. 37 */ 38#define GUAC_RDP_DISP_MAX_SIZE 8192 39 40/** 41 * The minimum amount of time that must elapse between display size updates, 42 * in milliseconds. 43 */ 44#define GUAC_RDP_DISP_UPDATE_INTERVAL 500 45 46/** 47 * Display size update module. 48 */ 49typedef struct guac_rdp_disp { 50 51 /** 52 * The guac_client instance handling the relevant RDP connection. 53 */ 54 guac_client* client; 55 56 /** 57 * Display control interface. 58 */ 59 DispClientContext* disp; 60 61 /** 62 * The timestamp of the last display update request, or 0 if no request 63 * has been sent yet. 64 */ 65 guac_timestamp last_request; 66 67 /** 68 * The last requested screen width, in pixels. 69 */ 70 int requested_width; 71 72 /** 73 * The last requested screen height, in pixels. 74 */ 75 int requested_height; 76 77 /** 78 * Whether the size has changed and the RDP connection must be closed and 79 * reestablished. 80 */ 81 int reconnect_needed; 82 83} guac_rdp_disp; 84 85/** 86 * Allocates a new display update module, which will ultimately control the 87 * display update channel once connected. 88 * 89 * @param client 90 * The guac_client instance handling the relevant RDP connection. 91 * 92 * @return 93 * A newly-allocated display update module. 94 */ 95guac_rdp_disp* guac_rdp_disp_alloc(guac_client* client); 96 97/** 98 * Frees the resources associated with support for the RDP Display Update 99 * channel. Only resources specific to Guacamole are freed. Resources specific 100 * to FreeRDP's handling of the Display Update channel will be freed by 101 * FreeRDP. If no resources are currently allocated for Display Update support, 102 * this function has no effect. 103 * 104 * @param disp 105 * The display update module to free. 106 */ 107void guac_rdp_disp_free(guac_rdp_disp* disp); 108 109/** 110 * Adds FreeRDP's "disp" plugin to the list of dynamic virtual channel plugins 111 * to be loaded by FreeRDP's "drdynvc" plugin. The context of the plugin will 112 * automatically be associated with the guac_rdp_disp instance pointed to by the 113 * current guac_rdp_client. The plugin will only be loaded once the "drdynvc" 114 * plugin is loaded. The "disp" plugin ultimately adds support for the Display 115 * Update channel. 116 * 117 * If failures occur, messages noting the specifics of those failures will be 118 * logged, and the RDP side of Display Update support will not be functional. 119 * 120 * This MUST be called within the PreConnect callback of the freerdp instance 121 * for Display Update support to be loaded. 122 * 123 * @param context 124 * The rdpContext associated with the active RDP session. 125 */ 126void guac_rdp_disp_load_plugin(rdpContext* context); 127 128/** 129 * Requests a display size update, which may then be sent immediately to the 130 * RDP server. If an update was recently sent, this update may be delayed until 131 * the RDP server has had time to settle. The width/height values provided may 132 * be automatically altered to comply with the restrictions imposed by the 133 * display update channel. 134 * 135 * @param disp 136 * The display update module which should maintain the requested size, 137 * sending the corresponding display update request when appropriate. 138 * 139 * @param settings 140 * The RDP client settings associated with the current or pending RDP 141 * session. These settings will be automatically adjusted to match the new 142 * screen size. 143 * 144 * @param rdp_inst 145 * The FreeRDP instance associated with the current or pending RDP session, 146 * if any. If no RDP session is active, this should be NULL. 147 * 148 * @param width 149 * The desired display width, in pixels. Due to the restrictions of the RDP 150 * display update channel, this will be contrained to the range of 200 151 * through 8192 inclusive, and rounded down to the nearest even number. 152 * 153 * @param height 154 * The desired display height, in pixels. Due to the restrictions of the 155 * RDP display update channel, this will be contrained to the range of 200 156 * through 8192 inclusive. 157 */ 158void guac_rdp_disp_set_size(guac_rdp_disp* disp, guac_rdp_settings* settings, 159 freerdp* rdp_inst, int width, int height); 160 161/** 162 * Sends an actual display update request to the RDP server based on previous 163 * calls to guac_rdp_disp_set_size(). If an update was recently sent, the 164 * update may be delayed until a future call to this function. If the RDP 165 * session has not yet been established, the request will be delayed until the 166 * session exists. 167 * 168 * @param disp 169 * The display update module which should track the update request. 170 * 171 * @param settings 172 * The RDP client settings associated with the current or pending RDP 173 * session. These settings will be automatically adjusted to match the new 174 * screen size. 175 * 176 * @param rdp_inst 177 * The FreeRDP instance associated with the current or pending RDP session, 178 * if any. If no RDP session is active, this should be NULL. 179 */ 180void guac_rdp_disp_update_size(guac_rdp_disp* disp, 181 guac_rdp_settings* settings, freerdp* rdp_inst); 182 183/** 184 * Signals the given display update module that the requested reconnect has 185 * been performed. 186 * 187 * @param disp 188 * The display update module that should be signaled regarding the state 189 * of reconnection. 190 */ 191void guac_rdp_disp_reconnect_complete(guac_rdp_disp* disp); 192 193/** 194 * Returns whether a full RDP reconnect is required for display update changes 195 * to take effect. 196 * 197 * @param disp 198 * The display update module that should be checked to determine whether a 199 * reconnect is required. 200 * 201 * @return 202 * Non-zero if a reconnect is needed, zero otherwise. 203 */ 204int guac_rdp_disp_reconnect_needed(guac_rdp_disp* disp); 205 206#endif 207