<<MenuNavi(roscpp/Overview)>>
<<TableOfContents(4)>>

== Message Generation ==
Like all ROS [[Client Libraries]], roscpp takes [[msg]] files and generates C++ source code for them.  The pattern for this is:
 `package_name/msg/Foo.msg` &rarr; `package_name::Foo`
Similarly, [[srv]] files have C++ source code generated.  The pattern for this is:
 `package_name/srv/Foo.srv` &rarr; `package_name::Foo`

Note that a limitation of roscpp is that the message and service namespaces overlap.

The source for the generated files are put in the `msg_gen/cpp/include/package_name/` and `srv_gen/cpp/include/package_name/` directories, for messages and services respectively.  The header files are generated with the same name as the filename of the msg/srv.

Thus, including the `std_msgs/String` message in your code involves:
{{{#!cplusplus
#include <std_msgs/String.h>
}}}

and instantiating the message:

{{{#!cplusplus
std_msgs::String str;
}}}

For details on what C++ code results from different message primitives, please see the [[msg]] page.

Note that all fields in a message are currently initialized to a default value of 0 (or empty for strings and variable-length arrays).

== Exposing Messages to Other Packages (not necessary in ROS 1.1+) ==
In ROS 1.1+ this is taken care of automatically, no changes to the manifest are necessary.

In order to expose messages for use by other packages, you must include an export tag in your package's manifest.  For example:
{{{
<export>
    <cpp cflags="-I${prefix}/msg/cpp"/>
</export>
}}}

If you want to also expose services:
{{{
<export>
    <cpp cflags="-I${prefix}/msg/cpp -I${prefix}/srv/cpp"/>
</export>
}}}

== Forward-declaring Messages [ROS 1.1+] ==
There is a macro that lets you easily forward-declare a message and its `shared_ptr` types:

{{{
#!cplusplus
ROS_DECLARE_MESSAGE(MyMessage);
}}}

This will expand to:
{{{
#!cplusplus
template<class ContainerAllocator> struct MyMsg_;
typedef MyMessage_<std::allocator<void> > MyMsg;
typedef boost::shared_ptr<MyMsg> MyMsgPtr;
typedef boost::shared_ptr<MyMsg const> MyMsgConstPtr;
}}}

== Retrieving Type Information for Fields in Templates ==
The C++ message generator provides some useful typedefs because C++ does not offer a `typeof` operator.  For every field in a message, it generates a `_fieldname_type` typedef.  This allows template code some useful introspection on messages.

For example, the `std_msgs/String` message has the following typedef inside it:
{{{#!cplusplus
typedef std::string _data_type;
}}}

which corresponds to the field
{{{#!cplusplus
std::string data;
}}}

=== Example ===
An example of where this is useful is for array types.  If you want to iterate over an array, you don't need to know the full type of the array:
{{{
#!cplusplus
MyMessage::_my_array_type::iterator it = msg.my_array.begin();
...
}}}