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.

See Also

Index Creating Packets Sending Packets Receiving Packets Bitstreams