UsbTestServiceGadget.h@ 60324

Last change on this file since 60324 was 60324, checked in by vboxsync, 9 years ago
ValidationKit/usb/UsbTestService: Updates, start implementing the USB/IP specific interfaces (laptop -> desktop)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.9 KB

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

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

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

Download in other formats: