summaryrefslogtreecommitdiffstats
path: root/include/VBox/ExtPack/ExtPack.h
blob: 671c9171241bb1d33aad9e9ffc34a999ff266a1c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
/** @file
 * VirtualBox - Extension Pack Interface.
 */

/*
 * Copyright (C) 2010-2023 Oracle and/or its affiliates.
 *
 * This file is part of VirtualBox base platform packages, as
 * available from https://www.virtualbox.org.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation, in version 3 of the
 * License.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses>.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
 * in the VirtualBox distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
 */

#ifndef VBOX_INCLUDED_ExtPack_ExtPack_h
#define VBOX_INCLUDED_ExtPack_ExtPack_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif

#include <VBox/types.h>

/** @def VBOXEXTPACK_IF_CS
 * Selects 'class' on 'struct' for interface references.
 * @param I         The interface name
 */
#if defined(__cplusplus) && !defined(RT_OS_WINDOWS)
# define VBOXEXTPACK_IF_CS(I)   class I
#else
# define VBOXEXTPACK_IF_CS(I)   struct I
#endif

VBOXEXTPACK_IF_CS(IUnknown);
VBOXEXTPACK_IF_CS(IConsole);
VBOXEXTPACK_IF_CS(IMachine);
VBOXEXTPACK_IF_CS(IVirtualBox);
VBOXEXTPACK_IF_CS(IProgress);
VBOXEXTPACK_IF_CS(IEvent);
VBOXEXTPACK_IF_CS(IVetoEvent);
VBOXEXTPACK_IF_CS(IEventSource);

/**
 * Module kind for use with VBOXEXTPACKHLP::pfnFindModule.
 */
typedef enum VBOXEXTPACKMODKIND
{
    /** Zero is invalid as always. */
    VBOXEXTPACKMODKIND_INVALID = 0,
    /** Raw-mode context module. */
    VBOXEXTPACKMODKIND_RC,
    /** Ring-0 context module. */
    VBOXEXTPACKMODKIND_R0,
    /** Ring-3 context module. */
    VBOXEXTPACKMODKIND_R3,
    /** End of the valid values (exclusive). */
    VBOXEXTPACKMODKIND_END,
    /** The usual 32-bit type hack. */
    VBOXEXTPACKMODKIND_32BIT_HACK = 0x7fffffff
} VBOXEXTPACKMODKIND;

/**
 * Contexts returned by VBOXEXTPACKHLP::pfnGetContext.
 */
typedef enum VBOXEXTPACKCTX
{
    /** Zero is invalid as always. */
    VBOXEXTPACKCTX_INVALID = 0,
    /** The per-user daemon process (VBoxSVC). */
    VBOXEXTPACKCTX_PER_USER_DAEMON,
    /** A VM process. */
    VBOXEXTPACKCTX_VM_PROCESS,
    /** An API client process.
     * @remarks This will not be returned by VirtualBox yet. */
    VBOXEXTPACKCTX_CLIENT_PROCESS,
    /** End of the valid values (exclusive). */
    VBOXEXTPACKCTX_END,
    /** The usual 32-bit type hack. */
    VBOXEXTPACKCTX_32BIT_HACK = 0x7fffffff
} VBOXEXTPACKCTX;


/** Pointer to const helpers passed to the VBoxExtPackRegister() call. */
typedef const struct VBOXEXTPACKHLP *PCVBOXEXTPACKHLP;
/**
 * Extension pack helpers passed to VBoxExtPackRegister().
 *
 * This will be valid until the module is unloaded.
 */
typedef struct VBOXEXTPACKHLP
{
    /** Interface version.
     * This is set to VBOXEXTPACKHLP_VERSION. */
    uint32_t                    u32Version;

    /** The VirtualBox full version (see VBOX_FULL_VERSION).  */
    uint32_t                    uVBoxFullVersion;
    /** The VirtualBox subversion tree revision.  */
    uint32_t                    uVBoxInternalRevision;
    /** Explicit alignment padding, must be zero. */
    uint32_t                    u32Padding;
    /** Pointer to the version string (read-only). */
    const char                 *pszVBoxVersion;

    /**
     * Finds a module belonging to this extension pack.
     *
     * @returns VBox status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pszName         The module base name.
     * @param   pszExt          The extension. If NULL the default ring-3
     *                          library extension will be used.
     * @param   enmKind         The kind of module to locate.
     * @param   pszFound        Where to return the path to the module on
     *                          success.
     * @param   cbFound         The size of the buffer @a pszFound points to.
     * @param   pfNative        Where to return the native/agnostic indicator.
     */
    DECLR3CALLBACKMEMBER(int, pfnFindModule,(PCVBOXEXTPACKHLP pHlp, const char *pszName, const char *pszExt,
                                             VBOXEXTPACKMODKIND enmKind,
                                             char *pszFound, size_t cbFound, bool *pfNative));

    /**
     * Gets the path to a file belonging to this extension pack.
     *
     * @returns VBox status code.
     * @retval  VERR_INVALID_POINTER if any of the pointers are invalid.
     * @retval  VERR_BUFFER_OVERFLOW if the buffer is too small.  The buffer
     *          will contain nothing.
     *
     * @param   pHlp            Pointer to this helper structure.
     * @param   pszFilename     The filename.
     * @param   pszPath         Where to return the path to the file on
     *                          success.
     * @param   cbPath          The size of the buffer @a pszPath.
     */
    DECLR3CALLBACKMEMBER(int, pfnGetFilePath,(PCVBOXEXTPACKHLP pHlp, const char *pszFilename, char *pszPath, size_t cbPath));

    /**
     * Gets the context the extension pack is operating in.
     *
     * @returns The context.
     * @retval  VBOXEXTPACKCTX_INVALID if @a pHlp is invalid.
     *
     * @param   pHlp            Pointer to this helper structure.
     */
    DECLR3CALLBACKMEMBER(VBOXEXTPACKCTX, pfnGetContext,(PCVBOXEXTPACKHLP pHlp));

    /**
     * Loads a HGCM service provided by an extension pack.
     *
     * @returns VBox status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pConsole        Pointer to the VM's console object.
     * @param   pszServiceLibrary Name of the library file containing the
     *                          service implementation, without extension.
     * @param   pszServiceName  Name of HGCM service.
     */
    DECLR3CALLBACKMEMBER(int, pfnLoadHGCMService,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IConsole) *pConsole,
                                                  const char *pszServiceLibrary, const char *pszServiceName));

    /**
     * Loads a VD plugin provided by an extension pack.
     *
     * This makes sense only in the context of the per-user service (VBoxSVC).
     *
     * @returns VBox status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pVirtualBox     Pointer to the VirtualBox object.
     * @param   pszPluginLibrary Name of the library file containing the plugin
     *                          implementation, without extension.
     */
    DECLR3CALLBACKMEMBER(int, pfnLoadVDPlugin,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
                                               const char *pszPluginLibrary));

    /**
     * Unloads a VD plugin provided by an extension pack.
     *
     * This makes sense only in the context of the per-user service (VBoxSVC).
     *
     * @returns VBox status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pVirtualBox     Pointer to the VirtualBox object.
     * @param   pszPluginLibrary Name of the library file containing the plugin
     *                          implementation, without extension.
     */
    DECLR3CALLBACKMEMBER(int, pfnUnloadVDPlugin,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
                                                 const char *pszPluginLibrary));

    /**
     * Creates an IProgress object instance for a long running extension
     * pack provided API operation which is executed asynchronously.
     *
     * This implicitly creates a cancellable progress object, since anything
     * else is user unfriendly. You need to design your code to handle
     * cancellation with reasonable response time.
     *
     * @returns COM status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pInitiator      Pointer to the initiating object.
     * @param   pcszDescription Description of the overall task.
     * @param   cOperations     Number of operations for this task.
     * @param   uTotalOperationsWeight        Overall weight for the entire task.
     * @param   pcszFirstOperationDescription Description of the first operation.
     * @param   uFirstOperationWeight         Weight for the first operation.
     * @param   ppProgressOut   Output parameter for the IProgress object reference.
     */
    DECLR3CALLBACKMEMBER(uint32_t, pfnCreateProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IUnknown) *pInitiator,
                                                      const char *pcszDescription, uint32_t cOperations,
                                                      uint32_t uTotalOperationsWeight, const char *pcszFirstOperationDescription,
                                                      uint32_t uFirstOperationWeight, VBOXEXTPACK_IF_CS(IProgress) **ppProgressOut));

    /**
     * Checks if the Progress object is marked as canceled.
     *
     * @returns COM status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pProgress       Pointer to the IProgress object reference returned
     *                          by pfnCreateProgress.
     * @param   pfCanceled      @c true if canceled, @c false otherwise.
     */
    DECLR3CALLBACKMEMBER(uint32_t, pfnGetCanceledProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
                                                           bool *pfCanceled));

    /**
     * Updates the percentage value of the current operation of the
     * Progress object.
     *
     * @returns COM status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pProgress       Pointer to the IProgress object reference returned
     *                          by pfnCreateProgress.
     * @param   uPercent        Result of the overall task.
     */
    DECLR3CALLBACKMEMBER(uint32_t, pfnUpdateProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
                                                      uint32_t uPercent));

    /**
     * Signals that the current operation is successfully completed and
     * advances to the next operation. The operation percentage is reset
     * to 0.
     *
     * If the operation count is exceeded this returns an error.
     *
     * @returns COM status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pProgress       Pointer to the IProgress object reference returned
     *                          by pfnCreateProgress.
     * @param   pcszNextOperationDescription Description of the next operation.
     * @param   uNextOperationWeight         Weight for the next operation.
     */
    DECLR3CALLBACKMEMBER(uint32_t, pfnNextOperationProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
                                                             const char *pcszNextOperationDescription,
                                                             uint32_t uNextOperationWeight));

    /**
     * Waits until the other task is completed (including all sub-operations)
     * and forward all changes from the other progress to this progress. This
     * means sub-operation number, description, percent and so on.
     *
     * The caller is responsible for having at least the same count of
     * sub-operations in this progress object as there are in the other
     * progress object.
     *
     * If the other progress object supports cancel and this object gets any
     * cancel request (when here enabled as well), it will be forwarded to
     * the other progress object.
     *
     * Error information is automatically preserved (by transferring it to
     * the current thread's error information). If the caller wants to set it
     * as the completion state of this progress it needs to be done separately.
     *
     * @returns COM status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pProgress       Pointer to the IProgress object reference returned
     *                          by pfnCreateProgress.
     * @param   pProgressOther  Pointer to an IProgress object reference, the one
     *                          to be waited for.
     * @param   cTimeoutMS      Timeout in milliseconds, 0 for indefinite wait.
     */
    DECLR3CALLBACKMEMBER(uint32_t, pfnWaitOtherProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
                                                         VBOXEXTPACK_IF_CS(IProgress) *pProgressOther,
                                                         uint32_t cTimeoutMS));

    /**
     * Marks the whole task as complete and sets the result code.
     *
     * If the result code indicates a failure then this method will store
     * the currently set COM error info from the current thread in the
     * the errorInfo attribute of this Progress object instance. If there
     * is no error information available then an error is returned.
     *
     * If the result code indicates success then the task is terminated,
     * without paying attention to the current operation being the last.
     *
     * Note that this must be called only once for the given Progress
     * object. Subsequent calls will return errors.
     *
     * @returns COM status code.
     * @param   pHlp            Pointer to this helper structure.
     * @param   pProgress       Pointer to the IProgress object reference returned
     *                          by pfnCreateProgress.
     * @param   uResultCode     Result of the overall task.
     */
    DECLR3CALLBACKMEMBER(uint32_t, pfnCompleteProgress,(PCVBOXEXTPACKHLP pHlp, VBOXEXTPACK_IF_CS(IProgress) *pProgress,
                                                        uint32_t uResultCode));


    DECLR3CALLBACKMEMBER(uint32_t, pfnCreateEvent,(PCVBOXEXTPACKHLP pHlp,
                                                   VBOXEXTPACK_IF_CS(IEventSource) *aSource,
                                                   /* VBoxEventType_T */ uint32_t aType, bool aWaitable,
                                                   VBOXEXTPACK_IF_CS(IEvent) **ppEventOut));

    DECLR3CALLBACKMEMBER(uint32_t, pfnCreateVetoEvent,(PCVBOXEXTPACKHLP pHlp,
                                                       VBOXEXTPACK_IF_CS(IEventSource) *aSource,
                                                       /* VBoxEventType_T */ uint32_t aType,
                                                       VBOXEXTPACK_IF_CS(IVetoEvent) **ppEventOut));

    /**
     * Translate the string using registered translation files.
     *
     * Translation files are excluded from translation engine. Although
     * the already loaded translation remains in the translation cache the new
     * translation will not be loaded after returning from the function if the
     * user changes the language.
     *
     * @returns Translated string on success the pszSourceText otherwise.
     * @param   pHlp                      Pointer to this helper structure.
     * @param   aComponent                Translation context e.g. class name
     * @param   pszSourceText             String to translate
     * @param   pszComment                Comment to the string to resolve possible ambiguities
     *                                    (NULL means no comment).
     * @param   aNum                      Number used to define plural form of the translation
     */
    DECLR3CALLBACKMEMBER(const char *, pfnTranslate,(PCVBOXEXTPACKHLP pHlp,
                                                     const char  *pszComponent,
                                                     const char  *pszSourceText,
                                                     const char  *pszComment,
                                                     const size_t aNum));

    DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */

    /** Reserved for minor structure revisions. */
    uint32_t                    uReserved7;

    /** End of structure marker (VBOXEXTPACKHLP_VERSION). */
    uint32_t                    u32EndMarker;
} VBOXEXTPACKHLP;
/** Current version of the VBOXEXTPACKHLP structure.  */
#define VBOXEXTPACKHLP_VERSION          RT_MAKE_U32(0, 5)


/** Pointer to the extension pack callback table. */
typedef struct VBOXEXTPACKREG const *PCVBOXEXTPACKREG;
/**
 * Callback table returned by VBoxExtPackRegister.
 *
 * All the callbacks are called the context of the per-user service (VBoxSVC).
 *
 * This must be valid until the extension pack main module is unloaded.
 */
typedef struct VBOXEXTPACKREG
{
    /** Interface version.
     * This is set to VBOXEXTPACKREG_VERSION. */
    uint32_t                    u32Version;
    /** The VirtualBox version this extension pack was built against.  */
    uint32_t                    uVBoxVersion;
    /** Translation files base name. Set to NULL if no translation files. */
    const char                 *pszNlsBaseName;

    /**
     * Hook for doing setups after the extension pack was installed.
     *
     * @returns VBox status code.
     * @retval  VERR_EXTPACK_UNSUPPORTED_HOST_UNINSTALL if the extension pack
     *          requires some different host version or a prerequisite is
     *          missing from the host.  Automatic uninstall will be attempted.
     *          Must set error info.
     *
     * @param   pThis       Pointer to this structure.
     * @param   pVirtualBox The VirtualBox interface.
     * @param   pErrInfo    Where to return extended error information.
     */
    DECLCALLBACKMEMBER(int, pfnInstalled,(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
                                          PRTERRINFO pErrInfo));

    /**
     * Hook for cleaning up before the extension pack is uninstalled.
     *
     * @returns VBox status code.
     * @param   pThis       Pointer to this structure.
     * @param   pVirtualBox The VirtualBox interface.
     *
     * @todo    This is currently called holding locks making pVirtualBox
     *          relatively unusable.
     */
    DECLCALLBACKMEMBER(int, pfnUninstall,(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox));

    /**
     * Hook for doing work after the VirtualBox object is ready.
     *
     * @param   pThis       Pointer to this structure.
     * @param   pVirtualBox The VirtualBox interface.
     */
    DECLCALLBACKMEMBER(void, pfnVirtualBoxReady,(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox));

    /**
     * Hook for doing work before unloading.
     *
     * @param   pThis       Pointer to this structure.
     *
     * @remarks The helpers are not available at this point in time.
     * @remarks This is not called on uninstall, then pfnUninstall will be the
     *          last callback.
     */
    DECLCALLBACKMEMBER(void, pfnUnload,(PCVBOXEXTPACKREG pThis));

    /**
     * Hook for changing the default VM configuration upon creation.
     *
     * @returns VBox status code.
     * @param   pThis       Pointer to this structure.
     * @param   pVirtualBox The VirtualBox interface.
     * @param   pMachine    The machine interface.
     */
    DECLCALLBACKMEMBER(int, pfnVMCreated,(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox,
                                          VBOXEXTPACK_IF_CS(IMachine) *pMachine));

    /**
     * Query the IUnknown interface to an object in the main module.
     *
     * @returns IUnknown pointer (referenced) on success, NULL on failure.
     * @param   pThis       Pointer to this structure.
     * @param   pObjectId   Pointer to the object ID (UUID).
     */
    DECLCALLBACKMEMBER(void *, pfnQueryObject,(PCVBOXEXTPACKREG pThis, PCRTUUID pObjectId));

    DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKREG pThis)); /**< Reserved for minor structure revisions. */

    /** Reserved for minor structure revisions. */
    uint32_t                    uReserved7;

    /** End of structure marker (VBOXEXTPACKREG_VERSION). */
    uint32_t                    u32EndMarker;
} VBOXEXTPACKREG;
/** Current version of the VBOXEXTPACKREG structure.  */
#define VBOXEXTPACKREG_VERSION        RT_MAKE_U32(0, 3)


/**
 * The VBoxExtPackRegister callback function.
 *
 * The Main API (as in VBoxSVC) will invoke this function after loading an
 * extension pack Main module. Its job is to do version compatibility checking
 * and returning the extension pack registration structure.
 *
 * @returns VBox status code.
 * @param   pHlp            Pointer to the extension pack helper function
 *                          table.  This is valid until the module is unloaded.
 * @param   ppReg           Where to return the pointer to the registration
 *                          structure containing all the hooks.  This structure
 *                          be valid and unchanged until the module is unloaded
 *                          (i.e. use some static const data for it).
 * @param   pErrInfo        Where to return extended error information.
 */
typedef DECLCALLBACKTYPE(int, FNVBOXEXTPACKREGISTER,(PCVBOXEXTPACKHLP pHlp, PCVBOXEXTPACKREG *ppReg, PRTERRINFO pErrInfo));
/** Pointer to a FNVBOXEXTPACKREGISTER. */
typedef FNVBOXEXTPACKREGISTER *PFNVBOXEXTPACKREGISTER;

/** The name of the main module entry point. */
#define VBOX_EXTPACK_MAIN_MOD_ENTRY_POINT   "VBoxExtPackRegister"


/** Pointer to the extension pack VM callback table. */
typedef struct VBOXEXTPACKVMREG const *PCVBOXEXTPACKVMREG;
/**
 * Callback table returned by VBoxExtPackVMRegister.
 *
 * All the callbacks are called the context of a VM process.
 *
 * This must be valid until the extension pack main VM module is unloaded.
 */
typedef struct VBOXEXTPACKVMREG
{
    /** Interface version.
     * This is set to VBOXEXTPACKVMREG_VERSION. */
    uint32_t                    u32Version;
    /** The VirtualBox version this extension pack was built against.  */
    uint32_t                    uVBoxVersion;
    /** Translation files base name.  Set to NULL if no translation files.  */
    const char                 *pszNlsBaseName;

    /**
     * Hook for doing work after the Console object is ready.
     *
     * @param   pThis       Pointer to this structure.
     * @param   pConsole    The Console interface.
     */
    DECLCALLBACKMEMBER(void, pfnConsoleReady,(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole));

    /**
     * Hook for doing work before unloading.
     *
     * @param   pThis       Pointer to this structure.
     *
     * @remarks The helpers are not available at this point in time.
     */
    DECLCALLBACKMEMBER(void, pfnUnload,(PCVBOXEXTPACKVMREG pThis));

    /**
     * Hook for configuring the VMM for a VM.
     *
     * @returns VBox status code.
     * @param   pThis       Pointer to this structure.
     * @param   pConsole    The console interface.
     * @param   pVM         The cross context VM structure.
     * @param   pVMM        The VMM function table.
     */
    DECLCALLBACKMEMBER(int, pfnVMConfigureVMM,(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole,
                                               PVM pVM, PCVMMR3VTABLE pVMM));

    /**
     * Hook for doing work right before powering on the VM.
     *
     * @returns VBox status code.
     * @param   pThis       Pointer to this structure.
     * @param   pConsole    The console interface.
     * @param   pVM         The cross context VM structure.
     * @param   pVMM        The VMM function table.
     */
    DECLCALLBACKMEMBER(int, pfnVMPowerOn,(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole,
                                          PVM pVM, PCVMMR3VTABLE pVMM));

    /**
     * Hook for doing work after powering off the VM.
     *
     * @param   pThis       Pointer to this structure.
     * @param   pConsole    The console interface.
     * @param   pVM         The cross context VM structure. Can be NULL.
     * @param   pVMM        The VMM function table.
     */
    DECLCALLBACKMEMBER(void, pfnVMPowerOff,(PCVBOXEXTPACKVMREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole,
                                            PVM pVM, PCVMMR3VTABLE pVMM));

    /**
     * Query the IUnknown interface to an object in the main VM module.
     *
     * @returns IUnknown pointer (referenced) on success, NULL on failure.
     * @param   pThis       Pointer to this structure.
     * @param   pObjectId   Pointer to the object ID (UUID).
     */
    DECLCALLBACKMEMBER(void *, pfnQueryObject,(PCVBOXEXTPACKVMREG pThis, PCRTUUID pObjectId));

    DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKVMREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKVMREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKVMREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKVMREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKVMREG pThis)); /**< Reserved for minor structure revisions. */
    DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKVMREG pThis)); /**< Reserved for minor structure revisions. */

    /** Reserved for minor structure revisions. */
    uint32_t                    uReserved7;

    /** End of structure marker (VBOXEXTPACKVMREG_VERSION). */
    uint32_t                    u32EndMarker;
} VBOXEXTPACKVMREG;
/** Current version of the VBOXEXTPACKVMREG structure.  */
#define VBOXEXTPACKVMREG_VERSION      RT_MAKE_U32(1, 0)


/**
 * The VBoxExtPackVMRegister callback function.
 *
 * The Main API (in a VM process) will invoke this function after loading an
 * extension pack VM module. Its job is to do version compatibility checking
 * and returning the extension pack registration structure for a VM.
 *
 * @returns VBox status code.
 * @param   pHlp            Pointer to the extension pack helper function
 *                          table.  This is valid until the module is unloaded.
 * @param   ppReg           Where to return the pointer to the registration
 *                          structure containing all the hooks.  This structure
 *                          be valid and unchanged until the module is unloaded
 *                          (i.e. use some static const data for it).
 * @param   pErrInfo        Where to return extended error information.
 */
typedef DECLCALLBACKTYPE(int, FNVBOXEXTPACKVMREGISTER,(PCVBOXEXTPACKHLP pHlp, PCVBOXEXTPACKVMREG *ppReg, PRTERRINFO pErrInfo));
/** Pointer to a FNVBOXEXTPACKVMREGISTER. */
typedef FNVBOXEXTPACKVMREGISTER *PFNVBOXEXTPACKVMREGISTER;

/** The name of the main VM module entry point. */
#define VBOX_EXTPACK_MAIN_VM_MOD_ENTRY_POINT   "VBoxExtPackVMRegister"


/**
 * Checks if extension pack interface version is compatible.
 *
 * @returns true if the do, false if they don't.
 * @param   u32Provider     The provider version.
 * @param   u32User         The user version.
 */
#define VBOXEXTPACK_IS_VER_COMPAT(u32Provider, u32User) \
    (    VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Provider, u32User) \
      && (int32_t)RT_LOWORD(u32Provider) >= (int32_t)RT_LOWORD(u32User) ) /* stupid casts to shut up gcc */

/**
 * Check if two extension pack interface versions has the same major version.
 *
 * @returns true if the do, false if they don't.
 * @param   u32Ver1         The first version number.
 * @param   u32Ver2         The second version number.
 */
#define VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Ver1, u32Ver2)  (RT_HIWORD(u32Ver1) == RT_HIWORD(u32Ver2))

#endif /* !VBOX_INCLUDED_ExtPack_ExtPack_h */