3 // Copyright (C) 2006 Stefan Bund <g0dil@berlios.de>
5 // This program is free software; you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation; either version 2 of the License, or
8 // (at your option) any later version.
10 // This program is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with this program; if not, write to the
17 // Free Software Foundation, Inc.,
18 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
22 \brief ReadHelper public header */
24 #ifndef HH_ReadHelper_
25 #define HH_ReadHelper_ 1
29 #include <boost/function.hpp>
30 #include <boost/intrusive_ptr.hpp>
31 #include <boost/scoped_ptr.hpp>
33 #include "Utils/intrusive_refcount.hh"
34 #include "Scheduler.hh"
36 //#include "ReadHelper.mpp"
37 ///////////////////////////////hh.p////////////////////////////////////////
42 /** \brief Asyncronous reading helper
44 This class provides a simple asynchronous reading facility. This helper will register with
45 the Scheduler and read incoming data. It will collect the data until a specific number of
46 bytes has been read or some Predicate evaluated on the data read thus far signals end of
49 The ReadHelper accepts the same flexible file handle interfaces as the Scheduler.
51 The callback must take a ReadHelper::ptr argument. Using this ReadHelper instance, the
52 callback can access the data read or retrieve state information.
54 The ReadHelper separates the data into two parts: data() will return the matched data,
55 tail() will return any surplus data already read. If you don't specify a predicate, tail()
56 will always be empty (there may however some data be left in the socket input buffer after
57 the ReadHelper returns).
59 The predicate is any class instance with an <tt>operator(std::string const &)</tt>. This
60 operator is called, whenever some data has been read. If the data is not yet complete, the
61 predicate must return \c std::string::npos. If the ReadHelper should stop reading more
62 data, the predicate must return the number of bytes which are to be considered 'matched'.
64 \todo Move all not Handle dependent members to a ReadHandleBase class
65 \todo Add an optional <tt>std::string const & tail</tt> argument to the constructors which
66 takes the tail() of a previous ReadHelper instance.
68 template <class Handle>
70 : public senf::intrusive_refcount
73 ///////////////////////////////////////////////////////////////////////////
76 typedef boost::intrusive_ptr<ReadHelper> ptr; ///< Smart pointer type for this class
77 typedef boost::function<void (ptr)> Callback; ///< Callback type
79 ///////////////////////////////////////////////////////////////////////////
80 ///\name Structors and default members
83 static ptr dispatch(Handle handle, std::string::size_type maxSize,
84 Callback callback); ///< Register new ReadHandler instance
85 /**< The registered Callback will be called after \a maxSize
86 bytes have been read or EOF or some error is
88 \post The returned ReadHelper instance is registered
89 with the Scheduler to handle read events.
90 \param[in] handle file descriptor or handle providing
91 the Handle interface defined above.
92 \param[in] maxSize maximum number of bytes to read
93 \param[in] callback callback
94 \returns Smart pointer to new ReadHelper instance */
96 template <class Predicate>
97 static ptr dispatch(Handle handle, std::string::size_type maxSize, Predicate const & predicate,
98 Callback callback); ///< Register new ReadHelper instance
99 /**< The registered Callback will be called after the \a
100 predicate returns a Value other than \c
101 std::string::npos, \a maxSize bytes have been read, or
102 EOF or some error condition is encountered.
103 \post The returned ReadHelper instance is registered
104 with the Scheduler to handle read events
105 . \param[in] handle file descriptor or handle providing
106 the Handle interface defined above.
107 \param[in] maxSize maximum number of bytes to read
108 \param[in] predicate predicate to check
109 \param[in] callback callback
110 \returns smart pointer to new ReadHelper instance */
113 ///////////////////////////////////////////////////////////////////////////
115 Handle handle() const; ///< Access the handle object
116 unsigned maxSize() const; ///< Return maximum number of bytes to be read
118 std::string const & data() const; ///< return data read
119 std::string const & tail() const; ///< return data read but not matched by the predicate
121 bool complete() const; ///< Check whether the read has completed successfully
122 bool error() const; ///< Check for error condition
123 void throw_error() const; ///< If an error occurred, throw it
125 void revoke(); ///< Remove the ReadHelper from the scheduler
130 struct InternalPredicate;
132 ReadHelper(Handle handle, unsigned maxSize, InternalPredicate * predicate, Callback cb);
134 static void dispatchProcess(ptr helper, Handle handle, senf::Scheduler::EventId event);
135 void process(Handle handle, senf::Scheduler::EventId event);
139 std::string::size_type maxSize_;
140 boost::scoped_ptr<InternalPredicate> predicate_;
149 /** \brief ReadHelper predicate matching an arbitrary string
151 This predicate will terminate the read when the data read matches a given fixed string. All
152 data up to and including the string matched is considered to be part of the data() portion,
153 everything after the matched string is placed into the tail().
159 ReadUntil(std::string const & target);
160 std::string::size_type operator()(std::string const & data);
166 ///////////////////////////////hh.e////////////////////////////////////////
167 #include "ReadHelper.cci"
168 #include "ReadHelper.ct"
169 #include "ReadHelper.cti"
170 //#include "ReadHelper.mpp"
177 // c-file-style: "senf"
178 // indent-tabs-mode: nil
179 // ispell-local-dictionary: "american"