VirtualBox

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

Last change on this file since 36423 was 36423, checked in by vboxsync, 14 years ago

VRDE.h: note about UTF8 USB descriptor strings. Minor updates for 4th version of VRDE interface
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 58.6 KB
Line 
1/** @file
2 * VBox Remote Desktop Extension (VRDE) - Public APIs.
3 */
4
5/*
6 * Copyright (C) 2006-2010 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
441typedef struct _VRDE_USB_REQ_DEVICE_LIST_RET
442{
443 VRDEUSBDEVICEDESC body;
444 /* Other devices may follow.
445 * The list ends with (uint16_t)0,
446 * which means that an empty list consists of 2 zero bytes.
447 */
448} VRDE_USB_REQ_DEVICE_LIST_RET;
449
450typedef struct _VRDEUSBREQNEGOTIATEPARM
451{
452 uint8_t code;
453
454 /* Remote USB Protocol version. */
455 /* VRDE_USB_VERSION_3: the 32 bit field is splitted to 16 bit version and 16 bit flags.
456 * Version 1 and 2 servers therefore have 'flags' == 0.
457 * Version 3+ servers can send some capabilities in this field, this way it is possible to add
458 * a new capability without increasing the protocol version.
459 */
460 uint16_t version;
461 uint16_t flags;
462
463} VRDEUSBREQNEGOTIATEPARM;
464
465#define VRDE_USB_CAPS_FLAG_ASYNC (0x0)
466#define VRDE_USB_CAPS_FLAG_POLL (0x1)
467/* VRDE_USB_VERSION_2: New flag. */
468#define VRDE_USB_CAPS2_FLAG_VERSION (0x2) /* The client is negotiating the protocol version. */
469
470
471#define VRDE_USB_CAPS_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL)
472/* VRDE_USB_VERSION_2: A set of valid flags. */
473#define VRDE_USB_CAPS2_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL | VRDE_USB_CAPS2_FLAG_VERSION)
474
475typedef struct _VRDEUSBREQNEGOTIATERET
476{
477 uint8_t flags;
478} VRDEUSBREQNEGOTIATERET;
479
480typedef struct _VRDEUSBREQNEGOTIATERET_2
481{
482 uint8_t flags;
483 uint32_t u32Version; /* This field presents only if the VRDE_USB_CAPS2_FLAG_VERSION flag is set. */
484} VRDEUSBREQNEGOTIATERET_2;
485#pragma pack()
486
487#define VRDE_CLIPBOARD_FORMAT_NULL (0x0)
488#define VRDE_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
489#define VRDE_CLIPBOARD_FORMAT_BITMAP (0x2)
490#define VRDE_CLIPBOARD_FORMAT_HTML (0x4)
491
492#define VRDE_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
493#define VRDE_CLIPBOARD_FUNCTION_DATA_READ (1)
494#define VRDE_CLIPBOARD_FUNCTION_DATA_WRITE (2)
495
496
497/** Indexes of information values. */
498
499/** Whether a client is connected at the moment.
500 * uint32_t
501 */
502#define VRDE_QI_ACTIVE (0)
503
504/** How many times a client connected up to current moment.
505 * uint32_t
506 */
507#define VRDE_QI_NUMBER_OF_CLIENTS (1)
508
509/** When last connection was established.
510 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
511 */
512#define VRDE_QI_BEGIN_TIME (2)
513
514/** When last connection was terminated or current time if connection still active.
515 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
516 */
517#define VRDE_QI_END_TIME (3)
518
519/** How many bytes were sent in last (current) connection.
520 * uint64_t
521 */
522#define VRDE_QI_BYTES_SENT (4)
523
524/** How many bytes were sent in all connections.
525 * uint64_t
526 */
527#define VRDE_QI_BYTES_SENT_TOTAL (5)
528
529/** How many bytes were received in last (current) connection.
530 * uint64_t
531 */
532#define VRDE_QI_BYTES_RECEIVED (6)
533
534/** How many bytes were received in all connections.
535 * uint64_t
536 */
537#define VRDE_QI_BYTES_RECEIVED_TOTAL (7)
538
539/** Login user name supplied by the client.
540 * UTF8 nul terminated string.
541 */
542#define VRDE_QI_USER (8)
543
544/** Login domain supplied by the client.
545 * UTF8 nul terminated string.
546 */
547#define VRDE_QI_DOMAIN (9)
548
549/** The client name supplied by the client.
550 * UTF8 nul terminated string.
551 */
552#define VRDE_QI_CLIENT_NAME (10)
553
554/** IP address of the client.
555 * UTF8 nul terminated string.
556 */
557#define VRDE_QI_CLIENT_IP (11)
558
559/** The client software version number.
560 * uint32_t.
561 */
562#define VRDE_QI_CLIENT_VERSION (12)
563
564/** Public key exchange method used when connection was established.
565 * Values: 0 - RDP4 public key exchange scheme.
566 * 1 - X509 sertificates were sent to client.
567 * uint32_t.
568 */
569#define VRDE_QI_ENCRYPTION_STYLE (13)
570
571/** TCP port where the server listens.
572 * Values: 0 - VRDE server failed to start.
573 * -1 - .
574 * int32_t.
575 */
576#define VRDE_QI_PORT (14)
577
578
579/** Hints what has been intercepted by the application. */
580#define VRDE_CLIENT_INTERCEPT_AUDIO (0x1)
581#define VRDE_CLIENT_INTERCEPT_USB (0x2)
582#define VRDE_CLIENT_INTERCEPT_CLIPBOARD (0x4)
583#define VRDE_CLIENT_INTERCEPT_AUDIO_INPUT (0x8)
584
585
586/** The version of the VRDE server interface. */
587#define VRDE_INTERFACE_VERSION_1 (1)
588#define VRDE_INTERFACE_VERSION_2 (2)
589#define VRDE_INTERFACE_VERSION_3 (3)
590#define VRDE_INTERFACE_VERSION_4 (4)
591
592/** The header that does not change when the interface changes. */
593typedef struct _VRDEINTERFACEHDR
594{
595 /** The version of the interface. */
596 uint64_t u64Version;
597
598 /** The size of the structure. */
599 uint64_t u64Size;
600
601} VRDEINTERFACEHDR;
602
603/** The VRDE server entry points. Interface version 1. */
604typedef struct _VRDEENTRYPOINTS_1
605{
606 /** The header. */
607 VRDEINTERFACEHDR header;
608
609 /** Destroy the server instance.
610 *
611 * @param hServer The server instance handle.
612 *
613 * @return IPRT status code.
614 */
615 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
616
617 /** The server should start to accept clients connections.
618 *
619 * @param hServer The server instance handle.
620 * @param fEnable Whether to enable or disable client connections.
621 * When is false, all existing clients are disconnected.
622 *
623 * @return IPRT status code.
624 */
625 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
626 bool fEnable));
627
628 /** The server should disconnect the client.
629 *
630 * @param hServer The server instance handle.
631 * @param u32ClientId The client identifier.
632 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
633 * client before disconnecting.
634 *
635 * @return IPRT status code.
636 */
637 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
638 uint32_t u32ClientId,
639 bool fReconnect));
640
641 /**
642 * Inform the server that the display was resized.
643 * The server will query information about display
644 * from the application via callbacks.
645 *
646 * @param hServer Handle of VRDE server instance.
647 */
648 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
649
650 /**
651 * Send a update.
652 *
653 * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called.
654 * If the have to access the bitmap later or from another thread, then
655 * it must used an intermediate buffer and copy the framebuffer data to the
656 * intermediate buffer in VRDEUpdate.
657 *
658 * @param hServer Handle of VRDE server instance.
659 * @param uScreenId The screen index.
660 * @param pvUpdate Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data.
661 * @param cbUpdate Size of the update data.
662 */
663 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
664 unsigned uScreenId,
665 void *pvUpdate,
666 uint32_t cbUpdate));
667
668 /**
669 * Set the mouse pointer shape.
670 *
671 * @param hServer Handle of VRDE server instance.
672 * @param pPointer The pointer shape information.
673 */
674 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
675 const VRDECOLORPOINTER *pPointer));
676
677 /**
678 * Hide the mouse pointer.
679 *
680 * @param hServer Handle of VRDE server instance.
681 */
682 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
683
684 /**
685 * Queues the samples to be sent to clients.
686 *
687 * @param hServer Handle of VRDE server instance.
688 * @param pvSamples Address of samples to be sent.
689 * @param cSamples Number of samples.
690 * @param format Encoded audio format for these samples.
691 *
692 * @note Initialized to NULL when the application audio callbacks are NULL.
693 */
694 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
695 const void *pvSamples,
696 uint32_t cSamples,
697 VRDEAUDIOFORMAT format));
698
699 /**
700 * Sets the sound volume on clients.
701 *
702 * @param hServer Handle of VRDE server instance.
703 * @param left 0..0xFFFF volume level for left channel.
704 * @param right 0..0xFFFF volume level for right channel.
705 *
706 * @note Initialized to NULL when the application audio callbacks are NULL.
707 */
708 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
709 uint16_t u16Left,
710 uint16_t u16Right));
711
712 /**
713 * Sends a USB request.
714 *
715 * @param hServer Handle of VRDE server instance.
716 * @param u32ClientId An identifier that allows the server to find the corresponding client.
717 * The identifier is always passed by the server as a parameter
718 * of the FNVRDEUSBCALLBACK. Note that the value is the same as
719 * in the VRDESERVERCALLBACK functions.
720 * @param pvParm Function specific parameters buffer.
721 * @param cbParm Size of the buffer.
722 *
723 * @note Initialized to NULL when the application USB callbacks are NULL.
724 */
725 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
726 uint32_t u32ClientId,
727 void *pvParm,
728 uint32_t cbParm));
729
730 /**
731 * Called by the application when (VRDE_CLIPBOARD_FUNCTION_*):
732 * - (0) guest announces available clipboard formats;
733 * - (1) guest requests clipboard data;
734 * - (2) guest responds to the client's request for clipboard data.
735 *
736 * @param hServer The VRDE server handle.
737 * @param u32Function The cause of the call.
738 * @param u32Format Bitmask of announced formats or the format of data.
739 * @param pvData Points to: (1) buffer to be filled with clients data;
740 * (2) data from the host.
741 * @param cbData Size of 'pvData' buffer in bytes.
742 * @param pcbActualRead Size of the copied data in bytes.
743 *
744 * @note Initialized to NULL when the application clipboard callbacks are NULL.
745 */
746 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
747 uint32_t u32Function,
748 uint32_t u32Format,
749 void *pvData,
750 uint32_t cbData,
751 uint32_t *pcbActualRead));
752
753 /**
754 * Query various information from the VRDE server.
755 *
756 * @param hServer The VRDE server handle.
757 * @param index VRDE_QI_* identifier of information to be returned.
758 * @param pvBuffer Address of memory buffer to which the information must be written.
759 * @param cbBuffer Size of the memory buffer in bytes.
760 * @param pcbOut Size in bytes of returned information value.
761 *
762 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
763 * A value greater than cbBuffer means that information is too big to fit in the
764 * buffer, in that case no information was placed to the buffer.
765 */
766 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
767 uint32_t index,
768 void *pvBuffer,
769 uint32_t cbBuffer,
770 uint32_t *pcbOut));
771} VRDEENTRYPOINTS_1;
772
773/** The VRDE server entry points. Interface version 2.
774 * A new entry point VRDERedirect has been added relative to version 1.
775 */
776typedef struct _VRDEENTRYPOINTS_2
777{
778 /** The header. */
779 VRDEINTERFACEHDR header;
780
781 /** Destroy the server instance.
782 *
783 * @param hServer The server instance handle.
784 *
785 * @return IPRT status code.
786 */
787 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
788
789 /** The server should start to accept clients connections.
790 *
791 * @param hServer The server instance handle.
792 * @param fEnable Whether to enable or disable client connections.
793 * When is false, all existing clients are disconnected.
794 *
795 * @return IPRT status code.
796 */
797 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
798 bool fEnable));
799
800 /** The server should disconnect the client.
801 *
802 * @param hServer The server instance handle.
803 * @param u32ClientId The client identifier.
804 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
805 * client before disconnecting.
806 *
807 * @return IPRT status code.
808 */
809 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
810 uint32_t u32ClientId,
811 bool fReconnect));
812
813 /**
814 * Inform the server that the display was resized.
815 * The server will query information about display
816 * from the application via callbacks.
817 *
818 * @param hServer Handle of VRDE server instance.
819 */
820 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
821
822 /**
823 * Send a update.
824 *
825 * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called.
826 * If the have to access the bitmap later or from another thread, then
827 * it must used an intermediate buffer and copy the framebuffer data to the
828 * intermediate buffer in VRDEUpdate.
829 *
830 * @param hServer Handle of VRDE server instance.
831 * @param uScreenId The screen index.
832 * @param pvUpdate Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data.
833 * @param cbUpdate Size of the update data.
834 */
835 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
836 unsigned uScreenId,
837 void *pvUpdate,
838 uint32_t cbUpdate));
839
840 /**
841 * Set the mouse pointer shape.
842 *
843 * @param hServer Handle of VRDE server instance.
844 * @param pPointer The pointer shape information.
845 */
846 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
847 const VRDECOLORPOINTER *pPointer));
848
849 /**
850 * Hide the mouse pointer.
851 *
852 * @param hServer Handle of VRDE server instance.
853 */
854 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
855
856 /**
857 * Queues the samples to be sent to clients.
858 *
859 * @param hServer Handle of VRDE server instance.
860 * @param pvSamples Address of samples to be sent.
861 * @param cSamples Number of samples.
862 * @param format Encoded audio format for these samples.
863 *
864 * @note Initialized to NULL when the application audio callbacks are NULL.
865 */
866 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
867 const void *pvSamples,
868 uint32_t cSamples,
869 VRDEAUDIOFORMAT format));
870
871 /**
872 * Sets the sound volume on clients.
873 *
874 * @param hServer Handle of VRDE server instance.
875 * @param left 0..0xFFFF volume level for left channel.
876 * @param right 0..0xFFFF volume level for right channel.
877 *
878 * @note Initialized to NULL when the application audio callbacks are NULL.
879 */
880 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
881 uint16_t u16Left,
882 uint16_t u16Right));
883
884 /**
885 * Sends a USB request.
886 *
887 * @param hServer Handle of VRDE server instance.
888 * @param u32ClientId An identifier that allows the server to find the corresponding client.
889 * The identifier is always passed by the server as a parameter
890 * of the FNVRDEUSBCALLBACK. Note that the value is the same as
891 * in the VRDESERVERCALLBACK functions.
892 * @param pvParm Function specific parameters buffer.
893 * @param cbParm Size of the buffer.
894 *
895 * @note Initialized to NULL when the application USB callbacks are NULL.
896 */
897 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
898 uint32_t u32ClientId,
899 void *pvParm,
900 uint32_t cbParm));
901
902 /**
903 * Called by the application when (VRDE_CLIPBOARD_FUNCTION_*):
904 * - (0) guest announces available clipboard formats;
905 * - (1) guest requests clipboard data;
906 * - (2) guest responds to the client's request for clipboard data.
907 *
908 * @param hServer The VRDE server handle.
909 * @param u32Function The cause of the call.
910 * @param u32Format Bitmask of announced formats or the format of data.
911 * @param pvData Points to: (1) buffer to be filled with clients data;
912 * (2) data from the host.
913 * @param cbData Size of 'pvData' buffer in bytes.
914 * @param pcbActualRead Size of the copied data in bytes.
915 *
916 * @note Initialized to NULL when the application clipboard callbacks are NULL.
917 */
918 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
919 uint32_t u32Function,
920 uint32_t u32Format,
921 void *pvData,
922 uint32_t cbData,
923 uint32_t *pcbActualRead));
924
925 /**
926 * Query various information from the VRDE server.
927 *
928 * @param hServer The VRDE server handle.
929 * @param index VRDE_QI_* identifier of information to be returned.
930 * @param pvBuffer Address of memory buffer to which the information must be written.
931 * @param cbBuffer Size of the memory buffer in bytes.
932 * @param pcbOut Size in bytes of returned information value.
933 *
934 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
935 * A value greater than cbBuffer means that information is too big to fit in the
936 * buffer, in that case no information was placed to the buffer.
937 */
938 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
939 uint32_t index,
940 void *pvBuffer,
941 uint32_t cbBuffer,
942 uint32_t *pcbOut));
943
944 /**
945 * The server should redirect the client to the specified server.
946 *
947 * @param hServer The server instance handle.
948 * @param u32ClientId The client identifier.
949 * @param pszServer The server to redirect the client to.
950 * @param pszUser The username to use for the redirection.
951 * Can be NULL.
952 * @param pszDomain The domain. Can be NULL.
953 * @param pszPassword The password. Can be NULL.
954 * @param u32SessionId The ID of the session to redirect to.
955 * @param pszCookie The routing token used by a load balancer to
956 * route the redirection. Can be NULL.
957 */
958 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer,
959 uint32_t u32ClientId,
960 const char *pszServer,
961 const char *pszUser,
962 const char *pszDomain,
963 const char *pszPassword,
964 uint32_t u32SessionId,
965 const char *pszCookie));
966} VRDEENTRYPOINTS_2;
967
968/** The VRDE server entry points. Interface version 3.
969 * New entry points VRDEAudioInOpen and VRDEAudioInClose has been added relative to version 2.
970 */
971typedef struct _VRDEENTRYPOINTS_3
972{
973 /* The header. */
974 VRDEINTERFACEHDR header;
975
976 /*
977 * Same as version 2. See comment in VRDEENTRYPOINTS_2.
978 */
979
980 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
981
982 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
983 bool fEnable));
984
985 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
986 uint32_t u32ClientId,
987 bool fReconnect));
988
989 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
990
991 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
992 unsigned uScreenId,
993 void *pvUpdate,
994 uint32_t cbUpdate));
995
996 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
997 const VRDECOLORPOINTER *pPointer));
998
999 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
1000
1001 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
1002 const void *pvSamples,
1003 uint32_t cSamples,
1004 VRDEAUDIOFORMAT format));
1005
1006 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
1007 uint16_t u16Left,
1008 uint16_t u16Right));
1009
1010 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
1011 uint32_t u32ClientId,
1012 void *pvParm,
1013 uint32_t cbParm));
1014
1015 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
1016 uint32_t u32Function,
1017 uint32_t u32Format,
1018 void *pvData,
1019 uint32_t cbData,
1020 uint32_t *pcbActualRead));
1021
1022 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
1023 uint32_t index,
1024 void *pvBuffer,
1025 uint32_t cbBuffer,
1026 uint32_t *pcbOut));
1027
1028 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer,
1029 uint32_t u32ClientId,
1030 const char *pszServer,
1031 const char *pszUser,
1032 const char *pszDomain,
1033 const char *pszPassword,
1034 uint32_t u32SessionId,
1035 const char *pszCookie));
1036
1037 /*
1038 * New for version 3.
1039 */
1040
1041 /**
1042 * Audio input open request.
1043 *
1044 * @param hServer Handle of VRDE server instance.
1045 * @param pvCtx To be used in VRDECallbackAudioIn.
1046 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1047 * @param audioFormat Preferred format of audio data.
1048 * @param u32SamplesPerBlock Preferred number of samples in one block of audio input data.
1049 *
1050 * @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL.
1051 */
1052 DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer,
1053 void *pvCtx,
1054 uint32_t u32ClientId,
1055 VRDEAUDIOFORMAT audioFormat,
1056 uint32_t u32SamplesPerBlock));
1057
1058 /**
1059 * Audio input close request.
1060 *
1061 * @param hServer Handle of VRDE server instance.
1062 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1063 *
1064 * @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL.
1065 */
1066 DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer,
1067 uint32_t u32ClientId));
1068} VRDEENTRYPOINTS_3;
1069
1070
1071/* Indexes for VRDECallbackProperty.
1072 * *_QP_* queries a property.
1073 * *_SP_* sets a property.
1074 */
1075#define VRDE_QP_NETWORK_PORT (1) /* Obsolete. Use VRDE_QP_NETWORK_PORT_RANGE instead. */
1076#define VRDE_QP_NETWORK_ADDRESS (2) /* UTF8 string. Host network interface IP address to bind to. */
1077#define VRDE_QP_NUMBER_MONITORS (3) /* 32 bit. Number of monitors in the VM. */
1078#define VRDE_QP_NETWORK_PORT_RANGE (4) /* UTF8 string. List of ports. The server must bind to one of
1079 * free ports from the list. Example: "3000,3010-3012,4000",
1080 * which tells the server to bind to either of ports:
1081 * 3000, 3010, 3011, 3012, 4000.
1082 */
1083#ifdef VBOX_WITH_VRDP_VIDEO_CHANNEL
1084#define VRDE_QP_VIDEO_CHANNEL (5)
1085#define VRDE_QP_VIDEO_CHANNEL_QUALITY (6)
1086#define VRDE_QP_VIDEO_CHANNEL_SUNFLSH (7)
1087#endif /* VBOX_WITH_VRDP_VIDEO_CHANNEL */
1088#define VRDE_QP_FEATURE (8) /* VRDEFEATURE structure. Generic interface to query named VRDE properties. */
1089
1090#define VRDE_SP_BASE 0x1000
1091#define VRDE_SP_NETWORK_BIND_PORT (VRDE_SP_BASE + 1) /* 32 bit. The port number actually used by the server.
1092 * If VRDECreateServer fails, it should set the port to 0.
1093 * If VRDECreateServer succeeds, then the port must be set
1094 * in VRDEEnableConnections to the actually used value.
1095 * VRDEDestroy must set the port to 0xFFFFFFFF.
1096 */
1097
1098#pragma pack(1)
1099/* VRDE_QP_FEATURE data. */
1100typedef struct _VRDEFEATURE
1101{
1102 uint32_t u32ClientId;
1103 char achInfo[1]; /* UTF8 property input name and output value. */
1104} VRDEFEATURE;
1105
1106/* A framebuffer description. */
1107typedef struct _VRDEFRAMEBUFFERINFO
1108{
1109 const uint8_t *pu8Bits;
1110 int xOrigin;
1111 int yOrigin;
1112 unsigned cWidth;
1113 unsigned cHeight;
1114 unsigned cBitsPerPixel;
1115 unsigned cbLine;
1116} VRDEFRAMEBUFFERINFO;
1117
1118#define VRDE_INPUT_SCANCODE 0
1119#define VRDE_INPUT_POINT 1
1120#define VRDE_INPUT_CAD 2
1121#define VRDE_INPUT_RESET 3
1122#define VRDE_INPUT_SYNCH 4
1123
1124typedef struct _VRDEINPUTSCANCODE
1125{
1126 unsigned uScancode;
1127} VRDEINPUTSCANCODE;
1128
1129#define VRDE_INPUT_POINT_BUTTON1 0x01
1130#define VRDE_INPUT_POINT_BUTTON2 0x02
1131#define VRDE_INPUT_POINT_BUTTON3 0x04
1132#define VRDE_INPUT_POINT_WHEEL_UP 0x08
1133#define VRDE_INPUT_POINT_WHEEL_DOWN 0x10
1134
1135typedef struct _VRDEINPUTPOINT
1136{
1137 int x;
1138 int y;
1139 unsigned uButtons;
1140} VRDEINPUTPOINT;
1141
1142#define VRDE_INPUT_SYNCH_SCROLL 0x01
1143#define VRDE_INPUT_SYNCH_NUMLOCK 0x02
1144#define VRDE_INPUT_SYNCH_CAPITAL 0x04
1145
1146typedef struct _VRDEINPUTSYNCH
1147{
1148 unsigned uLockStatus;
1149} VRDEINPUTSYNCH;
1150#pragma pack()
1151
1152/** The VRDE server callbacks. Interface version 1. */
1153typedef struct _VRDECALLBACKS_1
1154{
1155 /** The header. */
1156 VRDEINTERFACEHDR header;
1157
1158 /**
1159 * Query or set various information, on how the VRDE server operates, from or to the application.
1160 *
1161 *
1162 * @param pvCallback The callback specific pointer.
1163 * @param index VRDE_[Q|S]P_* identifier of information to be returned or set.
1164 * @param pvBuffer Address of memory buffer to which the information must be written or read.
1165 * @param cbBuffer Size of the memory buffer in bytes.
1166 * @param pcbOut Size in bytes of returned information value.
1167 *
1168 * @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value.
1169 */
1170 DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1171 uint32_t index,
1172 void *pvBuffer,
1173 uint32_t cbBuffer,
1174 uint32_t *pcbOut));
1175
1176 /* A client is logging in, the application must decide whether
1177 * to let to connect the client. The server will drop the connection,
1178 * when an error code is returned by the callback.
1179 *
1180 * @param pvCallback The callback specific pointer.
1181 * @param u32ClientId An unique client identifier generated by the server.
1182 * @param pszUser The username.
1183 * @param pszPassword The password.
1184 * @param pszDomain The domain.
1185 *
1186 * @return IPRT status code.
1187 */
1188 DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1189 uint32_t u32ClientId,
1190 const char *pszUser,
1191 const char *pszPassword,
1192 const char *pszDomain));
1193
1194 /* The client has been successfully connected. That is logon was successful and the
1195 * remote desktop protocol connection completely established.
1196 *
1197 * @param pvCallback The callback specific pointer.
1198 * @param u32ClientId An unique client identifier generated by the server.
1199 */
1200 DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1201 uint32_t u32ClientId));
1202
1203 /* The client has been disconnected.
1204 *
1205 * @param pvCallback The callback specific pointer.
1206 * @param u32ClientId An unique client identifier generated by the server.
1207 * @param fu32Intercepted What was intercepted by the client (VRDE_CLIENT_INTERCEPT_*).
1208 */
1209 DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1210 uint32_t u32ClientId,
1211 uint32_t fu32Intercepted));
1212 /* The client supports one of RDP channels.
1213 *
1214 * @param pvCallback The callback specific pointer.
1215 * @param u32ClientId An unique client identifier generated by the server.
1216 * @param fu32Intercept What the client wants to intercept. One of VRDE_CLIENT_INTERCEPT_* flags.
1217 * @param ppvIntercept The value to be passed to the channel specific callback.
1218 *
1219 * @return IPRT status code.
1220 */
1221 DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1222 uint32_t u32ClientId,
1223 uint32_t fu32Intercept,
1224 void **ppvIntercept));
1225
1226 /**
1227 * Called by the server when a reply is received from a client.
1228 *
1229 * @param pvCallback The callback specific pointer.
1230 * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_USB.
1231 * @param u32ClientId Identifies the client that sent the reply.
1232 * @param u8Code The operation code VRDE_USB_REQ_*.
1233 * @param pvRet Points to data received from the client.
1234 * @param cbRet Size of the data in bytes.
1235 *
1236 * @return IPRT status code.
1237 */
1238 DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1239 void *pvIntercept,
1240 uint32_t u32ClientId,
1241 uint8_t u8Code,
1242 const void *pvRet,
1243 uint32_t cbRet));
1244
1245 /**
1246 * Called by the server when (VRDE_CLIPBOARD_FUNCTION_*):
1247 * - (0) client announces available clipboard formats;
1248 * - (1) client requests clipboard data.
1249 *
1250 * @param pvCallback The callback specific pointer.
1251 * @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_CLIPBOARD.
1252 * @param u32ClientId Identifies the RDP client that sent the reply.
1253 * @param u32Function The cause of the callback.
1254 * @param u32Format Bitmask of reported formats or the format of received data.
1255 * @param pvData Reserved.
1256 * @param cbData Reserved.
1257 *
1258 * @return IPRT status code.
1259 */
1260 DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1261 void *pvIntercept,
1262 uint32_t u32ClientId,
1263 uint32_t u32Function,
1264 uint32_t u32Format,
1265 const void *pvData,
1266 uint32_t cbData));
1267
1268 /* The framebuffer information is queried.
1269 *
1270 * @param pvCallback The callback specific pointer.
1271 * @param uScreenId The framebuffer index.
1272 * @param pInfo The information structure to ber filled.
1273 *
1274 * @return Whether the framebuffer is available.
1275 */
1276 DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1277 unsigned uScreenId,
1278 VRDEFRAMEBUFFERINFO *pInfo));
1279
1280 /* Request the exclusive access to the framebuffer bitmap.
1281 * Currently not used because VirtualBox makes sure that the framebuffer is available
1282 * when VRDEUpdate is called.
1283 *
1284 * @param pvCallback The callback specific pointer.
1285 * @param uScreenId The framebuffer index.
1286 */
1287 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1288 unsigned uScreenId));
1289
1290 /* Release the exclusive access to the framebuffer bitmap.
1291 * Currently not used because VirtualBox makes sure that the framebuffer is available
1292 * when VRDEUpdate is called.
1293 *
1294 * @param pvCallback The callback specific pointer.
1295 * @param uScreenId The framebuffer index.
1296 */
1297 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1298 unsigned uScreenId));
1299
1300 /* Input from the client.
1301 *
1302 * @param pvCallback The callback specific pointer.
1303 * @param pvInput The input information.
1304 * @param cbInput The size of the input information.
1305 */
1306 DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1307 int type,
1308 const void *pvInput,
1309 unsigned cbInput));
1310
1311 /* Video mode hint from the client.
1312 *
1313 * @param pvCallback The callback specific pointer.
1314 * @param cWidth Requested width.
1315 * @param cHeight Requested height.
1316 * @param cBitsPerPixel Requested color depth.
1317 * @param uScreenId The framebuffer index.
1318 */
1319 DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1320 unsigned cWidth,
1321 unsigned cHeight,
1322 unsigned cBitsPerPixel,
1323 unsigned uScreenId));
1324
1325} VRDECALLBACKS_1;
1326
1327/* Callbacks are the same for the version 1 and version 2 interfaces. */
1328typedef VRDECALLBACKS_1 VRDECALLBACKS_2;
1329
1330/** The VRDE server callbacks. Interface version 3. */
1331typedef struct _VRDECALLBACKS_3
1332{
1333 /* The header. */
1334 VRDEINTERFACEHDR header;
1335
1336 /*
1337 * Same as in version 1 and 2. See comment in VRDECALLBACKS_1.
1338 */
1339 DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1340 uint32_t index,
1341 void *pvBuffer,
1342 uint32_t cbBuffer,
1343 uint32_t *pcbOut));
1344
1345 DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1346 uint32_t u32ClientId,
1347 const char *pszUser,
1348 const char *pszPassword,
1349 const char *pszDomain));
1350
1351 DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1352 uint32_t u32ClientId));
1353
1354 DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1355 uint32_t u32ClientId,
1356 uint32_t fu32Intercepted));
1357 DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1358 uint32_t u32ClientId,
1359 uint32_t fu32Intercept,
1360 void **ppvIntercept));
1361
1362 DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1363 void *pvIntercept,
1364 uint32_t u32ClientId,
1365 uint8_t u8Code,
1366 const void *pvRet,
1367 uint32_t cbRet));
1368
1369 DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1370 void *pvIntercept,
1371 uint32_t u32ClientId,
1372 uint32_t u32Function,
1373 uint32_t u32Format,
1374 const void *pvData,
1375 uint32_t cbData));
1376
1377 DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1378 unsigned uScreenId,
1379 VRDEFRAMEBUFFERINFO *pInfo));
1380
1381 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1382 unsigned uScreenId));
1383
1384 DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1385 unsigned uScreenId));
1386
1387 DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1388 int type,
1389 const void *pvInput,
1390 unsigned cbInput));
1391
1392 DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1393 unsigned cWidth,
1394 unsigned cHeight,
1395 unsigned cBitsPerPixel,
1396 unsigned uScreenId));
1397
1398 /*
1399 * New for version 3.
1400 */
1401
1402 /**
1403 * Called by the server when something happens with audio input.
1404 *
1405 * @param pvCallback The callback specific pointer.
1406 * @param pvCtx The value passed in VRDEAudioInOpen.
1407 * @param u32ClientId Identifies the client that sent the reply.
1408 * @param u32Event The event code VRDE_AUDIOIN_*.
1409 * @param pvData Points to data received from the client.
1410 * @param cbData Size of the data in bytes.
1411 */
1412 DECLR3CALLBACKMEMBER(void, VRDECallbackAudioIn,(void *pvCallback,
1413 void *pvCtx,
1414 uint32_t u32ClientId,
1415 uint32_t u32Event,
1416 const void *pvData,
1417 uint32_t cbData));
1418} VRDECALLBACKS_3;
1419
1420/** The VRDE server entry points. Interface version 4.
1421 * New entry point VRDEGetInterface has been added relative to version 3.
1422 */
1423typedef struct _VRDEENTRYPOINTS_4
1424{
1425 /* The header. */
1426 VRDEINTERFACEHDR header;
1427
1428 /*
1429 * Same as version 3. See comment in VRDEENTRYPOINTS_3.
1430 */
1431
1432 DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
1433 DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer, bool fEnable));
1434 DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer, uint32_t u32ClientId, bool fReconnect));
1435 DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
1436 DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer, unsigned uScreenId, void *pvUpdate,
1437 uint32_t cbUpdate));
1438 DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer, const VRDECOLORPOINTER *pPointer));
1439 DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
1440 DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer, const void *pvSamples, uint32_t cSamples,
1441 VRDEAUDIOFORMAT format));
1442 DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer, uint16_t u16Left, uint16_t u16Right));
1443 DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer, uint32_t u32ClientId, void *pvParm,
1444 uint32_t cbParm));
1445 DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer, uint32_t u32Function, uint32_t u32Format,
1446 void *pvData, uint32_t cbData, uint32_t *pcbActualRead));
1447 DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer, uint32_t index, void *pvBuffer, uint32_t cbBuffer,
1448 uint32_t *pcbOut));
1449 DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer, uint32_t u32ClientId, const char *pszServer,
1450 const char *pszUser, const char *pszDomain, const char *pszPassword,
1451 uint32_t u32SessionId, const char *pszCookie));
1452 DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer, void *pvCtx, uint32_t u32ClientId,
1453 VRDEAUDIOFORMAT audioFormat, uint32_t u32SamplesPerBlock));
1454 DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer, uint32_t u32ClientId));
1455
1456 /**
1457 * Generic interface query. An interface is a set of entry points and callbacks.
1458 * It is not a reference counted interface.
1459 *
1460 * @param hServer Handle of VRDE server instance.
1461 * @param pszId String identifier of the interface, like uuid.
1462 * @param pInterface The interface structure to be initialized by the VRDE server.
1463 * Only VRDEINTERFACEHDR is initialized by the caller.
1464 * @param pCallbacks Callbacks required by the interface. The server makes a local copy.
1465 * VRDEINTERFACEHDR version must correspond to the requested interface version.
1466 * @param pvContext The context to be used in callbacks.
1467 */
1468
1469 DECLR3CALLBACKMEMBER(int, VRDEGetInterface, (HVRDESERVER hServer,
1470 const char *pszId,
1471 VRDEINTERFACEHDR *pInterface,
1472 const VRDEINTERFACEHDR *pCallbacks,
1473 void *pvContext));
1474} VRDEENTRYPOINTS_4;
1475
1476/* Callbacks are the same for the version 3 and version 4 interfaces. */
1477typedef VRDECALLBACKS_3 VRDECALLBACKS_4;
1478
1479/**
1480 * Create a new VRDE server instance. The instance is fully functional but refuses
1481 * client connections until the entry point VRDEEnableConnections is called by the application.
1482 *
1483 * The caller prepares the VRDECALLBACKS_* structure. The header.u64Version field of the
1484 * structure must be initialized with the version of the interface to use.
1485 * The server will return pointer to VRDEENTRYPOINTS_* table in *ppEntryPoints
1486 * to match the requested interface.
1487 * That is if pCallbacks->header.u64Version == VRDE_INTERFACE_VERSION_1, then the server
1488 * expects pCallbacks to point to VRDECALLBACKS_1 and will return a pointer to VRDEENTRYPOINTS_1.
1489 *
1490 * @param pCallback Pointer to the application callbacks which let the server to fetch
1491 * the configuration data and to access the desktop.
1492 * @param pvCallback The callback specific pointer to be passed back to the application.
1493 * @param ppEntryPoints Where to store the pointer to the VRDE entry points structure.
1494 * @param phServer Pointer to the created server instance handle.
1495 *
1496 * @return IPRT status code.
1497 */
1498DECLEXPORT(int) VRDECreateServer (const VRDEINTERFACEHDR *pCallbacks,
1499 void *pvCallback,
1500 VRDEINTERFACEHDR **ppEntryPoints,
1501 HVRDESERVER *phServer);
1502
1503typedef DECLCALLBACK(int) FNVRDECREATESERVER (const VRDEINTERFACEHDR *pCallbacks,
1504 void *pvCallback,
1505 VRDEINTERFACEHDR **ppEntryPoints,
1506 HVRDESERVER *phServer);
1507typedef FNVRDECREATESERVER *PFNVRDECREATESERVER;
1508
1509/**
1510 * List of names of the VRDE properties, which are recognized by the VRDE.
1511 *
1512 * For example VRDESupportedProperties should return gapszProperties declared as:
1513 *
1514 * static const char * const gapszProperties[] =
1515 * {
1516 * "TCP/Ports",
1517 * "TCP/Address",
1518 * NULL
1519 * };
1520 *
1521 * @returns pointer to array of pointers to name strings (UTF8).
1522 */
1523DECLEXPORT(const char * const *) VRDESupportedProperties (void);
1524
1525typedef DECLCALLBACK(const char * const *) FNVRDESUPPORTEDPROPERTIES (void);
1526typedef FNVRDESUPPORTEDPROPERTIES *PFNVRDESUPPORTEDPROPERTIES;
1527
1528RT_C_DECLS_END
1529
1530/** @} */
1531
1532#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