VirtualBox

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

Last change on this file since 3700 was 3633, checked in by vboxsync, 18 years ago

VBox_hdr_h -> _VBox_hdr_h

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 52.8 KB
Line 
1/** @file
2 * VBox Remote Desktop Protocol:
3 * Public APIs.
4 */
5
6/*
7 * Copyright (C) 2006-2007 innotek GmbH
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 as published by the Free Software Foundation,
13 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
14 * distribution. VirtualBox OSE is distributed in the hope that it will
15 * be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * If you received this file as part of a commercial VirtualBox
18 * distribution, then only the terms of your commercial VirtualBox
19 * license agreement apply instead of the previous paragraph.
20 */
21
22#ifndef ___VBox_vrdpapi_h
23#define ___VBox_vrdpapi_h
24
25#ifdef VRDP_NO_COM
26#include <iprt/cdefs.h>
27#include <iprt/types.h>
28#else
29#include <VBox/cdefs.h>
30#include <VBox/types.h>
31#endif /* VRDP_NO_COM */
32
33#ifdef IN_RING0
34# error "There are no VRDP APIs available in Ring-0 Host Context!"
35#endif
36#ifdef IN_GC
37# error "There are no VRDP APIs available Guest Context!"
38#endif
39
40
41/** @defgroup grp_vrdp VRDP
42 * VirtualBox Remote Desktop Protocol (VRDP) interface that lets to use
43 * the VRDP server.
44 * @{
45 */
46
47/** Default port that VRDP binds to. */
48#define VRDP_DEFAULT_PORT (3389)
49
50__BEGIN_DECLS
51
52/* Forward declaration of the VRDP server instance handle. */
53#ifdef __cplusplus
54class VRDPServer;
55typedef class VRDPServer *HVRDPSERVER;
56#else
57struct VRDPServer;
58typedef struct VRDPServer *HVRDPSERVER;
59#endif /* __cplusplus */
60
61#ifdef VRDP_NO_COM
62/* New, callback based VRDP server interface declarations. */
63
64#if defined(IN_VRDP)
65# define VRDPDECL(type) DECLEXPORT(type) RTCALL
66#else
67# define VRDPDECL(type) DECLIMPORT(type) RTCALL
68#endif /* IN_VRDP */
69
70/** The color mouse pointer information. */
71typedef struct _VRDPCOLORPOINTER
72{
73 uint16_t u16HotX;
74 uint16_t u16HotY;
75 uint16_t u16Width;
76 uint16_t u16Height;
77 uint16_t u16MaskLen;
78 uint16_t u16DataLen;
79 /* The mask and the bitmap follow. */
80} VRDPCOLORPOINTER;
81
82/** Audio format information packed in a 32 bit value. */
83typedef uint32_t VRDPAUDIOFORMAT;
84
85/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
86#define VRDP_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
87
88/** Decode frequency. */
89#define VRDP_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
90/** Decode number of channels. */
91#define VRDP_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
92/** Decode number signess. */
93#define VRDP_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
94/** Decode number of bits per sample. */
95#define VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
96/** Decode number of bytes per sample. */
97#define VRDP_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
98
99/*
100 * Remote USB protocol.
101 */
102
103/* The version of Remote USB Protocol. */
104#define VRDP_USB_VERSION (1)
105
106/** USB backend operations. */
107#define VRDP_USB_REQ_OPEN (0)
108#define VRDP_USB_REQ_CLOSE (1)
109#define VRDP_USB_REQ_RESET (2)
110#define VRDP_USB_REQ_SET_CONFIG (3)
111#define VRDP_USB_REQ_CLAIM_INTERFACE (4)
112#define VRDP_USB_REQ_RELEASE_INTERFACE (5)
113#define VRDP_USB_REQ_INTERFACE_SETTING (6)
114#define VRDP_USB_REQ_QUEUE_URB (7)
115#define VRDP_USB_REQ_REAP_URB (8)
116#define VRDP_USB_REQ_CLEAR_HALTED_EP (9)
117#define VRDP_USB_REQ_CANCEL_URB (10)
118
119/** USB service operations. */
120#define VRDP_USB_REQ_DEVICE_LIST (11)
121#define VRDP_USB_REQ_NEGOTIATE (12)
122
123/** An operation completion status is a byte. */
124typedef uint8_t VRDPUSBSTATUS;
125
126/** USB device identifier is an 32 bit value. */
127typedef uint32_t VRDPUSBDEVID;
128
129/** Status codes. */
130#define VRDP_USB_STATUS_SUCCESS ((VRDPUSBSTATUS)0)
131#define VRDP_USB_STATUS_ACCESS_DENIED ((VRDPUSBSTATUS)1)
132#define VRDP_USB_STATUS_DEVICE_REMOVED ((VRDPUSBSTATUS)2)
133
134/*
135 * Data structures to use with VRDPUSBRequest.
136 * The *RET* structures always represent the layout of VRDP data.
137 * The *PARM* structures normally the same as VRDP layout.
138 * However the VRDP_USB_REQ_QUEUE_URB_PARM has a pointer to
139 * URB data in place where actual data will be in VRDP layout.
140 *
141 * Since replies (*RET*) are asynchronous, the 'success'
142 * replies are not required for operations which return
143 * only the status code (VRDPUSBREQRETHDR only):
144 * VRDP_USB_REQ_OPEN
145 * VRDP_USB_REQ_RESET
146 * VRDP_USB_REQ_SET_CONFIG
147 * VRDP_USB_REQ_CLAIM_INTERFACE
148 * VRDP_USB_REQ_RELEASE_INTERFACE
149 * VRDP_USB_REQ_INTERFACE_SETTING
150 * VRDP_USB_REQ_CLEAR_HALTED_EP
151 *
152 */
153
154/* VRDP layout has no aligments. */
155#pragma pack(1)
156/* Common header for all VRDP USB packets. After the reply hdr follows *PARM* or *RET* data. */
157typedef struct _VRDPUSBPKTHDR
158{
159 /* Total length of the reply NOT including the 'length' field. */
160 uint32_t length;
161 /* The operation code for which the reply was sent by the client. */
162 uint8_t code;
163} VRDPUSBPKTHDR;
164
165/* Common header for all return structures. */
166typedef struct _VRDPUSBREQRETHDR
167{
168 /* Device status. */
169 VRDPUSBSTATUS status;
170 /* Device id. */
171 VRDPUSBDEVID id;
172} VRDPUSBREQRETHDR;
173
174
175/* VRDP_USB_REQ_OPEN
176 */
177typedef struct _VRDP_USB_REQ_OPEN_PARM
178{
179 uint8_t code;
180 VRDPUSBDEVID id;
181} VRDP_USB_REQ_OPEN_PARM;
182
183typedef struct _VRDP_USB_REQ_OPEN_RET
184{
185 VRDPUSBREQRETHDR hdr;
186} VRDP_USB_REQ_OPEN_RET;
187
188
189/* VRDP_USB_REQ_CLOSE
190 */
191typedef struct _VRDP_USB_REQ_CLOSE_PARM
192{
193 uint8_t code;
194 VRDPUSBDEVID id;
195} VRDP_USB_REQ_CLOSE_PARM;
196
197/* The close request has no returned data. */
198
199
200/* VRDP_USB_REQ_RESET
201 */
202typedef struct _VRDP_USB_REQ_RESET_PARM
203{
204 uint8_t code;
205 VRDPUSBDEVID id;
206} VRDP_USB_REQ_RESET_PARM;
207
208typedef struct _VRDP_USB_REQ_RESET_RET
209{
210 VRDPUSBREQRETHDR hdr;
211} VRDP_USB_REQ_RESET_RET;
212
213
214/* VRDP_USB_REQ_SET_CONFIG
215 */
216typedef struct _VRDP_USB_REQ_SET_CONFIG_PARM
217{
218 uint8_t code;
219 VRDPUSBDEVID id;
220 uint8_t configuration;
221} VRDP_USB_REQ_SET_CONFIG_PARM;
222
223typedef struct _VRDP_USB_REQ_SET_CONFIG_RET
224{
225 VRDPUSBREQRETHDR hdr;
226} VRDP_USB_REQ_SET_CONFIG_RET;
227
228
229/* VRDP_USB_REQ_CLAIM_INTERFACE
230 */
231typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_PARM
232{
233 uint8_t code;
234 VRDPUSBDEVID id;
235 uint8_t iface;
236} VRDP_USB_REQ_CLAIM_INTERFACE_PARM;
237
238typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_RET
239{
240 VRDPUSBREQRETHDR hdr;
241} VRDP_USB_REQ_CLAIM_INTERFACE_RET;
242
243
244/* VRDP_USB_REQ_RELEASE_INTERFACE
245 */
246typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_PARM
247{
248 uint8_t code;
249 VRDPUSBDEVID id;
250 uint8_t iface;
251} VRDP_USB_REQ_RELEASE_INTERFACE_PARM;
252
253typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_RET
254{
255 VRDPUSBREQRETHDR hdr;
256} VRDP_USB_REQ_RELEASE_INTERFACE_RET;
257
258
259/* VRDP_USB_REQ_INTERFACE_SETTING
260 */
261typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_PARM
262{
263 uint8_t code;
264 VRDPUSBDEVID id;
265 uint8_t iface;
266 uint8_t setting;
267} VRDP_USB_REQ_INTERFACE_SETTING_PARM;
268
269typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_RET
270{
271 VRDPUSBREQRETHDR hdr;
272} VRDP_USB_REQ_INTERFACE_SETTING_RET;
273
274
275/* VRDP_USB_REQ_QUEUE_URB
276 */
277
278#define VRDP_USB_TRANSFER_TYPE_CTRL (0)
279#define VRDP_USB_TRANSFER_TYPE_ISOC (1)
280#define VRDP_USB_TRANSFER_TYPE_BULK (2)
281#define VRDP_USB_TRANSFER_TYPE_INTR (3)
282#define VRDP_USB_TRANSFER_TYPE_MSG (4)
283
284#define VRDP_USB_DIRECTION_SETUP (0)
285#define VRDP_USB_DIRECTION_IN (1)
286#define VRDP_USB_DIRECTION_OUT (2)
287
288typedef struct _VRDP_USB_REQ_QUEUE_URB_PARM
289{
290 uint8_t code;
291 VRDPUSBDEVID id;
292 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
293 uint8_t type;
294 uint8_t ep;
295 uint8_t direction;
296 uint32_t urblen; /* Length of the URB. */
297 uint32_t datalen; /* Length of the data. */
298 void *data; /* In RDP layout the data follow. */
299} VRDP_USB_REQ_QUEUE_URB_PARM;
300
301/* The queue URB has no explicit return. The reap URB reply will be
302 * eventually the indirect result.
303 */
304
305
306/* VRDP_USB_REQ_REAP_URB
307 * Notificationg from server to client that server expects an URB
308 * from any device.
309 * Only sent if negotiated URB return method is polling.
310 * Normally, the client will send URBs back as soon as they are ready.
311 */
312typedef struct _VRDP_USB_REQ_REAP_URB_PARM
313{
314 uint8_t code;
315} VRDP_USB_REQ_REAP_URB_PARM;
316
317
318#define VRDP_USB_XFER_OK (0)
319#define VRDP_USB_XFER_STALL (1)
320#define VRDP_USB_XFER_DNR (2)
321#define VRDP_USB_XFER_CRC (3)
322
323#define VRDP_USB_REAP_FLAG_CONTINUED (0x0)
324#define VRDP_USB_REAP_FLAG_LAST (0x1)
325
326#define VRDP_USB_REAP_VALID_FLAGS (VRDP_USB_REAP_FLAG_LAST)
327
328typedef struct _VRDPUSBREQREAPURBBODY
329{
330 VRDPUSBDEVID id; /* From which device the URB arrives. */
331 uint8_t flags; /* VRDP_USB_REAP_FLAG_* */
332 uint8_t error; /* VRDP_USB_XFER_* */
333 uint32_t handle; /* Handle of returned URB. Not 0. */
334 uint32_t len; /* Length of data actually transferred. */
335 /* Data follow. */
336} VRDPUSBREQREAPURBBODY;
337
338typedef struct _VRDP_USB_REQ_REAP_URB_RET
339{
340 /* The REAP URB has no header, only completed URBs are returned. */
341 VRDPUSBREQREAPURBBODY body;
342 /* Another body may follow, depending on flags. */
343} VRDP_USB_REQ_REAP_URB_RET;
344
345
346/* VRDP_USB_REQ_CLEAR_HALTED_EP
347 */
348typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_PARM
349{
350 uint8_t code;
351 VRDPUSBDEVID id;
352 uint8_t ep;
353} VRDP_USB_REQ_CLEAR_HALTED_EP_PARM;
354
355typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_RET
356{
357 VRDPUSBREQRETHDR hdr;
358} VRDP_USB_REQ_CLEAR_HALTED_EP_RET;
359
360
361/* VRDP_USB_REQ_CANCEL_URB
362 */
363typedef struct _VRDP_USB_REQ_CANCEL_URB_PARM
364{
365 uint8_t code;
366 VRDPUSBDEVID id;
367 uint32_t handle;
368} VRDP_USB_REQ_CANCEL_URB_PARM;
369
370/* The cancel URB request has no return. */
371
372
373/* VRDP_USB_REQ_DEVICE_LIST
374 *
375 * Server polls USB devices on client by sending this request
376 * periodically. Client sends back a list of all devices
377 * connected to it. Each device is assigned with an identifier,
378 * that is used to distinguish the particular device.
379 */
380typedef struct _VRDP_USB_REQ_DEVICE_LIST_PARM
381{
382 uint8_t code;
383} VRDP_USB_REQ_DEVICE_LIST_PARM;
384
385/* Data is a list of the following variable length structures. */
386typedef struct _VRDPUSBDEVICEDESC
387{
388 /* Offset of the next structure. 0 if last. */
389 uint16_t oNext;
390
391 /* Identifier of the device assigned by client. */
392 VRDPUSBDEVID id;
393
394 /** USB version number. */
395 uint16_t bcdUSB;
396 /** Device class. */
397 uint8_t bDeviceClass;
398 /** Device subclass. */
399 uint8_t bDeviceSubClass;
400 /** Device protocol */
401 uint8_t bDeviceProtocol;
402 /** Vendor ID. */
403 uint16_t idVendor;
404 /** Product ID. */
405 uint16_t idProduct;
406 /** Revision, integer part. */
407 uint16_t bcdRev;
408 /** Manufacturer string. */
409 uint16_t oManufacturer;
410 /** Product string. */
411 uint16_t oProduct;
412 /** Serial number string. */
413 uint16_t oSerialNumber;
414 /** Physical USB port the device is connected to. */
415 uint16_t idPort;
416
417} VRDPUSBDEVICEDESC;
418
419typedef struct _VRDP_USB_REQ_DEVICE_LIST_RET
420{
421 VRDPUSBDEVICEDESC body;
422 /* Other devices may follow.
423 * The list ends with (uint16_t)0,
424 * which means that an empty list consists of 2 zero bytes.
425 */
426} VRDP_USB_REQ_DEVICE_LIST_RET;
427
428typedef struct _VRDPUSBREQNEGOTIATEPARM
429{
430 uint8_t code;
431
432 /* Remote USB Protocol version. */
433 uint32_t version;
434
435} VRDPUSBREQNEGOTIATEPARM;
436
437#define VRDP_USB_CAPS_FLAG_ASYNC (0x0)
438#define VRDP_USB_CAPS_FLAG_POLL (0x1)
439
440#define VRDP_USB_CAPS_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL)
441
442typedef struct _VRDPUSBREQNEGOTIATERET
443{
444 uint8_t flags;
445} VRDPUSBREQNEGOTIATERET;
446#pragma pack()
447
448#define VRDP_CLIPBOARD_FORMAT_NULL (0x0)
449#define VRDP_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
450#define VRDP_CLIPBOARD_FORMAT_BITMAP (0x2)
451#define VRDP_CLIPBOARD_FORMAT_HTML (0x4)
452
453#define VRDP_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
454#define VRDP_CLIPBOARD_FUNCTION_DATA_READ (1)
455#define VRDP_CLIPBOARD_FUNCTION_DATA_WRITE (2)
456
457
458/** Indexes of information values. */
459
460/** Whether a client is connected at the moment.
461 * uint32_t
462 */
463#define VRDP_QI_ACTIVE (0)
464
465/** How many times a client connected up to current moment.
466 * uint32_t
467 */
468#define VRDP_QI_NUMBER_OF_CLIENTS (1)
469
470/** When last connection was established.
471 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
472 */
473#define VRDP_QI_BEGIN_TIME (2)
474
475/** When last connection was terminated or current time if connection still active.
476 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
477 */
478#define VRDP_QI_END_TIME (3)
479
480/** How many bytes were sent in last (current) connection.
481 * uint64_t
482 */
483#define VRDP_QI_BYTES_SENT (4)
484
485/** How many bytes were sent in all connections.
486 * uint64_t
487 */
488#define VRDP_QI_BYTES_SENT_TOTAL (5)
489
490/** How many bytes were received in last (current) connection.
491 * uint64_t
492 */
493#define VRDP_QI_BYTES_RECEIVED (6)
494
495/** How many bytes were received in all connections.
496 * uint64_t
497 */
498#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
499
500/** Login user name supplied by the client.
501 * UTF8 nul terminated string.
502 */
503#define VRDP_QI_USER (8)
504
505/** Login domain supplied by the client.
506 * UTF8 nul terminated string.
507 */
508#define VRDP_QI_DOMAIN (9)
509
510/** The client name supplied by the client.
511 * UTF8 nul terminated string.
512 */
513#define VRDP_QI_CLIENT_NAME (10)
514
515/** IP address of the client.
516 * UTF8 nul terminated string.
517 */
518#define VRDP_QI_CLIENT_IP (11)
519
520/** The client software version number.
521 * uint32_t.
522 */
523#define VRDP_QI_CLIENT_VERSION (12)
524
525/** Public key exchange method used when connection was established.
526 * Values: 0 - RDP4 public key exchange scheme.
527 * 1 - X509 sertificates were sent to client.
528 * uint32_t.
529 */
530#define VRDP_QI_ENCRYPTION_STYLE (13)
531
532
533/** Hints what has been intercepted by the application. */
534#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
535#define VRDP_CLIENT_INTERCEPT_USB (0x2)
536#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
537
538
539/** The version of the VRDP server interface. */
540#define VRDP_INTERFACE_VERSION_1 (1)
541
542/** The header that does not change when the interface changes. */
543typedef struct _VRDPINTERFACEHDR
544{
545 /** The version of the interface. */
546 uint64_t u64Version;
547
548 /** The size of the structure. */
549 uint64_t u64Size;
550
551} VRDPINTERFACEHDR;
552
553/** The VRDP server entry points. Interface version 1. */
554typedef struct _VRDPENTRYPOINTS_1
555{
556 /** The header. */
557 VRDPINTERFACEHDR header;
558
559 /** Destroy the server instance.
560 *
561 * @param hServer The server instance handle.
562 *
563 * @return IPRT status code.
564 */
565 DECLCALLBACKMEMBER(void, VRDPDestroy)(HVRDPSERVER hServer);
566
567 /** The server should start to accept clients connections.
568 *
569 * @param hServer The server instance handle.
570 * @param fEnable Whether to enable or disable client connections.
571 * When is false, all existing clients are disconnected.
572 *
573 * @return IPRT status code.
574 */
575 DECLCALLBACKMEMBER(int, VRDPEnableConnections)(HVRDPSERVER hServer,
576 bool fEnable);
577
578 /** The server should disconnect the client.
579 *
580 * @param hServer The server instance handle.
581 * @param u32ClientId The client identifier.
582 * @param fReconnect Whether to send a "REDIRECT to the same server" packet to the
583 * client before disconnecting.
584 *
585 * @return IPRT status code.
586 */
587 DECLCALLBACKMEMBER(void, VRDPDisconnect)(HVRDPSERVER hServer,
588 uint32_t u32ClientId,
589 bool fReconnect);
590
591 /**
592 * Inform the server that the display was resized.
593 * The server will query information about display
594 * from the application via callbacks.
595 *
596 * @param hServer Handle of VRDP server instance.
597 */
598 DECLCALLBACKMEMBER(void, VRDPResize)(HVRDPSERVER hServer);
599
600 /**
601 * Send a update.
602 *
603 * @param hServer Handle of VRDP server instance.
604 * @param uScreenId The screen index.
605 * @param pvUpdate Pointer to VBoxGuest.h::VRDPORDERHDR structure with extra data.
606 * @param cbUpdate Size of the update data.
607 */
608 DECLCALLBACKMEMBER(void, VRDPUpdate)(HVRDPSERVER hServer,
609 unsigned uScreenId,
610 void *pvUpdate,
611 uint32_t cbUpdate);
612
613 /**
614 * Set the mouse pointer shape.
615 *
616 * @param hServer Handle of VRDP server instance.
617 * @param pPointer The pointer shape information.
618 */
619 DECLCALLBACKMEMBER(void, VRDPColorPointer)(HVRDPSERVER hServer,
620 const VRDPCOLORPOINTER *pPointer);
621
622 /**
623 * Hide the mouse pointer.
624 *
625 * @param hServer Handle of VRDP server instance.
626 */
627 DECLCALLBACKMEMBER(void, VRDPHidePointer)(HVRDPSERVER hServer);
628
629 /**
630 * Queues the samples to be sent to clients.
631 *
632 * @param hServer Handle of VRDP server instance.
633 * @param pvSamples Address of samples to be sent.
634 * @param cSamples Number of samples.
635 * @param format Encoded audio format for these samples.
636 *
637 * @note Initialized to NULL when the application audio callbacks are NULL.
638 */
639 DECLCALLBACKMEMBER(void, VRDPAudioSamples)(HVRDPSERVER hServer,
640 const void *pvSamples,
641 uint32_t cSamples,
642 VRDPAUDIOFORMAT format);
643
644 /**
645 * Sets the sound volume on clients.
646 *
647 * @param hServer Handle of VRDP server instance.
648 * @param left 0..0xFFFF volume level for left channel.
649 * @param right 0..0xFFFF volume level for right channel.
650 *
651 * @note Initialized to NULL when the application audio callbacks are NULL.
652 */
653 DECLCALLBACKMEMBER(void, VRDPAudioVolume)(HVRDPSERVER hServer,
654 uint16_t u16Left,
655 uint16_t u16Right);
656
657 /**
658 * Sends a USB request.
659 *
660 * @param hServer Handle of VRDP server instance.
661 * @param u32ClientId An identifier that allows the server to find the corresponding client.
662 * The identifier is always passed by the server as a parameter
663 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
664 * in the VRDPSERVERCALLBACK functions.
665 * @param pvParm Function specific parameters buffer.
666 * @param cbParm Size of the buffer.
667 *
668 * @note Initialized to NULL when the application USB callbacks are NULL.
669 */
670 DECLCALLBACKMEMBER(void, VRDPUSBRequest)(HVRDPSERVER hServer,
671 uint32_t u32ClientId,
672 void *pvParm,
673 uint32_t cbParm);
674
675 /**
676 * Called by the application when (VRDP_CLIPBOARD_FUNCTION_*):
677 * - (0) guest announces available clipboard formats;
678 * - (1) guest requests clipboard data;
679 * - (2) guest responds to the client's request for clipboard data.
680 *
681 * @param hServer The VRDP server handle.
682 * @param u32Function The cause of the call.
683 * @param u32Format Bitmask of announced formats or the format of data.
684 * @param pvData Points to: (1) buffer to be filled with clients data;
685 * (2) data from the host.
686 * @param cbData Size of 'pvData' buffer in bytes.
687 * @param pcbActualRead Size of the copied data in bytes.
688 *
689 * @note Initialized to NULL when the application clipboard callbacks are NULL.
690 */
691 DECLCALLBACKMEMBER(void, VRDPClipboard)(HVRDPSERVER hServer,
692 uint32_t u32Function,
693 uint32_t u32Format,
694 void *pvData,
695 uint32_t cbData,
696 uint32_t *pcbActualRead);
697
698 /**
699 * Query various information from the VRDP server.
700 *
701 * @param hServer The VRDP server handle.
702 * @param index VRDP_QI_* identifier of information to be returned.
703 * @param pvBuffer Address of memory buffer to which the information must be written.
704 * @param cbBuffer Size of the memory buffer in bytes.
705 * @param pcbOut Size in bytes of returned information value.
706 *
707 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
708 * A value greater than cbBuffer means that information is too big to fit in the
709 * buffer, in that case no information was placed to the buffer.
710 */
711 DECLCALLBACKMEMBER(void, VRDPQueryInfo)(HVRDPSERVER hServer,
712 uint32_t index,
713 void *pvBuffer,
714 uint32_t cbBuffer,
715 uint32_t *pcbOut);
716} VRDPENTRYPOINTS_1;
717
718#define VRDP_QP_NETWORK_PORT (1)
719#define VRDP_QP_NETWORK_ADDRESS (2)
720#define VRDP_QP_NUMBER_MONITORS (3)
721
722#pragma pack(1)
723/* A framebuffer description. */
724typedef struct _VRDPFRAMEBUFFERINFO
725{
726 const uint8_t *pu8Bits;
727 int xOrigin;
728 int yOrigin;
729 unsigned cWidth;
730 unsigned cHeight;
731 unsigned cBitsPerPixel;
732 unsigned cbLine;
733} VRDPFRAMEBUFFERINFO;
734
735#define VRDP_INPUT_SCANCODE 0
736#define VRDP_INPUT_POINT 1
737#define VRDP_INPUT_CAD 2
738#define VRDP_INPUT_RESET 3
739
740typedef struct _VRDPINPUTSCANCODE
741{
742 unsigned uScancode;
743} VRDPINPUTSCANCODE;
744
745#define VRDP_INPUT_POINT_BUTTON1 0x01
746#define VRDP_INPUT_POINT_BUTTON2 0x02
747#define VRDP_INPUT_POINT_BUTTON3 0x04
748#define VRDP_INPUT_POINT_WHEEL_UP 0x08
749#define VRDP_INPUT_POINT_WHEEL_DOWN 0x10
750
751typedef struct _VRDPINPUTPOINT
752{
753 int x;
754 int y;
755 unsigned uButtons;
756} VRDPINPUTPOINT;
757#pragma pack()
758
759/** The VRDP server callbacks. Interface version 1. */
760typedef struct _VRDPCALLBACKS_1
761{
762 /** The header. */
763 VRDPINTERFACEHDR header;
764
765 /**
766 * Query various information, on how the VRDP server must operate, from the application.
767 *
768 * @param pvCallback The callback specific pointer.
769 * @param index VRDP_QP_* identifier of information to be returned.
770 * @param pvBuffer Address of memory buffer to which the information must be written.
771 * @param cbBuffer Size of the memory buffer in bytes.
772 * @param pcbOut Size in bytes of returned information value.
773 *
774 * @return IPRT status code. VINF_BUFFER_OVERFLOW if the buffer is too small for the value.
775 */
776 DECLCALLBACKMEMBER(int, VRDPCallbackQueryProperty)(void *pvCallback,
777 uint32_t index,
778 void *pvBuffer,
779 uint32_t cbBuffer,
780 uint32_t *pcbOut);
781
782 /* A client is logging in, the application must decide whether
783 * to let to connect the client. The server will drop the connection,
784 * when an error code is returned by the callback.
785 *
786 * @param pvCallback The callback specific pointer.
787 * @param u32ClientId An unique client identifier generated by the server.
788 * @param pszUser The username.
789 * @param pszPassword The password.
790 * @param pszDomain The domain.
791 *
792 * @return IPRT status code.
793 */
794 DECLCALLBACKMEMBER(int, VRDPCallbackClientLogon)(void *pvCallback,
795 uint32_t u32ClientId,
796 const char *pszUser,
797 const char *pszPassword,
798 const char *pszDomain);
799
800 /* The client has been successfully connected.
801 *
802 * @param pvCallback The callback specific pointer.
803 * @param u32ClientId An unique client identifier generated by the server.
804 */
805 DECLCALLBACKMEMBER(void, VRDPCallbackClientConnect)(void *pvCallback,
806 uint32_t u32ClientId);
807
808 /* The client has been disconnected.
809 *
810 * @param pvCallback The callback specific pointer.
811 * @param u32ClientId An unique client identifier generated by the server.
812 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
813 */
814 DECLCALLBACKMEMBER(void, VRDPCallbackClientDisconnect)(void *pvCallback,
815 uint32_t u32ClientId,
816 uint32_t fu32Intercepted);
817 /* The client supports one of RDP channels.
818 *
819 * @param pvCallback The callback specific pointer.
820 * @param u32ClientId An unique client identifier generated by the server.
821 * @param fu32Intercept What the client wants to intercept. One of VRDP_CLIENT_INTERCEPT_* flags.
822 * @param ppvIntercept The value to be passed to the channel specific callback.
823 *
824 * @return IPRT status code.
825 */
826 DECLCALLBACKMEMBER(int, VRDPCallbackIntercept)(void *pvCallback,
827 uint32_t u32ClientId,
828 uint32_t fu32Intercept,
829 void **ppvIntercept);
830
831 /**
832 * Called by the server when a reply is received from a client.
833 *
834 * @param pvCallback The callback specific pointer.
835 * @param ppvIntercept The value returned by VRDPCallbackIntercept for the VRDP_CLIENT_INTERCEPT_USB.
836 * @param u32ClientId Identifies the client that sent the reply.
837 * @param u8Code The operation code VRDP_USB_REQ_*.
838 * @param pvRet Points to data received from the client.
839 * @param cbRet Size of the data in bytes.
840 *
841 * @return IPRT status code.
842 */
843 DECLCALLBACKMEMBER(int, VRDPCallbackUSB)(void *pvCallback,
844 void *pvIntercept,
845 uint32_t u32ClientId,
846 uint8_t u8Code,
847 const void *pvRet,
848 uint32_t cbRet);
849
850 /**
851 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
852 * - (0) client announces available clipboard formats;
853 * - (1) client requests clipboard data.
854 *
855 * @param pvCallback The callback specific pointer.
856 * @param ppvIntercept The value returned by VRDPCallbackIntercept for the VRDP_CLIENT_INTERCEPT_CLIPBOARD.
857 * @param u32ClientId Identifies the RDP client that sent the reply.
858 * @param u32Function The cause of the callback.
859 * @param u32Format Bitmask of reported formats or the format of received data.
860 * @param pvData Reserved.
861 * @param cbData Reserved.
862 *
863 * @return IPRT status code.
864 */
865 DECLCALLBACKMEMBER(int, VRDPCallbackClipboard)(void *pvCallback,
866 void *pvIntercept,
867 uint32_t u32ClientId,
868 uint32_t u32Function,
869 uint32_t u32Format,
870 const void *pvData,
871 uint32_t cbData);
872
873 /* The framebuffer information is queried.
874 *
875 * @param pvCallback The callback specific pointer.
876 * @param uScreenId The framebuffer index.
877 * @param pInfo The information structure to ber filled.
878 *
879 * @return Whether the framebuffer is available.
880 */
881 DECLCALLBACKMEMBER(bool, VRDPCallbackFramebufferQuery)(void *pvCallback,
882 unsigned uScreenId,
883 VRDPFRAMEBUFFERINFO *pInfo);
884
885 /* The framebuffer is locked.
886 *
887 * @param pvCallback The callback specific pointer.
888 * @param uScreenId The framebuffer index.
889 */
890 DECLCALLBACKMEMBER(void, VRDPCallbackFramebufferLock)(void *pvCallback,
891 unsigned uScreenId);
892
893 /* The framebuffer is unlocked.
894 *
895 * @param pvCallback The callback specific pointer.
896 * @param uScreenId The framebuffer index.
897 */
898 DECLCALLBACKMEMBER(void, VRDPCallbackFramebufferUnlock)(void *pvCallback,
899 unsigned uScreenId);
900
901 /* Input from the client.
902 *
903 * @param pvCallback The callback specific pointer.
904 * @param pvInput The input information.
905 * @param cbInput The size of the input information.
906 */
907 DECLCALLBACKMEMBER(void, VRDPCallbackInput)(void *pvCallback,
908 const void *pvInput,
909 unsigned cbInput);
910
911 /* Video mode hint from the client.
912 *
913 * @param pvCallback The callback specific pointer.
914 * @param cWidth Requested width.
915 * @param cHeight Requested height.
916 * @param cBitsPerPixel Requested color depth.
917 * @param uScreenId The framebuffer index.
918 */
919 DECLCALLBACKMEMBER(void, VRDPCallbackVideoModeHint)(void *pvCallback,
920 unsigned cWidth,
921 unsigned cHeight,
922 unsigned cBitsPerPixel,
923 unsigned uScreenId);
924
925} VRDPCALLBACKS_1;
926
927/**
928 * Create a new VRDP server instance. The instance is fully functional but refuses
929 * client connections until the entry point VRDPEnableConnections is called by the application.
930 *
931 * The caller prepares the callbacks structure. The header.u64Version field
932 * must be initialized with the version of the insterface to use.
933 * The server will initialize the callbacks table to match the requested interface.
934 *
935 * @param pCallback Pointer to the application callbacks which let the server to fetch
936 * the configuration data and to access the desktop.
937 * @param pvCallback The callback specific pointer to be passed back to the application.
938 * @param ppEntryPoints Where to store the pointer to the VRDP entry points structure.
939 * @param phServer Pointer to the created server instance handle.
940 *
941 * @return IPRT status code.
942 */
943VRDPDECL(int) VRDPCreateServer (const VRDPINTERFACEHDR *pCallbacks,
944 void *pvCallback,
945 VRDPINTERFACEHDR **ppEntryPoints,
946 HVRDPSERVER *phServer);
947
948
949#else
950/**
951 * Start server for the specified IConsole.
952 *
953 * @return VBox status code
954 * @param pconsole Pointer to IConsole instance to fetch display, mouse and keyboard interfaces.
955 * @param pvrdpserver Pointer to IVRDPServer instance to fetch configuration.
956 * @param phserver Pointer to server instance handle,
957 * created by the function.
958 */
959VRDPR3DECL(int) VRDPStartServer (IConsole *pconsole, IVRDPServer *pvrdpserver, HVRDPSERVER *phserver);
960
961
962/**
963 * Shutdown server.
964 *
965 * @param hserver Handle of VRDP server instance to be stopped.
966 */
967VRDPR3DECL(void) VRDPShutdownServer (HVRDPSERVER hserver);
968
969
970/**
971 * Send framebuffer bitmap to client.
972 *
973 * @param hserver Handle of VRDP server instance.
974 * @param x top left horizontal coordinate in framebuffer.
975 * @param y top left vertical coordinate in framebuffer.
976 * @param w width of rectangle.
977 * @param h height of rectangle.
978 */
979VRDPR3DECL(void) VRDPSendUpdateBitmap (HVRDPSERVER hserver, unsigned uScreenId, unsigned x, unsigned y, unsigned w, unsigned h);
980
981/**
982 * Inform client that display was resized.
983 * New width and height are taken from the current framebuffer.
984 *
985 * @param hserver Handle of VRDP server instance.
986 */
987VRDPR3DECL(void) VRDPSendResize (HVRDPSERVER hserver);
988
989/**
990 * Send an update in accelerated mode.
991 *
992 * @param hserver Handle of VRDP server instance.
993 * @param pvUpdate The update information. Actually pointer to VBoxGuest.h::VBVACMDHDR structure with extra data.
994 * @param cbUpdate Size of the update data.
995 */
996VRDPR3DECL(void) VRDPSendUpdate (HVRDPSERVER hserver, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate);
997
998/** @todo comment the structure. */
999typedef struct _VRDPCOLORPOINTER
1000{
1001 uint16_t u16HotX;
1002 uint16_t u16HotY;
1003 uint16_t u16Width;
1004 uint16_t u16Height;
1005 uint16_t u16MaskLen;
1006 uint16_t u16DataLen;
1007 uint32_t vrdpInternal;
1008} VRDPCOLORPOINTER;
1009
1010typedef VRDPCOLORPOINTER *PVRDPCOLORPOINTER;
1011
1012/**
1013 * Set mouse pointer shape.
1014 *
1015 * @param hserver Handle of VRDP server instance.
1016 * @param porder The pointer shape information.
1017 */
1018VRDPR3DECL(void) VRDPSendColorPointer (HVRDPSERVER hserver, PVRDPCOLORPOINTER pdata);
1019
1020/**
1021 * Hide mouse pointer.
1022 *
1023 * @param hserver Handle of VRDP server instance.
1024 */
1025VRDPR3DECL(void) VRDPSendHidePointer (HVRDPSERVER hserver);
1026
1027/** Audio format information packed in a 32 bit value. */
1028typedef uint32_t VRDPAUDIOFORMAT;
1029
1030/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
1031#define VRDP_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
1032
1033/** Decode frequency. */
1034#define VRDP_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
1035/** Decode number of channels. */
1036#define VRDP_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
1037/** Decode number signess. */
1038#define VRDP_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
1039/** Decode number of bits per sample. */
1040#define VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
1041/** Decode number of bytes per sample. */
1042#define VRDP_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
1043
1044/**
1045 * Queues the samples to be sent to client.
1046 *
1047 * @param hserver Handle of VRDP server instance.
1048 * @param pvSamples Address of samples to be sent.
1049 * @param cSamples Number of samples.
1050 * @param format Encoded audio format for these samples.
1051 */
1052VRDPR3DECL(void) VRDPSendAudioSamples (HVRDPSERVER hserver, void *pvSamples, uint32_t cSamples, VRDPAUDIOFORMAT format);
1053
1054/**
1055 * Sets sound volume on client.
1056 *
1057 * @param hserver Handle of VRDP server instance.
1058 * @param left 0..0xFFFF volume level for left channel.
1059 * @param right 0..0xFFFF volume level for right channel.
1060 */
1061VRDPR3DECL(void) VRDPSendAudioVolume (HVRDPSERVER hserver, uint16_t left, uint16_t right);
1062
1063
1064/*
1065 * Remote USB backend protocol.
1066 */
1067
1068/* The version of Remote USB Protocol. */
1069#define VRDP_USB_VERSION (1)
1070
1071/** USB backend operations. */
1072#define VRDP_USB_REQ_OPEN (0)
1073#define VRDP_USB_REQ_CLOSE (1)
1074#define VRDP_USB_REQ_RESET (2)
1075#define VRDP_USB_REQ_SET_CONFIG (3)
1076#define VRDP_USB_REQ_CLAIM_INTERFACE (4)
1077#define VRDP_USB_REQ_RELEASE_INTERFACE (5)
1078#define VRDP_USB_REQ_INTERFACE_SETTING (6)
1079#define VRDP_USB_REQ_QUEUE_URB (7)
1080#define VRDP_USB_REQ_REAP_URB (8)
1081#define VRDP_USB_REQ_CLEAR_HALTED_EP (9)
1082#define VRDP_USB_REQ_CANCEL_URB (10)
1083
1084/** USB service operations. */
1085#define VRDP_USB_REQ_DEVICE_LIST (11)
1086#define VRDP_USB_REQ_NEGOTIATE (12)
1087
1088/** An operation completion status is a byte. */
1089typedef uint8_t VRDPUSBSTATUS;
1090
1091/** USB device identifier is an 32 bit value. */
1092typedef uint32_t VRDPUSBDEVID;
1093
1094/** Status codes. */
1095#define VRDP_USB_STATUS_SUCCESS ((VRDPUSBSTATUS)0)
1096#define VRDP_USB_STATUS_ACCESS_DENIED ((VRDPUSBSTATUS)1)
1097#define VRDP_USB_STATUS_DEVICE_REMOVED ((VRDPUSBSTATUS)2)
1098
1099/*
1100 * Data structures to use with VRDPSendUSBRequest.
1101 * The *RET* structures always represent the layout of VRDP data.
1102 * The *PARM* structures normally the same as VRDP layout.
1103 * However the VRDP_USB_REQ_QUEUE_URB_PARM has a pointer to
1104 * URB data in place where actual data will be in VRDP layout.
1105 *
1106 * Since replies (*RET*) are asynchronous, the 'success'
1107 * replies are not required for operations which return
1108 * only the status code (VRDPUSBREQRETHDR only):
1109 * VRDP_USB_REQ_OPEN
1110 * VRDP_USB_REQ_RESET
1111 * VRDP_USB_REQ_SET_CONFIG
1112 * VRDP_USB_REQ_CLAIM_INTERFACE
1113 * VRDP_USB_REQ_RELEASE_INTERFACE
1114 * VRDP_USB_REQ_INTERFACE_SETTING
1115 * VRDP_USB_REQ_CLEAR_HALTED_EP
1116 *
1117 */
1118
1119/* VRDP layout has no aligments. */
1120#pragma pack(1)
1121
1122/* Common header for all VRDP USB packets. After the reply hdr follows *PARM* or *RET* data. */
1123typedef struct _VRDPUSBPKTHDR
1124{
1125 /* Total length of the reply NOT including the 'length' field. */
1126 uint32_t length;
1127 /* The operation code for which the reply was sent by the client. */
1128 uint8_t code;
1129} VRDPUSBPKTHDR;
1130
1131/* Common header for all return structures. */
1132typedef struct _VRDPUSBREQRETHDR
1133{
1134 /* Device status. */
1135 VRDPUSBSTATUS status;
1136 /* Device id. */
1137 VRDPUSBDEVID id;
1138} VRDPUSBREQRETHDR;
1139
1140
1141/* VRDP_USB_REQ_OPEN
1142 */
1143typedef struct _VRDP_USB_REQ_OPEN_PARM
1144{
1145 uint8_t code;
1146 VRDPUSBDEVID id;
1147} VRDP_USB_REQ_OPEN_PARM;
1148
1149typedef struct _VRDP_USB_REQ_OPEN_RET
1150{
1151 VRDPUSBREQRETHDR hdr;
1152} VRDP_USB_REQ_OPEN_RET;
1153
1154
1155/* VRDP_USB_REQ_CLOSE
1156 */
1157typedef struct _VRDP_USB_REQ_CLOSE_PARM
1158{
1159 uint8_t code;
1160 VRDPUSBDEVID id;
1161} VRDP_USB_REQ_CLOSE_PARM;
1162
1163/* The close request has no returned data. */
1164
1165
1166/* VRDP_USB_REQ_RESET
1167 */
1168typedef struct _VRDP_USB_REQ_RESET_PARM
1169{
1170 uint8_t code;
1171 VRDPUSBDEVID id;
1172} VRDP_USB_REQ_RESET_PARM;
1173
1174typedef struct _VRDP_USB_REQ_RESET_RET
1175{
1176 VRDPUSBREQRETHDR hdr;
1177} VRDP_USB_REQ_RESET_RET;
1178
1179
1180/* VRDP_USB_REQ_SET_CONFIG
1181 */
1182typedef struct _VRDP_USB_REQ_SET_CONFIG_PARM
1183{
1184 uint8_t code;
1185 VRDPUSBDEVID id;
1186 uint8_t configuration;
1187} VRDP_USB_REQ_SET_CONFIG_PARM;
1188
1189typedef struct _VRDP_USB_REQ_SET_CONFIG_RET
1190{
1191 VRDPUSBREQRETHDR hdr;
1192} VRDP_USB_REQ_SET_CONFIG_RET;
1193
1194
1195/* VRDP_USB_REQ_CLAIM_INTERFACE
1196 */
1197typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_PARM
1198{
1199 uint8_t code;
1200 VRDPUSBDEVID id;
1201 uint8_t iface;
1202} VRDP_USB_REQ_CLAIM_INTERFACE_PARM;
1203
1204typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_RET
1205{
1206 VRDPUSBREQRETHDR hdr;
1207} VRDP_USB_REQ_CLAIM_INTERFACE_RET;
1208
1209
1210/* VRDP_USB_REQ_RELEASE_INTERFACE
1211 */
1212typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_PARM
1213{
1214 uint8_t code;
1215 VRDPUSBDEVID id;
1216 uint8_t iface;
1217} VRDP_USB_REQ_RELEASE_INTERFACE_PARM;
1218
1219typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_RET
1220{
1221 VRDPUSBREQRETHDR hdr;
1222} VRDP_USB_REQ_RELEASE_INTERFACE_RET;
1223
1224
1225/* VRDP_USB_REQ_INTERFACE_SETTING
1226 */
1227typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_PARM
1228{
1229 uint8_t code;
1230 VRDPUSBDEVID id;
1231 uint8_t iface;
1232 uint8_t setting;
1233} VRDP_USB_REQ_INTERFACE_SETTING_PARM;
1234
1235typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_RET
1236{
1237 VRDPUSBREQRETHDR hdr;
1238} VRDP_USB_REQ_INTERFACE_SETTING_RET;
1239
1240
1241/* VRDP_USB_REQ_QUEUE_URB
1242 */
1243
1244#define VRDP_USB_TRANSFER_TYPE_CTRL (0)
1245#define VRDP_USB_TRANSFER_TYPE_ISOC (1)
1246#define VRDP_USB_TRANSFER_TYPE_BULK (2)
1247#define VRDP_USB_TRANSFER_TYPE_INTR (3)
1248#define VRDP_USB_TRANSFER_TYPE_MSG (4)
1249
1250#define VRDP_USB_DIRECTION_SETUP (0)
1251#define VRDP_USB_DIRECTION_IN (1)
1252#define VRDP_USB_DIRECTION_OUT (2)
1253
1254typedef struct _VRDP_USB_REQ_QUEUE_URB_PARM
1255{
1256 uint8_t code;
1257 VRDPUSBDEVID id;
1258 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
1259 uint8_t type;
1260 uint8_t ep;
1261 uint8_t direction;
1262 uint32_t urblen; /* Length of the URB. */
1263 uint32_t datalen; /* Length of the data. */
1264 void *data; /* In RDP layout the data follow. */
1265} VRDP_USB_REQ_QUEUE_URB_PARM;
1266
1267/* The queue URB has no explicit return. The reap URB reply will be
1268 * eventually the indirect result.
1269 */
1270
1271
1272/* VRDP_USB_REQ_REAP_URB
1273 * Notificationg from server to client that server expects an URB
1274 * from any device.
1275 * Only sent if negotiated URB return method is polling.
1276 * Normally, the client will send URBs back as soon as they are ready.
1277 */
1278typedef struct _VRDP_USB_REQ_REAP_URB_PARM
1279{
1280 uint8_t code;
1281} VRDP_USB_REQ_REAP_URB_PARM;
1282
1283
1284#define VRDP_USB_XFER_OK (0)
1285#define VRDP_USB_XFER_STALL (1)
1286#define VRDP_USB_XFER_DNR (2)
1287#define VRDP_USB_XFER_CRC (3)
1288
1289#define VRDP_USB_REAP_FLAG_CONTINUED (0x0)
1290#define VRDP_USB_REAP_FLAG_LAST (0x1)
1291
1292#define VRDP_USB_REAP_VALID_FLAGS (VRDP_USB_REAP_FLAG_LAST)
1293
1294typedef struct _VRDPUSBREQREAPURBBODY
1295{
1296 VRDPUSBDEVID id; /* From which device the URB arrives. */
1297 uint8_t flags; /* VRDP_USB_REAP_FLAG_* */
1298 uint8_t error; /* VRDP_USB_XFER_* */
1299 uint32_t handle; /* Handle of returned URB. Not 0. */
1300 uint32_t len; /* Length of data actually transferred. */
1301 /* Data follow. */
1302} VRDPUSBREQREAPURBBODY;
1303
1304typedef struct _VRDP_USB_REQ_REAP_URB_RET
1305{
1306 /* The REAP URB has no header, only completed URBs are returned. */
1307 VRDPUSBREQREAPURBBODY body;
1308 /* Another body may follow, depending on flags. */
1309} VRDP_USB_REQ_REAP_URB_RET;
1310
1311
1312/* VRDP_USB_REQ_CLEAR_HALTED_EP
1313 */
1314typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_PARM
1315{
1316 uint8_t code;
1317 VRDPUSBDEVID id;
1318 uint8_t ep;
1319} VRDP_USB_REQ_CLEAR_HALTED_EP_PARM;
1320
1321typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_RET
1322{
1323 VRDPUSBREQRETHDR hdr;
1324} VRDP_USB_REQ_CLEAR_HALTED_EP_RET;
1325
1326
1327/* VRDP_USB_REQ_CANCEL_URB
1328 */
1329typedef struct _VRDP_USB_REQ_CANCEL_URB_PARM
1330{
1331 uint8_t code;
1332 VRDPUSBDEVID id;
1333 uint32_t handle;
1334} VRDP_USB_REQ_CANCEL_URB_PARM;
1335
1336/* The cancel URB request has no return. */
1337
1338
1339/* VRDP_USB_REQ_DEVICE_LIST
1340 *
1341 * Server polls USB devices on client by sending this request
1342 * periodically. Client sends back a list of all devices
1343 * connected to it. Each device is assigned with an identifier,
1344 * that is used to distinguish the particular device.
1345 */
1346typedef struct _VRDP_USB_REQ_DEVICE_LIST_PARM
1347{
1348 uint8_t code;
1349} VRDP_USB_REQ_DEVICE_LIST_PARM;
1350
1351/* Data is a list of the following variable length structures. */
1352typedef struct _VRDPUSBDEVICEDESC
1353{
1354 /* Offset of the next structure. 0 if last. */
1355 uint16_t oNext;
1356
1357 /* Identifier of the device assigned by client. */
1358 VRDPUSBDEVID id;
1359
1360 /** USB version number. */
1361 uint16_t bcdUSB;
1362 /** Device class. */
1363 uint8_t bDeviceClass;
1364 /** Device subclass. */
1365 uint8_t bDeviceSubClass;
1366 /** Device protocol */
1367 uint8_t bDeviceProtocol;
1368 /** Vendor ID. */
1369 uint16_t idVendor;
1370 /** Product ID. */
1371 uint16_t idProduct;
1372 /** Revision, integer part. */
1373 uint16_t bcdRev;
1374 /** Manufacturer string. */
1375 uint16_t oManufacturer;
1376 /** Product string. */
1377 uint16_t oProduct;
1378 /** Serial number string. */
1379 uint16_t oSerialNumber;
1380 /** Physical USB port the device is connected to. */
1381 uint16_t idPort;
1382
1383} VRDPUSBDEVICEDESC;
1384
1385typedef struct _VRDP_USB_REQ_DEVICE_LIST_RET
1386{
1387 VRDPUSBDEVICEDESC body;
1388 /* Other devices may follow.
1389 * The list ends with (uint16_t)0,
1390 * which means that an empty list consists of 2 zero bytes.
1391 */
1392} VRDP_USB_REQ_DEVICE_LIST_RET;
1393
1394typedef struct _VRDPUSBREQNEGOTIATEPARM
1395{
1396 uint8_t code;
1397
1398 /* Remote USB Protocol version. */
1399 uint32_t version;
1400
1401} VRDPUSBREQNEGOTIATEPARM;
1402
1403#define VRDP_USB_CAPS_FLAG_ASYNC (0x0)
1404#define VRDP_USB_CAPS_FLAG_POLL (0x1)
1405
1406#define VRDP_USB_CAPS_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL)
1407
1408typedef struct _VRDPUSBREQNEGOTIATERET
1409{
1410 uint8_t flags;
1411} VRDPUSBREQNEGOTIATERET;
1412
1413#pragma pack()
1414
1415
1416#define VRDP_CLIPBOARD_FORMAT_NULL (0x0)
1417#define VRDP_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
1418#define VRDP_CLIPBOARD_FORMAT_BITMAP (0x2)
1419#define VRDP_CLIPBOARD_FORMAT_HTML (0x4)
1420
1421#define VRDP_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
1422#define VRDP_CLIPBOARD_FUNCTION_DATA_READ (1)
1423#define VRDP_CLIPBOARD_FUNCTION_DATA_WRITE (2)
1424
1425/**
1426 * Called by the host when (VRDP_CLIPBOARD_FUNCTION_*):
1427 * - (0) guest announces available clipboard formats;
1428 * - (1) guest requests clipboard data;
1429 * - (2) guest responds to the client's request for clipboard data.
1430 *
1431 * @param hserver The VRDP server handle.
1432 * @param u32Function The cause of the call.
1433 * @param u32Format Bitmask of announced formats or the format of data.
1434 * @param pvData Points to: (1) buffer to be filled with clients data;
1435 * (2) data from the host.
1436 * @param cbData Size of 'pvData' buffer in bytes.
1437 * @param pcbActualRead Size of the copied data in bytes.
1438 *
1439 */
1440VRDPR3DECL(void) VRDPClipboard (HVRDPSERVER hserver,
1441 uint32_t u32Function,
1442 uint32_t u32Format,
1443 void *pvData,
1444 uint32_t cbData,
1445 uint32_t *pcbActualRead);
1446
1447/**
1448 * Sends a USB request.
1449 *
1450 * @param hserver Handle of VRDP server instance.
1451 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1452 * The identifier is always passed by the server as a parameter
1453 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
1454 * in the VRDPSERVERCALLBACK functions.
1455 * @param pvParm Function specific parameters buffer.
1456 * @param cbParm Size of the buffer.
1457 */
1458VRDPR3DECL(void) VRDPSendUSBRequest (HVRDPSERVER hserver,
1459 uint32_t u32ClientId,
1460 void *pvParm,
1461 uint32_t cbRarm);
1462
1463
1464/**
1465 * Called by the server when a reply is received from a client.
1466 *
1467 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptUSB.
1468 * @param u32ClientId Identifies the client that sent the reply.
1469 * @param u8Code The operation code VRDP_USB_REQ_*.
1470 * @param pvRet Points to data received from the client.
1471 * @param cbRet Size of the data in bytes.
1472 *
1473 * @return VBox error code.
1474 */
1475typedef DECLCALLBACK(int) FNVRDPUSBCALLBACK (void *pvCallback,
1476 uint32_t u32ClientId,
1477 uint8_t u8Code,
1478 const void *pvRet,
1479 uint32_t cbRet);
1480
1481typedef FNVRDPUSBCALLBACK *PFNVRDPUSBCALLBACK;
1482
1483/**
1484 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
1485 * - (0) client announces available clipboard formats;
1486 * - (1) client requests clipboard data.
1487 *
1488 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptClipboard.
1489 * @param u32ClientId Identifies the RDP client that sent the reply.
1490 * @param u32Function The cause of the callback.
1491 * @param u32Format Bitmask of reported formats or the format of received data.
1492 * @param pvData Reserved.
1493 * @param cbData Reserved.
1494 *
1495 * @return VBox error code.
1496 */
1497typedef DECLCALLBACK(int) FNVRDPCLIPBOARDCALLBACK (void *pvCallback,
1498 uint32_t u32ClientId,
1499 uint32_t u32Function,
1500 uint32_t u32Format,
1501 const void *pvData,
1502 uint32_t cbData);
1503
1504typedef FNVRDPCLIPBOARDCALLBACK *PFNVRDPCLIPBOARDCALLBACK;
1505
1506#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
1507#define VRDP_CLIENT_INTERCEPT_USB (0x2)
1508#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
1509
1510typedef struct _VRDPSERVERCALLBACK
1511{
1512 /* A client is logging in.
1513 *
1514 * @param pvUser The callback specific pointer.
1515 * @param u32ClientId An unique client identifier generated by the server.
1516 * @param pszUser The username.
1517 * @param pszPassword The password.
1518 * @param pszDomain The domain.
1519 *
1520 * @return VBox error code.
1521 */
1522 DECLCALLBACKMEMBER(int, pfnClientLogon) (void *pvUser,
1523 uint32_t u32ClientId,
1524 const char *pszUser,
1525 const char *pszPassword,
1526 const char *pszDomain);
1527 /* The client has connected.
1528 *
1529 * @param pvUser The callback specific pointer.
1530 * @param u32ClientId An unique client identifier generated by the server.
1531 */
1532 DECLCALLBACKMEMBER(void, pfnClientConnect) (void *pvUser,
1533 uint32_t u32ClientId);
1534 /* The client has been disconnected.
1535 *
1536 * @param pvUser The callback specific pointer.
1537 * @param u32ClientId An unique client identifier generated by the server.
1538 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
1539 */
1540 DECLCALLBACKMEMBER(void, pfnClientDisconnect) (void *pvUser,
1541 uint32_t u32ClientId,
1542 uint32_t fu32Intercepted);
1543 /* The client supports audio channel.
1544 */
1545 DECLCALLBACKMEMBER(void, pfnInterceptAudio) (void *pvUser,
1546 uint32_t u32ClientId);
1547 /* The client supports USB channel.
1548 */
1549 DECLCALLBACKMEMBER(void, pfnInterceptUSB) (void *pvUser,
1550 uint32_t u32ClientId,
1551 PFNVRDPUSBCALLBACK *ppfn,
1552 void **ppv);
1553 /* The client supports clipboard channel.
1554 */
1555 DECLCALLBACKMEMBER(void, pfnInterceptClipboard) (void *pvUser,
1556 uint32_t u32ClientId,
1557 PFNVRDPCLIPBOARDCALLBACK *ppfn,
1558 void **ppv);
1559} VRDPSERVERCALLBACK;
1560
1561/**
1562 * Set a callback pointers table that will be called by the server in certain situations.
1563 *
1564 * @param hserver Handle of VRDP server instance.
1565 * @param pCallback Pointer to VRDPSERVERCALLBACK structure with function pointers.
1566 * @param pvUser An pointer to be passed to the callback functions.
1567 */
1568VRDPR3DECL(void) VRDPSetCallback (HVRDPSERVER hserver, VRDPSERVERCALLBACK *pCallback, void *pvUser);
1569
1570/** Indexes of information values. */
1571
1572/** Whether a client is connected at the moment.
1573 * uint32_t
1574 */
1575#define VRDP_QI_ACTIVE (0)
1576
1577/** How many times a client connected up to current moment.
1578 * uint32_t
1579 */
1580#define VRDP_QI_NUMBER_OF_CLIENTS (1)
1581
1582/** When last connection was established.
1583 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
1584 */
1585#define VRDP_QI_BEGIN_TIME (2)
1586
1587/** When last connection was terminated or current time if connection still active.
1588 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
1589 */
1590#define VRDP_QI_END_TIME (3)
1591
1592/** How many bytes were sent in last (current) connection.
1593 * uint64_t
1594 */
1595#define VRDP_QI_BYTES_SENT (4)
1596
1597/** How many bytes were sent in all connections.
1598 * uint64_t
1599 */
1600#define VRDP_QI_BYTES_SENT_TOTAL (5)
1601
1602/** How many bytes were received in last (current) connection.
1603 * uint64_t
1604 */
1605#define VRDP_QI_BYTES_RECEIVED (6)
1606
1607/** How many bytes were received in all connections.
1608 * uint64_t
1609 */
1610#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
1611
1612/** Login user name supplied by the client.
1613 * UTF8 nul terminated string.
1614 */
1615#define VRDP_QI_USER (8)
1616
1617/** Login domain supplied by the client.
1618 * UTF8 nul terminated string.
1619 */
1620#define VRDP_QI_DOMAIN (9)
1621
1622/** The client name supplied by the client.
1623 * UTF8 nul terminated string.
1624 */
1625#define VRDP_QI_CLIENT_NAME (10)
1626
1627/** IP address of the client.
1628 * UTF8 nul terminated string.
1629 */
1630#define VRDP_QI_CLIENT_IP (11)
1631
1632/** The client software version number.
1633 * uint32_t.
1634 */
1635#define VRDP_QI_CLIENT_VERSION (12)
1636
1637/** Public key exchange method used when connection was established.
1638 * Values: 0 - RDP4 public key exchange scheme.
1639 * 1 - X509 sertificates were sent to client.
1640 * uint32_t.
1641 */
1642#define VRDP_QI_ENCRYPTION_STYLE (13)
1643
1644/**
1645 * Query various information from the VRDP server.
1646 *
1647 * @param index VRDP_QI_* identifier of information to be returned.
1648 * @param pvBuffer Address of memory buffer to which the information must be written.
1649 * @param cbBuffer Size of the memory buffer in bytes.
1650 * @param pcbOut Size in bytes of returned information value.
1651 *
1652 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
1653 * A value greater than cbBuffer means that information is too big to fit in the
1654 * buffer, in that case no information was placed to the buffer.
1655 */
1656VRDPR3DECL(void) VRDPQueryInfo (HVRDPSERVER hserver, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut);
1657#endif /* VRDP_NO_COM */
1658
1659__END_DECLS
1660
1661/** @} */
1662
1663#endif
1664
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