23 namespace asn1 { |
23 namespace asn1 { |
24 namespace lib { |
24 namespace lib { |
25 |
25 |
26 class AbstractParserImpl; |
26 class AbstractParserImpl; |
27 |
27 |
|
28 /** |
|
29 * Event-driven parser that consumes sequence of byte buffers (chunked stream) |
|
30 * and produces some output (implementation specific). |
|
31 * |
|
32 * The flow is controlled from outside: incomming data pieces are passed to the parser through the write() method as they come. |
|
33 * |
|
34 * From the child class perspective (implementation of particular parser) |
|
35 * data pieces are obtained through the read() method from the internal buffer maintained by AbstractParser. |
|
36 */ |
28 class AbstractParser { |
37 class AbstractParser { |
29 private: |
38 private: |
30 friend AbstractParserImpl; |
39 friend AbstractParserImpl; |
31 AbstractParserImpl* implementation; |
40 AbstractParserImpl* implementation; |
|
41 void rollback(); |
32 public: |
42 public: |
33 virtual ~AbstractParser(); |
43 virtual ~AbstractParser(); |
|
44 |
|
45 /** |
|
46 * Submit a part of incomming data to the parser. |
|
47 * When possible, such data are usually processed synchronously during this method call. |
|
48 * If not (incomplete TLV/AVP/PDU/token/etc.) this part is appended to the internal buffer maintained by AbstractParser |
|
49 * and processed in some next cycle or – in worst case – during the close() call. |
|
50 * |
|
51 * @param buffer readable memory |
|
52 * @param length size of the buffer |
|
53 */ |
34 void write(const char* buffer, const size_t length); |
54 void write(const char* buffer, const size_t length); |
35 void rollback(); |
55 |
|
56 /** |
|
57 * Finalize the parsing process. |
|
58 * After calling this method, all data from AbstractParser buffers should be consumed, parsed and results published. |
|
59 * No write() call is expected after close() and would fail. |
|
60 * However the parser object remains valid and may be used to get some auxiliary information (if supperted by given implementation). |
|
61 */ |
|
62 void close(); |
36 protected: |
63 protected: |
37 AbstractParser(); |
64 AbstractParser(); |
38 |
65 |
39 /** |
66 /** |
40 * Is thrown from read() and peak() methods if there are not enough data. |
67 * Is thrown from read() and peak() methods if there are not enough data. |
64 * Note: There is no accessible rollback() method – throw ExplicitRollbackException instead. |
91 * Note: There is no accessible rollback() method – throw ExplicitRollbackException instead. |
65 */ |
92 */ |
66 void commit(); |
93 void commit(); |
67 |
94 |
68 /** |
95 /** |
|
96 * Fill the buffer with incomming data of given length (exactly). |
69 * |
97 * |
70 * @param buffer |
98 * If there are not enough data available, ReadBufferUnderflowException is thrown. |
71 * @param length |
99 * This exception should not be caught in the child class – it should propagate back to the AbstractParser |
|
100 * where it causes rollback(). In such case, the same data will be available during next update() cycle. |
|
101 * |
|
102 * @param buffer writable memory |
|
103 * @param length size of the buffer |
72 */ |
104 */ |
73 void read(char* buffer, const size_t length); |
105 void read(char* buffer, const size_t length); |
74 |
106 |
75 /** |
107 /** |
|
108 * Like read(), but does not update the marks (buffer positions), so it can be called again and again with same result. |
76 * |
109 * |
77 * @param buffer |
110 * @param buffer writable memory |
78 * @param length |
111 * @param length size of the buffer |
79 */ |
112 */ |
80 void peek(char* buffer, const size_t length); |
113 void peek(char* buffer, const size_t length); |
81 |
114 |
82 /** |
115 /** |
83 * |
116 * Reads input from buffers using read(), parses data and usually emits the result (e.g. to a handler/listener). |
|
117 * Is specific for particular format/parser. |
|
118 * |
|
119 * This method is called at least once at the end of the stream (with whole stream content in read buffers). |
|
120 * Usually it is called more often, by default: after each write (with just already received data part in read buffers). |
84 */ |
121 */ |
85 virtual void update() = 0; |
122 virtual void update() = 0; |
86 }; |
123 }; |
87 |
124 |
88 } |
125 } |