Document Networksettings API

4 files changed, 88 insertions, 15 deletions

diff --git a/noncore/settings/networksettings/interfaces/interfaceinformationimp.h b/noncore/settings/networksettings/interfaces/interfaceinformationimp.h
index 9c93d1d..03da736 100644
--- a/noncore/settings/networksettings/interfaces/interfaceinformationimp.h
+++ b/noncore/settings/networksettings/interfaces/interfaceinformationimp.h
@@ -1,28 +1,32 @@
-#ifndef INTERFACEINFORMATIONIMP_H 
+#ifndef INTERFACEINFORMATIONIMP_H
 #define INTERFACEINFORMATIONIMP_H
 
 #include "interfaceinformation.h"
 #include "interface.h"
 
+/**
+ * This widget just shows some generic information about the
+ * given Interface. IP Addresses and such will be shown.
+ */
 class InterfaceInformationImp : public InterfaceInformation {
 
 Q_OBJECT
-        
+
 public:
   InterfaceInformationImp(QWidget *parent=0, const char *name=0, Interface *i=0, WFlags f=0);
   ~InterfaceInformationImp();
-  
+
 private slots:
   void advanced();
   void updateInterface(Interface *i);
   void showMessage(const QString &message);
 
 private:
   Interface *interface;
-  
+
 };
 
 #endif
 
 // addserviceimp.h
 
diff --git a/noncore/settings/networksettings/interfaces/interfacesetupimp.h b/noncore/settings/networksettings/interfaces/interfacesetupimp.h
index 172da6a..f38fba5 100644
--- a/noncore/settings/networksettings/interfaces/interfacesetupimp.h
+++ b/noncore/settings/networksettings/interfaces/interfacesetupimp.h
@@ -1,58 +1,64 @@
 #ifndef INTERFACESETUPIMP_H
 #define INTERFACESETUPIMP_H
 
 #include "interfacesetup.h"
 #include "interfaces.h"
 #include <qdialog.h>
 
 class Interface;
 
+/**
+ * A default  implementation for setting up basic
+ * network config. Like DHCP, IP and other information.
+ * You can use it in a tab or  in any other way*
+ * On saveChanges() it'll save the changes to Interfaces.
+ */
 class InterfaceSetupImp : public InterfaceSetup {
   Q_OBJECT
-        
+
 public:
   InterfaceSetupImp( QWidget* parent = 0, const char* name = 0, Interface *i = 0, Interfaces *j = 0, WFlags fl = 0);
   ~InterfaceSetupImp();
   bool saveChanges();
-  
+
 public slots:
   void setProfile(const QString &profile);
   bool saveSettings();
 
 private:
   Interfaces *interfaces;
   Interface  *interface;
 
   bool delInterfaces;
 };
 
 
 #include <qlayout.h>
 
 class InterfaceSetupImpDialog : public QDialog {
 Q_OBJECT
-        
+
 public:
     InterfaceSetupImpDialog(QWidget* parent = 0, const char* name = 0, Interface *i=0, bool modal = false, WFlags fl = 0) : QDialog(parent, name, modal, fl){
     QVBoxLayout *InterfaceSetupLayout = new QVBoxLayout( this );
     setCaption("Interface Setup");
     interfaceSetup = new InterfaceSetupImp(this, "InterfaceSetup",i);
     InterfaceSetupLayout->addWidget( interfaceSetup );
   };
   void setProfile(QString &profile){ interfaceSetup->setProfile(profile);};
 
 private:
   InterfaceSetupImp *interfaceSetup;
 
 protected slots:
   void accept(){
     if(interfaceSetup->saveChanges())
       QDialog::accept();
   };
 
 };
 
 #endif
 
 // interfacesetupimp.h
 
diff --git a/noncore/settings/networksettings/module.h b/noncore/settings/networksettings/module.h
index 5cc82cd..3ef823c 100644
--- a/noncore/settings/networksettings/module.h
+++ b/noncore/settings/networksettings/module.h
@@ -1,113 +1,176 @@
 #ifndef NETCONF_MODULE_H
 #define NETCONF_MODULE_H
 
 #include <qobject.h>
 #if QT_VERSION < 300
 #include <qlist.h>
 #else
 #include <qptrlist.h>
 #endif
 #include <qmap.h>
 #include "interface.h"
 
 class QWidget;
 class QTabWidget;
 
-class Module : QObject{
+
+/**
+ * \brief The basis of all plugins
+ *
+ * This is the way to extend networksettings with
+ * extra functionality.
+ *
+ *
+ * Networksettings in the 1.0 release does not use QCOM
+ * for activation. You need to provide the following function yourself.
+ *
+ * A module needs to provide Name, Images, and methods for
+ * claiming interfaces. For example you can claim physicla
+ * interfaces like wlan0, ppp0 or virtual like a VPN
+ * connection and hide the real ppp device or ethernet device
+ * behind your VPN plugin.
+ *
+ * During start up. The main application searches for network devices
+ * and then looks for an owner under the plugins for them.
+ * For example the WLAN Plugin looks if there is a WLAN Extension
+ * on that interface and then claims it by returning true from isOwner()
+ *
+ * \code
+ * extern "C"
+ *  {
+ *   void* create_plugin() {
+ *   return new WLANModule();
+ * }
+ * };
+ * \endcode
+ * @see isOwner(Interface*)
+ */
+class Module : private QObject{
 
 signals:
+/**
+ * Emit this Signal once you change the Interface
+ * you're operating on
+ *
+ * @param i The Interface
+ */
   void updateInterface(Interface *i);
 
 
 public:
   Module(){};
 
   /**
    * The type of the plugin
-   * and the name of the dcop call
+   * and the name of the qcop call
    */
   virtual const QString type() = 0;
 
   /**
    * The current profile has been changed and the module should do any
    * neccesary changes also.
+   * As of Opie1.0 profiles are disabled.
+   *
    * @param newProfile what the profile should be changed to.
    */
   virtual void setProfile(const QString &newProfile) = 0;
 
   /**
    * get the icon name for this device.
    * @param Interface* can be used in determining the icon.
    * @return QString the icon name (minus .png, .gif etc)
    */
   virtual QString getPixmapName(Interface *) = 0;
 
   /**
    * Check to see if the interface i is owned by this module.
+   * See if you can handle it. And if you can claim ownership
+   * by returning true.
    * @param Interface* interface to check against
    * @return bool true if i is owned by this module, false otherwise.
    */
   virtual bool isOwner(Interface *){ return false; };
 
   /**
-   * Create and return the WLANConfigure Module
+   * Create and return the Configure Module
    * @param Interface *i the interface to configure.
    * @return QWidget* pointer to this modules configure.
+   *
+   * @see InterfaceSetupImp
    */
   virtual QWidget *configure(Interface *){ return NULL; } ;
 
   /**
-   * Create, and return the Information Module
+   * Create, and return the Information Module.
+   *
+   * An default Implementation is InterfaceInformationImp
+   *
    * @param Interface *i the interface to get info on.
    * @return QWidget* pointer to this modules info.
+   *
+   * @see InterfaceInformationImp
+   *
    */
   virtual QWidget *information(Interface *){ return NULL; };
 
   /**
-   * Get all active (up or down) interfaces
+   * Get all active (up or down) interfaces managed by this
+   * module.
    * @return QList<Interface> A list of interfaces that exsist that havn't
    * been called by isOwner()
    */
   virtual QList<Interface> getInterfaces() = 0;
 
   /**
    * Adds possible new interfaces to the list (Example: usb(ppp), ir(ppp),
    *  modem ppp)
+   * Both strings need to be translated. The first string is a Shortcut
+   * like PPP and the second argument is a description.
+   *
+   * <code>
+   *  list.insert(
+   *
+   * </code>
+   *
+   * @param list A reference to the list of supported additionns.
    */
   virtual void possibleNewInterfaces(QMap<QString, QString> &list) = 0;
 
   /**
-   * Attempts to create a new interface from name
+   * Attempts to create a new interface from name you gave
+   * possibleNewInterfaces()
    * @return Interface* NULL if it was unable to be created.
    * @param name the type of interface to create
+   *
+   * @see possibleNewInterfaces
    */
   virtual Interface *addNewInterface(const QString &name) = 0;
 
   /**
    * Attempts to remove the interface, doesn't delete i
    * @return bool true if successful, false otherwise.
    */
   virtual bool remove(Interface* i) = 0;
 
   /**
    * get dcop calls
    */
   virtual void receive(const QCString &msg, const QByteArray &arg) = 0;
 
     QStringList handledInterfaceNames()const { return m_inter; }
 protected:
     /**
      * set which interfaceNames should not be shown cause they're handled
      * internally of this module.. An already running ppp link or
-     * a tunnel...
+     * a tunnel... VPN an such
      */
     void setHandledInterfaceNames( const QStringList& in) { m_inter = in; }
 
 private:
     QStringList m_inter;
 };
 
 #endif
 
 // module.h
 
diff --git a/noncore/settings/networksettings/ppp/pppmodule.cpp b/noncore/settings/networksettings/ppp/pppmodule.cpp
index 2462fa4..f7dacf6 100644
--- a/noncore/settings/networksettings/ppp/pppmodule.cpp
+++ b/noncore/settings/networksettings/ppp/pppmodule.cpp
@@ -1,250 +1,250 @@
 #include <errno.h>
 #include <signal.h>
 
 
 #include <qpe/config.h>
 
 #include "modem.h"
 #include "pppconfig.h"
 #include "pppmodule.h"
 #include "pppdata.h"
 #include "interfaceinformationppp.h"
 #include "interfaceppp.h"
 
 // don't polute global namespace
 namespace {
     /*
      * If network settings is qutting and we've ppp
      * devices open we need to save the pid_t the PPData
      * and the interface number
      */
     struct Connection {
         pid_t pid;
         QString device;
         QString name;
     };
     class InterfaceKeeper {
     public:
         InterfaceKeeper();
         ~InterfaceKeeper();
 
         void addInterface( pid_t, const QString& pppDev, const QString& name );
         QMap<QString, Connection> interfaces()const; // will check if still available
     private:
         bool isAvailable( pid_t )const;
         QMap<QString, Connection> m_interfaces;
     };
 }
 
 
 /**
  * Constructor, find all of the possible interfaces
  * We also need to restore the state.. it could be that
  * an interface was up while closing the application
  * we need to be able to shut it down...
  */
 PPPModule::PPPModule() : Module()
 {
     InterfaceKeeper inFace;
     QMap<QString,Connection> running = inFace.interfaces();
     QStringList handledInterfaceNames;
 
     QMap<QString,QString> ifaces = PPPData::getConfiguredInterfaces();
     QMap<QString,QString>::Iterator it;
     InterfacePPP *iface;
     qDebug("getting interfaces");
     for( it = ifaces.begin(); it != ifaces.end(); ++it ){
         qDebug("ifaces %s %s", it.key().latin1(), it.data().latin1() );
         iface = new InterfacePPP( 0, it.key() );
         iface->setHardwareName( it.data() );
         list.append( (Interface*)iface );
 
         // check if (*it) is one of the running ifaces
         if ( running.contains( it.data() ) ) {
             qDebug("iface is running %s", it.key().latin1() );
             handledInterfaceNames << running[it.data()].device;
             iface->setStatus( true );
             iface->setPPPDpid( running[it.data()].pid );
             iface->modem()->setPPPDevice( running[it.data()].device );
             iface->refresh();
         }
     }
 
     setHandledInterfaceNames( handledInterfaceNames );
 }
 
 /**
  * Delete any interfaces that we own.
  */
 PPPModule::~PPPModule(){
     qDebug("PPPModule::~PPPModule() " );
     QMap<QString,QString> ifaces;
     InterfaceKeeper keeper;
     Interface *i;
     for ( i=list.first(); i != 0; i=list.next() ){
         /* if online save the state */
         if ( i->getStatus() ) {
             qDebug("Iface %s is still up", i->getHardwareName().latin1() );
             InterfacePPP* ppp = static_cast<InterfacePPP*>(i);
             keeper.addInterface( ppp->pppPID(), ppp->pppDev(), ppp->getHardwareName() );
         }
         ifaces.insert( i->getInterfaceName(), i->getHardwareName() );
         delete i;
     }
     PPPData::setConfiguredInterfaces( ifaces );
 }
 
 /**
  * Change the current profile
  */
 void PPPModule::setProfile(const QString &newProfile){
   profile = newProfile;
 }
 
 /**
  * get the icon name for this device.
  * @param Interface* can be used in determining the icon.
  * @return QString the icon name (minus .png, .gif etc)
  */
 QString PPPModule::getPixmapName(Interface* ){
   return "ppp";
 }
 
 /**
  * Check to see if the interface i is owned by this module.
  * @param Interface* interface to check against
  * @return bool true if i is owned by this module, false otherwise.
  */
 bool PPPModule::isOwner(Interface *i){
     return list.find( i ) != -1;
 }
 
 /**
  * Create, and return the WLANConfigure Module
  * @return QWidget* pointer to this modules configure.
  */
 QWidget *PPPModule::configure(Interface *i){
     qDebug("return ModemWidget");
     PPPConfigWidget *pppconfig = new PPPConfigWidget( (InterfacePPP*)i,
                                                       0, "PPPConfig", false,
-                                                      Qt::WDestructiveClose | Qt::WStyle_ContextHelp);
+                                                      (Qt::WDestructiveClose | Qt::WStyle_ContextHelp));
     return pppconfig;
 }
 
 /**
  * Create, and return the Information Module
  * @return QWidget* pointer to this modules info.
  */
 QWidget *PPPModule::information(Interface *i){
   // We don't have any advanced pppd information widget yet :-D
   // TODO ^
 
    return new InterfaceInformationPPP( 0, "InterfaceInformationPPP", i );
 }
 
 /**
  * Get all active (up or down) interfaces
  * @return QList<Interface> A list of interfaces that exsist that havn't
  * been called by isOwner()
  */
 QList<Interface> PPPModule::getInterfaces(){
   // List all of the files in the peer directory
     qDebug("PPPModule::getInterfaces");
   return list;
 }
 
 /**
  * Attempt to add a new interface as defined by name
  * @param name the name of the type of interface that should be created given
  *  by possibleNewInterfaces();
  * @return Interface* NULL if it was unable to be created.
  */
 Interface *PPPModule::addNewInterface(const QString &newInterface){
 
   InterfacePPP *ifaceppp;
   Interface *iface;
   ifaceppp = new InterfacePPP();
   PPPConfigWidget imp(ifaceppp, 0, "PPPConfigImp", true);
   imp.showMaximized();
   if(imp.exec() == QDialog::Accepted ){
       iface = (InterfacePPP*) ifaceppp;
       iface->setModuleOwner( this );
       list.append( iface );
       return iface;
   }else {
       delete ifaceppp;
       iface = NULL;
   }
   return iface;
 }
 
 /**
  * Attempts to remove the interface, doesn't delete i
  * @return bool true if successful, false otherwise.
  */
 bool PPPModule::remove(Interface *i){
     return list.remove(i);
 }
 
 void PPPModule::possibleNewInterfaces(QMap<QString, QString> &newIfaces)
 {
     newIfaces.insert(QObject::tr("PPP") ,
                      QObject::tr("generic ppp device"));
 }
 
 
 
 namespace {
     InterfaceKeeper::InterfaceKeeper( ) {
     }
     InterfaceKeeper::~InterfaceKeeper() {
         Config cfg("ppp_plugin_keeper");
         QStringList lst = cfg.groupList();
         for (QStringList::Iterator it = lst.begin(); it != lst.end(); ++it ) {
             Connection con;
             cfg.setGroup( (*it) );
             cfg.clearGroup();
         }
 
         for (QMap<QString, Connection>::Iterator it = m_interfaces.begin(); it != m_interfaces.end(); ++it ) {
             Connection con = it.data();
             cfg.setGroup( con.name );
             cfg.writeEntry( "pid", con.pid );
             cfg.writeEntry( "device", con.device );
         }
     }
     void InterfaceKeeper::addInterface(pid_t pid, const QString& dev, const QString& name ) {
         Connection con;
         con.pid = pid;
         con.device = dev;
         con.name = name;
         m_interfaces.insert( name, con );
     }
     QMap<QString, Connection> InterfaceKeeper::interfaces()const {
         Config cfg("ppp_plugin_keeper");
         QMap<QString, Connection> ifaces;
         QStringList lst = cfg.groupList();
         for (QStringList::Iterator it = lst.begin(); it != lst.end(); ++it ) {
             Connection con;
             cfg.setGroup( (*it) );
             con.name = (*it);
             con.pid = cfg.readNumEntry("pid");
             con.device = cfg.readEntry("device");
             qDebug(" %s %s %d", con.name.latin1(), con.device.latin1(),  con.pid );
 
             if ( con.pid != -1 && isAvailable( con.pid ) )
                 ifaces.insert( con.name, con );
         }
         return ifaces;
     }
     bool InterfaceKeeper::isAvailable( pid_t p)const {
         if (::kill(p, 0 ) == 0 || errno != ESRCH ) {
             qDebug("isAvailable %d",  p);
             return true;
         }
 
         qDebug("notAvailable %d", p);
         return false;
     }
 
 }