Attribute Syntax

Attributes can be defined either at class or at member function, variable or event level. Attributes must be placed before the respective class or member definition they apply to. Attributes are placed within special C++ line comments. A comment defining attributes must start with //@. Multiple attributes can be specified, either using multiple lines (each starting with //@, or within a single comment line, separated by comma.

Example: a single attribute:

//@ remote
void myMethod(int i);

Example: multiple attributes on a single line:

//@ remote, synchronized
void myMethod(int i);

Example: multiple attributes on multiple lines:

//@ remote
//@ synchronized
void myMethod(int i);

Attributes can have values. If no value is specified for an attribute, the attribute's default value is true.

Example:

//@ remote, synchronized
void myMethod(int i);

is equivalent to:

//@ remote = true, synchronized = true

An attribute specified at class level is inherited by all member functions of the class. If an attribute is specified both at class and member function level, the latter takes precedence. Attribute names and values are case sensitive.

Attributes can be specified for parameters, as well. In this case, the syntax is slightly different. The attribute name must be the same as the parameter name, prepended with a dollar sign, and the actual attributes are defined as subattributes of the parameter attribute, placed in curly brackets.

Example:

//@ remote
//@ $i = {name = "value-i", type = "attr"}
void myMethod(int i);

Attribute values must be quoted if they contain characters like -,.?/ or begin with an integer value.

Attribute Reference

action

Assigns an SOAP action to a method. Used by the SOAP transport only.

• level: method
• type: string

cacheExpire

Sets the time how long return values are cached. A cacheExpire value consists of a single positive integer number and a single appended unit. Valid units are: ms, s(ec), m(in), h(our) If no unit is specified milliseconds are assumed. The entire value must be written within quotes. If the value "infinite" is set, data will be cached infinitely. Note that setting this parameter is not enough to enable caching. The @cacheResult attribute must be specified as well.

• level: class, method
• type: "infinite" or an unsigned integer, followed by an optional unit

Examples: "2h", "4min", "2000ms", "infinite"

cacheResult

Enables caching of return values. Will reduce the number of method calls if a remote method always returns the same value (for a certain time). See also the @cacheExpire attribute.

• level : method
• type: boolean
• default: true

direction

Specifies whether a parameter is input, output or input/output. Whether a parameter is input or input/output is normally determined automatically, depending on how the parameter is passed (by value or by const or non-const reference). However, a C++ function signature provides no way to designate a parameter as output only. The @direction attribute allows to rectify that.

• level: parameter
• type: ["in"|"out"|"inout"]
• default: "in" for parameters passed by value or const reference, "inout" for parameters passed by non-const reference

Example:

//@ $image = {direction = "out"}
void retrieveImage(const std::string& id, std::vector<char>& image);

Without the @direction attribute, the image parameter would be first passed to the server, which in this case is unnecessary, and then passed back to the client, containing the desired result.

header

Serialize a parameter in the SOAP header instead of the SOAP body. Only useful with the SOAP Transport. Can be set at method parameters only. Can only be specified for parameters that have a complex data, user-defined data type (class or struct). Note that the @soapHeader attribute splits method parameters into two groups: the header group and the body group. The order value (see the @order attribute) of all header group members must be lower than the smallest order value of the body group, i.e. all header elements are serialized before the body elements.

• level: parameter
• type: boolean
• default: true

inline

Change the way return values are serialized. This attribute can only be set for the return value of a method.

• level: return value
• type: boolean
• default: true

For example a method:

Time currentTimeAsStruct() const;

will return the following XML structure if the SOAP Transport is used:

<currentTimeAsStructReply>
    <return>
        <hour>10</hour>
        <minut>31</minute>
        <second>22</second>
    </return>
</currentTimeAsStructReply>

To change that structure to:

<Time>
    <hour>10</hour>
    <minut>31</minute>
    <second>22</second>
</Time>

the @replyName attribute can be specified, along with the @inline attribute on the return value, as follows:

//@ replyName = "Time", return = {inline}
Time currentTimeAsStruct() const;

Note that inlining cannot be combined with attributes, only with elements. Furthermore, no other output parameters are permitted in the method signature if the @inline attribute is specified.

mandatory

Defines if a parameter is mandatory or not. Valid on parameters and member variables. Only evaluated during deserialization. If not specified, the default value is true.

• level: parameter/variable
• type: boolean
• default: true

name

Rename a method, event, variable or parameter name. Useful for XML based transports, if the used schema requires a name which would be invalid in C++, like a name containing a minus sign. If used on a method, the @replyName attribute should be specified as well.

• level: method/parameter/variable
• type: string

namespace

Assigns an XML namespace to a class, method or parameter. Used by the SOAP Transport only.

• level: class/method/parameter
• type: string

oneway

Can be set on methods or events that do not have return values or output parameters. Ignored on all other methods. The @oneway attribute is an optimization that disables sending any response back to the caller. For example, calling a simple method like

void foo();

will result in sending a request and returning an empty response or in case of an error, an exception. Setting @oneway will force the skeleton and proxy to omit this response. While this will improve performance for most transports, it is a setting that should be used with care. It should only be used if the remote method is guaranteed not to throw an exception, or if it doesn't matter if an exception is thrown.

• level: method/event
• type: boolean
• default: true

order

Enforces that parameters are serialized in a specific order. Useful when an XML schema requires an order which is impossible in C++ due to the use of default values. Also, the serializer orders member variables (but not parameters) by their name as default. This attribute can be used to change that behavior. Note that it is not recommended to only partially specify the order element. Omitted or duplicate order values lead to undefined results.

• level: parameter/variable
• type: unsigned integer

Example:

//@ remote, $first = {order = 1}, $second = {order = 2}
void foo(int first, int second);

remote

Required for the generation of client and server stub code (proxy, skeleton, helper objects, etc.) for a class, method or event.

• level: class/method/event
• type: boolean
• default: true

replyName

Allows to rename the reply structure (or XML element) name returned by a method. The default is the name of the function with Reply appended (e.g., getData returns a structure named getDataReply).

• level: method/event
• type: string

serialize

Enable generation of Serializer and Deserializer classes for the given class. Note that the classes must follow a certain coding style for this to work. Refer to the Remoting user manual for more information. If a class is serializable, all super classes must have the "serialize" attribute as well.

• level: class
• type: boolean
• default: true

synchronized

If specified, calls to the remote object and the proxy will be serialized. This is required if the service object is not thread-safe. It is also required if the same proxy object is used simultaneously by multiple threads, although this practice is not recommended. Can be applied to proxies, remote objects, or both (default).

• level: class/method
• type: boolean or ["proxy"|"remote"|"all"|"none"]
• default: true

type

Specify whether a parameter is serialized as XML element or XML attribute (XML-based transports only). Must be either "attr" or "elem". The default value is "elem". Note that "attr" can not be set on complex types or vectors. As a general rule of thumb, "elem" should be used whenever possible, "attr" only where XML schema restrictions require it.

• level: parameter
• type: ["attr"|"elem"]
• default: elem