UsbTestServiceGadget.h@ 90488

Last change on this file since 90488 was 82968, checked in by vboxsync, 5 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.0 KB

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

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

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

Download in other formats: