1/* This file is part of Strigi Desktop Search
2 *
3 * Copyright (C) 2007 Jos van den Oever <jos@vandenoever.info>
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 as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library 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 GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20#ifndef STRIGI_DATAEVENTINPUTSTREAM_H
21#define STRIGI_DATAEVENTINPUTSTREAM_H
22#include <strigi/strigiconfig.h>
23#include <strigi/streambase.h>
24
25namespace Strigi {
26
27/**
28 * @brief Handler interface for handling data events.
29 *
30 * By passing an implementation of this class to a
31 * DataEventInputStream, it will receive the data
32 * as it is read from the DataEventInputStream.
33 *
34 * See the DataEventInputStream documentation for
35 * more information.
36 */
37class STREAMS_EXPORT DataEventHandler {
38public:
39 /** Destructor */
40 virtual ~DataEventHandler() {}
41 /**
42 * @brief Handle a data event.
43 *
44 * Each piece of data from an InputStream attached to a
45 * DataEventInputStream will be passed to this function
46 * (in order) as it is read from the DataEventInputStream.
47 *
48 * When handleEnd is called, it is guaranteed that each
49 * element in the input stream has been passed in exactly
50 * one call to this function, and that the calls happened
51 * in the same order as the the data occurred in the
52 * InputStream.
53 *
54 * You should not call this function yourself. It forms
55 * part of an interface for the use of a DataEventInputStream.
56 *
57 * @param data pointer to the data from the inputstream
58 * @param size the size of the data pointed to by @p data
59 * @return @c true when the handler wants to receive more events
60 * false when the handler does not want any more events from this
61 * stream
62 */
63 virtual bool handleData(const char* data, uint32_t size) = 0;
64 /**
65 * @brief Handle the end of the stream.
66 *
67 * This function will be called exactly once, and notifies
68 * the DataEventHandler that all the data from the stream
69 * has been read and passed in exactly one call to handleData.
70 */
71 virtual void handleEnd() {}
72};
73
74/**
75 * @brief An InputStream that makes parallel handling of incoming data easier.
76 *
77 * When you read from this InputStream, it sends out data events to a registered
78 * handler. The data events cover all bytes in the inputstream and they are
79 * sent out in the same order as they occur in the stream. Each byte occurs in
80 * one event only. Rewinding this stream and rereading parts of it will not send
81 * a new event for the same data.
82 *
83 * Multiple DataEventInputStreams can be linked in series to send events to
84 * several handlers:
85 * @code
86 * DataEventHandler handler1, handler2, handler3;
87 * InputStream inputStream;
88 * DataEventInputStream handlerStream1(inputStream, handler1);
89 * DataEventInputStream handlerStream2(handlerStream1, handler1);
90 * DataEventInputStream handlerStream3(handlerStream2, handler1);
91 * int nRead = handlerStream3.read(start, min, max);
92 * @endcode
93 */
94class STREAMS_EXPORT DataEventInputStream : public InputStream {
95private:
96 int64_t totalread;
97 InputStream* input;
98 DataEventHandler& handler;
99 bool finished;
100
101 void finish();
102public:
103 /**
104 * @brief Creates a DataEventInputStream with a given InputStream
105 * as the data source.
106 *
107 * Each instance of a DataEventHandler should only be passed to
108 * one DataEventInputStream. Behaviour is undefined otherwise.
109 *
110 * @param input the InputStream to use as the data source
111 * @param handler the DataEventHandler that should be sent the
112 * data events
113 */
114 explicit DataEventInputStream(InputStream *input,
115 DataEventHandler& handler);
116 int32_t read(const char*& start, int32_t min, int32_t max);
117 int64_t skip(int64_t ntoskip);
118 int64_t reset(int64_t pos);
119};
120
121} // end namespace Strigi
122
123#endif
124