VirtualBox

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

Last change on this file since 103224 was 101293, checked in by vboxsync, 14 months ago

Main/ExtPack*: tidying up. (Please, do NOT use 'm' as a local variable, that's just so confusing.)

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