VirtualBox

source: vbox/trunk/include/VBox/usblib.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.8 KB
Line 
1/** @file
2 * USBLib - Library for wrapping up the VBoxUSB functionality. (DEV,HDrv,Main)
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_usblib_h
37#define VBOX_INCLUDED_usblib_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <VBox/cdefs.h>
43#include <VBox/types.h>
44#include <VBox/usb.h>
45#include <VBox/usbfilter.h>
46#include <iprt/ctype.h>
47#include <iprt/string.h>
48
49#ifdef RT_OS_WINDOWS
50# include <VBox/usblib-win.h>
51#endif
52#ifdef RT_OS_SOLARIS
53# include <VBox/usblib-solaris.h>
54#endif
55#ifdef RT_OS_DARWIN
56# include <VBox/usblib-darwin.h>
57#endif
58/** @todo merge the usblib-win.h interface into the darwin and linux ports where suitable. */
59
60RT_C_DECLS_BEGIN
61/** @defgroup grp_usblib USBLib - USB Support Library
62 * This module implements the basic low-level OS interfaces and common USB code.
63 * @{
64 */
65
66#ifdef IN_RING3
67/**
68 * Initializes the USBLib component.
69 *
70 * The USBLib keeps a per process connection to the kernel driver
71 * and all USBLib users within a process will share the same
72 * connection. USBLib does reference counting to make sure that
73 * the connection remains open until all users has called USBLibTerm().
74 *
75 * @returns VBox status code.
76 *
77 * @remark The users within the process are responsible for not calling
78 * this function at the same time (because I'm lazy).
79 */
80USBLIB_DECL(int) USBLibInit(void);
81
82/**
83 * Terminates the USBLib component.
84 *
85 * Must match successful USBLibInit calls.
86 *
87 * @returns VBox status code.
88 */
89USBLIB_DECL(int) USBLibTerm(void);
90
91/**
92 * Adds a filter.
93 *
94 * This function will validate and transfer the specified filter
95 * to the kernel driver and make it start using it. The kernel
96 * driver will return a filter id that this function passes on
97 * to its caller.
98 *
99 * The kernel driver will associate the added filter with the
100 * calling process and automatically remove all filters when
101 * the process terminates the connection to it or dies.
102 *
103 * @returns Filter id for passing to USBLibRemoveFilter on success.
104 * @returns NULL on failure.
105 *
106 * @param pFilter The filter to add.
107 */
108USBLIB_DECL(void *) USBLibAddFilter(PCUSBFILTER pFilter);
109
110/**
111 * Removes a filter.
112 *
113 * @param pvId The ID returned by USBLibAddFilter.
114 */
115USBLIB_DECL(void) USBLibRemoveFilter(void *pvId);
116
117/**
118 * Calculate the hash of the serial string.
119 *
120 * 64bit FNV1a, chosen because it is designed to hash in to a power of two
121 * space, and is much quicker and simpler than, say, a half MD4.
122 *
123 * @returns the hash.
124 * @param pszSerial The serial string.
125 */
126USBLIB_DECL(uint64_t) USBLibHashSerial(const char *pszSerial);
127
128#endif /* IN_RING3 */
129
130/**
131 * Purge string of non-UTF-8 encodings and control characters.
132 *
133 * Control characters creates problems when presented to the user and currently
134 * also when used in XML settings. So, we must purge them in the USB vendor,
135 * product, and serial number strings.
136 *
137 * @returns String length (excluding terminator).
138 * @param psz The string to purge.
139 *
140 * @remarks The return string may be shorter than the input, left over space
141 * after the end of the string will be filled with zeros.
142 */
143DECLINLINE(size_t) USBLibPurgeEncoding(char *psz)
144{
145 if (psz)
146 {
147 size_t offSrc;
148
149 /* Beat it into valid UTF-8 encoding. */
150 RTStrPurgeEncoding(psz);
151
152 /* Look for control characters. */
153 for (offSrc = 0; ; offSrc++)
154 {
155 char ch = psz[offSrc];
156 if (RT_UNLIKELY(RT_C_IS_CNTRL(ch) && ch != '\0'))
157 {
158 /* Found a control character! Replace tab by space and remove all others. */
159 size_t offDst = offSrc;
160 for (;; offSrc++)
161 {
162 ch = psz[offSrc];
163 if (RT_C_IS_CNTRL(ch) && ch != '\0')
164 {
165 if (ch == '\t')
166 ch = ' ';
167 else
168 continue;
169 }
170 psz[offDst++] = ch;
171 if (ch == '\0')
172 break;
173 }
174
175 /* Wind back to the zero terminator and zero fill any gap to make
176 USBFilterValidate happy. (offSrc is at zero terminator too.) */
177 offDst--;
178 while (offSrc > offDst)
179 psz[offSrc--] = '\0';
180
181 return offDst;
182 }
183 if (ch == '\0')
184 break;
185 }
186 return offSrc;
187 }
188 return 0;
189}
190
191
192/** @} */
193RT_C_DECLS_END
194
195#endif /* !VBOX_INCLUDED_usblib_h */
196
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