vrdpapi.h@ 3278

Last change on this file since 3278 was 3278, checked in by vboxsync, 17 years ago
Removed some obsolete VRDP code.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.0 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
55	class VRDPServer;
56	typedef class VRDPServer *HVRDPSERVER;
57
58	#else
59
60	struct VRDPServer;
61	typedef 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	*/
74	VRDPR3DECL(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	*/
88	VRDPR3DECL(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	*/
95	VRDPR3DECL(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	*/
107	VRDPR3DECL(void) VRDPSendUpdateBitmap (HVRDPSERVER hserver, unsigned uScreenId, 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	*/
115	VRDPR3DECL(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	*/
124	VRDPR3DECL(void) VRDPSendUpdate (HVRDPSERVER hserver, unsigned uScreenId, void *pvUpdate, uint32_t cbUpdate);
125
126	/** @todo comment the structure. */
127	typedef 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
138	typedef 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	*/
146	VRDPR3DECL(void) VRDPSendColorPointer (HVRDPSERVER hserver, PVRDPCOLORPOINTER pdata);
147
148	/**
149	* Hide mouse pointer.
150	*
151	* @param hserver Handle of VRDP server instance.
152	*/
153	VRDPR3DECL(void) VRDPSendHidePointer (HVRDPSERVER hserver);
154
155	/** Audio format information packed in a 32 bit value. */
156	typedef 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	*/
180	VRDPR3DECL(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	*/
189	VRDPR3DECL(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. */
217	typedef uint8_t VRDPUSBSTATUS;
218
219	/** USB device identifier is an 32 bit value. */
220	typedef 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. */
251	typedef 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. */
260	typedef 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	*/
271	typedef struct _VRDP_USB_REQ_OPEN_PARM
272	{
273	uint8_t code;
274	VRDPUSBDEVID id;
275	} VRDP_USB_REQ_OPEN_PARM;
276
277	typedef struct _VRDP_USB_REQ_OPEN_RET
278	{
279	VRDPUSBREQRETHDR hdr;
280	} VRDP_USB_REQ_OPEN_RET;
281
282
283	/* VRDP_USB_REQ_CLOSE
284	*/
285	typedef 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	*/
296	typedef struct _VRDP_USB_REQ_RESET_PARM
297	{
298	uint8_t code;
299	VRDPUSBDEVID id;
300	} VRDP_USB_REQ_RESET_PARM;
301
302	typedef 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	*/
310	typedef 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
317	typedef 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	*/
325	typedef 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
332	typedef 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	*/
340	typedef 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
347	typedef 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	*/
355	typedef 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
363	typedef 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
382	typedef 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	*/
406	typedef 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
422	typedef 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
432	typedef 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	*/
442	typedef 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
449	typedef 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	*/
457	typedef 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	*/
474	typedef 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. */
480	typedef 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
513	typedef 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
522	typedef 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
536	typedef 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	*/
568	VRDPR3DECL(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	/**
576	* Sends a USB request.
577	*
578	* @param hserver Handle of VRDP server instance.
579	* @param u32ClientId An identifier that allows the server to find the corresponding client.
580	* The identifier is always passed by the server as a parameter
581	* of the FNVRDPUSBCALLBACK. Note that the value is the same as
582	* in the VRDPSERVERCALLBACK functions.
583	* @param pvParm Function specific parameters buffer.
584	* @param cbParm Size of the buffer.
585	*/
586	VRDPR3DECL(void) VRDPSendUSBRequest (HVRDPSERVER hserver,
587	uint32_t u32ClientId,
588	void *pvParm,
589	uint32_t cbRarm);
590
591
592	/**
593	* Called by the server when a reply is received from a client.
594	*
595	* @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptUSB.
596	* @param u32ClientId Identifies the client that sent the reply.
597	* @param u8Code The operation code VRDP_USB_REQ_*.
598	* @param pvRet Points to data received from the client.
599	* @param cbRet Size of the data in bytes.
600	*
601	* @return VBox error code.
602	*/
603	typedef DECLCALLBACK(int) FNVRDPUSBCALLBACK (void *pvCallback,
604	uint32_t u32ClientId,
605	uint8_t u8Code,
606	const void *pvRet,
607	uint32_t cbRet);
608
609	typedef FNVRDPUSBCALLBACK *PFNVRDPUSBCALLBACK;
610
611	/**
612	* Called by the server when (VRDP_CLIPBOARD_FUNCTION_*):
613	* - (0) client announces available clipboard formats;
614	* - (1) client requests clipboard data.
615	*
616	* @param pvCallback Callback specific value returned by VRDPSERVERCALLBACK::pfnInterceptClipboard.
617	* @param u32ClientId Identifies the RDP client that sent the reply.
618	* @param u32Function The cause of the callback.
619	* @param u32Format Bitmask of reported formats or the format of received data.
620	* @param pvData Reserved.
621	* @param cbData Reserved.
622	*
623	* @return VBox error code.
624	*/
625	typedef DECLCALLBACK(int) FNVRDPCLIPBOARDCALLBACK (void *pvCallback,
626	uint32_t u32ClientId,
627	uint32_t u32Function,
628	uint32_t u32Format,
629	const void *pvData,
630	uint32_t cbData);
631
632	typedef FNVRDPCLIPBOARDCALLBACK *PFNVRDPCLIPBOARDCALLBACK;
633
634	#define VRDP_CLIENT_INTERCEPT_AUDIO (0x1)
635	#define VRDP_CLIENT_INTERCEPT_USB (0x2)
636	#define VRDP_CLIENT_INTERCEPT_CLIPBOARD (0x4)
637
638	typedef struct _VRDPSERVERCALLBACK
639	{
640	/* A client is logging in.
641	*
642	* @param pvUser The callback specific pointer.
643	* @param u32ClientId An unique client identifier generated by the server.
644	* @param pszUser The username.
645	* @param pszPassword The password.
646	* @param pszDomain The domain.
647	*
648	* @return VBox error code.
649	*/
650	DECLCALLBACKMEMBER(int, pfnClientLogon) (void *pvUser,
651	uint32_t u32ClientId,
652	const char *pszUser,
653	const char *pszPassword,
654	const char *pszDomain);
655	/* The client has connected.
656	*
657	* @param pvUser The callback specific pointer.
658	* @param u32ClientId An unique client identifier generated by the server.
659	*/
660	DECLCALLBACKMEMBER(void, pfnClientConnect) (void *pvUser,
661	uint32_t u32ClientId);
662	/* The client has been disconnected.
663	*
664	* @param pvUser The callback specific pointer.
665	* @param u32ClientId An unique client identifier generated by the server.
666	* @param fu32Intercepted What was intercepted by the client (VRDP_CLIENT_INTERCEPT_*).
667	*/
668	DECLCALLBACKMEMBER(void, pfnClientDisconnect) (void *pvUser,
669	uint32_t u32ClientId,
670	uint32_t fu32Intercepted);
671	/* The client supports audio channel.
672	*/
673	DECLCALLBACKMEMBER(void, pfnInterceptAudio) (void *pvUser,
674	uint32_t u32ClientId);
675	/* The client supports USB channel.
676	*/
677	DECLCALLBACKMEMBER(void, pfnInterceptUSB) (void *pvUser,
678	uint32_t u32ClientId,
679	PFNVRDPUSBCALLBACK *ppfn,
680	void **ppv);
681	/* The client supports clipboard channel.
682	*/
683	DECLCALLBACKMEMBER(void, pfnInterceptClipboard) (void *pvUser,
684	uint32_t u32ClientId,
685	PFNVRDPCLIPBOARDCALLBACK *ppfn,
686	void **ppv);
687	} VRDPSERVERCALLBACK;
688
689	/**
690	* Set a callback pointers table that will be called by the server in certain situations.
691	*
692	* @param hserver Handle of VRDP server instance.
693	* @param pCallback Pointer to VRDPSERVERCALLBACK structure with function pointers.
694	* @param pvUser An pointer to be passed to the callback functions.
695	*/
696	VRDPR3DECL(void) VRDPSetCallback (HVRDPSERVER hserver, VRDPSERVERCALLBACK pCallback, void pvUser);
697
698	/** Indexes of information values. */
699
700	/** Whether a client is connected at the moment.
701	* uint32_t
702	*/
703	#define VRDP_QI_ACTIVE (0)
704
705	/** How many times a client connected up to current moment.
706	* uint32_t
707	*/
708	#define VRDP_QI_NUMBER_OF_CLIENTS (1)
709
710	/** When last connection was established.
711	* int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
712	*/
713	#define VRDP_QI_BEGIN_TIME (2)
714
715	/** When last connection was terminated or current time if connection still active.
716	* int64_t time in milliseconds since 1970-01-01 00:00:00 UTC
717	*/
718	#define VRDP_QI_END_TIME (3)
719
720	/** How many bytes were sent in last (current) connection.
721	* uint64_t
722	*/
723	#define VRDP_QI_BYTES_SENT (4)
724
725	/** How many bytes were sent in all connections.
726	* uint64_t
727	*/
728	#define VRDP_QI_BYTES_SENT_TOTAL (5)
729
730	/** How many bytes were received in last (current) connection.
731	* uint64_t
732	*/
733	#define VRDP_QI_BYTES_RECEIVED (6)
734
735	/** How many bytes were received in all connections.
736	* uint64_t
737	*/
738	#define VRDP_QI_BYTES_RECEIVED_TOTAL (7)
739
740	/** Login user name supplied by the client.
741	* UTF8 nul terminated string.
742	*/
743	#define VRDP_QI_USER (8)
744
745	/** Login domain supplied by the client.
746	* UTF8 nul terminated string.
747	*/
748	#define VRDP_QI_DOMAIN (9)
749
750	/** The client name supplied by the client.
751	* UTF8 nul terminated string.
752	*/
753	#define VRDP_QI_CLIENT_NAME (10)
754
755	/** IP address of the client.
756	* UTF8 nul terminated string.
757	*/
758	#define VRDP_QI_CLIENT_IP (11)
759
760	/** The client software version number.
761	* uint32_t.
762	*/
763	#define VRDP_QI_CLIENT_VERSION (12)
764
765	/** Public key exchange method used when connection was established.
766	* Values: 0 - RDP4 public key exchange scheme.
767	* 1 - X509 sertificates were sent to client.
768	* uint32_t.
769	*/
770	#define VRDP_QI_ENCRYPTION_STYLE (13)
771
772	/**
773	* Query various information from the VRDP server.
774	*
775	* @param index VRDP_QI_* identifier of information to be returned.
776	* @param pvBuffer Address of memory buffer to which the information must be written.
777	* @param cbBuffer Size of the memory buffer in bytes.
778	* @param pcbOut Size in bytes of returned information value.
779	*
780	* @remark The caller must check the *pcbOut. 0 there means no information was returned.
781	* A value greater than cbBuffer means that information is too big to fit in the
782	* buffer, in that case no information was placed to the buffer.
783	*/
784	VRDPR3DECL(void) VRDPQueryInfo (HVRDPSERVER hserver, uint32_t index, void pvBuffer, uint32_t cbBuffer, uint32_t pcbOut);
785
786	__END_DECLS
787
788	/** @} */
789
790	#endif /* __VBox_vrdpapi_h__ */
791

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: