Remote Call Framework 3.4

Remote calls in RCF are based on the concept of interfaces. RCF interfaces are specified using the RCF_BEGIN(), RCF_METHOD_<xx>() and RCF_END() macros. An interface specifies a number of remote methods, along with parameters and return values for those methods.

Here is an example of a simple RCF interface:

RCF_METHOD_R2(int, Add, int, int)
RCF_METHOD_V3(void, Multiply, int, int, int&)

Due to limitations of the C++ preprocessor, the name of the RCF_METHOD_<xx>() macro depends on the number of parameters to the method, and whether or not the method has a return type. The naming convention is as follows:

RCF_METHOD_{V|R}{<n>}() - Defines a RCF method return void (V) or non-void (R), and taking n parameters, where n ranges from 0 to 15.

So for example RCF_METHOD_V0() defines a method with a void return type and no parameters, while RCF_METHOD_R5() defines a method with a non-void return type, and taking 5 parameters.

Note that parameter names may not appear within the interface definition. You can add them as comments instead:

int, // Returns sum of two numbers.
int, // First number.
int) // Second number.
int, // First number.
int, // Second number.
int&) // Returns product of two numbers.

The return and parameter types of a method can be arbitrary C++ data types. However, for any type used, a seriaization function must be available (see Serialization). RCF provides built-in serialization functions for most standard library data types, but for application specific data types you will need to write your own serialization functions.

The parameters of a RCF method can be values, const references, or non-const references. To return data from a remote call, you can either use return types, or non-const references. The example above demonstrates using a return type for Add(), and a non-const reference parameter for Multiply().

It's possible to use pointers as parameters for a remote call. However, to avoid manual memory management, you are strongly advised to use C++ smart pointer classes instead, such as std::unique_ptr<> and std::shared_ptr<>.

The methods in a RCF interface are identified by the order in which they appear. Each method has a method ID number, starting with zero for the first method, and incrementing by 1 for each subsequent method. As the method ID number identifies methods, it's important from a versioning perspective (see Versioning) not to rearrange the order of methods within a RCF interface, or to insert methods between existing methods, if you have already deployed clients and servers using the interface.

There is a limit to the number of methods that can appear in a single RCF interface. This limit is set to 100 by default, and can be adjusted by defining RCF_MAX_METHOD_COUNT in your build (see Building RCF).