VirtualBox

source: vbox/trunk/src/VBox/Storage/testcase/VDScript.h@ 103068

Last change on this file since 103068 was 99739, checked in by vboxsync, 19 months ago

*: doxygen corrections (mostly about removing @returns from functions returning void).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.8 KB
Line 
1/** @file
2 *
3 * VBox HDD container test utility - scripting engine.
4 */
5
6/*
7 * Copyright (C) 2013-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * SPDX-License-Identifier: GPL-3.0-only
26 */
27
28#ifndef VBOX_INCLUDED_SRC_testcase_VDScript_h
29#define VBOX_INCLUDED_SRC_testcase_VDScript_h
30#ifndef RT_WITHOUT_PRAGMA_ONCE
31# pragma once
32#endif
33
34/** Handle to the scripting context. */
35typedef struct VDSCRIPTCTXINT *VDSCRIPTCTX;
36/** Pointer to a scripting context handle. */
37typedef VDSCRIPTCTX *PVDSCRIPTCTX;
38
39/**
40 * Supprted primitive types in the scripting engine.
41 */
42typedef enum VDSCRIPTTYPE
43{
44 /** Invalid type, do not use. */
45 VDSCRIPTTYPE_INVALID = 0,
46 /** void type, used for no return value of methods. */
47 VDSCRIPTTYPE_VOID,
48 /** unsigned 8bit integer. */
49 VDSCRIPTTYPE_UINT8,
50 VDSCRIPTTYPE_INT8,
51 VDSCRIPTTYPE_UINT16,
52 VDSCRIPTTYPE_INT16,
53 VDSCRIPTTYPE_UINT32,
54 VDSCRIPTTYPE_INT32,
55 VDSCRIPTTYPE_UINT64,
56 VDSCRIPTTYPE_INT64,
57 VDSCRIPTTYPE_STRING,
58 VDSCRIPTTYPE_BOOL,
59 VDSCRIPTTYPE_POINTER,
60 /** As usual, the 32bit blowup hack. */
61 VDSCRIPTTYPE_32BIT_HACK = 0x7fffffff
62} VDSCRIPTTYPE;
63/** Pointer to a type. */
64typedef VDSCRIPTTYPE *PVDSCRIPTTYPE;
65/** Pointer to a const type. */
66typedef const VDSCRIPTTYPE *PCVDSCRIPTTYPE;
67
68/**
69 * Script argument.
70 */
71typedef struct VDSCRIPTARG
72{
73 /** Type of the argument. */
74 VDSCRIPTTYPE enmType;
75 /** Value */
76 union
77 {
78 uint8_t u8;
79 int8_t i8;
80 uint16_t u16;
81 int16_t i16;
82 uint32_t u32;
83 int32_t i32;
84 uint64_t u64;
85 int64_t i64;
86 const char *psz;
87 bool f;
88 void *p;
89 };
90} VDSCRIPTARG;
91/** Pointer to an argument. */
92typedef VDSCRIPTARG *PVDSCRIPTARG;
93
94/** Script callback. */
95typedef DECLCALLBACKTYPE(int, FNVDSCRIPTCALLBACK,(PVDSCRIPTARG paScriptArgs, void *pvUser));
96/** Pointer to a script callback. */
97typedef FNVDSCRIPTCALLBACK *PFNVDSCRIPTCALLBACK;
98
99/**
100 * Callback registration structure.
101 */
102typedef struct VDSCRIPTCALLBACK
103{
104 /** The function name. */
105 const char *pszFnName;
106 /** The return type of the function. */
107 VDSCRIPTTYPE enmTypeReturn;
108 /** Pointer to the array of argument types. */
109 PCVDSCRIPTTYPE paArgs;
110 /** Number of arguments this method takes. */
111 unsigned cArgs;
112 /** The callback handler. */
113 PFNVDSCRIPTCALLBACK pfnCallback;
114} VDSCRIPTCALLBACK;
115/** Pointer to a callback register entry. */
116typedef VDSCRIPTCALLBACK *PVDSCRIPTCALLBACK;
117/** Pointer to a const callback register entry. */
118typedef const VDSCRIPTCALLBACK *PCVDSCRIPTCALLBACK;
119
120/**
121 * @{
122 */
123/** The address space stays assigned to a variable
124 * even if the pointer is casted to another type.
125 */
126#define VDSCRIPT_AS_FLAGS_TRANSITIVE RT_BIT(0)
127/** @} */
128
129/**
130 * Address space read callback
131 *
132 * @returns VBox status code.
133 * @param pvUser Opaque user data given on registration.
134 * @param Address The address to read from, address is stored in the member for
135 * base type given on registration.
136 * @param pvBuf Where to store the read bits.
137 * @param cbRead How much to read.
138 */
139typedef DECLCALLBACKTYPE(int, FNVDSCRIPTASREAD,(void *pvUser, VDSCRIPTARG Address, void *pvBuf, size_t cbRead));
140/** Pointer to a read callback. */
141typedef FNVDSCRIPTASREAD *PFNVDSCRIPTASREAD;
142
143/**
144 * Address space write callback
145 *
146 * @returns VBox status code.
147 * @param pvUser Opaque user data given on registration.
148 * @param Address The address to write to, address is stored in the member for
149 * base type given on registration.
150 * @param pvBuf Data to write.
151 * @param cbWrite How much to write.
152 */
153typedef DECLCALLBACKTYPE(int, FNVDSCRIPTASWRITE,(void *pvUser, VDSCRIPTARG Address, const void *pvBuf, size_t cbWrite));
154/** Pointer to a write callback. */
155typedef FNVDSCRIPTASWRITE *PFNVDSCRIPTASWRITE;
156
157/**
158 * Create a new scripting context.
159 *
160 * @returns VBox status code.
161 * @param phScriptCtx Where to store the scripting context on success.
162 */
163DECLHIDDEN(int) VDScriptCtxCreate(PVDSCRIPTCTX phScriptCtx);
164
165/**
166 * Destroys the given scripting context.
167 *
168 * @param hScriptCtx The script context to destroy.
169 */
170DECLHIDDEN(void) VDScriptCtxDestroy(VDSCRIPTCTX hScriptCtx);
171
172/**
173 * Register callbacks for the scripting context.
174 *
175 * @returns VBox status code.
176 * @param hScriptCtx The script context handle.
177 * @param paCallbacks Pointer to the callbacks to register.
178 * @param cCallbacks Number of callbacks in the array.
179 * @param pvUser Opaque user data to pass on the callback invocation.
180 */
181DECLHIDDEN(int) VDScriptCtxCallbacksRegister(VDSCRIPTCTX hScriptCtx, PCVDSCRIPTCALLBACK paCallbacks,
182 unsigned cCallbacks, void *pvUser);
183
184/**
185 * Load a given script into the context.
186 *
187 * @returns VBox status code.
188 * @param hScriptCtx The script context handle.
189 * @param pszScript Pointer to the char buffer containing the script.
190 */
191DECLHIDDEN(int) VDScriptCtxLoadScript(VDSCRIPTCTX hScriptCtx, const char *pszScript);
192
193/**
194 * Execute a given method in the script context.
195 *
196 * @returns VBox status code.
197 * @param hScriptCtx The script context handle.
198 * @param pszFnCall The method to call.
199 * @param paArgs Pointer to arguments to pass.
200 * @param cArgs Number of arguments.
201 */
202DECLHIDDEN(int) VDScriptCtxCallFn(VDSCRIPTCTX hScriptCtx, const char *pszFnCall,
203 PVDSCRIPTARG paArgs, unsigned cArgs);
204
205/**
206 * Registers a new address space provider.
207 *
208 * @returns VBox status code.
209 * @param hScriptCtx The script context handle.
210 * @param pszType The type string.
211 * @param enmBaseType The base integer type to use for the address space.
212 * Bool and String are not supported of course.
213 * @param pfnRead The read callback for the registered address space.
214 * @param pfnWrite The write callback for the registered address space.
215 * @param pvUser Opaque user data to pass to the read and write callbacks.
216 * @param fFlags Flags, see VDSCRIPT_AS_FLAGS_*.
217 *
218 * @note This will automatically register a new type with the identifier given in pszType
219 * used for the pointer. Every variable with this type is automatically treated as a pointer.
220 *
221 * @note If the transitive flag is set the address space stays assigned even if the pointer value
222 * is casted to another pointer type.
223 * In the following example the pointer pStruct will use the registered address space for RTGCPHYS
224 * and dereferencing the pointer causes the read/write callbacks to be triggered.
225 *
226 * ...
227 * Struct *pStruct = (Struct *)(RTGCPHYS)0x12345678;
228 * pStruct->count++;
229 * ...
230 */
231DECLHIDDEN(int) VDScriptCtxAsRegister(VDSCRIPTCTX hScriptCtx, const char *pszType, VDSCRIPTTYPE enmBaseType,
232 PFNVDSCRIPTASREAD pfnRead, PFNVDSCRIPTASWRITE pfnWrite, void *pvUser,
233 uint32_t fFlags);
234
235#endif /* !VBOX_INCLUDED_SRC_testcase_VDScript_h */
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