1 /* 2 * Copyright (c) 2024 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 OH_Scan 18 * @{ 19 * 20 * @brief Provides the definition of the C interface for the scan module. 21 * 22 * @syscap SystemCapability.Print.PrintFramework 23 * 24 * @since 12 25 * @version 1.0 26 */ 27 28 /** 29 * @file ohscan.h 30 * 31 * @brief Declares the APIs to discover and connect scanners, scan images from the scanner, 32 * obtain the page scanning progress and set scanned image parameters, and so on. 33 * 34 * @library libohscan.so 35 * @syscap SystemCapability.Print.PrintFramework 36 * @since 12 37 * @version 1.0 38 */ 39 40 #ifndef OH_SCAN_H 41 #define OH_SCAN_H 42 43 #include <stdint.h> 44 #include <stdbool.h> 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Defines error codes. 52 * 53 * @since 12 54 * @version 1.0 55 */ 56 typedef enum { 57 /** @error The operation is successful. */ 58 SCAN_ERROR_NONE = 0, 59 /** @error Permission verification failed. */ 60 SCAN_ERROR_NO_PERMISSION = 201, 61 /** @error The parameter is invalid. For example, the pointer is null or the character string is null. */ 62 SCAN_ERROR_INVALID_PARAMETER = 401, 63 /** @error General internal error. */ 64 SCAN_ERROR_GENERIC_FAILURE = 24300101, 65 /** @error RPC communication error. */ 66 SCAN_ERROR_RPC_FAILURE = 24300102, 67 /** @error Server error. */ 68 SCAN_ERROR_SERVER_FAILURE = 24300103, 69 /** @error Operation is not supported. **/ 70 SCAN_ERROR_UNSUPPORTED = 24300104, 71 /** @error Operation was cancelled. **/ 72 SCAN_ERROR_CANCELED = 24300105, 73 /** @error Device is busy, try again later. **/ 74 SCAN_ERROR_DEVICE_BUSY = 24300106, 75 /** @error Data is invalid (includes no dev at open). **/ 76 SCAN_ERROR_INVALID = 24300107, 77 /** @error Document feeder jammed. **/ 78 SCAN_ERROR_JAMMED = 24300108, 79 /** @error Document feeder out of documents. **/ 80 SCAN_ERROR_NO_DOCS = 24300109, 81 /** @error Scanner cover is open. **/ 82 SCAN_ERROR_COVER_OPEN = 24300110, 83 /** @error Error during device I/O. **/ 84 SCAN_ERROR_IO_ERROR = 24300111, 85 /** @error Out of memory. **/ 86 SCAN_ERROR_NO_MEMORY = 24300112, 87 } Scan_ErrorCode; 88 89 /** 90 * @brief Indicates scanner device information. 91 * 92 * @since 12 93 */ 94 typedef struct { 95 /** Scanner id. */ 96 const char* scannerId; 97 /** Scanner manufacturer. */ 98 const char* manufacturer; 99 /** Scanner model. */ 100 const char* model; 101 /** Scanner discoverMode. */ 102 const char* discoverMode; 103 /** Scanner serialNumber. */ 104 const char* serialNumber; 105 } Scan_ScannerDevice; 106 107 /** 108 * @brief Indicates the progress of scanning a picture by the scanner. 109 * 110 * @since 12 111 */ 112 typedef struct { 113 /** Picture progress from 0 to 100. */ 114 int32_t progress; 115 /** scanner file handle. */ 116 int32_t fd; 117 /** Indicates whether the image is the last scanned image. */ 118 bool isFinal; 119 } Scan_PictureScanProgress; 120 121 /** 122 * @brief Indicates all parameter options for one scanner. 123 * 124 * @since 12 125 */ 126 typedef struct { 127 /** Title of an option. */ 128 char** titles; 129 /** Description of an option. */ 130 char** descriptions; 131 /** The range that an option can be set to. */ 132 char** ranges; 133 /** Number of parameter options that can be set. */ 134 int32_t optionCount; 135 } Scan_ScannerOptions; 136 137 /** 138 * @brief Scanner devices discovery callback, register by {@link OH_Scan_StartScannerDiscovery}. 139 * The memory of {@link devices} will be released when the callback function ends. 140 * 141 * @param devices List of all discovered scanner devices. 142 * @param deviceCount Number of Scanners Found. 143 * @since 12 144 */ 145 typedef void (*Scan_ScannerDiscoveryCallback)(Scan_ScannerDevice** devices, int32_t deviceCount); 146 147 /** 148 * @brief This API checks and pulls up the scan service, initializes the scan client, 149 * and establishes a connection to the scan service. 150 * 151 * @permission {@code ohos.permission.PRINT} 152 * @return {@link Scan_ERROR_NONE} Indicates the scanning service is successfully started. 153 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 154 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 155 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 156 * @syscap SystemCapability.Print.PrintFramework 157 * @since 12 158 */ 159 int32_t OH_Scan_Init(); 160 161 /** 162 * @brief This API starts discovering scanners, Register a callback to handle discovered scanner devices. 163 * 164 * @permission {@code ohos.permission.PRINT} 165 * @param callback The {@link Scan_ScannerDiscoveryCallback} of scanner discovery event. 166 * @return {@link Scan_ERROR_NONE} Indicates successful start of scanner search. 167 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 168 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 169 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 170 * @syscap SystemCapability.Print.PrintFramework 171 * @since 12 172 */ 173 int32_t OH_Scan_StartScannerDiscovery(Scan_ScannerDiscoveryCallback callback); 174 175 /** 176 * @brief This API connects to scanner devices. 177 * 178 * @permission {@code ohos.permission.PRINT} 179 * @param scannerId The id used to connect to the scanner. 180 * @return {@link Scan_ERROR_NONE} Indicates that the scanner was successfully connected. 181 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 182 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 183 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 184 * {@link SCAN_ERROR_DEVICE_BUSY} Indicates that the scanner is busy. 185 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates that the input parameter is invalid. 186 * {@link SCAN_ERROR_IO_ERROR} Indicates an error occured while communicating with the device. 187 * {@link SCAN_ERROR_NO_MEMORY} Indicates an insufficent amount of memory is available. 188 * @syscap SystemCapability.Print.PrintFramework 189 * @since 12 190 */ 191 int32_t OH_Scan_OpenScanner(const char* scannerId); 192 193 /** 194 * @brief This API is used to close the connected scanner device. 195 * 196 * @permission {@code ohos.permission.PRINT} 197 * @param scannerId The id to disconnect the scanner. 198 * @return {@link Scan_ERROR_NONE} Indicates that the scanner connection was successfully closed. 199 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 200 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 201 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 202 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates that the input parameter is invalid. 203 * @syscap SystemCapability.Print.PrintFramework 204 * @since 12 205 */ 206 int32_t OH_Scan_CloseScanner(const char* scannerId); 207 208 /** 209 * @brief This API can be used to get a list of options that can be set by the scanner. 210 * The returned struct pointer points to memory that is automatically freed when {@link OH_Scan_Exit}, 211 * and only one copy will be stored in memory for each model. 212 * 213 * @permission {@code ohos.permission.PRINT} 214 * @param scannerId The id used to obtain the scanner parameters. 215 * @param errorCode The errorCode returns {@link Scan_ErrorCode#Scan_ERROR_NONE} if the execution is successful, 216 * otherwise returns a specific error code, refer to {@link Print_ErrorCode}. 217 * @return {@link Scan_ERROR_NONE} Indicates that the scanner parameter options are successfully obtained. 218 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 219 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 220 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 221 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates invalid parameter. 222 * @syscap SystemCapability.Print.PrintFramework 223 * @since 12 224 */ 225 Scan_ScannerOptions* OH_Scan_GetScannerParameter(const char* scannerId, int32_t* errorCode); 226 227 /** 228 * @brief This API can be used to set one of the scanner's option parameters. 229 * The option and value passed in are obtained from {@link OH_Scan_GetScannerParameter}. 230 * 231 * @permission {@code ohos.permission.PRINT} 232 * @param scannerId This id is used to set the options for a specific scanner. 233 * @param option Options number to be set.The value ranges from 0 to {@link optionCount} - 1, 234 * be obtained from the {@link Scan_ScannerOptions}. 235 * @param value Option value to be set, valid value is obtained from the {@link ranges}, 236 * be obtained from the {@link Scan_ScannerOptions}. 237 * @return {@link Scan_ERROR_NONE} Indicates that the scanner parameters were successfully set. 238 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 239 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 240 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates an error occurs in the scan process. 241 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates invalid parameter. 242 * @syscap SystemCapability.Print.PrintFramework 243 * @since 12 244 */ 245 int32_t OH_Scan_SetScannerParameter(const char* scannerId, const int32_t option, const char* value); 246 247 /** 248 * @brief This API allows the scanner to start scanning. 249 * 250 * @permission {@code ohos.permission.PRINT} 251 * @param scannerId This id is used to start the scan job for the specified scanner. 252 * @param batchMode Whether to start the scanner in batch mode. 253 * @return {@link Scan_ERROR_NONE} Indicates that the scanner has successfully canceled the scan job. 254 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 255 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 256 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 257 * {@link SCAN_ERROR_JAMMED} Indicates the document feeder is jammed. 258 * {@link SCAN_ERROR_NO_DOCS} Indicates the document feeder is out of documents. 259 * {@link SCAN_ERROR_COVER_OPEN} Indicates the scanner cover is open. 260 * {@link SCAN_ERROR_IO_ERROR} Indicates an error occurred while communicating with the device. 261 * {@link SCAN_ERROR_NO_MEMORY} Indicates an insufficent amount of memory is available. 262 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates that the input parameter is invalid. 263 * {@link SCAN_ERROR_DEVICE_BUSY} Indicates the device is busy, the operation should be retried later. 264 * @syscap SystemCapability.Print.PrintFramework 265 * @since 12 266 */ 267 int32_t OH_Scan_StartScan(const char* scannerId, bool batchMode); 268 269 /** 270 * @brief This API allows the scanner to cancel the scan. 271 * 272 * @permission {@code ohos.permission.PRINT} 273 * @param scannerId This id is used to cancel the scan job for the specified scanner. 274 * @return {@link Scan_ERROR_NONE} Indicates that the scanner has successfully canceled the scan job. 275 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 276 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates if the pointer is null or the character string is null. 277 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 278 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 279 * @syscap SystemCapability.Print.PrintFramework 280 * @since 12 281 */ 282 int32_t OH_Scan_CancelScan(const char* scannerId); 283 284 /** 285 * @brief This API can get the progress of the scanner scanning the picture.A non-null value must be passed in, 286 * and the scan progress will be written to the structure to which the pointer points. 287 * 288 * @permission {@code ohos.permission.PRINT} 289 * @param scannerId The id for querying the image scanning progress of the scanner. 290 * @param prog The {@link Scan_PictureScanProgress} of scanning pictures, must be a non-null value. 291 * @return {@link Scan_ERROR_NONE} Indicates the scanner has successfully queried the progress of the scanned image. 292 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 293 * {@link SCAN_ERROR_INVALID_PARAMETER} Indicates if the pointer is null or the character string is null. 294 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 295 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 296 * {@link SCAN_ERROR_JAMMED} Indicates the document feeder is jammed. 297 * {@link SCAN_ERROR_NO_DOCS} Indicates the document feeder is out of documents. 298 * {@link SCAN_ERROR_COVER_OPEN} Indicates the scanner cover is open. 299 * {@link SCAN_ERROR_IO_ERROR} Indicates an error occurred while communicating with the scanner. 300 * {@link SCAN_ERROR_NO_MEMORY} Indicates an insufficent amount of memory is available. 301 * {@link SCAN_ERROR_DEVICE_BUSY} Indicates the device is busy, the operation should be retried later. 302 * @syscap SystemCapability.Print.PrintFramework 303 * @since 12 304 */ 305 int32_t OH_Scan_GetPictureScanProgress(const char* scannerId, Scan_PictureScanProgress* prog); 306 307 /** 308 * @brief This API can be used to exit the scanning service, free the Scan Framework Memory, 309 * and unregister the callback for scanner discover. 310 * 311 * @permission {@code ohos.permission.PRINT} 312 * @return {@link Scan_ERROR_NONE} Indicates the scan service exit successfully. 313 * {@link SCAN_ERROR_NO_PERMISSION} Indicates have no permission to use this interface. 314 * {@link SCAN_ERROR_RPC_FAILURE} Indicates an RPC communication error. 315 * {@link SCAN_ERROR_SERVER_FAILURE} Indicates An error occurs in the scan process. 316 * @syscap SystemCapability.Print.PrintFramework 317 * @since 12 318 */ 319 int32_t OH_Scan_Exit(); 320 321 #ifdef __cplusplus 322 } 323 #endif 324 325 #endif // OH_SCAN_H 326 /** @} */ 327