Remote Procedure Calls

RPC Overview

Overview

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

Create a packet 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 the client
RakClient *rakClient;
// A macro to assign the function to the client
REGISTER_AS_REMOTE_PROCEDURE_CALL(rakClient, MyFunction);

C++ static function
static void MyClass::MyFunction(RPCParameters *rpcParameters) {}
// A pointer to the client
RakClient *rakClient;
// A macro to assign the function to the client
REGISTER_AS_REMOTE_PROCEDURE_CALL(rakClient, MyClass::MyFunction);

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

You use a similar process for the server.

Step 2: (Optional) Encode your data

The RPC method of your server or client can take either a (char*) with a length or a Bitstream. This is equivalent to creating your packet.

Step 3: Call the RPC method

The RPC method of your server or client can take either a (char*) with a length or a Bitstream. Note that the parameters for the server are the same as with Send and will handle timestamping for you the same way.

Step 4: Handle the call on the remote system

Assuming all went well, you will get a packet with the identifier ID_RPC. Pass this directly to your server or client method "HandleRPC." The function you specified on the remote 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
One of the normal reasons a packet wouldn't arrive

See Samples/CodeSamples/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 UNASSIGNED_PLAYER_ID for the server or the PlayerID of a particular client.

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