VBoxGuestLib.h@ 98472

Last change on this file since 98472 was 98472, checked in by vboxsync, 22 months ago

Guest Library: Introduce VbglR3DaemonizeEx and VbglR3PidfileWait, bugref:10359.

VbglR3DaemonizeEx is a wrapper function for VbglR3Daemonize. In addition to the
original version it sets pidfile lock for the parent process and notifies caller
when child process terminates with exit status VBGLR3EXITCODERELOAD (currently
equal to 2) indicating that parent process should release its reference to vboxguest
kernel module and wait for SIGUSR2 in order to restart itself. This is a part of
the procedure to install and reload/restart Guest Additions kernel modules and
user services without requiring guest reboot. It is currently only has effect
on X11 guests.

VbglR3PidfileWait is a wrapper function for VbglR3Pidfile. In addition to the
original version, it waits specified amount of time until pidfile lock become
available or fails on timeout.

Property svn:eol-style set to native
Property svn:keywords set to Author Date Id Revision

File size: 62.2 KB

Line
1	/** @file
2	* VBoxGuestLib - VirtualBox Guest Additions Library.
3	*/
4
5	/*
6	* Copyright (C) 2006-2023 Oracle and/or its affiliates.
7	*
8	* Permission is hereby granted, free of charge, to any person
9	* obtaining a copy of this software and associated documentation
10	* files (the "Software"), to deal in the Software without
11	* restriction, including without limitation the rights to use,
12	* copy, modify, merge, publish, distribute, sublicense, and/or sell
13	* copies of the Software, and to permit persons to whom the
14	* Software is furnished to do so, subject to the following
15	* conditions:
16	*
17	* The above copyright notice and this permission notice shall be
18	* included in all copies or substantial portions of the Software.
19	*
20	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21	* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
22	* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
23	* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
24	* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
25	* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26	* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
27	* OTHER DEALINGS IN THE SOFTWARE.
28	*/
29
30	#ifndef VBOX_INCLUDED_VBoxGuestLib_h
31	#define VBOX_INCLUDED_VBoxGuestLib_h
32	#ifndef RT_WITHOUT_PRAGMA_ONCE
33	# pragma once
34	#endif
35
36	#include <VBox/types.h>
37	#include <VBox/VMMDev.h>
38	#include <VBox/VBoxGuestCoreTypes.h>
39	# ifdef VBOX_WITH_DRAG_AND_DROP
40	# include <VBox/GuestHost/DragAndDrop.h>
41	# include <VBox/GuestHost/DragAndDropDefs.h>
42	# endif
43	# ifdef VBOX_WITH_SHARED_CLIPBOARD
44	# include <VBox/GuestHost/SharedClipboard.h>
45	# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
46	# include <VBox/GuestHost/SharedClipboard-transfers.h>
47	# endif
48	# endif /* VBOX_WITH_SHARED_CLIPBOARD */
49
50	/** @defgroup grp_vboxguest_lib VirtualBox Guest Additions Library
51	* @ingroup grp_vboxguest
52	* @{
53	*/
54
55	/** @page pg_guest_lib VirtualBox Guest Library
56	*
57	* This is a library for abstracting the additions driver interface. There are
58	* multiple versions of the library depending on the context. The main
59	* distinction is between kernel and user mode where the interfaces are very
60	* different.
61	*
62	*
63	* @section sec_guest_lib_ring0 Ring-0
64	*
65	* In ring-0 there are two version:
66	* - VBOX_LIB_VBGL_R0_BASE / VBoxGuestR0LibBase for the VBoxGuest main driver,
67	* who is responsible for managing the VMMDev virtual hardware.
68	* - VBOX_LIB_VBGL_R0 / VBoxGuestR0Lib for other (client) guest drivers.
69	*
70	*
71	* The library source code and the header have a define VBGL_VBOXGUEST, which is
72	* defined for VBoxGuest and undefined for other drivers. Drivers must choose
73	* right library in their makefiles and set VBGL_VBOXGUEST accordingly.
74	*
75	* The libraries consists of:
76	* - common code to be used by both VBoxGuest and other drivers;
77	* - VBoxGuest specific code;
78	* - code for other drivers which communicate with VBoxGuest via an IOCTL.
79	*
80	*
81	* @section sec_guest_lib_ring3 Ring-3
82	*
83	* There are more variants of the library here:
84	* - VBOX_LIB_VBGL_R3 / VBoxGuestR3Lib for programs.
85	* - VBOX_LIB_VBGL_R3_XFREE86 / VBoxGuestR3LibXFree86 for old style XFree
86	* drivers which uses special loader and or symbol resolving strategy.
87	* - VBOX_LIB_VBGL_R3_SHARED / VBoxGuestR3LibShared for shared objects / DLLs /
88	* Dylibs.
89	*
90	*/
91
92	RT_C_DECLS_BEGIN
93
94	/** HGCM client ID.
95	* @todo Promote to VBox/types.h */
96	typedef uint32_t HGCMCLIENTID;
97
98
99	/** @defgroup grp_vboxguest_lib_r0 Ring-0 interface.
100	* @{
101	*/
102	#ifdef IN_RING0
103	/** @def DECLR0VBGL
104	* Declare a VBGL ring-0 API with the right calling convention and visibilitiy.
105	* @param type Return type. */
106	# ifdef RT_OS_DARWIN /** @todo probably apply to all, but don't want a forest fire on our hands right now. */
107	# define DECLR0VBGL(type) DECLHIDDEN(DECL_NOTHROW(type)) VBOXCALL
108	# else
109	# define DECLR0VBGL(type) DECL_NOTHROW(type) VBOXCALL
110	# endif
111	# define DECLVBGL(type) DECLR0VBGL(type)
112
113
114	/**
115	* The library initialization function to be used by the main VBoxGuest driver.
116	*
117	* @return VBox status code.
118	*/
119	DECLR0VBGL(int) VbglR0InitPrimary(RTIOPORT portVMMDev, VMMDevMemory pVMMDevMemory, uint32_t pfFeatures);
120
121	/**
122	* The library termination function to be used by the main VBoxGuest driver.
123	*
124	* @author bird (2017-08-23)
125	*/
126	DECLR0VBGL(void) VbglR0TerminatePrimary(void);
127
128	/**
129	* The library initialization function to be used by all drivers
130	* other than the main VBoxGuest system driver.
131	*
132	* @return VBox status code.
133	*/
134	DECLR0VBGL(int) VbglR0InitClient(void);
135
136	/**
137	* The library termination function.
138	*/
139	DECLR0VBGL(void) VbglR0TerminateClient(void);
140
141	/**
142	* Query the host feature mask.
143	*
144	* @returns VBox status code.
145	* @param pfHostFeatures Where to return the host feature mask,
146	* VMMDEV_HVF_XXX.
147	* @note Client only. May fail we're unable to connect VBoxGuest.
148	*/
149	DECLR0VBGL(int) VbglR0QueryHostFeatures(uint32_t *pfHostFeatures);
150
151
152	/** @name The IDC Client Interface
153	* @{
154	*/
155
156	/**
157	* Inter-Driver Communication Handle.
158	*/
159	typedef union VBGLIDCHANDLE
160	{
161	/** Padding for opaque usage.
162	* Must be greater or equal in size than the private struct. */
163	void *apvPadding[4];
164	#ifdef VBGLIDCHANDLEPRIVATE_DECLARED
165	/** The private view. */
166	struct VBGLIDCHANDLEPRIVATE s;
167	#endif
168	} VBGLIDCHANDLE;
169	/** Pointer to a handle. */
170	typedef VBGLIDCHANDLE *PVBGLIDCHANDLE;
171
172	DECLR0VBGL(int) VbglR0IdcOpen(PVBGLIDCHANDLE pHandle, uint32_t uReqVersion, uint32_t uMinVersion,
173	uint32_t puSessionVersion, uint32_t puDriverVersion, uint32_t *puDriverRevision);
174	struct VBGLREQHDR;
175	DECLR0VBGL(int) VbglR0IdcCallRaw(PVBGLIDCHANDLE pHandle, uintptr_t uReq, struct VBGLREQHDR *pReqHdr, uint32_t cbReq);
176	DECLR0VBGL(int) VbglR0IdcCall(PVBGLIDCHANDLE pHandle, uintptr_t uReq, struct VBGLREQHDR *pReqHdr, uint32_t cbReq);
177	DECLR0VBGL(int) VbglR0IdcClose(PVBGLIDCHANDLE pHandle);
178
179	/** @} */
180
181
182	/** @name Generic request functions.
183	* @{
184	*/
185
186	/**
187	* Allocate memory for generic request and initialize the request header.
188	*
189	* @returns VBox status code.
190	* @param ppReq Where to return the pointer to the allocated memory.
191	* @param cbReq Size of memory block required for the request.
192	* @param enmReqType the generic request type.
193	*/
194	# if defined(VBOX_INCLUDED_VMMDev_h) \|\| defined(DOXYGEN_RUNNING)
195	DECLR0VBGL(int) VbglR0GRAlloc(struct VMMDevRequestHeader **ppReq, size_t cbReq, VMMDevRequestType enmReqType);
196	# else
197	DECLR0VBGL(int) VbglR0GRAlloc(struct VMMDevRequestHeader **ppReq, size_t cbReq, int32_t enmReqType);
198	# endif
199
200	/**
201	* Perform the generic request.
202	*
203	* @param pReq pointer the request structure.
204	*
205	* @return VBox status code.
206	*/
207	DECLR0VBGL(int) VbglR0GRPerform(struct VMMDevRequestHeader *pReq);
208
209	/**
210	* Free the generic request memory.
211	*
212	* @param pReq pointer the request structure.
213	*
214	* @return VBox status code.
215	*/
216	DECLR0VBGL(void) VbglR0GRFree(struct VMMDevRequestHeader *pReq);
217
218	/**
219	* Verify the generic request header.
220	*
221	* @param pReq pointer the request header structure.
222	* @param cbReq size of the request memory block. It should be equal to the request size
223	* for fixed size requests. It can be greater than the request size for
224	* variable size requests.
225	*
226	* @return VBox status code.
227	*/
228	DECLR0VBGL(int) VbglGR0Verify(const struct VMMDevRequestHeader *pReq, size_t cbReq);
229
230	/** @} */
231
232	# ifdef VBOX_WITH_HGCM
233	struct VBGLIOCHGCMCALL;
234	struct VBGLIOCIDCHGCMFASTCALL;
235
236	# ifdef VBGL_VBOXGUEST
237
238	/**
239	* Callback function called from HGCM helpers when a wait for request
240	* completion IRQ is required.
241	*
242	* @returns VINF_SUCCESS, VERR_INTERRUPT or VERR_TIMEOUT.
243	* @param pvData VBoxGuest pointer to be passed to callback.
244	* @param u32Data VBoxGuest 32 bit value to be passed to callback.
245	*/
246	typedef DECLCALLBACKTYPE(int, FNVBGLHGCMCALLBACK,(VMMDevHGCMRequestHeader pHeader, void pvData, uint32_t u32Data));
247	/** Pointer to a FNVBGLHGCMCALLBACK. */
248	typedef FNVBGLHGCMCALLBACK *PFNVBGLHGCMCALLBACK;
249
250	/**
251	* Perform a connect request.
252	*
253	* That is locate required service and obtain a client identifier for future
254	* access.
255	*
256	* @note This function can NOT handle cancelled requests!
257	*
258	* @param pLoc The service to connect to.
259	* @param fRequestor VMMDEV_REQUESTOR_XXX.
260	* @param pidClient Where to return the client ID on success.
261	* @param pfnAsyncCallback Required pointer to function that is calledwhen
262	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
263	* implements waiting for an IRQ in this function.
264	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
265	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
266	*
267	* @return VBox status code.
268	*/
269	DECLR0VBGL(int) VbglR0HGCMInternalConnect(HGCMServiceLocation const pLoc, uint32_t fRequestor, HGCMCLIENTID pidClient,
270	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
271
272
273	/**
274	* Perform a disconnect request.
275	*
276	* That is tell the host that the client will not call the service anymore.
277	*
278	* @note This function can NOT handle cancelled requests!
279	*
280	* @param idClient The client ID to disconnect.
281	* @param fRequestor VMMDEV_REQUESTOR_XXX.
282	* @param pfnAsyncCallback Required pointer to function that is called when
283	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
284	* implements waiting for an IRQ in this function.
285	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
286	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to
287	* callback.
288	*
289	* @return VBox status code.
290	*/
291
292	DECLR0VBGL(int) VbglR0HGCMInternalDisconnect(HGCMCLIENTID idClient, uint32_t fRequestor,
293	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
294
295	/** Call a HGCM service.
296	*
297	* @note This function can deal with cancelled requests.
298	*
299	* @param pCallInfo The request data.
300	* @param fFlags Flags, see VBGLR0_HGCMCALL_F_XXX.
301	* @param fRequestor VMMDEV_REQUESTOR_XXX.
302	* @param pfnAsyncCallback Required pointer to function that is called when
303	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
304	* implements waiting for an IRQ in this function.
305	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
306	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
307	*
308	* @return VBox status code.
309	*/
310	DECLR0VBGL(int) VbglR0HGCMInternalCall(struct VBGLIOCHGCMCALL *pCallInfo, uint32_t cbCallInfo, uint32_t fFlags, uint32_t fRequestor,
311	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
312
313	/** Call a HGCM service. (32 bits packet structure in a 64 bits guest)
314	*
315	* @note This function can deal with cancelled requests.
316	*
317	* @param pCallInfo The request data.
318	* @param fFlags Flags, see VBGLR0_HGCMCALL_F_XXX.
319	* @param fRequestor VMMDEV_REQUESTOR_XXX.
320	* @param pfnAsyncCallback Required pointer to function that is called when
321	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
322	* implements waiting for an IRQ in this function.
323	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
324	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
325	*
326	* @return VBox status code.
327	*/
328	DECLR0VBGL(int) VbglR0HGCMInternalCall32(struct VBGLIOCHGCMCALL *pCallInfo, uint32_t cbCallInfo, uint32_t fFlags, uint32_t fRequestor,
329	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
330
331	/** @name VbglR0HGCMInternalCall flags
332	* @{ */
333	/** User mode request.
334	* Indicates that only user mode addresses are permitted as parameters. */
335	#define VBGLR0_HGCMCALL_F_USER UINT32_C(0)
336	/** Kernel mode request.
337	* Indicates that kernel mode addresses are permitted as parameters. Whether or
338	* not user mode addresses are permitted is, unfortunately, OS specific. The
339	* following OSes allows user mode addresses: Windows, TODO.
340	*/
341	#define VBGLR0_HGCMCALL_F_KERNEL UINT32_C(1)
342	/** Mode mask. */
343	#define VBGLR0_HGCMCALL_F_MODE_MASK UINT32_C(1)
344	/** @} */
345
346	# else /* !VBGL_VBOXGUEST */
347
348	#ifndef VBGL_VBOXGUEST
349	/** @internal */
350	typedef struct VBGLHGCMHANDLEDATA
351	{
352	uint32_t fAllocated;
353	VBGLIDCHANDLE IdcHandle;
354	} VBGLHGCMHANDLEDATA;
355	#else
356	struct VBGLHGCMHANDLEDATA;
357	#endif
358
359	typedef struct VBGLHGCMHANDLEDATA *VBGLHGCMHANDLE;
360
361	/** @name HGCM functions
362	* @{
363	*/
364
365	/**
366	* Initializes HGCM in the R0 guest library. Must be called before any HGCM
367	* connections are made. Is called by VbglInitClient().
368	*
369	* @return VBox status code.
370	*/
371	DECLR0VBGL(int) VbglR0HGCMInit(void);
372
373	/**
374	* Terminates HGCM in the R0 guest library. Is called by VbglTerminate().
375	*
376	* @return VBox status code.
377	*/
378	DECLR0VBGL(int) VbglR0HGCMTerminate(void);
379
380	/**
381	* Connect to a service.
382	*
383	* @param pHandle Pointer to variable that will hold a handle to be used
384	* further in VbglHGCMCall and VbglHGCMClose.
385	* @param pszServiceName The service to connect to.
386	* @param pidClient Where to return the client ID for the connection.
387	*
388	* @return VBox status code.
389	*
390	* @todo consider baking the client Id into the handle.
391	*/
392	DECLR0VBGL(int) VbglR0HGCMConnect(VBGLHGCMHANDLE pHandle, const char pszServiceName, HGCMCLIENTID *pidClient);
393
394	/**
395	* Connect to a service.
396	*
397	* @param handle Handle of the connection.
398	* @param idClient The ID of the client connection.
399	*
400	* @return VBox status code.
401	*
402	* @todo consider baking the client Id into the handle.
403	*/
404	DECLR0VBGL(int) VbglR0HGCMDisconnect(VBGLHGCMHANDLE handle, HGCMCLIENTID idClient);
405
406	/**
407	* Call to a service, returning only the I/O control status code.
408	*
409	* @param handle Handle of the connection.
410	* @param pData Call request information structure, including function parameters.
411	* @param cbData Length in bytes of data.
412	*
413	* @return VBox status code.
414	*/
415	DECLR0VBGL(int) VbglR0HGCMCallRaw(VBGLHGCMHANDLE handle, struct VBGLIOCHGCMCALL *pData, uint32_t cbData);
416
417	/**
418	* Call to a service, returning the HGCM status code.
419	*
420	* @param handle Handle of the connection.
421	* @param pData Call request information structure, including function parameters.
422	* @param cbData Length in bytes of data.
423	*
424	* @return VBox status code. Either the I/O control status code if that failed,
425	* or the HGCM status code (pData->Hdr.rc).
426	*/
427	DECLR0VBGL(int) VbglR0HGCMCall(VBGLHGCMHANDLE handle, struct VBGLIOCHGCMCALL *pData, uint32_t cbData);
428
429	/**
430	* Call to a service with user-mode data received by the calling driver from the User-Mode process.
431	* The call must be done in the context of a calling process.
432	*
433	* @param handle Handle of the connection.
434	* @param pData Call request information structure, including function parameters.
435	* @param cbData Length in bytes of data.
436	*
437	* @return VBox status code.
438	*/
439	DECLR0VBGL(int) VbglR0HGCMCallUserDataRaw(VBGLHGCMHANDLE handle, struct VBGLIOCHGCMCALL *pData, uint32_t cbData);
440
441	/**
442	* Call to a service, w/o any repacking and buffer locking in VBoxGuest,
443	* returning the only request related status code (not HGCM).
444	*
445	* The driver only submits the request and waits for completion, nothing else.
446	*
447	* @param hHandle The connection handle.
448	* @param pCallReq The call request. Will be passed directly to the host.
449	* @param cbCallReq The size of the whole call request.
450	*
451	* @return VBox status code.
452	*
453	* @remarks The result of the HGCM call is found in
454	* @a pCallReq->HgcmCallReq.header.result on a successful return. The
455	* @a pCallReq->Hdr.rc and @a pCallReq->HgcmCallReq.header.header.rc
456	* fields are the same as the return value and can safely be ignored.
457	*/
458	DECLR0VBGL(int) VbglR0HGCMFastCall(VBGLHGCMHANDLE hHandle, struct VBGLIOCIDCHGCMFASTCALL *pCallReq, uint32_t cbCallReq);
459
460	/** @} */
461
462	/** @name Undocumented helpers for talking to the Chromium OpenGL Host Service
463	* @{ */
464	typedef VBGLHGCMHANDLE VBGLCRCTLHANDLE;
465	DECLR0VBGL(int) VbglR0CrCtlCreate(VBGLCRCTLHANDLE *phCtl);
466	DECLR0VBGL(int) VbglR0CrCtlDestroy(VBGLCRCTLHANDLE hCtl);
467	DECLR0VBGL(int) VbglR0CrCtlConConnect(VBGLCRCTLHANDLE hCtl, HGCMCLIENTID *pidClient);
468	DECLR0VBGL(int) VbglR0CrCtlConDisconnect(VBGLCRCTLHANDLE hCtl, HGCMCLIENTID idClient);
469	struct VBGLIOCHGCMCALL;
470	DECLR0VBGL(int) VbglR0CrCtlConCallRaw(VBGLCRCTLHANDLE hCtl, struct VBGLIOCHGCMCALL *pCallInfo, int cbCallInfo);
471	DECLR0VBGL(int) VbglR0CrCtlConCall(VBGLCRCTLHANDLE hCtl, struct VBGLIOCHGCMCALL *pCallInfo, int cbCallInfo);
472	DECLR0VBGL(int) VbglR0CrCtlConCallUserDataRaw(VBGLCRCTLHANDLE hCtl, struct VBGLIOCHGCMCALL *pCallInfo, int cbCallInfo);
473	/** @} */
474
475	# endif /* !VBGL_VBOXGUEST */
476
477	# endif /* VBOX_WITH_HGCM */
478
479
480	/**
481	* Initialize the heap.
482	*
483	* @returns VBox status code.
484	*/
485	DECLR0VBGL(int) VbglR0PhysHeapInit(void);
486
487	/**
488	* Shutdown the heap.
489	*/
490	DECLR0VBGL(void) VbglR0PhysHeapTerminate(void);
491
492	/**
493	* Allocate a memory block.
494	*
495	* @returns Virtual address of the allocated memory block.
496	* @param cb Number of bytes to allocate.
497	*/
498	DECLR0VBGL(void *) VbglR0PhysHeapAlloc(uint32_t cb);
499
500	/**
501	* Get physical address of memory block pointed by the virtual address.
502	*
503	* @note WARNING!
504	* The function does not acquire the Heap mutex!
505	* When calling the function make sure that the pointer is a valid one and
506	* is not being deallocated. This function can NOT be used for verifying
507	* if the given pointer is a valid one allocated from the heap.
508	*
509	* @param pv Virtual address of memory block.
510	* @returns Physical address of the memory block. Zero is returned if @a pv
511	* isn't valid.
512	*/
513	DECLR0VBGL(uint32_t) VbglR0PhysHeapGetPhysAddr(void *pv);
514
515	# ifdef IN_TESTCASE
516	DECLVBGL(size_t) VbglR0PhysHeapGetFreeSize(void);
517	# endif
518
519	/**
520	* Free a memory block.
521	*
522	* @param pv Virtual address of memory block.
523	*/
524	DECLR0VBGL(void) VbglR0PhysHeapFree(void *pv);
525
526	DECLR0VBGL(int) VbglR0QueryVMMDevMemory(struct VMMDevMemory **ppVMMDevMemory);
527	DECLR0VBGL(bool) VbglR0CanUsePhysPageList(void);
528
529	# ifndef VBOX_GUEST
530	/** @name Mouse
531	* @{ */
532	DECLR0VBGL(int) VbglR0SetMouseNotifyCallback(PFNVBOXGUESTMOUSENOTIFY pfnNotify, void *pvUser);
533	DECLR0VBGL(int) VbglR0GetMouseStatus(uint32_t pfFeatures, uint32_t px, uint32_t *py);
534	DECLR0VBGL(int) VbglR0SetMouseStatus(uint32_t fFeatures);
535	/** @} */
536	# endif /* VBOX_GUEST */
537
538	#endif /* IN_RING0 */
539
540	/** @} */
541
542
543	/** @defgroup grp_vboxguest_lib_r3 Ring-3 interface.
544	* @{
545	*/
546	#ifdef IN_RING3
547
548	/** @def VBGLR3DECL
549	* Ring 3 VBGL declaration.
550	* @param type The return type of the function declaration.
551	*/
552	# define VBGLR3DECL(type) DECL_HIDDEN_NOTHROW(type) VBOXCALL
553
554	/** @name General-purpose functions
555	* @{ */
556	/** Exit code which is returned by VBoxClient child process to notify
557	* parent to release VBoxGuest driver resources on Unix-like guests. */
558	#define VBGLR3EXITCODERELOAD (2)
559
560	VBGLR3DECL(int) VbglR3Init(void);
561	VBGLR3DECL(int) VbglR3InitUser(void);
562	VBGLR3DECL(void) VbglR3Term(void);
563	# ifdef IPRT_INCLUDED_time_h
564	VBGLR3DECL(int) VbglR3GetHostTime(PRTTIMESPEC pTime);
565	# endif
566	VBGLR3DECL(int) VbglR3InterruptEventWaits(void);
567	VBGLR3DECL(int) VbglR3WriteLog(const char *pch, size_t cch);
568	VBGLR3DECL(int) VbglR3CtlFilterMask(uint32_t fOr, uint32_t fNot);
569	VBGLR3DECL(int) VbglR3Daemonize(bool fNoChDir, bool fNoClose, bool fRespawn, unsigned *pcRespawn);
570	VBGLR3DECL(int) VbglR3DaemonizeEx(bool fNoChDir, bool fNoClose, bool fRespawn, unsigned *pcRespawn,
571	bool fReturnOnUpdate, bool pfUpdateStarted, const char szPidfile,
572	RTFILE *phPidfile);
573	VBGLR3DECL(int) VbglR3PidFile(const char *pszPath, PRTFILE phFile);
574	VBGLR3DECL(void) VbglR3ClosePidFile(const char *pszPath, RTFILE hFile);
575	VBGLR3DECL(int) VbglR3PidfileWait(const char szPidfile, RTFILE phPidfile, uint64_t u64TimeoutMs);
576	VBGLR3DECL(int) VbglR3SetGuestCaps(uint32_t fOr, uint32_t fNot);
577	VBGLR3DECL(int) VbglR3AcquireGuestCaps(uint32_t fOr, uint32_t fNot, bool fConfig);
578	VBGLR3DECL(int) VbglR3WaitEvent(uint32_t fMask, uint32_t cMillies, uint32_t *pfEvents);
579
580	VBGLR3DECL(int) VbglR3ReportAdditionsStatus(VBoxGuestFacilityType Facility, VBoxGuestFacilityStatus StatusCurrent,
581	uint32_t fFlags);
582	VBGLR3DECL(int) VbglR3GetAdditionsVersion(char ppszVer, char ppszVerEx, char **ppszRev);
583	VBGLR3DECL(int) VbglR3GetAdditionsInstallationPath(char **ppszPath);
584	VBGLR3DECL(int) VbglR3GetSessionId(uint64_t *pu64IdSession);
585
586	/** @} */
587
588	# ifdef VBOX_WITH_SHARED_CLIPBOARD
589	/** @name Shared Clipboard
590	* @{ */
591
592	# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
593	/**
594	* Structure for maintaining a VbglR3 Shared Clipboard transfer context.
595	*/
596	typedef struct VBGLR3SHCLTRANSFERCMDCTX
597	{
598	/** Default chunk size (in bytes).
599	* This is set by VbglR3ClipboardConnectEx(). */
600	uint32_t cbChunkSize;
601	/** Max chunk size (in bytes).
602	* This is set by VbglR3ClipboardConnectEx(). */
603	uint32_t cbMaxChunkSize;
604	/** Optional callbacks to invoke. */
605	SHCLTRANSFERCALLBACKTABLE Callbacks;
606	} VBGLR3SHCLTRANSFERCTX;
607	/** Pointer to a Shared Clipboard transfer context. */
608	typedef VBGLR3SHCLTRANSFERCMDCTX *PVBGLR3SHCLTRANSFERCMDCTX;
609	# endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
610
611	/**
612	* The context required for either retrieving or sending a HGCM shared clipboard
613	* commands from or to the host.
614	*
615	* @todo This struct could be handy if we want to implement a second
616	* communication channel, e.g. via TCP/IP. Use a union for the HGCM stuff then.
617	*/
618	typedef struct VBGLR3SHCLCMDCTX
619	{
620	/** HGCM client ID to use for communication.
621	* This is set by VbglR3ClipboardConnectEx(). */
622	uint32_t idClient;
623	/** This is @c false if both VBOX_SHCL_HF_0_CONTEXT_ID and
624	* VBOX_SHCL_GF_0_CONTEXT_ID are set, otherwise @c true and only the old
625	* protocol (< 6.1) should be used.
626	* This is set by VbglR3ClipboardConnectEx(). */
627	bool fUseLegacyProtocol;
628	/** Host feature flags (VBOX_SHCL_HF_XXX).
629	* This is set by VbglR3ClipboardConnectEx(). */
630	uint64_t fHostFeatures;
631	/** The guest feature flags reported to the host (VBOX_SHCL_GF_XXX).
632	* This is set by VbglR3ClipboardConnectEx(). */
633	uint64_t fGuestFeatures;
634	/** The context ID - input or/and output depending on the operation. */
635	uint64_t idContext;
636	/** OUT: Number of parameters retrieved.
637	* This is set by ??. */
638	uint32_t cParmsRecived;
639	# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
640	/** Data related to Shared Clipboard file transfers. */
641	VBGLR3SHCLTRANSFERCMDCTX Transfers;
642	# endif
643	} VBGLR3SHCLCMDCTX;
644	/** Pointer to a shared clipboard context for Vbgl. */
645	typedef VBGLR3SHCLCMDCTX *PVBGLR3SHCLCMDCTX;
646
647	/**
648	* Enumeration specifying a Shared Clipboard event type.
649	* @todo r=bird: Surely, this isn't necessary?!
650	*/
651	typedef enum _VBGLR3CLIPBOARDEVENTTYPE
652	{
653	/** No event needed / defined. */
654	VBGLR3CLIPBOARDEVENTTYPE_NONE = 0,
655	/** Host reports available clipboard formats to the guest. */
656	VBGLR3CLIPBOARDEVENTTYPE_REPORT_FORMATS,
657	/** Host wants to read Shared Clipboard data from the guest. */
658	VBGLR3CLIPBOARDEVENTTYPE_READ_DATA,
659	/** Terminates the Shared Clipboard service. */
660	VBGLR3CLIPBOARDEVENTTYPE_QUIT,
661	# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
662	/** Reports a transfer status to the guest. */
663	VBGLR3CLIPBOARDEVENTTYPE_TRANSFER_STATUS,
664	# endif
665	/** Blow the type up to 32-bit. */
666	VBGLR3CLIPBOARDEVENTTYPE_32BIT_HACK = 0x7fffffff
667	} VBGLR3CLIPBOARDEVENTTYPE;
668
669	/**
670	* Structure for keeping a Shared Clipboard VbglR3 event.
671	*/
672	typedef struct _VBGLR3CLIPBOARDEVENT
673	{
674	/** The event type the union contains. */
675	VBGLR3CLIPBOARDEVENTTYPE enmType;
676	/** Command context bound to this event. */
677	VBGLR3SHCLCMDCTX cmdCtx;
678	union
679	{
680	/** Reports available formats from the host. */
681	SHCLFORMATS fReportedFormats;
682	/** Reports that data needs to be read from the guest. */
683	SHCLFORMAT fReadData;
684	# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
685	/** Reports a transfer status to the guest. */
686	struct
687	{
688	/** ID of the trnasfer. */
689	SHCLTRANSFERID uID;
690	/** Transfer direction. */
691	SHCLTRANSFERDIR enmDir;
692	/** Additional reproting information. */
693	SHCLTRANSFERREPORT Report;
694	} TransferStatus;
695	# endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
696	} u;
697	} VBGLR3CLIPBOARDEVENT, *PVBGLR3CLIPBOARDEVENT;
698	typedef const PVBGLR3CLIPBOARDEVENT CPVBGLR3CLIPBOARDEVENT;
699
700	/** @todo r=bird: I'm not sure it is appropriate for the VbglR3 to use types
701	* from VBox/GuestHost/SharedClipboard.h, doesn't seem clean to me. /
702
703	VBGLR3DECL(int) VbglR3ClipboardConnect(HGCMCLIENTID *pidClient);
704	VBGLR3DECL(int) VbglR3ClipboardDisconnect(HGCMCLIENTID idClient);
705	VBGLR3DECL(int) VbglR3ClipboardGetHostMsgOld(HGCMCLIENTID idClient, uint32_t pMsg, uint32_t pfFormats);
706	VBGLR3DECL(int) VbglR3ClipboardReadData(HGCMCLIENTID idClient, uint32_t fFormat, void pv, uint32_t cb, uint32_t pcb);
707	VBGLR3DECL(int) VbglR3ClipboardReadDataEx(PVBGLR3SHCLCMDCTX pCtx, SHCLFORMAT uFormat, void pvData, uint32_t cbData, uint32_t pcbRead);
708	VBGLR3DECL(int) VbglR3ClipboardWriteData(HGCMCLIENTID idClient, uint32_t fFormat, void *pv, uint32_t cb);
709	VBGLR3DECL(int) VbglR3ClipboardWriteDataEx(PVBGLR3SHCLCMDCTX pCtx, SHCLFORMAT fFormat, void *pvData, uint32_t cbData);
710	VBGLR3DECL(int) VbglR3ClipboardReportFormats(HGCMCLIENTID idClient, uint32_t fFormats);
711
712	VBGLR3DECL(int) VbglR3ClipboardConnectEx(PVBGLR3SHCLCMDCTX pCtx, uint64_t fGuestFeatures);
713	VBGLR3DECL(int) VbglR3ClipboardDisconnectEx(PVBGLR3SHCLCMDCTX pCtx);
714
715	VBGLR3DECL(int) VbglR3ClipboardReportFeatures(uint32_t idClient, uint64_t fGuestFeatures, uint64_t *pfHostFeatures);
716	VBGLR3DECL(int) VbglR3ClipboardQueryFeatures(uint32_t idClient, uint64_t *pfHostFeatures);
717	VBGLR3DECL(int) VbglR3ClipboardMsgPeekWait(PVBGLR3SHCLCMDCTX pCtx, uint32_t pidMsg, uint32_t pcParameters, uint64_t *pidRestoreCheck);
718	VBGLR3DECL(int) VbglR3ClipboardEventGetNext(uint32_t idMsg, uint32_t cParms, PVBGLR3SHCLCMDCTX pCtx, PVBGLR3CLIPBOARDEVENT pEvent);
719	VBGLR3DECL(void) VbglR3ClipboardEventFree(PVBGLR3CLIPBOARDEVENT pEvent);
720
721	VBGLR3DECL(int) VbglR3ClipboardWriteError(HGCMCLIENTID idClient, int rcErr);
722
723	# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
724	VBGLR3DECL(void) VbglR3ClipboardTransferSetCallbacks(PSHCLTRANSFERCALLBACKTABLE pCallbacks);
725	VBGLR3DECL(int) VbglR3ClipboardEventGetNextEx(uint32_t idMsg, uint32_t cParms, PVBGLR3SHCLCMDCTX pCtx, PSHCLTRANSFERCTX pTransferCtx, PVBGLR3CLIPBOARDEVENT pEvent);
726
727	VBGLR3DECL(int) VbglR3ClipboardTransferStatusReply(PVBGLR3SHCLCMDCTX pCtx, PSHCLTRANSFER pTransfer, SHCLTRANSFERSTATUS uStatus);
728
729	VBGLR3DECL(int) VbglR3ClipboardRootListRead(PVBGLR3SHCLCMDCTX pCtx, PSHCLROOTLIST *ppRootList);
730
731	VBGLR3DECL(int) VbglR3ClipboardRootListHdrReadReq(PVBGLR3SHCLCMDCTX pCtx, uint32_t *pfRoots);
732	VBGLR3DECL(int) VbglR3ClipboardRootListHdrReadReply(PVBGLR3SHCLCMDCTX pCtx, PSHCLROOTLIST pRootList);
733	VBGLR3DECL(int) VbglR3ClipboardRootsWrite(PVBGLR3SHCLCMDCTX pCtx, PSHCLROOTLISTHDR pRoots);
734
735	VBGLR3DECL(int) VbglR3ClipboardListOpenSend(PVBGLR3SHCLCMDCTX pCtx, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList);
736	VBGLR3DECL(int) VbglR3ClipboardListOpenRecv(PVBGLR3SHCLCMDCTX pCtx, PSHCLLISTOPENPARMS pOpenParms);
737	VBGLR3DECL(int) VbglR3ClipboardListOpenReply(PVBGLR3SHCLCMDCTX pCtx, int rcReply, SHCLLISTHANDLE hList);
738
739	VBGLR3DECL(int) VbglR3ClipboardListCloseSend(PVBGLR3SHCLCMDCTX pCtx, SHCLLISTHANDLE hList);
740	VBGLR3DECL(int) VbglR3ClipboardListCloseRecv(PVBGLR3SHCLCMDCTX pCtx, PSHCLLISTHANDLE phList);
741
742	VBGLR3DECL(int) VbglR3ClipboardListHdrWrite(PVBGLR3SHCLCMDCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr);
743	VBGLR3DECL(int) VbglR3ClipboardListEntryWrite(PVBGLR3SHCLCMDCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pListEntry);
744
745	VBGLR3DECL(int) VbglR3ClipboardObjOpenRecv(PVBGLR3SHCLCMDCTX pCtx, PSHCLOBJOPENCREATEPARMS pCreateParms);
746	VBGLR3DECL(int) VbglR3ClipboardObjOpenReply(PVBGLR3SHCLCMDCTX pCtx, int rcReply, SHCLOBJHANDLE hObj);
747	VBGLR3DECL(int) VbglR3ClipboardObjOpenSend(PVBGLR3SHCLCMDCTX pCtx, PSHCLOBJOPENCREATEPARMS pCreateParms,
748	PSHCLOBJHANDLE phObj);
749
750	VBGLR3DECL(int) VbglR3ClipboardObjCloseRecv(PVBGLR3SHCLCMDCTX pCtx, PSHCLOBJHANDLE phObj);
751	VBGLR3DECL(int) VbglR3ClipboardObjCloseReply(PVBGLR3SHCLCMDCTX pCtx, int rcReply, SHCLOBJHANDLE hObj);
752	VBGLR3DECL(int) VbglR3ClipboardObjCloseSend(PVBGLR3SHCLCMDCTX pCtx, SHCLOBJHANDLE hObj);
753
754	VBGLR3DECL(int) VbglR3ClipboardObjReadRecv(PVBGLR3SHCLCMDCTX pCtx, PSHCLOBJHANDLE phObj, uint32_t pcbToRead,
755	uint32_t *pfFlags);
756	VBGLR3DECL(int) VbglR3ClipboardObjReadSend(PVBGLR3SHCLCMDCTX pCtx, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf,
757	uint32_t *pcbRead);
758	VBGLR3DECL(int) VbglR3ClipboardObjWriteSend(PVBGLR3SHCLCMDCTX pCtx, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf,
759	uint32_t *pcbWritten);
760	# endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
761	/** @} */
762	# endif /* VBOX_WITH_SHARED_CLIPBOARD */
763
764	/** @name Seamless mode
765	* @{ */
766	VBGLR3DECL(int) VbglR3SeamlessSetCap(bool fState);
767	VBGLR3DECL(int) VbglR3SeamlessWaitEvent(VMMDevSeamlessMode *pMode);
768	VBGLR3DECL(int) VbglR3SeamlessSendRects(uint32_t cRects, PRTRECT pRects);
769	VBGLR3DECL(int) VbglR3SeamlessSendMonitorPositions(uint32_t cPositions, PRTPOINT pPositions);
770	VBGLR3DECL(int) VbglR3SeamlessGetLastEvent(VMMDevSeamlessMode *pMode);
771
772	/** @} */
773
774	/** @name Mouse
775	* @{ */
776	VBGLR3DECL(int) VbglR3GetMouseStatus(uint32_t pfFeatures, uint32_t px, uint32_t *py);
777	VBGLR3DECL(int) VbglR3SetMouseStatus(uint32_t fFeatures);
778	/** @} */
779
780	/** @name Video
781	* @{ */
782	VBGLR3DECL(int) VbglR3VideoAccelEnable(bool fEnable);
783	VBGLR3DECL(int) VbglR3VideoAccelFlush(void);
784	VBGLR3DECL(int) VbglR3SetPointerShape(uint32_t fFlags, uint32_t xHot, uint32_t yHot, uint32_t cx, uint32_t cy,
785	const void *pvImg, size_t cbImg);
786	VBGLR3DECL(int) VbglR3SetPointerShapeReq(struct VMMDevReqMousePointer *pReq);
787	/** @} */
788
789	/** @name Display
790	* @{ */
791	/** The folder for the video mode hint unix domain socket on Unix-like guests.
792	* @note This can be safely changed as all users are rebuilt in lock-step. */
793	#define VBGLR3HOSTDISPSOCKETPATH "/tmp/.VBoxService"
794	/** The path to the video mode hint unix domain socket on Unix-like guests. */
795	#define VBGLR3HOSTDISPSOCKET VBGLR3VIDEOMODEHINTSOCKETPATH "/VideoModeHint"
796
797	/** The folder for saving video mode hints to between sessions. */
798	#define VBGLR3HOSTDISPSAVEDMODEPATH "/var/lib/VBoxGuestAdditions"
799	/** The path to the file for saving video mode hints to between sessions. */
800	#define VBGLR3HOSTDISPSAVEDMODE VBGLR3HOSTDISPSAVEDMODEPATH "/SavedVideoModes"
801
802	VBGLR3DECL(int) VbglR3GetDisplayChangeRequest(uint32_t pcx, uint32_t pcy, uint32_t pcBits, uint32_t piDisplay,
803	uint32_t pdx, uint32_t pdy, bool pfEnabled, bool pfChangeOrigin, bool fAck);
804	VBGLR3DECL(int) VbglR3GetDisplayChangeRequestMulti(uint32_t cDisplaysIn, uint32_t *pcDisplaysOut,
805	VMMDevDisplayDef *paDisplays, bool fAck);
806	VBGLR3DECL(bool) VbglR3HostLikesVideoMode(uint32_t cx, uint32_t cy, uint32_t cBits);
807	VBGLR3DECL(int) VbglR3VideoModeGetHighestSavedScreen(unsigned *pcScreen);
808	VBGLR3DECL(int) VbglR3SaveVideoMode(unsigned cScreen, unsigned cx, unsigned cy, unsigned cBits,
809	unsigned x, unsigned y, bool fEnabled);
810	VBGLR3DECL(int) VbglR3RetrieveVideoMode(unsigned cScreen, unsigned pcx, unsigned pcy, unsigned *pcBits,
811	unsigned px, unsigned py, bool *pfEnabled);
812	/** @} */
813
814	/** @name VRDP
815	* @{ */
816	VBGLR3DECL(int) VbglR3VrdpGetChangeRequest(bool pfActive, uint32_t puExperienceLevel);
817	/** @} */
818
819	/** @name VM Statistics
820	* @{ */
821	VBGLR3DECL(int) VbglR3StatQueryInterval(uint32_t *pu32Interval);
822	# if defined(VBOX_INCLUDED_VMMDev_h) \|\| defined(DOXYGEN_RUNNING)
823	VBGLR3DECL(int) VbglR3StatReport(VMMDevReportGuestStats *pReq);
824	# endif
825	/** @} */
826
827	/** @name Memory ballooning
828	* @{ */
829	VBGLR3DECL(int) VbglR3MemBalloonRefresh(uint32_t pcChunks, bool pfHandleInR3);
830	VBGLR3DECL(int) VbglR3MemBalloonChange(void *pv, bool fInflate);
831	/** @} */
832
833	/** @name Core Dump
834	* @{ */
835	VBGLR3DECL(int) VbglR3WriteCoreDump(void);
836
837	/** @} */
838
839	/** @name DRM client handling
840	* @{ */
841	/** Guest property names pattern which is used by Guest Additions DRM services. */
842	# define VBGLR3DRMPROPPTR "/VirtualBox/GuestAdd/DRM*"
843	/** Guest property that defines if the DRM IPC server access should be restricted to a specific user group. */
844	# define VBGLR3DRMIPCPROPRESTRICT "/VirtualBox/GuestAdd/DRMIpcRestricted"
845
846	VBGLR3DECL(bool) VbglR3DrmClientIsNeeded(void);
847	VBGLR3DECL(bool) VbglR3DrmRestrictedIpcAccessIsNeeded(void);
848	VBGLR3DECL(bool) VbglR3DrmClientIsRunning(void);
849	VBGLR3DECL(int) VbglR3DrmClientStart(void);
850	VBGLR3DECL(int) VbglR3DrmLegacyClientStart(void);
851	VBGLR3DECL(int) VbglR3DrmLegacyX11AgentStart(void);
852	/** @} */
853
854	# ifdef VBOX_WITH_GUEST_PROPS
855	/** @name Guest properties
856	* @{ */
857	/** @todo Docs. */
858	typedef struct VBGLR3GUESTPROPENUM VBGLR3GUESTPROPENUM;
859	/** @todo Docs. */
860	typedef VBGLR3GUESTPROPENUM *PVBGLR3GUESTPROPENUM;
861	VBGLR3DECL(int) VbglR3GuestPropConnect(uint32_t *pidClient);
862	VBGLR3DECL(int) VbglR3GuestPropDisconnect(HGCMCLIENTID idClient);
863	VBGLR3DECL(bool) VbglR3GuestPropExist(uint32_t idClient, const char *pszPropName);
864	VBGLR3DECL(int) VbglR3GuestPropWrite(HGCMCLIENTID idClient, const char pszName, const char pszValue, const char *pszFlags);
865	VBGLR3DECL(int) VbglR3GuestPropWriteValue(HGCMCLIENTID idClient, const char pszName, const char pszValue);
866	VBGLR3DECL(int) VbglR3GuestPropWriteValueV(HGCMCLIENTID idClient, const char *pszName,
867	const char *pszValueFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
868	VBGLR3DECL(int) VbglR3GuestPropWriteValueF(HGCMCLIENTID idClient, const char *pszName,
869	const char *pszValueFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
870	VBGLR3DECL(int) VbglR3GuestPropRead(HGCMCLIENTID idClient, const char pszName, void pvBuf, uint32_t cbBuf, char **ppszValue,
871	uint64_t pu64Timestamp, char ppszFlags, uint32_t pcbBufActual);
872	VBGLR3DECL(int) VbglR3GuestPropReadEx(uint32_t u32ClientId,
873	const char pszPropName, char ppszValue, char ppszFlags, uint64_t puTimestamp);
874	VBGLR3DECL(int) VbglR3GuestPropReadValue(uint32_t ClientId, const char pszName, char pszValue, uint32_t cchValue,
875	uint32_t *pcchValueActual);
876	VBGLR3DECL(int) VbglR3GuestPropReadValueAlloc(HGCMCLIENTID idClient, const char pszName, char *ppszValue);
877	VBGLR3DECL(void) VbglR3GuestPropReadValueFree(char *pszValue);
878	VBGLR3DECL(int) VbglR3GuestPropEnumRaw(HGCMCLIENTID idClient, const char paszPatterns, char pcBuf, uint32_t cbBuf,
879	uint32_t *pcbBufActual);
880	VBGLR3DECL(int) VbglR3GuestPropEnum(HGCMCLIENTID idClient, char const * const *ppaszPatterns, uint32_t cPatterns,
881	PVBGLR3GUESTPROPENUM ppHandle, char const ppszName, char const *ppszValue,
882	uint64_t pu64Timestamp, char const *ppszFlags);
883	VBGLR3DECL(int) VbglR3GuestPropEnumNext(PVBGLR3GUESTPROPENUM pHandle, char const ppszName, char const ppszValue,
884	uint64_t pu64Timestamp, char const *ppszFlags);
885	VBGLR3DECL(void) VbglR3GuestPropEnumFree(PVBGLR3GUESTPROPENUM pHandle);
886	VBGLR3DECL(int) VbglR3GuestPropDelete(HGCMCLIENTID idClient, const char *pszName);
887	VBGLR3DECL(int) VbglR3GuestPropDelSet(HGCMCLIENTID idClient, char const * const *papszPatterns, uint32_t cPatterns);
888	VBGLR3DECL(int) VbglR3GuestPropWait(HGCMCLIENTID idClient, const char pszPatterns, void pvBuf, uint32_t cbBuf,
889	uint64_t u64Timestamp, uint32_t cMillies, char ppszName, char ppszValue,
890	uint64_t pu64Timestamp, char ppszFlags, uint32_t pcbBufActual, bool *pfWasDeleted);
891	/** @} */
892
893	/** @name Guest user handling / reporting.
894	* @{ */
895	VBGLR3DECL(int) VbglR3GuestUserReportState(const char pszUser, const char pszDomain, VBoxGuestUserState enmState,
896	uint8_t *pbDetails, uint32_t cbDetails);
897	/** @} */
898
899	/** @name Host version handling
900	* @{ */
901	VBGLR3DECL(int) VbglR3HostVersionCheckForUpdate(HGCMCLIENTID idClient, bool pfUpdate, char *ppszHostVersion,
902	char **ppszGuestVersion);
903	VBGLR3DECL(int) VbglR3HostVersionLastCheckedLoad(HGCMCLIENTID idClient, char **ppszVer);
904	VBGLR3DECL(int) VbglR3HostVersionLastCheckedStore(HGCMCLIENTID idClient, const char *pszVer);
905	/** @} */
906	# endif /* VBOX_WITH_GUEST_PROPS defined */
907
908	# ifdef VBOX_WITH_SHARED_FOLDERS
909	/** @name Shared folders
910	* @{ */
911	/**
912	* Structure containing mapping information for a shared folder.
913	*/
914	typedef struct VBGLR3SHAREDFOLDERMAPPING
915	{
916	/** Mapping status. */
917	uint32_t u32Status;
918	/** Root handle. */
919	uint32_t u32Root;
920	} VBGLR3SHAREDFOLDERMAPPING;
921	/** Pointer to a shared folder mapping information structure. */
922	typedef VBGLR3SHAREDFOLDERMAPPING *PVBGLR3SHAREDFOLDERMAPPING;
923	/** Pointer to a const shared folder mapping information structure. */
924	typedef VBGLR3SHAREDFOLDERMAPPING const *PCVBGLR3SHAREDFOLDERMAPPING;
925
926	VBGLR3DECL(int) VbglR3SharedFolderConnect(uint32_t *pidClient);
927	VBGLR3DECL(int) VbglR3SharedFolderDisconnect(HGCMCLIENTID idClient);
928	VBGLR3DECL(bool) VbglR3SharedFolderExists(HGCMCLIENTID idClient, const char *pszShareName);
929	VBGLR3DECL(int) VbglR3SharedFolderGetMappings(HGCMCLIENTID idClient, bool fAutoMountOnly,
930	PVBGLR3SHAREDFOLDERMAPPING ppaMappings, uint32_t pcMappings);
931	VBGLR3DECL(void) VbglR3SharedFolderFreeMappings(PVBGLR3SHAREDFOLDERMAPPING paMappings);
932	VBGLR3DECL(int) VbglR3SharedFolderGetName(HGCMCLIENTID idClient,uint32_t u32Root, char ppszName); /< @todo r=bird: GET functions return the value, not a status code!*/
933	VBGLR3DECL(int) VbglR3SharedFolderQueryFolderInfo(HGCMCLIENTID idClient, uint32_t idRoot, uint64_t fQueryFlags,
934	char ppszName, char ppszMountPoint,
935	uint64_t pfFlags, uint32_t puRootIdVersion);
936	VBGLR3DECL(int) VbglR3SharedFolderWaitForMappingsChanges(HGCMCLIENTID idClient, uint32_t uPrevVersion, uint32_t *puCurVersion);
937	VBGLR3DECL(int) VbglR3SharedFolderCancelMappingsChangesWaits(HGCMCLIENTID idClient);
938
939	VBGLR3DECL(int) VbglR3SharedFolderGetMountPrefix(char ppszPrefix); /< @todo r=bird: GET functions return the value, not a status code! */
940	VBGLR3DECL(int) VbglR3SharedFolderGetMountDir(char ppszDir); /< @todo r=bird: GET functions return the value, not a status code! */
941	/** @} */
942	# endif /* VBOX_WITH_SHARED_FOLDERS defined */
943
944	# ifdef VBOX_WITH_GUEST_CONTROL
945	/** @name Guest control
946	* @{ */
947
948	/**
949	* Structure containing the context required for
950	* either retrieving or sending a HGCM guest control
951	* commands from or to the host.
952	*
953	* @note Do not change parameter order without also adapting all structure
954	* initializers.
955	*/
956	typedef struct VBGLR3GUESTCTRLCMDCTX
957	{
958	/** @todo This struct could be handy if we want to implement
959	* a second communication channel, e.g. via TCP/IP.
960	* Use a union for the HGCM stuff then. */
961
962	/** IN: HGCM client ID to use for communication. */
963	uint32_t uClientID;
964	/** IN/OUT: Context ID to retrieve or to use. */
965	uint32_t uContextID;
966	/** IN: Protocol version to use. */
967	uint32_t uProtocol;
968	/** OUT: Number of parameters retrieved. */
969	uint32_t uNumParms;
970	} VBGLR3GUESTCTRLCMDCTX, *PVBGLR3GUESTCTRLCMDCTX;
971
972	/**
973	* Structure holding information for starting a guest
974	* session.
975	*/
976	typedef struct VBGLR3GUESTCTRLSESSIONSTARTUPINFO
977	{
978	/** The session's protocol version to use. */
979	uint32_t uProtocol;
980	/** The session's ID. */
981	uint32_t uSessionID;
982	/** User name (account) to start the guest session under. */
983	char *pszUser;
984	/** Size (in bytes) of allocated pszUser. */
985	uint32_t cbUser;
986	/** Password of specified user name (account). */
987	char *pszPassword;
988	/** Size (in bytes) of allocated pszPassword. */
989	uint32_t cbPassword;
990	/** Domain of the user account. */
991	char *pszDomain;
992	/** Size (in bytes) of allocated pszDomain. */
993	uint32_t cbDomain;
994	/** Session creation flags.
995	* @sa VBOXSERVICECTRLSESSIONSTARTUPFLAG_* flags. */
996	uint32_t fFlags;
997	} VBGLR3GUESTCTRLSESSIONSTARTUPINFO;
998	/** Pointer to a guest session startup info. */
999	typedef VBGLR3GUESTCTRLSESSIONSTARTUPINFO *PVBGLR3GUESTCTRLSESSIONSTARTUPINFO;
1000
1001	/**
1002	* Structure holding information for starting a guest
1003	* process.
1004	*/
1005	typedef struct VBGLR3GUESTCTRLPROCSTARTUPINFO
1006	{
1007	/** Full qualified path of process to start (without arguments).
1008	* Note: This is not argv[0]! */
1009	char *pszCmd;
1010	/** Size (in bytes) of allocated pszCmd. */
1011	uint32_t cbCmd;
1012	/** Process execution flags. @sa */
1013	uint32_t fFlags;
1014	/** Command line arguments. */
1015	char *pszArgs;
1016	/** Size (in bytes) of allocated pszArgs. */
1017	uint32_t cbArgs;
1018	/** Number of arguments specified in pszArgs. */
1019	uint32_t cArgs;
1020	/** String of environment variables ("FOO=BAR") to pass to the process
1021	* to start. */
1022	char *pszEnv;
1023	/** Size (in bytes) of environment variables block. */
1024	uint32_t cbEnv;
1025	/** Number of environment variables specified in pszEnv. */
1026	uint32_t cEnvVars;
1027	/** User name (account) to start the process under. */
1028	char *pszUser;
1029	/** Size (in bytes) of allocated pszUser. */
1030	uint32_t cbUser;
1031	/** Password of specified user name (account). */
1032	char *pszPassword;
1033	/** Size (in bytes) of allocated pszPassword. */
1034	uint32_t cbPassword;
1035	/** Domain to be used for authenticating the specified user name (account). */
1036	char *pszDomain;
1037	/** Size (in bytes) of allocated pszDomain. */
1038	uint32_t cbDomain;
1039	/** Time limit (in ms) of the process' life time. */
1040	uint32_t uTimeLimitMS;
1041	/** Process priority. */
1042	uint32_t uPriority;
1043	/** Process affinity block. At the moment we support
1044	* up to 4 blocks, that is, 4 * 64 = 256 CPUs total. */
1045	uint64_t uAffinity[4];
1046	/** Number of used process affinity blocks. */
1047	uint32_t cAffinity;
1048	} VBGLR3GUESTCTRLPROCSTARTUPINFO;
1049	/** Pointer to a guest process startup info. */
1050	typedef VBGLR3GUESTCTRLPROCSTARTUPINFO *PVBGLR3GUESTCTRLPROCSTARTUPINFO;
1051
1052	/* General message handling on the guest. */
1053	VBGLR3DECL(int) VbglR3GuestCtrlConnect(uint32_t *pidClient);
1054	VBGLR3DECL(int) VbglR3GuestCtrlDisconnect(uint32_t idClient);
1055	VBGLR3DECL(bool) VbglR3GuestCtrlSupportsOptimizations(uint32_t idClient);
1056	VBGLR3DECL(int) VbglR3GuestCtrlMakeMeMaster(uint32_t idClient);
1057	VBGLR3DECL(int) VbglR3GuestCtrlReportFeatures(uint32_t idClient, uint64_t fGuestFeatures, uint64_t *pfHostFeatures);
1058	VBGLR3DECL(int) VbglR3GuestCtrlQueryFeatures(uint32_t idClient, uint64_t *pfHostFeatures);
1059	VBGLR3DECL(int) VbglR3GuestCtrlMsgFilterSet(uint32_t uClientId, uint32_t uValue, uint32_t uMaskAdd, uint32_t uMaskRemove);
1060	VBGLR3DECL(int) VbglR3GuestCtrlMsgReply(PVBGLR3GUESTCTRLCMDCTX pCtx, int rc);
1061	VBGLR3DECL(int) VbglR3GuestCtrlMsgReplyEx(PVBGLR3GUESTCTRLCMDCTX pCtx, int rc, uint32_t uType,
1062	void *pvPayload, uint32_t cbPayload);
1063	VBGLR3DECL(int) VbglR3GuestCtrlMsgSkip(uint32_t idClient, int rcSkip, uint32_t idMsg);
1064	VBGLR3DECL(int) VbglR3GuestCtrlMsgSkipOld(uint32_t uClientId);
1065	VBGLR3DECL(int) VbglR3GuestCtrlMsgPeekWait(uint32_t idClient, uint32_t pidMsg, uint32_t pcParameters, uint64_t *pidRestoreCheck);
1066	VBGLR3DECL(int) VbglR3GuestCtrlCancelPendingWaits(HGCMCLIENTID idClient);
1067	/* Guest session handling. */
1068	VBGLR3DECL(int) VbglR3GuestCtrlSessionStartupInfoInit(PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pStartupInfo);
1069	VBGLR3DECL(int) VbglR3GuestCtrlSessionStartupInfoInitEx(PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pStartupInfo, size_t cbUser, size_t cbPassword, size_t cbDomain);
1070	VBGLR3DECL(void) VbglR3GuestCtrlSessionStartupInfoDestroy(PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pStartupInfo);
1071	VBGLR3DECL(void) VbglR3GuestCtrlSessionStartupInfoFree(PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pStartupInfo);
1072	VBGLR3DECL(PVBGLR3GUESTCTRLSESSIONSTARTUPINFO) VbglR3GuestCtrlSessionStartupInfoDup(PVBGLR3GUESTCTRLSESSIONSTARTUPINFO pStartupInfo);
1073	VBGLR3DECL(int) VbglR3GuestCtrlSessionPrepare(uint32_t idClient, uint32_t idSession, void const *pvKey, uint32_t cbKey);
1074	VBGLR3DECL(int) VbglR3GuestCtrlSessionAccept(uint32_t idClient, uint32_t idSession, void const *pvKey, uint32_t cbKey);
1075	VBGLR3DECL(int) VbglR3GuestCtrlSessionCancelPrepared(uint32_t idClient, uint32_t idSession);
1076	VBGLR3DECL(int) VbglR3GuestCtrlSessionHasChanged(uint32_t idClient, uint64_t idNewControlSession);
1077	VBGLR3DECL(int) VbglR3GuestCtrlSessionClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t fFlags);
1078	VBGLR3DECL(int) VbglR3GuestCtrlSessionNotify(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uType, int32_t iResult);
1079	VBGLR3DECL(int) VbglR3GuestCtrlSessionGetOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, PVBGLR3GUESTCTRLSESSIONSTARTUPINFO *ppStartupInfo);
1080	VBGLR3DECL(int) VbglR3GuestCtrlSessionGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t pfFlags, uint32_t pidSession);
1081	/* Guest path handling. */
1082	VBGLR3DECL(int) VbglR3GuestCtrlPathGetRename(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszSource, uint32_t cbSource, char pszDest,
1083	uint32_t cbDest, uint32_t *pfFlags);
1084	VBGLR3DECL(int) VbglR3GuestCtrlPathGetUserDocuments(PVBGLR3GUESTCTRLCMDCTX pCtx);
1085	VBGLR3DECL(int) VbglR3GuestCtrlPathGetUserHome(PVBGLR3GUESTCTRLCMDCTX pCtx);
1086	VBGLR3DECL(int) VbglR3GuestCtrlGetShutdown(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *pfAction);
1087	/* Guest process execution. */
1088	VBGLR3DECL(int) VbglR3GuestCtrlProcStartupInfoInit(PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo);
1089	VBGLR3DECL(int) VbglR3GuestCtrlProcStartupInfoInitEx(PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo, size_t cbCmd, size_t cbUser, size_t cbPassword, size_t cbDomain, size_t cbArgs, size_t cbEnv);
1090	VBGLR3DECL(void) VbglR3GuestCtrlProcStartupInfoDestroy(PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo);
1091	VBGLR3DECL(void) VbglR3GuestCtrlProcStartupInfoFree(PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo);
1092	VBGLR3DECL(PVBGLR3GUESTCTRLPROCSTARTUPINFO) VbglR3GuestCtrlProcStartupInfoDup(PVBGLR3GUESTCTRLPROCSTARTUPINFO pStartupInfo);
1093	VBGLR3DECL(int) VbglR3GuestCtrlProcGetStart(PVBGLR3GUESTCTRLCMDCTX pCtx, PVBGLR3GUESTCTRLPROCSTARTUPINFO *ppStartupInfo);
1094	VBGLR3DECL(int) VbglR3GuestCtrlProcGetTerminate(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puPID);
1095	VBGLR3DECL(int) VbglR3GuestCtrlProcGetInput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puPID, uint32_t pfFlags, void *pvData,
1096	uint32_t cbData, uint32_t *pcbSize);
1097	VBGLR3DECL(int) VbglR3GuestCtrlProcGetOutput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puPID, uint32_t puHandle, uint32_t *pfFlags);
1098	VBGLR3DECL(int) VbglR3GuestCtrlProcGetWaitFor(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puPID, uint32_t puWaitFlags,
1099	uint32_t *puTimeoutMS);
1100	/* Guest native directory handling. */
1101	VBGLR3DECL(int) VbglR3GuestCtrlDirGetRemove(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszPath, uint32_t cbPath, uint32_t pfFlags);
1102	/* Guest native file handling. */
1103	VBGLR3DECL(int) VbglR3GuestCtrlFileGetOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszFileName, uint32_t cbFileName, char pszOpenMode,
1104	uint32_t cbOpenMode, char pszDisposition, uint32_t cbDisposition, char pszSharing,
1105	uint32_t cbSharing, uint32_t puCreationMode, uint64_t puOffset);
1106	VBGLR3DECL(int) VbglR3GuestCtrlFileGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
1107	VBGLR3DECL(int) VbglR3GuestCtrlFileGetRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puHandle, uint32_t puToRead);
1108	VBGLR3DECL(int) VbglR3GuestCtrlFileGetReadAt(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle,
1109	uint32_t puToRead, uint64_t poffRead);
1110	VBGLR3DECL(int) VbglR3GuestCtrlFileGetWrite(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle,
1111	void pvData, uint32_t cbData, uint32_t pcbActual);
1112	VBGLR3DECL(int) VbglR3GuestCtrlFileGetWriteAt(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puHandle, void pvData, uint32_t cbData,
1113	uint32_t pcbActual, uint64_t poffWrite);
1114	VBGLR3DECL(int) VbglR3GuestCtrlFileGetSeek(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle,
1115	uint32_t puSeekMethod, uint64_t poffSeek);
1116	VBGLR3DECL(int) VbglR3GuestCtrlFileGetTell(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
1117	VBGLR3DECL(int) VbglR3GuestCtrlFileGetSetSize(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puHandle, uint64_t pcbNew);
1118
1119	/* Guest -> Host. */
1120	VBGLR3DECL(int) VbglR3GuestCtrlFileCbOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t uFileHandle);
1121	VBGLR3DECL(int) VbglR3GuestCtrlFileCbClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
1122	VBGLR3DECL(int) VbglR3GuestCtrlFileCbError(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
1123	VBGLR3DECL(int) VbglR3GuestCtrlFileCbRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, void *pvData, uint32_t cbData);
1124	VBGLR3DECL(int) VbglR3GuestCtrlFileCbReadOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc,
1125	void *pvData, uint32_t cbData, int64_t offNew);
1126	VBGLR3DECL(int) VbglR3GuestCtrlFileCbWrite(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cbWritten);
1127	VBGLR3DECL(int) VbglR3GuestCtrlFileCbWriteOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cbWritten, int64_t offNew);
1128
1129	VBGLR3DECL(int) VbglR3GuestCtrlFileCbSeek(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t offCurrent);
1130	VBGLR3DECL(int) VbglR3GuestCtrlFileCbTell(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t offCurrent);
1131	VBGLR3DECL(int) VbglR3GuestCtrlFileCbSetSize(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t cbNew);
1132	VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatus(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uStatus, uint32_t fFlags,
1133	void *pvData, uint32_t cbData);
1134	VBGLR3DECL(int) VbglR3GuestCtrlProcCbOutput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uHandle, uint32_t fFlags,
1135	void *pvData, uint32_t cbData);
1136	VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatusInput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t u32PID, uint32_t uStatus,
1137	uint32_t fFlags, uint32_t cbWritten);
1138
1139	/** @} */
1140	# endif /* VBOX_WITH_GUEST_CONTROL defined */
1141
1142	/** @name Auto-logon handling
1143	* @{ */
1144	VBGLR3DECL(int) VbglR3AutoLogonReportStatus(VBoxGuestFacilityStatus enmStatus);
1145	VBGLR3DECL(bool) VbglR3AutoLogonIsRemoteSession(void);
1146	/** @} */
1147
1148	/** @name User credentials handling
1149	* @{ */
1150	VBGLR3DECL(int) VbglR3CredentialsQueryAvailability(void);
1151	VBGLR3DECL(int) VbglR3CredentialsRetrieve(char ppszUser, char ppszPassword, char **ppszDomain);
1152	VBGLR3DECL(int) VbglR3CredentialsRetrieveUtf16(PRTUTF16 ppwszUser, PRTUTF16 ppwszPassword, PRTUTF16 *ppwszDomain);
1153	VBGLR3DECL(void) VbglR3CredentialsDestroy(char pszUser, char pszPassword, char *pszDomain, uint32_t cPasses);
1154	VBGLR3DECL(void) VbglR3CredentialsDestroyUtf16(PRTUTF16 pwszUser, PRTUTF16 pwszPassword, PRTUTF16 pwszDomain,
1155	uint32_t cPasses);
1156	/** @} */
1157
1158	/** @name CPU hotplug monitor
1159	* @{ */
1160	VBGLR3DECL(int) VbglR3CpuHotPlugInit(void);
1161	VBGLR3DECL(int) VbglR3CpuHotPlugTerm(void);
1162	VBGLR3DECL(int) VbglR3CpuHotPlugWaitForEvent(VMMDevCpuEventType penmEventType, uint32_t pidCpuCore, uint32_t *pidCpuPackage);
1163	/** @} */
1164
1165	/** @name Page sharing
1166	* @{ */
1167	struct VMMDEVSHAREDREGIONDESC;
1168	VBGLR3DECL(int) VbglR3RegisterSharedModule(char pszModuleName, char pszVersion, RTGCPTR64 GCBaseAddr, uint32_t cbModule,
1169	unsigned cRegions, struct VMMDEVSHAREDREGIONDESC *pRegions);
1170	VBGLR3DECL(int) VbglR3UnregisterSharedModule(char pszModuleName, char pszVersion, RTGCPTR64 GCBaseAddr, uint32_t cbModule);
1171	VBGLR3DECL(int) VbglR3CheckSharedModules(void);
1172	VBGLR3DECL(bool) VbglR3PageSharingIsEnabled(void);
1173	VBGLR3DECL(int) VbglR3PageIsShared(RTGCPTR pPage, bool pfShared, uint64_t puPageFlags);
1174	/** @} */
1175
1176	# ifdef VBOX_WITH_DRAG_AND_DROP
1177	/** @name Drag and Drop
1178	* @{ */
1179	/**
1180	* Structure containing the context required for
1181	* either retrieving or sending a HGCM guest drag'n drop
1182	* commands from or to the host.
1183	*
1184	* Note: Do not change parameter order without also
1185	* adapting all structure initializers.
1186	*/
1187	typedef struct VBGLR3GUESTDNDCMDCTX
1188	{
1189	/** @todo This struct could be handy if we want to implement
1190	* a second communication channel, e.g. via TCP/IP.
1191	* Use a union for the HGCM stuff then. */
1192
1193	/** HGCM client ID to use for communication. */
1194	uint32_t uClientID;
1195	/** The VM's current session ID. */
1196	uint64_t uSessionID;
1197	/** Protocol version to use.
1198	* Deprecated; do not used / rely on it anymore. */
1199	uint32_t uProtocolDeprecated;
1200	/** Host feature flags (VBOX_DND_HF_XXX).
1201	* This is set by VbglR3DnDConnect(). */
1202	uint64_t fHostFeatures;
1203	/** The guest feature flags reported to the host (VBOX_DND_GF_XXX).
1204	* This is set by VbglR3DnDConnect(). */
1205	uint64_t fGuestFeatures;
1206	/** Number of parameters retrieved for the current command. */
1207	uint32_t uNumParms;
1208	/** Max chunk size (in bytes) for data transfers. */
1209	uint32_t cbMaxChunkSize;
1210	} VBGLR3GUESTDNDCMDCTX, *PVBGLR3GUESTDNDCMDCTX;
1211
1212	/**
1213	* Enumeration for specifying the DnD meta data type.
1214	*/
1215	typedef enum VBGLR3GUESTDNDMETADATATYPE
1216	{
1217	/** Unknown meta data type; don't use. */
1218	VBGLR3GUESTDNDMETADATATYPE_UNKNOWN = 0,
1219	/** Raw meta data; can be everything. */
1220	VBGLR3GUESTDNDMETADATATYPE_RAW,
1221	/** Meta data is a transfer list, specifying objects. */
1222	VBGLR3GUESTDNDMETADATATYPE_URI_LIST,
1223	/** Blow the type up to 32-bit. */
1224	VBGLR3GUESTDNDMETADATATYPE_32BIT_HACK = 0x7fffffff
1225	} VBGLR3GUESTDNDMETADATATYPE;
1226
1227	/**
1228	* Structure for keeping + handling DnD meta data.
1229	*/
1230	typedef struct VBGLR3GUESTDNDMETADATA
1231	{
1232	/** The meta data type the union contains. */
1233	VBGLR3GUESTDNDMETADATATYPE enmType;
1234	/** Union based on \a enmType. */
1235	union
1236	{
1237	struct
1238	{
1239	/** Pointer to actual meta data. */
1240	void *pvMeta;
1241	/** Size (in bytes) of meta data. */
1242	uint32_t cbMeta;
1243	} Raw;
1244	struct
1245	{
1246	DNDTRANSFERLIST Transfer;
1247	} URI;
1248	} u;
1249	} VBGLR3GUESTDNDMETADATA;
1250
1251	/** Pointer to VBGLR3GUESTDNDMETADATA. */
1252	typedef VBGLR3GUESTDNDMETADATA *PVBGLR3GUESTDNDMETADATA;
1253
1254	/** Const pointer to VBGLR3GUESTDNDMETADATA. */
1255	typedef const PVBGLR3GUESTDNDMETADATA CPVBGLR3GUESTDNDMETADATA;
1256
1257	/**
1258	* Enumeration specifying a DnD event type.
1259	*/
1260	typedef enum VBGLR3DNDEVENTTYPE
1261	{
1262	VBGLR3DNDEVENTTYPE_INVALID = 0,
1263	VBGLR3DNDEVENTTYPE_CANCEL,
1264	VBGLR3DNDEVENTTYPE_HG_ERROR,
1265	VBGLR3DNDEVENTTYPE_HG_ENTER,
1266	VBGLR3DNDEVENTTYPE_HG_MOVE,
1267	VBGLR3DNDEVENTTYPE_HG_LEAVE,
1268	VBGLR3DNDEVENTTYPE_HG_DROP,
1269	VBGLR3DNDEVENTTYPE_HG_RECEIVE,
1270	# ifdef VBOX_WITH_DRAG_AND_DROP_GH
1271	VBGLR3DNDEVENTTYPE_GH_ERROR,
1272	VBGLR3DNDEVENTTYPE_GH_REQ_PENDING,
1273	VBGLR3DNDEVENTTYPE_GH_DROP,
1274	# endif
1275	/** Tells the caller that it has to quit operation. */
1276	VBGLR3DNDEVENTTYPE_QUIT,
1277	/** Blow the type up to 32-bit. */
1278	VBGLR3DNDEVENTTYPE_32BIT_HACK = 0x7fffffff
1279	} VBGLR3DNDEVENTTYPE;
1280
1281	typedef struct VBGLR3DNDEVENT
1282	{
1283	/** The event type the union contains. */
1284	VBGLR3DNDEVENTTYPE enmType;
1285	union
1286	{
1287	struct
1288	{
1289	/** Screen ID this request belongs to. */
1290	uint32_t uScreenID;
1291	/** Format list (UTF-8, \r\n separated). */
1292	char *pszFormats;
1293	/** Size (in bytes) of pszFormats (\0 included). */
1294	uint32_t cbFormats;
1295	/** List of allowed DnD actions. */
1296	VBOXDNDACTIONLIST dndLstActionsAllowed;
1297	} HG_Enter;
1298	struct
1299	{
1300	/** Absolute X position of guest screen. */
1301	uint32_t uXpos;
1302	/** Absolute Y position of guest screen. */
1303	uint32_t uYpos;
1304	/** Default DnD action. */
1305	VBOXDNDACTION dndActionDefault;
1306	} HG_Move;
1307	struct
1308	{
1309	/** Absolute X position of guest screen. */
1310	uint32_t uXpos;
1311	/** Absolute Y position of guest screen. */
1312	uint32_t uYpos;
1313	/** Default DnD action. */
1314	VBOXDNDACTION dndActionDefault;
1315	} HG_Drop;
1316	struct
1317	{
1318	/** Meta data for the operation. */
1319	VBGLR3GUESTDNDMETADATA Meta;
1320	} HG_Received;
1321	struct
1322	{
1323	/** IPRT-style error code. */
1324	int rc;
1325	} HG_Error;
1326	# ifdef VBOX_WITH_DRAG_AND_DROP_GH
1327	struct
1328	{
1329	/** Screen ID this request belongs to. */
1330	uint32_t uScreenID;
1331	} GH_IsPending;
1332	struct
1333	{
1334	/** Requested format by the host. */
1335	char *pszFormat;
1336	/** Size (in bytes) of pszFormat (\0 included). */
1337	uint32_t cbFormat;
1338	/** Requested DnD action. */
1339	VBOXDNDACTION dndActionRequested;
1340	} GH_Drop;
1341	# endif
1342	} u;
1343	} VBGLR3DNDEVENT;
1344	typedef VBGLR3DNDEVENT *PVBGLR3DNDEVENT;
1345	typedef const PVBGLR3DNDEVENT CPVBGLR3DNDEVENT;
1346
1347	VBGLR3DECL(int) VbglR3DnDConnect(PVBGLR3GUESTDNDCMDCTX pCtx);
1348	VBGLR3DECL(int) VbglR3DnDDisconnect(PVBGLR3GUESTDNDCMDCTX pCtx);
1349
1350	VBGLR3DECL(int) VbglR3DnDReportFeatures(uint32_t idClient, uint64_t fGuestFeatures, uint64_t *pfHostFeatures);
1351	VBGLR3DECL(int) VbglR3DnDSendError(PVBGLR3GUESTDNDCMDCTX pCtx, int rcOp);
1352
1353	VBGLR3DECL(int) VbglR3DnDEventGetNext(PVBGLR3GUESTDNDCMDCTX pCtx, PVBGLR3DNDEVENT *ppEvent);
1354	VBGLR3DECL(void) VbglR3DnDEventFree(PVBGLR3DNDEVENT pEvent);
1355
1356	VBGLR3DECL(int) VbglR3DnDHGSendAckOp(PVBGLR3GUESTDNDCMDCTX pCtx, VBOXDNDACTION dndAction);
1357	VBGLR3DECL(int) VbglR3DnDHGSendReqData(PVBGLR3GUESTDNDCMDCTX pCtx, const char *pcszFormat);
1358	VBGLR3DECL(int) VbglR3DnDHGSendProgress(PVBGLR3GUESTDNDCMDCTX pCtx, uint32_t uStatus, uint8_t uPercent, int rcErr);
1359	# ifdef VBOX_WITH_DRAG_AND_DROP_GH
1360	VBGLR3DECL(int) VbglR3DnDGHSendAckPending(PVBGLR3GUESTDNDCMDCTX pCtx, VBOXDNDACTION dndActionDefault, VBOXDNDACTIONLIST dndLstActionsAllowed, const char* pcszFormats, uint32_t cbFormats);
1361	VBGLR3DECL(int) VbglR3DnDGHSendData(PVBGLR3GUESTDNDCMDCTX pCtx, const char pszFormat, void pvData, uint32_t cbData);
1362	# endif /* VBOX_WITH_DRAG_AND_DROP_GH */
1363	/** @} */
1364	# endif /* VBOX_WITH_DRAG_AND_DROP */
1365
1366	/* Generic Host Channel Service. */
1367	VBGLR3DECL(int) VbglR3HostChannelInit(uint32_t *pidClient);
1368	VBGLR3DECL(void) VbglR3HostChannelTerm(uint32_t idClient);
1369	VBGLR3DECL(int) VbglR3HostChannelAttach(uint32_t *pu32ChannelHandle, uint32_t u32HGCMClientId,
1370	const char *pszName, uint32_t u32Flags);
1371	VBGLR3DECL(void) VbglR3HostChannelDetach(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId);
1372	VBGLR3DECL(int) VbglR3HostChannelSend(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId,
1373	void *pvData, uint32_t cbData);
1374	VBGLR3DECL(int) VbglR3HostChannelRecv(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId,
1375	void *pvData, uint32_t cbData,
1376	uint32_t pu32SizeReceived, uint32_t pu32SizeRemaining);
1377	VBGLR3DECL(int) VbglR3HostChannelControl(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId,
1378	uint32_t u32Code, void *pvParm, uint32_t cbParm,
1379	void pvData, uint32_t cbData, uint32_t pu32SizeDataReturned);
1380	VBGLR3DECL(int) VbglR3HostChannelEventWait(uint32_t *pu32ChannelHandle, uint32_t u32HGCMClientId,
1381	uint32_t pu32EventId, void pvParm, uint32_t cbParm,
1382	uint32_t *pu32SizeReturned);
1383	VBGLR3DECL(int) VbglR3HostChannelEventCancel(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId);
1384	VBGLR3DECL(int) VbglR3HostChannelQuery(const char *pszName, uint32_t u32HGCMClientId, uint32_t u32Code,
1385	void pvParm, uint32_t cbParm, void pvData, uint32_t cbData,
1386	uint32_t *pu32SizeDataReturned);
1387
1388	/** @name Mode hint storage
1389	* @{ */
1390	VBGLR3DECL(int) VbglR3ReadVideoMode(unsigned cDisplay, unsigned *cx,
1391	unsigned cy, unsigned cBPP, unsigned *x,
1392	unsigned y, unsigned fEnabled);
1393	VBGLR3DECL(int) VbglR3WriteVideoMode(unsigned cDisplay, unsigned cx,
1394	unsigned cy, unsigned cBPP, unsigned x,
1395	unsigned y, unsigned fEnabled);
1396	/** @} */
1397
1398	/** @name Generic HGCM
1399	* @{ */
1400	VBGLR3DECL(int) VbglR3HGCMConnect(const char pszServiceName, HGCMCLIENTID pidClient);
1401	VBGLR3DECL(int) VbglR3HGCMDisconnect(HGCMCLIENTID idClient);
1402	struct VBGLIOCHGCMCALL;
1403	VBGLR3DECL(int) VbglR3HGCMCall(struct VBGLIOCHGCMCALL *pInfo, size_t cbInfo);
1404	/** @} */
1405
1406	#endif /* IN_RING3 */
1407	/** @} */
1408
1409	RT_C_DECLS_END
1410
1411	/** @} */
1412
1413	#endif /* !VBOX_INCLUDED_VBoxGuestLib_h */

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

source: vbox/trunk/include/VBox/VBoxGuestLib.h@ 98472

Download in other formats: