VirtualBox

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

Last change on this file since 59337 was 59337, checked in by vboxsync, 9 years ago

VBOXEXTPACKREG: Extended with uVBoxFullVersion member and reserved space to prevent future amendments from having to be incompatible.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.8 KB
Line 
1/** @file
2 * VirtualBox - Extension Pack Interface.
3 */
4
5/*
6 * Copyright (C) 2010-2015 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_ExtPack_ExtPack_h
27#define ___VBox_ExtPack_ExtPack_h
28
29#include <VBox/types.h>
30
31/** @def VBOXEXTPACK_IF_CS
32 * Selects 'class' on 'struct' for interface references.
33 * @param I The interface name
34 */
35#if defined(__cplusplus) && !defined(RT_OS_WINDOWS)
36# define VBOXEXTPACK_IF_CS(I) class I
37#else
38# define VBOXEXTPACK_IF_CS(I) struct I
39#endif
40
41VBOXEXTPACK_IF_CS(IConsole);
42VBOXEXTPACK_IF_CS(IMachine);
43VBOXEXTPACK_IF_CS(IVirtualBox);
44
45/**
46 * Module kind for use with VBOXEXTPACKHLP::pfnFindModule.
47 */
48typedef enum VBOXEXTPACKMODKIND
49{
50 /** Zero is invalid as alwasy. */
51 VBOXEXTPACKMODKIND_INVALID = 0,
52 /** Raw-mode context module. */
53 VBOXEXTPACKMODKIND_RC,
54 /** Ring-0 context module. */
55 VBOXEXTPACKMODKIND_R0,
56 /** Ring-3 context module. */
57 VBOXEXTPACKMODKIND_R3,
58 /** End of the valid values (exclusive). */
59 VBOXEXTPACKMODKIND_END,
60 /** The usual 32-bit type hack. */
61 VBOXEXTPACKMODKIND_32BIT_HACK = 0x7fffffff
62} VBOXEXTPACKMODKIND;
63
64/**
65 * Contexts returned by VBOXEXTPACKHLP::pfnGetContext.
66 */
67typedef enum VBOXEXTPACKCTX
68{
69 /** Zero is invalid as alwasy. */
70 VBOXEXTPACKCTX_INVALID = 0,
71 /** The per-user daemon process (VBoxSVC). */
72 VBOXEXTPACKCTX_PER_USER_DAEMON,
73 /** A VM process.
74 * @remarks This will also include the client processes in v4.0. */
75 VBOXEXTPACKCTX_VM_PROCESS,
76 /** A API client process.
77 * @remarks This will not be returned by VirtualBox 4.0. */
78 VBOXEXTPACKCTX_CLIENT_PROCESS,
79 /** End of the valid values (exclusive). */
80 VBOXEXTPACKCTX_END,
81 /** The usual 32-bit type hack. */
82 VBOXEXTPACKCTX_32BIT_HACK = 0x7fffffff
83} VBOXEXTPACKCTX;
84
85
86/** Pointer to const helpers passed to the VBoxExtPackRegister() call. */
87typedef const struct VBOXEXTPACKHLP *PCVBOXEXTPACKHLP;
88/**
89 * Extension pack helpers passed to VBoxExtPackRegister().
90 *
91 * This will be valid until the module is unloaded.
92 */
93typedef struct VBOXEXTPACKHLP
94{
95 /** Interface version.
96 * This is set to VBOXEXTPACKHLP_VERSION. */
97 uint32_t u32Version;
98
99 /** The VirtualBox full version (see VBOX_FULL_VERSION). */
100 uint32_t uVBoxFullVersion;
101 /** The VirtualBox subversion tree revision. */
102 uint32_t uVBoxInternalRevision;
103 /** Explicit alignment padding, must be zero. */
104 uint32_t u32Padding;
105 /** Pointer to the version string (read-only). */
106 const char *pszVBoxVersion;
107
108 /**
109 * Finds a module belonging to this extension pack.
110 *
111 * @returns VBox status code.
112 * @param pHlp Pointer to this helper structure.
113 * @param pszName The module base name.
114 * @param pszExt The extension. If NULL the default ring-3
115 * library extension will be used.
116 * @param enmKind The kind of module to locate.
117 * @param pszFound Where to return the path to the module on
118 * success.
119 * @param cbFound The size of the buffer @a pszFound points to.
120 * @param pfNative Where to return the native/agnostic indicator.
121 */
122 DECLR3CALLBACKMEMBER(int, pfnFindModule,(PCVBOXEXTPACKHLP pHlp, const char *pszName, const char *pszExt,
123 VBOXEXTPACKMODKIND enmKind,
124 char *pszFound, size_t cbFound, bool *pfNative));
125
126 /**
127 * Gets the path to a file belonging to this extension pack.
128 *
129 * @returns VBox status code.
130 * @retval VERR_INVALID_POINTER if any of the pointers are invalid.
131 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer
132 * will contain nothing.
133 *
134 * @param pHlp Pointer to this helper structure.
135 * @param pszFilename The filename.
136 * @param pszPath Where to return the path to the file on
137 * success.
138 * @param cbPath The size of the buffer @a pszPath.
139 */
140 DECLR3CALLBACKMEMBER(int, pfnGetFilePath,(PCVBOXEXTPACKHLP pHlp, const char *pszFilename, char *pszPath, size_t cbPath));
141
142 /**
143 * Gets the context the extension pack is operating in.
144 *
145 * @returns The context.
146 * @retval VBOXEXTPACKCTX_INVALID if @a pHlp is invalid.
147 *
148 * @param pHlp Pointer to this helper structure.
149 */
150 DECLR3CALLBACKMEMBER(VBOXEXTPACKCTX, pfnGetContext,(PCVBOXEXTPACKHLP pHlp));
151
152 /**
153 * Loads a HGCM service provided by an extension pack.
154 *
155 * @returns VBox status code.
156 * @param pHlp Pointer to this helper structure.
157 * @param pConsole Pointer to the VM's console object.
158 * @param pszServiceLibrary Name of the library file containing the
159 * service implementation, without extension.
160 * @param pszServiceName Name of HGCM service.
161 */
162 DECLR3CALLBACKMEMBER(int, pfnLoadHGCMService,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IConsole) *pConsole,
163 const char *pszServiceLibrary, const char *pszServiceName));
164
165 /**
166 * Loads a VD plugin provided by an extension pack.
167 *
168 * This makes sense only in the context of the per-user service (VBoxSVC).
169 *
170 * @returns VBox status code.
171 * @param pHlp Pointer to this helper structure.
172 * @param pVirtualBox Pointer to the VirtualBox object.
173 * @param pszPluginLibrary Name of the library file containing the plugin
174 * implementation, without extension.
175 */
176 DECLR3CALLBACKMEMBER(int, pfnLoadVDPlugin,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
177 const char *pszPluginLibrary));
178
179 /**
180 * Unloads a VD plugin provided by an extension pack.
181 *
182 * This makes sense only in the context of the per-user service (VBoxSVC).
183 *
184 * @returns VBox status code.
185 * @param pHlp Pointer to this helper structure.
186 * @param pVirtualBox Pointer to the VirtualBox object.
187 * @param pszPluginLibrary Name of the library file containing the plugin
188 * implementation, without extension.
189 */
190 DECLR3CALLBACKMEMBER(int, pfnUnloadVDPlugin,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
191 const char *pszPluginLibrary));
192
193 DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
194 DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
195 DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
196 DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
197 DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
198 DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
199
200 /** End of structure marker (VBOXEXTPACKHLP_VERSION). */
201 uint32_t u32EndMarker;
202} VBOXEXTPACKHLP;
203/** Current version of the VBOXEXTPACKHLP structure. */
204#define VBOXEXTPACKHLP_VERSION RT_MAKE_U32(2, 1)
205
206
207/** Pointer to the extension pack callback table. */
208typedef struct VBOXEXTPACKREG const *PCVBOXEXTPACKREG;
209/**
210 * Callback table returned by VBoxExtPackRegister.
211 *
212 * This must be valid until the extension pack main module is unloaded.
213 */
214typedef struct VBOXEXTPACKREG
215{
216 /** Interface version.
217 * This is set to VBOXEXTPACKREG_VERSION. */
218 uint32_t u32Version;
219 /** The VirtualBox version this extension pack was built against. */
220 uint32_t uVBoxVersion;
221
222 /**
223 * Hook for doing setups after the extension pack was installed.
224 *
225 * This is called in the context of the per-user service (VBoxSVC).
226 *
227 * @returns VBox status code.
228 * @retval VERR_EXTPACK_UNSUPPORTED_HOST_UNINSTALL if the extension pack
229 * requires some different host version or a prerequisite is
230 * missing from the host. Automatic uninstall will be attempted.
231 * Must set error info.
232 *
233 * @param pThis Pointer to this structure.
234 * @param pVirtualBox The VirtualBox interface.
235 * @param pErrInfo Where to return extended error information.
236 */
237 DECLCALLBACKMEMBER(int, pfnInstalled)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
238 PRTERRINFO pErrInfo);
239
240 /**
241 * Hook for cleaning up before the extension pack is uninstalled.
242 *
243 * This is called in the context of the per-user service (VBoxSVC).
244 *
245 * @returns VBox status code.
246 * @param pThis Pointer to this structure.
247 * @param pVirtualBox The VirtualBox interface.
248 *
249 * @todo This is currently called holding locks making pVirtualBox
250 * relatively unusable.
251 */
252 DECLCALLBACKMEMBER(int, pfnUninstall)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox);
253
254 /**
255 * Hook for doing work after the VirtualBox object is ready.
256 *
257 * This is called in the context of the per-user service (VBoxSVC). The
258 * pfnConsoleReady method is the equivalent for the VM/client process.
259 *
260 * @param pThis Pointer to this structure.
261 * @param pVirtualBox The VirtualBox interface.
262 */
263 DECLCALLBACKMEMBER(void, pfnVirtualBoxReady)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox);
264
265 /**
266 * Hook for doing work after the Console object is ready.
267 *
268 * This is called in the context of the VM/client process. The
269 * pfnVirtualBoxReady method is the equivalent for the per-user service
270 * (VBoxSVC).
271 *
272 * @param pThis Pointer to this structure.
273 * @param pConsole The Console interface.
274 */
275 DECLCALLBACKMEMBER(void, pfnConsoleReady)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole);
276
277 /**
278 * Hook for doing work before unloading.
279 *
280 * This is called both in the context of the per-user service (VBoxSVC) and
281 * in context of the VM process (VBoxC).
282 *
283 * @param pThis Pointer to this structure.
284 *
285 * @remarks The helpers are not available at this point in time.
286 * @remarks This is not called on uninstall, then pfnUninstall will be the
287 * last callback.
288 */
289 DECLCALLBACKMEMBER(void, pfnUnload)(PCVBOXEXTPACKREG pThis);
290
291 /**
292 * Hook for changing the default VM configuration upon creation.
293 *
294 * This is called in the context of the per-user service (VBoxSVC).
295 *
296 * @returns VBox status code.
297 * @param pThis Pointer to this structure.
298 * @param pVirtualBox The VirtualBox interface.
299 * @param pMachine The machine interface.
300 */
301 DECLCALLBACKMEMBER(int, pfnVMCreated)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
302 VBOXEXTPACK_IF_CS(IMachine) *pMachine);
303
304 /**
305 * Hook for configuring the VMM for a VM.
306 *
307 * This is called in the context of the VM process (VBoxC).
308 *
309 * @returns VBox status code.
310 * @param pThis Pointer to this structure.
311 * @param pConsole The console interface.
312 * @param pVM The cross context VM structure.
313 */
314 DECLCALLBACKMEMBER(int, pfnVMConfigureVMM)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole, PVM pVM);
315
316 /**
317 * Hook for doing work right before powering on the VM.
318 *
319 * This is called in the context of the VM process (VBoxC).
320 *
321 * @returns VBox status code.
322 * @param pThis Pointer to this structure.
323 * @param pConsole The console interface.
324 * @param pVM The cross context VM structure.
325 */
326 DECLCALLBACKMEMBER(int, pfnVMPowerOn)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole, PVM pVM);
327
328 /**
329 * Hook for doing work after powering on the VM.
330 *
331 * This is called in the context of the VM process (VBoxC).
332 *
333 * @param pThis Pointer to this structure.
334 * @param pConsole The console interface.
335 * @param pVM The cross context VM structure. Can be NULL.
336 */
337 DECLCALLBACKMEMBER(void, pfnVMPowerOff)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole, PVM pVM);
338
339 /**
340 * Query the IUnknown interface to an object in the main module.
341 *
342 * This is can be called in any context.
343 *
344 * @returns IUnknown pointer (referenced) on success, NULL on failure.
345 * @param pThis Pointer to this structure.
346 * @param pObjectId Pointer to the object ID (UUID).
347 */
348 DECLCALLBACKMEMBER(void *, pfnQueryObject)(PCVBOXEXTPACKREG pThis, PCRTUUID pObjectId);
349
350 DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
351 DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
352 DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
353 DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
354 DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
355 DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
356
357 /** Reserved for minor structure revisions. */
358 uint32_t uReserved7;
359
360 /** End of structure marker (VBOXEXTPACKREG_VERSION). */
361 uint32_t u32EndMarker;
362} VBOXEXTPACKREG;
363/** Current version of the VBOXEXTPACKREG structure. */
364#define VBOXEXTPACKREG_VERSION RT_MAKE_U32(1, 1)
365
366
367/**
368 * The VBoxExtPackRegister callback function.
369 *
370 * PDM will invoke this function after loading a driver module and letting
371 * the module decide which drivers to register and how to handle conflicts.
372 *
373 * @returns VBox status code.
374 * @param pHlp Pointer to the extension pack helper function
375 * table. This is valid until the module is unloaded.
376 * @param ppReg Where to return the pointer to the registration
377 * structure containing all the hooks. This structure
378 * be valid and unchanged until the module is unloaded
379 * (i.e. use some static const data for it).
380 * @param pErrInfo Where to return extended error information.
381 */
382typedef DECLCALLBACK(int) FNVBOXEXTPACKREGISTER(PCVBOXEXTPACKHLP pHlp, PCVBOXEXTPACKREG *ppReg, PRTERRINFO pErrInfo);
383/** Pointer to a FNVBOXEXTPACKREGISTER. */
384typedef FNVBOXEXTPACKREGISTER *PFNVBOXEXTPACKREGISTER;
385
386/** The name of the main module entry point. */
387#define VBOX_EXTPACK_MAIN_MOD_ENTRY_POINT "VBoxExtPackRegister"
388
389
390/**
391 * Checks if extension pack interface version is compatible.
392 *
393 * @returns true if the do, false if they don't.
394 * @param u32Provider The provider version.
395 * @param u32User The user version.
396 */
397#define VBOXEXTPACK_IS_VER_COMPAT(u32Provider, u32User) \
398 ( VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Provider, u32User) \
399 && (int32_t)RT_LOWORD(u32Provider) >= (int32_t)RT_LOWORD(u32User) ) /* stupid casts to shut up gcc */
400
401/**
402 * Check if two extension pack interface versions has the same major version.
403 *
404 * @returns true if the do, false if they don't.
405 * @param u32Ver1 The first version number.
406 * @param u32Ver2 The second version number.
407 */
408#define VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Ver1, u32Ver2) (RT_HIWORD(u32Ver1) == RT_HIWORD(u32Ver2))
409
410#endif
411
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette