2
* VBox Remote Desktop Extension (VRDE) - Public APIs.
6
* Copyright (C) 2006-2010 Oracle Corporation
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.
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.
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.
26
#ifndef ___VBox_RemoteDesktop_VRDE_h
27
#define ___VBox_RemoteDesktop_VRDE_h
29
#include <iprt/cdefs.h>
30
#include <iprt/types.h>
32
/** @defgroup grp_vrdp VRDE
33
* VirtualBox Remote Desktop Extension (VRDE) interface that lets to use
34
* a Remote Desktop server like RDP.
40
/* Forward declaration of the VRDE server instance handle. */
43
typedef class VRDEServerType *HVRDESERVER;
46
typedef struct VRDEServerType *HVRDESERVER;
47
#endif /* __cplusplus */
49
/* Callback based VRDE server interface declarations. */
51
/** The color mouse pointer information. */
52
typedef struct _VRDECOLORPOINTER
60
/* The 1BPP mask and the 24BPP bitmap follow. */
63
/** Audio format information packed in a 32 bit value. */
64
typedef uint32_t VRDEAUDIOFORMAT;
66
/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
67
#define VRDE_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
69
/** Decode frequency. */
70
#define VRDE_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
71
/** Decode number of channels. */
72
#define VRDE_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
73
/** Decode number signess. */
74
#define VRDE_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
75
/** Decode number of bits per sample. */
76
#define VRDE_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
77
/** Decode number of bytes per sample. */
78
#define VRDE_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDE_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
85
/* Audio input notifications. */
86
#define VRDE_AUDIOIN_BEGIN 1
87
#define VRDE_AUDIOIN_DATA 2
88
#define VRDE_AUDIOIN_END 3
90
typedef struct VRDEAUDIOINBEGIN
92
VRDEAUDIOFORMAT fmt; /* Actual format of data, which will be sent in VRDE_AUDIOIN_DATA events. */
97
* Remote USB protocol.
100
/* The initial version 1. */
101
#define VRDE_USB_VERSION_1 (1)
102
/* Version 2: look for VRDE_USB_VERSION_2 comments in the code. */
103
#define VRDE_USB_VERSION_2 (2)
104
/* Version 3: look for VRDE_USB_VERSION_3 comments in the code. */
105
#define VRDE_USB_VERSION_3 (3)
107
/* The default VRDE server version of Remote USB Protocol. */
108
#define VRDE_USB_VERSION VRDE_USB_VERSION_3
111
/** USB backend operations. */
112
#define VRDE_USB_REQ_OPEN (0)
113
#define VRDE_USB_REQ_CLOSE (1)
114
#define VRDE_USB_REQ_RESET (2)
115
#define VRDE_USB_REQ_SET_CONFIG (3)
116
#define VRDE_USB_REQ_CLAIM_INTERFACE (4)
117
#define VRDE_USB_REQ_RELEASE_INTERFACE (5)
118
#define VRDE_USB_REQ_INTERFACE_SETTING (6)
119
#define VRDE_USB_REQ_QUEUE_URB (7)
120
#define VRDE_USB_REQ_REAP_URB (8)
121
#define VRDE_USB_REQ_CLEAR_HALTED_EP (9)
122
#define VRDE_USB_REQ_CANCEL_URB (10)
124
/** USB service operations. */
125
#define VRDE_USB_REQ_DEVICE_LIST (11)
126
#define VRDE_USB_REQ_NEGOTIATE (12)
128
/** An operation completion status is a byte. */
129
typedef uint8_t VRDEUSBSTATUS;
131
/** USB device identifier is an 32 bit value. */
132
typedef uint32_t VRDEUSBDEVID;
135
#define VRDE_USB_STATUS_SUCCESS ((VRDEUSBSTATUS)0)
136
#define VRDE_USB_STATUS_ACCESS_DENIED ((VRDEUSBSTATUS)1)
137
#define VRDE_USB_STATUS_DEVICE_REMOVED ((VRDEUSBSTATUS)2)
140
* Data structures to use with VRDEUSBRequest.
141
* The *RET* structures always represent the layout of VRDE data.
142
* The *PARM* structures normally the same as VRDE layout.
143
* However the VRDE_USB_REQ_QUEUE_URB_PARM has a pointer to
144
* URB data in place where actual data will be in VRDE layout.
146
* Since replies (*RET*) are asynchronous, the 'success'
147
* replies are not required for operations which return
148
* only the status code (VRDEUSBREQRETHDR only):
151
* VRDE_USB_REQ_SET_CONFIG
152
* VRDE_USB_REQ_CLAIM_INTERFACE
153
* VRDE_USB_REQ_RELEASE_INTERFACE
154
* VRDE_USB_REQ_INTERFACE_SETTING
155
* VRDE_USB_REQ_CLEAR_HALTED_EP
159
/* VRDE layout has no alignments. */
161
/* Common header for all VRDE USB packets. After the reply hdr follows *PARM* or *RET* data. */
162
typedef struct _VRDEUSBPKTHDR
164
/* Total length of the reply NOT including the 'length' field. */
166
/* The operation code for which the reply was sent by the client. */
170
/* Common header for all return structures. */
171
typedef struct _VRDEUSBREQRETHDR
174
VRDEUSBSTATUS status;
182
typedef struct _VRDE_USB_REQ_OPEN_PARM
186
} VRDE_USB_REQ_OPEN_PARM;
188
typedef struct _VRDE_USB_REQ_OPEN_RET
190
VRDEUSBREQRETHDR hdr;
191
} VRDE_USB_REQ_OPEN_RET;
194
/* VRDE_USB_REQ_CLOSE
196
typedef struct _VRDE_USB_REQ_CLOSE_PARM
200
} VRDE_USB_REQ_CLOSE_PARM;
202
/* The close request has no returned data. */
205
/* VRDE_USB_REQ_RESET
207
typedef struct _VRDE_USB_REQ_RESET_PARM
211
} VRDE_USB_REQ_RESET_PARM;
213
typedef struct _VRDE_USB_REQ_RESET_RET
215
VRDEUSBREQRETHDR hdr;
216
} VRDE_USB_REQ_RESET_RET;
219
/* VRDE_USB_REQ_SET_CONFIG
221
typedef struct _VRDE_USB_REQ_SET_CONFIG_PARM
225
uint8_t configuration;
226
} VRDE_USB_REQ_SET_CONFIG_PARM;
228
typedef struct _VRDE_USB_REQ_SET_CONFIG_RET
230
VRDEUSBREQRETHDR hdr;
231
} VRDE_USB_REQ_SET_CONFIG_RET;
234
/* VRDE_USB_REQ_CLAIM_INTERFACE
236
typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_PARM
241
} VRDE_USB_REQ_CLAIM_INTERFACE_PARM;
243
typedef struct _VRDE_USB_REQ_CLAIM_INTERFACE_RET
245
VRDEUSBREQRETHDR hdr;
246
} VRDE_USB_REQ_CLAIM_INTERFACE_RET;
249
/* VRDE_USB_REQ_RELEASE_INTERFACE
251
typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_PARM
256
} VRDE_USB_REQ_RELEASE_INTERFACE_PARM;
258
typedef struct _VRDE_USB_REQ_RELEASE_INTERFACE_RET
260
VRDEUSBREQRETHDR hdr;
261
} VRDE_USB_REQ_RELEASE_INTERFACE_RET;
264
/* VRDE_USB_REQ_INTERFACE_SETTING
266
typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_PARM
272
} VRDE_USB_REQ_INTERFACE_SETTING_PARM;
274
typedef struct _VRDE_USB_REQ_INTERFACE_SETTING_RET
276
VRDEUSBREQRETHDR hdr;
277
} VRDE_USB_REQ_INTERFACE_SETTING_RET;
280
/* VRDE_USB_REQ_QUEUE_URB
283
#define VRDE_USB_TRANSFER_TYPE_CTRL (0)
284
#define VRDE_USB_TRANSFER_TYPE_ISOC (1)
285
#define VRDE_USB_TRANSFER_TYPE_BULK (2)
286
#define VRDE_USB_TRANSFER_TYPE_INTR (3)
287
#define VRDE_USB_TRANSFER_TYPE_MSG (4)
289
#define VRDE_USB_DIRECTION_SETUP (0)
290
#define VRDE_USB_DIRECTION_IN (1)
291
#define VRDE_USB_DIRECTION_OUT (2)
293
typedef struct _VRDE_USB_REQ_QUEUE_URB_PARM
297
uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
301
uint32_t urblen; /* Length of the URB. */
302
uint32_t datalen; /* Length of the data. */
303
void *data; /* In RDP layout the data follow. */
304
} VRDE_USB_REQ_QUEUE_URB_PARM;
306
/* The queue URB has no explicit return. The reap URB reply will be
307
* eventually the indirect result.
311
/* VRDE_USB_REQ_REAP_URB
312
* Notificationg from server to client that server expects an URB
314
* Only sent if negotiated URB return method is polling.
315
* Normally, the client will send URBs back as soon as they are ready.
317
typedef struct _VRDE_USB_REQ_REAP_URB_PARM
320
} VRDE_USB_REQ_REAP_URB_PARM;
323
#define VRDE_USB_XFER_OK (0)
324
#define VRDE_USB_XFER_STALL (1)
325
#define VRDE_USB_XFER_DNR (2)
326
#define VRDE_USB_XFER_CRC (3)
327
/* VRDE_USB_VERSION_2: New error codes. */
328
#define VRDE_USB_XFER_BS (4)
329
#define VRDE_USB_XFER_DTM (5)
330
#define VRDE_USB_XFER_PCF (6)
331
#define VRDE_USB_XFER_UPID (7)
332
#define VRDE_USB_XFER_DO (8)
333
#define VRDE_USB_XFER_DU (9)
334
#define VRDE_USB_XFER_BO (10)
335
#define VRDE_USB_XFER_BU (11)
336
#define VRDE_USB_XFER_ERR (12) /* VBox protocol error. */
338
#define VRDE_USB_REAP_FLAG_CONTINUED (0x0)
339
#define VRDE_USB_REAP_FLAG_LAST (0x1)
340
/* VRDE_USB_VERSION_3: Fragmented URBs. */
341
#define VRDE_USB_REAP_FLAG_FRAGMENT (0x2)
343
#define VRDE_USB_REAP_VALID_FLAGS (VRDE_USB_REAP_FLAG_LAST)
344
/* VRDE_USB_VERSION_3: Fragmented URBs. */
345
#define VRDE_USB_REAP_VALID_FLAGS_3 (VRDE_USB_REAP_FLAG_LAST | VRDE_USB_REAP_FLAG_FRAGMENT)
347
typedef struct _VRDEUSBREQREAPURBBODY
349
VRDEUSBDEVID id; /* From which device the URB arrives. */
350
uint8_t flags; /* VRDE_USB_REAP_FLAG_* */
351
uint8_t error; /* VRDE_USB_XFER_* */
352
uint32_t handle; /* Handle of returned URB. Not 0. */
353
uint32_t len; /* Length of data actually transferred. */
354
/* 'len' bytes of data follow if direction of this URB was VRDE_USB_DIRECTION_IN. */
355
} VRDEUSBREQREAPURBBODY;
357
typedef struct _VRDE_USB_REQ_REAP_URB_RET
359
/* The REAP URB has no header, only completed URBs are returned. */
360
VRDEUSBREQREAPURBBODY body;
361
/* Another body may follow, depending on flags. */
362
} VRDE_USB_REQ_REAP_URB_RET;
365
/* VRDE_USB_REQ_CLEAR_HALTED_EP
367
typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_PARM
372
} VRDE_USB_REQ_CLEAR_HALTED_EP_PARM;
374
typedef struct _VRDE_USB_REQ_CLEAR_HALTED_EP_RET
376
VRDEUSBREQRETHDR hdr;
377
} VRDE_USB_REQ_CLEAR_HALTED_EP_RET;
380
/* VRDE_USB_REQ_CANCEL_URB
382
typedef struct _VRDE_USB_REQ_CANCEL_URB_PARM
387
} VRDE_USB_REQ_CANCEL_URB_PARM;
389
/* The cancel URB request has no return. */
392
/* VRDE_USB_REQ_DEVICE_LIST
394
* Server polls USB devices on client by sending this request
395
* periodically. Client sends back a list of all devices
396
* connected to it. Each device is assigned with an identifier,
397
* that is used to distinguish the particular device.
399
typedef struct _VRDE_USB_REQ_DEVICE_LIST_PARM
402
} VRDE_USB_REQ_DEVICE_LIST_PARM;
404
/* Data is a list of the following variable length structures. */
405
typedef struct _VRDEUSBDEVICEDESC
407
/* Offset of the next structure. 0 if last. */
410
/* Identifier of the device assigned by client. */
413
/** USB version number. */
416
uint8_t bDeviceClass;
417
/** Device subclass. */
418
uint8_t bDeviceSubClass;
419
/** Device protocol */
420
uint8_t bDeviceProtocol;
425
/** Revision, integer part. */
427
/** Manufacturer string. */
428
uint16_t oManufacturer;
429
/** Product string. */
431
/** Serial number string. */
432
uint16_t oSerialNumber;
433
/** Physical USB port the device is connected to. */
438
typedef struct _VRDE_USB_REQ_DEVICE_LIST_RET
440
VRDEUSBDEVICEDESC body;
441
/* Other devices may follow.
442
* The list ends with (uint16_t)0,
443
* which means that an empty list consists of 2 zero bytes.
445
} VRDE_USB_REQ_DEVICE_LIST_RET;
447
typedef struct _VRDEUSBREQNEGOTIATEPARM
451
/* Remote USB Protocol version. */
452
/* VRDE_USB_VERSION_3: the 32 bit field is splitted to 16 bit version and 16 bit flags.
453
* Version 1 and 2 servers therefore have 'flags' == 0.
454
* Version 3+ servers can send some capabilities in this field, this way it is possible to add
455
* a new capability without increasing the protocol version.
460
} VRDEUSBREQNEGOTIATEPARM;
462
#define VRDE_USB_CAPS_FLAG_ASYNC (0x0)
463
#define VRDE_USB_CAPS_FLAG_POLL (0x1)
464
/* VRDE_USB_VERSION_2: New flag. */
465
#define VRDE_USB_CAPS2_FLAG_VERSION (0x2) /* The client is negotiating the protocol version. */
468
#define VRDE_USB_CAPS_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL)
469
/* VRDE_USB_VERSION_2: A set of valid flags. */
470
#define VRDE_USB_CAPS2_VALID_FLAGS (VRDE_USB_CAPS_FLAG_POLL | VRDE_USB_CAPS2_FLAG_VERSION)
472
typedef struct _VRDEUSBREQNEGOTIATERET
475
} VRDEUSBREQNEGOTIATERET;
477
typedef struct _VRDEUSBREQNEGOTIATERET_2
480
uint32_t u32Version; /* This field presents only if the VRDE_USB_CAPS2_FLAG_VERSION flag is set. */
481
} VRDEUSBREQNEGOTIATERET_2;
484
#define VRDE_CLIPBOARD_FORMAT_NULL (0x0)
485
#define VRDE_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
486
#define VRDE_CLIPBOARD_FORMAT_BITMAP (0x2)
487
#define VRDE_CLIPBOARD_FORMAT_HTML (0x4)
489
#define VRDE_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
490
#define VRDE_CLIPBOARD_FUNCTION_DATA_READ (1)
491
#define VRDE_CLIPBOARD_FUNCTION_DATA_WRITE (2)
494
/** Indexes of information values. */
496
/** Whether a client is connected at the moment.
499
#define VRDE_QI_ACTIVE (0)
501
/** How many times a client connected up to current moment.
504
#define VRDE_QI_NUMBER_OF_CLIENTS (1)
506
/** When last connection was established.
507
* int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
509
#define VRDE_QI_BEGIN_TIME (2)
511
/** When last connection was terminated or current time if connection still active.
512
* int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
514
#define VRDE_QI_END_TIME (3)
516
/** How many bytes were sent in last (current) connection.
519
#define VRDE_QI_BYTES_SENT (4)
521
/** How many bytes were sent in all connections.
524
#define VRDE_QI_BYTES_SENT_TOTAL (5)
526
/** How many bytes were received in last (current) connection.
529
#define VRDE_QI_BYTES_RECEIVED (6)
531
/** How many bytes were received in all connections.
534
#define VRDE_QI_BYTES_RECEIVED_TOTAL (7)
536
/** Login user name supplied by the client.
537
* UTF8 nul terminated string.
539
#define VRDE_QI_USER (8)
541
/** Login domain supplied by the client.
542
* UTF8 nul terminated string.
544
#define VRDE_QI_DOMAIN (9)
546
/** The client name supplied by the client.
547
* UTF8 nul terminated string.
549
#define VRDE_QI_CLIENT_NAME (10)
551
/** IP address of the client.
552
* UTF8 nul terminated string.
554
#define VRDE_QI_CLIENT_IP (11)
556
/** The client software version number.
559
#define VRDE_QI_CLIENT_VERSION (12)
561
/** Public key exchange method used when connection was established.
562
* Values: 0 - RDP4 public key exchange scheme.
563
* 1 - X509 sertificates were sent to client.
566
#define VRDE_QI_ENCRYPTION_STYLE (13)
568
/** TCP port where the server listens.
569
* Values: 0 - VRDE server failed to start.
573
#define VRDE_QI_PORT (14)
576
/** Hints what has been intercepted by the application. */
577
#define VRDE_CLIENT_INTERCEPT_AUDIO (0x1)
578
#define VRDE_CLIENT_INTERCEPT_USB (0x2)
579
#define VRDE_CLIENT_INTERCEPT_CLIPBOARD (0x4)
580
#define VRDE_CLIENT_INTERCEPT_AUDIO_INPUT (0x8)
583
/** The version of the VRDE server interface. */
584
#define VRDE_INTERFACE_VERSION_1 (1)
585
#define VRDE_INTERFACE_VERSION_2 (2)
586
#define VRDE_INTERFACE_VERSION_3 (3)
588
/** The header that does not change when the interface changes. */
589
typedef struct _VRDEINTERFACEHDR
591
/** The version of the interface. */
594
/** The size of the structure. */
599
/** The VRDE server entry points. Interface version 1. */
600
typedef struct _VRDEENTRYPOINTS_1
603
VRDEINTERFACEHDR header;
605
/** Destroy the server instance.
607
* @param hServer The server instance handle.
609
* @return IPRT status code.
611
DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
613
/** The server should start to accept clients connections.
615
* @param hServer The server instance handle.
616
* @param fEnable Whether to enable or disable client connections.
617
* When is false, all existing clients are disconnected.
619
* @return IPRT status code.
621
DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
624
/** The server should disconnect the client.
626
* @param hServer The server instance handle.
627
* @param u32ClientId The client identifier.
628
* @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
629
* client before disconnecting.
631
* @return IPRT status code.
633
DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
634
uint32_t u32ClientId,
638
* Inform the server that the display was resized.
639
* The server will query information about display
640
* from the application via callbacks.
642
* @param hServer Handle of VRDE server instance.
644
DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
649
* @param hServer Handle of VRDE server instance.
650
* @param uScreenId The screen index.
651
* @param pvUpdate Pointer to VBoxGuest.h::VRDEORDERHDR structure with extra data.
652
* @param cbUpdate Size of the update data.
654
DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
660
* Set the mouse pointer shape.
662
* @param hServer Handle of VRDE server instance.
663
* @param pPointer The pointer shape information.
665
DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
666
const VRDECOLORPOINTER *pPointer));
669
* Hide the mouse pointer.
671
* @param hServer Handle of VRDE server instance.
673
DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
676
* Queues the samples to be sent to clients.
678
* @param hServer Handle of VRDE server instance.
679
* @param pvSamples Address of samples to be sent.
680
* @param cSamples Number of samples.
681
* @param format Encoded audio format for these samples.
683
* @note Initialized to NULL when the application audio callbacks are NULL.
685
DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
686
const void *pvSamples,
688
VRDEAUDIOFORMAT format));
691
* Sets the sound volume on clients.
693
* @param hServer Handle of VRDE server instance.
694
* @param left 0..0xFFFF volume level for left channel.
695
* @param right 0..0xFFFF volume level for right channel.
697
* @note Initialized to NULL when the application audio callbacks are NULL.
699
DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
704
* Sends a USB request.
706
* @param hServer Handle of VRDE server instance.
707
* @param u32ClientId An identifier that allows the server to find the corresponding client.
708
* The identifier is always passed by the server as a parameter
709
* of the FNVRDEUSBCALLBACK. Note that the value is the same as
710
* in the VRDESERVERCALLBACK functions.
711
* @param pvParm Function specific parameters buffer.
712
* @param cbParm Size of the buffer.
714
* @note Initialized to NULL when the application USB callbacks are NULL.
716
DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
717
uint32_t u32ClientId,
722
* Called by the application when (VRDE_CLIPBOARD_FUNCTION_*):
723
* - (0) guest announces available clipboard formats;
724
* - (1) guest requests clipboard data;
725
* - (2) guest responds to the client's request for clipboard data.
727
* @param hServer The VRDE server handle.
728
* @param u32Function The cause of the call.
729
* @param u32Format Bitmask of announced formats or the format of data.
730
* @param pvData Points to: (1) buffer to be filled with clients data;
731
* (2) data from the host.
732
* @param cbData Size of 'pvData' buffer in bytes.
733
* @param pcbActualRead Size of the copied data in bytes.
735
* @note Initialized to NULL when the application clipboard callbacks are NULL.
737
DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
738
uint32_t u32Function,
742
uint32_t *pcbActualRead));
745
* Query various information from the VRDE server.
747
* @param hServer The VRDE server handle.
748
* @param index VRDE_QI_* identifier of information to be returned.
749
* @param pvBuffer Address of memory buffer to which the information must be written.
750
* @param cbBuffer Size of the memory buffer in bytes.
751
* @param pcbOut Size in bytes of returned information value.
753
* @remark The caller must check the *pcbOut. 0 there means no information was returned.
754
* A value greater than cbBuffer means that information is too big to fit in the
755
* buffer, in that case no information was placed to the buffer.
757
DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
764
/** The VRDE server entry points. Interface version 2.
765
* A new entry point VRDERedirect has been added relative to version 1.
767
typedef struct _VRDEENTRYPOINTS_2
770
VRDEINTERFACEHDR header;
772
/** Destroy the server instance.
774
* @param hServer The server instance handle.
776
* @return IPRT status code.
778
DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
780
/** The server should start to accept clients connections.
782
* @param hServer The server instance handle.
783
* @param fEnable Whether to enable or disable client connections.
784
* When is false, all existing clients are disconnected.
786
* @return IPRT status code.
788
DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
791
/** The server should disconnect the client.
793
* @param hServer The server instance handle.
794
* @param u32ClientId The client identifier.
795
* @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
796
* client before disconnecting.
798
* @return IPRT status code.
800
DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
801
uint32_t u32ClientId,
805
* Inform the server that the display was resized.
806
* The server will query information about display
807
* from the application via callbacks.
809
* @param hServer Handle of VRDE server instance.
811
DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
816
* @param hServer Handle of VRDE server instance.
817
* @param uScreenId The screen index.
818
* @param pvUpdate Pointer to VBoxGuest.h::VRDEORDERHDR structure with extra data.
819
* @param cbUpdate Size of the update data.
821
DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
827
* Set the mouse pointer shape.
829
* @param hServer Handle of VRDE server instance.
830
* @param pPointer The pointer shape information.
832
DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
833
const VRDECOLORPOINTER *pPointer));
836
* Hide the mouse pointer.
838
* @param hServer Handle of VRDE server instance.
840
DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
843
* Queues the samples to be sent to clients.
845
* @param hServer Handle of VRDE server instance.
846
* @param pvSamples Address of samples to be sent.
847
* @param cSamples Number of samples.
848
* @param format Encoded audio format for these samples.
850
* @note Initialized to NULL when the application audio callbacks are NULL.
852
DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
853
const void *pvSamples,
855
VRDEAUDIOFORMAT format));
858
* Sets the sound volume on clients.
860
* @param hServer Handle of VRDE server instance.
861
* @param left 0..0xFFFF volume level for left channel.
862
* @param right 0..0xFFFF volume level for right channel.
864
* @note Initialized to NULL when the application audio callbacks are NULL.
866
DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
871
* Sends a USB request.
873
* @param hServer Handle of VRDE server instance.
874
* @param u32ClientId An identifier that allows the server to find the corresponding client.
875
* The identifier is always passed by the server as a parameter
876
* of the FNVRDEUSBCALLBACK. Note that the value is the same as
877
* in the VRDESERVERCALLBACK functions.
878
* @param pvParm Function specific parameters buffer.
879
* @param cbParm Size of the buffer.
881
* @note Initialized to NULL when the application USB callbacks are NULL.
883
DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
884
uint32_t u32ClientId,
889
* Called by the application when (VRDE_CLIPBOARD_FUNCTION_*):
890
* - (0) guest announces available clipboard formats;
891
* - (1) guest requests clipboard data;
892
* - (2) guest responds to the client's request for clipboard data.
894
* @param hServer The VRDE server handle.
895
* @param u32Function The cause of the call.
896
* @param u32Format Bitmask of announced formats or the format of data.
897
* @param pvData Points to: (1) buffer to be filled with clients data;
898
* (2) data from the host.
899
* @param cbData Size of 'pvData' buffer in bytes.
900
* @param pcbActualRead Size of the copied data in bytes.
902
* @note Initialized to NULL when the application clipboard callbacks are NULL.
904
DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
905
uint32_t u32Function,
909
uint32_t *pcbActualRead));
912
* Query various information from the VRDE server.
914
* @param hServer The VRDE server handle.
915
* @param index VRDE_QI_* identifier of information to be returned.
916
* @param pvBuffer Address of memory buffer to which the information must be written.
917
* @param cbBuffer Size of the memory buffer in bytes.
918
* @param pcbOut Size in bytes of returned information value.
920
* @remark The caller must check the *pcbOut. 0 there means no information was returned.
921
* A value greater than cbBuffer means that information is too big to fit in the
922
* buffer, in that case no information was placed to the buffer.
924
DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
931
* The server should redirect the client to the specified server.
933
* @param hServer The server instance handle.
934
* @param u32ClientId The client identifier.
935
* @param pszServer The server to redirect the client to.
936
* @param pszUser The username to use for the redirection.
938
* @param pszDomain The domain. Can be NULL.
939
* @param pszPassword The password. Can be NULL.
940
* @param u32SessionId The ID of the session to redirect to.
941
* @param pszCookie The routing token used by a load balancer to
942
* route the redirection. Can be NULL.
944
DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer,
945
uint32_t u32ClientId,
946
const char *pszServer,
948
const char *pszDomain,
949
const char *pszPassword,
950
uint32_t u32SessionId,
951
const char *pszCookie));
954
/** The VRDE server entry points. Interface version 3.
955
* A new entry point VRDE has been added relative to version 2.
957
typedef struct _VRDEENTRYPOINTS_3
960
VRDEINTERFACEHDR header;
966
DECLR3CALLBACKMEMBER(void, VRDEDestroy,(HVRDESERVER hServer));
968
DECLR3CALLBACKMEMBER(int, VRDEEnableConnections,(HVRDESERVER hServer,
971
DECLR3CALLBACKMEMBER(void, VRDEDisconnect,(HVRDESERVER hServer,
972
uint32_t u32ClientId,
975
DECLR3CALLBACKMEMBER(void, VRDEResize,(HVRDESERVER hServer));
977
DECLR3CALLBACKMEMBER(void, VRDEUpdate,(HVRDESERVER hServer,
982
DECLR3CALLBACKMEMBER(void, VRDEColorPointer,(HVRDESERVER hServer,
983
const VRDECOLORPOINTER *pPointer));
985
DECLR3CALLBACKMEMBER(void, VRDEHidePointer,(HVRDESERVER hServer));
987
DECLR3CALLBACKMEMBER(void, VRDEAudioSamples,(HVRDESERVER hServer,
988
const void *pvSamples,
990
VRDEAUDIOFORMAT format));
992
DECLR3CALLBACKMEMBER(void, VRDEAudioVolume,(HVRDESERVER hServer,
996
DECLR3CALLBACKMEMBER(void, VRDEUSBRequest,(HVRDESERVER hServer,
997
uint32_t u32ClientId,
1001
DECLR3CALLBACKMEMBER(void, VRDEClipboard,(HVRDESERVER hServer,
1002
uint32_t u32Function,
1006
uint32_t *pcbActualRead));
1008
DECLR3CALLBACKMEMBER(void, VRDEQueryInfo,(HVRDESERVER hServer,
1014
DECLR3CALLBACKMEMBER(void, VRDERedirect,(HVRDESERVER hServer,
1015
uint32_t u32ClientId,
1016
const char *pszServer,
1017
const char *pszUser,
1018
const char *pszDomain,
1019
const char *pszPassword,
1020
uint32_t u32SessionId,
1021
const char *pszCookie));
1024
* New for version 3.
1028
* Audio input open request.
1030
* @param hServer Handle of VRDE server instance.
1031
* @param pvCtx To be used in VRDECallbackAudioIn.
1032
* @param u32ClientId An identifier that allows the server to find the corresponding client.
1033
* @param audioFormat Preferred format of audio data.
1034
* @param u32SamplesPerBlock Preferred number of samples in one block of audio input data.
1036
* @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL.
1038
DECLR3CALLBACKMEMBER(void, VRDEAudioInOpen,(HVRDESERVER hServer,
1040
uint32_t u32ClientId,
1041
VRDEAUDIOFORMAT audioFormat,
1042
uint32_t u32SamplesPerBlock));
1045
* Audio input close request.
1047
* @param hServer Handle of VRDE server instance.
1048
* @param u32ClientId An identifier that allows the server to find the corresponding client.
1050
* @note Initialized to NULL when the VRDECallbackAudioIn callback is NULL.
1052
DECLR3CALLBACKMEMBER(void, VRDEAudioInClose,(HVRDESERVER hServer,
1053
uint32_t u32ClientId));
1054
} VRDEENTRYPOINTS_3;
1057
#define VRDE_QP_NETWORK_PORT (1)
1058
#define VRDE_QP_NETWORK_ADDRESS (2)
1059
#define VRDE_QP_NUMBER_MONITORS (3)
1060
#define VRDE_QP_NETWORK_PORT_RANGE (4)
1061
#ifdef VBOX_WITH_VRDP_VIDEO_CHANNEL
1062
#define VRDE_QP_VIDEO_CHANNEL (5)
1063
#define VRDE_QP_VIDEO_CHANNEL_QUALITY (6)
1064
#define VRDE_QP_VIDEO_CHANNEL_SUNFLSH (7)
1065
#endif /* VBOX_WITH_VRDP_VIDEO_CHANNEL */
1066
#define VRDE_QP_FEATURE (8)
1068
#define VRDE_SP_BASE 0x1000
1069
#define VRDE_SP_NETWORK_BIND_PORT (VRDE_SP_BASE + 1)
1072
/* VRDE_QP_FEATURE data. */
1073
typedef struct _VRDEFEATURE
1075
uint32_t u32ClientId;
1076
char achInfo[1]; /* UTF8 property input name and output value. */
1079
/* A framebuffer description. */
1080
typedef struct _VRDEFRAMEBUFFERINFO
1082
const uint8_t *pu8Bits;
1087
unsigned cBitsPerPixel;
1089
} VRDEFRAMEBUFFERINFO;
1091
#define VRDE_INPUT_SCANCODE 0
1092
#define VRDE_INPUT_POINT 1
1093
#define VRDE_INPUT_CAD 2
1094
#define VRDE_INPUT_RESET 3
1095
#define VRDE_INPUT_SYNCH 4
1097
typedef struct _VRDEINPUTSCANCODE
1100
} VRDEINPUTSCANCODE;
1102
#define VRDE_INPUT_POINT_BUTTON1 0x01
1103
#define VRDE_INPUT_POINT_BUTTON2 0x02
1104
#define VRDE_INPUT_POINT_BUTTON3 0x04
1105
#define VRDE_INPUT_POINT_WHEEL_UP 0x08
1106
#define VRDE_INPUT_POINT_WHEEL_DOWN 0x10
1108
typedef struct _VRDEINPUTPOINT
1115
#define VRDE_INPUT_SYNCH_SCROLL 0x01
1116
#define VRDE_INPUT_SYNCH_NUMLOCK 0x02
1117
#define VRDE_INPUT_SYNCH_CAPITAL 0x04
1119
typedef struct _VRDEINPUTSYNCH
1121
unsigned uLockStatus;
1125
/** The VRDE server callbacks. Interface version 1. */
1126
typedef struct _VRDECALLBACKS_1
1129
VRDEINTERFACEHDR header;
1132
* Query or set various information, on how the VRDE server operates, from or to the application.
1135
* @param pvCallback The callback specific pointer.
1136
* @param index VRDE_[Q|S]P_* identifier of information to be returned or set.
1137
* @param pvBuffer Address of memory buffer to which the information must be written or read.
1138
* @param cbBuffer Size of the memory buffer in bytes.
1139
* @param pcbOut Size in bytes of returned information value.
1141
* @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value.
1143
DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1149
/* A client is logging in, the application must decide whether
1150
* to let to connect the client. The server will drop the connection,
1151
* when an error code is returned by the callback.
1153
* @param pvCallback The callback specific pointer.
1154
* @param u32ClientId An unique client identifier generated by the server.
1155
* @param pszUser The username.
1156
* @param pszPassword The password.
1157
* @param pszDomain The domain.
1159
* @return IPRT status code.
1161
DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1162
uint32_t u32ClientId,
1163
const char *pszUser,
1164
const char *pszPassword,
1165
const char *pszDomain));
1167
/* The client has been successfully connected.
1169
* @param pvCallback The callback specific pointer.
1170
* @param u32ClientId An unique client identifier generated by the server.
1172
DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1173
uint32_t u32ClientId));
1175
/* The client has been disconnected.
1177
* @param pvCallback The callback specific pointer.
1178
* @param u32ClientId An unique client identifier generated by the server.
1179
* @param fu32Intercepted What was intercepted by the client (VRDE_CLIENT_INTERCEPT_*).
1181
DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1182
uint32_t u32ClientId,
1183
uint32_t fu32Intercepted));
1184
/* The client supports one of RDP channels.
1186
* @param pvCallback The callback specific pointer.
1187
* @param u32ClientId An unique client identifier generated by the server.
1188
* @param fu32Intercept What the client wants to intercept. One of VRDE_CLIENT_INTERCEPT_* flags.
1189
* @param ppvIntercept The value to be passed to the channel specific callback.
1191
* @return IPRT status code.
1193
DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1194
uint32_t u32ClientId,
1195
uint32_t fu32Intercept,
1196
void **ppvIntercept));
1199
* Called by the server when a reply is received from a client.
1201
* @param pvCallback The callback specific pointer.
1202
* @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_USB.
1203
* @param u32ClientId Identifies the client that sent the reply.
1204
* @param u8Code The operation code VRDE_USB_REQ_*.
1205
* @param pvRet Points to data received from the client.
1206
* @param cbRet Size of the data in bytes.
1208
* @return IPRT status code.
1210
DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1212
uint32_t u32ClientId,
1218
* Called by the server when (VRDE_CLIPBOARD_FUNCTION_*):
1219
* - (0) client announces available clipboard formats;
1220
* - (1) client requests clipboard data.
1222
* @param pvCallback The callback specific pointer.
1223
* @param ppvIntercept The value returned by VRDECallbackIntercept for the VRDE_CLIENT_INTERCEPT_CLIPBOARD.
1224
* @param u32ClientId Identifies the RDP client that sent the reply.
1225
* @param u32Function The cause of the callback.
1226
* @param u32Format Bitmask of reported formats or the format of received data.
1227
* @param pvData Reserved.
1228
* @param cbData Reserved.
1230
* @return IPRT status code.
1232
DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1234
uint32_t u32ClientId,
1235
uint32_t u32Function,
1240
/* The framebuffer information is queried.
1242
* @param pvCallback The callback specific pointer.
1243
* @param uScreenId The framebuffer index.
1244
* @param pInfo The information structure to ber filled.
1246
* @return Whether the framebuffer is available.
1248
DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1250
VRDEFRAMEBUFFERINFO *pInfo));
1252
/* The framebuffer is locked.
1254
* @param pvCallback The callback specific pointer.
1255
* @param uScreenId The framebuffer index.
1257
DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1258
unsigned uScreenId));
1260
/* The framebuffer is unlocked.
1262
* @param pvCallback The callback specific pointer.
1263
* @param uScreenId The framebuffer index.
1265
DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1266
unsigned uScreenId));
1268
/* Input from the client.
1270
* @param pvCallback The callback specific pointer.
1271
* @param pvInput The input information.
1272
* @param cbInput The size of the input information.
1274
DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1276
const void *pvInput,
1279
/* Video mode hint from the client.
1281
* @param pvCallback The callback specific pointer.
1282
* @param cWidth Requested width.
1283
* @param cHeight Requested height.
1284
* @param cBitsPerPixel Requested color depth.
1285
* @param uScreenId The framebuffer index.
1287
DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1290
unsigned cBitsPerPixel,
1291
unsigned uScreenId));
1295
/* Callbacks are the same for the version 1 and version 2 interfaces. */
1296
typedef VRDECALLBACKS_1 VRDECALLBACKS_2;
1298
/** The VRDE server callbacks. Interface version 3. */
1299
typedef struct _VRDECALLBACKS_3
1302
VRDEINTERFACEHDR header;
1305
* Same as in version 2.
1307
DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
1313
DECLR3CALLBACKMEMBER(int, VRDECallbackClientLogon,(void *pvCallback,
1314
uint32_t u32ClientId,
1315
const char *pszUser,
1316
const char *pszPassword,
1317
const char *pszDomain));
1319
DECLR3CALLBACKMEMBER(void, VRDECallbackClientConnect,(void *pvCallback,
1320
uint32_t u32ClientId));
1322
DECLR3CALLBACKMEMBER(void, VRDECallbackClientDisconnect,(void *pvCallback,
1323
uint32_t u32ClientId,
1324
uint32_t fu32Intercepted));
1325
DECLR3CALLBACKMEMBER(int, VRDECallbackIntercept,(void *pvCallback,
1326
uint32_t u32ClientId,
1327
uint32_t fu32Intercept,
1328
void **ppvIntercept));
1330
DECLR3CALLBACKMEMBER(int, VRDECallbackUSB,(void *pvCallback,
1332
uint32_t u32ClientId,
1337
DECLR3CALLBACKMEMBER(int, VRDECallbackClipboard,(void *pvCallback,
1339
uint32_t u32ClientId,
1340
uint32_t u32Function,
1345
DECLR3CALLBACKMEMBER(bool, VRDECallbackFramebufferQuery,(void *pvCallback,
1347
VRDEFRAMEBUFFERINFO *pInfo));
1349
DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferLock,(void *pvCallback,
1350
unsigned uScreenId));
1352
DECLR3CALLBACKMEMBER(void, VRDECallbackFramebufferUnlock,(void *pvCallback,
1353
unsigned uScreenId));
1355
DECLR3CALLBACKMEMBER(void, VRDECallbackInput,(void *pvCallback,
1357
const void *pvInput,
1360
DECLR3CALLBACKMEMBER(void, VRDECallbackVideoModeHint,(void *pvCallback,
1363
unsigned cBitsPerPixel,
1364
unsigned uScreenId));
1367
* New for version 3.
1371
* Called by the server when something happens with audio input.
1373
* @param pvCallback The callback specific pointer.
1374
* @param pvCtx The value passed in VRDEAudioInOpen.
1375
* @param u32ClientId Identifies the client that sent the reply.
1376
* @param u32Event The event code VRDE_AUDIOIN_*.
1377
* @param pvData Points to data received from the client.
1378
* @param cbData Size of the data in bytes.
1380
DECLR3CALLBACKMEMBER(void, VRDECallbackAudioIn,(void *pvCallback,
1382
uint32_t u32ClientId,
1389
* Create a new VRDE server instance. The instance is fully functional but refuses
1390
* client connections until the entry point VRDEEnableConnections is called by the application.
1392
* The caller prepares the VRDECALLBACKS_* structure. The header.u64Version field of the
1393
* structure must be initialized with the version of the interface to use.
1394
* The server will return pointer to VRDEENTRYPOINTS_* table in *ppEntryPoints
1395
* to match the requested interface.
1396
* That is if pCallbacks->header.u64Version == VRDE_INTERFACE_VERSION_1, then the server
1397
* expects pCallbacks to point to VRDECALLBACKS_1 and will return a pointer to VRDEENTRYPOINTS_1.
1399
* @param pCallback Pointer to the application callbacks which let the server to fetch
1400
* the configuration data and to access the desktop.
1401
* @param pvCallback The callback specific pointer to be passed back to the application.
1402
* @param ppEntryPoints Where to store the pointer to the VRDE entry points structure.
1403
* @param phServer Pointer to the created server instance handle.
1405
* @return IPRT status code.
1407
DECLEXPORT(int) VRDECreateServer (const VRDEINTERFACEHDR *pCallbacks,
1409
VRDEINTERFACEHDR **ppEntryPoints,
1410
HVRDESERVER *phServer);
1412
typedef DECLCALLBACK(int) FNVRDECREATESERVER (const VRDEINTERFACEHDR *pCallbacks,
1414
VRDEINTERFACEHDR **ppEntryPoints,
1415
HVRDESERVER *phServer);
1416
typedef FNVRDECREATESERVER *PFNVRDECREATESERVER;
1419
* List of names of the VRDE properties, which are recognized by the VRDE.
1421
* @returns pointer to array of pointers to name strings (UTF8).
1423
DECLEXPORT(const char * const *) VRDESupportedProperties (void);
1425
typedef DECLCALLBACK(const char * const *) FNVRDESUPPORTEDPROPERTIES (void);
1426
typedef FNVRDESUPPORTEDPROPERTIES *PFNVRDESUPPORTEDPROPERTIES;
added
removed
include/VBox/RemoteDesktop/VRDE.h
