1 /*
2     SPDX-FileCopyrightText: 2014 Jasem Mutlaq <mutlaqja@ikarustech.com>
3 
4     SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include <QObject>
10 #include <QtDBus/QtDBus>
11 
12 /**
13  * @class INDIDBus
14  *
15  * Collection of INDI DBus functions.
16  *
17  * @author Jasem Mutlaq
18  */
19 class INDIDBus : public QObject
20 {
21     Q_OBJECT
22     Q_CLASSINFO("D-Bus Interface", "org.kde.kstars.INDI")
23 
24   public:
25     explicit INDIDBus(QObject *parent = nullptr);
26 
27     /** @defgroup INDIDBusInterface INDI DBus Interface
28          * INDIDBus interface provides complete scripting capability over INDI servers and devices within KStars.
29          *
30          * A Python DBus <a href="http://indilib.org/support/tutorials/148-dbus-scripting-with-kstars-python.html">tutorial</a> demonstrates
31          * the capabilities of the INDI DBus interface.
32         */
33 
34     /*@{*/
35 
36     /** DBUS interface function.  Start a local INDI server given a list of drivers on the given port.
37         * @param port Port used to establish  server. If empty, default port 7624 is used.
38         * @param drivers List of drivers executables to run.
39         */
40     Q_SCRIPTABLE bool start(const QString &port, const QStringList &drivers);
41 
42     /** DBUS interface function.  Stops server running on the given port
43           @param port Port of existing  server to stop
44         */
45     Q_SCRIPTABLE bool stop(const QString &port);
46 
47     /** DBUS interface function. Connect to an INDI server
48         * @param host hostname of  server to connect to.
49         * @param port Port of  server.
50         */
51     Q_SCRIPTABLE bool connect(const QString &host, const QString &port);
52 
53     /** DBUS interface function. Disconnect from an INDI server
54         * @param host hostname of  server to disconnect.
55         * @param port Port of  server.
56         */
57     Q_SCRIPTABLE bool disconnect(const QString &host, const QString &port);
58 
59     /** DBUS interface function. Returns a list of INDI devices
60         * @returns List of  device names
61         */
62     Q_SCRIPTABLE QStringList getDevices();
63 
64     /** DBUS interface function. Returns a list of INDI properties
65         * @param device device name
66         * @returns List of  properties in the format DEVICE.PROPERTY.ELEMENT.
67         */
68     Q_SCRIPTABLE QStringList getProperties(const QString &device);
69 
70     /** DBUS interface function. Returns INDI property state
71         * @param device device name
72         * @param property property name
73         * @returns Idle, Ok, Busy, or Alert. If no property is found, it returns "Invalid"
74         */
75     Q_SCRIPTABLE QString getPropertyState(const QString &device, const QString &property);
76 
77     /** DBUS interface function. Sends property to INDI server
78         * @param device device name
79         * @param property property name
80         * @returns true if property is found and sent to  server, false otherwise.
81         */
82     Q_SCRIPTABLE bool sendProperty(const QString &device, const QString &property);
83 
84     /** DBUS interface function. Set INDI Switch status
85         * @param device device name
86         * @param property property name
87         * @param switchName switch name
88         * @param status Either On or Off.
89         * /note This function ONLY sets the switch status but does not send it to  server. Use sendProperty to send a switch to  server.
90         */
91     Q_SCRIPTABLE bool setSwitch(const QString &device, const QString &property, const QString &switchName,
92                                 const QString &status);
93 
94     /** DBUS interface function. Returns INDI switch status
95         * @param device device name
96         * @param property property name
97         * @param switchName switch name
98         * @returns On or Off if switch is found. If no switch is found, it returns "Invalid".
99         */
100     Q_SCRIPTABLE QString getSwitch(const QString &device, const QString &property, const QString &switchName);
101 
102     /** DBUS interface function. Set INDI Text
103         * @param device device name
104         * @param property property name
105         * @param textName text element name
106         * @param text text value
107         * /note This function ONLY sets the text value but does not send it to  server. Use sendProperty to send a text to  server.
108         */
109     Q_SCRIPTABLE bool setText(const QString &device, const QString &property, const QString &textName,
110                               const QString &text);
111 
112     /** DBUS interface function. Returns INDI text value
113         * @param device device name
114         * @param property property name
115         * @param textName text element name
116         * @returns text value. If no text is found, it returns "Invalid".
117         */
118     Q_SCRIPTABLE QString getText(const QString &device, const QString &property, const QString &textName);
119 
120     /** DBUS interface function. Set INDI  Number
121         * @param device device name
122         * @param property property name
123         * @param numberName number element name
124         * @param value number value
125         * @returns true if successful, false otherwise.
126         * /note This function ONLY sets the number value but does not send it to  server. Use sendProperty to send a number to  server.
127         */
128     Q_SCRIPTABLE bool setNumber(const QString &device, const QString &property, const QString &numberName,
129                                 double value);
130 
131     /** DBUS interface function. Returns INDI number value
132         * @param device device name
133         * @param property name
134         * @param numberName number element name
135         * @returns number value. If no text is found, it returns NAN.
136         */
137     Q_SCRIPTABLE double getNumber(const QString &device, const QString &property, const QString &numberName);
138 
139     /** DBUS interface function. Returns INDI  Light state
140         * @param device device name
141         * @param property name
142         * @param lightName light element name
143         * @returns Idle, Ok, Busy, or Alert. If no property is found, it returns "Invalid"
144         */
145     Q_SCRIPTABLE QString getLight(const QString &device, const QString &property, const QString &lightName);
146 
147     /** DBUS interface function. Returns INDI blob data. It can be extremely inefficient transporting large amount of data via DBUS.
148         * @param device device name
149         * @param property property name
150         * @param blobName blob element name
151         * @param blobFormat blob element format. It is usually the extension of the blob file.
152         * @param size blob element size in bytes. If -1, then there is an error.
153         * @returns array of bytes containing blob.
154         * @see getBLOBFile
155         */
156     Q_SCRIPTABLE QByteArray getBLOBData(const QString &device, const QString &property, const QString &blobName,
157                                         QString &blobFormat, int &size);
158 
159     /** DBUS interface function. Returns INDI blob filename stored on the local file system.
160         * @param device device name
161         * @param property property name
162         * @param blobName blob element name
163         * @param blobFormat blob element format. It is usually the extension of a file.
164         * @param size blob element size in bytes. If -1, then there is an error.
165         * @returns full file name
166         */
167     Q_SCRIPTABLE QString getBLOBFile(const QString &device, const QString &property, const QString &blobName,
168                                      QString &blobFormat, int &size);
169 
170     /** @}*/
171 };
172