VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use