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.

See Also

Index Creating Packets Sending Packets Receiving Packets Bitstreams