KSaneCore

interface.h
1/*
2 * SPDX-FileCopyrightText: 2007-2010 Kare Sars <kare dot sars at iki dot fi>
3 * SPDX-FileCopyrightText: 2007 Gilles Caulier <caulier dot gilles at gmail dot com>
4 * SPDX-FileCopyrightText: 2014 Gregor Mitsch : port to KDE5 frameworks
5 * SPDX-FileCopyrightText: 2021 Alexander Stippich <a.stippich@gmx.net>
6 *
7 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
8 */
9
10#ifndef KSANE_COREINTERFACE_H
11#define KSANE_COREINTERFACE_H
12
13#include "ksanecore_export.h"
14
15#include <memory>
16
17#include <QImage>
18#include <QJsonObject>
19#include <QList>
20#include <QObject>
21
22#include "deviceinformation.h"
23
24namespace KSaneCore
25{
26
27class InterfacePrivate;
28class Option;
29
30/**
31 * This class provides the core interface for accessing the scan controls and options.
32 */
33class KSANECORE_EXPORT Interface : public QObject
34{
35 Q_OBJECT
36 friend class InterfacePrivate;
37
38public:
39 /**
40 * Enum defining the message level of the returned scan status string.
41 * @note There might come more enumerations in the future.
42 */
44 NoError, // The scanning has finished successfully
45 ErrorGeneral, // The error string should contain an error message.
46 Information // There is some information to the user.
47 };
48
49 /**
50 * Enum determining whether the scanner opened correctly.
51 */
53 OpeningSucceeded, // scanner opened successfully
54 OpeningDenied, // access was denied,
55 OpeningFailed, // opening the scanner failed for unknown reasons
56 };
57
58 /**
59 * This enumeration is used to obtain a specific option with getOption(KSaneOptionName).
60 * Depending on the backend, not all options are available, nor this list is complete.
61 * For the remaining options, getOptionsList() must be used.
62 */
64 SourceOption,
65 ScanModeOption,
66 BitDepthOption,
67 ResolutionOption,
68 TopLeftXOption,
69 TopLeftYOption,
70 BottomRightXOption,
71 BottomRightYOption,
72 FilmTypeOption,
73 NegativeOption,
74 InvertColorOption,
75 PageSizeOption,
76 ThresholdOption,
77 XResolutionOption,
78 YResolutionOption,
79 PreviewOption,
80 WaitForButtonOption,
81 BrightnessOption,
82 ContrastOption,
83 GammaOption,
84 GammaRedOption,
85 GammaGreenOption,
86 GammaBlueOption,
87 BlackLevelOption,
88 WhiteLevelOption,
89 BatchModeOption,
90 BatchDelayOption,
91 };
92
93 /**
94 * This enumeration is used to filter the devices found by SANE.
95 * Sometimes, webcam may show up as scanner device and some
96 * more special scanner are also classified as cameras.
97 */
98 enum DeviceType { AllDevices, NoCameraAndVirtualDevices };
99
100 /**
101 * This constructor initializes the private class variables.
102 */
103 explicit Interface(QObject *parent = nullptr);
104
105 /**
106 * Standard destructor.
107 */
108 ~Interface() override;
109
110 /**
111 * Get the list of available scanning devices. Connect to availableDevices()
112 * which is fired once these devices are known. While the querying is done in a
113 * separate thread and thus not blocking the application, the application must
114 * ensure that no other action accessing the scanner device (settings options etc.)
115 * is performed during this period.
116 * @return whether the devices list are being reloaded or not
117 * @param type specify whether only specific device types shall be queried
118 */
119 bool reloadDevicesList(DeviceType type = AllDevices);
120
121 /**
122 * This method opens the specified scanner device and adds the scan options to the
123 * options list.
124 * @param deviceName is the SANE device name for the scanner to open.
125 * @return the status of the opening action.
126 */
127 OpenStatus openDevice(const QString &deviceName);
128
129 /**
130 * This method opens the specified scanner device with a specified username and password.
131 * Adds the scan options to the options list.
132 * @param deviceName is the SANE device name for the scanner to open.
133 * @param userName the username required to open for the scanner.
134 * @param password the password required to open for the scanner.
135 * @return the status of the opening action.
136 */
137 OpenStatus openRestrictedDevice(const QString &deviceName, const QString &userName, const QString &password);
138
139 /**
140 * This method closes the currently open scanner device.
141 * @return 'true' if all goes well and 'false' if no device is open.
142 */
143 bool closeDevice();
144
145 /**
146 * This method returns the internal device name of the currently opened scanner.
147 * @note Due to limitations of the SANE API, this will function will return an empty string
148 * if reloadDevicesList() has not been called before.
149 */
150 QString deviceName() const;
151
152 /**
153 * This method returns the vendor name of the currently opened scanner.
154 * @note Due to limitations of the SANE API, this will function will return an empty string
155 * if reloadDevicesList() has not been called before.
156 */
157 QString deviceVendor() const;
158
159 /**
160 * This method returns the model of the currently opened scanner.
161 * @note Due to limitations of the SANE API, this will function will return an empty string
162 * if reloadDevicesList() has not been called before.
163 */
164 QString deviceModel() const;
165
166 /**
167 * This function returns all available options when a device is opened.
168 * @return list containing pointers to all KSaneOptions provided by the backend.
169 * Becomes invalid when closing a device.
170 * The pointers must not be deleted by the client.
171 */
172 QList<Option *> getOptionsList();
173
174 /**
175 * This function returns a specific option.
176 * @param optionEnum the enum specifying the option.
177 * @return pointer to the KSaneOption. Returns a nullptr in case the options
178 * is not available for the currently opened device.
179 */
180 Option *getOption(OptionName optionEnum);
181
182 /**
183 * This function returns a specific option.
184 * @param optionName the internal name of the option defined by SANE.
185 * @return pointer to the KSaneOption. Returns a nullptr in case the options
186 * is not available for the currently opened device.
187 */
188 Option *getOption(const QString &optionName);
189
190 /**
191 * This method reads the available parameters and their values and
192 * returns them in a QMap (Name, value)
193 * @return map with the parameter names and their values.
194 */
195 QMap<QString, QString> getOptionsMap();
196
197 /**
198 * This method can be used to write many parameter values at once.
199 * @param options a QMap with the parameter names and values.
200 * @return This function returns the number of successful writes
201 * or -1 if scanning is in progress.
202 */
203 int setOptionsMap(const QMap<QString, QString> &options);
204
205 /**
206 * Gives direct access to the QImage that is used to store the image
207 * data retrieved from the scanner.
208 * Useful to display an in-progress image while scanning.
209 * When accessing the direct image pointer during a scan, the image
210 * must be locked before accessing the image and unlocked afterwards
211 * using the lockScanImage() and unlockScanImage() functions.
212 * @return pointer for direct access of the QImage data.
213 */
214 QImage *scanImage() const;
215
216 /**
217 * Locks the mutex protecting the QImage pointer of scanImage() from
218 * concurrent access during scanning.
219 */
220 void lockScanImage();
221
222 /**
223 * Unlocks the mutex protecting the QImage pointer of scanImage() from
224 * concurrent access during scanning. The scanning progress will blocked
225 * when lockScanImage() is called until unlockScanImage() is called.
226 */
227 void unlockScanImage();
228
229 /**
230 * Returns a JSON object containing the device name, model and vendor.
231 * A scanner device must have been opened before, returns an empty
232 * object otherwise. Mainly intended for debugging purposes and
233 * identifying issues with different scanner hardware.
234 * @return JSON object holding the data
235 */
236 QJsonObject scannerDeviceToJson();
237
238 /**
239 * Returns a JSON Object with all available data for all scanner options.
240 * A scanner device must have been opened before, returns an empty
241 * object otherwise. Mainly intended for debugging purposes and
242 * identifying issues with different scanner hardware.
243 * @return JSON object holding the data
244 */
245 QJsonObject scannerOptionsToJson();
246
247public Q_SLOTS:
248 /**
249 * This method is used to cancel a scan or prevent an automatic new scan.
250 */
251 void stopScan();
252
253 /**
254 * This method is used to start a scan.
255 * @note CoreInterface may return one or more images as a result of one invocation of this slot.
256 * If no more images are wanted stopScan() should be called in the slot handling the
257 * imageReady signal.
258 */
259 void startScan();
260
261Q_SIGNALS:
262 /**
263 * This signal is emitted when a final scan is ready.
264 * @param scannedImage is the QImage containing the scanned image data.
265 */
266 void scannedImageReady(const QImage &scannedImage);
267
268 /**
269 * This signal is emitted when the scanning has ended.
270 * @param status contains a ScanStatus status code.
271 * @param strStatus If an error has occurred this string will contain an error message.
272 * otherwise the string is empty.
273 */
275
276 /**
277 * This signal is emitted when the user is to be notified about something.
278 * @param type contains a ScanStatus code to identify the type of message (error/info/...).
279 * @param strStatus If an error has occurred this string will contain an error message.
280 * otherwise the string is empty.
281 */
283
284 /**
285 * This signal is emitted for progress information during a scan.
286 * @param percent is the percentage of the scan progress (0-100).
287 * A negative value indicates that a scan is being prepared.
288 */
289 void scanProgress(int percent);
290
291 /**
292 * This signal is emitted every time the device list is updated or
293 * after reloadDevicesList() is called.
294 * @param deviceList is a QList of KSane::DeviceInformation that contain the
295 * device name, model, vendor and type of the attached scanners.
296 * @note The list is only a snapshot of the current available devices. Devices
297 * might be added or removed/opened after the signal is emitted.
298 */
300
301 /**
302 * This signal is emitted when a hardware button is pressed.
303 * @param optionName is the untranslated technical name of the sane-option.
304 * @param optionLabel is the translated user visible label of the sane-option.
305 * @param pressed indicates if the value is true or false.
306 * @note The SANE standard does not specify hardware buttons and their behaviors,
307 * so this signal is emitted for sane-options that behave like hardware buttons.
308 * That is the sane-options are read-only and type boolean. The naming of hardware
309 * buttons also differ from backend to backend.
310 */
311 void buttonPressed(const QString &optionName, const QString &optionLabel, bool pressed);
312
313 /**
314 * This signal is emitted for the count down when in batch mode.
315 * @param remainingSeconds are the remaining seconds until the next scan starts.
316 */
317 void batchModeCountDown(int remainingSeconds);
318
319private:
320 std::unique_ptr<InterfacePrivate> d;
321};
322
323} // namespace KSaneCore
324
325#endif // KSANE_COREINTERFACE_H
This class provides the core interface for accessing the scan controls and options.
Definition interface.h:34
OptionName
This enumeration is used to obtain a specific option with getOption(KSaneOptionName).
Definition interface.h:63
void scannedImageReady(const QImage &scannedImage)
This signal is emitted when a final scan is ready.
ScanStatus
Enum defining the message level of the returned scan status string.
Definition interface.h:43
void availableDevices(const QList< DeviceInformation * > &deviceList)
This signal is emitted every time the device list is updated or after reloadDevicesList() is called.
void scanFinished(KSaneCore::Interface::ScanStatus status, const QString &strStatus)
This signal is emitted when the scanning has ended.
OpenStatus
Enum determining whether the scanner opened correctly.
Definition interface.h:52
void batchModeCountDown(int remainingSeconds)
This signal is emitted for the count down when in batch mode.
void userMessage(KSaneCore::Interface::ScanStatus status, const QString &strStatus)
This signal is emitted when the user is to be notified about something.
DeviceType
This enumeration is used to filter the devices found by SANE.
Definition interface.h:98
void scanProgress(int percent)
This signal is emitted for progress information during a scan.
void buttonPressed(const QString &optionName, const QString &optionLabel, bool pressed)
This signal is emitted when a hardware button is pressed.
A wrapper class providing access to the internal KSaneBaseOption to access all options provided by KS...
Definition option.h:29
Q_SCRIPTABLE CaptureState status()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:49:00 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.