VirtualBox

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

Last change on this file since 3427 was 3359, checked in by vboxsync, 18 years ago

Some VRDP_NO_COM code
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 49.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 RECONNECT message 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 cbRarm);
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 index VRDP_QI_* identifier of information to be returned.
702 * @param pvBuffer Address of memory buffer to which the information must be written.
703 * @param cbBuffer Size of the memory buffer in bytes.
704 * @param pcbOut Size in bytes of returned information value.
705 *
706 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
707 * A value greater than cbBuffer means that information is too big to fit in the
708 * buffer, in that case no information was placed to the buffer.
709 */
710 DECLCALLBACKMEMBER(void, VRDPQueryInfo)(HVRDPSERVER hServer,
711 uint32_t index,
712 void *pvBuffer,
713 uint32_t cbBuffer,
714 uint32_t *pcbOut);
715} VRDPENTRYPOINTS_1;
716
717#define VRDP_QP_NETWORK_PORT (1)
718#define VRDP_QP_NETWORK_ADDRESS (2)
719#define VRDP_QP_NUMBER_MONITORS (3)
720
721/** The VRDP server callbacks. Interface version 1. */
722typedef struct _VRDPCALLBACKS_1
723{
724 /** The header. */
725 VRDPINTERFACEHDR header;
726
727 /**
728 * Query various information, on how the VRDP server must operate, from the application.
729 *
730 * @param pvCallback The callback specific pointer.
731 * @param index VRDP_QP_* identifier of information to be returned.
732 * @param pvBuffer Address of memory buffer to which the information must be written.
733 * @param cbBuffer Size of the memory buffer in bytes.
734 * @param pcbOut Size in bytes of returned information value.
735 *
736 * @remark The VRDP server checks the *pcbOut. 0 there means no information was returned.
737 * A value greater than cbBuffer means that information is too big to fit in the
738 * buffer, in that case no information was placed to the buffer.
739 */
740 DECLCALLBACKMEMBER(void, VRDPQueryProperty)(void *pvCallback,
741 uint32_t index,
742 void *pvBuffer,
743 uint32_t cbBuffer,
744 uint32_t *pcbOut);
745
746 /* A client is logging in, the application must decide whether
747 * to let to connect the client. The server will drop the connection,
748 * when an error code is returned by the callback.
749 *
750 * @param pvCallback The callback specific pointer.
751 * @param u32ClientId An unique client identifier generated by the server.
752 * @param pszUser The username.
753 * @param pszPassword The password.
754 * @param pszDomain The domain.
755 *
756 * @return IPRT status code.
757 */
758 DECLCALLBACKMEMBER(int, VRDPCallbackClientLogon)(void *pvCallback,
759 uint32_t u32ClientId,
760 const char *pszUser,
761 const char *pszPassword,
762 const char *pszDomain);
763
764 /* The client has been successfully connected.
765 *
766 * @param pvCallback The callback specific pointer.
767 * @param u32ClientId An unique client identifier generated by the server.
768 */
769 DECLCALLBACKMEMBER(void, VRDPCallbackClientConnect)(void *pvCallback,
770 uint32_t u32ClientId);
771
772 /* The client has been disconnected.
773 *
774 * @param pvCallback The callback specific pointer.
775 * @param u32ClientId An unique client identifier generated by the server.
776 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
777 */
778 DECLCALLBACKMEMBER(void, VRDPCallbackClientDisconnect)(void *pvCallback,
779 uint32_t u32ClientId,
780 uint32_t fu32Intercepted);
781 /* The client supports one of RDP channels.
782 *
783 * @param pvCallback The callback specific pointer.
784 * @param u32ClientId An unique client identifier generated by the server.
785 * @param fu32Intercept What the client wants to intercept. One of VRDP_CLIENT_INTERCEPT_* flags.
786 * @param ppvIntercept The value to be passed to the channel specific callback.
787 *
788 * @return IPRT status code.
789 */
790 DECLCALLBACKMEMBER(int, VRDPCallbackIntercept)(void *pvCallback,
791 uint32_t u32ClientId,
792 uint32_t fu32Intercept,
793 void **ppvIntercept);
794
795 /**
796 * Called by the server when a reply is received from a client.
797 *
798 * @param pvCallback The callback specific pointer.
799 * @param ppvIntercept The value returned by VRDPCallbackIntercept for the VRDP_CLIENT_INTERCEPT_USB.
800 * @param u32ClientId Identifies the client that sent the reply.
801 * @param u8Code The operation code VRDP_USB_REQ_*.
802 * @param pvRet Points to data received from the client.
803 * @param cbRet Size of the data in bytes.
804 *
805 * @return IPRT status code.
806 */
807 DECLCALLBACKMEMBER(int, VRDPCallbackUSB)(void *pvCallback,
808 void *pvIntercept,
809 uint32_t u32ClientId,
810 uint8_t u8Code,
811 const void *pvRet,
812 uint32_t cbRet);
813
814 /**
815 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
816 * - (0) client announces available clipboard formats;
817 * - (1) client requests clipboard data.
818 *
819 * @param pvCallback The callback specific pointer.
820 * @param ppvIntercept The value returned by VRDPCallbackIntercept for the VRDP_CLIENT_INTERCEPT_CLIPBOARD.
821 * @param u32ClientId Identifies the RDP client that sent the reply.
822 * @param u32Function The cause of the callback.
823 * @param u32Format Bitmask of reported formats or the format of received data.
824 * @param pvData Reserved.
825 * @param cbData Reserved.
826 *
827 * @return IPRT status code.
828 */
829 DECLCALLBACKMEMBER(int, VRDPCallbackClipboard)(void *pvCallback,
830 void *pvIntercept,
831 uint32_t u32ClientId,
832 uint32_t u32Function,
833 uint32_t u32Format,
834 const void *pvData,
835 uint32_t cbData);
836} VRDPCALLBACKS_1;
837
838/**
839 * Create a new VRDP server instance. The instance is fully functional but refuses
840 * client connections until the entry point VRDPEnableConnections is called by the application.
841 *
842 * The caller prepares the callbacks structure. The header.u64Version field
843 * must be initialized with the version of the insterface to use.
844 * The server will initialize the callbacks table to match the requested interface.
845 *
846 * @param pCallback Pointer to the application callbacks which let the server to fetch
847 * the configuration data and to access the desktop.
848 * @param pvCallback The callback specific pointer to be passed back to the application.
849 * @param ppEntryPoints Where to store the pointer to the VRDP entry points structure.
850 * @param phServer Pointer to the created server instance handle.
851 *
852 * @return IPRT status code.
853 */
854VRDPDECL(int) VRDPCreateServer (const VRDPINTERFACEHDR *pCallbacks,
855 void *pvCallback,
856 VRDPINTERFACEHDR **ppEntryPoints,
857 HVRDPSERVER *phServer);
858
859
860#else
861/**
862 * Start server for the specified IConsole.
863 *
864 * @return VBox status code
865 * @param pconsole Pointer to IConsole instance to fetch display, mouse and keyboard interfaces.
866 * @param pvrdpserver Pointer to IVRDPServer instance to fetch configuration.
867 * @param phserver Pointer to server instance handle,
868 * created by the function.
869 */
870VRDPR3DECL(int) VRDPStartServer (IConsole *pconsole, IVRDPServer *pvrdpserver, HVRDPSERVER *phserver);
871
872
873/**
874 * Shutdown server.
875 *
876 * @param hserver Handle of VRDP server instance to be stopped.
877 */
878VRDPR3DECL(void) VRDPShutdownServer (HVRDPSERVER hserver);
879
880
881/**
882 * Send framebuffer bitmap to client.
883 *
884 * @param hserver Handle of VRDP server instance.
885 * @param x top left horizontal coordinate in framebuffer.
886 * @param y top left vertical coordinate in framebuffer.
887 * @param w width of rectangle.
888 * @param h height of rectangle.
889 */
890VRDPR3DECL(void) VRDPSendUpdateBitmap (HVRDPSERVER hserver, unsigned uScreenId, unsigned x, unsigned y, unsigned w, unsigned h);
891
892/**
893 * Inform client that display was resized.
894 * New width and height are taken from the current framebuffer.
895 *
896 * @param hserver Handle of VRDP server instance.
897 */
898VRDPR3DECL(void) VRDPSendResize (HVRDPSERVER hserver);
899
900/**
901 * Send an update in accelerated mode.
902 *
903 * @param hserver Handle of VRDP server instance.
904 * @param pvUpdate The update information. Actually pointer to VBoxGuest.h::VBVACMDHDR structure with extra data.
905 * @param cbUpdate Size of the update data.
906 */
907VRDPR3DECL(void) VRDPSendUpdate (HVRDPSERVER hserver, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate);
908
909/** @todo comment the structure. */
910typedef struct _VRDPCOLORPOINTER
911{
912 uint16_t xHot;
913 uint16_t yHot;
914 uint16_t width;
915 uint16_t height;
916 uint16_t masklen;
917 uint16_t datalen;
918 uint32_t vrdpInternal;
919} VRDPCOLORPOINTER;
920
921typedef VRDPCOLORPOINTER *PVRDPCOLORPOINTER;
922
923/**
924 * Set mouse pointer shape.
925 *
926 * @param hserver Handle of VRDP server instance.
927 * @param porder The pointer shape information.
928 */
929VRDPR3DECL(void) VRDPSendColorPointer (HVRDPSERVER hserver, PVRDPCOLORPOINTER pdata);
930
931/**
932 * Hide mouse pointer.
933 *
934 * @param hserver Handle of VRDP server instance.
935 */
936VRDPR3DECL(void) VRDPSendHidePointer (HVRDPSERVER hserver);
937
938/** Audio format information packed in a 32 bit value. */
939typedef uint32_t VRDPAUDIOFORMAT;
940
941/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
942#define VRDP_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
943
944/** Decode frequency. */
945#define VRDP_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
946/** Decode number of channels. */
947#define VRDP_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
948/** Decode number signess. */
949#define VRDP_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
950/** Decode number of bits per sample. */
951#define VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
952/** Decode number of bytes per sample. */
953#define VRDP_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
954
955/**
956 * Queues the samples to be sent to client.
957 *
958 * @param hserver Handle of VRDP server instance.
959 * @param pvSamples Address of samples to be sent.
960 * @param cSamples Number of samples.
961 * @param format Encoded audio format for these samples.
962 */
963VRDPR3DECL(void) VRDPSendAudioSamples (HVRDPSERVER hserver, void *pvSamples, uint32_t cSamples, VRDPAUDIOFORMAT format);
964
965/**
966 * Sets sound volume on client.
967 *
968 * @param hserver Handle of VRDP server instance.
969 * @param left 0..0xFFFF volume level for left channel.
970 * @param right 0..0xFFFF volume level for right channel.
971 */
972VRDPR3DECL(void) VRDPSendAudioVolume (HVRDPSERVER hserver, uint16_t left, uint16_t right);
973
974
975/*
976 * Remote USB backend protocol.
977 */
978
979/* The version of Remote USB Protocol. */
980#define VRDP_USB_VERSION (1)
981
982/** USB backend operations. */
983#define VRDP_USB_REQ_OPEN (0)
984#define VRDP_USB_REQ_CLOSE (1)
985#define VRDP_USB_REQ_RESET (2)
986#define VRDP_USB_REQ_SET_CONFIG (3)
987#define VRDP_USB_REQ_CLAIM_INTERFACE (4)
988#define VRDP_USB_REQ_RELEASE_INTERFACE (5)
989#define VRDP_USB_REQ_INTERFACE_SETTING (6)
990#define VRDP_USB_REQ_QUEUE_URB (7)
991#define VRDP_USB_REQ_REAP_URB (8)
992#define VRDP_USB_REQ_CLEAR_HALTED_EP (9)
993#define VRDP_USB_REQ_CANCEL_URB (10)
994
995/** USB service operations. */
996#define VRDP_USB_REQ_DEVICE_LIST (11)
997#define VRDP_USB_REQ_NEGOTIATE (12)
998
999/** An operation completion status is a byte. */
1000typedef uint8_t VRDPUSBSTATUS;
1001
1002/** USB device identifier is an 32 bit value. */
1003typedef uint32_t VRDPUSBDEVID;
1004
1005/** Status codes. */
1006#define VRDP_USB_STATUS_SUCCESS ((VRDPUSBSTATUS)0)
1007#define VRDP_USB_STATUS_ACCESS_DENIED ((VRDPUSBSTATUS)1)
1008#define VRDP_USB_STATUS_DEVICE_REMOVED ((VRDPUSBSTATUS)2)
1009
1010/*
1011 * Data structures to use with VRDPSendUSBRequest.
1012 * The *RET* structures always represent the layout of VRDP data.
1013 * The *PARM* structures normally the same as VRDP layout.
1014 * However the VRDP_USB_REQ_QUEUE_URB_PARM has a pointer to
1015 * URB data in place where actual data will be in VRDP layout.
1016 *
1017 * Since replies (*RET*) are asynchronous, the 'success'
1018 * replies are not required for operations which return
1019 * only the status code (VRDPUSBREQRETHDR only):
1020 * VRDP_USB_REQ_OPEN
1021 * VRDP_USB_REQ_RESET
1022 * VRDP_USB_REQ_SET_CONFIG
1023 * VRDP_USB_REQ_CLAIM_INTERFACE
1024 * VRDP_USB_REQ_RELEASE_INTERFACE
1025 * VRDP_USB_REQ_INTERFACE_SETTING
1026 * VRDP_USB_REQ_CLEAR_HALTED_EP
1027 *
1028 */
1029
1030/* VRDP layout has no aligments. */
1031#pragma pack(1)
1032
1033/* Common header for all VRDP USB packets. After the reply hdr follows *PARM* or *RET* data. */
1034typedef struct _VRDPUSBPKTHDR
1035{
1036 /* Total length of the reply NOT including the 'length' field. */
1037 uint32_t length;
1038 /* The operation code for which the reply was sent by the client. */
1039 uint8_t code;
1040} VRDPUSBPKTHDR;
1041
1042/* Common header for all return structures. */
1043typedef struct _VRDPUSBREQRETHDR
1044{
1045 /* Device status. */
1046 VRDPUSBSTATUS status;
1047 /* Device id. */
1048 VRDPUSBDEVID id;
1049} VRDPUSBREQRETHDR;
1050
1051
1052/* VRDP_USB_REQ_OPEN
1053 */
1054typedef struct _VRDP_USB_REQ_OPEN_PARM
1055{
1056 uint8_t code;
1057 VRDPUSBDEVID id;
1058} VRDP_USB_REQ_OPEN_PARM;
1059
1060typedef struct _VRDP_USB_REQ_OPEN_RET
1061{
1062 VRDPUSBREQRETHDR hdr;
1063} VRDP_USB_REQ_OPEN_RET;
1064
1065
1066/* VRDP_USB_REQ_CLOSE
1067 */
1068typedef struct _VRDP_USB_REQ_CLOSE_PARM
1069{
1070 uint8_t code;
1071 VRDPUSBDEVID id;
1072} VRDP_USB_REQ_CLOSE_PARM;
1073
1074/* The close request has no returned data. */
1075
1076
1077/* VRDP_USB_REQ_RESET
1078 */
1079typedef struct _VRDP_USB_REQ_RESET_PARM
1080{
1081 uint8_t code;
1082 VRDPUSBDEVID id;
1083} VRDP_USB_REQ_RESET_PARM;
1084
1085typedef struct _VRDP_USB_REQ_RESET_RET
1086{
1087 VRDPUSBREQRETHDR hdr;
1088} VRDP_USB_REQ_RESET_RET;
1089
1090
1091/* VRDP_USB_REQ_SET_CONFIG
1092 */
1093typedef struct _VRDP_USB_REQ_SET_CONFIG_PARM
1094{
1095 uint8_t code;
1096 VRDPUSBDEVID id;
1097 uint8_t configuration;
1098} VRDP_USB_REQ_SET_CONFIG_PARM;
1099
1100typedef struct _VRDP_USB_REQ_SET_CONFIG_RET
1101{
1102 VRDPUSBREQRETHDR hdr;
1103} VRDP_USB_REQ_SET_CONFIG_RET;
1104
1105
1106/* VRDP_USB_REQ_CLAIM_INTERFACE
1107 */
1108typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_PARM
1109{
1110 uint8_t code;
1111 VRDPUSBDEVID id;
1112 uint8_t iface;
1113} VRDP_USB_REQ_CLAIM_INTERFACE_PARM;
1114
1115typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_RET
1116{
1117 VRDPUSBREQRETHDR hdr;
1118} VRDP_USB_REQ_CLAIM_INTERFACE_RET;
1119
1120
1121/* VRDP_USB_REQ_RELEASE_INTERFACE
1122 */
1123typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_PARM
1124{
1125 uint8_t code;
1126 VRDPUSBDEVID id;
1127 uint8_t iface;
1128} VRDP_USB_REQ_RELEASE_INTERFACE_PARM;
1129
1130typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_RET
1131{
1132 VRDPUSBREQRETHDR hdr;
1133} VRDP_USB_REQ_RELEASE_INTERFACE_RET;
1134
1135
1136/* VRDP_USB_REQ_INTERFACE_SETTING
1137 */
1138typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_PARM
1139{
1140 uint8_t code;
1141 VRDPUSBDEVID id;
1142 uint8_t iface;
1143 uint8_t setting;
1144} VRDP_USB_REQ_INTERFACE_SETTING_PARM;
1145
1146typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_RET
1147{
1148 VRDPUSBREQRETHDR hdr;
1149} VRDP_USB_REQ_INTERFACE_SETTING_RET;
1150
1151
1152/* VRDP_USB_REQ_QUEUE_URB
1153 */
1154
1155#define VRDP_USB_TRANSFER_TYPE_CTRL (0)
1156#define VRDP_USB_TRANSFER_TYPE_ISOC (1)
1157#define VRDP_USB_TRANSFER_TYPE_BULK (2)
1158#define VRDP_USB_TRANSFER_TYPE_INTR (3)
1159#define VRDP_USB_TRANSFER_TYPE_MSG (4)
1160
1161#define VRDP_USB_DIRECTION_SETUP (0)
1162#define VRDP_USB_DIRECTION_IN (1)
1163#define VRDP_USB_DIRECTION_OUT (2)
1164
1165typedef struct _VRDP_USB_REQ_QUEUE_URB_PARM
1166{
1167 uint8_t code;
1168 VRDPUSBDEVID id;
1169 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
1170 uint8_t type;
1171 uint8_t ep;
1172 uint8_t direction;
1173 uint32_t urblen; /* Length of the URB. */
1174 uint32_t datalen; /* Length of the data. */
1175 void *data; /* In RDP layout the data follow. */
1176} VRDP_USB_REQ_QUEUE_URB_PARM;
1177
1178/* The queue URB has no explicit return. The reap URB reply will be
1179 * eventually the indirect result.
1180 */
1181
1182
1183/* VRDP_USB_REQ_REAP_URB
1184 * Notificationg from server to client that server expects an URB
1185 * from any device.
1186 * Only sent if negotiated URB return method is polling.
1187 * Normally, the client will send URBs back as soon as they are ready.
1188 */
1189typedef struct _VRDP_USB_REQ_REAP_URB_PARM
1190{
1191 uint8_t code;
1192} VRDP_USB_REQ_REAP_URB_PARM;
1193
1194
1195#define VRDP_USB_XFER_OK (0)
1196#define VRDP_USB_XFER_STALL (1)
1197#define VRDP_USB_XFER_DNR (2)
1198#define VRDP_USB_XFER_CRC (3)
1199
1200#define VRDP_USB_REAP_FLAG_CONTINUED (0x0)
1201#define VRDP_USB_REAP_FLAG_LAST (0x1)
1202
1203#define VRDP_USB_REAP_VALID_FLAGS (VRDP_USB_REAP_FLAG_LAST)
1204
1205typedef struct _VRDPUSBREQREAPURBBODY
1206{
1207 VRDPUSBDEVID id; /* From which device the URB arrives. */
1208 uint8_t flags; /* VRDP_USB_REAP_FLAG_* */
1209 uint8_t error; /* VRDP_USB_XFER_* */
1210 uint32_t handle; /* Handle of returned URB. Not 0. */
1211 uint32_t len; /* Length of data actually transferred. */
1212 /* Data follow. */
1213} VRDPUSBREQREAPURBBODY;
1214
1215typedef struct _VRDP_USB_REQ_REAP_URB_RET
1216{
1217 /* The REAP URB has no header, only completed URBs are returned. */
1218 VRDPUSBREQREAPURBBODY body;
1219 /* Another body may follow, depending on flags. */
1220} VRDP_USB_REQ_REAP_URB_RET;
1221
1222
1223/* VRDP_USB_REQ_CLEAR_HALTED_EP
1224 */
1225typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_PARM
1226{
1227 uint8_t code;
1228 VRDPUSBDEVID id;
1229 uint8_t ep;
1230} VRDP_USB_REQ_CLEAR_HALTED_EP_PARM;
1231
1232typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_RET
1233{
1234 VRDPUSBREQRETHDR hdr;
1235} VRDP_USB_REQ_CLEAR_HALTED_EP_RET;
1236
1237
1238/* VRDP_USB_REQ_CANCEL_URB
1239 */
1240typedef struct _VRDP_USB_REQ_CANCEL_URB_PARM
1241{
1242 uint8_t code;
1243 VRDPUSBDEVID id;
1244 uint32_t handle;
1245} VRDP_USB_REQ_CANCEL_URB_PARM;
1246
1247/* The cancel URB request has no return. */
1248
1249
1250/* VRDP_USB_REQ_DEVICE_LIST
1251 *
1252 * Server polls USB devices on client by sending this request
1253 * periodically. Client sends back a list of all devices
1254 * connected to it. Each device is assigned with an identifier,
1255 * that is used to distinguish the particular device.
1256 */
1257typedef struct _VRDP_USB_REQ_DEVICE_LIST_PARM
1258{
1259 uint8_t code;
1260} VRDP_USB_REQ_DEVICE_LIST_PARM;
1261
1262/* Data is a list of the following variable length structures. */
1263typedef struct _VRDPUSBDEVICEDESC
1264{
1265 /* Offset of the next structure. 0 if last. */
1266 uint16_t oNext;
1267
1268 /* Identifier of the device assigned by client. */
1269 VRDPUSBDEVID id;
1270
1271 /** USB version number. */
1272 uint16_t bcdUSB;
1273 /** Device class. */
1274 uint8_t bDeviceClass;
1275 /** Device subclass. */
1276 uint8_t bDeviceSubClass;
1277 /** Device protocol */
1278 uint8_t bDeviceProtocol;
1279 /** Vendor ID. */
1280 uint16_t idVendor;
1281 /** Product ID. */
1282 uint16_t idProduct;
1283 /** Revision, integer part. */
1284 uint16_t bcdRev;
1285 /** Manufacturer string. */
1286 uint16_t oManufacturer;
1287 /** Product string. */
1288 uint16_t oProduct;
1289 /** Serial number string. */
1290 uint16_t oSerialNumber;
1291 /** Physical USB port the device is connected to. */
1292 uint16_t idPort;
1293
1294} VRDPUSBDEVICEDESC;
1295
1296typedef struct _VRDP_USB_REQ_DEVICE_LIST_RET
1297{
1298 VRDPUSBDEVICEDESC body;
1299 /* Other devices may follow.
1300 * The list ends with (uint16_t)0,
1301 * which means that an empty list consists of 2 zero bytes.
1302 */
1303} VRDP_USB_REQ_DEVICE_LIST_RET;
1304
1305typedef struct _VRDPUSBREQNEGOTIATEPARM
1306{
1307 uint8_t code;
1308
1309 /* Remote USB Protocol version. */
1310 uint32_t version;
1311
1312} VRDPUSBREQNEGOTIATEPARM;
1313
1314#define VRDP_USB_CAPS_FLAG_ASYNC (0x0)
1315#define VRDP_USB_CAPS_FLAG_POLL (0x1)
1316
1317#define VRDP_USB_CAPS_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL)
1318
1319typedef struct _VRDPUSBREQNEGOTIATERET
1320{
1321 uint8_t flags;
1322} VRDPUSBREQNEGOTIATERET;
1323
1324#pragma pack()
1325
1326
1327#define VRDP_CLIPBOARD_FORMAT_NULL (0x0)
1328#define VRDP_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
1329#define VRDP_CLIPBOARD_FORMAT_BITMAP (0x2)
1330#define VRDP_CLIPBOARD_FORMAT_HTML (0x4)
1331
1332#define VRDP_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
1333#define VRDP_CLIPBOARD_FUNCTION_DATA_READ (1)
1334#define VRDP_CLIPBOARD_FUNCTION_DATA_WRITE (2)
1335
1336/**
1337 * Called by the host when (VRDP_CLIPBOARD_FUNCTION_*):
1338 * - (0) guest announces available clipboard formats;
1339 * - (1) guest requests clipboard data;
1340 * - (2) guest responds to the client's request for clipboard data.
1341 *
1342 * @param hserver The VRDP server handle.
1343 * @param u32Function The cause of the call.
1344 * @param u32Format Bitmask of announced formats or the format of data.
1345 * @param pvData Points to: (1) buffer to be filled with clients data;
1346 * (2) data from the host.
1347 * @param cbData Size of 'pvData' buffer in bytes.
1348 * @param pcbActualRead Size of the copied data in bytes.
1349 *
1350 */
1351VRDPR3DECL(void) VRDPClipboard (HVRDPSERVER hserver,
1352 uint32_t u32Function,
1353 uint32_t u32Format,
1354 void *pvData,
1355 uint32_t cbData,
1356 uint32_t *pcbActualRead);
1357
1358/**
1359 * Sends a USB request.
1360 *
1361 * @param hserver Handle of VRDP server instance.
1362 * @param u32ClientId An identifier that allows the server to find the corresponding client.
1363 * The identifier is always passed by the server as a parameter
1364 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
1365 * in the VRDPSERVERCALLBACK functions.
1366 * @param pvParm Function specific parameters buffer.
1367 * @param cbParm Size of the buffer.
1368 */
1369VRDPR3DECL(void) VRDPSendUSBRequest (HVRDPSERVER hserver,
1370 uint32_t u32ClientId,
1371 void *pvParm,
1372 uint32_t cbRarm);
1373
1374
1375/**
1376 * Called by the server when a reply is received from a client.
1377 *
1378 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptUSB.
1379 * @param u32ClientId Identifies the client that sent the reply.
1380 * @param u8Code The operation code VRDP_USB_REQ_*.
1381 * @param pvRet Points to data received from the client.
1382 * @param cbRet Size of the data in bytes.
1383 *
1384 * @return VBox error code.
1385 */
1386typedef DECLCALLBACK(int) FNVRDPUSBCALLBACK (void *pvCallback,
1387 uint32_t u32ClientId,
1388 uint8_t u8Code,
1389 const void *pvRet,
1390 uint32_t cbRet);
1391
1392typedef FNVRDPUSBCALLBACK *PFNVRDPUSBCALLBACK;
1393
1394/**
1395 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
1396 * - (0) client announces available clipboard formats;
1397 * - (1) client requests clipboard data.
1398 *
1399 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptClipboard.
1400 * @param u32ClientId Identifies the RDP client that sent the reply.
1401 * @param u32Function The cause of the callback.
1402 * @param u32Format Bitmask of reported formats or the format of received data.
1403 * @param pvData Reserved.
1404 * @param cbData Reserved.
1405 *
1406 * @return VBox error code.
1407 */
1408typedef DECLCALLBACK(int) FNVRDPCLIPBOARDCALLBACK (void *pvCallback,
1409 uint32_t u32ClientId,
1410 uint32_t u32Function,
1411 uint32_t u32Format,
1412 const void *pvData,
1413 uint32_t cbData);
1414
1415typedef FNVRDPCLIPBOARDCALLBACK *PFNVRDPCLIPBOARDCALLBACK;
1416
1417#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
1418#define VRDP_CLIENT_INTERCEPT_USB (0x2)
1419#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
1420
1421typedef struct _VRDPSERVERCALLBACK
1422{
1423 /* A client is logging in.
1424 *
1425 * @param pvUser The callback specific pointer.
1426 * @param u32ClientId An unique client identifier generated by the server.
1427 * @param pszUser The username.
1428 * @param pszPassword The password.
1429 * @param pszDomain The domain.
1430 *
1431 * @return VBox error code.
1432 */
1433 DECLCALLBACKMEMBER(int, pfnClientLogon) (void *pvUser,
1434 uint32_t u32ClientId,
1435 const char *pszUser,
1436 const char *pszPassword,
1437 const char *pszDomain);
1438 /* The client has connected.
1439 *
1440 * @param pvUser The callback specific pointer.
1441 * @param u32ClientId An unique client identifier generated by the server.
1442 */
1443 DECLCALLBACKMEMBER(void, pfnClientConnect) (void *pvUser,
1444 uint32_t u32ClientId);
1445 /* The client has been disconnected.
1446 *
1447 * @param pvUser The callback specific pointer.
1448 * @param u32ClientId An unique client identifier generated by the server.
1449 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
1450 */
1451 DECLCALLBACKMEMBER(void, pfnClientDisconnect) (void *pvUser,
1452 uint32_t u32ClientId,
1453 uint32_t fu32Intercepted);
1454 /* The client supports audio channel.
1455 */
1456 DECLCALLBACKMEMBER(void, pfnInterceptAudio) (void *pvUser,
1457 uint32_t u32ClientId);
1458 /* The client supports USB channel.
1459 */
1460 DECLCALLBACKMEMBER(void, pfnInterceptUSB) (void *pvUser,
1461 uint32_t u32ClientId,
1462 PFNVRDPUSBCALLBACK *ppfn,
1463 void **ppv);
1464 /* The client supports clipboard channel.
1465 */
1466 DECLCALLBACKMEMBER(void, pfnInterceptClipboard) (void *pvUser,
1467 uint32_t u32ClientId,
1468 PFNVRDPCLIPBOARDCALLBACK *ppfn,
1469 void **ppv);
1470} VRDPSERVERCALLBACK;
1471
1472/**
1473 * Set a callback pointers table that will be called by the server in certain situations.
1474 *
1475 * @param hserver Handle of VRDP server instance.
1476 * @param pCallback Pointer to VRDPSERVERCALLBACK structure with function pointers.
1477 * @param pvUser An pointer to be passed to the callback functions.
1478 */
1479VRDPR3DECL(void) VRDPSetCallback (HVRDPSERVER hserver, VRDPSERVERCALLBACK *pCallback, void *pvUser);
1480
1481/** Indexes of information values. */
1482
1483/** Whether a client is connected at the moment.
1484 * uint32_t
1485 */
1486#define VRDP_QI_ACTIVE (0)
1487
1488/** How many times a client connected up to current moment.
1489 * uint32_t
1490 */
1491#define VRDP_QI_NUMBER_OF_CLIENTS (1)
1492
1493/** When last connection was established.
1494 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
1495 */
1496#define VRDP_QI_BEGIN_TIME (2)
1497
1498/** When last connection was terminated or current time if connection still active.
1499 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
1500 */
1501#define VRDP_QI_END_TIME (3)
1502
1503/** How many bytes were sent in last (current) connection.
1504 * uint64_t
1505 */
1506#define VRDP_QI_BYTES_SENT (4)
1507
1508/** How many bytes were sent in all connections.
1509 * uint64_t
1510 */
1511#define VRDP_QI_BYTES_SENT_TOTAL (5)
1512
1513/** How many bytes were received in last (current) connection.
1514 * uint64_t
1515 */
1516#define VRDP_QI_BYTES_RECEIVED (6)
1517
1518/** How many bytes were received in all connections.
1519 * uint64_t
1520 */
1521#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
1522
1523/** Login user name supplied by the client.
1524 * UTF8 nul terminated string.
1525 */
1526#define VRDP_QI_USER (8)
1527
1528/** Login domain supplied by the client.
1529 * UTF8 nul terminated string.
1530 */
1531#define VRDP_QI_DOMAIN (9)
1532
1533/** The client name supplied by the client.
1534 * UTF8 nul terminated string.
1535 */
1536#define VRDP_QI_CLIENT_NAME (10)
1537
1538/** IP address of the client.
1539 * UTF8 nul terminated string.
1540 */
1541#define VRDP_QI_CLIENT_IP (11)
1542
1543/** The client software version number.
1544 * uint32_t.
1545 */
1546#define VRDP_QI_CLIENT_VERSION (12)
1547
1548/** Public key exchange method used when connection was established.
1549 * Values: 0 - RDP4 public key exchange scheme.
1550 * 1 - X509 sertificates were sent to client.
1551 * uint32_t.
1552 */
1553#define VRDP_QI_ENCRYPTION_STYLE (13)
1554
1555/**
1556 * Query various information from the VRDP server.
1557 *
1558 * @param index VRDP_QI_* identifier of information to be returned.
1559 * @param pvBuffer Address of memory buffer to which the information must be written.
1560 * @param cbBuffer Size of the memory buffer in bytes.
1561 * @param pcbOut Size in bytes of returned information value.
1562 *
1563 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
1564 * A value greater than cbBuffer means that information is too big to fit in the
1565 * buffer, in that case no information was placed to the buffer.
1566 */
1567VRDPR3DECL(void) VRDPQueryInfo (HVRDPSERVER hserver, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut);
1568#endif /* VRDP_NO_COM */
1569
1570__END_DECLS
1571
1572/** @} */
1573
1574#endif /* __VBox_vrdpapi_h__ */
1575
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette