VirtualBox

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

Last change on this file since 74102 was 69107, checked in by vboxsync, 7 years ago

include/VBox/: (C) year

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