VBoxGuestLib.h@ 100205

最後變更在這個檔案從100205是 100205,由 vboxsync 提交於 20 月前
Shared Clipboard: Unified root list entry code to also use the generic list entry code, a lot of updates for the cross OS transfer handling code, more updates for HTTP server transfer handling. This also changed the handling of how that transfers are being initiated, as we needed to have this for X11: Before, transfers were initiated as soon as on side announced the URI list format -- now we postpone initiating the transfer until the receiving side requests the data as URI list [build fix]. bugref:9437
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Author Date Id Revision`
檔案大小: 65.9 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: