1# OH_Scan
2
3
4## Overview
5
6Enables applications to use CAPI to access scanners.
7
8**Since**: 12
9
10
11## Summary
12
13
14### Types
15
16| Name| Description|
17| -------- | -------- |
18| Scan_ScannerDevice | Device information of a scanner.|
19| Scan_PictureScanProgress | Image scanning progress.|
20| Scan_ScannerOptions | Scanner options.|
21| Scan_ScannerDiscoveryCallback | Callback function for scanner discovery.|
22
23
24### Enums
25
26| Name| Description|
27| -------- | -------- |
28| Scan_ErrorCode | Enumerates the error codes.|
29
30
31### Functions
32
33| Name| Description|
34| -------- | -------- |
35| OH_Scan_Init | Starts the scanning service, initializes the client, and establishes a connection with the scanning service.|
36| OH_Scan_StartScannerDiscovery | Searches for scanners and registers a callback function to process the found scanners.|
37| OH_Scan_OpenScanner | Connects to a scanner.|
38| OH_Scan_CloseScanner | Disconnects from the scanner.|
39| OH_Scan_GetScannerParameter | Obtains scanner settings.|
40| OH_Scan_SetScannerParameter | Sets the option parameters of the scanner. |
41| OH_Scan_StartScan | Starts the scanner.|
42| OH_Scan_CancelScan | Cancels scanning.|
43| OH_Scan_GetPictureScanProgress | Queries the image scanning progress.|
44| OH_Scan_Exit | Exits the scanning service and releases the client memory.|
45
46
47## Type Description
48
49
50### Scan_ScannerDevice
51
52**Description**
53
54Device information of a scanner.
55
56**Since**: 12
57
58| Member        | Description    |
59| ------------ | -------- |
60| scannerId    | Scanner ID.|
61| manufacturer | Manufacturer.  |
62| model        | Device model.|
63| discoverMode | Device discovery mode|
64| serialNumber | Serial number.  |
65
66### Scan_PictureScanProgress
67
68**Description**
69
70Image scanning progress.
71
72**Since**: 12
73
74| Member    | Description                   |
75| -------- | ----------------------- |
76| progress | Image scanning progress. The value ranges from 0 to 100.|
77| fd       | Image handle.           |
78| isFinal  | Whether the next image is available.       |
79
80### Scan_ScannerOptions
81
82**Description**
83
84Scanner options.
85
86**Since**: 12
87
88| Member        | Description        |
89| ------------ | ------------ |
90| titles       | Option title.    |
91| descriptions | Option description.|
92| ranges       | Option range.    |
93| optionCount  | Number of options.    |
94
95### Scan_ScannerDiscoveryCallback
96
97**Description**
98
99Callback function for scanner discovery.
100
101**Since**: 12
102
103| Parameter       | Description      |
104| ----------- | ---------- |
105| devices     | Scanner.|
106| deviceCount | Number of scanners.  |
107
108
109
110## Enum Description
111
112
113### Scan_ErrorCode
114
115**Description**
116
117Enumerates the error codes.
118
119**Since**: 12
120
121| Value| Description|
122| -------- | -------- |
123| SCAN_ERROR_NONE | Operation succeeded.|
124| SCAN_ERROR_NO_PERMISSION | Permission denied.|
125| SCAN_ERROR_INVALID_PARAMETER | Invalid parameter.|
126| SCAN_ERROR_GENERIC_FAILURE | Internal error.|
127| SCAN_ERROR_RPC_FAILURE | PRC communication error.|
128| SCAN_ERROR_SERVER_FAILURE | Server error.|
129| SCAN_ERROR_UNSUPPORTED | Operation is not supported.|
130| SCAN_ERROR_CANCELED | Operation canceled.|
131| SCAN_ERROR_DEVICE_BUSY | Device is busy.|
132| SCAN_ERROR_INVALID | Invalid operation.|
133| SCAN_ERROR_JAMMED | Paper jammed at the paper feeder.|
134| SCAN_ERROR_NO_DOCS | Out of paper.|
135| SCAN_ERROR_COVER_OPEN | The cover of the scanner is opened.|
136| SCAN_ERROR_IO_ERROR | Scanner I/O operation error.|
137| SCAN_ERROR_NO_MEMORY | Insufficient memory.|
138
139
140## Function Description
141
142
143### OH_Scan_Init()
144
145```cpp
146int32_t OH_Scan_Init();
147```
148
149**Description**
150
151Starts the scanning service, initializes the client, and establishes a connection with the scanning service.
152
153**System capability**: ohos.permission.PRINT
154
155**Since**: 12
156
157**Returns**
158
159**Scan_ERROR_NONE**: Operation is succeeded.
160
161**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
162
163**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
164
165**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
166
167### OH_Scan_StartScannerDiscovery()
168
169```cpp
170int32_t OH_Scan_StartScannerDiscovery(Scan_ScannerDiscoveryCallback callback);
171```
172
173**Description**
174
175Searches for scanners and registers a callback function to process the found scanners.
176
177**System capability**: ohos.permission.PRINT
178
179**Since**: 12
180
181**Parameters**
182
183| Name    | Description                      |
184| -------- | -------------------------- |
185| callback | Callback function for scanner discovery.|
186
187**Returns**
188
189**Scan_ERROR_NONE**: Operation is succeeded.
190
191**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
192
193**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
194
195**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
196
197### OH_Scan_OpenScanner()
198
199```cpp
200int32_t OH_Scan_OpenScanner(const char* scannerId);
201```
202
203**Description**
204
205Connects to a scanner.
206
207**System capability**: ohos.permission.PRINT
208
209**Since**: 12
210
211**Parameters**
212
213| Name     | Description      |
214| --------- | ---------- |
215| scannerId | Scanner ID.|
216
217**Returns**
218
219**Scan_ERROR_NONE**: Operation is succeeded.
220
221**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
222
223**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
224
225**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
226
227**SCAN_ERROR_DEVICE_BUSY**: The scanner is busy.
228
229**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
230
231**SCAN_ERROR_IO_ERROR**: An I/O operation error occurs on the scanner.
232
233**SCAN_ERROR_NO_MEMORY**: The scanner memory is insufficient.
234
235### OH_Scan_CloseScanner()
236
237```cpp
238int32_t OH_Scan_CloseScanner(const char* scannerId);
239```
240
241**Description**
242
243Disconnects from a scanner.
244
245**System capability**: ohos.permission.PRINT
246
247**Since**: 12
248
249**Parameters**
250
251| Name     | Description      |
252| --------- | ---------- |
253| scannerId | Scanner ID.|
254
255**Returns**
256
257**Scan_ERROR_NONE**: Operation is succeeded.
258
259**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
260
261**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
262
263**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
264
265**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
266
267### OH_Scan_GetScannerParameter()
268
269```cpp
270Scan_ScannerOptions* OH_Scan_GetScannerParameter(const char* scannerId, int32_t* errorCode);
271```
272
273**Description**
274
275Obtains the scanner setting options. The memory is automatically released when returned structure points to {@link OH_Scan_Exit}. Only one copy of each scanner model is stored in the memory.
276
277**System capability**: ohos.permission.PRINT
278
279**Since**: 12
280
281**Parameters**
282
283| Name     | Description      |
284| --------- | ---------- |
285| scannerId | Scanner ID.|
286| errorCode | Error code.    |
287
288**Returns**
289
290**Scan_ERROR_NONE**: Operation is succeeded.
291
292**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
293
294**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
295
296**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
297
298### OH_Scan_SetScannerParameter()
299
300```cpp
301int32_t OH_Scan_SetScannerParameter(const char* scannerId, const int32_t option, const char* value);
302```
303
304**Description**
305
306Sets the option parameters of the scanner. The option values are obtained through the {@link OH_Scan_GetScannerParameter} API.
307
308**System capability**: ohos.permission.PRINT
309
310**Since**: 12
311
312**Parameters**
313
314| Name     | Description      |
315| --------- | ---------- |
316| scannerId | Scanner ID.|
317| option    | Option Number.  |
318| value     | Option value.    |
319
320**Returns**
321
322**Scan_ERROR_NONE**: Operation is succeeded.
323
324**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
325
326**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
327
328**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
329
330**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
331
332### OH_Scan_StartScan()
333
334```cpp
335int32_t OH_Scan_StartScan(const char* scannerId, bool batchMode);
336```
337
338**Description**
339
340Starts a scanner.
341
342**System capability**: ohos.permission.PRINT
343
344**Since**: 12
345
346**Parameters**
347
348| Name     | Description      |
349| --------- | ---------- |
350| scannerId | Scanner ID.|
351| batchMode | Batch processing mode.|
352
353**Returns**
354
355**Scan_ERROR_NONE**: Operation is succeeded.
356
357**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
358
359**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
360
361**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
362
363**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
364
365**SCAN_ERROR_JAMMED**: Paper jammed at the paper feeder.
366
367**SCAN_ERROR_NO_DOCS**: The scanner is out of paper.
368
369**SCAN_ERROR_COVER_OPEN**: The cover of the scanner is opened.
370
371**SCAN_ERROR_IO_ERROR**: An I/O operation exception occurs on the scanner.
372
373**SCAN_ERROR_NO_MEMORY**: The scanner memory is insufficient.
374
375**SCAN_ERROR_DEVICE_BUSY**: The scanner is busy.
376
377### OH_Scan_CancelScan()
378
379```cpp
380int32_t OH_Scan_CancelScan(const char* scannerId);
381```
382
383**Description**
384
385Cancels scanning.
386
387**System capability**: ohos.permission.PRINT
388
389**Since**: 12
390
391**Parameters**
392
393| Name     | Description      |
394| --------- | ---------- |
395| scannerId | Scanner ID.|
396
397**Returns**
398
399**Scan_ERROR_NONE**: Operation is succeeded.
400
401**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
402
403**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
404
405**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
406
407**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
408
409### OH_Scan_GetPictureScanProgress()
410
411```cpp
412int32_t OH_Scan_GetPictureScanProgress(const char* scannerId, Scan_PictureScanProgress* prog);
413```
414
415**Description**
416
417Queries the image scanning progress.
418
419**System capability**: ohos.permission.PRINT
420
421**Since**: 12
422
423**Parameters**
424
425| Name     | Description        |
426| --------- | ------------ |
427| scannerId | Scanner ID.  |
428| prog      | Image scanning progress.|
429
430**Returns**
431
432**Scan_ERROR_NONE**: Operation is succeeded.
433
434**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
435
436**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
437
438**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
439
440**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
441
442**SCAN_ERROR_JAMMED**: Paper jammed at the paper feeder.
443
444**SCAN_ERROR_NO_DOCS**: The scanner is out of paper.
445
446**SCAN_ERROR_COVER_OPEN**: The cover of the scanner is opened.
447
448**SCAN_ERROR_IO_ERROR**: An I/O operation exception occurs on the scanner.
449
450**SCAN_ERROR_NO_MEMORY**: The scanner memory is insufficient.
451
452**SCAN_ERROR_DEVICE_BUSY**: The scanner is busy.
453
454### OH_Scan_Exit()
455
456```cpp
457int32_t OH_Scan_Exit();
458```
459
460**Description**
461
462Exits the scanning service, clear the client memory, and cancel the registered scanning callback function.
463
464**System capability**: ohos.permission.PRINT
465
466**Since**: 12
467
468**Returns**
469
470**Scan_ERROR_NONE**: Operation is succeeded.
471
472**SCAN_ERROR_NO_PERMISSION**: Permission is denied.
473
474**SCAN_ERROR_RPC_FAILURE**: An RPC communication error occurs.
475
476**SCAN_ERROR_SERVER_FAILURE**: A server exception occurs.
477
478**SCAN_ERROR_INVALID_PARAMETER**: The parameter is invalid.
479