UsbTestServiceGadget.h@ 62471

Last change on this file since 62471 was 62471, checked in by vboxsync, 8 years ago
Misc: scm
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 17.9 KB

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

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

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

Download in other formats: