← Back to branch summary

~ubuntu-branches/ubuntu/trusty/virtualbox-lts-xenial/trusty-proposed

« back to all changes in this revision

Viewing changes to include/VBox/hgcmsvc.h

  • Committer: Package Import Robot
  • Author(s): Gianfranco Costamagna
  • Date: 2016-02-23 14:28:26 UTC
  • Revision ID: package-import@ubuntu.com-20160223142826-bdu69el2z6wa2a44
Tags: upstream-4.3.36-dfsg
Import upstream version 4.3.36-dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/VBox/hgcmsvc.h
 
1
/** @file
 
2
 * Host-Guest Communication Manager (HGCM) - Service library definitions.
 
3
 */
 
4
 
 
5
/*
 
6
 * Copyright (C) 2006-2011 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_hgcm_h
 
27
#define ___VBox_hgcm_h
 
28
 
 
29
#include <iprt/assert.h>
 
30
#include <iprt/string.h>
 
31
#include <VBox/cdefs.h>
 
32
#include <VBox/types.h>
 
33
#include <VBox/err.h>
 
34
#ifdef VBOX_TEST_HGCM_PARMS
 
35
# include <iprt/test.h>
 
36
#endif
 
37
 
 
38
/** @todo proper comments. */
 
39
 
 
40
/**
 
41
 * Service interface version.
 
42
 *
 
43
 * Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
 
44
 *
 
45
 * A service can work with these structures if major version
 
46
 * is equal and minor version of service is <= version of the
 
47
 * structures.
 
48
 *
 
49
 * For example when a new helper is added at the end of helpers
 
50
 * structure, then the minor version will be increased. All older
 
51
 * services still can work because they have their old helpers
 
52
 * unchanged.
 
53
 *
 
54
 * Revision history.
 
55
 * 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
 
56
 * 2.1->2.2 Because pfnSaveState and pfnLoadState were added
 
57
 * 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
 
58
 * 3.1->3.2 Because pfnRegisterExtension was added
 
59
 * 3.2->3.3 Because pfnDisconnectClient helper was added
 
60
 * 3.3->4.1 Because the pvService entry and parameter was added
 
61
 * 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK parameter type was added
 
62
 * 4.2->5.1 Removed the VBOX_HGCM_SVC_PARM_CALLBACK parameter type, as
 
63
 *          this problem is already solved by service extension callbacks
 
64
 */
 
65
#define VBOX_HGCM_SVC_VERSION_MAJOR (0x0005)
 
66
#define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
 
67
#define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
 
68
 
 
69
 
 
70
/** Typed pointer to distinguish a call to service. */
 
71
struct VBOXHGCMCALLHANDLE_TYPEDEF;
 
72
typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
 
73
 
 
74
/** Service helpers pointers table. */
 
75
typedef struct _VBOXHGCMSVCHELPERS
 
76
{
 
77
    /** The service has processed the Call request. */
 
78
    DECLR3CALLBACKMEMBER(void, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
 
79
 
 
80
    void *pvInstance;
 
81
 
 
82
    /** The service disconnects the client. */
 
83
    DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
 
84
} VBOXHGCMSVCHELPERS;
 
85
 
 
86
typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
 
87
 
 
88
 
 
89
#define VBOX_HGCM_SVC_PARM_INVALID (0U)
 
90
#define VBOX_HGCM_SVC_PARM_32BIT (1U)
 
91
#define VBOX_HGCM_SVC_PARM_64BIT (2U)
 
92
#define VBOX_HGCM_SVC_PARM_PTR   (3U)
 
93
 
 
94
typedef struct VBOXHGCMSVCPARM
 
95
{
 
96
    /** VBOX_HGCM_SVC_PARM_* values. */
 
97
    uint32_t type;
 
98
 
 
99
    union
 
100
    {
 
101
        uint32_t uint32;
 
102
        uint64_t uint64;
 
103
        struct
 
104
        {
 
105
            uint32_t size;
 
106
            void *addr;
 
107
        } pointer;
 
108
    } u;
 
109
#ifdef __cplusplus
 
110
    /** Extract a uint32_t value from an HGCM parameter structure */
 
111
    int getUInt32 (uint32_t *u32)
 
112
    {
 
113
        AssertPtrReturn(u32, VERR_INVALID_POINTER);
 
114
        int rc = VINF_SUCCESS;
 
115
        if (type != VBOX_HGCM_SVC_PARM_32BIT)
 
116
            rc = VERR_INVALID_PARAMETER;
 
117
        if (RT_SUCCESS(rc))
 
118
            *u32 = u.uint32;
 
119
        return rc;
 
120
    }
 
121
 
 
122
    /** Extract a uint64_t value from an HGCM parameter structure */
 
123
    int getUInt64 (uint64_t *u64)
 
124
    {
 
125
        AssertPtrReturn(u64, VERR_INVALID_POINTER);
 
126
        int rc = VINF_SUCCESS;
 
127
        if (type != VBOX_HGCM_SVC_PARM_64BIT)
 
128
            rc = VERR_INVALID_PARAMETER;
 
129
        if (RT_SUCCESS(rc))
 
130
            *u64 = u.uint64;
 
131
        return rc;
 
132
    }
 
133
 
 
134
    /** Extract a pointer value from an HGCM parameter structure */
 
135
    int getPointer (void **ppv, uint32_t *pcb)
 
136
    {
 
137
        AssertPtrReturn(ppv, VERR_INVALID_POINTER);
 
138
        AssertPtrReturn(pcb, VERR_INVALID_POINTER);
 
139
        if (type == VBOX_HGCM_SVC_PARM_PTR)
 
140
        {
 
141
            *ppv = u.pointer.addr;
 
142
            *pcb = u.pointer.size;
 
143
            return VINF_SUCCESS;
 
144
        }
 
145
 
 
146
        return VERR_INVALID_PARAMETER;
 
147
    }
 
148
 
 
149
    /** Extract a constant pointer value from an HGCM parameter structure */
 
150
    int getPointer (const void **ppcv, uint32_t *pcb)
 
151
    {
 
152
        AssertPtrReturn(ppcv, VERR_INVALID_POINTER);
 
153
        AssertPtrReturn(pcb, VERR_INVALID_POINTER);
 
154
        void *pv;
 
155
        int rc = getPointer(&pv, pcb);
 
156
        *ppcv = pv;
 
157
        return rc;
 
158
    }
 
159
 
 
160
    /** Extract a pointer value to a non-empty buffer from an HGCM parameter
 
161
     * structure */
 
162
    int getBuffer (void **ppv, uint32_t *pcb)
 
163
    {
 
164
        AssertPtrReturn(ppv, VERR_INVALID_POINTER);
 
165
        AssertPtrReturn(pcb, VERR_INVALID_POINTER);
 
166
        void *pv = NULL;
 
167
        uint32_t cb = 0;
 
168
        int rc = getPointer(&pv, &cb);
 
169
        if (   RT_SUCCESS(rc)
 
170
            && VALID_PTR(pv)
 
171
            && cb > 0)
 
172
        {
 
173
            *ppv = pv;
 
174
            *pcb = cb;
 
175
            return VINF_SUCCESS;
 
176
        }
 
177
 
 
178
        return VERR_INVALID_PARAMETER;
 
179
    }
 
180
 
 
181
    /** Extract a pointer value to a non-empty constant buffer from an HGCM
 
182
     * parameter structure */
 
183
    int getBuffer (const void **ppcv, uint32_t *pcb)
 
184
    {
 
185
        AssertPtrReturn(ppcv, VERR_INVALID_POINTER);
 
186
        AssertPtrReturn(pcb, VERR_INVALID_POINTER);
 
187
        void *pcv = NULL;
 
188
        int rc = getBuffer(&pcv, pcb);
 
189
        *ppcv = pcv;
 
190
        return rc;
 
191
    }
 
192
 
 
193
    /** Extract a string value from an HGCM parameter structure */
 
194
    int getString (char **ppch, uint32_t *pcb)
 
195
    {
 
196
        uint32_t cb = 0;
 
197
        char *pch = NULL;
 
198
        int rc = getBuffer((void **)&pch, &cb);
 
199
        if (RT_FAILURE(rc))
 
200
        {
 
201
            *ppch = NULL;
 
202
            *pcb = 0;
 
203
            return rc;
 
204
        }
 
205
        rc = RTStrValidateEncodingEx(pch, cb,
 
206
                                     RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
 
207
        *ppch = pch;
 
208
        *pcb = cb;
 
209
        return rc;
 
210
    }
 
211
 
 
212
    /** Extract a constant string value from an HGCM parameter structure */
 
213
    int getString (const char **ppch, uint32_t *pcb)
 
214
    {
 
215
        char *pch = NULL;
 
216
        int rc = getString(&pch, pcb);
 
217
        *ppch = pch;
 
218
        return rc;
 
219
    }
 
220
 
 
221
    /** Set a uint32_t value to an HGCM parameter structure */
 
222
    void setUInt32(uint32_t u32)
 
223
    {
 
224
        type = VBOX_HGCM_SVC_PARM_32BIT;
 
225
        u.uint32 = u32;
 
226
    }
 
227
 
 
228
    /** Set a uint64_t value to an HGCM parameter structure */
 
229
    void setUInt64(uint64_t u64)
 
230
    {
 
231
        type = VBOX_HGCM_SVC_PARM_64BIT;
 
232
        u.uint64 = u64;
 
233
    }
 
234
 
 
235
    /** Set a pointer value to an HGCM parameter structure */
 
236
    void setPointer(void *pv, uint32_t cb)
 
237
    {
 
238
        type = VBOX_HGCM_SVC_PARM_PTR;
 
239
        u.pointer.addr = pv;
 
240
        u.pointer.size = cb;
 
241
    }
 
242
 
 
243
    /** Set a const string value to an HGCM parameter structure */
 
244
    void setString(const char *psz)
 
245
    {
 
246
        type = VBOX_HGCM_SVC_PARM_PTR;
 
247
        u.pointer.addr = (void *)psz;
 
248
        u.pointer.size = (uint32_t)strlen(psz) + 1;
 
249
    }
 
250
 
 
251
#ifdef VBOX_TEST_HGCM_PARMS
 
252
    /** Test the getString member function.  Indirectly tests the getPointer
 
253
     * and getBuffer APIs.
 
254
     * @param  hTest  an running IPRT test
 
255
     * @param  aType  the type that the parameter should be set to before
 
256
     *                calling getString
 
257
     * @param  apcc   the value that the parameter should be set to before
 
258
     *                calling getString, and also the address (!) which we
 
259
     *                expect getString to return.  Stricter than needed of
 
260
     *                course, but I was feeling lazy.
 
261
     * @param  acb    the size that the parameter should be set to before
 
262
     *                calling getString, and also the size which we expect
 
263
     *                getString to return.
 
264
     * @param  rcExp  the expected return value of the call to getString.
 
265
     */
 
266
    void doTestGetString(RTTEST hTest, uint32_t aType, const char *apcc,
 
267
                         uint32_t acb, int rcExp)
 
268
    {
 
269
        /* An RTTest API like this, which would print out an additional line
 
270
         * of context if a test failed, would be nice.  This is because the
 
271
         * line number alone doesn't help much here, given that this is a
 
272
         * subroutine called many times. */
 
273
        /*
 
274
        RTTestContextF(hTest,
 
275
                       ("doTestGetString, aType=%u, apcc=%p, acp=%u, rcExp=%Rrc",
 
276
                        aType, apcc, acp, rcExp));
 
277
         */
 
278
        setPointer((void *)apcc, acb);
 
279
        type = aType;  /* in case we don't want VBOX_HGCM_SVC_PARM_PTR */
 
280
        const char *pcc = NULL;
 
281
        uint32_t cb = 0;
 
282
        int rc = getString(&pcc, &cb);
 
283
        RTTEST_CHECK_RC(hTest, rc, rcExp);
 
284
        if (RT_SUCCESS(rcExp))
 
285
        {
 
286
            RTTEST_CHECK_MSG_RETV(hTest, (pcc == apcc),
 
287
                                  (hTest, "expected %p, got %p", apcc, pcc));
 
288
            RTTEST_CHECK_MSG_RETV(hTest, (cb == acb),
 
289
                                  (hTest, "expected %u, got %u", acb, cb));
 
290
        }
 
291
    }
 
292
 
 
293
    /** Run some unit tests on the getString method and indirectly test
 
294
     * getPointer and getBuffer as well. */
 
295
    void testGetString(RTTEST hTest)
 
296
    {
 
297
        RTTestSub(hTest, "HGCM string parameter handling");
 
298
        doTestGetString(hTest, VBOX_HGCM_SVC_PARM_32BIT, "test", 3,
 
299
                        VERR_INVALID_PARAMETER);
 
300
        doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test", 5,
 
301
                        VINF_SUCCESS);
 
302
        doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test", 3,
 
303
                        VERR_BUFFER_OVERFLOW);
 
304
        doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test\xf0", 6,
 
305
                        VERR_INVALID_UTF8_ENCODING);
 
306
        doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test", 0,
 
307
                        VERR_INVALID_PARAMETER);
 
308
        doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, (const char *)0x1, 5,
 
309
                        VERR_INVALID_PARAMETER);
 
310
        RTTestSubDone(hTest);
 
311
    }
 
312
#endif
 
313
 
 
314
    VBOXHGCMSVCPARM() : type(VBOX_HGCM_SVC_PARM_INVALID) {}
 
315
#endif
 
316
} VBOXHGCMSVCPARM;
 
317
 
 
318
typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
 
319
 
 
320
#ifdef VBOX_WITH_CRHGSMI
 
321
typedef void * HGCMCVSHANDLE;
 
322
 
 
323
typedef DECLCALLBACK(void) HGCMHOSTFASTCALLCB (int32_t result, uint32_t u32Function, PVBOXHGCMSVCPARM pParam, void *pvContext);
 
324
typedef HGCMHOSTFASTCALLCB *PHGCMHOSTFASTCALLCB;
 
325
#endif
 
326
 
 
327
 
 
328
/** Service specific extension callback.
 
329
 *  This callback is called by the service to perform service specific operation.
 
330
 *
 
331
 * @param pvExtension The extension pointer.
 
332
 * @param u32Function What the callback is supposed to do.
 
333
 * @param pvParm      The function parameters.
 
334
 * @param cbParm      The size of the function parameters.
 
335
 */
 
336
typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
 
337
typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
 
338
 
 
339
/** The Service DLL entry points.
 
340
 *
 
341
 *  HGCM will call the DLL "VBoxHGCMSvcLoad"
 
342
 *  function and the DLL must fill in the VBOXHGCMSVCFNTABLE
 
343
 *  with function pointers.
 
344
 */
 
345
 
 
346
/* The structure is used in separately compiled binaries so an explicit packing is required. */
 
347
#pragma pack(1)
 
348
typedef struct _VBOXHGCMSVCFNTABLE
 
349
{
 
350
    /** Filled by HGCM */
 
351
 
 
352
    /** Size of the structure. */
 
353
    uint32_t                 cbSize;
 
354
 
 
355
    /** Version of the structure, including the helpers. */
 
356
    uint32_t                 u32Version;
 
357
 
 
358
    PVBOXHGCMSVCHELPERS      pHelpers;
 
359
 
 
360
    /** Filled by the service. */
 
361
 
 
362
    /** Size of client information the service want to have. */
 
363
    uint32_t                 cbClient;
 
364
#if ARCH_BITS == 64
 
365
    /** Ensure that the following pointers are properly aligned on 64-bit system. */
 
366
    uint32_t                 u32Alignment0;
 
367
#endif
 
368
 
 
369
    /** Uninitialize service */
 
370
    DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
 
371
 
 
372
    /** Inform the service about a client connection. */
 
373
    DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
 
374
 
 
375
    /** Inform the service that the client wants to disconnect. */
 
376
    DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
 
377
 
 
378
    /** Service entry point.
 
379
     *  Return code is passed to pfnCallComplete callback.
 
380
     */
 
381
    DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
 
382
 
 
383
    /** Host Service entry point meant for privileged features invisible to the guest.
 
384
     *  Return code is passed to pfnCallComplete callback.
 
385
     */
 
386
    DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
 
387
 
 
388
    /** Inform the service about a VM save operation. */
 
389
    DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
 
390
 
 
391
    /** Inform the service about a VM load operation. */
 
392
    DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
 
393
 
 
394
    /** Register a service extension callback. */
 
395
    DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
 
396
 
 
397
    /** User/instance data pointer for the service. */
 
398
    void *pvService;
 
399
 
 
400
} VBOXHGCMSVCFNTABLE;
 
401
#pragma pack()
 
402
 
 
403
 
 
404
/** Service initialization entry point. */
 
405
typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
 
406
typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
 
407
#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
 
408
 
 
409
#endif