VirtualBox

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

Last change on this file since 12954 was 12297, checked in by vboxsync, 16 years ago

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