VirtualBox

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

Last change on this file since 24130 was 23643, checked in by vboxsync, 15 years ago

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