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
47extern "C" {
48#endif
49
50/**
51 * @brief Defines error codes.
52 *
53 * @since 12
54 * @version 1.0
55 */
56typedef 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 */
94typedef 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 */
112typedef 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 */
126typedef 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 */
145typedef 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 */
159int32_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 */
173int32_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 */
191int32_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 */
206int32_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 */
225Scan_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 */
245int32_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 */
267int32_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 */
282int32_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 */
305int32_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 */
319int32_t OH_Scan_Exit();
320
321#ifdef __cplusplus
322}
323#endif
324
325#endif  // OH_SCAN_H
326/** @} */
327