1 /* 2 * Copyright (c) 2021 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 USB 18 * @{ 19 * 20 * @brief Declares USB-related APIs, including the custom data types and functions 21 * used to obtain descriptors, interface objects, and request objects, and to submit requests. 22 * 23 * @since 3.0 24 * @version 1.0 25 */ 26 27 /** 28 * @file usbd_client.h 29 * 30 * @brief Defines usbd APIs. 31 * 32 * @since 3.0 33 * @version 1.0 34 */ 35 36 #ifndef USBD_CLIENT_H 37 #define USBD_CLIENT_H 38 39 #include "usb_param.h" 40 #include "usbd_subscriber.h" 41 42 namespace OHOS { 43 namespace USB { 44 class UsbdClient { 45 public: 46 static UsbdClient &GetInstance(); 47 48 /* * 49 * @brief Opens a USB device to set up a connection. 50 * 51 * @param dev Indicates the USB device address. 52 * 53 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 54 * @since 3.0 55 */ 56 int32_t OpenDevice(const UsbDev &dev); 57 58 /* * 59 * @brief Closes a USB device to release all system resources related to the device. 60 * 61 * @param dev Indicates the USB device address. 62 * 63 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 64 * @since 3.0 65 */ 66 int32_t CloseDevice(const UsbDev &dev); 67 68 /* * 69 * @brief Obtains the USB device descriptor. 70 * 71 * @param dev Indicates the USB device address. 72 * @param descriptor Indicates the USB device descriptor. 73 * 74 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 75 * @since 3.0 76 */ 77 int32_t GetDeviceDescriptor(const UsbDev &dev, std::vector<uint8_t> &decriptor); 78 79 /* * 80 * @brief Obtains the string descriptor of a USB device based on the specified string ID. 81 * 82 * @param dev Indicates the USB device address. 83 * @param descId Indicates string descriptor ID. 84 * @param descriptor Indicates the configuration descriptor of the USB device. 85 * 86 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 87 * @since 3.0 88 */ 89 int32_t GetStringDescriptor(const UsbDev &dev, uint8_t descId, std::vector<uint8_t> &decriptor); 90 91 /* * 92 * @brief Obtains the configuration descriptor of a USB device based on the specified config ID. 93 * 94 * @param dev Indicates the USB device address. 95 * @param descId Indicates configuration descriptor ID. 96 * @param descriptor Indicates the configuration descriptor of the USB device. 97 * 98 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 99 * @since 3.0 100 */ 101 int32_t GetConfigDescriptor(const UsbDev &dev, uint8_t descId, std::vector<uint8_t> &decriptor); 102 103 /* * 104 * @brief Obtains the raw descriptor. 105 * 106 * @param dev Indicates the USB device address. 107 * @param descriptor Indicates the raw descriptor of the USB device. 108 * 109 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 110 * @since 3.0 111 */ 112 int32_t GetRawDescriptor(const UsbDev &dev, std::vector<uint8_t> &decriptor); 113 114 /* * 115 * @brief Obtains the file descriptor. 116 * 117 * @param dev Indicates the USB device address. 118 * @param fd USB device file descriptor 119 * 120 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 121 * @since 3.0 122 */ 123 int32_t GetFileDescriptor(const UsbDev &dev, int32_t &fd); 124 125 /* * 126 * @brief Sets the configuration information of a USB device. 127 * 128 * @param dev Indicates the USB device address. 129 * @param configIndex Indicates the configuration information of the USB device. 130 * 131 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 132 * @since 3.0 133 */ 134 int32_t SetConfig(const UsbDev &dev, uint8_t configIndex); 135 136 /* * 137 * @brief Obtains the configuration information of a USB device. 138 * 139 * @param dev Indicates the USB device address. 140 * @param configIndex Indicates the configuration information of the USB device. 141 * 142 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 143 * @since 3.0 144 */ 145 int32_t GetConfig(const UsbDev &dev, uint8_t &configIndex); 146 147 /* * 148 * @brief Claims a USB interface exclusively. This must be done before data transfer. 149 * 150 * @param dev Indicates the USB device address. 151 * @param interfaceid Indicates the interface ID of the USB device. 152 * @param force Indicates whether to enable the force mode. The value <b>1</b> indicates that the force mode is 153 * enabled, and value <b>0</b> indicates the opposite. 154 * 155 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 156 * @since 3.0 157 */ 158 int32_t ClaimInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t force); 159 160 /* * 161 * @brief Releases a USB interface. This is usually done after data transfer. 162 * 163 * @param dev Indicates the USB device address. 164 * @param interfaceid Indicates the interface ID of the USB device. 165 * 166 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 167 * @since 3.0 168 */ 169 int32_t ReleaseInterface(const UsbDev &dev, uint8_t interfaceid); 170 171 /* * 172 * @brief Sets the alternate settings for the specified USB interface. This allows you to switch between two 173 * interfaces with the same ID but different alternate settings. 174 * 175 * @param dev Indicates the USB device address. 176 * @param interfaceid Indicates the interface ID of the USB device. 177 * @param altIndex Indicates the alternate settings of the USB interface. 178 * 179 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 180 * @since 3.0 181 */ 182 int32_t SetInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t altIndex); 183 184 /* * 185 * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading 186 * direction. You can specify a timeout duration if needed. 187 * 188 * @param dev Indicates the USB device address. 189 * @param pipe Indicates the pipe of the USB device. 190 * @param timeout Indicates the timeout duration. 191 * @param data Indicates the read data. 192 * 193 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 194 * @since 3.0 195 */ 196 int32_t BulkTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data); 197 198 /* * 199 * @brief Writes data on a specified endpoint during bulk transfer. The endpoint must be in the data writing 200 * direction. 201 * 202 * @param dev Indicates the USB device address. 203 * @param pipe Indicates the pipe of the USB device. 204 * @param timeout Indicates the timeout duration. 205 * @param data Indicates the written data. 206 * 207 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 208 * @since 3.0 209 */ 210 int32_t BulkTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, 211 const std::vector<uint8_t> &data); 212 213 /* * 214 * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the 215 * request type. If the result of <b>requestType</b>& 216 * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result 217 * is <b>USB_DIR_IN</b>, the endpoint is in the data reading direction. 218 * 219 * @param dev Indicates the USB device address. 220 * @param ctrl Indicates the control data packet structure. 221 * @param data Indicates the read or written data. 222 * 223 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 224 * @since 3.0 225 */ 226 int32_t ControlTransfer(const UsbDev &dev, const UsbCtrlTransfer &ctrl, std::vector<uint8_t> &data); 227 228 /* * 229 * @brief Reads data on a specified endpoint during interrupt transfer. The endpoint must be in the data reading 230 * direction. 231 * 232 * @param dev Indicates the USB device address. 233 * @param pipe Indicates the pipe of the USB device. 234 * @param timeout Indicates the timeout duration. 235 * @param data Indicates the read data. 236 * 237 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 238 * @since 3.0 239 */ 240 int32_t InterruptTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data); 241 242 /* * 243 * @brief Writes data on a specified endpoint during interrupt transfer. The endpoint must be in the data writing 244 * direction. 245 * 246 * @param dev Indicates the USB device address. 247 * @param pipe Indicates the pipe of the USB device. 248 * @param timeout Indicates the timeout duration. 249 * @param data Indicates the read data. 250 * 251 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 252 * @since 3.0 253 */ 254 int32_t InterruptTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data); 255 256 /* * 257 * @brief Reads data on a specified endpoint during isochronous transfer. The endpoint must be in the data reading 258 * direction. 259 * 260 * @param dev Indicates the USB device address. 261 * @param pipe Indicates the pipe of the USB device. 262 * @param timeout Indicates the timeout duration. 263 * @param data Indicates the read data. 264 * 265 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 266 * @since 3.0 267 */ 268 int32_t IsoTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data); 269 270 /* * 271 * @brief Writes data on a specified endpoint during isochronous transfer. The endpoint must be in the data writing 272 * direction. 273 * 274 * @param dev Indicates the USB device address. 275 * @param pipe Indicates the pipe of the USB device. 276 * @param timeout Indicates the timeout duration. 277 * @param data Indicates the read data. 278 * 279 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 280 * @since 3.0 281 */ 282 int32_t IsoTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data); 283 284 /* * 285 * @brief Sends or receives requests for isochronous transfer on a specified endpoint. The data transfer direction 286 * is determined by the endpoint direction. 287 * 288 * @param dev Indicates the USB device address. 289 * @param pipe Indicates the pipe of the USB device. 290 * @param clientData Indicates the client data. 291 * @param buffer Indicates the transferred data. 292 * 293 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 294 * @since 3.0 295 */ 296 int32_t RequestQueue(const UsbDev &dev, const UsbPipe &pipe, const std::vector<uint8_t> &clientData, 297 const std::vector<uint8_t> &buffer); 298 299 /* * 300 * @brief Waits for the operation result of the isochronous transfer request in <b>RequestQueue</b>. 301 * 302 * @param dev Indicates the USB device address. 303 * @param clientData Indicates the client data. 304 * @param buffer Indicates the transferred data. 305 * @param timeout Indicates the timeout duration. 306 * 307 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 308 * @since 3.0 309 */ 310 int32_t RequestWait(const UsbDev &dev, std::vector<uint8_t> &clientData, std::vector<uint8_t> &buffer, 311 int32_t timeout); 312 313 /* * 314 * @brief Cancels the data transfer requests to be processed. 315 * 316 * @param dev Indicates the USB device address. 317 * @param pipe Indicates the pipe of the USB device. 318 * 319 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 320 * @since 3.0 321 */ 322 int32_t RequestCancel(const UsbDev &dev, const UsbPipe &pipe); 323 324 /* * 325 * @brief Obtains the list of functions (represented by bit field) supported by the current device. 326 * 327 * @param funcs Indicates the list of functions supported by the current device. 328 * 329 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 330 * @since 3.0 331 */ 332 int32_t GetCurrentFunctions(int32_t &funcs); 333 334 /* * 335 * @brief Sets the list of functions (represented by bit field) supported by the current device. 336 * 337 * @param funcs Indicates the list of functions supported by the current 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.0 341 */ 342 int32_t SetCurrentFunctions(int32_t funcs); 343 344 /* * 345 * @brief Closes a USB device to release all system resources related to the device. 346 * 347 * @param portId Indicates the port ID of the USB interface. 348 * @param powerRole Indicates the power role. 349 * @param dataRole Indicates the data role. 350 * 351 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 352 * @since 3.0 353 */ 354 int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole); 355 356 /* * 357 * @brief Queries the current settings of a port. 358 * 359 * @param portId Indicates the port ID of the USB interface. 360 * @param powerRole Indicates the power role. 361 * @param dataRole Indicates the data role. 362 * @param mode Indicates the mode. 363 * 364 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 365 * @since 3.0 366 */ 367 int32_t QueryPort(int32_t &portId, int32_t &powerRole, int32_t &dataRole, int32_t &mode); 368 369 /* * 370 * @brief Binds a subscriber. 371 * 372 * @param subscriber Indicates the subscriber. 373 * 374 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 375 * @since 3.0 376 */ 377 int32_t BindUsbdSubscriber(const sptr<UsbdSubscriber> &subscriber); 378 379 /* * 380 * @brief Unbinds a subscriber. 381 * 382 * @param subscriber Indicates the subscriber. 383 * 384 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 385 * @since 3.0 386 */ 387 int32_t UnbindUsbdSubscriber(const sptr<UsbdSubscriber> &subscriber); 388 389 /* * 390 * @brief Registers a callback for isochronous bulk transfer. 391 * 392 * @param dev Indicates the USB device address. 393 * @param pipe Indicates the pipe of the USB device. 394 * @param cb Indicates the reference to the callback. 395 * 396 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 397 * @since 3.0 398 */ 399 int32_t RegBulkCallback(const UsbDev &dev, const UsbPipe &pipe, const sptr<IRemoteObject> &cb); 400 401 /* * 402 * @brief Unregisters the callback for isochronous bulk transfer. 403 * 404 * @param dev Indicates the USB device address. 405 * @param pipe Indicates the pipe of the USB device. 406 * 407 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 408 * @since 3.0 409 */ 410 int32_t UnRegBulkCallback(const UsbDev &dev, const UsbPipe &pipe); 411 412 /* * 413 * @brief Reads data during isochronous bulk transfer. 414 * 415 * @param dev Indicates the USB device address. 416 * @param pipe Indicates the pipe of the USB device. 417 * @param ashmem Indicates the shared memory, which is used to store the read data. 418 * 419 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 420 * @since 3.0 421 */ 422 int32_t BulkRead(const UsbDev &dev, const UsbPipe &pipe, sptr<Ashmem> &ashmem); 423 424 /* * 425 * @brief Writes data during isochronous bulk transfer. 426 * 427 * @param dev Indicates the USB device address. 428 * @param pipe Indicates the pipe of the USB device. 429 * @param ashmem Indicates the shared memory, which is used to store the written data. 430 * 431 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 432 * @since 3.0 433 */ 434 int32_t BulkWrite(const UsbDev &dev, const UsbPipe &pipe, sptr<Ashmem> &ashmem); 435 436 /* * 437 * @brief Cancels the isochronous bulk transfer. The read and write operations on the current USB interface will 438 * be cancelled. 439 * 440 * @param dev Indicates the USB device address. 441 * @param pipe Indicates the pipe of the USB device. 442 * 443 * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails. 444 * @since 3.0 445 */ 446 int32_t BulkCancel(const UsbDev &dev, const UsbPipe &pipe); 447 448 private: 449 int32_t SetDeviceMessage(MessageParcel &data, const UsbDev &dev); 450 int32_t SetBufferMessage(MessageParcel &data, const std::vector<uint8_t> &bufferData); 451 int32_t GetBufferMessage(MessageParcel &data, std::vector<uint8_t> &bufferData); 452 sptr<IRemoteObject> GetUsbdService(); 453 int32_t DoDispatch(uint32_t cmd, MessageParcel &data, MessageParcel &reply); 454 static inline const std::u16string metaDescriptor_ = u"hdf.usb.usbd"; GetDescriptor()455 static inline const std::u16string &GetDescriptor() 456 { 457 return metaDescriptor_; 458 } 459 }; 460 } // namespace USB 461 } // namespace OHOS 462 #endif // USBD_CLIENT_H