<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Atlas-C++: Using Message::Object and higher layers</title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.9 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="tutorial_message">Using Message::Object and higher layers </a></h1><h3>Note</h3>
<h2><a class="anchor" name="higher_concepts">
Higher Concepts</a></h2>
<h3><a class="anchor" name="message_intro">
Introduction</a></h3>
By now you should know about Codecs, Bridges and such. You might have noticed that these are quite low-level. After all, it would be a great hassle if a server would have to parse messages itself by overriding Bridge member functions.<p>
This is where Atlas-C++'s higher layers come in. These include Encoders, Decoders and Layers.<h3><a class="anchor" name="encoders">
Encoders</a></h3>
Encoders accept data in a certain way and construct <a class="el" href="namespace_atlas.html" title="The Atlas namespace.">Atlas</a> messages from these, which they pass on to Codecs. For instance, you might have an encoder that takes STL maps and can send each of the items in the map as an <a class="el" href="namespace_atlas.html" title="The Atlas namespace.">Atlas</a> map item.<h3><a class="anchor" name="decoders">
Decoders</a></h3>
Decoders are on the other side of Encoders. They inherit from Bridge, which means you can pass them to a codec. They then parse incoming messages and pass them on to the application in some way. For instance, the corresponding example to the above case would be a Decoder that parses messages into STL maps and passes these on to the application, for instance with callback functions.<h3><a class="anchor" name="layers">
Layers</a></h3>
Layers are simply the combination of an Encoder and a Decoder. They are usually formed by publicly inheriting from an Encoder and a Decoder.<h3><a class="anchor" name="message">
The Message Layer</a></h3>
Now that you are aware of what Encoders, Decoders and Layers are, I will introduce you to one of the higher levels that Atlas-C++ provides: Message.<h3><a class="anchor" name="object">
Message::Object</a></h3>
This namespace includes a class called Object. As previously mentioned, <a class="el" href="namespace_atlas.html" title="The Atlas namespace.">Atlas</a> values can consists of one of 5 types: integers, floats, strings, maps and lists. However, C++ is a typed language, and does not support variables that can change type.<p>
This is where Message::Object comes in. It is a class that stores 5 differently typed values at once, namely - as you can surely guess - int, double, std::string, std::list<Message::Object> and std::map<std::string, Message::Object>.<p>
For each type two member functions exist: AsType() and IsType(), where Type may be one of Int, Float, String, List or Map (i.e. the 5 atlas types). AsType() comes in two forms, as a constant method returning a constant reference (so you can use it on const Message::Objects) and as a non-constant method returning a non-constant reference (so expressions of the form obj.AsList().push_back(123) are legal). IsType() returns a boolean value.<p>
To store a value in a Message::Object, you can simply assign the value to it. For instance, if you were to initialise an object with an empty string, you could declare your object in the form of Message::Object obj(string("")). Message::Object overrides conversion constructors for each of the 5 types.<p>
Message::Object also has an enum defined within it, Message::Object::Type. This can have one of the 6 values TYPE_INT, TYPE_FLOAT, TYPE_STRING, TYPE_LIST, TYPE_MAP and TYPE_NONE. It provides a member function, GetType(), which returns the appropriate value corresponding to the current type of the object. This is useful in switch() statements. TYPE_NONE is returned for objects that aren't initialised with any type at all, e.g. if you do not pass an argument to the constructor of an object.<h3><a class="anchor" name="message_enc">
Message::Encoder</a></h3>
Now, wouldn't it be useful if you could create your message as a Message::Object, and then simply send it off through a Codec, without having to call all those stream methods? Well, that's exactly what Message::Encoder lets you do. You can call StreamMessage(const Message::Object&) and it will send the object through a Codec (which you specified at construction time).<h3><a class="anchor" name="message_dec">
Message::Decoder</a></h3>
Message::Object truely comes in handy when you're receiving messages. Instead of having to keep a parse stack and implement your own Bridge, you can use the Message::DecoderBase class. This class is inherited publicly from Bridge and will do all the parsing for you. Hence, when a new message arrives, it gets put together into an easy-to-digest Message::Object. A protected method, ObjectArrived(const Message::Object&) then gets called, which you can override in a derived class to do something with the newly arrived message.<h3><a class="anchor" name="message_queued">
Message::QueuedDecoder</a></h3>
Message::QueuedDecoder, as annoying as it might be to spell, inherits from Message::DecoderBase and allows you to retrieve incoming Message::Objects in a queued fashion, rather than by overriding ObjectArrived(). It lets you check how many messages are currently queued, peek at the top of the message queue and pop the top message off the queue.<p>
<a class="el" href="tutorial_simple.html">Previous</a> <a class="el" href="tutorial_index.html">Index</a> <a class="el" href="tutorial_objects.html">Next</a><p>
<dl class="author" compact><dt><b>Author:</b></dt><dd>Stefanus Du Toit <<a href="mailto:sdt@gmx.net">sdt@gmx.net</a>> </dd></dl>
</div>
<HR>
<P>Copyright 2000-2004 the respective authors.</P>
<P>This document can be licensed under the terms of the GNU Free Documentation
License or the GNU General Public License and may be freely distributed under
the terms given by one of these licenses.</P>
