VirtualBox

source: vbox/trunk/include/VBox/RemoteDesktop/VRDE.h@ 87835

Last change on this file since 87835 was 85121, checked in by vboxsync, 4 years ago

iprt/cdefs.h: Refactored the typedef use of DECLCALLBACK as well as DECLCALLBACKMEMBER to wrap the whole expression, similar to the DECLR?CALLBACKMEMBER macros. This allows adding a throw() at the end when compiling with the VC++ compiler to indicate that the callbacks won't throw anything, so we can stop supressing the C5039 warning about passing functions that can potential throw C++ exceptions to extern C code that can't necessarily cope with such (unwind,++). Introduced a few _EX variations that allows specifying different/no calling convention too, as that's handy when dynamically resolving host APIs. Fixed numerous places missing DECLCALLBACK and such. Left two angry @todos regarding use of CreateThread. bugref:9794
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 62.0 KB
Line 
1/** @file
2 * VBox Remote Desktop Extension (VRDE) - Public APIs.
3 */
4
5/*
6 * Copyright (C) 2006-2020 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef VBOX_INCLUDED_RemoteDesktop_VRDE_h
27#define VBOX_INCLUDED_RemoteDesktop_VRDE_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34
35/** @defgroup grp_vrdp VRDE
36 * VirtualBox Remote Desktop Extension (VRDE) interface that lets to use
37 * a Remote Desktop server like RDP.
38 * @{
39 */
40
41RT_C_DECLS_BEGIN
42
43/* Forward declaration of the VRDE server instance handle.
44 * This is an opaque pointer for VirtualBox.
45 * The VRDE library uses it as a pointer to some internal data.
46 */
47#ifdef __cplusplus
48class VRDEServer;
49typedef class VRDEServerType *HVRDESERVER;
50#else
51struct VRDEServer;
52typedef struct VRDEServerType *HVRDESERVER;
53#endif /* !__cplusplus */
54
55/* Callback based VRDE server interface declarations. */
56
57/** The color mouse pointer information. */
58typedef struct _VRDECOLORPOINTER
59{
60 uint16_t u16HotX;
61 uint16_t u16HotY;
62 uint16_t u16Width;
63 uint16_t u16Height;
64 uint16_t u16MaskLen;
65 uint16_t u16DataLen;
66 /* The 1BPP mask and the 24BPP bitmap follow. */
67} VRDECOLORPOINTER;
68
69/** Audio format information packed in a 32 bit value. */
70typedef uint32_t VRDEAUDIOFORMAT;
71
72/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
73#define VRDE_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
74
75/** Decode frequency. */
76#define VRDE_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
77/** Decode number of channels. */
78#define VRDE_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
79/** Decode number signess. */
80#define VRDE_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
81/** Decode number of bits per sample. */
82#define VRDE_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
83/** Decode number of bytes per sample. */
84#define VRDE_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDE_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
85
86
87/*
88 * Audio input.
89 */
90
91/* Audio input notifications. */
92#define VRDE_AUDIOIN_BEGIN 1
93#define VRDE_AUDIOIN_DATA 2
94#define VRDE_AUDIOIN_END 3
95
96typedef struct VRDEAUDIOINBEGIN
97{
98 VRDEAUDIOFORMAT fmt; /* Actual format of data, which will be sent in VRDE_AUDIOIN_DATA events. */
99} VRDEAUDIOINBEGIN, *PVRDEAUDIOINBEGIN;
100
101
102/*
103 * Remote USB protocol.
104 */
105
106/* The initial version 1. */
107#define VRDE_USB_VERSION_1 (1)
108/* Version 2: look for VRDE_USB_VERSION_2 comments in the code. */
109#define VRDE_USB_VERSION_2 (2)
110/* Version 3: look for VRDE_USB_VERSION_3 comments in the code. */
111#define VRDE_USB_VERSION_3 (3)
112
113/* The default VRDE server version of Remote USB Protocol. */
114#define VRDE_USB_VERSION VRDE_USB_VERSION_3
115
116
117/** USB backend operations. */
118#define VRDE_USB_REQ_OPEN (0)
119#define VRDE_USB_REQ_CLOSE (1)
120#define VRDE_USB_REQ_RESET (2)
121#define VRDE_USB_REQ_SET_CONFIG (3)
122#define VRDE_USB_REQ_CLAIM_INTERFACE (4)
123#define VRDE_USB_REQ_RELEASE_INTERFACE (5)
124#define VRDE_USB_REQ_INTERFACE_SETTING (6)
125#define VRDE_USB_REQ_QUEUE_URB (7)
126#define VRDE_USB_REQ_REAP_URB (8)
127#define VRDE_USB_REQ_CLEAR_HALTED_EP (9)
128#define VRDE_USB_REQ_CANCEL_URB (10)
129
130/** USB service operations. */
131#define VRDE_USB_REQ_DEVICE_LIST (11)
132#define VRDE_USB_REQ_NEGOTIATE (12)
133
134/** An operation completion status is a byte. */
135typedef uint8_t VRDEUSBSTATUS;
136
137/** USB device identifier is an 32 bit value. */
138typedef uint32_t VRDEUSBDEVID;
139
140/** Status codes. */
141#define VRDE_USB_STATUS_SUCCESS ((VRDEUSBSTATUS)0)
142#define VRDE_USB_STATUS_ACCESS_DENIED ((VRDEUSBSTATUS)1)
143#define VRDE_USB_STATUS_DEVICE_REMOVED ((VRDEUSBSTATUS)2)
144
145/*
146 * Data structures to use with VRDEUSBRequest.
147 * The *RET* structures always represent the layout of VRDE data.
148 * The *PARM* structures normally the same as VRDE layout.
149 * However the VRDE_USB_REQ_QUEUE_URB_PARM has a pointer to
150 * URB data in place where actual data will be in VRDE layout.
151 *
152 * Since replies (*RET*) are asynchronous, the 'success'
153 * replies are not required for operations which return
154 * only the status code (VRDEUSBREQRETHDR only):
155 * VRDE_USB_REQ_OPEN
156 * VRDE_USB_REQ_RESET
157 * VRDE_USB_REQ_SET_CONFIG
158 * VRDE_USB_REQ_CLAIM_INTERFACE
159 * VRDE_USB_REQ_RELEASE_INTERFACE
160 * VRDE_USB_REQ_INTERFACE_SETTING
161 * VRDE_USB_REQ_CLEAR_HALTED_EP
162 *
163 */
164
165/* VRDE layout has no alignments. */
166#pragma pack(1)
167/* Common header for all VRDE USB packets. After the reply hdr follows *PARM* or *RET* data. */
168typedef struct _VRDEUSBPKTHDR
169{
170 /* Total length of the reply NOT including the 'length' field. */
171 uint32_t length;
172 /* The operation code for which the reply was sent by the client. */
173 uint8_t code;
174} VRDEUSBPKTHDR;
175
176/* Common header for all return structures. */
177typedef struct _VRDEUSBREQRETHDR
178{
179 /* Device status. */
180 VRDEUSBSTATUS status;
181 /* Device id. */
182 VRDEUSBDEVID id;
183} VRDEUSBREQRETHDR;
184
185
186/* VRDE_USB_REQ_OPEN
187 */
188typedef struct _VRDE_USB_REQ_OPEN_PARM
189{
190 uint8_t code;
191 VRDEUSBDEVID id;
192} VRDE_USB_REQ_OPEN_PARM;
193
194typedef struct _VRDE_USB_REQ_OPEN_RET
195{
196 VRDEUSBREQRETHDR hdr;
197} VRDE_USB_REQ_OPEN_RET;
198
199
200/* VRDE_USB_REQ_CLOSE
201 */
202typedef struct _VRDE_USB_REQ_CLOSE_PARM
203{
204 uint8_t code;
205 VRDEUSBDEVID id;
206} VRDE_USB_REQ_CLOSE_PARM;
207
208/* The close request has no returned data. */
209
210
211/* VRDE_USB_REQ_RESET
212 */
213typedef struct _VRDE_USB_REQ_RESET_PARM
214{
215 uint8_t code;
216 VRDEUSBDEVID id;
217} VRDE_USB_REQ_RESET_PARM;
218
219typedef struct _VRDE_USB_REQ_RESET_RET
220{
221 VRDEUSBREQRETHDR hdr;
222} VRDE_USB_REQ_RESET_RET;
223
224
225/* VRDE_USB_REQ_SET_CONFIG
226 */
227typedef struct _VRDE_USB_REQ_SET_CONFIG_PARM
228{
229 uint8_t code;
230 VRDEUSBDEVID id;
231 uint8_t configuration;
232} VRDE_USB_REQ_SET_CONFIG_PARM;
233
234typedef struct _VRDE_USB_REQ_SET_CONFIG_RET
235{
236 VRDEUSBREQRETHDR hdr;
237} VRDE_USB_REQ_SET_CONFIG_RET;
238
239
240/* VRDE_USB_REQ_CLAIM_INTERFACE
241 */
242typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_PARM
243{
244 uint8_t code;
245 VRDEUSBDEVID id;
246 uint8_t iface;
247} VRDE_USB_REQ_CLAIM_INTERFACE_PARM;
248
249typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_RET
250{
251 VRDEUSBREQRETHDR hdr;
252} VRDE_USB_REQ_CLAIM_INTERFACE_RET;
253
254
255/* VRDE_USB_REQ_RELEASE_INTERFACE
256 */
257typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_PARM
258{
259 uint8_t code;
260 VRDEUSBDEVID id;
261 uint8_t iface;
262} VRDE_USB_REQ_RELEASE_INTERFACE_PARM;
263
264typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_RET
265{
266 VRDEUSBREQRETHDR hdr;
267} VRDE_USB_REQ_RELEASE_INTERFACE_RET;
268
269
270/* VRDE_USB_REQ_INTERFACE_SETTING
271 */
272typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_PARM
273{
274 uint8_t code;
275 VRDEUSBDEVID id;
276 uint8_t iface;
277 uint8_t setting;
278} VRDE_USB_REQ_INTERFACE_SETTING_PARM;
279
280typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_RET
281{
282 VRDEUSBREQRETHDR hdr;
283} VRDE_USB_REQ_INTERFACE_SETTING_RET;
284
285
286/* VRDE_USB_REQ_QUEUE_URB
287 */
288
289#define VRDE_USB_TRANSFER_TYPE_CTRL (0)
290#define VRDE_USB_TRANSFER_TYPE_ISOC (1)
291#define VRDE_USB_TRANSFER_TYPE_BULK (2)
292#define VRDE_USB_TRANSFER_TYPE_INTR (3)
293#define VRDE_USB_TRANSFER_TYPE_MSG (4)
294
295#define VRDE_USB_DIRECTION_SETUP (0)
296#define VRDE_USB_DIRECTION_IN (1)
297#define VRDE_USB_DIRECTION_OUT (2)
298
299typedef struct _VRDE_USB_REQ_QUEUE_URB_PARM
300{
301 uint8_t code;
302 VRDEUSBDEVID id;
303 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
304 uint8_t type;
305 uint8_t ep;
306 uint8_t direction;
307 uint32_t urblen; /* Length of the URB. */
308 uint32_t datalen; /* Length of the data. */
309 void *data; /* In RDP layout the data follow. */
310} VRDE_USB_REQ_QUEUE_URB_PARM;
311
312/* The queue URB has no explicit return. The reap URB reply will be
313 * eventually the indirect result.
314 */
315
316
317/* VRDE_USB_REQ_REAP_URB
318 * Notificationg from server to client that server expects an URB
319 * from any device.
320 * Only sent if negotiated URB return method is polling.
321 * Normally, the client will send URBs back as soon as they are ready.
322 */
323typedef struct _VRDE_USB_REQ_REAP_URB_PARM
324{
325 uint8_t code;
326} VRDE_USB_REQ_REAP_URB_PARM;
327
328
329#define VRDE_USB_XFER_OK (0)
330#define VRDE_USB_XFER_STALL (1)
331#define VRDE_USB_XFER_DNR (2)
332#define VRDE_USB_XFER_CRC (3)
333/* VRDE_USB_VERSION_2: New error codes. OHCI Completion Codes. */
334#define VRDE_USB_XFER_BS (4) /* BitStuffing */
335#define VRDE_USB_XFER_DTM (5) /* DataToggleMismatch */
336#define VRDE_USB_XFER_PCF (6) /* PIDCheckFailure */
337#define VRDE_USB_XFER_UPID (7) /* UnexpectedPID */
338#define VRDE_USB_XFER_DO (8) /* DataOverrun */
339#define VRDE_USB_XFER_DU (9) /* DataUnderrun */
340#define VRDE_USB_XFER_BO (10) /* BufferOverrun */
341#define VRDE_USB_XFER_BU (11) /* BufferUnderrun */
342#define VRDE_USB_XFER_ERR (12) /* VBox protocol error. */
343
344#define VRDE_USB_REAP_FLAG_CONTINUED (0x0)
345#define VRDE_USB_REAP_FLAG_LAST (0x1)
346/* VRDE_USB_VERSION_3: Fragmented URBs. */
347#define VRDE_USB_REAP_FLAG_FRAGMENT (0x2)
348
349#define VRDE_USB_REAP_VALID_FLAGS (VRDE_USB_REAP_FLAG_LAST)
350/* VRDE_USB_VERSION_3: Fragmented URBs. */
351#define VRDE_USB_REAP_VALID_FLAGS_3 (VRDE_USB_REAP_FLAG_LAST | VRDE_USB_REAP_FLAG_FRAGMENT)
352
353typedef struct _VRDEUSBREQREAPURBBODY
354{
355 VRDEUSBDEVID id; /* From which device the URB arrives. */
356 uint8_t flags; /* VRDE_USB_REAP_FLAG_* */
357 uint8_t error; /* VRDE_USB_XFER_* */
358 uint32_t handle; /* Handle of returned URB. Not 0. */
359 uint32_t len; /* Length of data actually transferred. */
360 /* 'len' bytes of data follow if direction of this URB was VRDE_USB_DIRECTION_IN. */
361} VRDEUSBREQREAPURBBODY;
362
363typedef struct _VRDE_USB_REQ_REAP_URB_RET
364{
365 /* The REAP URB has no header, only completed URBs are returned. */
366 VRDEUSBREQREAPURBBODY body;
367 /* Another body may follow, depending on flags. */
368} VRDE_USB_REQ_REAP_URB_RET;
369
370
371/* VRDE_USB_REQ_CLEAR_HALTED_EP
372 */
373typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_PARM
374{
375 uint8_t code;
376 VRDEUSBDEVID id;
377 uint8_t ep;
378} VRDE_USB_REQ_CLEAR_HALTED_EP_PARM;
379
380typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_RET
381{
382 VRDEUSBREQRETHDR hdr;
383} VRDE_USB_REQ_CLEAR_HALTED_EP_RET;
384
385
386/* VRDE_USB_REQ_CANCEL_URB
387 */
388typedef struct _VRDE_USB_REQ_CANCEL_URB_PARM
389{
390 uint8_t code;
391 VRDEUSBDEVID id;
392 uint32_t handle;
393} VRDE_USB_REQ_CANCEL_URB_PARM;
394
395/* The cancel URB request has no return. */
396
397
398/* VRDE_USB_REQ_DEVICE_LIST
399 *
400 * Server polls USB devices on client by sending this request
401 * periodically. Client sends back a list of all devices
402 * connected to it. Each device is assigned with an identifier,
403 * that is used to distinguish the particular device.
404 */
405typedef struct _VRDE_USB_REQ_DEVICE_LIST_PARM
406{
407 uint8_t code;
408} VRDE_USB_REQ_DEVICE_LIST_PARM;
409
410/* Data is a list of the following variable length structures. */
411typedef struct _VRDEUSBDEVICEDESC
412{
413 /* Offset of the next structure. 0 if last. */
414 uint16_t oNext;
415
416 /* Identifier of the device assigned by client. */
417 VRDEUSBDEVID id;
418
419 /** USB version number. */
420 uint16_t bcdUSB;
421 /** Device class. */
422 uint8_t bDeviceClass;
423 /** Device subclass. */
424 uint8_t bDeviceSubClass;
425 /** Device protocol */
426 uint8_t bDeviceProtocol;
427 /** Vendor ID. */
428 uint16_t idVendor;
429 /** Product ID. */
430 uint16_t idProduct;
431 /** Revision, integer part. */
432 uint16_t bcdRev;
433 /** Offset of the UTF8 manufacturer string relative to the structure start. */
434 uint16_t oManufacturer;
435 /** Offset of the UTF8 product string relative to the structure start. */
436 uint16_t oProduct;
437 /** Offset of the UTF8 serial number string relative to the structure start. */
438 uint16_t oSerialNumber;
439 /** Physical USB port the device is connected to. */
440 uint16_t idPort;
441
442} VRDEUSBDEVICEDESC;
443
444#define VRDE_USBDEVICESPEED_UNKNOWN 0 /* Unknown. */
445#define VRDE_USBDEVICESPEED_LOW 1 /* Low speed (1.5 Mbit/s). */
446#define VRDE_USBDEVICESPEED_FULL 2 /* Full speed (12 Mbit/s). */
447#define VRDE_USBDEVICESPEED_HIGH 3 /* High speed (480 Mbit/s). */
448#define VRDE_USBDEVICESPEED_VARIABLE 4 /* Variable speed - USB 2.5 / wireless. */
449#define VRDE_USBDEVICESPEED_SUPERSPEED 5 /* Super Speed - USB 3.0 */
450
451typedef struct _VRDEUSBDEVICEDESCEXT
452{
453 VRDEUSBDEVICEDESC desc;
454
455 /* Extended info.
456 */
457
458 /** The USB device speed: VRDE_USBDEVICESPEED_*. */
459 uint16_t u16DeviceSpeed;
460} VRDEUSBDEVICEDESCEXT;
461
462typedef struct _VRDE_USB_REQ_DEVICE_LIST_RET
463{
464 VRDEUSBDEVICEDESC body;
465 /* Other devices may follow.
466 * The list ends with (uint16_t)0,
467 * which means that an empty list consists of 2 zero bytes.
468 */
469} VRDE_USB_REQ_DEVICE_LIST_RET;
470
471typedef struct _VRDE_USB_REQ_DEVICE_LIST_EXT_RET
472{
473 VRDEUSBDEVICEDESCEXT body;
474 /* Other devices may follow.
475 * The list ends with (uint16_t)0,
476 * which means that an empty list consists of 2 zero bytes.
477 */
478} VRDE_USB_REQ_DEVICE_LIST_EXT_RET;
479
480/* The server requests the version of the port the device is attached to.
481 * The client must use VRDEUSBDEVICEDESCEXT structure.
482 */
483#define VRDE_USB_SERVER_CAPS_PORT_VERSION 0x0001
484
485typedef struct _VRDEUSBREQNEGOTIATEPARM
486{
487 uint8_t code;
488
489 /* Remote USB Protocol version. */
490 /* VRDE_USB_VERSION_3: the 32 bit field is splitted to 16 bit version and 16 bit flags.
491 * Version 1 and 2 servers therefore have 'flags' == 0.
492 * Version 3+ servers can send some capabilities in this field, this way it is possible to add
493 * a new capability without increasing the protocol version.
494 */
495 uint16_t version;
496 uint16_t flags; /* See VRDE_USB_SERVER_CAPS_* */
497
498} VRDEUSBREQNEGOTIATEPARM;
499
500/* VRDEUSBREQNEGOTIATERET flags. */
501#define VRDE_USB_CAPS_FLAG_ASYNC (0x0)
502#define VRDE_USB_CAPS_FLAG_POLL (0x1)
503/* VRDE_USB_VERSION_2: New flag. */
504#define VRDE_USB_CAPS2_FLAG_VERSION (0x2) /* The client is negotiating the protocol version. */
505/* VRDE_USB_VERSION_3: New flag. */
506#define VRDE_USB_CAPS3_FLAG_EXT (0x4) /* The client is negotiating the extended flags.
507 * If this flag is set, then the VRDE_USB_CAPS2_FLAG_VERSION
508 * must also be set.
509 */
510
511
512#define VRDE_USB_CAPS_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL)
513/* VRDE_USB_VERSION_2: A set of valid flags. */
514#define VRDE_USB_CAPS2_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL | VRDE_USB_CAPS2_FLAG_VERSION)
515/* VRDE_USB_VERSION_3: A set of valid flags. */
516#define VRDE_USB_CAPS3_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL | VRDE_USB_CAPS2_FLAG_VERSION | VRDE_USB_CAPS3_FLAG_EXT)
517
518typedef struct _VRDEUSBREQNEGOTIATERET
519{
520 uint8_t flags;
521} VRDEUSBREQNEGOTIATERET;
522
523typedef struct _VRDEUSBREQNEGOTIATERET_2
524{
525 uint8_t flags;
526 uint32_t u32Version; /* This field presents only if the VRDE_USB_CAPS2_FLAG_VERSION flag is set. */
527} VRDEUSBREQNEGOTIATERET_2;
528
529/* The server requests the version of the port the device is attached to.
530 * The client must use VRDEUSBDEVICEDESCEXT structure.
531 */
532#define VRDE_USB_CLIENT_CAPS_PORT_VERSION 0x00000001
533
534typedef struct _VRDEUSBREQNEGOTIATERET_3
535{
536 uint8_t flags;
537 uint32_t u32Version; /* This field presents only if the VRDE_USB_CAPS2_FLAG_VERSION flag is set. */
538 uint32_t u32Flags; /* This field presents only if both VRDE_USB_CAPS2_FLAG_VERSION and
539 * VRDE_USB_CAPS2_FLAG_EXT flag are set.
540 * See VRDE_USB_CLIENT_CAPS_*
541 */
542} VRDEUSBREQNEGOTIATERET_3;
543#pragma pack()
544
545#define VRDE_CLIPBOARD_FORMAT_NULL (0x0)
546#define VRDE_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
547#define VRDE_CLIPBOARD_FORMAT_BITMAP (0x2)
548#define VRDE_CLIPBOARD_FORMAT_HTML (0x4)
549
550#define VRDE_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
551#define VRDE_CLIPBOARD_FUNCTION_DATA_READ (1)
552#define VRDE_CLIPBOARD_FUNCTION_DATA_WRITE (2)
553
554
555/** Indexes of information values. */
556
557/** Whether a client is connected at the moment.
558 * uint32_t
559 */
560#define VRDE_QI_ACTIVE (0)
561
562/** How many times a client connected up to current moment.
563 * uint32_t
564 */
565#define VRDE_QI_NUMBER_OF_CLIENTS (1)
566
567/** When last connection was established.
568 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
569 */
570#define VRDE_QI_BEGIN_TIME (2)
571
572/** When last connection was terminated or current time if connection still active.
573 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
574 */
575#define VRDE_QI_END_TIME (3)
576
577/** How many bytes were sent in last (current) connection.
578 * uint64_t
579 */
580#define VRDE_QI_BYTES_SENT (4)
581
582/** How many bytes were sent in all connections.
583 * uint64_t
584 */
585#define VRDE_QI_BYTES_SENT_TOTAL (5)
586
587/** How many bytes were received in last (current) connection.
588 * uint64_t
589 */
590#define VRDE_QI_BYTES_RECEIVED (6)
591
592/** How many bytes were received in all connections.
593 * uint64_t
594 */
595#define VRDE_QI_BYTES_RECEIVED_TOTAL (7)
596
597/** Login user name supplied by the client.
598 * UTF8 nul terminated string.
599 */
600#define VRDE_QI_USER (8)
601
602/** Login domain supplied by the client.
603 * UTF8 nul terminated string.
604 */
605#define VRDE_QI_DOMAIN (9)
606
607/** The client name supplied by the client.
608 * UTF8 nul terminated string.
609 */
610#define VRDE_QI_CLIENT_NAME (10)
611
612/** IP address of the client.
613 * UTF8 nul terminated string.
614 */
615#define VRDE_QI_CLIENT_IP (11)
616
617/** The client software version number.
618 * uint32_t.
619 */
620#define VRDE_QI_CLIENT_VERSION (12)
621
622/** Public key exchange method used when connection was established.
623 * Values: 0 - RDP4 public key exchange scheme.
624 * 1 - X509 sertificates were sent to client.
625 * uint32_t.
626 */
627#define VRDE_QI_ENCRYPTION_STYLE (13)
628
629/** TCP port where the server listens.
630 * Values: 0 - VRDE server failed to start.
631 * -1 - .
632 * int32_t.
633 */
634#define VRDE_QI_PORT (14)
635
636
637/** Hints what has been intercepted by the application. */
638#define VRDE_CLIENT_INTERCEPT_AUDIO RT_BIT(0)
639#define VRDE_CLIENT_INTERCEPT_USB RT_BIT(1)
640#define VRDE_CLIENT_INTERCEPT_CLIPBOARD RT_BIT(2)
641#define VRDE_CLIENT_INTERCEPT_AUDIO_INPUT RT_BIT(3)
642
643
644/** The version of the VRDE server interface. */
645#define VRDE_INTERFACE_VERSION_1 (1)
646#define VRDE_INTERFACE_VERSION_2 (2)
647#define VRDE_INTERFACE_VERSION_3 (3)
648#define VRDE_INTERFACE_VERSION_4 (4)
649
650/** The header that does not change when the interface changes. */
651typedef struct _VRDEINTERFACEHDR
652{
653 /** The version of the interface. */
654 uint64_t u64Version;
655
656 /** The size of the structure. */
657 uint64_t u64Size;
658
659} VRDEINTERFACEHDR;
660
661/** The VRDE server entry points. Interface version 1. */
662typedef struct _VRDEENTRYPOINTS_1
663{
664 /** The header. */
665 VRDEINTERFACEHDR header;
666
667 /** Destroy the server instance.
668 *
669 * @param hServer The server instance handle.
670 *
671 * @return IPRT status code.
672 */
673 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
674
675 /** The server should start to accept clients connections.
676 *
677 * @param hServer The server instance handle.
678 * @param fEnable Whether to enable or disable client connections.
679 * When is false, all existing clients are disconnected.
680 *
681 * @return IPRT status code.
682 */
683 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
684 bool fEnable));
685
686 /** The server should disconnect the client.
687 *
688 * @param hServer The server instance handle.
689 * @param u32ClientId The client identifier.
690 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
691 * client before disconnecting.
692 *
693 * @return IPRT status code.
694 */
695 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
696 uint32_t u32ClientId,
697 bool fReconnect));
698
699 /**
700 * Inform the server that the display was resized.
701 * The server will query information about display
702 * from the application via callbacks.
703 *
704 * @param hServer Handle of VRDE server instance.
705 */
706 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
707
708 /**
709 * Send a update.
710 *
711 * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called.
712 * If the have to access the bitmap later or from another thread, then
713 * it must used an intermediate buffer and copy the framebuffer data to the
714 * intermediate buffer in VRDEUpdate.
715 *
716 * @param hServer Handle of VRDE server instance.
717 * @param uScreenId The screen index.
718 * @param pvUpdate Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data.
719 * @param cbUpdate Size of the update data.
720 */
721 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
722 unsigned uScreenId,
723 void *pvUpdate,
724 uint32_t cbUpdate));
725
726 /**
727 * Set the mouse pointer shape.
728 *
729 * @param hServer Handle of VRDE server instance.
730 * @param pPointer The pointer shape information.
731 */
732 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
733 const VRDECOLORPOINTER *pPointer));
734
735 /**
736 * Hide the mouse pointer.
737 *
738 * @param hServer Handle of VRDE server instance.
739 */
740 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
741
742 /**
743 * Queues the samples to be sent to clients.
744 *
745 * @param hServer Handle of VRDE server instance.
746 * @param pvSamples Address of samples to be sent.
747 * @param cSamples Number of samples.
748 * @param format Encoded audio format for these samples.
749 *
750 * @note Initialized to NULL when the application audio callbacks are NULL.
751 */
752 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
753 const void *pvSamples,
754 uint32_t cSamples,
755 VRDEAUDIOFORMAT format));
756
757 /**
758 * Sets the sound volume on clients.
759 *
760 * @param hServer Handle of VRDE server instance.
761 * @param left 0..0xFFFF volume level for left channel.
762 * @param right 0..0xFFFF volume level for right channel.
763 *
764 * @note Initialized to NULL when the application audio callbacks are NULL.
765 */
766 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
767 uint16_t u16Left,
768 uint16_t u16Right));
769
770 /**
771 * Sends a USB request.
772 *
773 * @param hServer Handle of VRDE server instance.
774 * @param u32ClientId An identifier that allows the server to find the corresponding client.
775 * The identifier is always passed by the server as a parameter
776 * of the FNVRDEUSBCALLBACK. Note that the value is the same as
777 * in the VRDESERVERCALLBACK functions.
778 * @param pvParm Function specific parameters buffer.
779 * @param cbParm Size of the buffer.
780 *
781 * @note Initialized to NULL when the application USB callbacks are NULL.
782 */
783 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
784 uint32_t u32ClientId,
785 void *pvParm,
786 uint32_t cbParm));
787
788 /**
789 * Called by the application when (VRDE_CLIPBOARD_FUNCTION_*):
790 * - (0) guest announces available clipboard formats;
791 * - (1) guest requests clipboard data;
792 * - (2) guest responds to the client's request for clipboard data.
793 *
794 * @param hServer The VRDE server handle.
795 * @param u32Function The cause of the call.
796 * @param u32Format Bitmask of announced formats or the format of data.
797 * @param pvData Points to: (1) buffer to be filled with clients data;
798 * (2) data from the host.
799 * @param cbData Size of 'pvData' buffer in bytes.
800 * @param pcbActualRead Size of the copied data in bytes.
801 *
802 * @note Initialized to NULL when the application clipboard callbacks are NULL.
803 */
804 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
805 uint32_t u32Function,
806 uint32_t u32Format,
807 void *pvData,
808 uint32_t cbData,
809 uint32_t *pcbActualRead));
810
811 /**
812 * Query various information from the VRDE server.
813 *
814 * @param hServer The VRDE server handle.
815 * @param index VRDE_QI_* identifier of information to be returned.
816 * @param pvBuffer Address of memory buffer to which the information must be written.
817 * @param cbBuffer Size of the memory buffer in bytes.
818 * @param pcbOut Size in bytes of returned information value.
819 *
820 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
821 * A value greater than cbBuffer means that information is too big to fit in the
822 * buffer, in that case no information was placed to the buffer.
823 */
824 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
825 uint32_t index,
826 void *pvBuffer,
827 uint32_t cbBuffer,
828 uint32_t *pcbOut));
829} VRDEENTRYPOINTS_1;
830
831/** The VRDE server entry points. Interface version 2.
832 * A new entry point VRDERedirect has been added relative to version 1.
833 */
834typedef struct _VRDEENTRYPOINTS_2
835{
836 /** The header. */
837 VRDEINTERFACEHDR header;
838
839 /** Destroy the server instance.
840 *
841 * @param hServer The server instance handle.
842 *
843 * @return IPRT status code.
844 */
845 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
846
847 /** The server should start to accept clients connections.
848 *
849 * @param hServer The server instance handle.
850 * @param fEnable Whether to enable or disable client connections.
851 * When is false, all existing clients are disconnected.
852 *
853 * @return IPRT status code.
854 */
855 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
856 bool fEnable));
857
858 /** The server should disconnect the client.
859 *
860 * @param hServer The server instance handle.
861 * @param u32ClientId The client identifier.
862 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
863 * client before disconnecting.
864 *
865 * @return IPRT status code.
866 */
867 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
868 uint32_t u32ClientId,
869 bool fReconnect));
870
871 /**
872 * Inform the server that the display was resized.
873 * The server will query information about display
874 * from the application via callbacks.
875 *
876 * @param hServer Handle of VRDE server instance.
877 */
878 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
879
880 /**
881 * Send a update.
882 *
883 * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called.
884 * If the have to access the bitmap later or from another thread, then
885 * it must used an intermediate buffer and copy the framebuffer data to the
886 * intermediate buffer in VRDEUpdate.
887 *
888 * @param hServer Handle of VRDE server instance.
889 * @param uScreenId The screen index.
890 * @param pvUpdate Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data.
891 * @param cbUpdate Size of the update data.
892 */
893 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
894 unsigned uScreenId,
895 void *pvUpdate,
896 uint32_t cbUpdate));
897
898 /**
899 * Set the mouse pointer shape.
900 *
901 * @param hServer Handle of VRDE server instance.
902 * @param pPointer The pointer shape information.
903 */
904 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
905 const VRDECOLORPOINTER *pPointer));
906
907 /**
908 * Hide the mouse pointer.
909 *
910 * @param hServer Handle of VRDE server instance.
911 */
912 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
913
914 /**
915 * Queues the samples to be sent to clients.
916 *
917 * @param hServer Handle of VRDE server instance.
918 * @param pvSamples Address of samples to be sent.
919 * @param cSamples Number of samples.
920 * @param format Encoded audio format for these samples.
921 *
922 * @note Initialized to NULL when the application audio callbacks are NULL.
923 */
924 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
925 const void *pvSamples,
926 uint32_t cSamples,
927 VRDEAUDIOFORMAT format));
928
929 /**
930 * Sets the sound volume on clients.
931 *
932 * @param hServer Handle of VRDE server instance.
933 * @param left 0..0xFFFF volume level for left channel.
934 * @param right 0..0xFFFF volume level for right channel.
935 *
936 * @note Initialized to NULL when the application audio callbacks are NULL.
937 */
938 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
939 uint16_t u16Left,
940 uint16_t u16Right));
941
942 /**
943 * Sends a USB request.
944 *
945 * @param hServer Handle of VRDE server instance.
946 * @param u32ClientId An identifier that allows the server to find the corresponding client.
947 * The identifier is always passed by the server as a parameter
948 * of the FNVRDEUSBCALLBACK. Note that the value is the same as
949 * in the VRDESERVERCALLBACK functions.
950 * @param pvParm Function specific parameters buffer.
951 * @param cbParm Size of the buffer.
952 *
953 * @note Initialized to NULL when the application USB callbacks are NULL.
954 */
955 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
956 uint32_t u32ClientId,
957 void *pvParm,
958 uint32_t cbParm));
959
960 /**
961 * Called by the application when (VRDE_CLIPBOARD_FUNCTION_*):
962 * - (0) guest announces available clipboard formats;
963 * - (1) guest requests clipboard data;
964 * - (2) guest responds to the client's request for clipboard data.
965 *
966 * @param hServer The VRDE server handle.
967 * @param u32Function The cause of the call.
968 * @param u32Format Bitmask of announced formats or the format of data.
969 * @param pvData Points to: (1) buffer to be filled with clients data;
970 * (2) data from the host.
971 * @param cbData Size of 'pvData' buffer in bytes.
972 * @param pcbActualRead Size of the copied data in bytes.
973 *
974 * @note Initialized to NULL when the application clipboard callbacks are NULL.
975 */
976 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
977 uint32_t u32Function,
978 uint32_t u32Format,
979 void *pvData,
980 uint32_t cbData,
981 uint32_t *pcbActualRead));
982
983 /**
984 * Query various information from the VRDE server.
985 *
986 * @param hServer The VRDE server handle.
987 * @param index VRDE_QI_* identifier of information to be returned.
988 * @param pvBuffer Address of memory buffer to which the information must be written.
989 * @param cbBuffer Size of the memory buffer in bytes.
990 * @param pcbOut Size in bytes of returned information value.
991 *
992 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
993 * A value greater than cbBuffer means that information is too big to fit in the
994 * buffer, in that case no information was placed to the buffer.
995 */
996 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
997 uint32_t index,
998 void *pvBuffer,
999 uint32_t cbBuffer,
1000 uint32_t *pcbOut));
1001
1002 /**
1003 * The server should redirect the client to the specified server.
1004 *
1005 * @param hServer The server instance handle.
1006 * @param u32ClientId The client identifier.
1007 * @param pszServer The server to redirect the client to.
1008 * @param pszUser The username to use for the redirection.
1009 * Can be NULL.
1010 * @param pszDomain The domain. Can be NULL.
1011 * @param pszPassword The password. Can be NULL.
1012 * @param u32SessionId The ID of the session to redirect to.
1013 * @param pszCookie The routing token used by a load balancer to
1014 * route the redirection. Can be NULL.
1015 */
1016 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer,
1017 uint32_t u32ClientId,
1018 const char *pszServer,
1019 const char *pszUser,
1020 const char *pszDomain,
1021 const char *pszPassword,
1022 uint32_t u32SessionId,
1023 const char *pszCookie));
1024} VRDEENTRYPOINTS_2;
1025
1026/** The VRDE server entry points. Interface version 3.
1027 * New entry points VRDEAudioInOpen and VRDEAudioInClose has been added relative to version 2.
1028 */
1029typedef struct _VRDEENTRYPOINTS_3
1030{
1031 /* The header. */
1032 VRDEINTERFACEHDR header;
1033
1034 /*
1035 * Same as version 2. See comment in VRDEENTRYPOINTS_2.
1036 */
1037
1038 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
1039
1040 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
1041 bool fEnable));
1042
1043 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
1044 uint32_t u32ClientId,
1045 bool fReconnect));
1046
1047 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
1048
1049 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
1050 unsigned uScreenId,
1051 void *pvUpdate,
1052 uint32_t cbUpdate));
1053
1054 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
1055 const VRDECOLORPOINTER *pPointer));
1056
1057 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
1058
1059 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
1060 const void *pvSamples,
1061 uint32_t cSamples,
1062 VRDEAUDIOFORMAT format));
1063
1064 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
1065 uint16_t u16Left,
1066 uint16_t u16Right));
1067
1068 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
1069 uint32_t u32ClientId,
1070 void *pvParm,
1071 uint32_t cbParm));
1072
1073 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
1074 uint32_t u32Function,
1075 uint32_t u32Format,
1076 void *pvData,
1077 uint32_t cbData,
1078 uint32_t *pcbActualRead));
1079
1080 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
1081 uint32_t index,
1082 void *pvBuffer,
1083 uint32_t cbBuffer,
1084 uint32_t *pcbOut));
1085
1086 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer,
1087 uint32_t u32ClientId,
1088 const char *pszServer,
1089 const char *pszUser,
1090 const char *pszDomain,
1091 const char *pszPassword,
1092 uint32_t u32SessionId,
1093 const char *pszCookie));
1094
1095 /*
1096 * New for version 3.
1097 */
1098
1099 /**
1100 * Audio input open request.
1101 *
1102 * @param hServer Handle of VRDE server instance.
1103 * @param pvCtx To be used in VRDECallbackAudioIn.
1104 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1105 * @param audioFormat Preferred format of audio data.
1106 * @param u32SamplesPerBlock Preferred number of samples in one block of audio input data.
1107 *
1108 * @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL.
1109 */
1110 DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer,
1111 void *pvCtx,
1112 uint32_t u32ClientId,
1113 VRDEAUDIOFORMAT audioFormat,
1114 uint32_t u32SamplesPerBlock));
1115
1116 /**
1117 * Audio input close request.
1118 *
1119 * @param hServer Handle of VRDE server instance.
1120 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1121 *
1122 * @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL.
1123 */
1124 DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer,
1125 uint32_t u32ClientId));
1126} VRDEENTRYPOINTS_3;
1127
1128
1129/* Indexes for VRDECallbackProperty.
1130 * *_QP_* queries a property.
1131 * *_SP_* sets a property.
1132 */
1133#define VRDE_QP_NETWORK_PORT (1) /* Obsolete. Use VRDE_QP_NETWORK_PORT_RANGE instead. */
1134#define VRDE_QP_NETWORK_ADDRESS (2) /* UTF8 string. Host network interface IP address to bind to. */
1135#define VRDE_QP_NUMBER_MONITORS (3) /* 32 bit. Number of monitors in the VM. */
1136#define VRDE_QP_NETWORK_PORT_RANGE (4) /* UTF8 string. List of ports. The server must bind to one of
1137 * free ports from the list. Example: "3000,3010-3012,4000",
1138 * which tells the server to bind to either of ports:
1139 * 3000, 3010, 3011, 3012, 4000.
1140 */
1141#define VRDE_QP_VIDEO_CHANNEL (5)
1142#define VRDE_QP_VIDEO_CHANNEL_QUALITY (6)
1143#define VRDE_QP_VIDEO_CHANNEL_SUNFLSH (7)
1144#define VRDE_QP_FEATURE (8) /* VRDEFEATURE structure. Generic interface to query named VRDE properties. */
1145#define VRDE_QP_UNIX_SOCKET_PATH (9) /* Path to a UNIX Socket for incoming connections */
1146
1147#define VRDE_SP_BASE 0x1000
1148#define VRDE_SP_NETWORK_BIND_PORT (VRDE_SP_BASE + 1) /* 32 bit. The port number actually used by the server.
1149 * If VRDECreateServer fails, it should set the port to 0.
1150 * If VRDECreateServer succeeds, then the port must be set
1151 * in VRDEEnableConnections to the actually used value.
1152 * VRDEDestroy must set the port to 0xFFFFFFFF.
1153 */
1154#define VRDE_SP_CLIENT_STATUS (VRDE_SP_BASE + 2) /* UTF8 string. The change of the generic client status:
1155 * "ATTACH" - the client is attached;
1156 * "DETACH" - the client is detached;
1157 * "NAME=..." - the client name changes.
1158 * Can be used for other notifications.
1159 */
1160
1161#pragma pack(1)
1162/* VRDE_QP_FEATURE data. */
1163typedef struct _VRDEFEATURE
1164{
1165 uint32_t u32ClientId;
1166 char achInfo[1]; /* UTF8 property input name and output value. */
1167} VRDEFEATURE;
1168
1169/* VRDE_SP_CLIENT_STATUS data. */
1170typedef struct VRDECLIENTSTATUS
1171{
1172 uint32_t u32ClientId;
1173 uint32_t cbStatus;
1174 char achStatus[1]; /* UTF8 status string. */
1175} VRDECLIENTSTATUS;
1176
1177/* A framebuffer description. */
1178typedef struct _VRDEFRAMEBUFFERINFO
1179{
1180 const uint8_t *pu8Bits;
1181 int xOrigin;
1182 int yOrigin;
1183 unsigned cWidth;
1184 unsigned cHeight;
1185 unsigned cBitsPerPixel;
1186 unsigned cbLine;
1187} VRDEFRAMEBUFFERINFO;
1188
1189#define VRDE_INPUT_SCANCODE 0
1190#define VRDE_INPUT_POINT 1
1191#define VRDE_INPUT_CAD 2
1192#define VRDE_INPUT_RESET 3
1193#define VRDE_INPUT_SYNCH 4
1194
1195typedef struct _VRDEINPUTSCANCODE
1196{
1197 unsigned uScancode;
1198} VRDEINPUTSCANCODE;
1199
1200#define VRDE_INPUT_POINT_BUTTON1 0x01
1201#define VRDE_INPUT_POINT_BUTTON2 0x02
1202#define VRDE_INPUT_POINT_BUTTON3 0x04
1203#define VRDE_INPUT_POINT_WHEEL_UP 0x08
1204#define VRDE_INPUT_POINT_WHEEL_DOWN 0x10
1205
1206typedef struct _VRDEINPUTPOINT
1207{
1208 int x;
1209 int y;
1210 unsigned uButtons;
1211} VRDEINPUTPOINT;
1212
1213#define VRDE_INPUT_SYNCH_SCROLL 0x01
1214#define VRDE_INPUT_SYNCH_NUMLOCK 0x02
1215#define VRDE_INPUT_SYNCH_CAPITAL 0x04
1216
1217typedef struct _VRDEINPUTSYNCH
1218{
1219 unsigned uLockStatus;
1220} VRDEINPUTSYNCH;
1221#pragma pack()
1222
1223/** The VRDE server callbacks. Interface version 1. */
1224typedef struct _VRDECALLBACKS_1
1225{
1226 /** The header. */
1227 VRDEINTERFACEHDR header;
1228
1229 /**
1230 * Query or set various information, on how the VRDE server operates, from or to the application.
1231 * Queries for properties will always return success, and if the key is not known or has no
1232 * value associated with it an empty string is returned.
1233 *
1234 *
1235 * @param pvCallback The callback specific pointer.
1236 * @param index VRDE_[Q|S]P_* identifier of information to be returned or set.
1237 * @param pvBuffer Address of memory buffer to which the information must be written or read.
1238 * @param cbBuffer Size of the memory buffer in bytes.
1239 * @param pcbOut Size in bytes of returned information value.
1240 *
1241 * @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value.
1242 */
1243 DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1244 uint32_t index,
1245 void *pvBuffer,
1246 uint32_t cbBuffer,
1247 uint32_t *pcbOut));
1248
1249 /* A client is logging in, the application must decide whether
1250 * to let to connect the client. The server will drop the connection,
1251 * when an error code is returned by the callback.
1252 *
1253 * @param pvCallback The callback specific pointer.
1254 * @param u32ClientId An unique client identifier generated by the server.
1255 * @param pszUser The username.
1256 * @param pszPassword The password.
1257 * @param pszDomain The domain.
1258 *
1259 * @return IPRT status code.
1260 */
1261 DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1262 uint32_t u32ClientId,
1263 const char *pszUser,
1264 const char *pszPassword,
1265 const char *pszDomain));
1266
1267 /* The client has been successfully connected. That is logon was successful and the
1268 * remote desktop protocol connection completely established.
1269 *
1270 * @param pvCallback The callback specific pointer.
1271 * @param u32ClientId An unique client identifier generated by the server.
1272 */
1273 DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1274 uint32_t u32ClientId));
1275
1276 /* The client has been disconnected.
1277 *
1278 * @param pvCallback The callback specific pointer.
1279 * @param u32ClientId An unique client identifier generated by the server.
1280 * @param fu32Intercepted What was intercepted by the client (VRDE_CLIENT_INTERCEPT_*).
1281 */
1282 DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1283 uint32_t u32ClientId,
1284 uint32_t fu32Intercepted));
1285 /* The client supports one of RDP channels.
1286 *
1287 * @param pvCallback The callback specific pointer.
1288 * @param u32ClientId An unique client identifier generated by the server.
1289 * @param fu32Intercept What the client wants to intercept. One of VRDE_CLIENT_INTERCEPT_* flags.
1290 * @param ppvIntercept The value to be passed to the channel specific callback.
1291 *
1292 * @return IPRT status code.
1293 */
1294 DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1295 uint32_t u32ClientId,
1296 uint32_t fu32Intercept,
1297 void **ppvIntercept));
1298
1299 /**
1300 * Called by the server when a reply is received from a client.
1301 *
1302 * @param pvCallback The callback specific pointer.
1303 * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_USB.
1304 * @param u32ClientId Identifies the client that sent the reply.
1305 * @param u8Code The operation code VRDE_USB_REQ_*.
1306 * @param pvRet Points to data received from the client.
1307 * @param cbRet Size of the data in bytes.
1308 *
1309 * @return IPRT status code.
1310 */
1311 DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1312 void *pvIntercept,
1313 uint32_t u32ClientId,
1314 uint8_t u8Code,
1315 const void *pvRet,
1316 uint32_t cbRet));
1317
1318 /**
1319 * Called by the server when (VRDE_CLIPBOARD_FUNCTION_*):
1320 * - (0) client announces available clipboard formats;
1321 * - (1) client requests clipboard data.
1322 *
1323 * @param pvCallback The callback specific pointer.
1324 * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_CLIPBOARD.
1325 * @param u32ClientId Identifies the RDP client that sent the reply.
1326 * @param u32Function The cause of the callback.
1327 * @param u32Format Bitmask of reported formats or the format of received data.
1328 * @param pvData Reserved.
1329 * @param cbData Reserved.
1330 *
1331 * @return IPRT status code.
1332 */
1333 DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1334 void *pvIntercept,
1335 uint32_t u32ClientId,
1336 uint32_t u32Function,
1337 uint32_t u32Format,
1338 const void *pvData,
1339 uint32_t cbData));
1340
1341 /* The framebuffer information is queried.
1342 *
1343 * @param pvCallback The callback specific pointer.
1344 * @param uScreenId The framebuffer index.
1345 * @param pInfo The information structure to ber filled.
1346 *
1347 * @return Whether the framebuffer is available.
1348 */
1349 DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1350 unsigned uScreenId,
1351 VRDEFRAMEBUFFERINFO *pInfo));
1352
1353 /* Request the exclusive access to the framebuffer bitmap.
1354 * Currently not used because VirtualBox makes sure that the framebuffer is available
1355 * when VRDEUpdate is called.
1356 *
1357 * @param pvCallback The callback specific pointer.
1358 * @param uScreenId The framebuffer index.
1359 */
1360 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1361 unsigned uScreenId));
1362
1363 /* Release the exclusive access to the framebuffer bitmap.
1364 * Currently not used because VirtualBox makes sure that the framebuffer is available
1365 * when VRDEUpdate is called.
1366 *
1367 * @param pvCallback The callback specific pointer.
1368 * @param uScreenId The framebuffer index.
1369 */
1370 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1371 unsigned uScreenId));
1372
1373 /* Input from the client.
1374 *
1375 * @param pvCallback The callback specific pointer.
1376 * @param pvInput The input information.
1377 * @param cbInput The size of the input information.
1378 */
1379 DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1380 int type,
1381 const void *pvInput,
1382 unsigned cbInput));
1383
1384 /* Video mode hint from the client.
1385 *
1386 * @param pvCallback The callback specific pointer.
1387 * @param cWidth Requested width.
1388 * @param cHeight Requested height.
1389 * @param cBitsPerPixel Requested color depth.
1390 * @param uScreenId The framebuffer index.
1391 */
1392 DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1393 unsigned cWidth,
1394 unsigned cHeight,
1395 unsigned cBitsPerPixel,
1396 unsigned uScreenId));
1397
1398} VRDECALLBACKS_1;
1399
1400/* Callbacks are the same for the version 1 and version 2 interfaces. */
1401typedef VRDECALLBACKS_1 VRDECALLBACKS_2;
1402
1403/** The VRDE server callbacks. Interface version 3. */
1404typedef struct _VRDECALLBACKS_3
1405{
1406 /* The header. */
1407 VRDEINTERFACEHDR header;
1408
1409 /*
1410 * Same as in version 1 and 2. See comment in VRDECALLBACKS_1.
1411 */
1412 DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1413 uint32_t index,
1414 void *pvBuffer,
1415 uint32_t cbBuffer,
1416 uint32_t *pcbOut));
1417
1418 DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1419 uint32_t u32ClientId,
1420 const char *pszUser,
1421 const char *pszPassword,
1422 const char *pszDomain));
1423
1424 DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1425 uint32_t u32ClientId));
1426
1427 DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1428 uint32_t u32ClientId,
1429 uint32_t fu32Intercepted));
1430 DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1431 uint32_t u32ClientId,
1432 uint32_t fu32Intercept,
1433 void **ppvIntercept));
1434
1435 DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1436 void *pvIntercept,
1437 uint32_t u32ClientId,
1438 uint8_t u8Code,
1439 const void *pvRet,
1440 uint32_t cbRet));
1441
1442 DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1443 void *pvIntercept,
1444 uint32_t u32ClientId,
1445 uint32_t u32Function,
1446 uint32_t u32Format,
1447 const void *pvData,
1448 uint32_t cbData));
1449
1450 DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1451 unsigned uScreenId,
1452 VRDEFRAMEBUFFERINFO *pInfo));
1453
1454 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1455 unsigned uScreenId));
1456
1457 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1458 unsigned uScreenId));
1459
1460 DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1461 int type,
1462 const void *pvInput,
1463 unsigned cbInput));
1464
1465 DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1466 unsigned cWidth,
1467 unsigned cHeight,
1468 unsigned cBitsPerPixel,
1469 unsigned uScreenId));
1470
1471 /*
1472 * New for version 3.
1473 */
1474
1475 /**
1476 * Called by the server when something happens with audio input.
1477 *
1478 * @param pvCallback The callback specific pointer.
1479 * @param pvCtx The value passed in VRDEAudioInOpen.
1480 * @param u32ClientId Identifies the client that sent the reply.
1481 * @param u32Event The event code VRDE_AUDIOIN_*.
1482 * @param pvData Points to data received from the client.
1483 * @param cbData Size of the data in bytes.
1484 */
1485 DECLR3CALLBACKMEMBER(void, VRDECallbackAudioIn,(void *pvCallback,
1486 void *pvCtx,
1487 uint32_t u32ClientId,
1488 uint32_t u32Event,
1489 const void *pvData,
1490 uint32_t cbData));
1491} VRDECALLBACKS_3;
1492
1493/** The VRDE server entry points. Interface version 4.
1494 * New entry point VRDEGetInterface has been added relative to version 3.
1495 */
1496typedef struct _VRDEENTRYPOINTS_4
1497{
1498 /* The header. */
1499 VRDEINTERFACEHDR header;
1500
1501 /*
1502 * Same as version 3. See comment in VRDEENTRYPOINTS_3.
1503 */
1504
1505 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
1506 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable));
1507 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect));
1508 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
1509 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate,
1510 uint32_t cbUpdate));
1511 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer));
1512 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
1513 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples,
1514 VRDEAUDIOFORMAT format));
1515 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right));
1516 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm,
1517 uint32_t cbParm));
1518 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format,
1519 void *pvData, uint32_t cbData, uint32_t *pcbActualRead));
1520 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer,
1521 uint32_t *pcbOut));
1522 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer,
1523 const char *pszUser, const char *pszDomain, const char *pszPassword,
1524 uint32_t u32SessionId, const char *pszCookie));
1525 DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer, void *pvCtx, uint32_t u32ClientId,
1526 VRDEAUDIOFORMAT audioFormat, uint32_t u32SamplesPerBlock));
1527 DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer, uint32_t u32ClientId));
1528
1529 /**
1530 * Generic interface query. An interface is a set of entry points and callbacks.
1531 * It is not a reference counted interface.
1532 *
1533 * @param hServer Handle of VRDE server instance.
1534 * @param pszId String identifier of the interface, like uuid.
1535 * @param pInterface The interface structure to be initialized by the VRDE server.
1536 * Only VRDEINTERFACEHDR is initialized by the caller.
1537 * @param pCallbacks Callbacks required by the interface. The server makes a local copy.
1538 * VRDEINTERFACEHDR version must correspond to the requested interface version.
1539 * @param pvContext The context to be used in callbacks.
1540 */
1541
1542 DECLR3CALLBACKMEMBER(int, VRDEGetInterface, (HVRDESERVER hServer,
1543 const char *pszId,
1544 VRDEINTERFACEHDR *pInterface,
1545 const VRDEINTERFACEHDR *pCallbacks,
1546 void *pvContext));
1547} VRDEENTRYPOINTS_4;
1548
1549/* Callbacks are the same for the version 3 and version 4 interfaces. */
1550typedef VRDECALLBACKS_3 VRDECALLBACKS_4;
1551
1552/**
1553 * Create a new VRDE server instance. The instance is fully functional but refuses
1554 * client connections until the entry point VRDEEnableConnections is called by the application.
1555 *
1556 * The caller prepares the VRDECALLBACKS_* structure. The header.u64Version field of the
1557 * structure must be initialized with the version of the interface to use.
1558 * The server will return pointer to VRDEENTRYPOINTS_* table in *ppEntryPoints
1559 * to match the requested interface.
1560 * That is if pCallbacks->header.u64Version == VRDE_INTERFACE_VERSION_1, then the server
1561 * expects pCallbacks to point to VRDECALLBACKS_1 and will return a pointer to VRDEENTRYPOINTS_1.
1562 *
1563 * @param pCallback Pointer to the application callbacks which let the server to fetch
1564 * the configuration data and to access the desktop.
1565 * @param pvCallback The callback specific pointer to be passed back to the application.
1566 * @param ppEntryPoints Where to store the pointer to the VRDE entry points structure.
1567 * @param phServer Pointer to the created server instance handle.
1568 *
1569 * @return IPRT status code.
1570 */
1571DECLEXPORT(int) VRDECreateServer (const VRDEINTERFACEHDR *pCallbacks,
1572 void *pvCallback,
1573 VRDEINTERFACEHDR **ppEntryPoints,
1574 HVRDESERVER *phServer);
1575
1576typedef DECLCALLBACKTYPE(int, FNVRDECREATESERVER,(const VRDEINTERFACEHDR *pCallbacks,
1577 void *pvCallback,
1578 VRDEINTERFACEHDR **ppEntryPoints,
1579 HVRDESERVER *phServer));
1580typedef FNVRDECREATESERVER *PFNVRDECREATESERVER;
1581
1582/**
1583 * List of names of the VRDE properties, which are recognized by the VRDE.
1584 *
1585 * For example VRDESupportedProperties should return gapszProperties declared as:
1586 *
1587 * static const char * const gapszProperties[] =
1588 * {
1589 * "TCP/Ports",
1590 * "TCP/Address",
1591 * NULL
1592 * };
1593 *
1594 * @returns pointer to array of pointers to name strings (UTF8).
1595 */
1596DECLEXPORT(const char * const *) VRDESupportedProperties (void);
1597
1598typedef DECLCALLBACKTYPE(const char * const *, FNVRDESUPPORTEDPROPERTIES,(void));
1599typedef FNVRDESUPPORTEDPROPERTIES *PFNVRDESUPPORTEDPROPERTIES;
1600
1601RT_C_DECLS_END
1602
1603/** @} */
1604
1605#endif /* !VBOX_INCLUDED_RemoteDesktop_VRDE_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette