VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use