VirtualBox

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

Last change on this file since 3786 was 3720, checked in by vboxsync, 17 years ago

VRDP NO_COM code in Main.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 53.2 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 int type,
909 const void *pvInput,
910 unsigned cbInput);
911
912 /* Video mode hint from the client.
913 *
914 * @param pvCallback The callback specific pointer.
915 * @param cWidth Requested width.
916 * @param cHeight Requested height.
917 * @param cBitsPerPixel Requested color depth.
918 * @param uScreenId The framebuffer index.
919 */
920 DECLCALLBACKMEMBER(void, VRDPCallbackVideoModeHint)(void *pvCallback,
921 unsigned cWidth,
922 unsigned cHeight,
923 unsigned cBitsPerPixel,
924 unsigned uScreenId);
925
926} VRDPCALLBACKS_1;
927
928/**
929 * Create a new VRDP server instance. The instance is fully functional but refuses
930 * client connections until the entry point VRDPEnableConnections is called by the application.
931 *
932 * The caller prepares the callbacks structure. The header.u64Version field
933 * must be initialized with the version of the insterface to use.
934 * The server will initialize the callbacks table to match the requested interface.
935 *
936 * @param pCallback Pointer to the application callbacks which let the server to fetch
937 * the configuration data and to access the desktop.
938 * @param pvCallback The callback specific pointer to be passed back to the application.
939 * @param ppEntryPoints Where to store the pointer to the VRDP entry points structure.
940 * @param phServer Pointer to the created server instance handle.
941 *
942 * @return IPRT status code.
943 */
944VRDPDECL(int) VRDPCreateServer (const VRDPINTERFACEHDR *pCallbacks,
945 void *pvCallback,
946 VRDPINTERFACEHDR **ppEntryPoints,
947 HVRDPSERVER *phServer);
948
949typedef VRDPDECL(int) FNVRDPCREATESERVER (const VRDPINTERFACEHDR *pCallbacks,
950 void *pvCallback,
951 VRDPINTERFACEHDR **ppEntryPoints,
952 HVRDPSERVER *phServer);
953typedef FNVRDPCREATESERVER *PFNVRDPCREATESERVER;
954#else
955/**
956 * Start server for the specified IConsole.
957 *
958 * @return VBox status code
959 * @param pconsole Pointer to IConsole instance to fetch display, mouse and keyboard interfaces.
960 * @param pvrdpserver Pointer to IVRDPServer instance to fetch configuration.
961 * @param phserver Pointer to server instance handle,
962 * created by the function.
963 */
964VRDPR3DECL(int) VRDPStartServer (IConsole *pconsole, IVRDPServer *pvrdpserver, HVRDPSERVER *phserver);
965
966
967/**
968 * Shutdown server.
969 *
970 * @param hserver Handle of VRDP server instance to be stopped.
971 */
972VRDPR3DECL(void) VRDPShutdownServer (HVRDPSERVER hserver);
973
974
975/**
976 * Send framebuffer bitmap to client.
977 *
978 * @param hserver Handle of VRDP server instance.
979 * @param x top left horizontal coordinate in framebuffer.
980 * @param y top left vertical coordinate in framebuffer.
981 * @param w width of rectangle.
982 * @param h height of rectangle.
983 */
984VRDPR3DECL(void) VRDPSendUpdateBitmap (HVRDPSERVER hserver, unsigned uScreenId, unsigned x, unsigned y, unsigned w, unsigned h);
985
986/**
987 * Inform client that display was resized.
988 * New width and height are taken from the current framebuffer.
989 *
990 * @param hserver Handle of VRDP server instance.
991 */
992VRDPR3DECL(void) VRDPSendResize (HVRDPSERVER hserver);
993
994/**
995 * Send an update in accelerated mode.
996 *
997 * @param hserver Handle of VRDP server instance.
998 * @param pvUpdate The update information. Actually pointer to VBoxGuest.h::VBVACMDHDR structure with extra data.
999 * @param cbUpdate Size of the update data.
1000 */
1001VRDPR3DECL(void) VRDPSendUpdate (HVRDPSERVER hserver, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate);
1002
1003/** @todo comment the structure. */
1004typedef struct _VRDPCOLORPOINTER
1005{
1006 uint16_t u16HotX;
1007 uint16_t u16HotY;
1008 uint16_t u16Width;
1009 uint16_t u16Height;
1010 uint16_t u16MaskLen;
1011 uint16_t u16DataLen;
1012 uint32_t vrdpInternal;
1013} VRDPCOLORPOINTER;
1014
1015typedef VRDPCOLORPOINTER *PVRDPCOLORPOINTER;
1016
1017/**
1018 * Set mouse pointer shape.
1019 *
1020 * @param hserver Handle of VRDP server instance.
1021 * @param porder The pointer shape information.
1022 */
1023VRDPR3DECL(void) VRDPSendColorPointer (HVRDPSERVER hserver, PVRDPCOLORPOINTER pdata);
1024
1025/**
1026 * Hide mouse pointer.
1027 *
1028 * @param hserver Handle of VRDP server instance.
1029 */
1030VRDPR3DECL(void) VRDPSendHidePointer (HVRDPSERVER hserver);
1031
1032/** Audio format information packed in a 32 bit value. */
1033typedef uint32_t VRDPAUDIOFORMAT;
1034
1035/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
1036#define VRDP_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
1037
1038/** Decode frequency. */
1039#define VRDP_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
1040/** Decode number of channels. */
1041#define VRDP_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
1042/** Decode number signess. */
1043#define VRDP_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
1044/** Decode number of bits per sample. */
1045#define VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
1046/** Decode number of bytes per sample. */
1047#define VRDP_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
1048
1049/**
1050 * Queues the samples to be sent to client.
1051 *
1052 * @param hserver Handle of VRDP server instance.
1053 * @param pvSamples Address of samples to be sent.
1054 * @param cSamples Number of samples.
1055 * @param format Encoded audio format for these samples.
1056 */
1057VRDPR3DECL(void) VRDPSendAudioSamples (HVRDPSERVER hserver, void *pvSamples, uint32_t cSamples, VRDPAUDIOFORMAT format);
1058
1059/**
1060 * Sets sound volume on client.
1061 *
1062 * @param hserver Handle of VRDP server instance.
1063 * @param left 0..0xFFFF volume level for left channel.
1064 * @param right 0..0xFFFF volume level for right channel.
1065 */
1066VRDPR3DECL(void) VRDPSendAudioVolume (HVRDPSERVER hserver, uint16_t left, uint16_t right);
1067
1068
1069/*
1070 * Remote USB backend protocol.
1071 */
1072
1073/* The version of Remote USB Protocol. */
1074#define VRDP_USB_VERSION (1)
1075
1076/** USB backend operations. */
1077#define VRDP_USB_REQ_OPEN (0)
1078#define VRDP_USB_REQ_CLOSE (1)
1079#define VRDP_USB_REQ_RESET (2)
1080#define VRDP_USB_REQ_SET_CONFIG (3)
1081#define VRDP_USB_REQ_CLAIM_INTERFACE (4)
1082#define VRDP_USB_REQ_RELEASE_INTERFACE (5)
1083#define VRDP_USB_REQ_INTERFACE_SETTING (6)
1084#define VRDP_USB_REQ_QUEUE_URB (7)
1085#define VRDP_USB_REQ_REAP_URB (8)
1086#define VRDP_USB_REQ_CLEAR_HALTED_EP (9)
1087#define VRDP_USB_REQ_CANCEL_URB (10)
1088
1089/** USB service operations. */
1090#define VRDP_USB_REQ_DEVICE_LIST (11)
1091#define VRDP_USB_REQ_NEGOTIATE (12)
1092
1093/** An operation completion status is a byte. */
1094typedef uint8_t VRDPUSBSTATUS;
1095
1096/** USB device identifier is an 32 bit value. */
1097typedef uint32_t VRDPUSBDEVID;
1098
1099/** Status codes. */
1100#define VRDP_USB_STATUS_SUCCESS ((VRDPUSBSTATUS)0)
1101#define VRDP_USB_STATUS_ACCESS_DENIED ((VRDPUSBSTATUS)1)
1102#define VRDP_USB_STATUS_DEVICE_REMOVED ((VRDPUSBSTATUS)2)
1103
1104/*
1105 * Data structures to use with VRDPSendUSBRequest.
1106 * The *RET* structures always represent the layout of VRDP data.
1107 * The *PARM* structures normally the same as VRDP layout.
1108 * However the VRDP_USB_REQ_QUEUE_URB_PARM has a pointer to
1109 * URB data in place where actual data will be in VRDP layout.
1110 *
1111 * Since replies (*RET*) are asynchronous, the 'success'
1112 * replies are not required for operations which return
1113 * only the status code (VRDPUSBREQRETHDR only):
1114 * VRDP_USB_REQ_OPEN
1115 * VRDP_USB_REQ_RESET
1116 * VRDP_USB_REQ_SET_CONFIG
1117 * VRDP_USB_REQ_CLAIM_INTERFACE
1118 * VRDP_USB_REQ_RELEASE_INTERFACE
1119 * VRDP_USB_REQ_INTERFACE_SETTING
1120 * VRDP_USB_REQ_CLEAR_HALTED_EP
1121 *
1122 */
1123
1124/* VRDP layout has no aligments. */
1125#pragma pack(1)
1126
1127/* Common header for all VRDP USB packets. After the reply hdr follows *PARM* or *RET* data. */
1128typedef struct _VRDPUSBPKTHDR
1129{
1130 /* Total length of the reply NOT including the 'length' field. */
1131 uint32_t length;
1132 /* The operation code for which the reply was sent by the client. */
1133 uint8_t code;
1134} VRDPUSBPKTHDR;
1135
1136/* Common header for all return structures. */
1137typedef struct _VRDPUSBREQRETHDR
1138{
1139 /* Device status. */
1140 VRDPUSBSTATUS status;
1141 /* Device id. */
1142 VRDPUSBDEVID id;
1143} VRDPUSBREQRETHDR;
1144
1145
1146/* VRDP_USB_REQ_OPEN
1147 */
1148typedef struct _VRDP_USB_REQ_OPEN_PARM
1149{
1150 uint8_t code;
1151 VRDPUSBDEVID id;
1152} VRDP_USB_REQ_OPEN_PARM;
1153
1154typedef struct _VRDP_USB_REQ_OPEN_RET
1155{
1156 VRDPUSBREQRETHDR hdr;
1157} VRDP_USB_REQ_OPEN_RET;
1158
1159
1160/* VRDP_USB_REQ_CLOSE
1161 */
1162typedef struct _VRDP_USB_REQ_CLOSE_PARM
1163{
1164 uint8_t code;
1165 VRDPUSBDEVID id;
1166} VRDP_USB_REQ_CLOSE_PARM;
1167
1168/* The close request has no returned data. */
1169
1170
1171/* VRDP_USB_REQ_RESET
1172 */
1173typedef struct _VRDP_USB_REQ_RESET_PARM
1174{
1175 uint8_t code;
1176 VRDPUSBDEVID id;
1177} VRDP_USB_REQ_RESET_PARM;
1178
1179typedef struct _VRDP_USB_REQ_RESET_RET
1180{
1181 VRDPUSBREQRETHDR hdr;
1182} VRDP_USB_REQ_RESET_RET;
1183
1184
1185/* VRDP_USB_REQ_SET_CONFIG
1186 */
1187typedef struct _VRDP_USB_REQ_SET_CONFIG_PARM
1188{
1189 uint8_t code;
1190 VRDPUSBDEVID id;
1191 uint8_t configuration;
1192} VRDP_USB_REQ_SET_CONFIG_PARM;
1193
1194typedef struct _VRDP_USB_REQ_SET_CONFIG_RET
1195{
1196 VRDPUSBREQRETHDR hdr;
1197} VRDP_USB_REQ_SET_CONFIG_RET;
1198
1199
1200/* VRDP_USB_REQ_CLAIM_INTERFACE
1201 */
1202typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_PARM
1203{
1204 uint8_t code;
1205 VRDPUSBDEVID id;
1206 uint8_t iface;
1207} VRDP_USB_REQ_CLAIM_INTERFACE_PARM;
1208
1209typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_RET
1210{
1211 VRDPUSBREQRETHDR hdr;
1212} VRDP_USB_REQ_CLAIM_INTERFACE_RET;
1213
1214
1215/* VRDP_USB_REQ_RELEASE_INTERFACE
1216 */
1217typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_PARM
1218{
1219 uint8_t code;
1220 VRDPUSBDEVID id;
1221 uint8_t iface;
1222} VRDP_USB_REQ_RELEASE_INTERFACE_PARM;
1223
1224typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_RET
1225{
1226 VRDPUSBREQRETHDR hdr;
1227} VRDP_USB_REQ_RELEASE_INTERFACE_RET;
1228
1229
1230/* VRDP_USB_REQ_INTERFACE_SETTING
1231 */
1232typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_PARM
1233{
1234 uint8_t code;
1235 VRDPUSBDEVID id;
1236 uint8_t iface;
1237 uint8_t setting;
1238} VRDP_USB_REQ_INTERFACE_SETTING_PARM;
1239
1240typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_RET
1241{
1242 VRDPUSBREQRETHDR hdr;
1243} VRDP_USB_REQ_INTERFACE_SETTING_RET;
1244
1245
1246/* VRDP_USB_REQ_QUEUE_URB
1247 */
1248
1249#define VRDP_USB_TRANSFER_TYPE_CTRL (0)
1250#define VRDP_USB_TRANSFER_TYPE_ISOC (1)
1251#define VRDP_USB_TRANSFER_TYPE_BULK (2)
1252#define VRDP_USB_TRANSFER_TYPE_INTR (3)
1253#define VRDP_USB_TRANSFER_TYPE_MSG (4)
1254
1255#define VRDP_USB_DIRECTION_SETUP (0)
1256#define VRDP_USB_DIRECTION_IN (1)
1257#define VRDP_USB_DIRECTION_OUT (2)
1258
1259typedef struct _VRDP_USB_REQ_QUEUE_URB_PARM
1260{
1261 uint8_t code;
1262 VRDPUSBDEVID id;
1263 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
1264 uint8_t type;
1265 uint8_t ep;
1266 uint8_t direction;
1267 uint32_t urblen; /* Length of the URB. */
1268 uint32_t datalen; /* Length of the data. */
1269 void *data; /* In RDP layout the data follow. */
1270} VRDP_USB_REQ_QUEUE_URB_PARM;
1271
1272/* The queue URB has no explicit return. The reap URB reply will be
1273 * eventually the indirect result.
1274 */
1275
1276
1277/* VRDP_USB_REQ_REAP_URB
1278 * Notificationg from server to client that server expects an URB
1279 * from any device.
1280 * Only sent if negotiated URB return method is polling.
1281 * Normally, the client will send URBs back as soon as they are ready.
1282 */
1283typedef struct _VRDP_USB_REQ_REAP_URB_PARM
1284{
1285 uint8_t code;
1286} VRDP_USB_REQ_REAP_URB_PARM;
1287
1288
1289#define VRDP_USB_XFER_OK (0)
1290#define VRDP_USB_XFER_STALL (1)
1291#define VRDP_USB_XFER_DNR (2)
1292#define VRDP_USB_XFER_CRC (3)
1293
1294#define VRDP_USB_REAP_FLAG_CONTINUED (0x0)
1295#define VRDP_USB_REAP_FLAG_LAST (0x1)
1296
1297#define VRDP_USB_REAP_VALID_FLAGS (VRDP_USB_REAP_FLAG_LAST)
1298
1299typedef struct _VRDPUSBREQREAPURBBODY
1300{
1301 VRDPUSBDEVID id; /* From which device the URB arrives. */
1302 uint8_t flags; /* VRDP_USB_REAP_FLAG_* */
1303 uint8_t error; /* VRDP_USB_XFER_* */
1304 uint32_t handle; /* Handle of returned URB. Not 0. */
1305 uint32_t len; /* Length of data actually transferred. */
1306 /* Data follow. */
1307} VRDPUSBREQREAPURBBODY;
1308
1309typedef struct _VRDP_USB_REQ_REAP_URB_RET
1310{
1311 /* The REAP URB has no header, only completed URBs are returned. */
1312 VRDPUSBREQREAPURBBODY body;
1313 /* Another body may follow, depending on flags. */
1314} VRDP_USB_REQ_REAP_URB_RET;
1315
1316
1317/* VRDP_USB_REQ_CLEAR_HALTED_EP
1318 */
1319typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_PARM
1320{
1321 uint8_t code;
1322 VRDPUSBDEVID id;
1323 uint8_t ep;
1324} VRDP_USB_REQ_CLEAR_HALTED_EP_PARM;
1325
1326typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_RET
1327{
1328 VRDPUSBREQRETHDR hdr;
1329} VRDP_USB_REQ_CLEAR_HALTED_EP_RET;
1330
1331
1332/* VRDP_USB_REQ_CANCEL_URB
1333 */
1334typedef struct _VRDP_USB_REQ_CANCEL_URB_PARM
1335{
1336 uint8_t code;
1337 VRDPUSBDEVID id;
1338 uint32_t handle;
1339} VRDP_USB_REQ_CANCEL_URB_PARM;
1340
1341/* The cancel URB request has no return. */
1342
1343
1344/* VRDP_USB_REQ_DEVICE_LIST
1345 *
1346 * Server polls USB devices on client by sending this request
1347 * periodically. Client sends back a list of all devices
1348 * connected to it. Each device is assigned with an identifier,
1349 * that is used to distinguish the particular device.
1350 */
1351typedef struct _VRDP_USB_REQ_DEVICE_LIST_PARM
1352{
1353 uint8_t code;
1354} VRDP_USB_REQ_DEVICE_LIST_PARM;
1355
1356/* Data is a list of the following variable length structures. */
1357typedef struct _VRDPUSBDEVICEDESC
1358{
1359 /* Offset of the next structure. 0 if last. */
1360 uint16_t oNext;
1361
1362 /* Identifier of the device assigned by client. */
1363 VRDPUSBDEVID id;
1364
1365 /** USB version number. */
1366 uint16_t bcdUSB;
1367 /** Device class. */
1368 uint8_t bDeviceClass;
1369 /** Device subclass. */
1370 uint8_t bDeviceSubClass;
1371 /** Device protocol */
1372 uint8_t bDeviceProtocol;
1373 /** Vendor ID. */
1374 uint16_t idVendor;
1375 /** Product ID. */
1376 uint16_t idProduct;
1377 /** Revision, integer part. */
1378 uint16_t bcdRev;
1379 /** Manufacturer string. */
1380 uint16_t oManufacturer;
1381 /** Product string. */
1382 uint16_t oProduct;
1383 /** Serial number string. */
1384 uint16_t oSerialNumber;
1385 /** Physical USB port the device is connected to. */
1386 uint16_t idPort;
1387
1388} VRDPUSBDEVICEDESC;
1389
1390typedef struct _VRDP_USB_REQ_DEVICE_LIST_RET
1391{
1392 VRDPUSBDEVICEDESC body;
1393 /* Other devices may follow.
1394 * The list ends with (uint16_t)0,
1395 * which means that an empty list consists of 2 zero bytes.
1396 */
1397} VRDP_USB_REQ_DEVICE_LIST_RET;
1398
1399typedef struct _VRDPUSBREQNEGOTIATEPARM
1400{
1401 uint8_t code;
1402
1403 /* Remote USB Protocol version. */
1404 uint32_t version;
1405
1406} VRDPUSBREQNEGOTIATEPARM;
1407
1408#define VRDP_USB_CAPS_FLAG_ASYNC (0x0)
1409#define VRDP_USB_CAPS_FLAG_POLL (0x1)
1410
1411#define VRDP_USB_CAPS_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL)
1412
1413typedef struct _VRDPUSBREQNEGOTIATERET
1414{
1415 uint8_t flags;
1416} VRDPUSBREQNEGOTIATERET;
1417
1418#pragma pack()
1419
1420
1421#define VRDP_CLIPBOARD_FORMAT_NULL (0x0)
1422#define VRDP_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
1423#define VRDP_CLIPBOARD_FORMAT_BITMAP (0x2)
1424#define VRDP_CLIPBOARD_FORMAT_HTML (0x4)
1425
1426#define VRDP_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
1427#define VRDP_CLIPBOARD_FUNCTION_DATA_READ (1)
1428#define VRDP_CLIPBOARD_FUNCTION_DATA_WRITE (2)
1429
1430/**
1431 * Called by the host when (VRDP_CLIPBOARD_FUNCTION_*):
1432 * - (0) guest announces available clipboard formats;
1433 * - (1) guest requests clipboard data;
1434 * - (2) guest responds to the client's request for clipboard data.
1435 *
1436 * @param hserver The VRDP server handle.
1437 * @param u32Function The cause of the call.
1438 * @param u32Format Bitmask of announced formats or the format of data.
1439 * @param pvData Points to: (1) buffer to be filled with clients data;
1440 * (2) data from the host.
1441 * @param cbData Size of 'pvData' buffer in bytes.
1442 * @param pcbActualRead Size of the copied data in bytes.
1443 *
1444 */
1445VRDPR3DECL(void) VRDPClipboard (HVRDPSERVER hserver,
1446 uint32_t u32Function,
1447 uint32_t u32Format,
1448 void *pvData,
1449 uint32_t cbData,
1450 uint32_t *pcbActualRead);
1451
1452/**
1453 * Sends a USB request.
1454 *
1455 * @param hserver Handle of VRDP server instance.
1456 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1457 * The identifier is always passed by the server as a parameter
1458 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
1459 * in the VRDPSERVERCALLBACK functions.
1460 * @param pvParm Function specific parameters buffer.
1461 * @param cbParm Size of the buffer.
1462 */
1463VRDPR3DECL(void) VRDPSendUSBRequest (HVRDPSERVER hserver,
1464 uint32_t u32ClientId,
1465 void *pvParm,
1466 uint32_t cbRarm);
1467
1468
1469/**
1470 * Called by the server when a reply is received from a client.
1471 *
1472 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptUSB.
1473 * @param u32ClientId Identifies the client that sent the reply.
1474 * @param u8Code The operation code VRDP_USB_REQ_*.
1475 * @param pvRet Points to data received from the client.
1476 * @param cbRet Size of the data in bytes.
1477 *
1478 * @return VBox error code.
1479 */
1480typedef DECLCALLBACK(int) FNVRDPUSBCALLBACK (void *pvCallback,
1481 uint32_t u32ClientId,
1482 uint8_t u8Code,
1483 const void *pvRet,
1484 uint32_t cbRet);
1485
1486typedef FNVRDPUSBCALLBACK *PFNVRDPUSBCALLBACK;
1487
1488/**
1489 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
1490 * - (0) client announces available clipboard formats;
1491 * - (1) client requests clipboard data.
1492 *
1493 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptClipboard.
1494 * @param u32ClientId Identifies the RDP client that sent the reply.
1495 * @param u32Function The cause of the callback.
1496 * @param u32Format Bitmask of reported formats or the format of received data.
1497 * @param pvData Reserved.
1498 * @param cbData Reserved.
1499 *
1500 * @return VBox error code.
1501 */
1502typedef DECLCALLBACK(int) FNVRDPCLIPBOARDCALLBACK (void *pvCallback,
1503 uint32_t u32ClientId,
1504 uint32_t u32Function,
1505 uint32_t u32Format,
1506 const void *pvData,
1507 uint32_t cbData);
1508
1509typedef FNVRDPCLIPBOARDCALLBACK *PFNVRDPCLIPBOARDCALLBACK;
1510
1511#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
1512#define VRDP_CLIENT_INTERCEPT_USB (0x2)
1513#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
1514
1515typedef struct _VRDPSERVERCALLBACK
1516{
1517 /* A client is logging in.
1518 *
1519 * @param pvUser The callback specific pointer.
1520 * @param u32ClientId An unique client identifier generated by the server.
1521 * @param pszUser The username.
1522 * @param pszPassword The password.
1523 * @param pszDomain The domain.
1524 *
1525 * @return VBox error code.
1526 */
1527 DECLCALLBACKMEMBER(int, pfnClientLogon) (void *pvUser,
1528 uint32_t u32ClientId,
1529 const char *pszUser,
1530 const char *pszPassword,
1531 const char *pszDomain);
1532 /* The client has connected.
1533 *
1534 * @param pvUser The callback specific pointer.
1535 * @param u32ClientId An unique client identifier generated by the server.
1536 */
1537 DECLCALLBACKMEMBER(void, pfnClientConnect) (void *pvUser,
1538 uint32_t u32ClientId);
1539 /* The client has been disconnected.
1540 *
1541 * @param pvUser The callback specific pointer.
1542 * @param u32ClientId An unique client identifier generated by the server.
1543 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
1544 */
1545 DECLCALLBACKMEMBER(void, pfnClientDisconnect) (void *pvUser,
1546 uint32_t u32ClientId,
1547 uint32_t fu32Intercepted);
1548 /* The client supports audio channel.
1549 */
1550 DECLCALLBACKMEMBER(void, pfnInterceptAudio) (void *pvUser,
1551 uint32_t u32ClientId);
1552 /* The client supports USB channel.
1553 */
1554 DECLCALLBACKMEMBER(void, pfnInterceptUSB) (void *pvUser,
1555 uint32_t u32ClientId,
1556 PFNVRDPUSBCALLBACK *ppfn,
1557 void **ppv);
1558 /* The client supports clipboard channel.
1559 */
1560 DECLCALLBACKMEMBER(void, pfnInterceptClipboard) (void *pvUser,
1561 uint32_t u32ClientId,
1562 PFNVRDPCLIPBOARDCALLBACK *ppfn,
1563 void **ppv);
1564} VRDPSERVERCALLBACK;
1565
1566/**
1567 * Set a callback pointers table that will be called by the server in certain situations.
1568 *
1569 * @param hserver Handle of VRDP server instance.
1570 * @param pCallback Pointer to VRDPSERVERCALLBACK structure with function pointers.
1571 * @param pvUser An pointer to be passed to the callback functions.
1572 */
1573VRDPR3DECL(void) VRDPSetCallback (HVRDPSERVER hserver, VRDPSERVERCALLBACK *pCallback, void *pvUser);
1574
1575/** Indexes of information values. */
1576
1577/** Whether a client is connected at the moment.
1578 * uint32_t
1579 */
1580#define VRDP_QI_ACTIVE (0)
1581
1582/** How many times a client connected up to current moment.
1583 * uint32_t
1584 */
1585#define VRDP_QI_NUMBER_OF_CLIENTS (1)
1586
1587/** When last connection was established.
1588 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
1589 */
1590#define VRDP_QI_BEGIN_TIME (2)
1591
1592/** When last connection was terminated or current time if connection still active.
1593 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
1594 */
1595#define VRDP_QI_END_TIME (3)
1596
1597/** How many bytes were sent in last (current) connection.
1598 * uint64_t
1599 */
1600#define VRDP_QI_BYTES_SENT (4)
1601
1602/** How many bytes were sent in all connections.
1603 * uint64_t
1604 */
1605#define VRDP_QI_BYTES_SENT_TOTAL (5)
1606
1607/** How many bytes were received in last (current) connection.
1608 * uint64_t
1609 */
1610#define VRDP_QI_BYTES_RECEIVED (6)
1611
1612/** How many bytes were received in all connections.
1613 * uint64_t
1614 */
1615#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
1616
1617/** Login user name supplied by the client.
1618 * UTF8 nul terminated string.
1619 */
1620#define VRDP_QI_USER (8)
1621
1622/** Login domain supplied by the client.
1623 * UTF8 nul terminated string.
1624 */
1625#define VRDP_QI_DOMAIN (9)
1626
1627/** The client name supplied by the client.
1628 * UTF8 nul terminated string.
1629 */
1630#define VRDP_QI_CLIENT_NAME (10)
1631
1632/** IP address of the client.
1633 * UTF8 nul terminated string.
1634 */
1635#define VRDP_QI_CLIENT_IP (11)
1636
1637/** The client software version number.
1638 * uint32_t.
1639 */
1640#define VRDP_QI_CLIENT_VERSION (12)
1641
1642/** Public key exchange method used when connection was established.
1643 * Values: 0 - RDP4 public key exchange scheme.
1644 * 1 - X509 sertificates were sent to client.
1645 * uint32_t.
1646 */
1647#define VRDP_QI_ENCRYPTION_STYLE (13)
1648
1649/**
1650 * Query various information from the VRDP server.
1651 *
1652 * @param index VRDP_QI_* identifier of information to be returned.
1653 * @param pvBuffer Address of memory buffer to which the information must be written.
1654 * @param cbBuffer Size of the memory buffer in bytes.
1655 * @param pcbOut Size in bytes of returned information value.
1656 *
1657 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
1658 * A value greater than cbBuffer means that information is too big to fit in the
1659 * buffer, in that case no information was placed to the buffer.
1660 */
1661VRDPR3DECL(void) VRDPQueryInfo (HVRDPSERVER hserver, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut);
1662#endif /* VRDP_NO_COM */
1663
1664__END_DECLS
1665
1666/** @} */
1667
1668#endif
1669
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