1 /* 2 * Copyright (c) 2025 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 USBSerialDDK 18 * @{ 19 * 20 * @brief Provides USB SERIAL DDK types and declares the macros, enumerated variables, and\n 21 * data structures required by the USB SERIAL DDK APIs. 22 * 23 * @since 16 24 */ 25 26 /** 27 * @file usb_serial_api.h 28 * 29 * @brief Declares the USB SERIAL DDK interfaces for the usb host to access an usb serial device. 30 * 31 * @kit DriverDevelopmentKit 32 * @library libusb_serial.z.so 33 * @syscap SystemCapability.Driver.UsbSerial.Extension 34 * @since 16 35 */ 36 37 #ifndef DDK_USB_SERIAL_API_H 38 #define DDK_USB_SERIAL_API_H 39 40 #include <stdint.h> 41 #include "usb_serial_types.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Initializes the USB serial DDK. 49 * 50 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 51 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 52 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 53 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk init error. 54 * @since 16 55 */ 56 int32_t OH_UsbSerial_Init(void); 57 58 /** 59 * @brief Releases the USB serial DDK. 60 * 61 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 62 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 63 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 64 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 65 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 66 * @since 16 67 */ 68 int32_t OH_UsbSerial_Release(void); 69 70 /** 71 * @brief Open USB serial device by deviceId. 72 * 73 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 74 * @param deviceId ID of the device to be operated. 75 * @param interfaceIndex Interface index, which corresponds to interface which supports USB Protocol ACM. 76 * @param dev Device handle. 77 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 78 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 79 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: dev is null. 80 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 81 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 82 * {@link USB_SERIAL_DDK_MEMORY_ERROR} insufficient memory. 83 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 84 * {@link USB_SERIAL_DDK_DEVICE_NOT_FOUND} device or interface not found. 85 * @since 16 86 */ 87 int32_t OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_Device **dev); 88 89 /** 90 * @brief Close USB serial device. 91 * 92 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 93 * @param dev Device handle. 94 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 95 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 96 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1. dev is null.\n 97 * 2. *dev is null. 98 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 99 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 100 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 101 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 102 * @since 16 103 */ 104 int32_t OH_UsbSerial_Close(UsbSerial_Device **dev); 105 106 /** 107 * @brief Read bytesRead into buff from UsbSerial device. 108 * 109 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 110 * @param dev Device handle. 111 * @param buff Received data from a serial device. 112 * @param bufferSize The buffer size. 113 * @param bytesRead Actual bytes read. 114 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 115 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 116 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 117 * 2.buff is null; 3.bufferSize is zero; 4.bytesRead is null. 118 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 119 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 120 * {@link USB_SERIAL_DDK_MEMORY_ERROR} the buff is outside accessible address space error. 121 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 122 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 123 * @since 16 124 */ 125 int32_t OH_UsbSerial_Read(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead); 126 127 /** 128 * @brief Write bytesWritten from buff to UsbSerial device. 129 * 130 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 131 * @param dev Device handle. 132 * @param buff Serial information write to device. 133 * @param bufferSize The buffer size. 134 * @param bytesWritten Actual bytes written. 135 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 136 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 137 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 138 * 2.buff is null; 3.bufferSize is zero; 4. bytesWritten is null. 139 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 140 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 141 * {@link USB_SERIAL_DDK_MEMORY_ERROR} the buff is outside accessible address space error. 142 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 143 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 144 * @since 16 145 */ 146 int32_t OH_UsbSerial_Write(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten); 147 148 /** 149 * @brief Set the serial port baud rate. 150 * 151 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 152 * @param dev Device handle. 153 * @param baudRate Serial port baud rate set to connect device. 154 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 155 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 156 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: dev is null. 157 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 158 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 159 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 160 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 161 * @since 16 162 */ 163 int32_t OH_UsbSerial_SetBaudRate(UsbSerial_Device *dev, uint32_t baudRate); 164 165 /** 166 * @brief Set the serial port parameters. 167 * 168 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 169 * @param dev Device handle. 170 * @param params Serial port params set to connect device. 171 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 172 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 173 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 174 * 2.params is null. 175 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 176 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 177 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 178 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 179 * @since 16 180 */ 181 int32_t OH_UsbSerial_SetParams(UsbSerial_Device *dev, UsbSerial_Params *params); 182 183 /** 184 * @brief Set the timeout in milliseconds. 185 * The timeout value defaults to 0 without calling this function. 186 * 187 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 188 * @param dev Device handle. 189 * @param timeout Set to -1 to infinite timeout, 0 to return immediately with any data, 190 * or > 0 to wait for data for a specified number of milliseconds. 191 * Timeout will be rounded to the nearest 100ms. Maximum value limited to 25500ms. 192 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 193 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 194 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 195 * 2. timeout < -1 or timeout > 25500. 196 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 197 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 198 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 199 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 200 * @since 16 201 */ 202 int32_t OH_UsbSerial_SetTimeout(UsbSerial_Device *dev, int timeout); 203 204 /** 205 * @brief Set the flow control. 206 * It defaults to no flow control without calling this function. 207 * 208 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 209 * @param dev Device handle. 210 * @param flowControl {@link UsbSerial_FlowControl} flow control mode. 211 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 212 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 213 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: dev is null. 214 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 215 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 216 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 217 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 218 * @since 16 219 */ 220 int32_t OH_UsbSerial_SetFlowControl(UsbSerial_Device *dev, UsbSerial_FlowControl flowControl); 221 222 /** 223 * @brief Flush the input and output buffers after finish writting. 224 * 225 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 226 * @param dev Device handle. 227 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 228 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 229 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: dev is null. 230 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 231 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 232 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 233 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 234 * @since 16 235 */ 236 int32_t OH_UsbSerial_Flush(UsbSerial_Device *dev); 237 238 /** 239 * @brief Flush the input buffer, and the data in the buffer will be cleared directly. 240 * 241 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 242 * @param dev Device handle. 243 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 244 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 245 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: dev is null. 246 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 247 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 248 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 249 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 250 * @since 16 251 */ 252 int32_t OH_UsbSerial_FlushInput(UsbSerial_Device *dev); 253 254 /** 255 * @brief Flush the output buffer, and the data in the buffer will be cleared directly. 256 * 257 * @permission ohos.permission.ACCESS_DDK_USB_SERIAL 258 * @param dev Device handle. 259 * @return {@link USB_SERIAL_DDK_SUCCESS} the operation is successful. 260 * {@link USB_SERIAL_DDK_NO_PERM} permission check failed. 261 * {@link USB_SERIAL_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: dev is null. 262 * {@link USB_SERIAL_DDK_INIT_ERROR} the ddk not init. 263 * {@link USB_SERIAL_DDK_SERVICE_ERROR} communication with the ddk service failed. 264 * {@link USB_SERIAL_DDK_IO_ERROR} the ddk I/O error. 265 * {@link USB_SERIAL_DDK_INVALID_OPERATION} invalid operation. 266 * @since 16 267 */ 268 int32_t OH_UsbSerial_FlushOutput(UsbSerial_Device *dev); 269 #ifdef __cplusplus 270 } 271 #endif /* __cplusplus */ 272 #endif // DDK_USB_SERIAL_API_H 273 /** @} */ 274