VirtualBox

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

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

VRDE.h: comments.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 61.9 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. OHCI Completion Codes. */
331#define VRDE_USB_XFER_BS (4) /* BitStuffing */
332#define VRDE_USB_XFER_DTM (5) /* DataToggleMismatch */
333#define VRDE_USB_XFER_PCF (6) /* PIDCheckFailure */
334#define VRDE_USB_XFER_UPID (7) /* UnexpectedPID */
335#define VRDE_USB_XFER_DO (8) /* DataOverrun */
336#define VRDE_USB_XFER_DU (9) /* DataUnderrun */
337#define VRDE_USB_XFER_BO (10) /* BufferOverrun */
338#define VRDE_USB_XFER_BU (11) /* BufferUnderrun */
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_STATUS (VRDE_SP_BASE + 2) /* UTF8 string. The change of the generic client status:
1153 * "ATTACH" - the client is attached;
1154 * "DETACH" - the client is detached;
1155 * "NAME=..." - the client name changes.
1156 * Can be used for other notifications.
1157 */
1158
1159#pragma pack(1)
1160/* VRDE_QP_FEATURE data. */
1161typedef struct _VRDEFEATURE
1162{
1163 uint32_t u32ClientId;
1164 char achInfo[1]; /* UTF8 property input name and output value. */
1165} VRDEFEATURE;
1166
1167/* VRDE_SP_CLIENT_STATUS data. */
1168typedef struct VRDECLIENTSTATUS
1169{
1170 uint32_t u32ClientId;
1171 uint32_t cbStatus;
1172 char achStatus[1]; /* UTF8 status string. */
1173} VRDECLIENTSTATUS;
1174
1175/* A framebuffer description. */
1176typedef struct _VRDEFRAMEBUFFERINFO
1177{
1178 const uint8_t *pu8Bits;
1179 int xOrigin;
1180 int yOrigin;
1181 unsigned cWidth;
1182 unsigned cHeight;
1183 unsigned cBitsPerPixel;
1184 unsigned cbLine;
1185} VRDEFRAMEBUFFERINFO;
1186
1187#define VRDE_INPUT_SCANCODE 0
1188#define VRDE_INPUT_POINT 1
1189#define VRDE_INPUT_CAD 2
1190#define VRDE_INPUT_RESET 3
1191#define VRDE_INPUT_SYNCH 4
1192
1193typedef struct _VRDEINPUTSCANCODE
1194{
1195 unsigned uScancode;
1196} VRDEINPUTSCANCODE;
1197
1198#define VRDE_INPUT_POINT_BUTTON1 0x01
1199#define VRDE_INPUT_POINT_BUTTON2 0x02
1200#define VRDE_INPUT_POINT_BUTTON3 0x04
1201#define VRDE_INPUT_POINT_WHEEL_UP 0x08
1202#define VRDE_INPUT_POINT_WHEEL_DOWN 0x10
1203
1204typedef struct _VRDEINPUTPOINT
1205{
1206 int x;
1207 int y;
1208 unsigned uButtons;
1209} VRDEINPUTPOINT;
1210
1211#define VRDE_INPUT_SYNCH_SCROLL 0x01
1212#define VRDE_INPUT_SYNCH_NUMLOCK 0x02
1213#define VRDE_INPUT_SYNCH_CAPITAL 0x04
1214
1215typedef struct _VRDEINPUTSYNCH
1216{
1217 unsigned uLockStatus;
1218} VRDEINPUTSYNCH;
1219#pragma pack()
1220
1221/** The VRDE server callbacks. Interface version 1. */
1222typedef struct _VRDECALLBACKS_1
1223{
1224 /** The header. */
1225 VRDEINTERFACEHDR header;
1226
1227 /**
1228 * Query or set various information, on how the VRDE server operates, from or to the application.
1229 * Queries for properties will always return success, and if the key is not known or has no
1230 * value associated with it an empty string is returned.
1231 *
1232 *
1233 * @param pvCallback The callback specific pointer.
1234 * @param index VRDE_[Q|S]P_* identifier of information to be returned or set.
1235 * @param pvBuffer Address of memory buffer to which the information must be written or read.
1236 * @param cbBuffer Size of the memory buffer in bytes.
1237 * @param pcbOut Size in bytes of returned information value.
1238 *
1239 * @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value.
1240 */
1241 DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1242 uint32_t index,
1243 void *pvBuffer,
1244 uint32_t cbBuffer,
1245 uint32_t *pcbOut));
1246
1247 /* A client is logging in, the application must decide whether
1248 * to let to connect the client. The server will drop the connection,
1249 * when an error code is returned by the callback.
1250 *
1251 * @param pvCallback The callback specific pointer.
1252 * @param u32ClientId An unique client identifier generated by the server.
1253 * @param pszUser The username.
1254 * @param pszPassword The password.
1255 * @param pszDomain The domain.
1256 *
1257 * @return IPRT status code.
1258 */
1259 DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1260 uint32_t u32ClientId,
1261 const char *pszUser,
1262 const char *pszPassword,
1263 const char *pszDomain));
1264
1265 /* The client has been successfully connected. That is logon was successful and the
1266 * remote desktop protocol connection completely established.
1267 *
1268 * @param pvCallback The callback specific pointer.
1269 * @param u32ClientId An unique client identifier generated by the server.
1270 */
1271 DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1272 uint32_t u32ClientId));
1273
1274 /* The client has been disconnected.
1275 *
1276 * @param pvCallback The callback specific pointer.
1277 * @param u32ClientId An unique client identifier generated by the server.
1278 * @param fu32Intercepted What was intercepted by the client (VRDE_CLIENT_INTERCEPT_*).
1279 */
1280 DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1281 uint32_t u32ClientId,
1282 uint32_t fu32Intercepted));
1283 /* The client supports one of RDP channels.
1284 *
1285 * @param pvCallback The callback specific pointer.
1286 * @param u32ClientId An unique client identifier generated by the server.
1287 * @param fu32Intercept What the client wants to intercept. One of VRDE_CLIENT_INTERCEPT_* flags.
1288 * @param ppvIntercept The value to be passed to the channel specific callback.
1289 *
1290 * @return IPRT status code.
1291 */
1292 DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1293 uint32_t u32ClientId,
1294 uint32_t fu32Intercept,
1295 void **ppvIntercept));
1296
1297 /**
1298 * Called by the server when a reply is received from a client.
1299 *
1300 * @param pvCallback The callback specific pointer.
1301 * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_USB.
1302 * @param u32ClientId Identifies the client that sent the reply.
1303 * @param u8Code The operation code VRDE_USB_REQ_*.
1304 * @param pvRet Points to data received from the client.
1305 * @param cbRet Size of the data in bytes.
1306 *
1307 * @return IPRT status code.
1308 */
1309 DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1310 void *pvIntercept,
1311 uint32_t u32ClientId,
1312 uint8_t u8Code,
1313 const void *pvRet,
1314 uint32_t cbRet));
1315
1316 /**
1317 * Called by the server when (VRDE_CLIPBOARD_FUNCTION_*):
1318 * - (0) client announces available clipboard formats;
1319 * - (1) client requests clipboard data.
1320 *
1321 * @param pvCallback The callback specific pointer.
1322 * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_CLIPBOARD.
1323 * @param u32ClientId Identifies the RDP client that sent the reply.
1324 * @param u32Function The cause of the callback.
1325 * @param u32Format Bitmask of reported formats or the format of received data.
1326 * @param pvData Reserved.
1327 * @param cbData Reserved.
1328 *
1329 * @return IPRT status code.
1330 */
1331 DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1332 void *pvIntercept,
1333 uint32_t u32ClientId,
1334 uint32_t u32Function,
1335 uint32_t u32Format,
1336 const void *pvData,
1337 uint32_t cbData));
1338
1339 /* The framebuffer information is queried.
1340 *
1341 * @param pvCallback The callback specific pointer.
1342 * @param uScreenId The framebuffer index.
1343 * @param pInfo The information structure to ber filled.
1344 *
1345 * @return Whether the framebuffer is available.
1346 */
1347 DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1348 unsigned uScreenId,
1349 VRDEFRAMEBUFFERINFO *pInfo));
1350
1351 /* Request the exclusive access to the framebuffer bitmap.
1352 * Currently not used because VirtualBox makes sure that the framebuffer is available
1353 * when VRDEUpdate is called.
1354 *
1355 * @param pvCallback The callback specific pointer.
1356 * @param uScreenId The framebuffer index.
1357 */
1358 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1359 unsigned uScreenId));
1360
1361 /* Release the exclusive access to the framebuffer bitmap.
1362 * Currently not used because VirtualBox makes sure that the framebuffer is available
1363 * when VRDEUpdate is called.
1364 *
1365 * @param pvCallback The callback specific pointer.
1366 * @param uScreenId The framebuffer index.
1367 */
1368 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1369 unsigned uScreenId));
1370
1371 /* Input from the client.
1372 *
1373 * @param pvCallback The callback specific pointer.
1374 * @param pvInput The input information.
1375 * @param cbInput The size of the input information.
1376 */
1377 DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1378 int type,
1379 const void *pvInput,
1380 unsigned cbInput));
1381
1382 /* Video mode hint from the client.
1383 *
1384 * @param pvCallback The callback specific pointer.
1385 * @param cWidth Requested width.
1386 * @param cHeight Requested height.
1387 * @param cBitsPerPixel Requested color depth.
1388 * @param uScreenId The framebuffer index.
1389 */
1390 DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1391 unsigned cWidth,
1392 unsigned cHeight,
1393 unsigned cBitsPerPixel,
1394 unsigned uScreenId));
1395
1396} VRDECALLBACKS_1;
1397
1398/* Callbacks are the same for the version 1 and version 2 interfaces. */
1399typedef VRDECALLBACKS_1 VRDECALLBACKS_2;
1400
1401/** The VRDE server callbacks. Interface version 3. */
1402typedef struct _VRDECALLBACKS_3
1403{
1404 /* The header. */
1405 VRDEINTERFACEHDR header;
1406
1407 /*
1408 * Same as in version 1 and 2. See comment in VRDECALLBACKS_1.
1409 */
1410 DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1411 uint32_t index,
1412 void *pvBuffer,
1413 uint32_t cbBuffer,
1414 uint32_t *pcbOut));
1415
1416 DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1417 uint32_t u32ClientId,
1418 const char *pszUser,
1419 const char *pszPassword,
1420 const char *pszDomain));
1421
1422 DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1423 uint32_t u32ClientId));
1424
1425 DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1426 uint32_t u32ClientId,
1427 uint32_t fu32Intercepted));
1428 DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1429 uint32_t u32ClientId,
1430 uint32_t fu32Intercept,
1431 void **ppvIntercept));
1432
1433 DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1434 void *pvIntercept,
1435 uint32_t u32ClientId,
1436 uint8_t u8Code,
1437 const void *pvRet,
1438 uint32_t cbRet));
1439
1440 DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1441 void *pvIntercept,
1442 uint32_t u32ClientId,
1443 uint32_t u32Function,
1444 uint32_t u32Format,
1445 const void *pvData,
1446 uint32_t cbData));
1447
1448 DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1449 unsigned uScreenId,
1450 VRDEFRAMEBUFFERINFO *pInfo));
1451
1452 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1453 unsigned uScreenId));
1454
1455 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1456 unsigned uScreenId));
1457
1458 DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1459 int type,
1460 const void *pvInput,
1461 unsigned cbInput));
1462
1463 DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1464 unsigned cWidth,
1465 unsigned cHeight,
1466 unsigned cBitsPerPixel,
1467 unsigned uScreenId));
1468
1469 /*
1470 * New for version 3.
1471 */
1472
1473 /**
1474 * Called by the server when something happens with audio input.
1475 *
1476 * @param pvCallback The callback specific pointer.
1477 * @param pvCtx The value passed in VRDEAudioInOpen.
1478 * @param u32ClientId Identifies the client that sent the reply.
1479 * @param u32Event The event code VRDE_AUDIOIN_*.
1480 * @param pvData Points to data received from the client.
1481 * @param cbData Size of the data in bytes.
1482 */
1483 DECLR3CALLBACKMEMBER(void, VRDECallbackAudioIn,(void *pvCallback,
1484 void *pvCtx,
1485 uint32_t u32ClientId,
1486 uint32_t u32Event,
1487 const void *pvData,
1488 uint32_t cbData));
1489} VRDECALLBACKS_3;
1490
1491/** The VRDE server entry points. Interface version 4.
1492 * New entry point VRDEGetInterface has been added relative to version 3.
1493 */
1494typedef struct _VRDEENTRYPOINTS_4
1495{
1496 /* The header. */
1497 VRDEINTERFACEHDR header;
1498
1499 /*
1500 * Same as version 3. See comment in VRDEENTRYPOINTS_3.
1501 */
1502
1503 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
1504 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable));
1505 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect));
1506 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
1507 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate,
1508 uint32_t cbUpdate));
1509 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer));
1510 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
1511 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples,
1512 VRDEAUDIOFORMAT format));
1513 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right));
1514 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm,
1515 uint32_t cbParm));
1516 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format,
1517 void *pvData, uint32_t cbData, uint32_t *pcbActualRead));
1518 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer,
1519 uint32_t *pcbOut));
1520 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer,
1521 const char *pszUser, const char *pszDomain, const char *pszPassword,
1522 uint32_t u32SessionId, const char *pszCookie));
1523 DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer, void *pvCtx, uint32_t u32ClientId,
1524 VRDEAUDIOFORMAT audioFormat, uint32_t u32SamplesPerBlock));
1525 DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer, uint32_t u32ClientId));
1526
1527 /**
1528 * Generic interface query. An interface is a set of entry points and callbacks.
1529 * It is not a reference counted interface.
1530 *
1531 * @param hServer Handle of VRDE server instance.
1532 * @param pszId String identifier of the interface, like uuid.
1533 * @param pInterface The interface structure to be initialized by the VRDE server.
1534 * Only VRDEINTERFACEHDR is initialized by the caller.
1535 * @param pCallbacks Callbacks required by the interface. The server makes a local copy.
1536 * VRDEINTERFACEHDR version must correspond to the requested interface version.
1537 * @param pvContext The context to be used in callbacks.
1538 */
1539
1540 DECLR3CALLBACKMEMBER(int, VRDEGetInterface, (HVRDESERVER hServer,
1541 const char *pszId,
1542 VRDEINTERFACEHDR *pInterface,
1543 const VRDEINTERFACEHDR *pCallbacks,
1544 void *pvContext));
1545} VRDEENTRYPOINTS_4;
1546
1547/* Callbacks are the same for the version 3 and version 4 interfaces. */
1548typedef VRDECALLBACKS_3 VRDECALLBACKS_4;
1549
1550/**
1551 * Create a new VRDE server instance. The instance is fully functional but refuses
1552 * client connections until the entry point VRDEEnableConnections is called by the application.
1553 *
1554 * The caller prepares the VRDECALLBACKS_* structure. The header.u64Version field of the
1555 * structure must be initialized with the version of the interface to use.
1556 * The server will return pointer to VRDEENTRYPOINTS_* table in *ppEntryPoints
1557 * to match the requested interface.
1558 * That is if pCallbacks->header.u64Version == VRDE_INTERFACE_VERSION_1, then the server
1559 * expects pCallbacks to point to VRDECALLBACKS_1 and will return a pointer to VRDEENTRYPOINTS_1.
1560 *
1561 * @param pCallback Pointer to the application callbacks which let the server to fetch
1562 * the configuration data and to access the desktop.
1563 * @param pvCallback The callback specific pointer to be passed back to the application.
1564 * @param ppEntryPoints Where to store the pointer to the VRDE entry points structure.
1565 * @param phServer Pointer to the created server instance handle.
1566 *
1567 * @return IPRT status code.
1568 */
1569DECLEXPORT(int) VRDECreateServer (const VRDEINTERFACEHDR *pCallbacks,
1570 void *pvCallback,
1571 VRDEINTERFACEHDR **ppEntryPoints,
1572 HVRDESERVER *phServer);
1573
1574typedef DECLCALLBACK(int) FNVRDECREATESERVER (const VRDEINTERFACEHDR *pCallbacks,
1575 void *pvCallback,
1576 VRDEINTERFACEHDR **ppEntryPoints,
1577 HVRDESERVER *phServer);
1578typedef FNVRDECREATESERVER *PFNVRDECREATESERVER;
1579
1580/**
1581 * List of names of the VRDE properties, which are recognized by the VRDE.
1582 *
1583 * For example VRDESupportedProperties should return gapszProperties declared as:
1584 *
1585 * static const char * const gapszProperties[] =
1586 * {
1587 * "TCP/Ports",
1588 * "TCP/Address",
1589 * NULL
1590 * };
1591 *
1592 * @returns pointer to array of pointers to name strings (UTF8).
1593 */
1594DECLEXPORT(const char * const *) VRDESupportedProperties (void);
1595
1596typedef DECLCALLBACK(const char * const *) FNVRDESUPPORTEDPROPERTIES (void);
1597typedef FNVRDESUPPORTEDPROPERTIES *PFNVRDESUPPORTEDPROPERTIES;
1598
1599RT_C_DECLS_END
1600
1601/** @} */
1602
1603#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