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