libguac  1.5.4
client.h
Go to the documentation of this file.
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_CLIENT_H
21 #define _GUAC_CLIENT_H
22 
29 #include "client-fntypes.h"
30 #include "client-types.h"
31 #include "client-constants.h"
32 #include "layer-types.h"
33 #include "object-types.h"
34 #include "pool-types.h"
35 #include "rwlock.h"
36 #include "socket-types.h"
37 #include "stream-types.h"
38 #include "timestamp-types.h"
39 #include "user-fntypes.h"
40 #include "user-types.h"
41 
42 #include <cairo/cairo.h>
43 
44 #include <pthread.h>
45 #include <stdarg.h>
46 #include <time.h>
47 
48 struct guac_client {
49 
60 
68 
76 
82  void* data;
83 
89 
112 
136 
142  guac_pool* __buffer_pool;
143 
149  guac_pool* __layer_pool;
150 
154  guac_pool* __stream_pool;
155 
160  guac_stream* __output_streams;
161 
170 
175  guac_rwlock __users_lock;
176 
181  guac_user* __users;
182 
187  guac_rwlock __pending_users_lock;
188 
195  timer_t __pending_users_timer;
196 
200  int __pending_users_timer_state;
201 
206  pthread_mutex_t __pending_users_timer_mutex;
207 
212  guac_user* __pending_users;
213 
219  guac_user* __owner;
220 
226 
249 
265 
283 
308  const char** args;
309 
315  void* __plugin_handle;
316 
317 };
318 
326 
332 void guac_client_free(guac_client* client);
333 
345  const char* format, ...);
346 
359  const char* format, va_list ap);
360 
368 void guac_client_stop(guac_client* client);
369 
382  const char* format, ...);
383 
397  const char* format, va_list ap);
398 
407 
416 
424 void guac_client_free_buffer(guac_client* client, guac_layer* layer);
425 
433 void guac_client_free_layer(guac_client* client, guac_layer* layer);
434 
447 
458 void guac_client_free_stream(guac_client* client, guac_stream* stream);
459 
472 int guac_client_add_user(guac_client* client, guac_user* user, int argc, char** argv);
473 
481 void guac_client_remove_user(guac_client* client, guac_user* user);
482 
504  guac_user_callback* callback, void* data);
505 
524  guac_user_callback* callback, void* data);
525 
552 void* guac_client_for_owner(guac_client* client, guac_user_callback* callback,
553  void* data);
554 
585 void* guac_client_for_user(guac_client* client, guac_user* user,
586  guac_user_callback* callback, void* data);
587 
600 
613 int guac_client_load_plugin(guac_client* client, const char* protocol);
614 
628 
643 int guac_client_owner_send_required(guac_client* client, const char** required);
644 
669 void guac_client_stream_argv(guac_client* client, guac_socket* socket,
670  const char* mimetype, const char* name, const char* value);
671 
701 void guac_client_stream_png(guac_client* client, guac_socket* socket,
702  guac_composite_mode mode, const guac_layer* layer, int x, int y,
703  cairo_surface_t* surface);
704 
739 void guac_client_stream_jpeg(guac_client* client, guac_socket* socket,
740  guac_composite_mode mode, const guac_layer* layer, int x, int y,
741  cairo_surface_t* surface, int quality);
742 
784 void guac_client_stream_webp(guac_client* client, guac_socket* socket,
785  guac_composite_mode mode, const guac_layer* layer, int x, int y,
786  cairo_surface_t* surface, int quality, int lossless);
787 
802 
817 
835 
853 
866 
870 extern const guac_layer* GUAC_DEFAULT_LAYER;
871 
872 #endif
873 
guac_user_join_handler * join_handler
Handler for join events, called whenever a new user is joining an active connection.
Definition: client.h:248
void guac_client_foreach_user(guac_client *client, guac_user_callback *callback, void *data)
Calls the given function on all currently-connected users of the given client.
int guac_client_end_frame(guac_client *client)
Marks the end of the current frame by sending a "sync" instruction to all connected users...
void vguac_client_abort(guac_client *client, guac_protocol_status status, const char *format, va_list ap)
Signals the given client to stop gracefully, while also signalling via the Guacamole protocol that an...
const guac_layer * GUAC_DEFAULT_LAYER
The default Guacamole client layer, layer 0.
int guac_client_supports_webp(guac_client *client)
Returns whether all users of the given client support WebP.
Constants related to the Guacamole client structure, guac_client.
int guac_client_load_plugin(guac_client *client, const char *protocol)
Initializes the given guac_client using the initialization routine provided by the plugin correspondi...
int guac_client_owner_notify_leave(guac_client *client, guac_user *quitter)
Notifies the owner of the given client that a user has left the connection, and returns zero if the m...
Type definitions related to the guac_socket object.
void * guac_user_callback(guac_user *user, void *data)
Callback which relates to a single guac_user at a time, along with arbitrary data.
Definition: user-fntypes.h:59
guac_socket * socket
The guac_socket structure to be used to communicate with all non-pending connected web-clients (users...
Definition: client.h:59
guac_timestamp last_sent_timestamp
The time (in milliseconds) that the last sync message was sent to the client.
Definition: client.h:88
const char ** args
NULL-terminated array of all arguments accepted by this client , in order.
Definition: client.h:308
Type definitions related to Guacamole protocol streams.
The core I/O object of Guacamole.
Definition: socket.h:39
guac_stream * guac_client_alloc_stream(guac_client *client)
Allocates a new stream.
Type definitions related to Guacamole protocol objects.
This file implements reentrant read-write locks using thread-local storage to keep track of how locks...
Definition: rwlock.h:48
guac_client_state
Possible current states of the Guacamole client.
Definition: client-types.h:41
int guac_client_owner_supports_msg(guac_client *client)
Returns whether the owner of the given client supports the "msg" instruction, returning non-zero if t...
void * data
Arbitrary reference to proxy client-specific data.
Definition: client.h:82
void guac_client_free_layer(guac_client *client, guac_layer *layer)
Returns the given layer to the pool of available layers, such that it can be reused by any subsequent...
Type definitions related to the Guacamole client structure, guac_client.
guac_layer * guac_client_alloc_buffer(guac_client *client)
Allocates a new buffer (invisible layer).
int guac_client_owner_supports_required(guac_client *client)
Returns whether the owner of the given client supports the "required" instruction, returning non-zero if the client owner does support the instruction, or zero if the owner does not.
int guac_client_join_pending_handler(guac_client *client)
Handler that will run before immediately before pending users are promoted to full users...
Definition: client-fntypes.h:65
void guac_client_abort(guac_client *client, guac_protocol_status status, const char *format,...)
Signals the given client to stop gracefully, while also signalling via the Guacamole protocol that an...
void vguac_client_log(guac_client *client, guac_client_log_level level, const char *format, va_list ap)
Writes a message in the log used by the given client.
guac_client_log_handler * log_handler
Logging handler.
Definition: client.h:135
void guac_client_stream_jpeg(guac_client *client, guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int x, int y, cairo_surface_t *surface, int quality)
Streams the image data of the given surface over an image stream ("img" instruction) as JPEG-encoded ...
void guac_client_free_buffer(guac_client *client, guac_layer *layer)
Returns the given buffer to the pool of available buffers, such that it can be reused by any subseque...
Function type definitions related to the guac_user object.
int guac_client_free_handler(guac_client *client)
Handler for freeing up any extra data allocated by the client implementation.
Definition: client-fntypes.h:51
Representation of a physical connection within a larger logical connection which may be shared...
Definition: user.h:115
int guac_client_add_user(guac_client *client, guac_user *user, int argc, char **argv)
Adds the given user to the internal list of connected users.
void guac_client_foreach_pending_user(guac_client *client, guac_user_callback *callback, void *data)
Calls the given function on all pending users of the given client.
Type definitions related to the guac_pool pool of unique integers.
void guac_client_stream_argv(guac_client *client, guac_socket *socket, const char *mimetype, const char *name, const char *value)
Streams the given connection parameter value over an argument value stream ("argv" instruction)...
guac_client_state state
The current state of the client.
Definition: client.h:75
int64_t guac_timestamp
An arbitrary timestamp denoting a relative time value in milliseconds.
Definition: timestamp-types.h:34
Function type definitions related to the Guacamole client structure, guac_client. ...
Guacamole proxy client.
Definition: client.h:48
int connected_users
The number of currently-connected users.
Definition: client.h:225
A pool of integers.
Definition: pool.h:34
guac_client * guac_client_alloc()
Returns a new, barebones guac_client.
guac_user_leave_handler * leave_handler
Handler for leave events, called whenever a new user is leaving an active connection.
Definition: client.h:282
void * guac_client_for_owner(guac_client *client, guac_user_callback *callback, void *data)
Calls the given function with the currently-connected user that is marked as the owner.
void guac_client_free(guac_client *client)
Free all resources associated with the given client.
void guac_client_stream_webp(guac_client *client, guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int x, int y, cairo_surface_t *surface, int quality, int lossless)
Streams the image data of the given surface over an image stream ("img" instruction) as WebP-encoded ...
guac_layer * guac_client_alloc_layer(guac_client *client)
Allocates a new layer.
Type definitions related to Guacamole layers.
int guac_user_leave_handler(guac_user *user)
Handler for Guacamole leave events.
Definition: user-fntypes.h:430
guac_composite_mode
Composite modes used by Guacamole draw instructions.
Definition: protocol-types.h:170
guac_client_join_pending_handler * join_pending_handler
A handler that will be run prior to pending users being promoted to full users.
Definition: client.h:264
guac_client_free_handler * free_handler
Handler for freeing data when the client is being unloaded.
Definition: client.h:111
guac_protocol_status
Set of all possible status codes returned by protocol operations.
Definition: protocol-types.h:44
Represents a single layer within the Guacamole protocol.
Definition: layer.h:34
void guac_client_stop(guac_client *client)
Signals the given client to stop gracefully.
void guac_client_stream_png(guac_client *client, guac_socket *socket, guac_composite_mode mode, const guac_layer *layer, int x, int y, cairo_surface_t *surface)
Streams the image data of the given surface over an image stream ("img" instruction) as PNG-encoded d...
void guac_client_remove_user(guac_client *client, guac_user *user)
Removes the given user, removing the user from the internally-tracked list of connected users...
Represents a single stream within the Guacamole protocol.
Definition: stream.h:32
void guac_client_log_handler(guac_client *client, guac_client_log_level level, const char *format, va_list args)
Handler for logging messages related to a given guac_client instance.
Definition: client-fntypes.h:83
int guac_client_get_processing_lag(guac_client *client)
Calculates and returns the approximate processing lag experienced by the pool of users.
int guac_client_owner_send_required(guac_client *client, const char **required)
Sends a request to the owner of the given guac_client for parameters required to continue the connect...
guac_client_log_level
All supported log levels used by the logging subsystem of each Guacamole client.
Definition: client-types.h:62
void guac_client_free_stream(guac_client *client, guac_stream *stream)
Returns the given stream to the pool of available streams, such that it can be reused by any subseque...
guac_socket * pending_socket
The guac_socket structure to be used to communicate with all pending connected web-clients (users)...
Definition: client.h:67
int guac_client_owner_notify_join(guac_client *client, guac_user *joiner)
Notifies the owner of the given client that a user has joined the connection, and returns zero if the...
int guac_user_join_handler(guac_user *user, int argc, char **argv)
Handler for Guacamole join events.
Definition: user-fntypes.h:411
Type definitions related to Guacamole protocol timestamps.
Type definitions related to the guac_user object.
char * connection_id
The unique identifier allocated for the connection, which may be used within the Guacamole protocol t...
Definition: client.h:169
void guac_client_log(guac_client *client, guac_client_log_level level, const char *format,...)
Writes a message in the log used by the given client.
void * guac_client_for_user(guac_client *client, guac_user *user, guac_user_callback *callback, void *data)
Calls the given function with the given user ONLY if they are currently connected.