Remote Procedure Calls

RPC Overview

Overview

-- DEPRECIATED: Use AutoRPC ---

Normally, when you send a network message you perform four steps:

Create or design a structure to hold your data
Write a function to encode and send that data
Create a packet identifier so the recipient knows which function to call
Write a function to decode and handle that data.

These four steps can be quite cumbersome and force you to focus on the process of networking rather than writing your game.

Since the focus of RakNet is to allow you, the end-user, to quickly develop applications, Remote Procedure Calls were built into RakNet to streamline this process down to what you actually need in your code:

Encode your data
Call a function on the remote system with that data

Here is the complete process of how to implement RPC in your game.

Step 1: Tell the network system to allow a function to be called using RPC:

You can't just call any function on the remote system with RPC, or else this would open up your servers to hacks. You must first tell the network system to allow a function, defined with a specific prototype, to be called. You must match the prototype parameters, calling convention, and return value exactly. This is done as follows:

C function
void MyFunction(RPCParameters *rpcParameters) {}
// A pointer to a peer
RakPeerInterface *rakPeer;
// A macro to assign the function to the peer
REGISTER_STATIC_RPC(rakPeer, MyFunction);

C++ static function
static void MyClass::MyFunction(RPCParameters *rpcParameters) {}
// A pointer to a peer
RakPeerInterface *rakPeer;
// A macro to assign the function to the client
REGISTER_STATIC_RPC(rakPeer, MyClass::MyFunction);

C++ member function
class MyClass : public NetworkIDObject {
void __cdecl func1(RPCParameters *rpcParms);
};
// A pointer to the client
RakPeerInterface *rakPeer;
// A macro to assign the function to the client
REGISTER_CLASS_MEMBER_RPC(rakPeer, MyClass, func1)

Step 2: (Optional) Encode your data

You may choose to prepare your data with the help of BitStream, or just use your own data in a (char*) block, as the RPC method of your RakPeerInterface object can take either a (char*) with a length or a Bitstream. This is equivalent to creating your packet.

Step 3: Call the RPC method

Call the RPC method of your RakPeerInterface object with either a (char*) and a length, or a Bitstream you used to create your packet.

Step 4: Handle the call on the remote system

Assuming all went well, the function you specified on the other system will now be called. If it wasn't called it could be several things:

You didn't register the function as callable
You called a different function, or mistyped the name
You are not calling Receive(). This is needed because RPCs are handled in the same thread that your code is running.
One of the normal reasons a packet wouldn't arrive

See Samples/RemoteProcedureCalls/RPC.cpp for a complete example.

RPC Function prototype

void functionName(RPCParameters *rpcParameters)

All RPC functions should be C functions that use the specified prototype. RPCParameters::input will point to a stream of bytes that is whatever data you passed when you made the call. RPCParameters::numberOfBitsOfData is just that - how many bits you sent. Note that if you parse this to a BitStream constructor, the BitStream constructor wants bytes of data. To convert bits to bytes, assuming you have at least one bit, use (numberOfBits-1)/8+1, or the macro BYTES_TO_BITS. The last parameter, RPCParameters::sender, is the SystemAddress of the system that made the call to RPC.

As stated above, function names must be composed of a string with only characters from a-z and is not case sensitive.