VirtualBox

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

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

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