VirtualBox

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

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

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