workspace/libs/solid/control/networking.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2006-2007 Will Stephenson <wstephenson@kde.org>
   3     Copyright (C) 2006-2007 Kevin Ottens <ervin@kde.org>
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License version 2 as published by the Free Software Foundation.
   8
   9     This library is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12     Library General Public License for more details.
  13
  14     You should have received a copy of the GNU Library General Public License
  15     along with this library; see the file COPYING.LIB.  If not, write to
  16     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17     Boston, MA 02110-1301, USA.
  18
  19 */
  20
  21 #ifndef SOLID_CONTROL_NETWORKING_H
  22 #define SOLID_CONTROL_NETWORKING_H
  23
  24 #include <QtCore/QObject>
  25
  26 #include "solid_control_export.h"
  27 class QAbstractSocket;
  28
  29 namespace Solid
  30 {
  31 namespace Control
  32 {
  33     /**
  34      * This class allow to query the underlying system to discover the available
  35      * network interfaces and reachable network.It has also the
  36      * responsibility to notify when a network interface or a network appear or disappear.
  37      *
  38      * It's the unique entry point for network management. Applications should use
  39      * it to find network interfaces, or to be notified about network related changes.
  40      *
  41      * Note that it's implemented as a singleton and encapsulates the backend logic.
  42      */
  43     namespace Networking
  44     {
  45         /**
  46          * Describe the result of a connection request
  47          * - Accepted : the request was accepted and is being acted upon
  48          * - AlreadyConnected : the system was already connected
  49          * - Denied : the request was denied
  50          */
  51         enum Result { Accepted, AlreadyConnected, Denied };
  52
  53         /**
  54          * Magic network management for application's sockets.
  55          * When the socket begins to connect it will automatically bring up
  56          * networking, if not already available.
  57          * When the network disconnects, optionally disconnects the socket early
  58          * so that an application may continue.
  59          * @param socket the socket to manage.
  60          * @param autoDisconnectTimeout wait this many milliseconds after receiving a disconnected
  61          * event from the networking subsystem before disconnecting the socket. A value of 0 means
  62          * never automatically disconnect.
  63          * @return whether the management request succeeded.
  64          */
  65         SOLIDCONTROL_EXPORT Result beginManagingSocket( QAbstractSocket * socket, uint autoDisconnectTimeout = 0 );
  66
  67         /**
  68          * Remove the socket from the list of sockets to manage.  The socket's state is unaltered.
  69          * @param socket the socket to stop managing.
  70          */
  71         SOLIDCONTROL_EXPORT void stopManagingSocket( QAbstractSocket * socket );
  72
  73         /**
  74          * Requests that the networking subsystem makes a connection.  If an on-demand connection
  75          * is started as a result of this request, the connection is refcounted and KDE's use of
  76          * the connection is dropped when the last application uses it calls @ref
  77          * releaseConnection().
  78          * Optionally, pass in a QObject and slot to call on it, to receive notification when the
  79          * connection is available or not.  The slot may take a Solid::Networking::Status to
  80          * indicate success or failure.
  81          *
  82          * @param receiver the QObject to call a slot on.
  83          * @param member the slot to call.
  84          * @return a Result indication whether the request was accepted.
  85          */
  86         SOLIDCONTROL_EXPORT Result requestConnection( QObject * receiver = 0, const char * member = 0 );
  87
  88         /**
  89          * Activates or deactivates networking (as a whole).
  90          *
  91          * @param enabled true to activate networking, false otherwise
  92          */
  93         SOLIDCONTROL_EXPORT void releaseConnection();
  94     } // Networking
  95
  96 } // namespace Control
  97 } // Solid
  98
  99 #endif