ExtPack.h@ 91312

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

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

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

Download in other formats: