UsbTestServiceGadget.h@ 96407

Last change on this file since 96407 was 96407, checked in by vboxsync, 2 years ago
scm copyright and license note update
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.3 KB

Line
1	/* $Id: UsbTestServiceGadget.h 96407 2022-08-22 17:43:14Z vboxsync $ */
2	/** @file
3	* UsbTestServ - Remote USB test configuration and execution server, Gadget API.
4	*/
5
6	/*
7	* Copyright (C) 2016-2022 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	* The contents of this file may alternatively be used under the terms
26	* of the Common Development and Distribution License Version 1.0
27	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28	* in the VirtualBox distribution, in which case the provisions of the
29	* CDDL are applicable instead of those of the GPL.
30	*
31	* You may elect to license modified versions of this file under the
32	* terms and conditions of either the GPL or the CDDL or both.
33	*
34	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35	*/
36
37	#ifndef VBOX_INCLUDED_SRC_usb_UsbTestServiceGadget_h
38	#define VBOX_INCLUDED_SRC_usb_UsbTestServiceGadget_h
39	#ifndef RT_WITHOUT_PRAGMA_ONCE
40	# pragma once
41	#endif
42
43	#include <iprt/cdefs.h>
44	#include <iprt/types.h>
45
46	RT_C_DECLS_BEGIN
47
48	/** Opaque gadget host handle. */
49	typedef struct UTSGADGETHOSTINT *UTSGADGETHOST;
50	/** Pointer to a gadget host handle. */
51	typedef UTSGADGETHOST *PUTSGADGETHOST;
52
53	/** NIL gadget host handle. */
54	#define NIL_UTSGADGETHOST ((UTSGADGETHOST)0)
55
56	/** Opaque USB gadget handle. */
57	typedef struct UTSGADGETINT *UTSGADGET;
58	/** Pointer to a USB gadget handle. */
59	typedef UTSGADGET *PUTSGADET;
60
61	/** NIL gadget handle. */
62	#define NIL_UTSGADGET ((UTSGADGET)0)
63
64	/**
65	* Gadget/Gadget host configuration item type.
66	*/
67	typedef enum UTSGADGETCFGTYPE
68	{
69	/** Don't use! */
70	UTSGADGETCFGTYPE_INVALID = 0,
71	/** Boolean type. */
72	UTSGADGETCFGTYPE_BOOLEAN,
73	/** UTF-8 string. */
74	UTSGADGETCFGTYPE_STRING,
75	/** Unsigned 8bit integer. */
76	UTSGADGETCFGTYPE_UINT8,
77	/** Unsigned 16bit integer. */
78	UTSGADGETCFGTYPE_UINT16,
79	/** Unsigned 32bit integer. */
80	UTSGADGETCFGTYPE_UINT32,
81	/** Unsigned 64bit integer. */
82	UTSGADGETCFGTYPE_UINT64,
83	/** Signed 8bit integer. */
84	UTSGADGETCFGTYPE_INT8,
85	/** Signed 16bit integer. */
86	UTSGADGETCFGTYPE_INT16,
87	/** Signed 32bit integer. */
88	UTSGADGETCFGTYPE_INT32,
89	/** Signed 64bit integer. */
90	UTSGADGETCFGTYPE_INT64,
91	/** 32bit hack. */
92	UTSGADGETCFGTYPE_32BIT_HACK = 0x7fffffff
93	} UTSGADGETCFGTYPE;
94
95	/**
96	* Gadget configuration value.
97	*/
98	typedef struct UTSGADGETCFGVAL
99	{
100	/** Value type */
101	UTSGADGETCFGTYPE enmType;
102	/** Value based on the type. */
103	union
104	{
105	bool f;
106	const char *psz;
107	uint8_t u8;
108	uint16_t u16;
109	uint32_t u32;
110	uint64_t u64;
111	int8_t i8;
112	int16_t i16;
113	int32_t i32;
114	int64_t i64;
115	} u;
116	} UTSGADGETCFGVAL;
117	/** Pointer to a gadget configuration value. */
118	typedef UTSGADGETCFGVAL *PUTSGADGETCFGVAL;
119	/** Pointer to a const gadget configuration value. */
120	typedef const UTSGADGETCFGVAL *PCUTSGADGETCFGVAL;
121
122	/**
123	* Gadget configuration item.
124	*/
125	typedef struct UTSGADGETCFGITEM
126	{
127	/** Item key. */
128	const char *pszKey;
129	/** Item value. */
130	UTSGADGETCFGVAL Val;
131	} UTSGADGETCFGITEM;
132	/** Pointer to a gadget configuration item. */
133	typedef UTSGADGETCFGITEM *PUTSGADGETCFGITEM;
134	/** Pointer to a const gadget configuration item. */
135	typedef const UTSGADGETCFGITEM *PCUTSGADGETCFGITEM;
136
137	/**
138	* Type for the gadget host.
139	*/
140	typedef enum UTSGADGETHOSTTYPE
141	{
142	/** Invalid type, don't use. */
143	UTSGADGETHOSTTYPE_INVALID = 0,
144	/** USB/IP host, gadgets are exported using a USB/IP server. */
145	UTSGADGETHOSTTYPE_USBIP,
146	/** Physical connection using a device or OTG port. */
147	UTSGADGETHOSTTYPE_PHYSICAL,
148	/** 32bit hack. */
149	UTSGADGETHOSTTYPE_32BIT_HACK = 0x7fffffff
150	} UTSGADGETHOSTTYPE;
151
152	/**
153	* USB gadget class.
154	*/
155	typedef enum UTSGADGETCLASS
156	{
157	/** Invalid class, don't use. */
158	UTSGADGETCLASS_INVALID = 0,
159	/** Special test device class. */
160	UTSGADGETCLASS_TEST,
161	/** MSD device. */
162	UTSGADGETCLASS_MSD,
163	/** 32bit hack. */
164	UTSGADGETCLASS_32BIT_HACK = 0x7fffffff
165	} UTSGADGETCLASS;
166
167	/**
168	* Queries the value of a given boolean key from the given configuration array.
169	*
170	* @returns IPRT status code.
171	* @param paCfg The configuration items.
172	* @param pszKey The key query the value for.
173	* @param pf Where to store the value on success.
174	*/
175	DECLHIDDEN(int) utsGadgetCfgQueryBool(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
176	bool *pf);
177
178	/**
179	* Queries the value of a given boolean key from the given configuration array,
180	* setting a default if not found.
181	*
182	* @returns IPRT status code.
183	* @param paCfg The configuration items.
184	* @param pszKey The key query the value for.
185	* @param pf Where to store the value on success.
186	* @param fDef The default value to assign if the key is not found.
187	*/
188	DECLHIDDEN(int) utsGadgetCfgQueryBoolDef(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
189	bool *pf, bool fDef);
190
191	/**
192	* Queries the string value of a given key from the given configuration array.
193	*
194	* @returns IPRT status code.
195	* @param paCfg The configuration items.
196	* @param pszKey The key query the value for.
197	* @param ppszVal Where to store the pointer to the string on success,
198	* must be freed with RTStrFree().
199	*/
200	DECLHIDDEN(int) utsGadgetCfgQueryString(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
201	char **ppszVal);
202
203	/**
204	* Queries the string value of a given key from the given configuration array,
205	* setting a default if not found.
206	*
207	* @returns IPRT status code.
208	* @param paCfg The configuration items.
209	* @param pszKey The key query the value for.
210	* @param ppszVal Where to store the pointer to the string on success,
211	* must be freed with RTStrFree().
212	* @param pszDef The default value to assign if the key is not found.
213	*/
214	DECLHIDDEN(int) utsGadgetCfgQueryStringDef(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
215	char *ppszVal, const char pszDef);
216
217	/**
218	* Queries the value of a given uint8_t key from the given configuration array.
219	*
220	* @returns IPRT status code.
221	* @param paCfg The configuration items.
222	* @param pszKey The key query the value for.
223	* @param pu8 Where to store the value on success.
224	*/
225	DECLHIDDEN(int) utsGadgetCfgQueryU8(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
226	uint8_t *pu8);
227
228	/**
229	* Queries the value of a given uint8_t key from the given configuration array,
230	* setting a default if not found.
231	*
232	* @returns IPRT status code.
233	* @param paCfg The configuration items.
234	* @param pszKey The key query the value for.
235	* @param pu8 Where to store the value on success.
236	* @param u8Def The default value to assign if the key is not found.
237	*/
238	DECLHIDDEN(int) utsGadgetCfgQueryU8Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
239	uint8_t *pu8, uint8_t u8Def);
240
241	/**
242	* Queries the value of a given uint16_t key from the given configuration array.
243	*
244	* @returns IPRT status code.
245	* @param paCfg The configuration items.
246	* @param pszKey The key query the value for.
247	* @param pu16 Where to store the value on success.
248	*/
249	DECLHIDDEN(int) utsGadgetCfgQueryU16(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
250	uint16_t *pu16);
251
252	/**
253	* Queries the value of a given uint16_t key from the given configuration array,
254	* setting a default if not found.
255	*
256	* @returns IPRT status code.
257	* @param paCfg The configuration items.
258	* @param pszKey The key query the value for.
259	* @param pu16 Where to store the value on success.
260	* @param u16Def The default value to assign if the key is not found.
261	*/
262	DECLHIDDEN(int) utsGadgetCfgQueryU16Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
263	uint16_t *pu16, uint16_t u16Def);
264
265	/**
266	* Queries the value of a given uint32_t key from the given configuration array.
267	*
268	* @returns IPRT status code.
269	* @param paCfg The configuration items.
270	* @param pszKey The key query the value for.
271	* @param pu32 Where to store the value on success.
272	*/
273	DECLHIDDEN(int) utsGadgetCfgQueryU32(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
274	uint32_t *pu32);
275
276	/**
277	* Queries the value of a given uint32_t key from the given configuration array,
278	* setting a default if not found.
279	*
280	* @returns IPRT status code.
281	* @param paCfg The configuration items.
282	* @param pszKey The key query the value for.
283	* @param pu32 Where to store the value on success.
284	* @param u32Def The default value to assign if the key is not found.
285	*/
286	DECLHIDDEN(int) utsGadgetCfgQueryU32Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
287	uint32_t *pu32, uint32_t u32Def);
288
289	/**
290	* Queries the value of a given uint64_t key from the given configuration array.
291	*
292	* @returns IPRT status code.
293	* @param paCfg The configuration items.
294	* @param pszKey The key query the value for.
295	* @param pu64 Where to store the value on success.
296	*/
297	DECLHIDDEN(int) utsGadgetCfgQueryU64(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
298	uint64_t *pu64);
299
300	/**
301	* Queries the value of a given uint64_t key from the given configuration array,
302	* setting a default if not found.
303	*
304	* @returns IPRT status code.
305	* @param paCfg The configuration items.
306	* @param pszKey The key query the value for.
307	* @param pu64 Where to store the value on success.
308	* @param u64Def The default value to assign if the key is not found.
309	*/
310	DECLHIDDEN(int) utsGadgetCfgQueryU64Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
311	uint64_t *pu64, uint64_t u64Def);
312
313	/**
314	* Queries the value of a given int8_t key from the given configuration array.
315	*
316	* @returns IPRT status code.
317	* @param paCfg The configuration items.
318	* @param pszKey The key query the value for.
319	* @param pi8 Where to store the value on success.
320	*/
321	DECLHIDDEN(int) utsGadgetCfgQueryS8(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
322	int8_t *pi8);
323
324	/**
325	* Queries the value of a given int8_t key from the given configuration array,
326	* setting a default if not found.
327	*
328	* @returns IPRT status code.
329	* @param paCfg The configuration items.
330	* @param pszKey The key query the value for.
331	* @param pi8 Where to store the value on success.
332	* @param i8Def The default value to assign if the key is not found.
333	*/
334	DECLHIDDEN(int) utsGadgetCfgQueryS8Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
335	int8_t *pi8, uint8_t i8Def);
336
337	/**
338	* Queries the value of a given int16_t key from the given configuration array.
339	*
340	* @returns IPRT status code.
341	* @param paCfg The configuration items.
342	* @param pszKey The key query the value for.
343	* @param pi16 Where to store the value on success.
344	*/
345	DECLHIDDEN(int) utsGadgetCfgQueryS16(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
346	uint16_t *pi16);
347
348	/**
349	* Queries the value of a given int16_t key from the given configuration array,
350	* setting a default if not found.
351	*
352	* @returns IPRT status code.
353	* @param paCfg The configuration items.
354	* @param pszKey The key query the value for.
355	* @param pi16 Where to store the value on success.
356	* @param i16Def The default value to assign if the key is not found.
357	*/
358	DECLHIDDEN(int) utsGadgetCfgQueryS16Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
359	uint16_t *pi16, uint16_t i16Def);
360
361	/**
362	* Queries the value of a given int32_t key from the given configuration array.
363	*
364	* @returns IPRT status code.
365	* @param paCfg The configuration items.
366	* @param pszKey The key query the value for.
367	* @param pi32 Where to store the value on success.
368	*/
369	DECLHIDDEN(int) utsGadgetCfgQueryS32(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
370	uint32_t *pi32);
371
372	/**
373	* Queries the value of a given int32_t key from the given configuration array,
374	* setting a default if not found.
375	*
376	* @returns IPRT status code.
377	* @param paCfg The configuration items.
378	* @param pszKey The key query the value for.
379	* @param pi32 Where to store the value on success.
380	* @param i32Def The default value to assign if the key is not found.
381	*/
382	DECLHIDDEN(int) utsGadgetCfgQueryS32Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
383	uint32_t *pi32, uint32_t i32Def);
384
385	/**
386	* Queries the value of a given int64_t key from the given configuration array.
387	*
388	* @returns IPRT status code.
389	* @param paCfg The configuration items.
390	* @param pszKey The key query the value for.
391	* @param pi64 Where to store the value on success.
392	*/
393	DECLHIDDEN(int) utsGadgetCfgQueryS64(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
394	uint64_t *pi64);
395
396	/**
397	* Queries the value of a given int64_t key from the given configuration array,
398	* setting a default if not found.
399	*
400	* @returns IPRT status code.
401	* @param paCfg The configuration items.
402	* @param pszKey The key query the value for.
403	* @param pi64 Where to store the value on success.
404	* @param i64Def The default value to assign if the key is not found.
405	*/
406	DECLHIDDEN(int) utsGadgetCfgQueryS64Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
407	uint64_t *pi64, uint64_t i64Def);
408
409	/**
410	* Creates a new USB gadget host.
411	*
412	* @returns IPRT status code.
413	* @param enmType The host type.
414	* @param paCfg Additional configuration parameters - optional.
415	* The array must be terminated with a NULL entry.
416	* @param phGadgetHost Where to store the handle to the gadget host on success.
417	*/
418	DECLHIDDEN(int) utsGadgetHostCreate(UTSGADGETHOSTTYPE enmType, PCUTSGADGETCFGITEM paCfg,
419	PUTSGADGETHOST phGadgetHost);
420
421	/**
422	* Retains the given gadget host handle.
423	*
424	* @returns New reference count.
425	* @param hGadgetHost The gadget host handle to retain.
426	*/
427	DECLHIDDEN(uint32_t) utsGadgetHostRetain(UTSGADGETHOST hGadgetHost);
428
429	/**
430	* Releases the given gadget host handle, destroying it if the reference
431	* count reaches 0.
432	*
433	* @returns New reference count.
434	* @param hGadgetHost The gadget host handle to release.
435	*/
436	DECLHIDDEN(uint32_t) utsGadgetHostRelease(UTSGADGETHOST hGadgetHost);
437
438	/**
439	* Returns the current config of the given gadget host.
440	*
441	* @returns Pointer to a constant array of configuration items for the given gadget host.
442	* @param hGadgetHost The gadget host handle.
443	*/
444	DECLHIDDEN(PCUTSGADGETCFGITEM) utsGadgetHostGetCfg(UTSGADGETHOST hGadgetHost);
445
446	/**
447	* Connects the given gadget to the host.
448	*
449	* @returns IPRT status code.
450	* @param hGadgetHost The gadget host handle.
451	* @param hGadget The gadget handle.
452	*/
453	DECLHIDDEN(int) utsGadgetHostGadgetConnect(UTSGADGETHOST hGadgetHost, UTSGADGET hGadget);
454
455	/**
456	* Disconnects the given gadget from the host.
457	*
458	* @returns IPRT status code.
459	* @param hGadgetHost The gadget host handle.
460	* @param hGadget The gadget handle.
461	*/
462	DECLHIDDEN(int) utsGadgetHostGadgetDisconnect(UTSGADGETHOST hGadgetHost, UTSGADGET hGadget);
463
464	/**
465	* Creates a new USB gadget based the class.
466	*
467	* @returns IPRT status code.
468	* @param hGadgetHost The gadget host the gadget is part of.
469	* @param enmClass The gadget class.
470	* @param paCfg Array of optional configuration items for the gadget.
471	* @param phGadget Where to store the gadget handle on success.
472	*/
473	DECLHIDDEN(int) utsGadgetCreate(UTSGADGETHOST hGadgetHost, UTSGADGETCLASS enmClass,
474	PCUTSGADGETCFGITEM paCfg, PUTSGADET phGadget);
475
476	/**
477	* Retains the given gadget handle.
478	*
479	* @returns New reference count.
480	* @param hGadget The gadget handle to retain.
481	*/
482	DECLHIDDEN(uint32_t) utsGadgetRetain(UTSGADGET hGadget);
483
484	/**
485	* Releases the given gadget handle, destroying it if the reference
486	* count reaches 0.
487	*
488	* @returns New reference count.
489	* @param hGadget The gadget handle to destroy.
490	*/
491	DECLHIDDEN(uint32_t) utsGadgetRelease(UTSGADGET hGadget);
492
493	/**
494	* Returns the current config of the given gadget.
495	*
496	* @returns Pointer to a constant array of configuration items for the given gadget.
497	* @param hGadget The gadget handle.
498	*/
499	DECLHIDDEN(PCUTSGADGETCFGITEM) utsGadgetGetCfg(UTSGADGET hGadget);
500
501	/**
502	* Returns the path of the given gadget from which it can be accessed.
503	*
504	* @returns Access path.
505	* @param hGadget The gadget handle.
506	*/
507	DECLHIDDEN(const char *) utsGadgetGetAccessPath(UTSGADGET hGadget);
508
509	/**
510	* Returns the bus ID the gadget is on.
511	*
512	* @returns Bus ID of the gadget.
513	* @param hGadget The gadget handle.
514	*/
515	DECLHIDDEN(uint32_t) utsGadgetGetBusId(UTSGADGET hGadget);
516
517	/**
518	* Returns the device ID of the gagdet.
519	*
520	* @returns Device ID of the gadget.
521	* @param hGadget The gadget handle.
522	*/
523	DECLHIDDEN(uint32_t) utsGadgetGetDevId(UTSGADGET hGadget);
524
525	/**
526	* Mark the gadget as connected to the host. Depending
527	* on the host type it will be appear as physically attached
528	* or will appear in the exported USB device list.
529	*
530	* @returns IPRT status code.
531	* @param hGadget The gadget handle to connect.
532	*/
533	DECLHIDDEN(int) utsGadgetConnect(UTSGADGET hGadget);
534
535	/**
536	* Mark the gadget as disconnected from the host.
537	*
538	* @returns IPRT status code.
539	* @param hGadget The gadget handle to disconnect.
540	*/
541	DECLHIDDEN(int) utsGadgetDisconnect(UTSGADGET hGadget);
542
543	RT_C_DECLS_END
544
545	#endif /* !VBOX_INCLUDED_SRC_usb_UsbTestServiceGadget_h */
546

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/ValidationKit/utils/usb/UsbTestServiceGadget.h@ 96407

Download in other formats: