VBoxGuestLib.h@ 79296

Last change on this file since 79296 was 79296, checked in by vboxsync, 6 years ago
Main,VBoxService,GstCtrlSvc: Added functions for exchanging feature masks between guest and host so new features can more easily be added without resorting to version comparsion magic. Added alternative read and write completion notifications that includes the new file offset. Made sure RTFileReadAt and RTFileWriteAt are followed by a RTFileSeek call so we'll end up with the same file position regardless of guest OS. bugref:9320
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 50.9 KB

Line
1	/** @file
2	* VBoxGuestLib - VirtualBox Guest Additions Library.
3	*/
4
5	/*
6	* Copyright (C) 2006-2019 Oracle Corporation
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/DragAndDropDefs.h>
41	# endif
42	# ifdef VBOX_WITH_SHARED_CLIPBOARD
43	# include <VBox/GuestHost/SharedClipboard.h>
44	# ifdef VBOX_WITH_SHARED_CLIPBOARD_URI_LIST
45	# include <VBox/GuestHost/SharedClipboard-uri.h>
46	# endif
47	# endif /* VBOX_WITH_SHARED_CLIPBOARD */
48
49	/** @defgroup grp_vboxguest_lib VirtualBox Guest Additions Library
50	* @ingroup grp_vboxguest
51	* @{
52	*/
53
54	/** @page pg_guest_lib VirtualBox Guest Library
55	*
56	* This is a library for abstracting the additions driver interface. There are
57	* multiple versions of the library depending on the context. The main
58	* distinction is between kernel and user mode where the interfaces are very
59	* different.
60	*
61	*
62	* @section sec_guest_lib_ring0 Ring-0
63	*
64	* In ring-0 there are two version:
65	* - VBOX_LIB_VBGL_R0_BASE / VBoxGuestR0LibBase for the VBoxGuest main driver,
66	* who is responsible for managing the VMMDev virtual hardware.
67	* - VBOX_LIB_VBGL_R0 / VBoxGuestR0Lib for other (client) guest drivers.
68	*
69	*
70	* The library source code and the header have a define VBGL_VBOXGUEST, which is
71	* defined for VBoxGuest and undefined for other drivers. Drivers must choose
72	* right library in their makefiles and set VBGL_VBOXGUEST accordingly.
73	*
74	* The libraries consists of:
75	* - common code to be used by both VBoxGuest and other drivers;
76	* - VBoxGuest specific code;
77	* - code for other drivers which communicate with VBoxGuest via an IOCTL.
78	*
79	*
80	* @section sec_guest_lib_ring3 Ring-3
81	*
82	* There are more variants of the library here:
83	* - VBOX_LIB_VBGL_R3 / VBoxGuestR3Lib for programs.
84	* - VBOX_LIB_VBGL_R3_XFREE86 / VBoxGuestR3LibXFree86 for old style XFree
85	* drivers which uses special loader and or symbol resolving strategy.
86	* - VBOX_LIB_VBGL_R3_SHARED / VBoxGuestR3LibShared for shared objects / DLLs /
87	* Dylibs.
88	*
89	*/
90
91	RT_C_DECLS_BEGIN
92
93	/** HGCM client ID.
94	* @todo Promote to VBox/types.h */
95	typedef uint32_t HGCMCLIENTID;
96
97
98	/** @defgroup grp_vboxguest_lib_r0 Ring-0 interface.
99	* @{
100	*/
101	#ifdef IN_RING0
102	/** @def DECLR0VBGL
103	* Declare a VBGL ring-0 API with the right calling convention and visibilitiy.
104	* @param type Return type. */
105	# ifdef RT_OS_DARWIN /** @todo probably apply to all, but don't want a forest fire on our hands right now. */
106	# define DECLR0VBGL(type) DECLHIDDEN(type) VBOXCALL
107	# else
108	# define DECLR0VBGL(type) type VBOXCALL
109	# endif
110	# define DECLVBGL(type) DECLR0VBGL(type)
111
112
113	/**
114	* The library initialization function to be used by the main VBoxGuest driver.
115	*
116	* @return VBox status code.
117	*/
118	DECLR0VBGL(int) VbglR0InitPrimary(RTIOPORT portVMMDev, VMMDevMemory pVMMDevMemory, uint32_t pfFeatures);
119
120	/**
121	* The library termination function to be used by the main VBoxGuest driver.
122	*
123	* @author bird (2017-08-23)
124	*/
125	DECLR0VBGL(void) VbglR0TerminatePrimary(void);
126
127	/**
128	* The library initialization function to be used by all drivers
129	* other than the main VBoxGuest system driver.
130	*
131	* @return VBox status code.
132	*/
133	DECLR0VBGL(int) VbglR0InitClient(void);
134
135	/**
136	* The library termination function.
137	*/
138	DECLR0VBGL(void) VbglR0TerminateClient(void);
139
140	/**
141	* Query the host feature mask.
142	*
143	* @returns VBox status code.
144	* @param pfHostFeatures Where to return the host feature mask,
145	* VMMDEV_HVF_XXX.
146	* @note Client only. May fail we're unable to connect VBoxGuest.
147	*/
148	DECLR0VBGL(int) VbglR0QueryHostFeatures(uint32_t *pfHostFeatures);
149
150
151	/** @name The IDC Client Interface
152	* @{
153	*/
154
155	/**
156	* Inter-Driver Communication Handle.
157	*/
158	typedef union VBGLIDCHANDLE
159	{
160	/** Padding for opaque usage.
161	* Must be greater or equal in size than the private struct. */
162	void *apvPadding[4];
163	#ifdef VBGLIDCHANDLEPRIVATE_DECLARED
164	/** The private view. */
165	struct VBGLIDCHANDLEPRIVATE s;
166	#endif
167	} VBGLIDCHANDLE;
168	/** Pointer to a handle. */
169	typedef VBGLIDCHANDLE *PVBGLIDCHANDLE;
170
171	DECLR0VBGL(int) VbglR0IdcOpen(PVBGLIDCHANDLE pHandle, uint32_t uReqVersion, uint32_t uMinVersion,
172	uint32_t puSessionVersion, uint32_t puDriverVersion, uint32_t *puDriverRevision);
173	struct VBGLREQHDR;
174	DECLR0VBGL(int) VbglR0IdcCallRaw(PVBGLIDCHANDLE pHandle, uintptr_t uReq, struct VBGLREQHDR *pReqHdr, uint32_t cbReq);
175	DECLR0VBGL(int) VbglR0IdcCall(PVBGLIDCHANDLE pHandle, uintptr_t uReq, struct VBGLREQHDR *pReqHdr, uint32_t cbReq);
176	DECLR0VBGL(int) VbglR0IdcClose(PVBGLIDCHANDLE pHandle);
177
178	/** @} */
179
180
181	/** @name Generic request functions.
182	* @{
183	*/
184
185	/**
186	* Allocate memory for generic request and initialize the request header.
187	*
188	* @returns VBox status code.
189	* @param ppReq Where to return the pointer to the allocated memory.
190	* @param cbReq Size of memory block required for the request.
191	* @param enmReqType the generic request type.
192	*/
193	# if defined(VBOX_INCLUDED_VMMDev_h) \|\| defined(DOXYGEN_RUNNING)
194	DECLR0VBGL(int) VbglR0GRAlloc(struct VMMDevRequestHeader **ppReq, size_t cbReq, VMMDevRequestType enmReqType);
195	# else
196	DECLR0VBGL(int) VbglR0GRAlloc(struct VMMDevRequestHeader **ppReq, size_t cbReq, int32_t enmReqType);
197	# endif
198
199	/**
200	* Perform the generic request.
201	*
202	* @param pReq pointer the request structure.
203	*
204	* @return VBox status code.
205	*/
206	DECLR0VBGL(int) VbglR0GRPerform(struct VMMDevRequestHeader *pReq);
207
208	/**
209	* Free the generic request memory.
210	*
211	* @param pReq pointer the request structure.
212	*
213	* @return VBox status code.
214	*/
215	DECLR0VBGL(void) VbglR0GRFree(struct VMMDevRequestHeader *pReq);
216
217	/**
218	* Verify the generic request header.
219	*
220	* @param pReq pointer the request header structure.
221	* @param cbReq size of the request memory block. It should be equal to the request size
222	* for fixed size requests. It can be greater than the request size for
223	* variable size requests.
224	*
225	* @return VBox status code.
226	*/
227	DECLR0VBGL(int) VbglGR0Verify(const struct VMMDevRequestHeader *pReq, size_t cbReq);
228
229	/** @} */
230
231	# ifdef VBOX_WITH_HGCM
232	struct VBGLIOCHGCMCALL;
233	struct VBGLIOCIDCHGCMFASTCALL;
234
235	# ifdef VBGL_VBOXGUEST
236
237	/**
238	* Callback function called from HGCM helpers when a wait for request
239	* completion IRQ is required.
240	*
241	* @returns VINF_SUCCESS, VERR_INTERRUPT or VERR_TIMEOUT.
242	* @param pvData VBoxGuest pointer to be passed to callback.
243	* @param u32Data VBoxGuest 32 bit value to be passed to callback.
244	*/
245	typedef DECLCALLBACK(int) FNVBGLHGCMCALLBACK(VMMDevHGCMRequestHeader pHeader, void pvData, uint32_t u32Data);
246	/** Pointer to a FNVBGLHGCMCALLBACK. */
247	typedef FNVBGLHGCMCALLBACK *PFNVBGLHGCMCALLBACK;
248
249	/**
250	* Perform a connect request.
251	*
252	* That is locate required service and obtain a client identifier for future
253	* access.
254	*
255	* @note This function can NOT handle cancelled requests!
256	*
257	* @param pLoc The service to connect to.
258	* @param fRequestor VMMDEV_REQUESTOR_XXX.
259	* @param pidClient Where to return the client ID on success.
260	* @param pfnAsyncCallback Required pointer to function that is calledwhen
261	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
262	* implements waiting for an IRQ in this function.
263	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
264	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
265	*
266	* @return VBox status code.
267	*/
268	DECLR0VBGL(int) VbglR0HGCMInternalConnect(HGCMServiceLocation const pLoc, uint32_t fRequestor, HGCMCLIENTID pidClient,
269	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
270
271
272	/**
273	* Perform a disconnect request.
274	*
275	* That is tell the host that the client will not call the service anymore.
276	*
277	* @note This function can NOT handle cancelled requests!
278	*
279	* @param idClient The client ID to disconnect.
280	* @param fRequestor VMMDEV_REQUESTOR_XXX.
281	* @param pfnAsyncCallback Required pointer to function that is called when
282	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
283	* implements waiting for an IRQ in this function.
284	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
285	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to
286	* callback.
287	*
288	* @return VBox status code.
289	*/
290
291	DECLR0VBGL(int) VbglR0HGCMInternalDisconnect(HGCMCLIENTID idClient, uint32_t fRequestor,
292	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
293
294	/** Call a HGCM service.
295	*
296	* @note This function can deal with cancelled requests.
297	*
298	* @param pCallInfo The request data.
299	* @param fFlags Flags, see VBGLR0_HGCMCALL_F_XXX.
300	* @param fRequestor VMMDEV_REQUESTOR_XXX.
301	* @param pfnAsyncCallback Required pointer to function that is called when
302	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
303	* implements waiting for an IRQ in this function.
304	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
305	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
306	*
307	* @return VBox status code.
308	*/
309	DECLR0VBGL(int) VbglR0HGCMInternalCall(struct VBGLIOCHGCMCALL *pCallInfo, uint32_t cbCallInfo, uint32_t fFlags, uint32_t fRequestor,
310	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
311
312	/** Call a HGCM service. (32 bits packet structure in a 64 bits guest)
313	*
314	* @note This function can deal with cancelled requests.
315	*
316	* @param pCallInfo The request data.
317	* @param fFlags Flags, see VBGLR0_HGCMCALL_F_XXX.
318	* @param fRequestor VMMDEV_REQUESTOR_XXX.
319	* @param pfnAsyncCallback Required pointer to function that is called when
320	* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
321	* implements waiting for an IRQ in this function.
322	* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
323	* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
324	*
325	* @return VBox status code.
326	*/
327	DECLR0VBGL(int) VbglR0HGCMInternalCall32(struct VBGLIOCHGCMCALL *pCallInfo, uint32_t cbCallInfo, uint32_t fFlags, uint32_t fRequestor,
328	PFNVBGLHGCMCALLBACK pfnAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
329
330	/** @name VbglR0HGCMInternalCall flags
331	* @{ */
332	/** User mode request.
333	* Indicates that only user mode addresses are permitted as parameters. */
334	#define VBGLR0_HGCMCALL_F_USER UINT32_C(0)
335	/** Kernel mode request.
336	* Indicates that kernel mode addresses are permitted as parameters. Whether or
337	* not user mode addresses are permitted is, unfortunately, OS specific. The
338	* following OSes allows user mode addresses: Windows, TODO.
339	*/
340	#define VBGLR0_HGCMCALL_F_KERNEL UINT32_C(1)
341	/** Mode mask. */
342	#define VBGLR0_HGCMCALL_F_MODE_MASK UINT32_C(1)
343	/** @} */
344
345	# else /* !VBGL_VBOXGUEST */
346
347	#ifndef VBGL_VBOXGUEST
348	/** @internal */
349	typedef struct VBGLHGCMHANDLEDATA
350	{
351	uint32_t fAllocated;
352	VBGLIDCHANDLE IdcHandle;
353	} VBGLHGCMHANDLEDATA;
354	#else
355	struct VBGLHGCMHANDLEDATA;
356	#endif
357
358	typedef struct VBGLHGCMHANDLEDATA *VBGLHGCMHANDLE;
359
360	/** @name HGCM functions
361	* @{
362	*/
363
364	/**
365	* Initializes HGCM in the R0 guest library. Must be called before any HGCM
366	* connections are made. Is called by VbglInitClient().
367	*
368	* @return VBox status code.
369	*/
370	DECLR0VBGL(int) VbglR0HGCMInit(void);
371
372	/**
373	* Terminates HGCM in the R0 guest library. Is called by VbglTerminate().
374	*
375	* @return VBox status code.
376	*/
377	DECLR0VBGL(int) VbglR0HGCMTerminate(void);
378
379	/**
380	* Connect to a service.
381	*
382	* @param pHandle Pointer to variable that will hold a handle to be used
383	* further in VbglHGCMCall and VbglHGCMClose.
384	* @param pszServiceName The service to connect to.
385	* @param pidClient Where to return the client ID for the connection.
386	*
387	* @return VBox status code.
388	*
389	* @todo consider baking the client Id into the handle.
390	*/
391	DECLR0VBGL(int) VbglR0HGCMConnect(VBGLHGCMHANDLE pHandle, const char pszServiceName, HGCMCLIENTID *pidClient);
392
393	/**
394	* Connect to a service.
395	*
396	* @param handle Handle of the connection.
397	* @param idClient The ID of the client connection.
398	*
399	* @return VBox status code.
400	*
401	* @todo consider baking the client Id into the handle.
402	*/
403	DECLR0VBGL(int) VbglR0HGCMDisconnect(VBGLHGCMHANDLE handle, HGCMCLIENTID idClient);
404
405	/**
406	* Call to a service, returning only the I/O control status code.
407	*
408	* @param handle Handle of the connection.
409	* @param pData Call request information structure, including function parameters.
410	* @param cbData Length in bytes of data.
411	*
412	* @return VBox status code.
413	*/
414	DECLR0VBGL(int) VbglR0HGCMCallRaw(VBGLHGCMHANDLE handle, struct VBGLIOCHGCMCALL *pData, uint32_t cbData);
415
416	/**
417	* Call to a service, returning the HGCM status code.
418	*
419	* @param handle Handle of the connection.
420	* @param pData Call request information structure, including function parameters.
421	* @param cbData Length in bytes of data.
422	*
423	* @return VBox status code. Either the I/O control status code if that failed,
424	* or the HGCM status code (pData->Hdr.rc).
425	*/
426	DECLR0VBGL(int) VbglR0HGCMCall(VBGLHGCMHANDLE handle, struct VBGLIOCHGCMCALL *pData, uint32_t cbData);
427
428	/**
429	* Call to a service with user-mode data received by the calling driver from the User-Mode process.
430	* The call must be done in the context of a calling process.
431	*
432	* @param handle Handle of the connection.
433	* @param pData Call request information structure, including function parameters.
434	* @param cbData Length in bytes of data.
435	*
436	* @return VBox status code.
437	*/
438	DECLR0VBGL(int) VbglR0HGCMCallUserDataRaw(VBGLHGCMHANDLE handle, struct VBGLIOCHGCMCALL *pData, uint32_t cbData);
439
440	/**
441	* Call to a service, w/o any repacking and buffer locking in VBoxGuest,
442	* returning the only request related status code (not HGCM).
443	*
444	* The driver only submits the request and waits for completion, nothing else.
445	*
446	* @param hHandle The connection handle.
447	* @param pCallReq The call request. Will be passed directly to the host.
448	* @param cbCallReq The size of the whole call request.
449	*
450	* @return VBox status code.
451	*
452	* @remarks The result of the HGCM call is found in
453	* @a pCallReq->HgcmCallReq.header.result on a successful return. The
454	* @a pCallReq->Hdr.rc and @a pCallReq->HgcmCallReq.header.header.rc
455	* fields are the same as the return value and can safely be ignored.
456	*/
457	DECLR0VBGL(int) VbglR0HGCMFastCall(VBGLHGCMHANDLE hHandle, struct VBGLIOCIDCHGCMFASTCALL *pCallReq, uint32_t cbCallReq);
458
459	/** @} */
460
461	/** @name Undocumented helpers for talking to the Chromium OpenGL Host Service
462	* @{ */
463	typedef VBGLHGCMHANDLE VBGLCRCTLHANDLE;
464	DECLR0VBGL(int) VbglR0CrCtlCreate(VBGLCRCTLHANDLE *phCtl);
465	DECLR0VBGL(int) VbglR0CrCtlDestroy(VBGLCRCTLHANDLE hCtl);
466	DECLR0VBGL(int) VbglR0CrCtlConConnect(VBGLCRCTLHANDLE hCtl, HGCMCLIENTID *pidClient);
467	DECLR0VBGL(int) VbglR0CrCtlConDisconnect(VBGLCRCTLHANDLE hCtl, HGCMCLIENTID idClient);
468	struct VBGLIOCHGCMCALL;
469	DECLR0VBGL(int) VbglR0CrCtlConCallRaw(VBGLCRCTLHANDLE hCtl, struct VBGLIOCHGCMCALL *pCallInfo, int cbCallInfo);
470	DECLR0VBGL(int) VbglR0CrCtlConCall(VBGLCRCTLHANDLE hCtl, struct VBGLIOCHGCMCALL *pCallInfo, int cbCallInfo);
471	DECLR0VBGL(int) VbglR0CrCtlConCallUserDataRaw(VBGLCRCTLHANDLE hCtl, struct VBGLIOCHGCMCALL *pCallInfo, int cbCallInfo);
472	/** @} */
473
474	# endif /* !VBGL_VBOXGUEST */
475
476	# endif /* VBOX_WITH_HGCM */
477
478
479	/**
480	* Initialize the heap.
481	*
482	* @returns VBox status code.
483	*/
484	DECLR0VBGL(int) VbglR0PhysHeapInit(void);
485
486	/**
487	* Shutdown the heap.
488	*/
489	DECLR0VBGL(void) VbglR0PhysHeapTerminate(void);
490
491	/**
492	* Allocate a memory block.
493	*
494	* @returns Virtual address of the allocated memory block.
495	* @param cbSize Size of block to be allocated.
496	*/
497	DECLR0VBGL(void *) VbglR0PhysHeapAlloc(uint32_t cbSize);
498
499	/**
500	* Get physical address of memory block pointed by the virtual address.
501	*
502	* @note WARNING!
503	* The function does not acquire the Heap mutex!
504	* When calling the function make sure that the pointer is a valid one and
505	* is not being deallocated. This function can NOT be used for verifying
506	* if the given pointer is a valid one allocated from the heap.
507	*
508	* @param pv Virtual address of memory block.
509	* @returns Physical address of the memory block.
510	*/
511	DECLR0VBGL(uint32_t) VbglR0PhysHeapGetPhysAddr(void *pv);
512
513	/**
514	* Free a memory block.
515	*
516	* @param pv Virtual address of memory block.
517	*/
518	DECLR0VBGL(void) VbglR0PhysHeapFree(void *pv);
519
520	DECLR0VBGL(int) VbglR0QueryVMMDevMemory(struct VMMDevMemory **ppVMMDevMemory);
521	DECLR0VBGL(bool) VbglR0CanUsePhysPageList(void);
522
523	# ifndef VBOX_GUEST
524	/** @name Mouse
525	* @{ */
526	DECLR0VBGL(int) VbglR0SetMouseNotifyCallback(PFNVBOXGUESTMOUSENOTIFY pfnNotify, void *pvUser);
527	DECLR0VBGL(int) VbglR0GetMouseStatus(uint32_t pfFeatures, uint32_t px, uint32_t *py);
528	DECLR0VBGL(int) VbglR0SetMouseStatus(uint32_t fFeatures);
529	/** @} */
530	# endif /* VBOX_GUEST */
531
532	#endif /* IN_RING0 */
533
534	/** @} */
535
536
537	/** @defgroup grp_vboxguest_lib_r3 Ring-3 interface.
538	* @{
539	*/
540	#ifdef IN_RING3
541
542	/** @def VBGLR3DECL
543	* Ring 3 VBGL declaration.
544	* @param type The return type of the function declaration.
545	*/
546	# define VBGLR3DECL(type) DECLHIDDEN(type) VBOXCALL
547
548	/** @name General-purpose functions
549	* @{ */
550	VBGLR3DECL(int) VbglR3Init(void);
551	VBGLR3DECL(int) VbglR3InitUser(void);
552	VBGLR3DECL(void) VbglR3Term(void);
553	# ifdef IPRT_INCLUDED_time_h
554	VBGLR3DECL(int) VbglR3GetHostTime(PRTTIMESPEC pTime);
555	# endif
556	VBGLR3DECL(int) VbglR3InterruptEventWaits(void);
557	VBGLR3DECL(int) VbglR3WriteLog(const char *pch, size_t cch);
558	VBGLR3DECL(int) VbglR3CtlFilterMask(uint32_t fOr, uint32_t fNot);
559	VBGLR3DECL(int) VbglR3Daemonize(bool fNoChDir, bool fNoClose, bool fRespawn, unsigned *pcRespawn);
560	VBGLR3DECL(int) VbglR3PidFile(const char *pszPath, PRTFILE phFile);
561	VBGLR3DECL(void) VbglR3ClosePidFile(const char *pszPath, RTFILE hFile);
562	VBGLR3DECL(int) VbglR3SetGuestCaps(uint32_t fOr, uint32_t fNot);
563	VBGLR3DECL(int) VbglR3AcquireGuestCaps(uint32_t fOr, uint32_t fNot, bool fConfig);
564	VBGLR3DECL(int) VbglR3WaitEvent(uint32_t fMask, uint32_t cMillies, uint32_t *pfEvents);
565
566	VBGLR3DECL(int) VbglR3ReportAdditionsStatus(VBoxGuestFacilityType Facility, VBoxGuestFacilityStatus StatusCurrent,
567	uint32_t fFlags);
568	VBGLR3DECL(int) VbglR3GetAdditionsVersion(char ppszVer, char ppszVerEx, char **ppszRev);
569	VBGLR3DECL(int) VbglR3GetAdditionsInstallationPath(char **ppszPath);
570	VBGLR3DECL(int) VbglR3GetSessionId(uint64_t *pu64IdSession);
571
572	/** @} */
573
574	# ifdef VBOX_WITH_SHARED_CLIPBOARD
575	/** @name Shared Clipboard
576	* @{ */
577	/**
578	* Structure containing the context required for Shared Clipboard operations.
579	*
580	* Note: Do not change parameter order without also
581	* adapting all structure initializers.
582	*/
583	typedef struct _VBGLR3GUESTCLIPBOARDCMDCTX
584	{
585	/** @todo This struct could be handy if we want to implement
586	* a second communication channel, e.g. via TCP/IP.
587	* Use a union for the HGCM stuff then. */
588
589	/** HGCM client ID to use for communication. */
590	uint32_t uClientID;
591	/** The VM's current session ID. */
592	uint64_t uSessionID;
593	/** The transfer ID to use. */
594	uint32_t uTransferID;
595	/** Number of parameters retrieved for the current command. */
596	uint32_t uNumParms;
597	/** Max chunk size (in bytes) for data transfers. */
598	uint32_t cbMaxChunkSize;
599	} VBGLR3GUESTCLIPBOARDCMDCTX, *PVBGLR3GUESTCLIPBOARDCMDCTX;
600
601	VBGLR3DECL(int) VbglR3ClipboardConnect(HGCMCLIENTID *pidClient);
602	VBGLR3DECL(int) VbglR3ClipboardDisconnect(HGCMCLIENTID idClient);
603	VBGLR3DECL(int) VbglR3ClipboardGetHostMsg(HGCMCLIENTID idClient, uint32_t pMsg, uint32_t pfFormats);
604	VBGLR3DECL(int) VbglR3ClipboardReadData(HGCMCLIENTID idClient, uint32_t fFormat, void pv, uint32_t cb, uint32_t pcb);
605	VBGLR3DECL(int) VbglR3ClipboardReportFormats(HGCMCLIENTID idClient, uint32_t fFormats);
606	VBGLR3DECL(int) VbglR3ClipboardWriteData(HGCMCLIENTID idClient, uint32_t fFormat, void *pv, uint32_t cb);
607
608	# ifdef VBOX_WITH_SHARED_CLIPBOARD_URI_LIST
609	VBGLR3DECL(int) VbglR3ClipboardReadDataHdr(HGCMCLIENTID idClient, PVBOXCLIPBOARDDATAHDR pDataHdr);
610	VBGLR3DECL(int) VbglR3ClipboardWriteDataHdr(HGCMCLIENTID idClient, const PVBOXCLIPBOARDDATAHDR pDataHdr);
611	VBGLR3DECL(int) VbglR3ClipboardReadMetaData(HGCMCLIENTID idClient, PVBOXCLIPBOARDDATAHDR pDataHdr,
612	void pvMeta, uint32_t cbMeta, uint32_t pcbRead);
613	VBGLR3DECL(int) VbglR3ClipboardReadMetaDataEx(HGCMCLIENTID idClient, PVBOXCLIPBOARDDATAHDR pDataHdr,
614	void pvMeta, uint32_t cbMeta, uint32_t pcbRead);
615	VBGLR3DECL(int) VbglR3ClipboardWriteMetaData(HGCMCLIENTID idClient, PVBOXCLIPBOARDDATAHDR pDataHdr,
616	const void pvMeta, uint32_t cbMeta, uint32_t pcbWritten);
617	VBGLR3DECL(int) VbglR3ClipboardWriteMetaDataEx(HGCMCLIENTID idClient, const void pvMeta, uint32_t cbMeta, uint32_t pcbWritten);
618	VBGLR3DECL(int) VbglR3ClipboardReadDir(HGCMCLIENTID idClient, char pszDirname, uint32_t cbDirname, uint32_t pcbDirnameRecv,
619	uint32_t *pfMode);
620	VBGLR3DECL(int) VbglR3ClipboardWriteDir(HGCMCLIENTID idClient, const char *pszPath, uint32_t cbPath, uint32_t fMode);
621	VBGLR3DECL(int) VbglR3ClipboardReadFileHdr(HGCMCLIENTID idClient, char pszFilename, uint32_t cbFilename, uint32_t puFlags,
622	uint32_t pfMode, uint64_t pcbTotal);
623	VBGLR3DECL(int) VbglR3ClipboardWriteFileHdr(HGCMCLIENTID idClient, const char *pszFilename, uint32_t cbFilename,
624	uint32_t fFlags, uint32_t fMode, uint64_t cbTotal);
625	VBGLR3DECL(int) VbglR3ClipboardReadFileData(HGCMCLIENTID idClient, void pvData, uint32_t cbData, uint32_t pcbRead);
626	VBGLR3DECL(int) VbglR3ClipboardWriteFileData(HGCMCLIENTID idClient, void pvData, uint32_t cbData, uint32_t pcbWritten);
627	VBGLR3DECL(int) VbglR3ClipboardSendError(HGCMCLIENTID idClient, int rcErr);
628	# endif /* VBOX_WITH_SHARED_CLIPBOARD_URI_LIST */
629	/** @} */
630	# endif /* VBOX_WITH_SHARED_CLIPBOARD */
631
632	/** @name Seamless mode
633	* @{ */
634	VBGLR3DECL(int) VbglR3SeamlessSetCap(bool fState);
635	VBGLR3DECL(int) VbglR3SeamlessWaitEvent(VMMDevSeamlessMode *pMode);
636	VBGLR3DECL(int) VbglR3SeamlessSendRects(uint32_t cRects, PRTRECT pRects);
637	VBGLR3DECL(int) VbglR3SeamlessGetLastEvent(VMMDevSeamlessMode *pMode);
638
639	/** @} */
640
641	/** @name Mouse
642	* @{ */
643	VBGLR3DECL(int) VbglR3GetMouseStatus(uint32_t pfFeatures, uint32_t px, uint32_t *py);
644	VBGLR3DECL(int) VbglR3SetMouseStatus(uint32_t fFeatures);
645	/** @} */
646
647	/** @name Video
648	* @{ */
649	VBGLR3DECL(int) VbglR3VideoAccelEnable(bool fEnable);
650	VBGLR3DECL(int) VbglR3VideoAccelFlush(void);
651	VBGLR3DECL(int) VbglR3SetPointerShape(uint32_t fFlags, uint32_t xHot, uint32_t yHot, uint32_t cx, uint32_t cy,
652	const void *pvImg, size_t cbImg);
653	VBGLR3DECL(int) VbglR3SetPointerShapeReq(struct VMMDevReqMousePointer *pReq);
654	/** @} */
655
656	/** @name Display
657	* @{ */
658	/** The folder for the video mode hint unix domain socket on Unix-like guests.
659	* @note This can be safely changed as all users are rebuilt in lock-step. */
660	#define VBGLR3HOSTDISPSOCKETPATH "/tmp/.VBoxService"
661	/** The path to the video mode hint unix domain socket on Unix-like guests. */
662	#define VBGLR3HOSTDISPSOCKET VBGLR3VIDEOMODEHINTSOCKETPATH "/VideoModeHint"
663
664	/** The folder for saving video mode hints to between sessions. */
665	#define VBGLR3HOSTDISPSAVEDMODEPATH "/var/lib/VBoxGuestAdditions"
666	/** The path to the file for saving video mode hints to between sessions. */
667	#define VBGLR3HOSTDISPSAVEDMODE VBGLR3HOSTDISPSAVEDMODEPATH "/SavedVideoModes"
668
669	VBGLR3DECL(int) VbglR3GetDisplayChangeRequest(uint32_t pcx, uint32_t pcy, uint32_t pcBits, uint32_t piDisplay,
670	uint32_t pdx, uint32_t pdy, bool pfEnabled, bool pfChangeOrigin, bool fAck);
671	VBGLR3DECL(int) VbglR3GetDisplayChangeRequestMulti(uint32_t cDisplaysIn, uint32_t *pcDisplaysOut,
672	VMMDevDisplayDef *paDisplays, bool fAck);
673	VBGLR3DECL(bool) VbglR3HostLikesVideoMode(uint32_t cx, uint32_t cy, uint32_t cBits);
674	VBGLR3DECL(int) VbglR3VideoModeGetHighestSavedScreen(unsigned *pcScreen);
675	VBGLR3DECL(int) VbglR3SaveVideoMode(unsigned cScreen, unsigned cx, unsigned cy, unsigned cBits,
676	unsigned x, unsigned y, bool fEnabled);
677	VBGLR3DECL(int) VbglR3RetrieveVideoMode(unsigned cScreen, unsigned pcx, unsigned pcy, unsigned *pcBits,
678	unsigned px, unsigned py, bool *pfEnabled);
679	/** @} */
680
681	/** @name VRDP
682	* @{ */
683	VBGLR3DECL(int) VbglR3VrdpGetChangeRequest(bool pfActive, uint32_t puExperienceLevel);
684	/** @} */
685
686	/** @name VM Statistics
687	* @{ */
688	VBGLR3DECL(int) VbglR3StatQueryInterval(uint32_t *pu32Interval);
689	# if defined(VBOX_INCLUDED_VMMDev_h) \|\| defined(DOXYGEN_RUNNING)
690	VBGLR3DECL(int) VbglR3StatReport(VMMDevReportGuestStats *pReq);
691	# endif
692	/** @} */
693
694	/** @name Memory ballooning
695	* @{ */
696	VBGLR3DECL(int) VbglR3MemBalloonRefresh(uint32_t pcChunks, bool pfHandleInR3);
697	VBGLR3DECL(int) VbglR3MemBalloonChange(void *pv, bool fInflate);
698	/** @} */
699
700	/** @name Core Dump
701	* @{ */
702	VBGLR3DECL(int) VbglR3WriteCoreDump(void);
703
704	/** @} */
705
706	# ifdef VBOX_WITH_GUEST_PROPS
707	/** @name Guest properties
708	* @{ */
709	/** @todo Docs. */
710	typedef struct VBGLR3GUESTPROPENUM VBGLR3GUESTPROPENUM;
711	/** @todo Docs. */
712	typedef VBGLR3GUESTPROPENUM *PVBGLR3GUESTPROPENUM;
713	VBGLR3DECL(int) VbglR3GuestPropConnect(uint32_t *pidClient);
714	VBGLR3DECL(int) VbglR3GuestPropDisconnect(HGCMCLIENTID idClient);
715	VBGLR3DECL(int) VbglR3GuestPropWrite(HGCMCLIENTID idClient, const char pszName, const char pszValue, const char *pszFlags);
716	VBGLR3DECL(int) VbglR3GuestPropWriteValue(HGCMCLIENTID idClient, const char pszName, const char pszValue);
717	VBGLR3DECL(int) VbglR3GuestPropWriteValueV(HGCMCLIENTID idClient, const char *pszName,
718	const char *pszValueFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
719	VBGLR3DECL(int) VbglR3GuestPropWriteValueF(HGCMCLIENTID idClient, const char *pszName,
720	const char *pszValueFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
721	VBGLR3DECL(int) VbglR3GuestPropRead(HGCMCLIENTID idClient, const char pszName, void pvBuf, uint32_t cbBuf, char **ppszValue,
722	uint64_t pu64Timestamp, char ppszFlags, uint32_t pcbBufActual);
723	VBGLR3DECL(int) VbglR3GuestPropReadValue(uint32_t ClientId, const char pszName, char pszValue, uint32_t cchValue,
724	uint32_t *pcchValueActual);
725	VBGLR3DECL(int) VbglR3GuestPropReadValueAlloc(HGCMCLIENTID idClient, const char pszName, char *ppszValue);
726	VBGLR3DECL(void) VbglR3GuestPropReadValueFree(char *pszValue);
727	VBGLR3DECL(int) VbglR3GuestPropEnumRaw(HGCMCLIENTID idClient, const char paszPatterns, char pcBuf, uint32_t cbBuf,
728	uint32_t *pcbBufActual);
729	VBGLR3DECL(int) VbglR3GuestPropEnum(HGCMCLIENTID idClient, char const * const *ppaszPatterns, uint32_t cPatterns,
730	PVBGLR3GUESTPROPENUM ppHandle, char const ppszName, char const *ppszValue,
731	uint64_t pu64Timestamp, char const *ppszFlags);
732	VBGLR3DECL(int) VbglR3GuestPropEnumNext(PVBGLR3GUESTPROPENUM pHandle, char const ppszName, char const ppszValue,
733	uint64_t pu64Timestamp, char const *ppszFlags);
734	VBGLR3DECL(void) VbglR3GuestPropEnumFree(PVBGLR3GUESTPROPENUM pHandle);
735	VBGLR3DECL(int) VbglR3GuestPropDelete(HGCMCLIENTID idClient, const char *pszName);
736	VBGLR3DECL(int) VbglR3GuestPropDelSet(HGCMCLIENTID idClient, char const * const *papszPatterns, uint32_t cPatterns);
737	VBGLR3DECL(int) VbglR3GuestPropWait(HGCMCLIENTID idClient, const char pszPatterns, void pvBuf, uint32_t cbBuf,
738	uint64_t u64Timestamp, uint32_t cMillies, char ppszName, char ppszValue,
739	uint64_t pu64Timestamp, char ppszFlags, uint32_t pcbBufActual);
740	/** @} */
741
742	/** @name Guest user handling / reporting.
743	* @{ */
744	VBGLR3DECL(int) VbglR3GuestUserReportState(const char pszUser, const char pszDomain, VBoxGuestUserState enmState,
745	uint8_t *pbDetails, uint32_t cbDetails);
746	/** @} */
747
748	/** @name Host version handling
749	* @{ */
750	VBGLR3DECL(int) VbglR3HostVersionCheckForUpdate(HGCMCLIENTID idClient, bool pfUpdate, char *ppszHostVersion,
751	char **ppszGuestVersion);
752	VBGLR3DECL(int) VbglR3HostVersionLastCheckedLoad(HGCMCLIENTID idClient, char **ppszVer);
753	VBGLR3DECL(int) VbglR3HostVersionLastCheckedStore(HGCMCLIENTID idClient, const char *pszVer);
754	/** @} */
755	# endif /* VBOX_WITH_GUEST_PROPS defined */
756
757	# ifdef VBOX_WITH_SHARED_FOLDERS
758	/** @name Shared folders
759	* @{ */
760	/**
761	* Structure containing mapping information for a shared folder.
762	*/
763	typedef struct VBGLR3SHAREDFOLDERMAPPING
764	{
765	/** Mapping status. */
766	uint32_t u32Status;
767	/** Root handle. */
768	uint32_t u32Root;
769	} VBGLR3SHAREDFOLDERMAPPING;
770	/** Pointer to a shared folder mapping information structure. */
771	typedef VBGLR3SHAREDFOLDERMAPPING *PVBGLR3SHAREDFOLDERMAPPING;
772	/** Pointer to a const shared folder mapping information structure. */
773	typedef VBGLR3SHAREDFOLDERMAPPING const *PCVBGLR3SHAREDFOLDERMAPPING;
774
775	VBGLR3DECL(int) VbglR3SharedFolderConnect(uint32_t *pidClient);
776	VBGLR3DECL(int) VbglR3SharedFolderDisconnect(HGCMCLIENTID idClient);
777	VBGLR3DECL(bool) VbglR3SharedFolderExists(HGCMCLIENTID idClient, const char *pszShareName);
778	VBGLR3DECL(int) VbglR3SharedFolderGetMappings(HGCMCLIENTID idClient, bool fAutoMountOnly,
779	PVBGLR3SHAREDFOLDERMAPPING ppaMappings, uint32_t pcMappings);
780	VBGLR3DECL(void) VbglR3SharedFolderFreeMappings(PVBGLR3SHAREDFOLDERMAPPING paMappings);
781	VBGLR3DECL(int) VbglR3SharedFolderGetName(HGCMCLIENTID idClient,uint32_t u32Root, char ppszName); /< @todo r=bird: GET functions return the value, not a status code!*/
782	VBGLR3DECL(int) VbglR3SharedFolderQueryFolderInfo(HGCMCLIENTID idClient, uint32_t idRoot, uint64_t fQueryFlags,
783	char ppszName, char ppszMountPoint,
784	uint64_t pfFlags, uint32_t puRootIdVersion);
785	VBGLR3DECL(int) VbglR3SharedFolderWaitForMappingsChanges(HGCMCLIENTID idClient, uint32_t uPrevVersion, uint32_t *puCurVersion);
786	VBGLR3DECL(int) VbglR3SharedFolderCancelMappingsChangesWaits(HGCMCLIENTID idClient);
787
788	VBGLR3DECL(int) VbglR3SharedFolderGetMountPrefix(char ppszPrefix); /< @todo r=bird: GET functions return the value, not a status code! */
789	VBGLR3DECL(int) VbglR3SharedFolderGetMountDir(char ppszDir); /< @todo r=bird: GET functions return the value, not a status code! */
790	/** @} */
791	# endif /* VBOX_WITH_SHARED_FOLDERS defined */
792
793	# ifdef VBOX_WITH_GUEST_CONTROL
794	/** @name Guest control
795	* @{ */
796
797	/**
798	* Structure containing the context required for
799	* either retrieving or sending a HGCM guest control
800	* commands from or to the host.
801	*
802	* Note: Do not change parameter order without also
803	* adapting all structure initializers.
804	*/
805	typedef struct VBGLR3GUESTCTRLCMDCTX
806	{
807	/** @todo This struct could be handy if we want to implement
808	* a second communication channel, e.g. via TCP/IP.
809	* Use a union for the HGCM stuff then. */
810
811	/** IN: HGCM client ID to use for communication. */
812	uint32_t uClientID;
813	/** IN/OUT: Context ID to retrieve or to use. */
814	uint32_t uContextID;
815	/** IN: Protocol version to use. */
816	uint32_t uProtocol;
817	/** OUT: Number of parameters retrieved. */
818	uint32_t uNumParms;
819	} VBGLR3GUESTCTRLCMDCTX, *PVBGLR3GUESTCTRLCMDCTX;
820
821	/* General message handling on the guest. */
822	VBGLR3DECL(int) VbglR3GuestCtrlConnect(uint32_t *pidClient);
823	VBGLR3DECL(int) VbglR3GuestCtrlDisconnect(uint32_t idClient);
824	VBGLR3DECL(bool) VbglR3GuestCtrlSupportsOptimizations(uint32_t idClient);
825	VBGLR3DECL(int) VbglR3GuestCtrlMakeMeMaster(uint32_t idClient);
826	VBGLR3DECL(int) VbglR3GuestCtrlReportFeatures(uint32_t idClient, uint64_t fGuestFeatures, uint64_t *pfHostFeatures);
827	VBGLR3DECL(int) VbglR3GuestCtrlQueryFeatures(uint32_t idClient, uint64_t *pfHostFeatures);
828	VBGLR3DECL(int) VbglR3GuestCtrlMsgFilterSet(uint32_t uClientId, uint32_t uValue, uint32_t uMaskAdd, uint32_t uMaskRemove);
829	VBGLR3DECL(int) VbglR3GuestCtrlMsgReply(PVBGLR3GUESTCTRLCMDCTX pCtx, int rc);
830	VBGLR3DECL(int) VbglR3GuestCtrlMsgReplyEx(PVBGLR3GUESTCTRLCMDCTX pCtx, int rc, uint32_t uType,
831	void *pvPayload, uint32_t cbPayload);
832	VBGLR3DECL(int) VbglR3GuestCtrlMsgSkip(uint32_t idClient, int rcSkip, uint32_t idMsg);
833	VBGLR3DECL(int) VbglR3GuestCtrlMsgSkipOld(uint32_t uClientId);
834	VBGLR3DECL(int) VbglR3GuestCtrlMsgPeekWait(uint32_t idClient, uint32_t pidMsg, uint32_t pcParameters, uint64_t *pidRestoreCheck);
835	VBGLR3DECL(int) VbglR3GuestCtrlCancelPendingWaits(HGCMCLIENTID idClient);
836	/* Guest session handling. */
837	VBGLR3DECL(int) VbglR3GuestCtrlSessionPrepare(uint32_t idClient, uint32_t idSession, void const *pvKey, uint32_t cbKey);
838	VBGLR3DECL(int) VbglR3GuestCtrlSessionAccept(uint32_t idClient, uint32_t idSession, void const *pvKey, uint32_t cbKey);
839	VBGLR3DECL(int) VbglR3GuestCtrlSessionCancelPrepared(uint32_t idClient, uint32_t idSession);
840	VBGLR3DECL(int) VbglR3GuestCtrlSessionClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t fFlags);
841	VBGLR3DECL(int) VbglR3GuestCtrlSessionNotify(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uType, int32_t iResult);
842	VBGLR3DECL(int) VbglR3GuestCtrlSessionGetOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puProtocol, char pszUser, uint32_t cbUser,
843	char pszPassword, uint32_t cbPassword, char pszDomain, uint32_t cbDomain,
844	uint32_t pfFlags, uint32_t pidSession);
845	VBGLR3DECL(int) VbglR3GuestCtrlSessionGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t pfFlags, uint32_t pidSession);
846	/* Guest path handling. */
847	VBGLR3DECL(int) VbglR3GuestCtrlPathGetRename(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszSource, uint32_t cbSource, char pszDest,
848	uint32_t cbDest, uint32_t *pfFlags);
849	VBGLR3DECL(int) VbglR3GuestCtrlPathGetUserDocuments(PVBGLR3GUESTCTRLCMDCTX pCtx);
850	VBGLR3DECL(int) VbglR3GuestCtrlPathGetUserHome(PVBGLR3GUESTCTRLCMDCTX pCtx);
851	/* Guest process execution. */
852	VBGLR3DECL(int) VbglR3GuestCtrlProcGetStart(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszCmd, uint32_t cbCmd, uint32_t pfFlags,
853	char pszArgs, uint32_t cbArgs, uint32_t puNumArgs, char pszEnv, uint32_t pcbEnv,
854	uint32_t puNumEnvVars, char pszUser, uint32_t cbUser, char *pszPassword,
855	uint32_t cbPassword, uint32_t puTimeoutMS, uint32_t puPriority,
856	uint64_t puAffinity, uint32_t cbAffinity, uint32_t pcAffinity);
857	VBGLR3DECL(int) VbglR3GuestCtrlProcGetTerminate(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puPID);
858	VBGLR3DECL(int) VbglR3GuestCtrlProcGetInput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puPID, uint32_t pfFlags, void *pvData,
859	uint32_t cbData, uint32_t *pcbSize);
860	VBGLR3DECL(int) VbglR3GuestCtrlProcGetOutput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puPID, uint32_t puHandle, uint32_t *pfFlags);
861	VBGLR3DECL(int) VbglR3GuestCtrlProcGetWaitFor(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puPID, uint32_t puWaitFlags,
862	uint32_t *puTimeoutMS);
863	/* Guest native directory handling. */
864	VBGLR3DECL(int) VbglR3GuestCtrlDirGetRemove(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszPath, uint32_t cbPath, uint32_t pfFlags);
865	/* Guest native file handling. */
866	VBGLR3DECL(int) VbglR3GuestCtrlFileGetOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, char pszFileName, uint32_t cbFileName, char pszOpenMode,
867	uint32_t cbOpenMode, char pszDisposition, uint32_t cbDisposition, char pszSharing,
868	uint32_t cbSharing, uint32_t puCreationMode, uint64_t puOffset);
869	VBGLR3DECL(int) VbglR3GuestCtrlFileGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
870	VBGLR3DECL(int) VbglR3GuestCtrlFileGetRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puHandle, uint32_t puToRead);
871	VBGLR3DECL(int) VbglR3GuestCtrlFileGetReadAt(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle,
872	uint32_t puToRead, uint64_t poffRead);
873	VBGLR3DECL(int) VbglR3GuestCtrlFileGetWrite(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle,
874	void pvData, uint32_t cbData, uint32_t pcbActual);
875	VBGLR3DECL(int) VbglR3GuestCtrlFileGetWriteAt(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puHandle, void pvData, uint32_t cbData,
876	uint32_t pcbActual, uint64_t poffWrite);
877	VBGLR3DECL(int) VbglR3GuestCtrlFileGetSeek(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle,
878	uint32_t puSeekMethod, uint64_t poffSeek);
879	VBGLR3DECL(int) VbglR3GuestCtrlFileGetTell(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
880	VBGLR3DECL(int) VbglR3GuestCtrlFileGetSetSize(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t puHandle, uint64_t pcbNew);
881
882	/* Guest -> Host. */
883	VBGLR3DECL(int) VbglR3GuestCtrlFileCbOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t uFileHandle);
884	VBGLR3DECL(int) VbglR3GuestCtrlFileCbClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
885	VBGLR3DECL(int) VbglR3GuestCtrlFileCbError(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
886	VBGLR3DECL(int) VbglR3GuestCtrlFileCbRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, void *pvData, uint32_t cbData);
887	VBGLR3DECL(int) VbglR3GuestCtrlFileCbReadOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc,
888	void *pvData, uint32_t cbData, int64_t offNew);
889	VBGLR3DECL(int) VbglR3GuestCtrlFileCbWrite(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cbWritten);
890	VBGLR3DECL(int) VbglR3GuestCtrlFileCbWriteOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cbWritten, int64_t offNew);
891
892	VBGLR3DECL(int) VbglR3GuestCtrlFileCbSeek(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t offCurrent);
893	VBGLR3DECL(int) VbglR3GuestCtrlFileCbTell(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t offCurrent);
894	VBGLR3DECL(int) VbglR3GuestCtrlFileCbSetSize(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t cbNew);
895	VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatus(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uStatus, uint32_t fFlags,
896	void *pvData, uint32_t cbData);
897	VBGLR3DECL(int) VbglR3GuestCtrlProcCbOutput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uHandle, uint32_t fFlags,
898	void *pvData, uint32_t cbData);
899	VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatusInput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t u32PID, uint32_t uStatus,
900	uint32_t fFlags, uint32_t cbWritten);
901
902	/** @} */
903	# endif /* VBOX_WITH_GUEST_CONTROL defined */
904
905	/** @name Auto-logon handling
906	* @{ */
907	VBGLR3DECL(int) VbglR3AutoLogonReportStatus(VBoxGuestFacilityStatus enmStatus);
908	VBGLR3DECL(bool) VbglR3AutoLogonIsRemoteSession(void);
909	/** @} */
910
911	/** @name User credentials handling
912	* @{ */
913	VBGLR3DECL(int) VbglR3CredentialsQueryAvailability(void);
914	VBGLR3DECL(int) VbglR3CredentialsRetrieve(char ppszUser, char ppszPassword, char **ppszDomain);
915	VBGLR3DECL(int) VbglR3CredentialsRetrieveUtf16(PRTUTF16 ppwszUser, PRTUTF16 ppwszPassword, PRTUTF16 *ppwszDomain);
916	VBGLR3DECL(void) VbglR3CredentialsDestroy(char pszUser, char pszPassword, char *pszDomain, uint32_t cPasses);
917	VBGLR3DECL(void) VbglR3CredentialsDestroyUtf16(PRTUTF16 pwszUser, PRTUTF16 pwszPassword, PRTUTF16 pwszDomain,
918	uint32_t cPasses);
919	/** @} */
920
921	/** @name CPU hotplug monitor
922	* @{ */
923	VBGLR3DECL(int) VbglR3CpuHotPlugInit(void);
924	VBGLR3DECL(int) VbglR3CpuHotPlugTerm(void);
925	VBGLR3DECL(int) VbglR3CpuHotPlugWaitForEvent(VMMDevCpuEventType penmEventType, uint32_t pidCpuCore, uint32_t *pidCpuPackage);
926	/** @} */
927
928	/** @name Page sharing
929	* @{ */
930	struct VMMDEVSHAREDREGIONDESC;
931	VBGLR3DECL(int) VbglR3RegisterSharedModule(char pszModuleName, char pszVersion, RTGCPTR64 GCBaseAddr, uint32_t cbModule,
932	unsigned cRegions, struct VMMDEVSHAREDREGIONDESC *pRegions);
933	VBGLR3DECL(int) VbglR3UnregisterSharedModule(char pszModuleName, char pszVersion, RTGCPTR64 GCBaseAddr, uint32_t cbModule);
934	VBGLR3DECL(int) VbglR3CheckSharedModules(void);
935	VBGLR3DECL(bool) VbglR3PageSharingIsEnabled(void);
936	VBGLR3DECL(int) VbglR3PageIsShared(RTGCPTR pPage, bool pfShared, uint64_t puPageFlags);
937	/** @} */
938
939	# ifdef VBOX_WITH_DRAG_AND_DROP
940	/** @name Drag and Drop
941	* @{ */
942	/**
943	* Structure containing the context required for
944	* either retrieving or sending a HGCM guest drag'n drop
945	* commands from or to the host.
946	*
947	* Note: Do not change parameter order without also
948	* adapting all structure initializers.
949	*/
950	typedef struct VBGLR3GUESTDNDCMDCTX
951	{
952	/** @todo This struct could be handy if we want to implement
953	* a second communication channel, e.g. via TCP/IP.
954	* Use a union for the HGCM stuff then. */
955
956	/** HGCM client ID to use for communication. */
957	uint32_t uClientID;
958	/** The VM's current session ID. */
959	uint64_t uSessionID;
960	/** Protocol version to use. */
961	uint32_t uProtocol;
962	/** Number of parameters retrieved for the current command. */
963	uint32_t uNumParms;
964	/** Max chunk size (in bytes) for data transfers. */
965	uint32_t cbMaxChunkSize;
966	} VBGLR3GUESTDNDCMDCTX, *PVBGLR3GUESTDNDCMDCTX;
967
968	/**
969	* Enumeration for specifying the DnD meta data type.
970	*/
971	typedef enum VBGLR3GUESTDNDMETADATATYPE
972	{
973	/** Unknown meta data type; don't use. */
974	VBGLR3GUESTDNDMETADATATYPE_UNKNOWN = 0,
975	/** Raw meta data; can be everything. */
976	VBGLR3GUESTDNDMETADATATYPE_RAW,
977	/** Meta data is an URI list, specifying objects. */
978	VBGLR3GUESTDNDMETADATATYPE_URI_LIST,
979	/** Blow the type up to 32-bit. */
980	VBGLR3GUESTDNDMETADATATYPE_32BIT_HACK = 0x7fffffff
981	} VBGLR3GUESTDNDMETADATATYPE;
982
983	/**
984	* Structure for keeping + handling DnD meta data.
985	*
986	* Note: Don't treat this struct as POD object, as the union has classes in it.
987	*/
988	typedef struct VBGLR3GUESTDNDMETADATA
989	{
990	/** The meta data type the union contains. */
991	VBGLR3GUESTDNDMETADATATYPE enmType;
992	/** Pointer to actual meta data. */
993	void *pvMeta;
994	/** Size (in bytes) of meta data. */
995	uint32_t cbMeta;
996	} VBGLR3GUESTDNDMETADATA;
997
998	/** Pointer to VBGLR3GUESTDNDMETADATA. */
999	typedef VBGLR3GUESTDNDMETADATA *PVBGLR3GUESTDNDMETADATA;
1000
1001	/** Const pointer to VBGLR3GUESTDNDMETADATA. */
1002	typedef const PVBGLR3GUESTDNDMETADATA CPVBGLR3GUESTDNDMETADATA;
1003
1004	/**
1005	* Enumeration specifying a DnD event type.
1006	*/
1007	typedef enum VBGLR3DNDEVENTTYPE
1008	{
1009	VBGLR3DNDEVENTTYPE_INVALID = 0,
1010	VBGLR3DNDEVENTTYPE_HG_ERROR = 1,
1011	VBGLR3DNDEVENTTYPE_HG_ENTER = 2,
1012	VBGLR3DNDEVENTTYPE_HG_MOVE = 3,
1013	VBGLR3DNDEVENTTYPE_HG_LEAVE = 4,
1014	VBGLR3DNDEVENTTYPE_HG_DROP = 5,
1015	VBGLR3DNDEVENTTYPE_HG_RECEIVE = 6,
1016	VBGLR3DNDEVENTTYPE_HG_CANCEL = 7,
1017	# ifdef VBOX_WITH_DRAG_AND_DROP_GH
1018	VBGLR3DNDEVENTTYPE_GH_ERROR = 100,
1019	VBGLR3DNDEVENTTYPE_GH_REQ_PENDING = 101,
1020	VBGLR3DNDEVENTTYPE_GH_DROP = 102,
1021	# endif
1022	/** Blow the type up to 32-bit. */
1023	VBGLR3DNDEVENTTYPE_32BIT_HACK = 0x7fffffff
1024	} VBGLR3DNDEVENTTYPE;
1025
1026	typedef struct VBGLR3DNDEVENT
1027	{
1028	/** The event type the union contains. */
1029	VBGLR3DNDEVENTTYPE enmType;
1030	union
1031	{
1032	struct
1033	{
1034	/** Screen ID this request belongs to. */
1035	uint32_t uScreenID;
1036	/** Format list (UTF-8, \r\n separated). */
1037	char *pszFormats;
1038	/** Size (in bytes) of pszFormats (\0 included). */
1039	uint32_t cbFormats;
1040	/** List of allowed DnD actions. */
1041	VBOXDNDACTIONLIST dndLstActionsAllowed;
1042	} HG_Enter;
1043	struct
1044	{
1045	/** Absolute X position of guest screen. */
1046	uint32_t uXpos;
1047	/** Absolute Y position of guest screen. */
1048	uint32_t uYpos;
1049	/** Default DnD action. */
1050	VBOXDNDACTION dndActionDefault;
1051	} HG_Move;
1052	struct
1053	{
1054	/** Absolute X position of guest screen. */
1055	uint32_t uXpos;
1056	/** Absolute Y position of guest screen. */
1057	uint32_t uYpos;
1058	/** Default DnD action. */
1059	VBOXDNDACTION dndActionDefault;
1060	} HG_Drop;
1061	struct
1062	{
1063	/** Meta data for the operation. */
1064	VBGLR3GUESTDNDMETADATA Meta;
1065	} HG_Received;
1066	struct
1067	{
1068	/** IPRT-style error code. */
1069	int rc;
1070	} HG_Error;
1071	# ifdef VBOX_WITH_DRAG_AND_DROP_GH
1072	struct
1073	{
1074	/** Screen ID this request belongs to. */
1075	uint32_t uScreenID;
1076	} GH_IsPending;
1077	struct
1078	{
1079	/** Requested format by the host. */
1080	char *pszFormat;
1081	/** Size (in bytes) of pszFormat (\0 included). */
1082	uint32_t cbFormat;
1083	/** Requested DnD action. */
1084	VBOXDNDACTION dndActionRequested;
1085	} GH_Drop;
1086	# endif
1087	} u;
1088	} VBGLR3DNDEVENT;
1089	typedef VBGLR3DNDEVENT *PVBGLR3DNDEVENT;
1090	typedef const PVBGLR3DNDEVENT CPVBGLR3DNDEVENT;
1091
1092	VBGLR3DECL(int) VbglR3DnDConnect(PVBGLR3GUESTDNDCMDCTX pCtx);
1093	VBGLR3DECL(int) VbglR3DnDDisconnect(PVBGLR3GUESTDNDCMDCTX pCtx);
1094
1095	VBGLR3DECL(int) VbglR3DnDEventGetNext(PVBGLR3GUESTDNDCMDCTX pCtx, PVBGLR3DNDEVENT *ppEvent);
1096	VBGLR3DECL(void) VbglR3DnDEventFree(PVBGLR3DNDEVENT pEvent);
1097
1098	VBGLR3DECL(int) VbglR3DnDHGSendAckOp(PVBGLR3GUESTDNDCMDCTX pCtx, VBOXDNDACTION dndAction);
1099	VBGLR3DECL(int) VbglR3DnDHGSendReqData(PVBGLR3GUESTDNDCMDCTX pCtx, const char *pcszFormat);
1100	VBGLR3DECL(int) VbglR3DnDHGSendProgress(PVBGLR3GUESTDNDCMDCTX pCtx, uint32_t uStatus, uint8_t uPercent, int rcErr);
1101	# ifdef VBOX_WITH_DRAG_AND_DROP_GH
1102	VBGLR3DECL(int) VbglR3DnDGHSendAckPending(PVBGLR3GUESTDNDCMDCTX pCtx, VBOXDNDACTION dndActionDefault, VBOXDNDACTIONLIST dndLstActionsAllowed, const char* pcszFormats, uint32_t cbFormats);
1103	VBGLR3DECL(int) VbglR3DnDGHSendData(PVBGLR3GUESTDNDCMDCTX pCtx, const char pszFormat, void pvData, uint32_t cbData);
1104	VBGLR3DECL(int) VbglR3DnDGHSendError(PVBGLR3GUESTDNDCMDCTX pCtx, int rcOp);
1105	# endif /* VBOX_WITH_DRAG_AND_DROP_GH */
1106	/** @} */
1107	# endif /* VBOX_WITH_DRAG_AND_DROP */
1108
1109	/* Generic Host Channel Service. */
1110	VBGLR3DECL(int) VbglR3HostChannelInit(uint32_t *pidClient);
1111	VBGLR3DECL(void) VbglR3HostChannelTerm(uint32_t idClient);
1112	VBGLR3DECL(int) VbglR3HostChannelAttach(uint32_t *pu32ChannelHandle, uint32_t u32HGCMClientId,
1113	const char *pszName, uint32_t u32Flags);
1114	VBGLR3DECL(void) VbglR3HostChannelDetach(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId);
1115	VBGLR3DECL(int) VbglR3HostChannelSend(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId,
1116	void *pvData, uint32_t cbData);
1117	VBGLR3DECL(int) VbglR3HostChannelRecv(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId,
1118	void *pvData, uint32_t cbData,
1119	uint32_t pu32SizeReceived, uint32_t pu32SizeRemaining);
1120	VBGLR3DECL(int) VbglR3HostChannelControl(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId,
1121	uint32_t u32Code, void *pvParm, uint32_t cbParm,
1122	void pvData, uint32_t cbData, uint32_t pu32SizeDataReturned);
1123	VBGLR3DECL(int) VbglR3HostChannelEventWait(uint32_t *pu32ChannelHandle, uint32_t u32HGCMClientId,
1124	uint32_t pu32EventId, void pvParm, uint32_t cbParm,
1125	uint32_t *pu32SizeReturned);
1126	VBGLR3DECL(int) VbglR3HostChannelEventCancel(uint32_t u32ChannelHandle, uint32_t u32HGCMClientId);
1127	VBGLR3DECL(int) VbglR3HostChannelQuery(const char *pszName, uint32_t u32HGCMClientId, uint32_t u32Code,
1128	void pvParm, uint32_t cbParm, void pvData, uint32_t cbData,
1129	uint32_t *pu32SizeDataReturned);
1130
1131	/** @name Mode hint storage
1132	* @{ */
1133	VBGLR3DECL(int) VbglR3ReadVideoMode(unsigned cDisplay, unsigned *cx,
1134	unsigned cy, unsigned cBPP, unsigned *x,
1135	unsigned y, unsigned fEnabled);
1136	VBGLR3DECL(int) VbglR3WriteVideoMode(unsigned cDisplay, unsigned cx,
1137	unsigned cy, unsigned cBPP, unsigned x,
1138	unsigned y, unsigned fEnabled);
1139	/** @} */
1140
1141	/** @name Generic HGCM
1142	* @{ */
1143	VBGLR3DECL(int) VbglR3HGCMConnect(const char pszServiceName, HGCMCLIENTID pidClient);
1144	VBGLR3DECL(int) VbglR3HGCMDisconnect(HGCMCLIENTID idClient);
1145	struct VBGLIOCHGCMCALL;
1146	VBGLR3DECL(int) VbglR3HGCMCall(struct VBGLIOCHGCMCALL *pInfo, size_t cbInfo);
1147	/** @} */
1148
1149	#endif /* IN_RING3 */
1150	/** @} */
1151
1152	RT_C_DECLS_END
1153
1154	/** @} */
1155
1156	#endif /* !VBOX_INCLUDED_VBoxGuestLib_h */
1157

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

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

Download in other formats: