VirtualBox

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

Last change on this file since 39435 was 39435, checked in by vboxsync, 13 years ago

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