VirtualBox

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

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

InnoTek -> innotek: all the headers and comments.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 25.4 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 * If you received this file as part of a commercial VirtualBox
18 * distribution, then only the terms of your commercial VirtualBox
19 * license agreement apply instead of the previous paragraph.
20 */
21
22#ifndef __VBox_vrdpapi_h__
23#define __VBox_vrdpapi_h__
24
25#include <VBox/cdefs.h>
26#include <VBox/types.h>
27
28#ifdef IN_RING0
29# error "There are no VRDP APIs available in Ring-0 Host Context!"
30#endif
31#ifdef IN_GC
32# error "There are no VRDP APIs available Guest Context!"
33#endif
34
35
36/** @defgroup grp_vrdp VRDP
37 * VirtualBox Remote Desktop Protocol (VRDP) interface that allows to use
38 * the VRDP server.
39 * @{
40 */
41
42/** Flags for VDRPSetFramebuffer */
43#define VRDP_INTERNAL_FRAMEBUFFER (0)
44#define VRDP_EXTERNAL_FRAMEBUFFER (1)
45
46/** Default port that VRDP binds to */
47#define VRDP_DEFAULT_PORT (3389)
48
49__BEGIN_DECLS
50
51/* Forward declaration */
52
53#ifdef __cplusplus
54
55class VRDPServer;
56typedef class VRDPServer *HVRDPSERVER;
57
58#else
59
60struct VRDPServer;
61typedef struct VRDPServer *HVRDPSERVER;
62
63#endif
64
65/**
66 * Start server for the specified IConsole.
67 *
68 * @return VBox status code
69 * @param pconsole Pointer to IConsole instance to fetch display, mouse and keyboard interfaces.
70 * @param pvrdpserver Pointer to IVRDPServer instance to fetch configuration.
71 * @param phserver Pointer to server instance handle,
72 * created by the function.
73 */
74VRDPR3DECL(int) VRDPStartServer (IConsole *pconsole, IVRDPServer *pvrdpserver, HVRDPSERVER *phserver);
75
76
77/**
78 * Set framebuffer which will be delivered to client.
79 *
80 * @param hserver Handle of VRDP server instance.
81 * @param pframebuffer Pointer to external IFramebuffer to be used.
82 * @param flags VRDP_EXTERNAL_FRAMEBUFFER - the server must use supplied
83 * framebuffer or do not use framebuffer if pframebuffer == NULL
84 * VRDP_INTERNAL_FRAMEBUFFER - the server must create internal
85 * framebuffer and register it with Machine's IDisplay,
86 * pframebuffer ignored.
87 */
88VRDPR3DECL(int) VRDPSetFramebuffer (HVRDPSERVER hserver, IFramebuffer *pframebuffer, uint32_t flags);
89
90/**
91 * Shutdown server.
92 *
93 * @param hserver Handle of VRDP server instance to be stopped.
94 */
95VRDPR3DECL(void) VRDPShutdownServer (HVRDPSERVER hserver);
96
97
98/**
99 * Send framebuffer bitmap to client.
100 *
101 * @param hserver Handle of VRDP server instance.
102 * @param x top left horizontal coordinate in framebuffer.
103 * @param y top left vertical coordinate in framebuffer.
104 * @param w width of rectangle.
105 * @param h height of rectangle.
106 */
107VRDPR3DECL(void) VRDPSendUpdateBitmap (HVRDPSERVER hserver, unsigned x, unsigned y, unsigned w, unsigned h);
108
109/**
110 * Inform client that display was resized.
111 * New width and height are taken from the current framebuffer.
112 *
113 * @param hserver Handle of VRDP server instance.
114 */
115VRDPR3DECL(void) VRDPSendResize (HVRDPSERVER hserver);
116
117/**
118 * Send an update in accelerated mode.
119 *
120 * @param hserver Handle of VRDP server instance.
121 * @param pvUpdate The update information. Actually pointer to VBoxGuest.h::VBVACMDHDR structure with extra data.
122 * @param cbUpdate Size of the update data.
123 */
124VRDPR3DECL(void) VRDPSendUpdate (HVRDPSERVER hserver, void *pvUpdate, uint32_t cbUpdate);
125
126/** @todo comment the structure. */
127typedef struct _VRDPCOLORPOINTER
128{
129 uint16_t xHot;
130 uint16_t yHot;
131 uint16_t width;
132 uint16_t height;
133 uint16_t masklen;
134 uint16_t datalen;
135 uint32_t vrdpInternal;
136} VRDPCOLORPOINTER;
137
138typedef VRDPCOLORPOINTER *PVRDPCOLORPOINTER;
139
140/**
141 * Set mouse pointer shape.
142 *
143 * @param hserver Handle of VRDP server instance.
144 * @param porder The pointer shape information.
145 */
146VRDPR3DECL(void) VRDPSendColorPointer (HVRDPSERVER hserver, PVRDPCOLORPOINTER pdata);
147
148/**
149 * Hide mouse pointer.
150 *
151 * @param hserver Handle of VRDP server instance.
152 */
153VRDPR3DECL(void) VRDPSendHidePointer (HVRDPSERVER hserver);
154
155/** Audio format information packed in a 32 bit value. */
156typedef uint32_t VRDPAUDIOFORMAT;
157
158/** Constructs 32 bit value for given frequency, number of channel and bits per sample. */
159#define VRDP_AUDIO_FMT_MAKE(freq, c, bps, s) ((((s) & 0x1) << 28) + (((bps) & 0xFF) << 20) + (((c) & 0xF) << 16) + ((freq) & 0xFFFF))
160
161/** Decode frequency. */
162#define VRDP_AUDIO_FMT_SAMPLE_FREQ(a) ((a) & 0xFFFF)
163/** Decode number of channels. */
164#define VRDP_AUDIO_FMT_CHANNELS(a) (((a) >> 16) & 0xF)
165/** Decode number signess. */
166#define VRDP_AUDIO_FMT_SIGNED(a) (((a) >> 28) & 0x1)
167/** Decode number of bits per sample. */
168#define VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) (((a) >> 20) & 0xFF)
169/** Decode number of bytes per sample. */
170#define VRDP_AUDIO_FMT_BYTES_PER_SAMPLE(a) ((VRDP_AUDIO_FMT_BITS_PER_SAMPLE(a) + 7) / 8)
171
172/**
173 * Queues the samples to be sent to client.
174 *
175 * @param hserver Handle of VRDP server instance.
176 * @param pvSamples Address of samples to be sent.
177 * @param cSamples Number of samples.
178 * @param format Encoded audio format for these samples.
179 */
180VRDPR3DECL(void) VRDPSendAudioSamples (HVRDPSERVER hserver, void *pvSamples, uint32_t cSamples, VRDPAUDIOFORMAT format);
181
182/**
183 * Sets sound volume on client.
184 *
185 * @param hserver Handle of VRDP server instance.
186 * @param left 0..0xFFFF volume level for left channel.
187 * @param right 0..0xFFFF volume level for right channel.
188 */
189VRDPR3DECL(void) VRDPSendAudioVolume (HVRDPSERVER hserver, uint16_t left, uint16_t right);
190
191
192/*
193 * Remote USB backend protocol.
194 */
195
196/* The version of Remote USB Protocol. */
197#define VRDP_USB_VERSION (1)
198
199/** USB backend operations. */
200#define VRDP_USB_REQ_OPEN (0)
201#define VRDP_USB_REQ_CLOSE (1)
202#define VRDP_USB_REQ_RESET (2)
203#define VRDP_USB_REQ_SET_CONFIG (3)
204#define VRDP_USB_REQ_CLAIM_INTERFACE (4)
205#define VRDP_USB_REQ_RELEASE_INTERFACE (5)
206#define VRDP_USB_REQ_INTERFACE_SETTING (6)
207#define VRDP_USB_REQ_QUEUE_URB (7)
208#define VRDP_USB_REQ_REAP_URB (8)
209#define VRDP_USB_REQ_CLEAR_HALTED_EP (9)
210#define VRDP_USB_REQ_CANCEL_URB (10)
211
212/** USB service operations. */
213#define VRDP_USB_REQ_DEVICE_LIST (11)
214#define VRDP_USB_REQ_NEGOTIATE (12)
215
216/** An operation completion status is a byte. */
217typedef uint8_t VRDPUSBSTATUS;
218
219/** USB device identifier is an 32 bit value. */
220typedef uint32_t VRDPUSBDEVID;
221
222/** Status codes. */
223#define VRDP_USB_STATUS_SUCCESS ((VRDPUSBSTATUS)0)
224#define VRDP_USB_STATUS_ACCESS_DENIED ((VRDPUSBSTATUS)1)
225#define VRDP_USB_STATUS_DEVICE_REMOVED ((VRDPUSBSTATUS)2)
226
227/*
228 * Data structures to use with VRDPSendUSBRequest.
229 * The *RET* structures always represent the layout of VRDP data.
230 * The *PARM* structures normally the same as VRDP layout.
231 * However the VRDP_USB_REQ_QUEUE_URB_PARM has a pointer to
232 * URB data in place where actual data will be in VRDP layout.
233 *
234 * Since replies (*RET*) are asynchronous, the 'success'
235 * replies are not required for operations which return
236 * only the status code (VRDPUSBREQRETHDR only):
237 * VRDP_USB_REQ_OPEN
238 * VRDP_USB_REQ_RESET
239 * VRDP_USB_REQ_SET_CONFIG
240 * VRDP_USB_REQ_CLAIM_INTERFACE
241 * VRDP_USB_REQ_RELEASE_INTERFACE
242 * VRDP_USB_REQ_INTERFACE_SETTING
243 * VRDP_USB_REQ_CLEAR_HALTED_EP
244 *
245 */
246
247/* VRDP layout has no aligments. */
248#pragma pack(1)
249
250/* Common header for all VRDP USB packets. After the reply hdr follows *PARM* or *RET* data. */
251typedef struct _VRDPUSBPKTHDR
252{
253 /* Total length of the reply NOT including the 'length' field. */
254 uint32_t length;
255 /* The operation code for which the reply was sent by the client. */
256 uint8_t code;
257} VRDPUSBPKTHDR;
258
259/* Common header for all return structures. */
260typedef struct _VRDPUSBREQRETHDR
261{
262 /* Device status. */
263 VRDPUSBSTATUS status;
264 /* Device id. */
265 VRDPUSBDEVID id;
266} VRDPUSBREQRETHDR;
267
268
269/* VRDP_USB_REQ_OPEN
270 */
271typedef struct _VRDP_USB_REQ_OPEN_PARM
272{
273 uint8_t code;
274 VRDPUSBDEVID id;
275} VRDP_USB_REQ_OPEN_PARM;
276
277typedef struct _VRDP_USB_REQ_OPEN_RET
278{
279 VRDPUSBREQRETHDR hdr;
280} VRDP_USB_REQ_OPEN_RET;
281
282
283/* VRDP_USB_REQ_CLOSE
284 */
285typedef struct _VRDP_USB_REQ_CLOSE_PARM
286{
287 uint8_t code;
288 VRDPUSBDEVID id;
289} VRDP_USB_REQ_CLOSE_PARM;
290
291/* The close request has no returned data. */
292
293
294/* VRDP_USB_REQ_RESET
295 */
296typedef struct _VRDP_USB_REQ_RESET_PARM
297{
298 uint8_t code;
299 VRDPUSBDEVID id;
300} VRDP_USB_REQ_RESET_PARM;
301
302typedef struct _VRDP_USB_REQ_RESET_RET
303{
304 VRDPUSBREQRETHDR hdr;
305} VRDP_USB_REQ_RESET_RET;
306
307
308/* VRDP_USB_REQ_SET_CONFIG
309 */
310typedef struct _VRDP_USB_REQ_SET_CONFIG_PARM
311{
312 uint8_t code;
313 VRDPUSBDEVID id;
314 uint8_t configuration;
315} VRDP_USB_REQ_SET_CONFIG_PARM;
316
317typedef struct _VRDP_USB_REQ_SET_CONFIG_RET
318{
319 VRDPUSBREQRETHDR hdr;
320} VRDP_USB_REQ_SET_CONFIG_RET;
321
322
323/* VRDP_USB_REQ_CLAIM_INTERFACE
324 */
325typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_PARM
326{
327 uint8_t code;
328 VRDPUSBDEVID id;
329 uint8_t iface;
330} VRDP_USB_REQ_CLAIM_INTERFACE_PARM;
331
332typedef struct _VRDP_USB_REQ_CLAIM_INTERFACE_RET
333{
334 VRDPUSBREQRETHDR hdr;
335} VRDP_USB_REQ_CLAIM_INTERFACE_RET;
336
337
338/* VRDP_USB_REQ_RELEASE_INTERFACE
339 */
340typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_PARM
341{
342 uint8_t code;
343 VRDPUSBDEVID id;
344 uint8_t iface;
345} VRDP_USB_REQ_RELEASE_INTERFACE_PARM;
346
347typedef struct _VRDP_USB_REQ_RELEASE_INTERFACE_RET
348{
349 VRDPUSBREQRETHDR hdr;
350} VRDP_USB_REQ_RELEASE_INTERFACE_RET;
351
352
353/* VRDP_USB_REQ_INTERFACE_SETTING
354 */
355typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_PARM
356{
357 uint8_t code;
358 VRDPUSBDEVID id;
359 uint8_t iface;
360 uint8_t setting;
361} VRDP_USB_REQ_INTERFACE_SETTING_PARM;
362
363typedef struct _VRDP_USB_REQ_INTERFACE_SETTING_RET
364{
365 VRDPUSBREQRETHDR hdr;
366} VRDP_USB_REQ_INTERFACE_SETTING_RET;
367
368
369/* VRDP_USB_REQ_QUEUE_URB
370 */
371
372#define VRDP_USB_TRANSFER_TYPE_CTRL (0)
373#define VRDP_USB_TRANSFER_TYPE_ISOC (1)
374#define VRDP_USB_TRANSFER_TYPE_BULK (2)
375#define VRDP_USB_TRANSFER_TYPE_INTR (3)
376#define VRDP_USB_TRANSFER_TYPE_MSG (4)
377
378#define VRDP_USB_DIRECTION_SETUP (0)
379#define VRDP_USB_DIRECTION_IN (1)
380#define VRDP_USB_DIRECTION_OUT (2)
381
382typedef struct _VRDP_USB_REQ_QUEUE_URB_PARM
383{
384 uint8_t code;
385 VRDPUSBDEVID id;
386 uint32_t handle; /* Distinguishes that particular URB. Later used in CancelURB and returned by ReapURB */
387 uint8_t type;
388 uint8_t ep;
389 uint8_t direction;
390 uint32_t urblen; /* Length of the URB. */
391 uint32_t datalen; /* Length of the data. */
392 void *data; /* In RDP layout the data follow. */
393} VRDP_USB_REQ_QUEUE_URB_PARM;
394
395/* The queue URB has no explicit return. The reap URB reply will be
396 * eventually the indirect result.
397 */
398
399
400/* VRDP_USB_REQ_REAP_URB
401 * Notificationg from server to client that server expects an URB
402 * from any device.
403 * Only sent if negotiated URB return method is polling.
404 * Normally, the client will send URBs back as soon as they are ready.
405 */
406typedef struct _VRDP_USB_REQ_REAP_URB_PARM
407{
408 uint8_t code;
409} VRDP_USB_REQ_REAP_URB_PARM;
410
411
412#define VRDP_USB_XFER_OK (0)
413#define VRDP_USB_XFER_STALL (1)
414#define VRDP_USB_XFER_DNR (2)
415#define VRDP_USB_XFER_CRC (3)
416
417#define VRDP_USB_REAP_FLAG_CONTINUED (0x0)
418#define VRDP_USB_REAP_FLAG_LAST (0x1)
419
420#define VRDP_USB_REAP_VALID_FLAGS (VRDP_USB_REAP_FLAG_LAST)
421
422typedef struct _VRDPUSBREQREAPURBBODY
423{
424 VRDPUSBDEVID id; /* From which device the URB arrives. */
425 uint8_t flags; /* VRDP_USB_REAP_FLAG_* */
426 uint8_t error; /* VRDP_USB_XFER_* */
427 uint32_t handle; /* Handle of returned URB. Not 0. */
428 uint32_t len; /* Length of data actually transferred. */
429 /* Data follow. */
430} VRDPUSBREQREAPURBBODY;
431
432typedef struct _VRDP_USB_REQ_REAP_URB_RET
433{
434 /* The REAP URB has no header, only completed URBs are returned. */
435 VRDPUSBREQREAPURBBODY body;
436 /* Another body may follow, depending on flags. */
437} VRDP_USB_REQ_REAP_URB_RET;
438
439
440/* VRDP_USB_REQ_CLEAR_HALTED_EP
441 */
442typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_PARM
443{
444 uint8_t code;
445 VRDPUSBDEVID id;
446 uint8_t ep;
447} VRDP_USB_REQ_CLEAR_HALTED_EP_PARM;
448
449typedef struct _VRDP_USB_REQ_CLEAR_HALTED_EP_RET
450{
451 VRDPUSBREQRETHDR hdr;
452} VRDP_USB_REQ_CLEAR_HALTED_EP_RET;
453
454
455/* VRDP_USB_REQ_CANCEL_URB
456 */
457typedef struct _VRDP_USB_REQ_CANCEL_URB_PARM
458{
459 uint8_t code;
460 VRDPUSBDEVID id;
461 uint32_t handle;
462} VRDP_USB_REQ_CANCEL_URB_PARM;
463
464/* The cancel URB request has no return. */
465
466
467/* VRDP_USB_REQ_DEVICE_LIST
468 *
469 * Server polls USB devices on client by sending this request
470 * periodically. Client sends back a list of all devices
471 * connected to it. Each device is assigned with an identifier,
472 * that is used to distinguish the particular device.
473 */
474typedef struct _VRDP_USB_REQ_DEVICE_LIST_PARM
475{
476 uint8_t code;
477} VRDP_USB_REQ_DEVICE_LIST_PARM;
478
479/* Data is a list of the following variable length structures. */
480typedef struct _VRDPUSBDEVICEDESC
481{
482 /* Offset of the next structure. 0 if last. */
483 uint16_t oNext;
484
485 /* Identifier of the device assigned by client. */
486 VRDPUSBDEVID id;
487
488 /** USB version number. */
489 uint16_t bcdUSB;
490 /** Device class. */
491 uint8_t bDeviceClass;
492 /** Device subclass. */
493 uint8_t bDeviceSubClass;
494 /** Device protocol */
495 uint8_t bDeviceProtocol;
496 /** Vendor ID. */
497 uint16_t idVendor;
498 /** Product ID. */
499 uint16_t idProduct;
500 /** Revision, integer part. */
501 uint16_t bcdRev;
502 /** Manufacturer string. */
503 uint16_t oManufacturer;
504 /** Product string. */
505 uint16_t oProduct;
506 /** Serial number string. */
507 uint16_t oSerialNumber;
508 /** Physical USB port the device is connected to. */
509 uint16_t idPort;
510
511} VRDPUSBDEVICEDESC;
512
513typedef struct _VRDP_USB_REQ_DEVICE_LIST_RET
514{
515 VRDPUSBDEVICEDESC body;
516 /* Other devices may follow.
517 * The list ends with (uint16_t)0,
518 * which means that an empty list consists of 2 zero bytes.
519 */
520} VRDP_USB_REQ_DEVICE_LIST_RET;
521
522typedef struct _VRDPUSBREQNEGOTIATEPARM
523{
524 uint8_t code;
525
526 /* Remote USB Protocol version. */
527 uint32_t version;
528
529} VRDPUSBREQNEGOTIATEPARM;
530
531#define VRDP_USB_CAPS_FLAG_ASYNC (0x0)
532#define VRDP_USB_CAPS_FLAG_POLL (0x1)
533
534#define VRDP_USB_CAPS_VALID_FLAGS (VRDP_USB_CAPS_FLAG_POLL)
535
536typedef struct _VRDPUSBREQNEGOTIATERET
537{
538 uint8_t flags;
539} VRDPUSBREQNEGOTIATERET;
540
541#pragma pack()
542
543
544#define VRDP_CLIPBOARD_FORMAT_NULL (0x0)
545#define VRDP_CLIPBOARD_FORMAT_UNICODE_TEXT (0x1)
546#define VRDP_CLIPBOARD_FORMAT_BITMAP (0x2)
547#define VRDP_CLIPBOARD_FORMAT_HTML (0x4)
548
549#define VRDP_CLIPBOARD_FUNCTION_FORMAT_ANNOUNCE (0)
550#define VRDP_CLIPBOARD_FUNCTION_DATA_READ (1)
551#define VRDP_CLIPBOARD_FUNCTION_DATA_WRITE (2)
552
553/**
554 * Called by the host when (VRDP_CLIPBOARD_FUNCTION_*):
555 * - (0) guest announces available clipboard formats;
556 * - (1) guest requests clipboard data;
557 * - (2) guest responds to the client's request for clipboard data.
558 *
559 * @param hserver The VRDP server handle.
560 * @param u32Function The cause of the call.
561 * @param u32Format Bitmask of announced formats or the format of data.
562 * @param pvData Points to: (1) buffer to be filled with clients data;
563 * (2) data from the host.
564 * @param cbData Size of 'pvData' buffer in bytes.
565 * @param pcbActualRead Size of the copied data in bytes.
566 *
567 */
568VRDPR3DECL(void) VRDPClipboard (HVRDPSERVER hserver,
569 uint32_t u32Function,
570 uint32_t u32Format,
571 void *pvData,
572 uint32_t cbData,
573 uint32_t *pcbActualRead);
574
575#ifdef VRDP_MC
576/**
577 * Sends a USB request.
578 *
579 * @param hserver Handle of VRDP server instance.
580 * @param u32ClientId An identifier that allows the server to find the corresponding client.
581 * The identifier is always passed by the server as a parameter
582 * of the FNVRDPUSBCALLBACK. Note that the value is the same as
583 * in the VRDPSERVERCALLBACK functions.
584 * @param pvParm Function specific parameters buffer.
585 * @param cbParm Size of the buffer.
586 */
587VRDPR3DECL(void) VRDPSendUSBRequest (HVRDPSERVER hserver,
588 uint32_t u32ClientId,
589 void *pvParm,
590 uint32_t cbRarm);
591
592
593/**
594 * Called by the server when a reply is received from a client.
595 *
596 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptUSB.
597 * @param u32ClientId Identifies the client that sent the reply.
598 * @param u8Code The operation code VRDP_USB_REQ_*.
599 * @param pvRet Points to data received from the client.
600 * @param cbRet Size of the data in bytes.
601 *
602 * @return VBox error code.
603 */
604typedef DECLCALLBACK(int) FNVRDPUSBCALLBACK (void *pvCallback,
605 uint32_t u32ClientId,
606 uint8_t u8Code,
607 const void *pvRet,
608 uint32_t cbRet);
609
610typedef FNVRDPUSBCALLBACK *PFNVRDPUSBCALLBACK;
611
612/**
613 * Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
614 * - (0) client announces available clipboard formats;
615 * - (1) client requests clipboard data.
616 *
617 * @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptClipboard.
618 * @param u32ClientId Identifies the RDP client that sent the reply.
619 * @param u32Function The cause of the callback.
620 * @param u32Format Bitmask of reported formats or the format of received data.
621 * @param pvData Reserved.
622 * @param cbData Reserved.
623 *
624 * @return VBox error code.
625 */
626typedef DECLCALLBACK(int) FNVRDPCLIPBOARDCALLBACK (void *pvCallback,
627 uint32_t u32ClientId,
628 uint32_t u32Function,
629 uint32_t u32Format,
630 const void *pvData,
631 uint32_t cbData);
632
633typedef FNVRDPCLIPBOARDCALLBACK *PFNVRDPCLIPBOARDCALLBACK;
634
635#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
636#define VRDP_CLIENT_INTERCEPT_USB (0x2)
637#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
638
639typedef struct _VRDPSERVERCALLBACK
640{
641 /* A client is logging in.
642 *
643 * @param pvUser The callback specific pointer.
644 * @param u32ClientId An unique client identifier generated by the server.
645 * @param pszUser The username.
646 * @param pszPassword The password.
647 * @param pszDomain The domain.
648 *
649 * @return VBox error code.
650 */
651 DECLCALLBACKMEMBER(int, pfnClientLogon) (void *pvUser,
652 uint32_t u32ClientId,
653 const char *pszUser,
654 const char *pszPassword,
655 const char *pszDomain);
656 /* The client has connected.
657 *
658 * @param pvUser The callback specific pointer.
659 * @param u32ClientId An unique client identifier generated by the server.
660 */
661 DECLCALLBACKMEMBER(void, pfnClientConnect) (void *pvUser,
662 uint32_t u32ClientId);
663 /* The client has been disconnected.
664 *
665 * @param pvUser The callback specific pointer.
666 * @param u32ClientId An unique client identifier generated by the server.
667 * @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
668 */
669 DECLCALLBACKMEMBER(void, pfnClientDisconnect) (void *pvUser,
670 uint32_t u32ClientId,
671 uint32_t fu32Intercepted);
672 /* The client supports audio channel.
673 */
674 DECLCALLBACKMEMBER(void, pfnInterceptAudio) (void *pvUser,
675 uint32_t u32ClientId);
676 /* The client supports USB channel.
677 */
678 DECLCALLBACKMEMBER(void, pfnInterceptUSB) (void *pvUser,
679 uint32_t u32ClientId,
680 PFNVRDPUSBCALLBACK *ppfn,
681 void **ppv);
682 /* The client supports clipboard channel.
683 */
684 DECLCALLBACKMEMBER(void, pfnInterceptClipboard) (void *pvUser,
685 uint32_t u32ClientId,
686 PFNVRDPCLIPBOARDCALLBACK *ppfn,
687 void **ppv);
688} VRDPSERVERCALLBACK;
689#else
690/**
691 * Sends a USB request.
692 *
693 * @param hserver Handle of VRDP server instance.
694 * @param pvParm Function specific parameters buffer.
695 * @param cbParm Size of the buffer.
696 * @param pvRet Function specific returned data buffer.
697 * @param cbRet Size of the buffer.
698 * @param prc VBox return code.
699 */
700VRDPR3DECL(void) VRDPSendUSBRequest (HVRDPSERVER hserver, void *pvParm, uint32_t cbRarm);
701
702
703typedef DECLCALLBACK(int) FNVRDPUSBCALLBACK (void *pv, uint8_t code, void *pvRet, uint32_t cbRet);
704typedef FNVRDPUSBCALLBACK *PFNVRDPUSBCALLBACK;
705
706typedef DECLCALLBACK(int) FNVRDPCLIPBOARDCALLBACK (void *pv, uint32_t u32Format, void *pvData, uint32_t cbData);
707typedef FNVRDPCLIPBOARDCALLBACK *PFNVRDPCLIPBOARDCALLBACK;
708
709typedef struct _VRDPSERVERCALLBACK
710{
711 DECLCALLBACKMEMBER(int, pfnClientLogon) (void *pvUser, const char *pszUser, const char *pszPassword, const char *pszDomain);
712 DECLCALLBACKMEMBER(void, pfnClientConnect) (void *pvUser, uint32_t fu32SupportedOrders);
713 DECLCALLBACKMEMBER(void, pfnClientDisconnect) (void *pvUser);
714 DECLCALLBACKMEMBER(void, pfnInterceptAudio) (void *pvUser, bool fKeepHostAudio);
715 DECLCALLBACKMEMBER(void, pfnInterceptUSB) (void *pvUser, PFNVRDPUSBCALLBACK *ppfn, void **ppv);
716 DECLCALLBACKMEMBER(void, pfnInterceptClipboard) (void *pvUser, PFNVRDPCLIPBOARDCALLBACK *ppfn, void **ppv);
717} VRDPSERVERCALLBACK;
718#endif /* VRDP_MC */
719
720/**
721 * Set a callback pointers table that will be called by the server in certain situations.
722 *
723 * @param hserver Handle of VRDP server instance.
724 * @param pCallback Pointer to VRDPSERVERCALLBACK structure with function pointers.
725 * @param pvUser An pointer to be passed to the callback functions.
726 */
727VRDPR3DECL(void) VRDPSetCallback (HVRDPSERVER hserver, VRDPSERVERCALLBACK *pCallback, void *pvUser);
728
729/** Indexes of information values. */
730
731/** Whether a client is connected at the moment.
732 * uint32_t
733 */
734#define VRDP_QI_ACTIVE (0)
735
736/** How many times a client connected up to current moment.
737 * uint32_t
738 */
739#define VRDP_QI_NUMBER_OF_CLIENTS (1)
740
741/** When last connection was established.
742 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
743 */
744#define VRDP_QI_BEGIN_TIME (2)
745
746/** When last connection was terminated or current time if connection still active.
747 * int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
748 */
749#define VRDP_QI_END_TIME (3)
750
751/** How many bytes were sent in last (current) connection.
752 * uint64_t
753 */
754#define VRDP_QI_BYTES_SENT (4)
755
756/** How many bytes were sent in all connections.
757 * uint64_t
758 */
759#define VRDP_QI_BYTES_SENT_TOTAL (5)
760
761/** How many bytes were received in last (current) connection.
762 * uint64_t
763 */
764#define VRDP_QI_BYTES_RECEIVED (6)
765
766/** How many bytes were received in all connections.
767 * uint64_t
768 */
769#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
770
771/** Login user name supplied by the client.
772 * UTF8 nul terminated string.
773 */
774#define VRDP_QI_USER (8)
775
776/** Login domain supplied by the client.
777 * UTF8 nul terminated string.
778 */
779#define VRDP_QI_DOMAIN (9)
780
781/** The client name supplied by the client.
782 * UTF8 nul terminated string.
783 */
784#define VRDP_QI_CLIENT_NAME (10)
785
786/** IP address of the client.
787 * UTF8 nul terminated string.
788 */
789#define VRDP_QI_CLIENT_IP (11)
790
791/** The client software version number.
792 * uint32_t.
793 */
794#define VRDP_QI_CLIENT_VERSION (12)
795
796/** Public key exchange method used when connection was established.
797 * Values: 0 - RDP4 public key exchange scheme.
798 * 1 - X509 sertificates were sent to client.
799 * uint32_t.
800 */
801#define VRDP_QI_ENCRYPTION_STYLE (13)
802
803/**
804 * Query various information from the VRDP server.
805 *
806 * @param index VRDP_QI_* identifier of information to be returned.
807 * @param pvBuffer Address of memory buffer to which the information must be written.
808 * @param cbBuffer Size of the memory buffer in bytes.
809 * @param pcbOut Size in bytes of returned information value.
810 *
811 * @remark The caller must check the *pcbOut. 0 there means no information was returned.
812 * A value greater than cbBuffer means that information is too big to fit in the
813 * buffer, in that case no information was placed to the buffer.
814 */
815VRDPR3DECL(void) VRDPQueryInfo (HVRDPSERVER hserver, uint32_t index, void *pvBuffer, uint32_t cbBuffer, uint32_t *pcbOut);
816
817__END_DECLS
818
819/** @} */
820
821#endif /* __VBox_vrdpapi_h__ */
822
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