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