File indexing completed on 2024-04-14 04:37:16

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