Writing Converters » History » Version 6

J. Wienke, 06/26/2011 03:45 PM
some minor additions to make some sentences more clear

1 1 J. Moringen
h1. Writing Converters
2 1 J. Moringen
3 1 J. Moringen
h2. Introduction
4 1 J. Moringen
5 1 J. Moringen
In RSB, converters are used to serialize and deserialize programming-language objects for transportation (e.g. over a network connection). RSB comes with converters for the fundamental types listed [[Types|here]]. However, in many use-cases it is necessary to use additional converters for domain-specific types and/or serialization mechanisms.
6 1 J. Moringen
7 2 J. Moringen
This page describes how to add such converters to RSB using the running example of a converter for a fictional @SimpleImage@ [[Glossary|data-type]].
8 1 J. Moringen
9 2 J. Moringen
*Warning: this tutorial has been written with simplicity in mind and should not be used as a blueprint for production code. In particular:*
10 2 J. Moringen
* It does not handle machine Endianess properly
11 2 J. Moringen
* It does not handle machine word sizes properly
12 2 J. Moringen
* It leaks memory
13 2 J. Moringen
* It does not validate any data
14 2 J. Moringen
15 5 J. Moringen
In many practical cases, some of these problems (and much of the manual work) can be avoided by using an IDL-specification in combination with code generation and generic converters as described [[ProtocolBufferConverter|here]] for Google protocol buffers.
16 5 J. Moringen
17 1 J. Moringen
h2. Preparation
18 1 J. Moringen
19 1 J. Moringen
In order to implement a new converter, the following information is required:
20 6 J. Wienke
* To/from which [[Glossary|wire-type]] will the converter serialize/deserialize? In our example, the wire-type is an array of bytes (or more formally an array of octets) which is represented in C++ using to @std::string@.
21 6 J. Wienke
* Which [[Glossary|data-type]] or (data-types) will be handled by the converter? The struct @SimpleImage@ in our example (please note that this is identified using a string for comparison, not the class itself).
22 2 J. Moringen
* What is the [[Glossary|wire-schema]] of the converter? In our example, we use the following ad-hoc wire-schema:
23 2 J. Moringen
** Name: @simple-image@
24 2 J. Moringen
** Binary layout: one integer encoding the image width, one integer encoding the image height, width x height bytes for the image data
25 1 J. Moringen
26 1 J. Moringen
h2. Implementation: C++
27 2 J. Moringen
28 2 J. Moringen
h3. @SimpleImage@ Domain type
29 2 J. Moringen
30 3 J. Moringen
The domain data-type is defined in:
31 1 J. Moringen
32 3 J. Moringen
source:trunk/cpp/core/examples/custom_converter/SimpleImage.h
33 3 J. Moringen
34 2 J. Moringen
h3. @SimpleImageConverter@ Class
35 2 J. Moringen
36 2 J. Moringen
For the actual converter implementation, four things are needed:
37 6 J. Wienke
# The C++ representation of the wire-type has to be passed to the @Converter@ interface as a template parameter
38 2 J. Moringen
# The wire-schema and data-type name have to be passed to the @Converter@ constructor
39 1 J. Moringen
# The @serialize@ method has to be implemented
40 1 J. Moringen
# The @deserialize@ method has to be implemented
41 1 J. Moringen
42 3 J. Moringen
A naive and incomplete implementation can be found here:
43 3 J. Moringen
44 3 J. Moringen
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.h
45 3 J. Moringen
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.cpp
46 3 J. Moringen
47 3 J. Moringen
h3. Using the Converter
48 3 J. Moringen
49 4 J. Moringen
A simple program that demonstrates the use of our @SimpleImageConverter@ can be found in
50 3 J. Moringen
51 3 J. Moringen
source:trunk/cpp/core/examples/custom_converter/sender.cpp
52 3 J. Moringen
53 3 J. Moringen
A similar program in which the registration of the converter is missing can be found in 
54 3 J. Moringen
55 3 J. Moringen
source:trunk/cpp/core/examples/custom_converter/senderNoConverter.cpp
56 3 J. Moringen
57 3 J. Moringen
This second program servers the purpose of familiarizing you with the "missing-converter" error message, that you will encounter sooner or later ;)