VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use