LCOV - code coverage report
Current view: top level - lang/cpp/src - eventloopinteractor.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 0 2 0.0 %
Date: 2016-11-29 15:07:43 Functions: 0 1 0.0 %

          Line data    Source code
       1             : /*
       2             :   eventloopinteractor.h
       3             :   Copyright (C) 2003,2004 Klarälvdalens Datakonsult AB
       4             : 
       5             :   This file is part of GPGME++.
       6             : 
       7             :   GPGME++ is free software; you can redistribute it and/or
       8             :   modify it under the terms of the GNU Library General Public
       9             :   License as published by the Free Software Foundation; either
      10             :   version 2 of the License, or (at your option) any later version.
      11             : 
      12             :   GPGME++ is distributed in the hope that it will be useful,
      13             :   but WITHOUT ANY WARRANTY; without even the implied warranty of
      14             :   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      15             :   GNU Library General Public License for more details.
      16             : 
      17             :   You should have received a copy of the GNU Library General Public License
      18             :   along with GPGME++; see the file COPYING.LIB.  If not, write to the
      19             :   Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
      20             :   Boston, MA 02110-1301, USA.
      21             : */
      22             : 
      23             : // -*- c++ -*-
      24             : #ifndef __GPGMEPP_EVENTLOOPINTERACTOR_H__
      25             : #define __GPGMEPP_EVENTLOOPINTERACTOR_H__
      26             : 
      27             : #include "gpgmepp_export.h"
      28             : 
      29             : namespace GpgME
      30             : {
      31             : 
      32             : class Context;
      33             : class Error;
      34             : class TrustItem;
      35             : class Key;
      36             : 
      37             : /*! \file eventloopinteractor.h
      38             :     \brief Abstract base class for gpgme's external event loop support
      39             : 
      40             :     This class does most of the work involved with hooking GpgME++
      41             :     up with external event loops, such as the GTK or Qt ones.
      42             : 
      43             :     It actually provides two interfaces: An interface to the gpgme
      44             :     IO Callback handling and one for gpgme events. The IO Callback
      45             :     interface consists of the three methods \c actOn(), \c
      46             :     registerWatcher() and \c unregisterWatcher(). The event
      47             :     interface consists of the three methods \c nextTrustItemEvent(),
      48             :     \c nextKeyEvent() and \c operationDoneEvent().
      49             : 
      50             :     \sect General Usage
      51             : 
      52             :     \c EventLoopInteractor is designed to be used as a
      53             :     singleton. However, in order to make any use of it, you have to
      54             :     subclass it and reimplement it's pure virtual methods (see
      55             :     below). We suggest you keep the constructor protected and
      56             :     provide a static \c instance() method that returns the single
      57             :     instance. Alternatively, you can create an instance on the
      58             :     stack, e.g. in \c main().
      59             : 
      60             :     If you want \c EventLoopInteractor to manage a particular \c
      61             :     Context, just call \c manage() on the \c Context. OTOH, if you
      62             :     want to disable IO callbacks for a \c Context, use \c unmanage().
      63             : 
      64             :     \sect IO Callback Interface
      65             : 
      66             :     One part of this interface is represented by \c
      67             :     registerWatcher() and \c unregisterWatcher(), both of which are
      68             :     pure virtual. \c registerWatcher() should do anything necessary
      69             :     to hook up watching of file descriptor \c fd for reading (\c dir
      70             :     = \c Read) or writing (\c dir = Write) to the event loop you use
      71             :     and return a tag identifying that particular watching process
      72             :     uniquely. This could be the index into an array of objects you
      73             :     use for that purpose or the address of such an object. E.g. in
      74             :     Qt, you'd essentially just create a new \c QSocketNotifier:
      75             : 
      76             :     \verbatim
      77             :     void * registerWatcher( int fd, Direction dir ) {
      78             :       return new QSocketNotifier( fd, dir == Read ? QSocketNotifier::Read : QSocketNotifier::Write );
      79             :       // misses connecting to the activated() signal...
      80             :     }
      81             :     \endverbatim
      82             : 
      83             :     which uses the address of the created object as unique tag. The
      84             :     tag returned by \c registerWatcher is stored by \c
      85             :     EventLoopInteractor and passed as argument to \c
      86             :     unregisterWatcher(). So, in the picture above, you'd implement \c
      87             :     unregisterWatcher() like this:
      88             : 
      89             :     \verbatim
      90             :     void unregisterWatcher( void * tag ) {
      91             :       delete static_cast<QSocketNotifier*>( tag );
      92             :     }
      93             :     \endverbatim
      94             : 
      95             :     The other part of the IO callback interface is \c actOn(), which
      96             :     you should call if you receive notification from your event loop
      97             :     about activity on file descriptor \c fd in direction \c dir. In
      98             :     the picture above, you'd call this from the slot connected to
      99             :     the socket notifier's \c activated() signal.
     100             : 
     101             :     \note \c registerWatcher() as well as \c unregisterWatcher() may
     102             :     be called from within \c actOn(), so be careful with
     103             :     e.g. locking in threaded environments and keep in mind that the
     104             :     object you used to find the \c fd and \c dir fo the \c actOn()
     105             :     call might be deleted when \c actOn() returns!
     106             : 
     107             :     \sect Event Handler Interface
     108             : 
     109             : */
     110             : class GPGMEPP_EXPORT EventLoopInteractor
     111             : {
     112             : protected:
     113             :     EventLoopInteractor();
     114             : public:
     115             :     virtual ~EventLoopInteractor();
     116             : 
     117           0 :     static EventLoopInteractor *instance()
     118             :     {
     119           0 :         return mSelf;
     120             :     }
     121             : 
     122             :     void manage(Context *context);
     123             :     void unmanage(Context *context);
     124             : 
     125             :     enum Direction { Read, Write };
     126             : protected:
     127             :     //
     128             :     // IO Notification Interface
     129             :     //
     130             : 
     131             :     /** Call this if your event loop detected activity on file
     132             :         descriptor fd, with direction dir */
     133             :     void actOn(int fd, Direction dir);
     134             : 
     135             :     virtual void *registerWatcher(int fd, Direction dir, bool &ok) = 0;
     136             :     virtual void unregisterWatcher(void *tag) = 0;
     137             : 
     138             :     //
     139             :     // Event Handler Interface
     140             :     //
     141             : 
     142             :     virtual void operationStartEvent(Context *context) = 0;
     143             :     virtual void nextTrustItemEvent(Context *context, const TrustItem &item) = 0;
     144             :     virtual void nextKeyEvent(Context *context, const Key &key) = 0;
     145             :     virtual void operationDoneEvent(Context *context, const Error &e) = 0;
     146             : 
     147             : private:
     148             :     class Private;
     149             :     friend class Private;
     150             :     Private *const d;
     151             :     static EventLoopInteractor *mSelf;
     152             : };
     153             : 
     154             : }
     155             : 
     156             : #endif // __GPGMEPP_EVENTLOOPINTERACTOR_H__

Generated by: LCOV version 1.11