VirtualBox

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

Last change on this file since 106165 was 106061, checked in by vboxsync, 3 months ago

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