User`s Manual - eProsima Middleware Experts
Contents
1. replace Replaces the generated source code files whether they exist ser lt cdr fastcdr gt Serialization mechanism used eProsima Fast Buffers currently supports two serialization mechanisms CDR serialization is the default mechanism but it also supports a Fast CDR serialization For each processed IDL file eProsima Fast Buffers tool generates four source code files Next diagram shows the generated source code files for a MyTypes idl example IDL file MyTypes cpp cm Y fastbuffers MyTypes h Next table summarizes the content of each generated file File Description MyTypes h C Header file containing the user data types mapped to C 11 programming language MyTypes cpp C Source file containing the user data types mapped to C 11 programming language 3 Defining your data types You have to define your data types using IDL format Not all IDL features are supported in this version of eProsima Fast Buffers This section shows you what IDL types are supported and how eProsima Fast Buffers maps them in C 11 programming language For each IDL file parsed by eProsima Fast Buffers two source code files are generated They contain the C 11 mapping of your IDL types For example from an IDL file named Foo idl eProsima Fast Buffers tool generates the files Foo h and Foo cpp that contain the C 11 mapping of the defined IDL types Next subsections introduce the supported IDL t2. struct HelloWorld string message Save this file as HelloWorld idl 6 2 Generating specific code Open a command prompt and go to the directory containing HelloWorld idl If you are running this example in Windows execute the following line fastbuffers example x64Win64VS2010 HelloWorld idl If you are running it in Linux execute this one fastbuffers example x64Linux2 6gcc HelloWorld idl Note that if you are running eProsima Fast Buffers in a 32 bit operating system you have to use example i86Win32VS2010 or example i86Linux2 6gcc instead This command generates your serialization code and some project files designed to build your HelloWorld example In Windows it generates a Visual Studio 2010 solution named solution x64Win64VS2010 s n This solution has two projects HelloWorld with the generated serialization code and HelloWorldExample with a usage example In Linux on the other hand it generates a makefile 6 3 Using the common API Edit the file HelloWorldExample cpp It takes a HelloWorld object defined as a structure in your IDL file serializes and deserializes it into another HelloWorld object You just have to add the initialization code and a statement to print the result like this example does int main FastBuffer fastbuffer Cdr HelloWorld_ser fastbuffer Structure to serialize HelloWorld ser_var The structure has to be initialized ser_var mes
3. operator const Union amp x Union amp operator Union amp amp x void d int32t _ d int32_t _d const int32_t amp d void octet_value uint8_t _octet_value uint8_t octet_value const 3 6 Enumerations uint8 t amp octet_value void long value int64_t _long value int64 t long value const int64_t amp long value void string value const std string amp string value void string value std string amp amp _string value const std string amp string value const std string amp string value private int32_t m_d uint8_t m_octet_value int64_t m_long value std string m_string value An enumeration in IDL format is a collection of identifiers that have a numeric value associated An IDL enumeration type is mapped directly to the corresponding C 11 enumeration definition The following table shows an example of an IDL enumeration type and its mapping to the C 11 programming language IDL C 11 enum Enumeration enum Enumeration uint32_t RED RED GREEN GREEN BLUE BLUE 5 y 4 Common API All generated data types contain the necessary functionality to be serialized or deserialized using the selected mechanism This section shows you the API provided to serialize your data types For more detailed information read the C 11 API Manual eProsima FastBuffers provides two classes which implement the supported serializat
4. take some points into consideration This section shows these points and how to deal with them eProsima Fast Buffers tool provides an option to generate and compile working examples You can obtain detailed information about integrating the generated code in your applications by using that option Including C 11 headers To compile the generated source code in your application you must specify the location of the C 11 headers used by this source code These headers are located in the eProsima Fast Buffers installation directory In Windows FAST_BUFFERS include In Linux they are found automatically because they were installed in usr include Linking against eProsima Fast Buffers library eProsima Fast Buffers contains a serialization library This library gathers all supported serialization mechanisms Your application must be linked against this library in order to achieve a successful compilation This library is located in the eProsima Fast Buffers installation directory In Windows FAST_BUFFERS lib In Linux it is found automatically because it was installed in usr lib 6 HelloWorld example This section explains how to write a HelloWorld example step by step This example has a simple structure with a string to serialize deserialize 6 1 Writing the IDL file The first step is to write an IDL file containing the structures you want to serialize deserialize In this case it is a simple structure
5. e E a is 16 1 Introduction eProsima Fast Buffers is a high performance serialization library capable of translating structured data into a format that can be stored and recovered later in the same or another computer environment You have to define your structured data once and then you can use specific generated source code to easily serialize and deserialize it in different operating systems To declare your structured data you have to use IDL Interface Definition Language format IDL is a specification language made by OMG Object Management Group which describes an interface in a language independent way enabling communication between software components that do not share the same language The main component of eProsima Fast Buffers is a tool that reads IDL files and parses a subset of the OMG IDL specification to generate serialization source code This subset includes only the data type descriptions included in section 3 Defining your data types The rest of the file content is ignored eProsima Fast Buffers has another relevant component a C 11 library which provides different serialization mechanisms Currently two serialization mechanisms are supported One of them is the standard CDR Common Data Representation CDR is a transfer syntax low level representation for transfer between agents mapping from data types defined in OMG IDL to byte streams The other one is a modified implementation of CDR which has an over
6. eProsima Fast Buffers User Manual Version 0 3 0 eProsima The Middleware Experts eProsima 2013 eProsima Proyectos y Sistemas de Mantenimiento SL Ronda del poniente 2 1 G 28760 Tres Cantos Madrid Tel 34 91 804 34 48 info eProsima com www eProsima com eProsima Trademarks eProsima is a trademark of Proyectos y Sistemas de Mantenimiento SL All other trademarks used in this document are the property of their respective owners License eProsima Fast Buffers is licensed under the terms described in the FAST_BUFFERS LICENSE file included in this distribution Technical Support e Phone 34 91 804 34 48 e Email support eprosima com Contents VANO CN A A A a sored ad canes seeds 4 2 Building your serialization COJE oooooooccccncconooononnnnnnnnonnnnnnrnnnnnnnnnnnnnnnnonnnnnnnnnnnnnnonnnnnnnnnnannnnnnnnnnnnnnnos 6 3 Defining YOUR dataVDES cansa faves e cones aa aa daa ved cade Lada IEA caves Reed ie 8 EA re OR n Pes id A A T 8 32 Array A ans 8 A ON 9 SA SUrUCtures dida 9 IJS UNION Srta dd cias 10 3 6 ENUIMEratiONS asen dai aa naaa res e Sei decoran daba 11 A COMMON AP EE TR E A E O A A E a T A 12 5 Integrating new SOUCE COMES arina eaa aaa lt div a deta taa dial dos as 14 6 Hello World Xampleniiiii a a E N A E A A aes 15 6 1 WritinethelDLl fe a r A a a RERS 15 6 2 Generating specific CO iia AA e a EA A ea ES 15 6 3 Using thecommon Alicia A A a aT 15 6 4 Building and eXe UTNE
7. g language IDL C 11 struct Structure octet octet_value long long value string string value 5 3 5 Unions class Structure 1 public Structure Structure Structure const Structure amp x Structure Structure amp amp x Structure amp operator const Structure amp x Structure amp operator Structure amp amp x void octet_value uint8_t _octet_value uint8_t octet_value const uint8 t amp octet_value void long value int64_t _long value int64 t long value const int64_t amp long value void string value const std string amp string value void string value std string amp amp string value const std string amp string value const std string amp string value private uint8_t m_octet_value int64_t m_long value std string m_string value y In IDL a union is defined as a sequence of members with their own types and a discriminant that specifies which member is in use An IDL union type is mapped as a C class with access functions to the union members and the discriminant The following table shows an example of IDL union type and its mapping to the C 11 programming language IDL C 11 union Union switch long case 1 octet octet_value case 2 long long value case 3 string string value class Union 1 public Union Union Union const Union amp x Union Union amp amp x Union amp
8. ion mechanisms The eprosima fastcdr Cdr class implements the CDR serialization and the eprosima fastcdr FastCdr class implements the FastCDR serialization This section splits this API in three categories and shows examples using both serialization mechanisms Initialization API eprosima fastcdr Cdr and eprosima fastcdr FastCdr classes need a raw buffer to read or write serialized data This raw buffer must be previously managed by an object of the class eprosima fastcdr FastBuffer Here is an example of the creation of both eprosima fastcdr FastBuffer and eprosima fastcdr Cdr objects Raw buffer where data is serialized char buffer 500 Object that manages the raw buffer eprosima fastcdr FastBuffer fastbuffer buffer 500 Object that serializes the data eprosima fastcdr Cdr ser fastbuffer An example of the creation of eprosima fastcdr FastBuffer and eprosima fastcdr FastCdr objects Raw buffer where data is serialized char buffer 500 Object that manages the raw buffer eprosima fastcdr FastBuffer fastbuffer buffer 500 Object that serializes the data eprosima fastcdr FastCdr ser fastbuffer Serialization API The eprosima fastcdr Cdr class offers two ways to serialize each data type e eprosima fastcdr Cdr amp operator lt lt const type amp This operator serializes a data value of the type type e eprosima fastcdr Cdr amp serialize const t
9. ir gt bin x64Linux2 6gcc directory and execute HelloWorld In both scenarios you will get this message when you run the binary file Hello World
10. ouble arraytype 5 std array lt double 5 gt arraytype 3 3 Sequences eProsima Fast Buffers supports sequences A sequence is mapped to the STD vector container The following table shows the supported sequence types and how they are mapped IDL C 11 sequence lt char gt sequencetype std vector lt char gt sequencetype sequence lt octet gt sequencetype std vector lt uint8_t gt sequencetype sequence lt short gt sequencetype std vector lt int16_t gt sequencetype sequence lt unsigned short gt sequencetype std vector lt uint16_t gt sequencetype sequence lt long gt sequencetype std vector lt int32_t gt sequencetype sequence lt unsigned long gt sequencetype std vector lt uint32_t gt sequencetype sequence lt long long gt sequencetype std vector lt int64_t gt sequencetype sequence lt unsigned long long gt sequencetype std vector lt uint64_t gt sequencetype sequence lt float gt sequencetype std vector lt float gt sequencetype sequence lt double gt sequencetype std vector lt double gt sequencetype 3 4 Structures In IDL a structure is defined as a set of members each one with its own type An IDL structure type is mapped as a C class while each member is mapped as a class attribute A set of methods to get and set the attribute is also created The following table shows and example of an IDL structure type and its mapping to the C 11 programmin
11. sage Hello World Serialization HelloWorld_ser lt lt ser_var Reset the reading position in the serializer object to start deserialization HelloWorld_ser reset The buffer will be deserialized in the next structure HelloWorld des_var Deserialization HelloWorld_ser gt gt des_var Print the deserialized message cout lt lt des_var message lt lt endl return Once your structure has been serialized if you want to obtain the corresponding char buffer you just have to invoke fastbuffer getBuffer method 6 4 Building and executing To build your code using Visual Studio 2010 make sure you are in the Debug or Release profile and then build it F7 Now go to lt example dir gt bin x64Win64vS2010 directory and execute HelloWorldExample exe You will get the message Hello World This example was created statically To create a DLL containing the serializators and the structures select the Debug DLL or Release DLL profile and build it F7 Now to get your dll and lib go to lt example_dir gt objs x64Win64vS2010 directory You can now run the same application dynamically using the exe file generated in lt example_dir gt bin x64wWin64vS2010 but first you have to make sure your dll location directory is appended to the PATH environment variable To build your code in Linux use this command make f makefile _x64Linux2 6gcc Now go to lt example_d
12. supports the generation of source code in C 11 Forthcoming releases will integrate more programming languages 2 Building your serialization code eProsima Fast Buffers provides a Java application responsible for generating source code using the data types defined in an IDL file This generated source code can be used in your applications in order to serialize your data types This section guides you through the usage of this Java application and briefly describes the generated files The Java application can be executed using the following script In Windows gt fastbuffers bat Note The script will be found by Windows if its location has been set in the PATH environment variable This can be done during the installation process More information can be found in the Installation Manual In Linux fastbuffers sh eProsima Fast Buffers Java application is capable of processing several IDL files The expected argument line is fastbuffers lt options gt lt IDL file gt lt IDL file gt where the available options are Option Description help Shows the help information version Shows the current version of eProsima Fast Buffers d lt directory gt Output directory where the generated files are created example lt platform gt Generates an example and a solution to compile the generated source code for a specific platform The help command shows the supported platforms
13. whelming speed up compared to the classical approach The reason why this implementation is faster is because it does not use some of the features of the standard CDR serialization in order to improve performance One of the main features of eProsima Fast Buffers is it avoids users from knowing anything about serialization or deserialization procedures For that task it provides a homogeneous API which supports serialization of several different data types With this document you are about to learn how to use eProsima Fast Buffers components improving the communications in your applications by using a fast serialization It is structured this Way e Section 1 Introduction presents eProsima Fast Buffers e You begin learning how to build source code for serializing data types in section 2 Building your serialization code e All supported data types by eProsima Fast Buffers are listed in section 3 Defining your data types This section also shows how to define these data types using the IDL definition language e Section 4 Common API explains the common API used by the generated source code e In section 5 Integrating new source code you learn how to integrate the new source code in your application e In section 6 HelloWorld example a complete HelloWorld example is shown 1 Visit http Awww omg org cgi bin doc formal 02 06 51 for more information about CDR serialization standard This release of eProsima Fast Buffers only
14. ype amp This method serializes a data value of the type type The eprosima fastcdr FastCdr class offers two ways to serialize each data type e eprosima fastcdr FastCdr amp operator lt lt const type amp This operator serializes a data value of the type type e eprosima fastcdr FastCdr amp serialize const type amp This method serializes a data value of the type type Deserialization API The eprosima fastcdr Cdr class offers two ways to deserialize e eprosima fastcdr Cdr amp operator gt gt type amp This operator deserializes a data value of the type type e eprosima fastcdr Cdr amp deserialize type amp This method deserializes a data value of the type type The eprosima fastcdr FastCdr class offers two ways to deserialize e eprosima fastcdr FastCdr amp operator gt gt type amp This operator deserializes a data value of the type type eprosima fastcdr FastCdr amp deserialize type amp This method deserializes a data value of the type type Here is an example of the serialization and deserialization of a Foo object Nariable of the type Foo defined in Foo idl Foo foo Serializing the variable with the previously created serialization object ser lt lt f00 Deserializing the variable with the previously created serialization object ser gt gt foo 5 Integrating new source code In order to integrate the generated source code in your application you have to
15. ypes 3 1 Basic types The following table shows the basic IDL types supported by eProsima Fast Buffers and how they are mapped to C 11 IDL C 11 char vartype char vartype octet vartype uint8_t vartype short vartype int16_t vartype unsigned short vartype uint16_t vartype long vartype int32_t vartype unsigned long vartype uint32_t vartype long long vartype int64_t vartype unsigned long long vartype uint64_t vartype float vartype float vartype double vartype double vartype boolean vartype bool vartype string vartype std string vartype 3 2 Arrays eProsima Fast Buffers supports arrays and multidimensional arrays An array is mapped to the STD array container The following table shows the supported array types and how they are mapped IDL type C 11 type char arraytype 5 std array lt char 5 gt arraytype octet arraytype 5 std array lt uint8_t 5 gt arraytype short arraytype 5 std array lt int16_t 5 gt arraytype unsigned short arraytype 5 std array lt uint16_t 5 gt arraytype long arraytype 5 std array lt int32_t 5 gt arraytype unsigned long arraytype 5 std array lt uint32_t 5 gt arraytype long long arraytype 5 std array lt int64 t 5 gt arraytype unsigned long long arraytype 5 std array lt uint64_t 5 gt arraytype float arraytype 5 std array lt float 5 gt arraytype d
Download Pdf Manuals
Related Search