VirtualBox

source: vbox/trunk/include/VBox/vrdpapi.h@ 21217

Last change on this file since 21217 was 21217, checked in by vboxsync, 15 years ago

include/VBox/*.h: Mark which components the header files relate to.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 41.9 KB
Line 
1/** @file
2 * VBox Remote Desktop Protocol - Public APIs. (VRDP)
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_vrdpapi_h
31#define ___VBox_vrdpapi_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35
36#ifdef IN_RING0
37# error "There are no VRDP APIs available in Ring-0 Host Context!"
38#endif
39#ifdef IN_RC
40# error "There are no VRDP APIs available Guest Context!"
41#endif
42
43
44/** @defgroup grp_vrdp VRDP
45 * VirtualBox Remote Desktop Protocol (VRDP) interface that lets to use
46 * the VRDP server.
47 * @{
48 */
49
50/** Default port that VRDP binds to. */
51#define VRDP_DEFAULT_PORT (3389)
52
53RT_C_DECLS_BEGIN
54
55/* Forward declaration of the VRDP server instance handle. */
56#ifdef __cplusplus
57class VRDPServer;
58typedef class VRDPServer *HVRDPSERVER;
59#else
60struct VRDPServer;
61typedef struct VRDPServer *HVRDPSERVER;
62#endif /* __cplusplus */
63
64/* Callback based VRDP server interface declarations. */
65
66#if defined(IN_VRDP)
67# define VRDPDECL(type) DECLEXPORT(type) RTCALL
68#else
69# define VRDPDECL(type) DECLIMPORT(type) RTCALL
70#endif /* IN_VRDP */
71
72/** The color mouse pointer information. */
73typedef struct _VRDPCOLORPOINTER
74{
75 uint16_t u16HotX;
76 uint16_t u16HotY;
77 uint16_t u16Width;
78 uint16_t u16Height;
79 uint16_t u16MaskLen;
80 uint16_t u16DataLen;
81 /* The mask and the bitmap follow. */
82} VRDPCOLORPOINTER;
83
84/** Audio format information packed in a 32 bit value. */
85typedef uint32_t VRDPAUDIOFORMAT;
86
87/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
88#define VRDP_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
89
90/** Decode frequency. */
91#define VRDP_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
92/** Decode number of channels. */
93#define VRDP_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
94/** Decode number signess. */
95#define VRDP_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
96/** Decode number of bits per sample. */
97#define VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
98/** Decode number of bytes per sample. */
99#define VRDP_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
100
101/*
102 * Remote USB protocol.
103 */
104
105/* The initial version 1. */
106#define VRDP_USB_VERSION_1 (1)
107/* Version 2: look for VRDP_USB_VERSION_2 comments in the code. */
108#define VRDP_USB_VERSION_2 (2)
109/* Version 3: look for VRDP_USB_VERSION_3 comments in the code. */
110#define VRDP_USB_VERSION_3 (3)
111
112/* The default VRDP server version of Remote USB Protocol. */
113#define VRDP_USB_VERSION VRDP_USB_VERSION_3
114
115
116/** USB backend operations. */
117#define VRDP_USB_REQ_OPEN (0)
118#define VRDP_USB_REQ_CLOSE (1)
119#define VRDP_USB_REQ_RESET (2)
120#define VRDP_USB_REQ_SET_CONFIG (3)
121#define VRDP_USB_REQ_CLAIM_INTERFACE (4)
122#define VRDP_USB_REQ_RELEASE_INTERFACE (5)
123#define VRDP_USB_REQ_INTERFACE_SETTING (6)
124#define VRDP_USB_REQ_QUEUE_URB (7)
125#define VRDP_USB_REQ_REAP_URB (8)
126#define VRDP_USB_REQ_CLEAR_HALTED_EP (9)
127#define VRDP_USB_REQ_CANCEL_URB (10)
128
129/** USB service operations. */
130#define VRDP_USB_REQ_DEVICE_LIST (11)
131#define VRDP_USB_REQ_NEGOTIATE (12)
132
133/** An operation completion status is a byte. */
134typedef uint8_t VRDPUSBSTATUS;
135
136/** USB device identifier is an 32 bit value. */
137typedef uint32_t VRDPUSBDEVID;
138
139/** Status codes. */
140#define VRDP_USB_STATUS_SUCCESS ((VRDPUSBSTATUS)0)
141#define VRDP_USB_STATUS_ACCESS_DENIED ((VRDPUSBSTATUS)1)
142#define VRDP_USB_STATUS_DEVICE_REMOVED ((VRDPUSBSTATUS)2)
143
144/*
145 * Data structures to use with VRDPUSBRequest.
146 * The *RET* structures always represent the layout of VRDP data.
147 * The *PARM* structures normally the same as VRDP layout.
148 * However the VRDP_USB_REQ_QUEUE_URB_PARM has a pointer to
149 * URB data in place where actual data will be in VRDP layout.
150 *
151 * Since replies (*RET*) are asynchronous, the 'success'
152 * replies are not required for operations which return
153 * only the status code (VRDPUSBREQRETHDR only):
154 * VRDP_USB_REQ_OPEN
155 * VRDP_USB_REQ_RESET
156 * VRDP_USB_REQ_SET_CONFIG
157 * VRDP_USB_REQ_CLAIM_INTERFACE
158 * VRDP_USB_REQ_RELEASE_INTERFACE
159 * VRDP_USB_REQ_INTERFACE_SETTING
160 * VRDP_USB_REQ_CLEAR_HALTED_EP
161 *
162 */
163
164/* VRDP layout has no aligments. */
165#pragma pack(1)
166/* Common header for all VRDP USB packets. After the reply hdr follows *PARM* or *RET* data. */
167typedef struct _VRDPUSBPKTHDR
168{
169 /* Total length of the reply NOT including the 'length' field. */
170 uint32_t length;
171 /* The operation code for which the reply was sent by the client. */
172 uint8_t code;
173} VRDPUSBPKTHDR;
174
175/* Common header for all return structures. */
176typedef struct _VRDPUSBREQRETHDR
177{
178 /* Device status. */
179 VRDPUSBSTATUS status;
180 /* Device id. */
181 VRDPUSBDEVID id;
182} VRDPUSBREQRETHDR;
183
184
185/* VRDP_USB_REQ_OPEN
186 */
187typedef struct _VRDP_USB_REQ_OPEN_PARM
188{
189 uint8_t code;
190 VRDPUSBDEVID id;
191} VRDP_USB_REQ_OPEN_PARM;
192
193typedef struct _VRDP_USB_REQ_OPEN_RET
194{
195 VRDPUSBREQRETHDR hdr;
196} VRDP_USB_REQ_OPEN_RET;
197
198
199/* VRDP_USB_REQ_CLOSE
200 */
201typedef struct _VRDP_USB_REQ_CLOSE_PARM
202{
203 uint8_t code;
204 VRDPUSBDEVID id;
205} VRDP_USB_REQ_CLOSE_PARM;
206
207/* The close request has no returned data. */
208
209
210/* VRDP_USB_REQ_RESET
211 */
212typedef struct _VRDP_USB_REQ_RESET_PARM
213{
214 uint8_t code;
215 VRDPUSBDEVID id;
216} VRDP_USB_REQ_RESET_PARM;
217
218typedef struct _VRDP_USB_REQ_RESET_RET
219{
220 VRDPUSBREQRETHDR hdr;
221} VRDP_USB_REQ_RESET_RET;
222
223
224/* VRDP_USB_REQ_SET_CONFIG
225 */
226typedef struct _VRDP_USB_REQ_SET_CONFIG_PARM
227{
228 uint8_t code;
229 VRDPUSBDEVID id;
230 uint8_t configuration;
231} VRDP_USB_REQ_SET_CONFIG_PARM;
232
233typedef struct _VRDP_USB_REQ_SET_CONFIG_RET
234{
235 VRDPUSBREQRETHDR hdr;
236} VRDP_USB_REQ_SET_CONFIG_RET;
237
238
239/* VRDP_USB_REQ_CLAIM_INTERFACE
240 */
241typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_PARM
242{
243 uint8_t code;
244 VRDPUSBDEVID id;
245 uint8_t iface;
246} VRDP_USB_REQ_CLAIM_INTERFACE_PARM;
247
248typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_RET
249{
250 VRDPUSBREQRETHDR hdr;
251} VRDP_USB_REQ_CLAIM_INTERFACE_RET;
252
253
254/* VRDP_USB_REQ_RELEASE_INTERFACE
255 */
256typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_PARM
257{
258 uint8_t code;
259 VRDPUSBDEVID id;
260 uint8_t iface;
261} VRDP_USB_REQ_RELEASE_INTERFACE_PARM;
262
263typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_RET
264{
265 VRDPUSBREQRETHDR hdr;
266} VRDP_USB_REQ_RELEASE_INTERFACE_RET;
267
268
269/* VRDP_USB_REQ_INTERFACE_SETTING
270 */
271typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_PARM
272{
273 uint8_t code;
274 VRDPUSBDEVID id;
275 uint8_t iface;
276 uint8_t setting;
277} VRDP_USB_REQ_INTERFACE_SETTING_PARM;
278
279typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_RET
280{
281 VRDPUSBREQRETHDR hdr;
282} VRDP_USB_REQ_INTERFACE_SETTING_RET;
283
284
285/* VRDP_USB_REQ_QUEUE_URB
286 */
287
288#define VRDP_USB_TRANSFER_TYPE_CTRL (0)
289#define VRDP_USB_TRANSFER_TYPE_ISOC (1)
290#define VRDP_USB_TRANSFER_TYPE_BULK (2)
291#define VRDP_USB_TRANSFER_TYPE_INTR (3)
292#define VRDP_USB_TRANSFER_TYPE_MSG (4)
293
294#define VRDP_USB_DIRECTION_SETUP (0)
295#define VRDP_USB_DIRECTION_IN (1)
296#define VRDP_USB_DIRECTION_OUT (2)
297
298typedef struct _VRDP_USB_REQ_QUEUE_URB_PARM
299{
300 uint8_t code;
301 VRDPUSBDEVID id;
302 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
303 uint8_t type;
304 uint8_t ep;
305 uint8_t direction;
306 uint32_t urblen; /* Length of the URB. */
307 uint32_t datalen; /* Length of the data. */
308 void *data; /* In RDP layout the data follow. */
309} VRDP_USB_REQ_QUEUE_URB_PARM;
310
311/* The queue URB has no explicit return. The reap URB reply will be
312 * eventually the indirect result.
313 */
314
315
316/* VRDP_USB_REQ_REAP_URB
317 * Notificationg from server to client that server expects an URB
318 * from any device.
319 * Only sent if negotiated URB return method is polling.
320 * Normally, the client will send URBs back as soon as they are ready.
321 */
322typedef struct _VRDP_USB_REQ_REAP_URB_PARM
323{
324 uint8_t code;
325} VRDP_USB_REQ_REAP_URB_PARM;
326
327
328#define VRDP_USB_XFER_OK (0)
329#define VRDP_USB_XFER_STALL (1)
330#define VRDP_USB_XFER_DNR (2)
331#define VRDP_USB_XFER_CRC (3)
332/* VRDP_USB_VERSION_2: New error codes. */
333#define VRDP_USB_XFER_BS (4)
334#define VRDP_USB_XFER_DTM (5)
335#define VRDP_USB_XFER_PCF (6)
336#define VRDP_USB_XFER_UPID (7)
337#define VRDP_USB_XFER_DO (8)
338#define VRDP_USB_XFER_DU (9)
339#define VRDP_USB_XFER_BO (10)
340#define VRDP_USB_XFER_BU (11)
341#define VRDP_USB_XFER_ERR (12) /* VBox protocol error. */
342
343#define VRDP_USB_REAP_FLAG_CONTINUED (0x0)
344#define VRDP_USB_REAP_FLAG_LAST (0x1)
345/* VRDP_USB_VERSION_3: Fragmented URBs. */
346#define VRDP_USB_REAP_FLAG_FRAGMENT (0x2)
347
348#define VRDP_USB_REAP_VALID_FLAGS (VRDP_USB_REAP_FLAG_LAST)
349/* VRDP_USB_VERSION_3: Fragmented URBs. */
350#define VRDP_USB_REAP_VALID_FLAGS_3 (VRDP_USB_REAP_FLAG_LAST | VRDP_USB_REAP_FLAG_FRAGMENT)
351
352typedef struct _VRDPUSBREQREAPURBBODY
353{
354 VRDPUSBDEVID id; /* From which device the URB arrives. */
355 uint8_t flags; /* VRDP_USB_REAP_FLAG_* */
356 uint8_t error; /* VRDP_USB_XFER_* */
357 uint32_t handle; /* Handle of returned URB. Not 0. */
358 uint32_t len; /* Length of data actually transferred. */
359 /* Data follow. */
360} VRDPUSBREQREAPURBBODY;
361
362typedef struct _VRDP_USB_REQ_REAP_URB_RET
363{
364 /* The REAP URB has no header, only completed URBs are returned. */
365 VRDPUSBREQREAPURBBODY body;
366 /* Another body may follow, depending on flags. */
367} VRDP_USB_REQ_REAP_URB_RET;
368
369
370/* VRDP_USB_REQ_CLEAR_HALTED_EP
371 */
372typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_PARM
373{
374 uint8_t code;
375 VRDPUSBDEVID id;
376 uint8_t ep;
377} VRDP_USB_REQ_CLEAR_HALTED_EP_PARM;
378
379typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_RET
380{
381 VRDPUSBREQRETHDR hdr;
382} VRDP_USB_REQ_CLEAR_HALTED_EP_RET;
383
384
385/* VRDP_USB_REQ_CANCEL_URB
386 */
387typedef struct _VRDP_USB_REQ_CANCEL_URB_PARM
388{
389 uint8_t code;
390 VRDPUSBDEVID id;
391 uint32_t handle;
392} VRDP_USB_REQ_CANCEL_URB_PARM;
393
394/* The cancel URB request has no return. */
395
396
397/* VRDP_USB_REQ_DEVICE_LIST
398 *
399 * Server polls USB devices on client by sending this request
400 * periodically. Client sends back a list of all devices
401 * connected to it. Each device is assigned with an identifier,
402 * that is used to distinguish the particular device.
403 */
404typedef struct _VRDP_USB_REQ_DEVICE_LIST_PARM
405{
406 uint8_t code;
407} VRDP_USB_REQ_DEVICE_LIST_PARM;
408
409/* Data is a list of the following variable length structures. */
410typedef struct _VRDPUSBDEVICEDESC
411{
412 /* Offset of the next structure. 0 if last. */
413 uint16_t oNext;
414
415 /* Identifier of the device assigned by client. */
416 VRDPUSBDEVID id;
417
418 /** USB version number. */
419 uint16_t bcdUSB;
420 /** Device class. */
421 uint8_t bDeviceClass;
422 /** Device subclass. */
423 uint8_t bDeviceSubClass;
424 /** Device protocol */
425 uint8_t bDeviceProtocol;
426 /** Vendor ID. */
427 uint16_t idVendor;
428 /** Product ID. */
429 uint16_t idProduct;
430 /** Revision, integer part. */
431 uint16_t bcdRev;
432 /** Manufacturer string. */
433 uint16_t oManufacturer;
434 /** Product string. */
435 uint16_t oProduct;
436 /** Serial number string. */
437 uint16_t oSerialNumber;
438 /** Physical USB port the device is connected to. */
439 uint16_t idPort;
440
441} VRDPUSBDEVICEDESC;
442
443typedef struct _VRDP_USB_REQ_DEVICE_LIST_RET
444{
445 VRDPUSBDEVICEDESC body;
446 /* Other devices may follow.
447 * The list ends with (uint16_t)0,
448 * which means that an empty list consists of 2 zero bytes.
449 */
450} VRDP_USB_REQ_DEVICE_LIST_RET;
451
452typedef struct _VRDPUSBREQNEGOTIATEPARM
453{
454 uint8_t code;
455
456 /* Remote USB Protocol version. */
457 /* VRDP_USB_VERSION_3: the 32 bit field is splitted to 16 bit version and 16 bit flags.
458 * Version 1 and 2 servers therefore have 'flags' == 0.
459 * Version 3+ servers can send some capabilities in this field, this way it is possible to add
460 * a new capability without increasing the protocol version.
461 */
462 uint16_t version;
463 uint16_t flags;
464
465} VRDPUSBREQNEGOTIATEPARM;
466
467#define VRDP_USB_CAPS_FLAG_ASYNC (0x0)
468#define VRDP_USB_CAPS_FLAG_POLL (0x1)
469/* VRDP_USB_VERSION_2: New flag. */
470#define VRDP_USB_CAPS2_FLAG_VERSION (0x2) /* The client is negotiating the protocol version. */
471
472
473#define VRDP_USB_CAPS_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL)
474/* VRDP_USB_VERSION_2: A set of valid flags. */
475#define VRDP_USB_CAPS2_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL | VRDP_USB_CAPS2_FLAG_VERSION)
476
477typedef struct _VRDPUSBREQNEGOTIATERET
478{
479 uint8_t flags;
480} VRDPUSBREQNEGOTIATERET;
481
482typedef struct _VRDPUSBREQNEGOTIATERET_2
483{
484 uint8_t flags;
485 uint32_t u32Version; /* This field presents only if the VRDP_USB_CAPS2_FLAG_VERSION flag is set. */
486} VRDPUSBREQNEGOTIATERET_2;
487#pragma pack()
488
489#define VRDP_CLIPBOARD_FORMAT_NULL (0x0)
490#define VRDP_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
491#define VRDP_CLIPBOARD_FORMAT_BITMAP (0x2)
492#define VRDP_CLIPBOARD_FORMAT_HTML (0x4)
493
494#define VRDP_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
495#define VRDP_CLIPBOARD_FUNCTION_DATA_READ (1)
496#define VRDP_CLIPBOARD_FUNCTION_DATA_WRITE (2)
497
498
499/** Indexes of information values. */
500
501/** Whether a client is connected at the moment.
502 * uint32_t
503 */
504#define VRDP_QI_ACTIVE (0)
505
506/** How many times a client connected up to current moment.
507 * uint32_t
508 */
509#define VRDP_QI_NUMBER_OF_CLIENTS (1)
510
511/** When last connection was established.
512 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
513 */
514#define VRDP_QI_BEGIN_TIME (2)
515
516/** When last connection was terminated or current time if connection still active.
517 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
518 */
519#define VRDP_QI_END_TIME (3)
520
521/** How many bytes were sent in last (current) connection.
522 * uint64_t
523 */
524#define VRDP_QI_BYTES_SENT (4)
525
526/** How many bytes were sent in all connections.
527 * uint64_t
528 */
529#define VRDP_QI_BYTES_SENT_TOTAL (5)
530
531/** How many bytes were received in last (current) connection.
532 * uint64_t
533 */
534#define VRDP_QI_BYTES_RECEIVED (6)
535
536/** How many bytes were received in all connections.
537 * uint64_t
538 */
539#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
540
541/** Login user name supplied by the client.
542 * UTF8 nul terminated string.
543 */
544#define VRDP_QI_USER (8)
545
546/** Login domain supplied by the client.
547 * UTF8 nul terminated string.
548 */
549#define VRDP_QI_DOMAIN (9)
550
551/** The client name supplied by the client.
552 * UTF8 nul terminated string.
553 */
554#define VRDP_QI_CLIENT_NAME (10)
555
556/** IP address of the client.
557 * UTF8 nul terminated string.
558 */
559#define VRDP_QI_CLIENT_IP (11)
560
561/** The client software version number.
562 * uint32_t.
563 */
564#define VRDP_QI_CLIENT_VERSION (12)
565
566/** Public key exchange method used when connection was established.
567 * Values: 0 - RDP4 public key exchange scheme.
568 * 1 - X509 sertificates were sent to client.
569 * uint32_t.
570 */
571#define VRDP_QI_ENCRYPTION_STYLE (13)
572
573
574/** Hints what has been intercepted by the application. */
575#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
576#define VRDP_CLIENT_INTERCEPT_USB (0x2)
577#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
578
579
580/** The version of the VRDP server interface. */
581#define VRDP_INTERFACE_VERSION_1 (1)
582#define VRDP_INTERFACE_VERSION_2 (2)
583
584/** The header that does not change when the interface changes. */
585typedef struct _VRDPINTERFACEHDR
586{
587 /** The version of the interface. */
588 uint64_t u64Version;
589
590 /** The size of the structure. */
591 uint64_t u64Size;
592
593} VRDPINTERFACEHDR;
594
595/** The VRDP server entry points. Interface version 1. */
596typedef struct _VRDPENTRYPOINTS_1
597{
598 /** The header. */
599 VRDPINTERFACEHDR header;
600
601 /** Destroy the server instance.
602 *
603 * @param hServer The server instance handle.
604 *
605 * @return IPRT status code.
606 */
607 DECLR3CALLBACKMEMBER(void, VRDPDestroy,(HVRDPSERVER hServer));
608
609 /** The server should start to accept clients connections.
610 *
611 * @param hServer The server instance handle.
612 * @param fEnable Whether to enable or disable client connections.
613 * When is false, all existing clients are disconnected.
614 *
615 * @return IPRT status code.
616 */
617 DECLR3CALLBACKMEMBER(int, VRDPEnableConnections,(HVRDPSERVER hServer,
618 bool fEnable));
619
620 /** The server should disconnect the client.
621 *
622 * @param hServer The server instance handle.
623 * @param u32ClientId The client identifier.
624 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
625 * client before disconnecting.
626 *
627 * @return IPRT status code.
628 */
629 DECLR3CALLBACKMEMBER(void, VRDPDisconnect,(HVRDPSERVER hServer,
630 uint32_t u32ClientId,
631 bool fReconnect));
632
633 /**
634 * Inform the server that the display was resized.
635 * The server will query information about display
636 * from the application via callbacks.
637 *
638 * @param hServer Handle of VRDP server instance.
639 */
640 DECLR3CALLBACKMEMBER(void, VRDPResize,(HVRDPSERVER hServer));
641
642 /**
643 * Send a update.
644 *
645 * @param hServer Handle of VRDP server instance.
646 * @param uScreenId The screen index.
647 * @param pvUpdate Pointer to VBoxGuest.h::VRDPORDERHDR structure with extra data.
648 * @param cbUpdate Size of the update data.
649 */
650 DECLR3CALLBACKMEMBER(void, VRDPUpdate,(HVRDPSERVER hServer,
651 unsigned uScreenId,
652 void *pvUpdate,
653 uint32_t cbUpdate));
654
655 /**
656 * Set the mouse pointer shape.
657 *
658 * @param hServer Handle of VRDP server instance.
659 * @param pPointer The pointer shape information.
660 */
661 DECLR3CALLBACKMEMBER(void, VRDPColorPointer,(HVRDPSERVER hServer,
662 const VRDPCOLORPOINTER *pPointer));
663
664 /**
665 * Hide the mouse pointer.
666 *
667 * @param hServer Handle of VRDP server instance.
668 */
669 DECLR3CALLBACKMEMBER(void, VRDPHidePointer,(HVRDPSERVER hServer));
670
671 /**
672 * Queues the samples to be sent to clients.
673 *
674 * @param hServer Handle of VRDP server instance.
675 * @param pvSamples Address of samples to be sent.
676 * @param cSamples Number of samples.
677 * @param format Encoded audio format for these samples.
678 *
679 * @note Initialized to NULL when the application audio callbacks are NULL.
680 */
681 DECLR3CALLBACKMEMBER(void, VRDPAudioSamples,(HVRDPSERVER hServer,
682 const void *pvSamples,
683 uint32_t cSamples,
684 VRDPAUDIOFORMAT format));
685
686 /**
687 * Sets the sound volume on clients.
688 *
689 * @param hServer Handle of VRDP server instance.
690 * @param left 0..0xFFFF volume level for left channel.
691 * @param right 0..0xFFFF volume level for right channel.
692 *
693 * @note Initialized to NULL when the application audio callbacks are NULL.
694 */
695 DECLR3CALLBACKMEMBER(void, VRDPAudioVolume,(HVRDPSERVER hServer,
696 uint16_t u16Left,
697 uint16_t u16Right));
698
699 /**
700 * Sends a USB request.
701 *
702 * @param hServer Handle of VRDP server instance.
703 * @param u32ClientId An identifier that allows the server to find the corresponding client.
704 * The identifier is always passed by the server as a parameter
705 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
706 * in the VRDPSERVERCALLBACK functions.
707 * @param pvParm Function specific parameters buffer.
708 * @param cbParm Size of the buffer.
709 *
710 * @note Initialized to NULL when the application USB callbacks are NULL.
711 */
712 DECLR3CALLBACKMEMBER(void, VRDPUSBRequest,(HVRDPSERVER hServer,
713 uint32_t u32ClientId,
714 void *pvParm,
715 uint32_t cbParm));
716
717 /**
718 * Called by the application when (VRDP_CLIPBOARD_FUNCTION_*):
719 * - (0) guest announces available clipboard formats;
720 * - (1) guest requests clipboard data;
721 * - (2) guest responds to the client's request for clipboard data.
722 *
723 * @param hServer The VRDP server handle.
724 * @param u32Function The cause of the call.
725 * @param u32Format Bitmask of announced formats or the format of data.
726 * @param pvData Points to: (1) buffer to be filled with clients data;
727 * (2) data from the host.
728 * @param cbData Size of 'pvData' buffer in bytes.
729 * @param pcbActualRead Size of the copied data in bytes.
730 *
731 * @note Initialized to NULL when the application clipboard callbacks are NULL.
732 */
733 DECLR3CALLBACKMEMBER(void, VRDPClipboard,(HVRDPSERVER hServer,
734 uint32_t u32Function,
735 uint32_t u32Format,
736 void *pvData,
737 uint32_t cbData,
738 uint32_t *pcbActualRead));
739
740 /**
741 * Query various information from the VRDP server.
742 *
743 * @param hServer The VRDP server handle.
744 * @param index VRDP_QI_* identifier of information to be returned.
745 * @param pvBuffer Address of memory buffer to which the information must be written.
746 * @param cbBuffer Size of the memory buffer in bytes.
747 * @param pcbOut Size in bytes of returned information value.
748 *
749 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
750 * A value greater than cbBuffer means that information is too big to fit in the
751 * buffer, in that case no information was placed to the buffer.
752 */
753 DECLR3CALLBACKMEMBER(void, VRDPQueryInfo,(HVRDPSERVER hServer,
754 uint32_t index,
755 void *pvBuffer,
756 uint32_t cbBuffer,
757 uint32_t *pcbOut));
758} VRDPENTRYPOINTS_1;
759
760/** The VRDP server entry points. Interface version 2.
761 * A new entry point VRDPRedirect has been added relative to version 1.
762 */
763typedef struct _VRDPENTRYPOINTS_2
764{
765 /** The header. */
766 VRDPINTERFACEHDR header;
767
768 /** Destroy the server instance.
769 *
770 * @param hServer The server instance handle.
771 *
772 * @return IPRT status code.
773 */
774 DECLR3CALLBACKMEMBER(void, VRDPDestroy,(HVRDPSERVER hServer));
775
776 /** The server should start to accept clients connections.
777 *
778 * @param hServer The server instance handle.
779 * @param fEnable Whether to enable or disable client connections.
780 * When is false, all existing clients are disconnected.
781 *
782 * @return IPRT status code.
783 */
784 DECLR3CALLBACKMEMBER(int, VRDPEnableConnections,(HVRDPSERVER hServer,
785 bool fEnable));
786
787 /** The server should disconnect the client.
788 *
789 * @param hServer The server instance handle.
790 * @param u32ClientId The client identifier.
791 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
792 * client before disconnecting.
793 *
794 * @return IPRT status code.
795 */
796 DECLR3CALLBACKMEMBER(void, VRDPDisconnect,(HVRDPSERVER hServer,
797 uint32_t u32ClientId,
798 bool fReconnect));
799
800 /**
801 * Inform the server that the display was resized.
802 * The server will query information about display
803 * from the application via callbacks.
804 *
805 * @param hServer Handle of VRDP server instance.
806 */
807 DECLR3CALLBACKMEMBER(void, VRDPResize,(HVRDPSERVER hServer));
808
809 /**
810 * Send a update.
811 *
812 * @param hServer Handle of VRDP server instance.
813 * @param uScreenId The screen index.
814 * @param pvUpdate Pointer to VBoxGuest.h::VRDPORDERHDR structure with extra data.
815 * @param cbUpdate Size of the update data.
816 */
817 DECLR3CALLBACKMEMBER(void, VRDPUpdate,(HVRDPSERVER hServer,
818 unsigned uScreenId,
819 void *pvUpdate,
820 uint32_t cbUpdate));
821
822 /**
823 * Set the mouse pointer shape.
824 *
825 * @param hServer Handle of VRDP server instance.
826 * @param pPointer The pointer shape information.
827 */
828 DECLR3CALLBACKMEMBER(void, VRDPColorPointer,(HVRDPSERVER hServer,
829 const VRDPCOLORPOINTER *pPointer));
830
831 /**
832 * Hide the mouse pointer.
833 *
834 * @param hServer Handle of VRDP server instance.
835 */
836 DECLR3CALLBACKMEMBER(void, VRDPHidePointer,(HVRDPSERVER hServer));
837
838 /**
839 * Queues the samples to be sent to clients.
840 *
841 * @param hServer Handle of VRDP server instance.
842 * @param pvSamples Address of samples to be sent.
843 * @param cSamples Number of samples.
844 * @param format Encoded audio format for these samples.
845 *
846 * @note Initialized to NULL when the application audio callbacks are NULL.
847 */
848 DECLR3CALLBACKMEMBER(void, VRDPAudioSamples,(HVRDPSERVER hServer,
849 const void *pvSamples,
850 uint32_t cSamples,
851 VRDPAUDIOFORMAT format));
852
853 /**
854 * Sets the sound volume on clients.
855 *
856 * @param hServer Handle of VRDP server instance.
857 * @param left 0..0xFFFF volume level for left channel.
858 * @param right 0..0xFFFF volume level for right channel.
859 *
860 * @note Initialized to NULL when the application audio callbacks are NULL.
861 */
862 DECLR3CALLBACKMEMBER(void, VRDPAudioVolume,(HVRDPSERVER hServer,
863 uint16_t u16Left,
864 uint16_t u16Right));
865
866 /**
867 * Sends a USB request.
868 *
869 * @param hServer Handle of VRDP server instance.
870 * @param u32ClientId An identifier that allows the server to find the corresponding client.
871 * The identifier is always passed by the server as a parameter
872 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
873 * in the VRDPSERVERCALLBACK functions.
874 * @param pvParm Function specific parameters buffer.
875 * @param cbParm Size of the buffer.
876 *
877 * @note Initialized to NULL when the application USB callbacks are NULL.
878 */
879 DECLR3CALLBACKMEMBER(void, VRDPUSBRequest,(HVRDPSERVER hServer,
880 uint32_t u32ClientId,
881 void *pvParm,
882 uint32_t cbParm));
883
884 /**
885 * Called by the application when (VRDP_CLIPBOARD_FUNCTION_*):
886 * - (0) guest announces available clipboard formats;
887 * - (1) guest requests clipboard data;
888 * - (2) guest responds to the client's request for clipboard data.
889 *
890 * @param hServer The VRDP server handle.
891 * @param u32Function The cause of the call.
892 * @param u32Format Bitmask of announced formats or the format of data.
893 * @param pvData Points to: (1) buffer to be filled with clients data;
894 * (2) data from the host.
895 * @param cbData Size of 'pvData' buffer in bytes.
896 * @param pcbActualRead Size of the copied data in bytes.
897 *
898 * @note Initialized to NULL when the application clipboard callbacks are NULL.
899 */
900 DECLR3CALLBACKMEMBER(void, VRDPClipboard,(HVRDPSERVER hServer,
901 uint32_t u32Function,
902 uint32_t u32Format,
903 void *pvData,
904 uint32_t cbData,
905 uint32_t *pcbActualRead));
906
907 /**
908 * Query various information from the VRDP server.
909 *
910 * @param hServer The VRDP server handle.
911 * @param index VRDP_QI_* identifier of information to be returned.
912 * @param pvBuffer Address of memory buffer to which the information must be written.
913 * @param cbBuffer Size of the memory buffer in bytes.
914 * @param pcbOut Size in bytes of returned information value.
915 *
916 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
917 * A value greater than cbBuffer means that information is too big to fit in the
918 * buffer, in that case no information was placed to the buffer.
919 */
920 DECLR3CALLBACKMEMBER(void, VRDPQueryInfo,(HVRDPSERVER hServer,
921 uint32_t index,
922 void *pvBuffer,
923 uint32_t cbBuffer,
924 uint32_t *pcbOut));
925
926 /**
927 * The server should redirect the client to the specified server.
928 *
929 * @param hServer The server instance handle.
930 * @param u32ClientId The client identifier.
931 * @param pszServer The server to redirect the client to.
932 * @param pszUser The username to use for the redirection.
933 * Can be NULL.
934 * @param pszDomain The domain. Can be NULL.
935 * @param pszPassword The password. Can be NULL.
936 * @param u32SessionId The ID of the session to redirect to.
937 * @param pszCookie The routing token used by a load balancer to
938 * route the redirection. Can be NULL.
939 */
940 DECLR3CALLBACKMEMBER(void, VRDPRedirect,(HVRDPSERVER hServer,
941 uint32_t u32ClientId,
942 const char *pszServer,
943 const char *pszUser,
944 const char *pszDomain,
945 const char *pszPassword,
946 uint32_t u32SessionId,
947 const char *pszCookie));
948} VRDPENTRYPOINTS_2;
949
950#define VRDP_QP_NETWORK_PORT (1)
951#define VRDP_QP_NETWORK_ADDRESS (2)
952#define VRDP_QP_NUMBER_MONITORS (3)
953
954#pragma pack(1)
955/* A framebuffer description. */
956typedef struct _VRDPFRAMEBUFFERINFO
957{
958 const uint8_t *pu8Bits;
959 int xOrigin;
960 int yOrigin;
961 unsigned cWidth;
962 unsigned cHeight;
963 unsigned cBitsPerPixel;
964 unsigned cbLine;
965} VRDPFRAMEBUFFERINFO;
966
967#define VRDP_INPUT_SCANCODE 0
968#define VRDP_INPUT_POINT 1
969#define VRDP_INPUT_CAD 2
970#define VRDP_INPUT_RESET 3
971#define VRDP_INPUT_SYNCH 4
972
973typedef struct _VRDPINPUTSCANCODE
974{
975 unsigned uScancode;
976} VRDPINPUTSCANCODE;
977
978#define VRDP_INPUT_POINT_BUTTON1 0x01
979#define VRDP_INPUT_POINT_BUTTON2 0x02
980#define VRDP_INPUT_POINT_BUTTON3 0x04
981#define VRDP_INPUT_POINT_WHEEL_UP 0x08
982#define VRDP_INPUT_POINT_WHEEL_DOWN 0x10
983
984typedef struct _VRDPINPUTPOINT
985{
986 int x;
987 int y;
988 unsigned uButtons;
989} VRDPINPUTPOINT;
990
991#define VRDP_INPUT_SYNCH_SCROLL 0x01
992#define VRDP_INPUT_SYNCH_NUMLOCK 0x02
993#define VRDP_INPUT_SYNCH_CAPITAL 0x04
994
995typedef struct _VRDPINPUTSYNCH
996{
997 unsigned uLockStatus;
998} VRDPINPUTSYNCH;
999#pragma pack()
1000
1001/** The VRDP server callbacks. Interface version 1. */
1002typedef struct _VRDPCALLBACKS_1
1003{
1004 /** The header. */
1005 VRDPINTERFACEHDR header;
1006
1007 /**
1008 * Query various information, on how the VRDP server must operate, from the application.
1009 *
1010 * @param pvCallback The callback specific pointer.
1011 * @param index VRDP_QP_* identifier of information to be returned.
1012 * @param pvBuffer Address of memory buffer to which the information must be written.
1013 * @param cbBuffer Size of the memory buffer in bytes.
1014 * @param pcbOut Size in bytes of returned information value.
1015 *
1016 * @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value.
1017 */
1018 DECLR3CALLBACKMEMBER(int, VRDPCallbackQueryProperty,(void *pvCallback,
1019 uint32_t index,
1020 void *pvBuffer,
1021 uint32_t cbBuffer,
1022 uint32_t *pcbOut));
1023
1024 /* A client is logging in, the application must decide whether
1025 * to let to connect the client. The server will drop the connection,
1026 * when an error code is returned by the callback.
1027 *
1028 * @param pvCallback The callback specific pointer.
1029 * @param u32ClientId An unique client identifier generated by the server.
1030 * @param pszUser The username.
1031 * @param pszPassword The password.
1032 * @param pszDomain The domain.
1033 *
1034 * @return IPRT status code.
1035 */
1036 DECLR3CALLBACKMEMBER(int, VRDPCallbackClientLogon,(void *pvCallback,
1037 uint32_t u32ClientId,
1038 const char *pszUser,
1039 const char *pszPassword,
1040 const char *pszDomain));
1041
1042 /* The client has been successfully connected.
1043 *
1044 * @param pvCallback The callback specific pointer.
1045 * @param u32ClientId An unique client identifier generated by the server.
1046 */
1047 DECLR3CALLBACKMEMBER(void, VRDPCallbackClientConnect,(void *pvCallback,
1048 uint32_t u32ClientId));
1049
1050 /* The client has been disconnected.
1051 *
1052 * @param pvCallback The callback specific pointer.
1053 * @param u32ClientId An unique client identifier generated by the server.
1054 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
1055 */
1056 DECLR3CALLBACKMEMBER(void, VRDPCallbackClientDisconnect,(void *pvCallback,
1057 uint32_t u32ClientId,
1058 uint32_t fu32Intercepted));
1059 /* The client supports one of RDP channels.
1060 *
1061 * @param pvCallback The callback specific pointer.
1062 * @param u32ClientId An unique client identifier generated by the server.
1063 * @param fu32Intercept What the client wants to intercept. One of VRDP_CLIENT_INTERCEPT_* flags.
1064 * @param ppvIntercept The value to be passed to the channel specific callback.
1065 *
1066 * @return IPRT status code.
1067 */
1068 DECLR3CALLBACKMEMBER(int, VRDPCallbackIntercept,(void *pvCallback,
1069 uint32_t u32ClientId,
1070 uint32_t fu32Intercept,
1071 void **ppvIntercept));
1072
1073 /**
1074 * Called by the server when a reply is received from a client.
1075 *
1076 * @param pvCallback The callback specific pointer.
1077 * @param ppvIntercept The value returned by VRDPCallbackIntercept for the VRDP_CLIENT_INTERCEPT_USB.
1078 * @param u32ClientId Identifies the client that sent the reply.
1079 * @param u8Code The operation code VRDP_USB_REQ_*.
1080 * @param pvRet Points to data received from the client.
1081 * @param cbRet Size of the data in bytes.
1082 *
1083 * @return IPRT status code.
1084 */
1085 DECLR3CALLBACKMEMBER(int, VRDPCallbackUSB,(void *pvCallback,
1086 void *pvIntercept,
1087 uint32_t u32ClientId,
1088 uint8_t u8Code,
1089 const void *pvRet,
1090 uint32_t cbRet));
1091
1092 /**
1093 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
1094 * - (0) client announces available clipboard formats;
1095 * - (1) client requests clipboard data.
1096 *
1097 * @param pvCallback The callback specific pointer.
1098 * @param ppvIntercept The value returned by VRDPCallbackIntercept for the VRDP_CLIENT_INTERCEPT_CLIPBOARD.
1099 * @param u32ClientId Identifies the RDP client that sent the reply.
1100 * @param u32Function The cause of the callback.
1101 * @param u32Format Bitmask of reported formats or the format of received data.
1102 * @param pvData Reserved.
1103 * @param cbData Reserved.
1104 *
1105 * @return IPRT status code.
1106 */
1107 DECLR3CALLBACKMEMBER(int, VRDPCallbackClipboard,(void *pvCallback,
1108 void *pvIntercept,
1109 uint32_t u32ClientId,
1110 uint32_t u32Function,
1111 uint32_t u32Format,
1112 const void *pvData,
1113 uint32_t cbData));
1114
1115 /* The framebuffer information is queried.
1116 *
1117 * @param pvCallback The callback specific pointer.
1118 * @param uScreenId The framebuffer index.
1119 * @param pInfo The information structure to ber filled.
1120 *
1121 * @return Whether the framebuffer is available.
1122 */
1123 DECLR3CALLBACKMEMBER(bool, VRDPCallbackFramebufferQuery,(void *pvCallback,
1124 unsigned uScreenId,
1125 VRDPFRAMEBUFFERINFO *pInfo));
1126
1127 /* The framebuffer is locked.
1128 *
1129 * @param pvCallback The callback specific pointer.
1130 * @param uScreenId The framebuffer index.
1131 */
1132 DECLR3CALLBACKMEMBER(void, VRDPCallbackFramebufferLock,(void *pvCallback,
1133 unsigned uScreenId));
1134
1135 /* The framebuffer is unlocked.
1136 *
1137 * @param pvCallback The callback specific pointer.
1138 * @param uScreenId The framebuffer index.
1139 */
1140 DECLR3CALLBACKMEMBER(void, VRDPCallbackFramebufferUnlock,(void *pvCallback,
1141 unsigned uScreenId));
1142
1143 /* Input from the client.
1144 *
1145 * @param pvCallback The callback specific pointer.
1146 * @param pvInput The input information.
1147 * @param cbInput The size of the input information.
1148 */
1149 DECLR3CALLBACKMEMBER(void, VRDPCallbackInput,(void *pvCallback,
1150 int type,
1151 const void *pvInput,
1152 unsigned cbInput));
1153
1154 /* Video mode hint from the client.
1155 *
1156 * @param pvCallback The callback specific pointer.
1157 * @param cWidth Requested width.
1158 * @param cHeight Requested height.
1159 * @param cBitsPerPixel Requested color depth.
1160 * @param uScreenId The framebuffer index.
1161 */
1162 DECLR3CALLBACKMEMBER(void, VRDPCallbackVideoModeHint,(void *pvCallback,
1163 unsigned cWidth,
1164 unsigned cHeight,
1165 unsigned cBitsPerPixel,
1166 unsigned uScreenId));
1167
1168} VRDPCALLBACKS_1;
1169
1170/* Callbacks are the same for the version 1 and version 2 interfaces. */
1171typedef VRDPCALLBACKS_1 VRDPCALLBACKS_2;
1172
1173/**
1174 * Create a new VRDP server instance. The instance is fully functional but refuses
1175 * client connections until the entry point VRDPEnableConnections is called by the application.
1176 *
1177 * The caller prepares the callbacks structure. The header.u64Version field
1178 * must be initialized with the version of the insterface to use.
1179 * The server will initialize the callbacks table to match the requested interface.
1180 *
1181 * @param pCallback Pointer to the application callbacks which let the server to fetch
1182 * the configuration data and to access the desktop.
1183 * @param pvCallback The callback specific pointer to be passed back to the application.
1184 * @param ppEntryPoints Where to store the pointer to the VRDP entry points structure.
1185 * @param phServer Pointer to the created server instance handle.
1186 *
1187 * @return IPRT status code.
1188 */
1189VRDPDECL(int) VRDPCreateServer (const VRDPINTERFACEHDR *pCallbacks,
1190 void *pvCallback,
1191 VRDPINTERFACEHDR **ppEntryPoints,
1192 HVRDPSERVER *phServer);
1193
1194typedef DECLCALLBACK(int) FNVRDPCREATESERVER (const VRDPINTERFACEHDR *pCallbacks,
1195 void *pvCallback,
1196 VRDPINTERFACEHDR **ppEntryPoints,
1197 HVRDPSERVER *phServer);
1198typedef FNVRDPCREATESERVER *PFNVRDPCREATESERVER;
1199
1200RT_C_DECLS_END
1201
1202/** @} */
1203
1204#endif
1205
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use