ExtPack.h@ 77807

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago
*: scm --fix-header-guard-endif
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 25.8 KB

Line
1	/** @file
2	* VirtualBox - Extension Pack Interface.
3	*/
4
5	/*
6	* Copyright (C) 2010-2019 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef VBOX_INCLUDED_ExtPack_ExtPack_h
27	#define VBOX_INCLUDED_ExtPack_ExtPack_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <VBox/types.h>
33
34	/** @def VBOXEXTPACK_IF_CS
35	* Selects 'class' on 'struct' for interface references.
36	* @param I The interface name
37	*/
38	#if defined(__cplusplus) && !defined(RT_OS_WINDOWS)
39	# define VBOXEXTPACK_IF_CS(I) class I
40	#else
41	# define VBOXEXTPACK_IF_CS(I) struct I
42	#endif
43
44	VBOXEXTPACK_IF_CS(IUnknown);
45	VBOXEXTPACK_IF_CS(IConsole);
46	VBOXEXTPACK_IF_CS(IMachine);
47	VBOXEXTPACK_IF_CS(IVirtualBox);
48	VBOXEXTPACK_IF_CS(IProgress);
49
50	/**
51	* Module kind for use with VBOXEXTPACKHLP::pfnFindModule.
52	*/
53	typedef enum VBOXEXTPACKMODKIND
54	{
55	/** Zero is invalid as always. */
56	VBOXEXTPACKMODKIND_INVALID = 0,
57	/** Raw-mode context module. */
58	VBOXEXTPACKMODKIND_RC,
59	/** Ring-0 context module. */
60	VBOXEXTPACKMODKIND_R0,
61	/** Ring-3 context module. */
62	VBOXEXTPACKMODKIND_R3,
63	/** End of the valid values (exclusive). */
64	VBOXEXTPACKMODKIND_END,
65	/** The usual 32-bit type hack. */
66	VBOXEXTPACKMODKIND_32BIT_HACK = 0x7fffffff
67	} VBOXEXTPACKMODKIND;
68
69	/**
70	* Contexts returned by VBOXEXTPACKHLP::pfnGetContext.
71	*/
72	typedef enum VBOXEXTPACKCTX
73	{
74	/** Zero is invalid as always. */
75	VBOXEXTPACKCTX_INVALID = 0,
76	/** The per-user daemon process (VBoxSVC). */
77	VBOXEXTPACKCTX_PER_USER_DAEMON,
78	/** A VM process. */
79	VBOXEXTPACKCTX_VM_PROCESS,
80	/** An API client process.
81	* @remarks This will not be returned by VirtualBox yet. */
82	VBOXEXTPACKCTX_CLIENT_PROCESS,
83	/** End of the valid values (exclusive). */
84	VBOXEXTPACKCTX_END,
85	/** The usual 32-bit type hack. */
86	VBOXEXTPACKCTX_32BIT_HACK = 0x7fffffff
87	} VBOXEXTPACKCTX;
88
89
90	/** Pointer to const helpers passed to the VBoxExtPackRegister() call. */
91	typedef const struct VBOXEXTPACKHLP *PCVBOXEXTPACKHLP;
92	/**
93	* Extension pack helpers passed to VBoxExtPackRegister().
94	*
95	* This will be valid until the module is unloaded.
96	*/
97	typedef struct VBOXEXTPACKHLP
98	{
99	/** Interface version.
100	* This is set to VBOXEXTPACKHLP_VERSION. */
101	uint32_t u32Version;
102
103	/** The VirtualBox full version (see VBOX_FULL_VERSION). */
104	uint32_t uVBoxFullVersion;
105	/** The VirtualBox subversion tree revision. */
106	uint32_t uVBoxInternalRevision;
107	/** Explicit alignment padding, must be zero. */
108	uint32_t u32Padding;
109	/** Pointer to the version string (read-only). */
110	const char *pszVBoxVersion;
111
112	/**
113	* Finds a module belonging to this extension pack.
114	*
115	* @returns VBox status code.
116	* @param pHlp Pointer to this helper structure.
117	* @param pszName The module base name.
118	* @param pszExt The extension. If NULL the default ring-3
119	* library extension will be used.
120	* @param enmKind The kind of module to locate.
121	* @param pszFound Where to return the path to the module on
122	* success.
123	* @param cbFound The size of the buffer @a pszFound points to.
124	* @param pfNative Where to return the native/agnostic indicator.
125	*/
126	DECLR3CALLBACKMEMBER(int, pfnFindModule,(PCVBOXEXTPACKHLP pHlp, const char pszName, const char pszExt,
127	VBOXEXTPACKMODKIND enmKind,
128	char pszFound, size_t cbFound, bool pfNative));
129
130	/**
131	* Gets the path to a file belonging to this extension pack.
132	*
133	* @returns VBox status code.
134	* @retval VERR_INVALID_POINTER if any of the pointers are invalid.
135	* @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer
136	* will contain nothing.
137	*
138	* @param pHlp Pointer to this helper structure.
139	* @param pszFilename The filename.
140	* @param pszPath Where to return the path to the file on
141	* success.
142	* @param cbPath The size of the buffer @a pszPath.
143	*/
144	DECLR3CALLBACKMEMBER(int, pfnGetFilePath,(PCVBOXEXTPACKHLP pHlp, const char pszFilename, char pszPath, size_t cbPath));
145
146	/**
147	* Gets the context the extension pack is operating in.
148	*
149	* @returns The context.
150	* @retval VBOXEXTPACKCTX_INVALID if @a pHlp is invalid.
151	*
152	* @param pHlp Pointer to this helper structure.
153	*/
154	DECLR3CALLBACKMEMBER(VBOXEXTPACKCTX, pfnGetContext,(PCVBOXEXTPACKHLP pHlp));
155
156	/**
157	* Loads a HGCM service provided by an extension pack.
158	*
159	* @returns VBox status code.
160	* @param pHlp Pointer to this helper structure.
161	* @param pConsole Pointer to the VM's console object.
162	* @param pszServiceLibrary Name of the library file containing the
163	* service implementation, without extension.
164	* @param pszServiceName Name of HGCM service.
165	*/
166	DECLR3CALLBACKMEMBER(int, pfnLoadHGCMService,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IConsole) *pConsole,
167	const char pszServiceLibrary, const char pszServiceName));
168
169	/**
170	* Loads a VD plugin provided by an extension pack.
171	*
172	* This makes sense only in the context of the per-user service (VBoxSVC).
173	*
174	* @returns VBox status code.
175	* @param pHlp Pointer to this helper structure.
176	* @param pVirtualBox Pointer to the VirtualBox object.
177	* @param pszPluginLibrary Name of the library file containing the plugin
178	* implementation, without extension.
179	*/
180	DECLR3CALLBACKMEMBER(int, pfnLoadVDPlugin,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
181	const char *pszPluginLibrary));
182
183	/**
184	* Unloads a VD plugin provided by an extension pack.
185	*
186	* This makes sense only in the context of the per-user service (VBoxSVC).
187	*
188	* @returns VBox status code.
189	* @param pHlp Pointer to this helper structure.
190	* @param pVirtualBox Pointer to the VirtualBox object.
191	* @param pszPluginLibrary Name of the library file containing the plugin
192	* implementation, without extension.
193	*/
194	DECLR3CALLBACKMEMBER(int, pfnUnloadVDPlugin,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
195	const char *pszPluginLibrary));
196
197	/**
198	* Creates an IProgress object instance for a long running extension
199	* pack provided API operation which is executed asynchronously.
200	*
201	* This implicitly creates a cancellable progress object, since anything
202	* else is user unfriendly. You need to design your code to handle
203	* cancellation with reasonable response time.
204	*
205	* @returns COM status code.
206	* @param pHlp Pointer to this helper structure.
207	* @param pInitiator Pointer to the initiating object.
208	* @param pcszDescription Description of the overall task.
209	* @param cOperations Number of operations for this task.
210	* @param uTotalOperationsWeight Overall weight for the entire task.
211	* @param pcszFirstOperationDescription Description of the first operation.
212	* @param uFirstOperationWeight Weight for the first operation.
213	* @param ppProgressOut Output parameter for the IProgress object reference.
214	*/
215	DECLR3CALLBACKMEMBER(uint32_t, pfnCreateProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IUnknown) *pInitiator,
216	const char *pcszDescription, uint32_t cOperations,
217	uint32_t uTotalOperationsWeight, const char *pcszFirstOperationDescription,
218	uint32_t uFirstOperationWeight, VBOXEXTPACK_IF_CS(IProgress) **ppProgressOut));
219
220	/**
221	* Checks if the Progress object is marked as canceled.
222	*
223	* @returns COM status code.
224	* @param pHlp Pointer to this helper structure.
225	* @param pProgress Pointer to the IProgress object reference returned
226	* by pfnCreateProgress.
227	* @param pfCanceled @c true if canceled, @c false otherwise.
228	*/
229	DECLR3CALLBACKMEMBER(uint32_t, pfnGetCanceledProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
230	bool *pfCanceled));
231
232	/**
233	* Updates the percentage value of the current operation of the
234	* Progress object.
235	*
236	* @returns COM status code.
237	* @param pHlp Pointer to this helper structure.
238	* @param pProgress Pointer to the IProgress object reference returned
239	* by pfnCreateProgress.
240	* @param uPercent Result of the overall task.
241	*/
242	DECLR3CALLBACKMEMBER(uint32_t, pfnUpdateProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
243	uint32_t uPercent));
244
245	/**
246	* Signals that the current operation is successfully completed and
247	* advances to the next operation. The operation percentage is reset
248	* to 0.
249	*
250	* If the operation count is exceeded this returns an error.
251	*
252	* @returns COM status code.
253	* @param pHlp Pointer to this helper structure.
254	* @param pProgress Pointer to the IProgress object reference returned
255	* by pfnCreateProgress.
256	* @param pcszNextOperationDescription Description of the next operation.
257	* @param uNextOperationWeight Weight for the next operation.
258	*/
259	DECLR3CALLBACKMEMBER(uint32_t, pfnNextOperationProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
260	const char *pcszNextOperationDescription,
261	uint32_t uNextOperationWeight));
262
263	/**
264	* Waits until the other task is completed (including all sub-operations)
265	* and forward all changes from the other progress to this progress. This
266	* means sub-operation number, description, percent and so on.
267	*
268	* The caller is responsible for having at least the same count of
269	* sub-operations in this progress object as there are in the other
270	* progress object.
271	*
272	* If the other progress object supports cancel and this object gets any
273	* cancel request (when here enabled as well), it will be forwarded to
274	* the other progress object.
275	*
276	* Error information is automatically preserved (by transferring it to
277	* the current thread's error information). If the caller wants to set it
278	* as the completion state of this progress it needs to be done separately.
279	*
280	* @returns COM status code.
281	* @param pHlp Pointer to this helper structure.
282	* @param pProgress Pointer to the IProgress object reference returned
283	* by pfnCreateProgress.
284	* @param pProgressOther Pointer to an IProgress object reference, the one
285	* to be waited for.
286	* @param cTimeoutMS Timeout in milliseconds, 0 for indefinite wait.
287	*/
288	DECLR3CALLBACKMEMBER(uint32_t, pfnWaitOtherProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
289	VBOXEXTPACK_IF_CS(IProgress) *pProgressOther,
290	uint32_t cTimeoutMS));
291
292	/**
293	* Marks the whole task as complete and sets the result code.
294	*
295	* If the result code indicates a failure then this method will store
296	* the currently set COM error info from the current thread in the
297	* the errorInfo attribute of this Progress object instance. If there
298	* is no error information available then an error is returned.
299	*
300	* If the result code indicates success then the task is terminated,
301	* without paying attention to the current operation being the last.
302	*
303	* Note that this must be called only once for the given Progress
304	* object. Subsequent calls will return errors.
305	*
306	* @returns COM status code.
307	* @param pHlp Pointer to this helper structure.
308	* @param pProgress Pointer to the IProgress object reference returned
309	* by pfnCreateProgress.
310	* @param uResultCode Result of the overall task.
311	*/
312	DECLR3CALLBACKMEMBER(uint32_t, pfnCompleteProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
313	uint32_t uResultCode));
314
315	DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKHLP pHlp)); /*< Reserved for minor structure revisions. /
316	DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKHLP pHlp)); /*< Reserved for minor structure revisions. /
317	DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKHLP pHlp)); /*< Reserved for minor structure revisions. /
318	DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKHLP pHlp)); /*< Reserved for minor structure revisions. /
319	DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKHLP pHlp)); /*< Reserved for minor structure revisions. /
320	DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKHLP pHlp)); /*< Reserved for minor structure revisions. /
321
322	/** End of structure marker (VBOXEXTPACKHLP_VERSION). */
323	uint32_t u32EndMarker;
324	} VBOXEXTPACKHLP;
325	/** Current version of the VBOXEXTPACKHLP structure. */
326	#define VBOXEXTPACKHLP_VERSION RT_MAKE_U32(3, 0)
327
328
329	/** Pointer to the extension pack callback table. */
330	typedef struct VBOXEXTPACKREG const *PCVBOXEXTPACKREG;
331	/**
332	* Callback table returned by VBoxExtPackRegister.
333	*
334	* All the callbacks are called the context of the per-user service (VBoxSVC).
335	*
336	* This must be valid until the extension pack main module is unloaded.
337	*/
338	typedef struct VBOXEXTPACKREG
339	{
340	/** Interface version.
341	* This is set to VBOXEXTPACKREG_VERSION. */
342	uint32_t u32Version;
343	/** The VirtualBox version this extension pack was built against. */
344	uint32_t uVBoxVersion;
345
346	/**
347	* Hook for doing setups after the extension pack was installed.
348	*
349	* @returns VBox status code.
350	* @retval VERR_EXTPACK_UNSUPPORTED_HOST_UNINSTALL if the extension pack
351	* requires some different host version or a prerequisite is
352	* missing from the host. Automatic uninstall will be attempted.
353	* Must set error info.
354	*
355	* @param pThis Pointer to this structure.
356	* @param pVirtualBox The VirtualBox interface.
357	* @param pErrInfo Where to return extended error information.
358	*/
359	DECLCALLBACKMEMBER(int, pfnInstalled)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
360	PRTERRINFO pErrInfo);
361
362	/**
363	* Hook for cleaning up before the extension pack is uninstalled.
364	*
365	* @returns VBox status code.
366	* @param pThis Pointer to this structure.
367	* @param pVirtualBox The VirtualBox interface.
368	*
369	* @todo This is currently called holding locks making pVirtualBox
370	* relatively unusable.
371	*/
372	DECLCALLBACKMEMBER(int, pfnUninstall)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox);
373
374	/**
375	* Hook for doing work after the VirtualBox object is ready.
376	*
377	* @param pThis Pointer to this structure.
378	* @param pVirtualBox The VirtualBox interface.
379	*/
380	DECLCALLBACKMEMBER(void, pfnVirtualBoxReady)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox);
381
382	/**
383	* Hook for doing work before unloading.
384	*
385	* @param pThis Pointer to this structure.
386	*
387	* @remarks The helpers are not available at this point in time.
388	* @remarks This is not called on uninstall, then pfnUninstall will be the
389	* last callback.
390	*/
391	DECLCALLBACKMEMBER(void, pfnUnload)(PCVBOXEXTPACKREG pThis);
392
393	/**
394	* Hook for changing the default VM configuration upon creation.
395	*
396	* @returns VBox status code.
397	* @param pThis Pointer to this structure.
398	* @param pVirtualBox The VirtualBox interface.
399	* @param pMachine The machine interface.
400	*/
401	DECLCALLBACKMEMBER(int, pfnVMCreated)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
402	VBOXEXTPACK_IF_CS(IMachine) *pMachine);
403
404	/**
405	* Query the IUnknown interface to an object in the main module.
406	*
407	* @returns IUnknown pointer (referenced) on success, NULL on failure.
408	* @param pThis Pointer to this structure.
409	* @param pObjectId Pointer to the object ID (UUID).
410	*/
411	DECLCALLBACKMEMBER(void *, pfnQueryObject)(PCVBOXEXTPACKREG pThis, PCRTUUID pObjectId);
412
413	DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKREG pThis)); /*< Reserved for minor structure revisions. /
414	DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKREG pThis)); /*< Reserved for minor structure revisions. /
415	DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKREG pThis)); /*< Reserved for minor structure revisions. /
416	DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKREG pThis)); /*< Reserved for minor structure revisions. /
417	DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKREG pThis)); /*< Reserved for minor structure revisions. /
418	DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKREG pThis)); /*< Reserved for minor structure revisions. /
419
420	/** Reserved for minor structure revisions. */
421	uint32_t uReserved7;
422
423	/** End of structure marker (VBOXEXTPACKREG_VERSION). */
424	uint32_t u32EndMarker;
425	} VBOXEXTPACKREG;
426	/** Current version of the VBOXEXTPACKREG structure. */
427	#define VBOXEXTPACKREG_VERSION RT_MAKE_U32(2, 0)
428
429
430	/**
431	* The VBoxExtPackRegister callback function.
432	*
433	* The Main API (as in VBoxSVC) will invoke this function after loading an
434	* extension pack Main module. Its job is to do version compatibility checking
435	* and returning the extension pack registration structure.
436	*
437	* @returns VBox status code.
438	* @param pHlp Pointer to the extension pack helper function
439	* table. This is valid until the module is unloaded.
440	* @param ppReg Where to return the pointer to the registration
441	* structure containing all the hooks. This structure
442	* be valid and unchanged until the module is unloaded
443	* (i.e. use some static const data for it).
444	* @param pErrInfo Where to return extended error information.
445	*/
446	typedef DECLCALLBACK(int) FNVBOXEXTPACKREGISTER(PCVBOXEXTPACKHLP pHlp, PCVBOXEXTPACKREG *ppReg, PRTERRINFO pErrInfo);
447	/** Pointer to a FNVBOXEXTPACKREGISTER. */
448	typedef FNVBOXEXTPACKREGISTER *PFNVBOXEXTPACKREGISTER;
449
450	/** The name of the main module entry point. */
451	#define VBOX_EXTPACK_MAIN_MOD_ENTRY_POINT "VBoxExtPackRegister"
452
453
454	/** Pointer to the extension pack VM callback table. */
455	typedef struct VBOXEXTPACKVMREG const *PCVBOXEXTPACKVMREG;
456	/**
457	* Callback table returned by VBoxExtPackVMRegister.
458	*
459	* All the callbacks are called the context of a VM process.
460	*
461	* This must be valid until the extension pack main VM module is unloaded.
462	*/
463	typedef struct VBOXEXTPACKVMREG
464	{
465	/** Interface version.
466	* This is set to VBOXEXTPACKVMREG_VERSION. */
467	uint32_t u32Version;
468	/** The VirtualBox version this extension pack was built against. */
469	uint32_t uVBoxVersion;
470
471	/**
472	* Hook for doing work after the Console object is ready.
473	*
474	* @param pThis Pointer to this structure.
475	* @param pConsole The Console interface.
476	*/
477	DECLCALLBACKMEMBER(void, pfnConsoleReady)(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole);
478
479	/**
480	* Hook for doing work before unloading.
481	*
482	* @param pThis Pointer to this structure.
483	*
484	* @remarks The helpers are not available at this point in time.
485	*/
486	DECLCALLBACKMEMBER(void, pfnUnload)(PCVBOXEXTPACKVMREG pThis);
487
488	/**
489	* Hook for configuring the VMM for a VM.
490	*
491	* @returns VBox status code.
492	* @param pThis Pointer to this structure.
493	* @param pConsole The console interface.
494	* @param pVM The cross context VM structure.
495	*/
496	DECLCALLBACKMEMBER(int, pfnVMConfigureVMM)(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole, PVM pVM);
497
498	/**
499	* Hook for doing work right before powering on the VM.
500	*
501	* @returns VBox status code.
502	* @param pThis Pointer to this structure.
503	* @param pConsole The console interface.
504	* @param pVM The cross context VM structure.
505	*/
506	DECLCALLBACKMEMBER(int, pfnVMPowerOn)(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole, PVM pVM);
507
508	/**
509	* Hook for doing work after powering off the VM.
510	*
511	* @param pThis Pointer to this structure.
512	* @param pConsole The console interface.
513	* @param pVM The cross context VM structure. Can be NULL.
514	*/
515	DECLCALLBACKMEMBER(void, pfnVMPowerOff)(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole, PVM pVM);
516
517	/**
518	* Query the IUnknown interface to an object in the main VM module.
519	*
520	* @returns IUnknown pointer (referenced) on success, NULL on failure.
521	* @param pThis Pointer to this structure.
522	* @param pObjectId Pointer to the object ID (UUID).
523	*/
524	DECLCALLBACKMEMBER(void *, pfnQueryObject)(PCVBOXEXTPACKVMREG pThis, PCRTUUID pObjectId);
525
526	DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKVMREG pThis)); /*< Reserved for minor structure revisions. /
527	DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKVMREG pThis)); /*< Reserved for minor structure revisions. /
528	DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKVMREG pThis)); /*< Reserved for minor structure revisions. /
529	DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKVMREG pThis)); /*< Reserved for minor structure revisions. /
530	DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKVMREG pThis)); /*< Reserved for minor structure revisions. /
531	DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKVMREG pThis)); /*< Reserved for minor structure revisions. /
532
533	/** Reserved for minor structure revisions. */
534	uint32_t uReserved7;
535
536	/** End of structure marker (VBOXEXTPACKVMREG_VERSION). */
537	uint32_t u32EndMarker;
538	} VBOXEXTPACKVMREG;
539	/** Current version of the VBOXEXTPACKVMREG structure. */
540	#define VBOXEXTPACKVMREG_VERSION RT_MAKE_U32(2, 0)
541
542
543	/**
544	* The VBoxExtPackVMRegister callback function.
545	*
546	* The Main API (in a VM process) will invoke this function after loading an
547	* extension pack VM module. Its job is to do version compatibility checking
548	* and returning the extension pack registration structure for a VM.
549	*
550	* @returns VBox status code.
551	* @param pHlp Pointer to the extension pack helper function
552	* table. This is valid until the module is unloaded.
553	* @param ppReg Where to return the pointer to the registration
554	* structure containing all the hooks. This structure
555	* be valid and unchanged until the module is unloaded
556	* (i.e. use some static const data for it).
557	* @param pErrInfo Where to return extended error information.
558	*/
559	typedef DECLCALLBACK(int) FNVBOXEXTPACKVMREGISTER(PCVBOXEXTPACKHLP pHlp, PCVBOXEXTPACKVMREG *ppReg, PRTERRINFO pErrInfo);
560	/** Pointer to a FNVBOXEXTPACKVMREGISTER. */
561	typedef FNVBOXEXTPACKVMREGISTER *PFNVBOXEXTPACKVMREGISTER;
562
563	/** The name of the main VM module entry point. */
564	#define VBOX_EXTPACK_MAIN_VM_MOD_ENTRY_POINT "VBoxExtPackVMRegister"
565
566
567	/**
568	* Checks if extension pack interface version is compatible.
569	*
570	* @returns true if the do, false if they don't.
571	* @param u32Provider The provider version.
572	* @param u32User The user version.
573	*/
574	#define VBOXEXTPACK_IS_VER_COMPAT(u32Provider, u32User) \
575	( VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Provider, u32User) \
576	&& (int32_t)RT_LOWORD(u32Provider) >= (int32_t)RT_LOWORD(u32User) ) /* stupid casts to shut up gcc */
577
578	/**
579	* Check if two extension pack interface versions has the same major version.
580	*
581	* @returns true if the do, false if they don't.
582	* @param u32Ver1 The first version number.
583	* @param u32Ver2 The second version number.
584	*/
585	#define VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Ver1, u32Ver2) (RT_HIWORD(u32Ver1) == RT_HIWORD(u32Ver2))
586
587	#endif /* !VBOX_INCLUDED_ExtPack_ExtPack_h */
588

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

source: vbox/trunk/include/VBox/ExtPack/ExtPack.h@ 77807

Download in other formats: