Writing Converters » History » Version 6
« Previous -
Version 6/10
(diff) -
Next » -
Current version
J. Wienke, 06/26/2011 03:45 PM
some minor additions to make some sentences more clear
Writing Converters¶
Introduction¶
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 here. However, in many use-cases it is necessary to use additional converters for domain-specific types and/or serialization mechanisms.
This page describes how to add such converters to RSB using the running example of a converter for a fictional SimpleImage
data-type.
- It does not handle machine Endianess properly
- It does not handle machine word sizes properly
- It leaks memory
- It does not validate any data
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 here for Google protocol buffers.
Preparation¶
In order to implement a new converter, the following information is required:- To/from which 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
. - Which 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). - What is the wire-schema of the converter? In our example, we use the following ad-hoc wire-schema:
- Name:
simple-image
- Binary layout: one integer encoding the image width, one integer encoding the image height, width x height bytes for the image data
- Name:
Implementation: C++¶
SimpleImage
Domain type¶
The domain data-type is defined in:
source:trunk/cpp/core/examples/custom_converter/SimpleImage.h
SimpleImageConverter
Class¶
For the actual converter implementation, four things are needed:
- The C++ representation of the wire-type has to be passed to the
Converter
interface as a template parameter - The wire-schema and data-type name have to be passed to the
Converter
constructor - The
serialize
method has to be implemented - The
deserialize
method has to be implemented
A naive and incomplete implementation can be found here:
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.h
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.cpp
Using the Converter¶
A simple program that demonstrates the use of our SimpleImageConverter
can be found in
source:trunk/cpp/core/examples/custom_converter/sender.cpp
A similar program in which the registration of the converter is missing can be found in
source:trunk/cpp/core/examples/custom_converter/senderNoConverter.cpp
This second program servers the purpose of familiarizing you with the "missing-converter" error message, that you will encounter sooner or later ;)