← Back to branch summary

~stub/ubuntu/trusty/avro-c/trunk

« back to all changes in this revision

Viewing changes to src/avro/consumer.h

  • Committer: Stuart Bishop
  • Date: 2015-05-14 11:53:53 UTC
  • Revision ID: stuart@stuartbishop.net-20150514115353-0cvnrcyohcq5l7yj
Tags: upstream-1.7.7
Import upstream version 1.7.7

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/avro/consumer.h
 
1
/*
 
2
 * Licensed to the Apache Software Foundation (ASF) under one or more
 
3
 * contributor license agreements.  See the NOTICE file distributed with
 
4
 * this work for additional information regarding copyright ownership.
 
5
 * The ASF licenses this file to you under the Apache License, Version 2.0
 
6
 * (the "License"); you may not use this file except in compliance with
 
7
 * the License.  You may obtain a copy of the License at
 
8
 *
 
9
 * http://www.apache.org/licenses/LICENSE-2.0
 
10
 *
 
11
 * Unless required by applicable law or agreed to in writing, software
 
12
 * distributed under the License is distributed on an "AS IS" BASIS,
 
13
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 
14
 * implied.  See the License for the specific language governing
 
15
 * permissions and limitations under the License.
 
16
 */
 
17
 
 
18
#ifndef AVRO_CONSUMER_H
 
19
#define AVRO_CONSUMER_H
 
20
#ifdef __cplusplus
 
21
extern "C" {
 
22
#define CLOSE_EXTERN }
 
23
#else
 
24
#define CLOSE_EXTERN
 
25
#endif
 
26
 
 
27
#include <avro/platform.h>
 
28
#include <stdlib.h>
 
29
 
 
30
#include <avro/io.h>
 
31
#include <avro/schema.h>
 
32
 
 
33
 
 
34
/*---------------------------------------------------------------------
 
35
 * Consumers
 
36
 */
 
37
 
 
38
/**
 
39
 * A <i>consumer</i> is an object that knows how to process Avro data.
 
40
 * There are consumer methods for each type of Avro data.  The
 
41
 * <code>avro_consumer_t</code> struct is an abstract superclass, which
 
42
 * you don't instantiate directly.  Later in this file, we define
 
43
 * several consumer classes that know how to process Avro data in
 
44
 * specific ways.
 
45
 *
 
46
 * For compound Avro values (records, arrays, maps, and unions), the
 
47
 * consumer callbacks provide a nested consumer that should be used to
 
48
 * process subvalues.  Each consumer instance, including these
 
49
 * "subconsumers", contains a reference to the schema of the data that
 
50
 * it expects to process.  This means that the functions that produce
 
51
 * Avro data (such as avro_consume_binary) don't need to maintain their
 
52
 * own references to any schemas, since they'll be encapsulated in the
 
53
 * consumer that they pass their data off to.
 
54
 */
 
55
 
 
56
typedef struct avro_consumer_t avro_consumer_t;
 
57
 
 
58
struct avro_consumer_t {
 
59
        /**
 
60
         * The schema of the data that this consumer expects to process.
 
61
         */
 
62
 
 
63
        avro_schema_t  schema;
 
64
 
 
65
        /**
 
66
         * Called when this consumer is freed.  This function should
 
67
         * free any additional resources acquired by a consumer
 
68
         * subclass.
 
69
         */
 
70
 
 
71
        void (*free)(avro_consumer_t *consumer);
 
72
 
 
73
        /* PRIMITIVE VALUES */
 
74
 
 
75
        /**
 
76
         * Called when a boolean value is encountered.
 
77
         */
 
78
 
 
79
        int (*boolean_value)(avro_consumer_t *consumer,
 
80
                             int value,
 
81
                             void *user_data);
 
82
 
 
83
        /**
 
84
         * Called when a bytes value is encountered. The @ref value
 
85
         * pointer is only guaranteed to be valid for the duration of
 
86
         * the callback function.  If you need to save the data for
 
87
         * processing later, you must copy it into another buffer.
 
88
         */
 
89
 
 
90
        int (*bytes_value)(avro_consumer_t *consumer,
 
91
                           const void *value, size_t value_len,
 
92
                           void *user_data);
 
93
 
 
94
        /**
 
95
         * Called when a double value is encountered.
 
96
         */
 
97
 
 
98
        int (*double_value)(avro_consumer_t *consumer,
 
99
                            double value,
 
100
                            void *user_data);
 
101
 
 
102
        /**
 
103
         * Called when a float value is encountered.
 
104
         */
 
105
 
 
106
        int (*float_value)(avro_consumer_t *consumer,
 
107
                           float value,
 
108
                           void *user_data);
 
109
 
 
110
        /**
 
111
         * Called when an int value is encountered.
 
112
         */
 
113
 
 
114
        int (*int_value)(avro_consumer_t *consumer,
 
115
                         int32_t value,
 
116
                         void *user_data);
 
117
 
 
118
        /**
 
119
         * Called when a long value is encountered.
 
120
         */
 
121
 
 
122
        int (*long_value)(avro_consumer_t *consumer,
 
123
                          int64_t value,
 
124
                          void *user_data);
 
125
 
 
126
        /**
 
127
         * Called when a null value is encountered.
 
128
         */
 
129
 
 
130
        int (*null_value)(avro_consumer_t *consumer, void *user_data);
 
131
 
 
132
        /**
 
133
         * Called when a string value is encountered.  The @ref value
 
134
         * pointer will point at UTF-8 encoded data.  (If the data
 
135
         * you're representing isn't a UTF-8 Unicode string, you
 
136
         * should use the bytes type.)  The @ref value_len parameter
 
137
         * gives the length of the data in bytes, not in Unicode
 
138
         * characters.  The @ref value pointer is only guaranteed to
 
139
         * be valid for the duration of the callback function.  If you
 
140
         * need to save the data for processing later, you must copy
 
141
         * it into another buffer.
 
142
         */
 
143
 
 
144
        int (*string_value)(avro_consumer_t *consumer,
 
145
                            const void *value, size_t value_len,
 
146
                            void *user_data);
 
147
 
 
148
        /* COMPOUND VALUES */
 
149
 
 
150
        /**
 
151
         * Called when the beginning of an array block is encountered.
 
152
         * The @ref block_count parameter will contain the number of
 
153
         * elements in this block.
 
154
         */
 
155
 
 
156
        int (*array_start_block)(avro_consumer_t *consumer,
 
157
                                 int is_first_block,
 
158
                                 unsigned int block_count,
 
159
                                 void *user_data);
 
160
 
 
161
        /**
 
162
         * Called before each individual element of an array is
 
163
         * processed.  The index of the current element is passed into
 
164
         * the callback.  The callback should fill in @ref
 
165
         * element_consumer and @ref element_user_data with the consumer
 
166
         * and <code>user_data</code> pointer to use to process the
 
167
         * element.
 
168
         */
 
169
 
 
170
        int (*array_element)(avro_consumer_t *consumer,
 
171
                             unsigned int index,
 
172
                             avro_consumer_t **element_consumer,
 
173
                             void **element_user_data,
 
174
                             void *user_data);
 
175
 
 
176
        /**
 
177
         * Called when an enum value is encountered.
 
178
         */
 
179
 
 
180
        int (*enum_value)(avro_consumer_t *consumer, int value,
 
181
                          void *user_data);
 
182
 
 
183
        /**
 
184
         * Called when a fixed value is encountered.  The @ref value
 
185
         * pointer is only guaranteed to be valid for the duration of
 
186
         * the callback function.  If you need to save the data for
 
187
         * processing later, you must copy it into another buffer.
 
188
         */
 
189
 
 
190
        int (*fixed_value)(avro_consumer_t *consumer,
 
191
                           const void *value, size_t value_len,
 
192
                           void *user_data);
 
193
 
 
194
        /**
 
195
         * Called when the beginning of a map block is encountered.
 
196
         * The @ref block_count parameter will contain the number of
 
197
         * elements in this block.
 
198
         */
 
199
 
 
200
        int (*map_start_block)(avro_consumer_t *consumer,
 
201
                               int is_first_block,
 
202
                               unsigned int block_count,
 
203
                               void *user_data);
 
204
 
 
205
        /**
 
206
         * Called before each individual element of a map is
 
207
         * processed.  The index and key of the current element is
 
208
         * passed into the callback.  The key is only guaranteed to be
 
209
         * valid for the duration of the map_element_start callback,
 
210
         * and the map's subschema callback.  If you need to save it for
 
211
         * later use, you must copy the key into another memory
 
212
         * location.  The callback should fill in @ref value_consumer
 
213
         * and @ref value_user_data with the consumer and
 
214
         * <code>user_data</code> pointer to use to process the value.
 
215
         */
 
216
 
 
217
        int (*map_element)(avro_consumer_t *consumer,
 
218
                           unsigned int index,
 
219
                           const char *key,
 
220
                           avro_consumer_t **value_consumer,
 
221
                           void **value_user_data,
 
222
                           void *user_data);
 
223
 
 
224
        /**
 
225
         * Called when the beginning of a record is encountered.
 
226
         */
 
227
 
 
228
        int (*record_start)(avro_consumer_t *consumer,
 
229
                            void *user_data);
 
230
 
 
231
        /**
 
232
         * Called before each individual field of a record is
 
233
         * processed.  The index and name of the current field is
 
234
         * passed into the callback.  The name is only guaranteed to
 
235
         * be valid for the duration of the record_field_start
 
236
         * callback, and the field's subschema callback.  If you need to
 
237
         * save it for later use, you must copy the key into another
 
238
         * memory location.  The callback should fill in @ref
 
239
         * field_consumer and @ref field_user_data with the consumer
 
240
         * <code>user_data</code> pointer to use to process the field.
 
241
         */
 
242
 
 
243
        int (*record_field)(avro_consumer_t *consumer,
 
244
                            unsigned int index,
 
245
                            avro_consumer_t **field_consumer,
 
246
                            void **field_user_data,
 
247
                            void *user_data);
 
248
 
 
249
        /**
 
250
         * Called when a union value is encountered.  The callback
 
251
         * should fill in @ref branch_consumer and @ref branch_user_data
 
252
         * with the consumer <code>user_data</code> pointer to use to
 
253
         * process the branch.
 
254
         */
 
255
 
 
256
        int (*union_branch)(avro_consumer_t *consumer,
 
257
                            unsigned int discriminant,
 
258
                            avro_consumer_t **branch_consumer,
 
259
                            void **branch_user_data,
 
260
                            void *user_data);
 
261
};
 
262
 
 
263
 
 
264
/**
 
265
 * Calls the given callback in consumer, if it's present.  If the
 
266
 * callback is NULL, it just returns a success code.
 
267
 */
 
268
 
 
269
#define avro_consumer_call(consumer, callback, ...)     \
 
270
        (((consumer)->callback == NULL)? 0:             \
 
271
         (consumer)->callback((consumer), __VA_ARGS__))
 
272
 
 
273
 
 
274
/**
 
275
 * Frees an @ref avro_consumer_t instance.  (This function works on
 
276
 * consumer subclasses, too.)
 
277
 */
 
278
 
 
279
void avro_consumer_free(avro_consumer_t *consumer);
 
280
 
 
281
 
 
282
/*---------------------------------------------------------------------
 
283
 * Resolvers
 
284
 */
 
285
 
 
286
/**
 
287
 * A <i>resolver</i> is a special kind of consumer that knows how to
 
288
 * implement Avro's schema resolution rules to translate between a
 
289
 * writer schema and a reader schema.  The consumer callbacks line up
 
290
 * with the writer schema; as each element of the datum is produced, the
 
291
 * resolver fills in the contents of an @ref avro_datum_t instance.
 
292
 * (The datum is provided as the user_data when you use the consumer.)
 
293
 */
 
294
 
 
295
avro_consumer_t *
 
296
avro_resolver_new(avro_schema_t writer_schema,
 
297
                  avro_schema_t reader_schema);
 
298
 
 
299
 
 
300
/*---------------------------------------------------------------------
 
301
 * Binary encoding
 
302
 */
 
303
 
 
304
/**
 
305
 * Reads an Avro datum from the given @ref avro_reader_t.  As the
 
306
 * datum is read, each portion of it is passed off to the appropriate
 
307
 * callback in @ref consumer.
 
308
 */
 
309
 
 
310
int
 
311
avro_consume_binary(avro_reader_t reader,
 
312
                    avro_consumer_t *consumer,
 
313
                    void *ud);
 
314
 
 
315
 
 
316
CLOSE_EXTERN
 
317
#endif