Change contact email address as the nokia one will be no longer valid soon

[profile/ivi/ofono-qt.git] / lib / ofonointerface.h

diff --git a/lib/ofonointerface.h b/lib/ofonointerface.h
index 4234cdc..da3d6a5 100644 (file)
--- a/lib/ofonointerface.h
+++ b/lib/ofonointerface.h
@@ -1,18 +1,9 @@
-/**
- * This file is part of CellularQt
- *
- * Copyright (C) 2010 Nokia Corporation. All rights reserved.
- */
-
-#ifndef OFONOINTERFACE_H
-#define OFONOINTERFACE_H
-
 /*
  * This file is part of ofono-qt
  *
  * Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
  *
- * Contact: Alexander Kanavin <alexander.kanavin@nokia.com>
+ * Contact: Alexander Kanavin <alex.kanavin@gmail.com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -30,39 +21,112 @@
  *
  */
 
+#ifndef OFONOINTERFACE_H
+#define OFONOINTERFACE_H
+
 #include <QtCore/QObject>
 #include <QVariant>
 #include <QDBusVariant>
 #include <QDBusError>
+#include "ofonopropertysetting.h"
 #include "libofono-qt_global.h"
 
+//! Basic oFono interface class
+/*!
+ * This class implements basic access to properties of oFono interfaces.
+ * It should not be instantiated directly; instead you should instantiate
+ * interface-specific classes.
+ */
 class OFONO_QT_EXPORT OfonoInterface : public QObject
 {
     Q_OBJECT
 public:
-    enum GetPropertySetting {
-       GetAllOnStartup,
-       GetAllOnFirstRequest
-    };
 
-    OfonoInterface(const QString& path, const QString& ifname, GetPropertySetting setting, QObject *parent=0);
+    /*!
+     * \param path D-Bus path to the interface
+     * \param ifname D-Bus name of the interface
+     * \param setting specifies how the object should handle oFono properties of the interface
+     */
+    OfonoInterface(const QString &path, const QString &ifname, OfonoGetPropertySetting setting, QObject *parent=0);
     ~OfonoInterface();
 
+    //! Get all properties
+    /*!
+     * Returns the full set of current properties. If the object was constructed with
+     * OfonoInterface::GetAllOnFirstRequest, and no properties have been explicitly queried yet
+     * via requestProperty(), then returns nothing.
+     */
     QVariantMap properties() const;
-    void requestProperty(const QString& name);
-    void setProperty(const QString& name, const QVariant& property);
+    
+    //! Request a property asynchronously.
+    /*! 
+     * Result is returned via requestPropertyComplete() signal.
+     */
+    void requestProperty(const QString &name);
+
+    //! Set a property asynchronously.
+    /*!
+     * Result is returned via propertyChanged() signal
+     * if setting is successful or via setPropertyFailed() signal if setting has failed.
+     */
+    void setProperty(const QString &name, const QVariant &property, const QString& password=0);
+    
+    //! Resets the property cache.
     void resetProperties();
     
+    //! Get the interface D-Bus path
     QString path() const {return m_path;}
     
+    //! Get the interface D-Bus name
     QString ifname() const {return m_ifname;}
+
+    //! Get the D-Bus error name of the last operation.
+    /*!
+     * Returns the D-Bus error name of the last operation (setting a property
+     * or calling a method) if it has failed
+     */
     QString errorName() const {return m_errorName;}
+
+    //! Get the D-Bus error message of the last operation.
+    /*!
+     * Returns the D-Bus error message of the last operation (setting a property
+     * or calling a method) if it has failed
+     */
     QString errorMessage() const {return m_errorMessage;}
 
+public slots:
+    //! Changes the interface path
+    /*!
+     * This method changes the D-Bus path to the interface.
+     * Properties are updated immediately if property setting is set to
+     * GetAllOnStartup or reset otherwise.
+     */
+    void setPath(const QString &path);
+    
+    //! Sets the last error explicitly
+    void setError(const QString &errorName, const QString &errorMessage);
+
 signals:
-    void propertyChanged(const QString& name, const QVariant& property);
-    void requestPropertyComplete(bool success, const QString& name, const QVariant& property);
-    void setPropertyFailed(const QString& name);
+    //! Issued when a property has changed
+    /*!
+     * \param name name of the property
+     * \param property value of the property
+     */
+    void propertyChanged(const QString &name, const QVariant &property);
+    
+    //! Issued when requesting a property has completed
+    /*!
+     * \param success true if requesting a property was successful, false if there was an error
+     * \param name name of the property
+     * \param property value of the property
+     */
+    void requestPropertyComplete(bool success, const QString &name, const QVariant &property);
+    
+    //! Issued when setting a property has failed
+    /*!
+     * \param name name of the property
+     */
+    void setPropertyFailed(const QString &name);
 
 private slots:
     void onPropertyChanged(QString property, QDBusVariant value);
@@ -71,7 +135,6 @@ private slots:
     void setPropertyResp();
     void setPropertyErr(const QDBusError& error);
 protected slots:
-    void setPath(const QString& path);
 private:
     QVariantMap getAllPropertiesSync();
     
@@ -84,7 +147,7 @@ private:
    QString m_ifname;
    QVariantMap m_properties;
    QString m_pendingProperty;
-   GetPropertySetting m_getpropsetting;
+   OfonoGetPropertySetting m_getpropsetting;
 };
 
 #endif