← Back to branch summary

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

« back to all changes in this revision

Viewing changes to src/avro/resolver.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/resolver.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_RESOLVER_H
 
19
#define AVRO_RESOLVER_H
 
20
#ifdef __cplusplus
 
21
extern "C" {
 
22
#define CLOSE_EXTERN }
 
23
#else
 
24
#define CLOSE_EXTERN
 
25
#endif
 
26
 
 
27
#include <avro/schema.h>
 
28
#include <avro/value.h>
 
29
 
 
30
/*
 
31
 * A <i>resolved value</i> is a special kind of value that knows how to
 
32
 * implement Avro's schema resolution rules to translate between a
 
33
 * writer schema and a reader schema.  A resolved value doesn't store or
 
34
 * process data itself; instead, it wraps an existing value instance.
 
35
 *
 
36
 * There are two resolved value classes.  In the first (@ref
 
37
 * avro_resolved_writer_t), the resolved value is an instance of the
 
38
 * writer schema, and wraps an instance of the reader schema.  This is
 
39
 * used, for instance, when reading from an Avro data file; you want the
 
40
 * end result to be a reader schema value, and the resolved value allows
 
41
 * the file reader to ignore the schema resolution and simply fill in
 
42
 * the values of the writer schema.  You can only set the values of a
 
43
 * resolved writer; you must use the original wrapped value to read.
 
44
 *
 
45
 * With other class (@ref avro_resolved_reader_t), the resolved value is
 
46
 * an instance of the reader schema, and wraps an instance of the writer
 
47
 * schema.  This is used when resolving an existing Avro value to
 
48
 * another schema; you've already got the value in the original (writer)
 
49
 * schema, and want to transparently treat it as if it were an instance
 
50
 * of the new (reader) schema.  You can only read the values of a
 
51
 * resolved reader; you must use the original wrapped value to write.
 
52
 *
 
53
 * For both classes, the “self” pointer of the resolved value is an
 
54
 * avro_value_t pointer, which points at the wrapped value.
 
55
 */
 
56
 
 
57
 
 
58
/**
 
59
 * Create a new resolved writer implementation for the given writer and
 
60
 * reader schemas.
 
61
 */
 
62
 
 
63
avro_value_iface_t *
 
64
avro_resolved_writer_new(avro_schema_t writer_schema,
 
65
                         avro_schema_t reader_schema);
 
66
 
 
67
/**
 
68
 * Creates a new resolved writer value.
 
69
 */
 
70
 
 
71
int
 
72
avro_resolved_writer_new_value(avro_value_iface_t *iface,
 
73
                               avro_value_t *value);
 
74
 
 
75
/**
 
76
 * Sets the wrapped value for a resolved writer.  This must be an
 
77
 * instance of the reader schema.  We create our own reference to the
 
78
 * destination value.
 
79
 */
 
80
 
 
81
void
 
82
avro_resolved_writer_set_dest(avro_value_t *resolved,
 
83
                              avro_value_t *dest);
 
84
 
 
85
 
 
86
/**
 
87
 * Clears the wrapped value for a resolved writer.
 
88
 */
 
89
 
 
90
void
 
91
avro_resolved_writer_clear_dest(avro_value_t *resolved);
 
92
 
 
93
 
 
94
/**
 
95
 * Create a new resolved reader implementation for the given writer and
 
96
 * reader schemas.
 
97
 */
 
98
 
 
99
avro_value_iface_t *
 
100
avro_resolved_reader_new(avro_schema_t writer_schema,
 
101
                         avro_schema_t reader_schema);
 
102
 
 
103
/**
 
104
 * Creates a new resolved reader value.
 
105
 */
 
106
 
 
107
int
 
108
avro_resolved_reader_new_value(avro_value_iface_t *iface,
 
109
                               avro_value_t *value);
 
110
 
 
111
/**
 
112
 * Sets the wrapped value for a resolved reader.  This must be an
 
113
 * instance of the reader schema.  We create our own reference to the
 
114
 * source value.
 
115
 */
 
116
 
 
117
void
 
118
avro_resolved_reader_set_source(avro_value_t *resolved,
 
119
                                avro_value_t *dest);
 
120
 
 
121
 
 
122
/**
 
123
 * Clears the wrapped value for a resolved reader.
 
124
 */
 
125
 
 
126
void
 
127
avro_resolved_reader_clear_source(avro_value_t *resolved);
 
128
 
 
129
CLOSE_EXTERN
 
130
#endif