ohscan.h

Overview

Declares APIs for discovering and connecting to scanners, scanning pictures, querying the scan progress, and setting parameters for scanning.

File to include: <BasicServicesKit/ohscan.h>

Library: libohscan.so

System capability: SystemCapability.Print.PrintFramework

Since: 12

Related module: OH_Scan

Summary

Structs

Name	typedef Keyword	Description
Scan_ScannerDevice	Scan_ScannerDevice	Defines scanner information.
Scan_PictureScanProgress	Scan_PictureScanProgress	Defines the progress of scanning a picture by the scanner.
Scan_ScannerOptions	Scan_ScannerOptions	Defines all parameter options of a scanner.

Enums

Name	typedef Keyword	Description
Scan_ErrorCode	Scan_ErrorCode	Enumerates the error codes.

Functions

Name	typedef Keyword	Description
typedef void (Scan_ScannerDiscoveryCallback)(Scan_ScannerDevice* devices, int32_t deviceCount)	Scan_ScannerDiscoveryCallback	Discovers scanners. The memory pointed to by the pointer registered via OH_Scan_StartScannerDiscovery will be released when the callback function ends.
int32_t OH_Scan_Init()	-	Initiates the scan service, initializes the scan client, and connects the client to the scan service.
int32_t OH_Scan_StartScannerDiscovery(Scan_ScannerDiscoveryCallback callback)	-	Starts scanner discovery and registers a callback used to process the discovered scanners.
int32_t OH_Scan_OpenScanner(const char* scannerId)	-	Opens a scanner.
int32_t OH_Scan_CloseScanner(const char* scannerId)	-	Closes a connected scanner.
Scan_ScannerOptions* OH_Scan_GetScannerParameter(const char* scannerId, int32_t* errorCode)	-	Obtains the scanner setting options. The memory to which the returned struct pointer points is automatically released when OH_Scan_Exit is called. Only one copy of each scanner model is stored in the memory.
int32_t OH_Scan_SetScannerParameter(const char* scannerId, const int32_t option, const char* value)	-	Sets the option parameters of a scanner. The option values are obtained through the OH_Scan_GetScannerParameter API.
int32_t OH_Scan_StartScan(const char* scannerId, bool batchMode)	-	Starts scanning.
int32_t OH_Scan_CancelScan(const char* scannerId)	-	Cancels scanning.
int32_t OH_Scan_GetPictureScanProgress(const char* scannerId, Scan_PictureScanProgress* prog)	-	Obtains the progress of scanning a picture by the scanner. A non-null value must be passed. The scan progress will be written into the struct pointed to by the pointer.
int32_t OH_Scan_Exit()	-	Exits the scan service, releases the memory of the scan framework, and deregisters the scanner discovery callback.

Enum Description

Scan_ErrorCode

enum Scan_ErrorCode

Description

Enumerates the error codes.

Since: 12

Enum Item	Description
SCAN_ERROR_NONE = 0	Operation successful.
SCAN_ERROR_NO_PERMISSION = 201	Permission verification failed.
SCAN_ERROR_INVALID_PARAMETER = 401	Invalid parameter. For example, the pointer or string is null.
SCAN_ERROR_GENERIC_FAILURE = 24300101	Internal error.
SCAN_ERROR_RPC_FAILURE = 24300102	RPC communication error.
SCAN_ERROR_SERVER_FAILURE = 24300103	Server error.
SCAN_ERROR_UNSUPPORTED = 24300104	Unsupported operation.
SCAN_ERROR_CANCELED = 24300105	Operation canceled.
SCAN_ERROR_DEVICE_BUSY = 24300106	Device busy.
SCAN_ERROR_INVALID = 24300107	Invalid data (for example, no device is available when the scanner is started).
SCAN_ERROR_JAMMED = 24300108	Paper jam in feeder.
SCAN_ERROR_NO_DOCS = 24300109	Out of paper.
SCAN_ERROR_COVER_OPEN = 24300110	Scanner cover open.
SCAN_ERROR_IO_ERROR = 24300111	Scanner I/O error.
SCAN_ERROR_NO_MEMORY = 24300112	Insufficient memory.

Function Description

Scan_ScannerDiscoveryCallback()

typedef void (*Scan_ScannerDiscoveryCallback)(Scan_ScannerDevice** devices, int32_t deviceCount)

Description

Discovers scanners. The memory pointed to by the pointer registered via OH_Scan_StartScannerDiscovery will be released when the callback function ends.

Since: 12

Parameters

Name	Description
Scan_ScannerDevice** devices	Double pointer to the list of all discovered scanners.
int32_t deviceCount	Number of scanners discovered.

OH_Scan_Init()

int32_t OH_Scan_Init()

Description

Initiates the scan service, initializes the scan client, and connects the client to the scan service.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error.

OH_Scan_StartScannerDiscovery()

int32_t OH_Scan_StartScannerDiscovery(Scan_ScannerDiscoveryCallback callback)

Description

Starts scanner discovery and registers a callback used to process the discovered scanners.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
Scan_ScannerDiscoveryCallback callback	Scan_ScannerDiscoveryCallback used to discover scanners.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error.

OH_Scan_OpenScanner()

int32_t OH_Scan_OpenScanner(const char* scannerId)

Description

Opens a scanner.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error. SCAN_ERROR_DEVICE_BUSY: device busy. SCAN_ERROR_INVALID_PARAMETER: invalid parameter. SCAN_ERROR_IO_ERROR: scanner I/O error. SCAN_ERROR_NO_MEMORY: insufficient memory.

OH_Scan_CloseScanner()

int32_t OH_Scan_CloseScanner(const char* scannerId)

Description

Closes a connected scanner.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error. SCAN_ERROR_INVALID_PARAMETER: invalid parameter.

OH_Scan_GetScannerParameter()

Scan_ScannerOptions* OH_Scan_GetScannerParameter(const char* scannerId, int32_t* errorCode)

Description

Obtains the scanner setting options. The memory to which the returned struct pointer points is automatically released when OH_Scan_Exit is called. Only one copy of each scanner model is stored in the memory.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.
int32_t* errorCode	Pointer to the error code. If the operation is successful, SCAN_ERROR_NONE is returned; otherwise, a specific error code is returned. For details, see Print_ErrorCode.

Returns

Type	Description
Scan_ScannerOptions*	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error. SCAN_ERROR_INVALID_PARAMETER: invalid parameter.

OH_Scan_SetScannerParameter()

int32_t OH_Scan_SetScannerParameter(const char* scannerId, const int32_t option, const char* value)

Description

Sets the option parameters of a scanner. The option values are obtained through the OH_Scan_GetScannerParameter API.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.
const int32_t option	ID of the option to be set. The value, obtained from Scan_ScannerOptions, ranges from 0 to optionCount – 1.
const char* value	Pointer to the option value to be set. The valid value is obtained from ranges of Scan_ScannerOptions.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error. SCAN_ERROR_INVALID_PARAMETER: invalid parameter.

OH_Scan_StartScan()

int32_t OH_Scan_StartScan(const char* scannerId, bool batchMode)

Description

Starts scanning.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.
bool batchMode	Whether to start the scanner in batch processing mode.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error. SCAN_ERROR_JAMMED: paper jam in feeder. SCAN_ERROR_NO_DOCS: out of paper. SCAN_ERROR_COVER_OPEN: scanner cover open. SCAN_ERROR_IO_ERROR: scanner I/O error. SCAN_ERROR_NO_MEMORY: insufficient memory. SCAN_ERROR_INVALID_PARAMETER: invalid parameter. SCAN_ERROR_DEVICE_BUSY: device busy.

Type

Description

int32_t

SCAN_ERROR_NONE: operation successful.
SCAN_ERROR_NO_PERMISSION: permission denied.
SCAN_ERROR_RPC_FAILURE: RPC communication error.
SCAN_ERROR_SERVER_FAILURE: server error.
SCAN_ERROR_JAMMED: paper jam in feeder.
SCAN_ERROR_NO_DOCS: out of paper.
SCAN_ERROR_COVER_OPEN: scanner cover open.
SCAN_ERROR_IO_ERROR: scanner I/O error.
SCAN_ERROR_NO_MEMORY: insufficient memory.
SCAN_ERROR_INVALID_PARAMETER: invalid parameter.
SCAN_ERROR_DEVICE_BUSY: device busy.

OH_Scan_CancelScan()

int32_t OH_Scan_CancelScan(const char* scannerId)

Description

Cancels scanning.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_INVALID_PARAMETER: invalid parameter. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error.

OH_Scan_GetPictureScanProgress()

int32_t OH_Scan_GetPictureScanProgress(const char* scannerId, Scan_PictureScanProgress* prog)

Description

Obtains the progress of scanning a picture by the scanner. A non-null value must be passed. The scan progress will be written into the struct pointed to by the pointer.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Parameters

Name	Description
const char* scannerId	Pointer to the scanner ID.
Scan_PictureScanProgress* prog	Pointer to Scan_PictureScanProgress. The value cannot be empty.

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_INVALID_PARAMETER: invalid parameter. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error. SCAN_ERROR_JAMMED: paper jam in feeder. SCAN_ERROR_NO_DOCS: out of paper. SCAN_ERROR_COVER_OPEN: scanner cover open. SCAN_ERROR_IO_ERROR: scanner I/O error. SCAN_ERROR_NO_MEMORY: insufficient memory. SCAN_ERROR_DEVICE_BUSY: device busy.

Type

Description

int32_t

SCAN_ERROR_NONE: operation successful.
SCAN_ERROR_NO_PERMISSION: permission denied.
SCAN_ERROR_INVALID_PARAMETER: invalid parameter.
SCAN_ERROR_RPC_FAILURE: RPC communication error.
SCAN_ERROR_SERVER_FAILURE: server error.
SCAN_ERROR_JAMMED: paper jam in feeder.
SCAN_ERROR_NO_DOCS: out of paper.
SCAN_ERROR_COVER_OPEN: scanner cover open.
SCAN_ERROR_IO_ERROR: scanner I/O error.
SCAN_ERROR_NO_MEMORY: insufficient memory.
SCAN_ERROR_DEVICE_BUSY: device busy.

OH_Scan_Exit()

int32_t OH_Scan_Exit()

Description

Exits the scan service, releases the memory of the scan framework, and deregisters the scanner discovery callback.

System capability: SystemCapability.Print.PrintFramework

Required permissions: ohos.permission.PRINT

Since: 12

Returns

Type	Description
int32_t	SCAN_ERROR_NONE: operation successful. SCAN_ERROR_NO_PERMISSION: permission denied. SCAN_ERROR_RPC_FAILURE: RPC communication error. SCAN_ERROR_SERVER_FAILURE: server error.