1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/* * 17 * @addtogroup HdiUsb 18 * @{ 19 * 20 * @brief Provides unified APIs for usb services to access usb drivers. 21 * 22 * A usb service can obtain a usb driver object or agent and then call APIs provided by this object or agent to 23 * access different types of usb devices based on the usb IDs, thereby obtaining usb information, 24 * subscribing to or unsubscribing from usb data, enabling or disabling a usb, 25 * setting the usb data reporting mode, and setting usb options such as the accuracy and measurement range. 26 * 27 * @since 3.2 28 */ 29 30/* * 31 * @file IUsbInterface.idl 32 * 33 * @brief Declares the APIs provided by the usb module for obtaining usb information, subscribing to or 34 * unsubscribing from usb data, enabling or disabling a usb, setting the usb data reporting mode, 35 * and setting usb options such as the accuracy and measurement range. 36 * 37 * @since 3.2 38 * @version 1.0 39 */ 40 41package ohos.hdi.usb.v1_0; 42 43import ohos.hdi.usb.v1_0.UsbTypes; 44import ohos.hdi.usb.v1_0.IUsbdSubscriber; 45import ohos.hdi.usb.v1_0.IUsbdBulkCallback; 46 47/* * 48 * @brief Defines the functions for performing basic operations on usb. 49 * 50 * The operations include obtaining usb information, subscribing to or unsubscribing from usb data, 51 * enabling or disabling a usb, setting the usb data reporting mode, and setting usb options such as 52 * the accuracy and measurement range. 53 */ 54interface IUsbInterface { 55 56 /* * 57 * @brief Opens a USB device to set up a connection. 58 * 59 * @param dev Indicates the USB device address. 60 * 61 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 62 * @since 3.2 63 */ 64 OpenDevice([in] struct UsbDev dev); 65 66 /* * 67 * @brief Closes a USB device to release all system resources related to the device. 68 * 69 * @param dev Indicates the USB device address. 70 * 71 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 72 * @since 3.2 73 */ 74 CloseDevice([in] struct UsbDev dev); 75 76 /* * 77 * @brief Obtains the USB device descriptor. 78 * 79 * @param dev Indicates the USB device address. 80 * @param descriptor Indicates the USB device descriptor. 81 * 82 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 83 * @since 3.2 84 */ 85 GetDeviceDescriptor([in] struct UsbDev dev, [out] unsigned char[] descriptor); 86 87 /* * 88 * @brief Obtains the string descriptor of a USB device based on the specified string ID. 89 * 90 * @param dev Indicates the USB device address. 91 * @param descId Indicates string descriptor ID. 92 * @param descriptor Indicates the configuration descriptor of the USB device. 93 * 94 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 95 * @since 3.2 96 */ 97 GetStringDescriptor([in] struct UsbDev dev, [in] unsigned char descId, [out] unsigned char[] descriptor); 98 99 /* * 100 * @brief Obtains the configuration descriptor of a USB device based on the specified config ID. 101 * 102 * @param dev Indicates the USB device address. 103 * @param descId Indicates configuration descriptor ID. 104 * @param descriptor Indicates the configuration descriptor of the USB device. 105 * 106 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 107 * @since 3.2 108 */ 109 GetConfigDescriptor([in] struct UsbDev dev, [in] unsigned char descId, [out] unsigned char[] descriptor); 110 111 /* * 112 * @brief Obtains the raw descriptor. 113 * 114 * @param dev Indicates the USB device address. 115 * @param descriptor Indicates the raw descriptor of the USB device. 116 * 117 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 118 * @since 3.2 119 */ 120 GetRawDescriptor([in] struct UsbDev dev, [out] unsigned char[] descriptor); 121 122 /* * 123 * @brief Obtains the file descriptor. 124 * 125 * @param dev Indicates the USB device address. 126 * @param fd USB device file descriptor 127 * 128 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 129 * @since 3.2 130 */ 131 GetFileDescriptor([in] struct UsbDev dev, [out] int fd); 132 133 /* * 134 * @brief Sets the configuration information of a USB device. 135 * 136 * @param dev Indicates the USB device address. 137 * @param configIndex Indicates the configuration information of the USB device. 138 * 139 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 140 * @since 3.2 141 */ 142 SetConfig([in] struct UsbDev dev, [in] unsigned char configIndex); 143 144 /* * 145 * @brief Obtains the configuration information of a USB device. 146 * 147 * @param dev Indicates the USB device address. 148 * @param configIndex Indicates the configuration information of the USB device. 149 * 150 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 151 * @since 3.2 152 */ 153 GetConfig([in] struct UsbDev dev, [out] unsigned char configIndex); 154 155 /* * 156 * @brief Claims a USB interface exclusively. This must be done before data transfer. 157 * 158 * @param dev Indicates the USB device address. 159 * @param interfaceid Indicates the interface ID of the USB device. 160 * @param force Indicates whether to enable the force mode. The value <b>1</b> indicates that the force mode is 161 * enabled, and value <b>0</b> indicates the opposite. 162 * 163 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 164 * @since 3.2 165 */ 166 ClaimInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] unsigned char force); 167 168 /* * 169 * @brief Releases a USB interface. This is usually done after data transfer. 170 * 171 * @param dev Indicates the USB device address. 172 * @param interfaceid Indicates the interface ID of the USB device. 173 * 174 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 175 * @since 3.2 176 */ 177 ReleaseInterface([in] struct UsbDev dev, [in] unsigned char interfaceid); 178 179 /* * 180 * @brief Sets the alternate settings for the specified USB interface. This allows you to switch between two 181 * interfaces with the same ID but different alternate settings. 182 * 183 * @param dev Indicates the USB device address. 184 * @param interfaceid Indicates the interface ID of the USB device. 185 * @param altIndex Indicates the alternate settings of the USB interface. 186 * 187 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 188 * @since 3.2 189 */ 190 SetInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] unsigned char altIndex); 191 192 /* * 193 * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading 194 * direction. You can specify a timeout duration if needed. 195 * 196 * @param dev Indicates the USB device address. 197 * @param pipe Indicates the pipe of the USB device. 198 * @param timeout Indicates the timeout duration. 199 * @param data Indicates the read data. 200 * 201 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 202 * @since 3.2 203 */ 204 BulkTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data); 205 206 /* * 207 * @brief Writes data on a specified endpoint during bulk transfer. The endpoint must be in the data writing 208 * direction. 209 * 210 * @param dev Indicates the USB device address. 211 * @param pipe Indicates the pipe of the USB device. 212 * @param timeout Indicates the timeout duration. 213 * @param data Indicates the written data. 214 * 215 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 216 * @since 3.2 217 */ 218 BulkTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data); 219 220 /* * 221 * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the 222 * request type. If the result of <b>requestType</b>& 223 * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result 224 * is <b>USB_DIR_IN</b>, the endpoint is in the data reading direction. 225 * 226 * @param dev Indicates the USB device address. 227 * @param ctrl Indicates the control data packet structure. 228 * @param data Indicates the read data. 229 * 230 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 231 * @since 3.2 232 */ 233 ControlTransferRead([in] struct UsbDev dev, [in] struct UsbCtrlTransfer ctrl, [out] unsigned char[] data); 234 235 /* * 236 * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the 237 * request type. If the result of <b>requestType</b>& 238 * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result 239 * is <b>USB_DIR_IN</b>, the endpoint is in the data writing direction. 240 * 241 * @param dev Indicates the USB device address. 242 * @param ctrl Indicates the control data packet structure. 243 * @param data Indicates the write data. 244 * 245 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 246 * @since 3.2 247 */ 248 ControlTransferWrite([in] struct UsbDev dev, [in] struct UsbCtrlTransfer ctrl, [in] unsigned char[] data); 249 250 /* * 251 * @brief Reads data on a specified endpoint during interrupt transfer. The endpoint must be in the data reading 252 * direction. 253 * 254 * @param dev Indicates the USB device address. 255 * @param pipe Indicates the pipe of the USB device. 256 * @param timeout Indicates the timeout duration. 257 * @param data Indicates the read data. 258 * 259 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 260 * @since 3.2 261 */ 262 InterruptTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data); 263 264 /* * 265 * @brief Writes data on a specified endpoint during interrupt transfer. The endpoint must be in the data writing 266 * direction. 267 * 268 * @param dev Indicates the USB device address. 269 * @param pipe Indicates the pipe of the USB device. 270 * @param timeout Indicates the timeout duration. 271 * @param data Indicates the read data. 272 * 273 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 274 * @since 3.2 275 */ 276 InterruptTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data); 277 278 /* * 279 * @brief Reads data on a specified endpoint during isochronous transfer. The endpoint must be in the data reading 280 * direction. 281 * 282 * @param dev Indicates the USB device address. 283 * @param pipe Indicates the pipe of the USB device. 284 * @param timeout Indicates the timeout duration. 285 * @param data Indicates the read data. 286 * 287 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 288 * @since 3.2 289 */ 290 IsoTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data); 291 292 /* * 293 * @brief Writes data on a specified endpoint during isochronous transfer. The endpoint must be in the data writing 294 * direction. 295 * 296 * @param dev Indicates the USB device address. 297 * @param pipe Indicates the pipe of the USB device. 298 * @param timeout Indicates the timeout duration. 299 * @param data Indicates the read data. 300 * 301 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 302 * @since 3.2 303 */ 304 IsoTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data); 305 306 /* * 307 * @brief Sends or receives requests for isochronous transfer on a specified endpoint. The data transfer direction 308 * is determined by the endpoint direction. 309 * 310 * @param dev Indicates the USB device address. 311 * @param pipe Indicates the pipe of the USB device. 312 * @param clientData Indicates the client data. 313 * @param buffer Indicates the transferred data. 314 * 315 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 316 * @since 3.2 317 */ 318 RequestQueue([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] unsigned char[] clientData, [in] unsigned char[] buffer); 319 320 /* * 321 * @brief Waits for the operation result of the isochronous transfer request in <b>RequestQueue</b>. 322 * 323 * @param dev Indicates the USB device address. 324 * @param clientData Indicates the client data. 325 * @param buffer Indicates the transferred data. 326 * @param timeout Indicates the timeout duration. 327 * 328 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 329 * @since 3.2 330 */ 331 RequestWait([in] struct UsbDev dev, [out] unsigned char[] clientData, [out] unsigned char[] buffer, [in] int timeout); 332 333 /* * 334 * @brief Cancels the data transfer requests to be processed. 335 * 336 * @param dev Indicates the USB device address. 337 * @param pipe Indicates the pipe of the USB device. 338 * 339 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 340 * @since 3.2 341 */ 342 RequestCancel([in] struct UsbDev dev, [in] struct UsbPipe pipe); 343 344 /* * 345 * @brief Obtains the list of functions (represented by bit field) supported by the current device. 346 * 347 * @param funcs Indicates the list of functions supported by the current device. 348 * 349 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 350 * @since 3.2 351 */ 352 GetCurrentFunctions([out] int funcs); 353 354 /* * 355 * @brief Sets the list of functions (represented by bit field) supported by the current device. 356 * 357 * @param funcs Indicates the list of functions supported by the current device. 358 * 359 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 360 * @since 3.2 361 */ 362 SetCurrentFunctions([in] int funcs); 363 364 /* * 365 * @brief Closes a USB device to release all system resources related to the device. 366 * 367 * @param portId Indicates the port ID of the USB interface. 368 * @param powerRole Indicates the power role. 369 * @param dataRole Indicates the data role. 370 * 371 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 372 * @since 3.2 373 */ 374 SetPortRole([in] int portId, [in] int powerRole, [in] int dataRole); 375 376 /* * 377 * @brief Queries the current settings of a port. 378 * 379 * @param portId Indicates the port ID of the USB interface. 380 * @param powerRole Indicates the power role. 381 * @param dataRole Indicates the data role. 382 * @param mode Indicates the mode. 383 * 384 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 385 * @since 3.2 386 */ 387 QueryPort([out] int portId, [out] int powerRole, [out] int dataRole, [out] int mode); 388 389 /* * 390 * @brief Binds a subscriber. 391 * 392 * @param subscriber Indicates the subscriber. 393 * 394 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 395 * @since 3.2 396 */ 397 BindUsbdSubscriber([in] IUsbdSubscriber subscriber); 398 399 /* * 400 * @brief Unbinds a subscriber. 401 * 402 * @param subscriber Indicates the subscriber. 403 * 404 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 405 * @since 3.2 406 */ 407 UnbindUsbdSubscriber([in] IUsbdSubscriber subscriber); 408 409 /* * 410 * @brief Registers a callback for isochronous bulk transfer. 411 * 412 * @param dev Indicates the USB device address. 413 * @param pipe Indicates the pipe of the USB device. 414 * @param cb Indicates the reference to the callback. 415 * 416 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 417 * @since 3.2 418 */ 419 RegBulkCallback([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] IUsbdBulkCallback cb); 420 421 /* * 422 * @brief Unregisters the callback for isochronous bulk transfer. 423 * 424 * @param dev Indicates the USB device address. 425 * @param pipe Indicates the pipe of the USB device. 426 * 427 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 428 * @since 3.2 429 */ 430 UnRegBulkCallback([in] struct UsbDev dev, [in] struct UsbPipe pipe); 431 432 /* * 433 * @brief Reads data during isochronous bulk transfer. 434 * 435 * @param dev Indicates the USB device address. 436 * @param pipe Indicates the pipe of the USB device. 437 * @param ashmem Indicates the shared memory, which is used to store the read data. 438 * 439 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 440 * @since 3.2 441 */ 442 BulkRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] Ashmem ashmem); 443 444 /* * 445 * @brief Writes data during isochronous bulk transfer. 446 * 447 * @param dev Indicates the USB device address. 448 * @param pipe Indicates the pipe of the USB device. 449 * @param ashmem Indicates the shared memory, which is used to store the written data. 450 * 451 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 452 * @since 3.2 453 */ 454 BulkWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] Ashmem ashmem); 455 456 /* * 457 * @brief Cancels the isochronous bulk transfer. The read and write operations on the current USB interface will 458 * be cancelled. 459 * 460 * @param dev Indicates the USB device address. 461 * @param pipe Indicates the pipe of the USB device. 462 * 463 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 464 * @since 3.2 465 */ 466 BulkCancel([in] struct UsbDev dev, [in] struct UsbPipe pipe); 467}