ExtPack.h@ 86058

Last change on this file since 86058 was 86058, checked in by vboxsync, 4 years ago
Main/ExtPack: belatedly bump VBOXEXTPACKHLP_VERSION for the event creation callback. While here, as a fore/after-thought add another, so far not used, callback for creation of IVetoEvent.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.6 KB

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

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

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

Download in other formats: