File indexing completed on 2024-10-27 07:30:05
0001 /* 0002 * SPDX-FileCopyrightText: 2007-2010 Kare Sars <kare dot sars at iki dot fi> 0003 * SPDX-FileCopyrightText: 2007 Gilles Caulier <caulier dot gilles at gmail dot com> 0004 * SPDX-FileCopyrightText: 2014 Gregor Mitsch : port to KDE5 frameworks 0005 * SPDX-FileCopyrightText: 2021 Alexander Stippich <a.stippich@gmx.net> 0006 * 0007 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0008 */ 0009 0010 #ifndef KSANE_COREINTERFACE_H 0011 #define KSANE_COREINTERFACE_H 0012 0013 #include "ksanecore_export.h" 0014 0015 #include <memory> 0016 0017 #include <QImage> 0018 #include <QList> 0019 #include <QObject> 0020 0021 #include "deviceinformation.h" 0022 0023 namespace KSaneCore 0024 { 0025 0026 class InterfacePrivate; 0027 class Option; 0028 0029 /** 0030 * This class provides the core interface for accessing the scan controls and options. 0031 */ 0032 class KSANECORE_EXPORT Interface : public QObject 0033 { 0034 Q_OBJECT 0035 friend class InterfacePrivate; 0036 0037 public: 0038 /** 0039 * Enum defining the message level of the returned scan status string. 0040 * @note There might come more enumerations in the future. 0041 */ 0042 enum ScanStatus { 0043 NoError, // The scanning has finished successfully 0044 ErrorGeneral, // The error string should contain an error message. 0045 Information // There is some information to the user. 0046 }; 0047 0048 /** 0049 * Enum determining whether the scanner opened correctly. 0050 */ 0051 enum OpenStatus { 0052 OpeningSucceeded, // scanner opened successfully 0053 OpeningDenied, // access was denied, 0054 OpeningFailed, // opening the scanner failed for unknown reasons 0055 }; 0056 0057 /** 0058 * This enumeration is used to obtain a specific option with getOption(KSaneOptionName). 0059 * Depending on the backend, not all options are available, nor this list is complete. 0060 * For the remaining options, getOptionsList() must be used. 0061 */ 0062 enum OptionName { 0063 SourceOption, 0064 ScanModeOption, 0065 BitDepthOption, 0066 ResolutionOption, 0067 TopLeftXOption, 0068 TopLeftYOption, 0069 BottomRightXOption, 0070 BottomRightYOption, 0071 FilmTypeOption, 0072 NegativeOption, 0073 InvertColorOption, 0074 PageSizeOption, 0075 ThresholdOption, 0076 XResolutionOption, 0077 YResolutionOption, 0078 PreviewOption, 0079 WaitForButtonOption, 0080 BrightnessOption, 0081 ContrastOption, 0082 GammaOption, 0083 GammaRedOption, 0084 GammaGreenOption, 0085 GammaBlueOption, 0086 BlackLevelOption, 0087 WhiteLevelOption, 0088 BatchModeOption, 0089 BatchDelayOption, 0090 }; 0091 0092 /** 0093 * This enumeration is used to filter the devices found by SANE. 0094 * Sometimes, webcam may show up as scanner device and some 0095 * more special scanner are also classified as cameras. 0096 */ 0097 enum DeviceType { AllDevices, NoCameraAndVirtualDevices }; 0098 0099 /** 0100 * This constructor initializes the private class variables. 0101 */ 0102 explicit Interface(QObject *parent = nullptr); 0103 0104 /** 0105 * Standard destructor. 0106 */ 0107 ~Interface() override; 0108 0109 /** 0110 * Get the list of available scanning devices. Connect to availableDevices() 0111 * which is fired once these devices are known. While the querying is done in a 0112 * separate thread and thus not blocking the application, the application must 0113 * ensure that no other action accessing the scanner device (settings options etc.) 0114 * is performed during this period. 0115 * @return whether the devices list are being reloaded or not 0116 * @param type specify whether only specific device types shall be queried 0117 */ 0118 bool reloadDevicesList(DeviceType type = AllDevices); 0119 0120 /** 0121 * This method opens the specified scanner device and adds the scan options to the 0122 * options list. 0123 * @param deviceName is the SANE device name for the scanner to open. 0124 * @return the status of the opening action. 0125 */ 0126 OpenStatus openDevice(const QString &deviceName); 0127 0128 /** 0129 * This method opens the specified scanner device with a specified username and password. 0130 * Adds the scan options to the options list. 0131 * @param deviceName is the SANE device name for the scanner to open. 0132 * @param userName the username required to open for the scanner. 0133 * @param password the password required to open for the scanner. 0134 * @return the status of the opening action. 0135 */ 0136 OpenStatus openRestrictedDevice(const QString &deviceName, const QString &userName, const QString &password); 0137 0138 /** 0139 * This method closes the currently open scanner device. 0140 * @return 'true' if all goes well and 'false' if no device is open. 0141 */ 0142 bool closeDevice(); 0143 0144 /** 0145 * This method returns the internal device name of the currently opened scanner. 0146 * @note Due to limitations of the SANE API, this will function will return an empty string 0147 * if reloadDevicesList() has not been called before. 0148 */ 0149 QString deviceName() const; 0150 0151 /** 0152 * This method returns the vendor name of the currently opened scanner. 0153 * @note Due to limitations of the SANE API, this will function will return an empty string 0154 * if reloadDevicesList() has not been called before. 0155 */ 0156 QString deviceVendor() const; 0157 0158 /** 0159 * This method returns the model of the currently opened scanner. 0160 * @note Due to limitations of the SANE API, this will function will return an empty string 0161 * if reloadDevicesList() has not been called before. 0162 */ 0163 QString deviceModel() const; 0164 0165 /** 0166 * This function returns all available options when a device is opened. 0167 * @return list containing pointers to all KSaneOptions provided by the backend. 0168 * Becomes invalid when closing a device. 0169 * The pointers must not be deleted by the client. 0170 */ 0171 QList<Option *> getOptionsList(); 0172 0173 /** 0174 * This function returns a specific option. 0175 * @param optionEnum the enum specifying the option. 0176 * @return pointer to the KSaneOption. Returns a nullptr in case the options 0177 * is not available for the currently opened device. 0178 */ 0179 Option *getOption(OptionName optionEnum); 0180 0181 /** 0182 * This function returns a specific option. 0183 * @param optionName the internal name of the option defined by SANE. 0184 * @return pointer to the KSaneOption. Returns a nullptr in case the options 0185 * is not available for the currently opened device. 0186 */ 0187 Option *getOption(const QString &optionName); 0188 0189 /** 0190 * This method reads the available parameters and their values and 0191 * returns them in a QMap (Name, value) 0192 * @return map with the parameter names and their values. 0193 */ 0194 QMap<QString, QString> getOptionsMap(); 0195 0196 /** 0197 * This method can be used to write many parameter values at once. 0198 * @param options a QMap with the parameter names and values. 0199 * @return This function returns the number of successful writes 0200 * or -1 if scanning is in progress. 0201 */ 0202 int setOptionsMap(const QMap<QString, QString> &options); 0203 0204 /** 0205 * Gives direct access to the QImage that is used to store the image 0206 * data retrieved from the scanner. 0207 * Useful to display an in-progress image while scanning. 0208 * When accessing the direct image pointer during a scan, the image 0209 * must be locked before accessing the image and unlocked afterwards 0210 * using the lockScanImage() and unlockScanImage() functions. 0211 * @return pointer for direct access of the QImage data. 0212 */ 0213 QImage *scanImage() const; 0214 0215 /** 0216 * Locks the mutex protecting the QImage pointer of scanImage() from 0217 * concurrent access during scanning. 0218 */ 0219 void lockScanImage(); 0220 0221 /** 0222 * Unlocks the mutex protecting the QImage pointer of scanImage() from 0223 * concurrent access during scanning. The scanning progress will blocked 0224 * when lockScanImage() is called until unlockScanImage() is called. 0225 */ 0226 void unlockScanImage(); 0227 0228 public Q_SLOTS: 0229 /** 0230 * This method is used to cancel a scan or prevent an automatic new scan. 0231 */ 0232 void stopScan(); 0233 0234 /** 0235 * This method is used to start a scan. 0236 * @note CoreInterface may return one or more images as a result of one invocation of this slot. 0237 * If no more images are wanted stopScan() should be called in the slot handling the 0238 * imageReady signal. 0239 */ 0240 void startScan(); 0241 0242 Q_SIGNALS: 0243 /** 0244 * This signal is emitted when a final scan is ready. 0245 * @param scannedImage is the QImage containing the scanned image data. 0246 */ 0247 void scannedImageReady(const QImage &scannedImage); 0248 0249 /** 0250 * This signal is emitted when the scanning has ended. 0251 * @param status contains a ScanStatus status code. 0252 * @param strStatus If an error has occurred this string will contain an error message. 0253 * otherwise the string is empty. 0254 */ 0255 void scanFinished(KSaneCore::Interface::ScanStatus status, const QString &strStatus); 0256 0257 /** 0258 * This signal is emitted when the user is to be notified about something. 0259 * @param type contains a ScanStatus code to identify the type of message (error/info/...). 0260 * @param strStatus If an error has occurred this string will contain an error message. 0261 * otherwise the string is empty. 0262 */ 0263 void userMessage(KSaneCore::Interface::ScanStatus status, const QString &strStatus); 0264 0265 /** 0266 * This signal is emitted for progress information during a scan. 0267 * @param percent is the percentage of the scan progress (0-100). 0268 * A negative value indicates that a scan is being prepared. 0269 */ 0270 void scanProgress(int percent); 0271 0272 /** 0273 * This signal is emitted every time the device list is updated or 0274 * after reloadDevicesList() is called. 0275 * @param deviceList is a QList of KSane::DeviceInformation that contain the 0276 * device name, model, vendor and type of the attached scanners. 0277 * @note The list is only a snapshot of the current available devices. Devices 0278 * might be added or removed/opened after the signal is emitted. 0279 */ 0280 void availableDevices(const QList<DeviceInformation *> &deviceList); 0281 0282 /** 0283 * This signal is emitted when a hardware button is pressed. 0284 * @param optionName is the untranslated technical name of the sane-option. 0285 * @param optionLabel is the translated user visible label of the sane-option. 0286 * @param pressed indicates if the value is true or false. 0287 * @note The SANE standard does not specify hardware buttons and their behaviors, 0288 * so this signal is emitted for sane-options that behave like hardware buttons. 0289 * That is the sane-options are read-only and type boolean. The naming of hardware 0290 * buttons also differ from backend to backend. 0291 */ 0292 void buttonPressed(const QString &optionName, const QString &optionLabel, bool pressed); 0293 0294 /** 0295 * This signal is emitted for the count down when in batch mode. 0296 * @param remainingSeconds are the remaining seconds until the next scan starts. 0297 */ 0298 void batchModeCountDown(int remainingSeconds); 0299 0300 private: 0301 std::unique_ptr<InterfacePrivate> d; 0302 }; 0303 0304 } // namespace KSaneCore 0305 0306 #endif // KSANE_COREINTERFACE_H