# Remote Procedure Call Subsystem

A system to call C or object member procudures on other systems, and even to return return values. More...

## Files
file | RPCMap.h
| [Internal] A container class for a list of RPCNodes

file | RPCNode.h
| [Internal] Holds information related to a RPC

## Defines
#define | REGISTER_STATIC_RPC(networkObject, functionName) (networkObject)->RegisterAsRemoteProcedureCall((#functionName),(functionName))
| RPC Function Implementation.
#define | CLASS_MEMBER_ID(className, functionName) #className "_" #functionName
| Concatenate two strings.
#define | REGISTER_CLASS_MEMBER_RPC(networkObject, className, functionName) {union {void (__cdecl className::*cFunc)( RPCParameters *rpcParms ); void* voidFunc;}; cFunc=&className::functionName; networkObject->RegisterClassMemberRPC(CLASS_MEMBER_ID(className, functionName),voidFunc);}
| Register a member function of an instantiated object as a Remote procedure call. RPC member Functions MUST be marked __cdecl!
#define | UNREGISTER_STATIC_RPC(networkObject, functionName) (networkObject)->UnregisterAsRemoteProcedureCall((#functionName))
## Functions
void | RakPeer::RegisterAsRemoteProcedureCall (const char *uniqueID, void(*functionPointer)(RPCParameters *rpcParms))
void | RakPeer::RegisterClassMemberRPC (const char *uniqueID, void *functionPointer)
void | RakPeer::UnregisterAsRemoteProcedureCall (const char *uniqueID)
void | RakPeer::SetNetworkIDManager (NetworkIDManager *manager)
bool | RakPeer::RPC (const char *uniqueID, const char *data, BitSize_t bitLength, PacketPriority priority, PacketReliability reliability, char orderingChannel, SystemAddress systemAddress, bool broadcast, RakNetTime *includedTimestamp, NetworkID networkID, RakNet::BitStream *replyFromTarget)
bool | RakPeer::RPC (const char *uniqueID, const RakNet::BitStream *bitStream, PacketPriority priority, PacketReliability reliability, char orderingChannel, SystemAddress systemAddress, bool broadcast, RakNetTime *includedTimestamp, NetworkID networkID, RakNet::BitStream *replyFromTarget)
virtual void | RakPeerInterface::RegisterAsRemoteProcedureCall (const char *uniqueID, void(*functionPointer)(RPCParameters *rpcParms))=0
virtual void | RakPeerInterface::RegisterClassMemberRPC (const char *uniqueID, void *functionPointer)=0
virtual void | RakPeerInterface::UnregisterAsRemoteProcedureCall (const char *uniqueID)=0
virtual void | RakPeerInterface::SetNetworkIDManager (NetworkIDManager *manager)=0
virtual bool | RakPeerInterface::RPC (const char *uniqueID, const char *data, BitSize_t bitLength, PacketPriority priority, PacketReliability reliability, char orderingChannel, SystemAddress systemAddress, bool broadcast, RakNetTime *includedTimestamp, NetworkID networkID, RakNet::BitStream *replyFromTarget)=0
virtual bool | RakPeerInterface::RPC (const char *uniqueID, const RakNet::BitStream *bitStream, PacketPriority priority, PacketReliability reliability, char orderingChannel, SystemAddress systemAddress, bool broadcast, RakNetTime *includedTimestamp, NetworkID networkID, RakNet::BitStream *replyFromTarget)=0

## Detailed Description

A system to call C or object member procudures on other systems, and even to return return values.

## Define Documentation

#define CLASS_MEMBER_ID | ( | className,
|  | functionName |  | ) | #className "_" #functionName

Concatenate two strings.

Use the AutoRPC plugin instead

#define REGISTER_CLASS_MEMBER_RPC | ( | networkObject,
|  | className,
|  | functionName |  | ) | {union {void (__cdecl className::*cFunc)( RPCParameters *rpcParms ); void* voidFunc;}; cFunc=&className::functionName; networkObject->RegisterClassMemberRPC(CLASS_MEMBER_ID(className, functionName),voidFunc);}

Register a member function of an instantiated object as a Remote procedure call. RPC member Functions MUST be marked __cdecl!

Use the AutoRPC plugin instead

See also:
  ObjectMemberRPC.cpp CLASS_MEMBER_ID is a utility macro to generate a unique signature for a class and function pair and can be used for the Raknet functions RegisterClassMemberRPC(...) and RPC(...) REGISTER_CLASS_MEMBER_RPC is a utility macro to more easily call RegisterClassMemberRPC

Parameters:

  `[in]` | networkObject | Your instance of RakPeer, RakPeer, or RakPeer
  `[in]` | className | The class containing the function
  `[in]` | functionName | The name of the function (not in quotes, just the name)

#define REGISTER_STATIC_RPC | ( | networkObject,
|  | functionName |  | ) | (networkObject)->RegisterAsRemoteProcedureCall((#functionName),(functionName))

RPC Function Implementation.

The Remote Procedure Call Subsystem provide the RPC paradigm to RakNet user. It consists in providing remote function call over the network. A call to a remote function require you to prepare the data for each parameter (using BitStream) for example.

Use the following C function prototype for your callbacks

     void functionName(RPCParameters *rpcParms);

If you pass input data, you can parse the input data in two ways. 1. Cast input to a struct (such as if you sent a struct) i.e. MyStruct *s = (MyStruct*) input; Make sure that the sizeof(MyStruct) is equal to the number of bytes passed! 2. Create a BitStream instance with input as data and the number of bytes i.e. BitStream myBitStream(input, (numberOfBitsOfData-1)/8+1) (numberOfBitsOfData-1)/8+1 is how convert from bits to bytes Full example:

     void MyFunc(RPCParameters *rpcParms) {}
     RakPeer *rakClient;
     REGISTER_AS_REMOTE_PROCEDURE_CALL(rakClient, MyFunc);
     This would allow MyFunc to be called from the server using  (for example)
     rakServer->RPC("MyFunc", 0, clientID, false);

Use the AutoRPC plugin instead Register a C function as a Remote procedure.

Parameters:

  `[in]` | networkObject | Your instance of RakPeer, RakPeer, or RakPeer
  `[in]` | functionName | The name of the C function to call

Attention:
  12/01/05 REGISTER_AS_REMOTE_PROCEDURE_CALL renamed to REGISTER_STATIC_RPC. Delete the old name sometime in the future

#define UNREGISTER_STATIC_RPC | ( | networkObject,
|  | functionName |  | ) | (networkObject)->UnregisterAsRemoteProcedureCall((#functionName))

Use the AutoRPC plugin instead Unregisters a remote procedure call RPC member Functions MUST be marked __cdecl! See the ObjectMemberRPC example.

Parameters:

  `[in]` | networkObject | The object that manages the function
  `[in]` | functionName | The function name

## Function Documentation

virtual void RakPeerInterface::RegisterAsRemoteProcedureCall | ( | const char * | uniqueID,
|  | void(*)(RPCParameters *rpcParms) | functionPointer |
| ) |  |  | `[pure virtual, inherited]`

Use the AutoRPC plugin instead Register a C or static member function as available for calling as a remote procedure call

Parameters:

  `[in]` | uniqueID | A null-terminated unique string to identify this procedure. See RegisterClassMemberRPC() for class member functions.
  `[in]` | functionPointer(...) | The name of the function to be used as a function pointer. This can be called whether active or not, and registered functions stay registered unless unregistered

Implemented in RakPeer.

void RakPeer::RegisterAsRemoteProcedureCall | ( | const char * | uniqueID,
|  | void(*)(RPCParameters *rpcParms) | functionPointer |
| ) |  |  | `[virtual, inherited]`

Register a C or static member function as available for calling as a remote procedure call

Parameters:

  `[in]` | uniqueID | A null-terminated unique string to identify this procedure. See RegisterClassMemberRPC() for class member functions.
  `[in]` | functionPointer(...) | The name of the function to be used as a function pointer. This can be called whether active or not, and registered functions stay registered unless unregistered

Implements RakPeerInterface.

virtual void RakPeerInterface::RegisterClassMemberRPC | ( | const char * | uniqueID,
|  | void * | functionPointer |
| ) |  |  | `[pure virtual, inherited]`

Use the AutoRPC plugin instead Register a C++ member function as available for calling as a remote procedure call.

Parameters:

  `[in]` | uniqueID | A null terminated string to identify this procedure. Recommended you use the macro REGISTER_CLASS_MEMBER_RPC to create the string. Use RegisterAsRemoteProcedureCall() for static functions.
  `[in]` | functionPointer | The name of the function to be used as a function pointer. This can be called whether active or not, and registered functions stay registered unless unregistered with UnregisterAsRemoteProcedureCall

See also:
  The sample ObjectMemberRPC.cpp

Implemented in RakPeer.

void RakPeer::RegisterClassMemberRPC | ( | const char * | uniqueID,
|  | void * | functionPointer |
| ) |  |  | `[virtual, inherited]`

Register a C++ member function as available for calling as a remote procedure call.

Parameters:

  `[in]` | uniqueID | A null terminated string to identify this procedure. Recommended you use the macro REGISTER_CLASS_MEMBER_RPC to create the string. Use RegisterAsRemoteProcedureCall() for static functions.
  `[in]` | functionPointer | The name of the function to be used as a function pointer. This can be called whether active or not, and registered functions stay registered unless unregistered with UnregisterAsRemoteProcedureCall

See also:
  The sample ObjectMemberRPC.cpp

Implements RakPeerInterface.

virtual bool RakPeerInterface::RPC | ( | const char * | uniqueID,
|  | const RakNet::BitStream * | bitStream,
|  | PacketPriority | priority,
|  | PacketReliability | reliability,
|  | char | orderingChannel,
|  | SystemAddress | systemAddress,
|  | bool | broadcast,
|  | RakNetTime * | includedTimestamp,
|  | NetworkID | networkID,
|  | RakNet::BitStream * | replyFromTarget |
| ) |  |  | `[pure virtual, inherited]`

Calls a C function on the remote system that was already registered using RegisterAsRemoteProcedureCall. If you want that function to return data you should call RPC from that system in the same wayReturns true on a successful packet send (this does not indicate the recipient performed the call), false on failure

Parameters:

  `[in]` | uniqueID | A NULL terminated string identifying the function to call. Recommended you use the macro CLASS_MEMBER_ID for class member functions.
  `[in]` | data | The data to send
  `[in]` | bitLength | The number of bits of data
  `[in]` | priority | What priority level to send on. See PacketPriority.h.
  `[in]` | reliability | How reliability to send this data. See PacketPriority.h.
  `[in]` | orderingChannel | When using ordered or sequenced message, what channel to order these on.
  `[in]` | systemAddress | Who to send this message to, or in the case of broadcasting who not to send it to. Use UNASSIGNED_SYSTEM_ADDRESS to specify none
  `[in]` | broadcast | True to send this packet to all connected systems. If true, then systemAddress specifies who not to send the packet to.
  `[in]` | includedTimestamp | Pass a timestamp if you wish, to be adjusted in the usual fashion as per ID_TIMESTAMP. Pass 0 to not include a timestamp.
  `[in]` | networkID | For static functions, pass UNASSIGNED_NETWORK_ID. For member functions, you must derive from NetworkIDObject and pass the value returned by NetworkIDObject::GetNetworkID for that object.
  `[in]` | replyFromTarget | If 0, this function is non-blocking. Otherwise it will block while waiting for a reply from the target procedure, which should be remotely written to RPCParameters::replyToSender and copied to replyFromTarget. The block will return early on disconnect or if the sent packet is unreliable and more than 3X the ping has elapsed.

Returns:
  True on a successful packet send (this does not indicate the recipient performed the call), false on failure

Implemented in RakPeer.

virtual bool RakPeerInterface::RPC | ( | const char * | uniqueID,
|  | const char * | data,
|  | BitSize_t | bitLength,
|  | PacketPriority | priority,
|  | PacketReliability | reliability,
|  | char | orderingChannel,
|  | SystemAddress | systemAddress,
|  | bool | broadcast,
|  | RakNetTime * | includedTimestamp,
|  | NetworkID | networkID,
|  | RakNet::BitStream * | replyFromTarget |
| ) |  |  | `[pure virtual, inherited]`

Calls a C function on the remote system that was already registered using RegisterAsRemoteProcedureCall().

Parameters:

  `[in]` | uniqueID | A NULL terminated string identifying the function to call. Recommended you use the macro CLASS_MEMBER_ID for class member functions.
  `[in]` | data | The data to send
  `[in]` | bitLength | The number of bits of data
  `[in]` | priority | What priority level to send on. See PacketPriority.h.
  `[in]` | reliability | How reliability to send this data. See PacketPriority.h.
  `[in]` | orderingChannel | When using ordered or sequenced message, what channel to order these on.
  `[in]` | systemAddress | Who to send this message to, or in the case of broadcasting who not to send it to. Use UNASSIGNED_SYSTEM_ADDRESS to specify none
  `[in]` | broadcast | True to send this packet to all connected systems. If true, then systemAddress specifies who not to send the packet to.
  `[in]` | includedTimestamp | Pass a timestamp if you wish, to be adjusted in the usual fashion as per ID_TIMESTAMP. Pass 0 to not include a timestamp.
  `[in]` | networkID | For static functions, pass UNASSIGNED_NETWORK_ID. For member functions, you must derive from NetworkIDObject and pass the value returned by NetworkIDObject::GetNetworkID for that object.
  `[in]` | replyFromTarget | If 0, this function is non-blocking. Otherwise it will block while waiting for a reply from the target procedure, which should be remotely written to RPCParameters::replyToSender and copied to replyFromTarget. The block will return early on disconnect or if the sent packet is unreliable and more than 3X the ping has elapsed.

Returns:
  True on a successful packet send (this does not indicate the recipient performed the call), false on failure

Implemented in RakPeer.

bool RakPeer::RPC | ( | const char * | uniqueID,
|  | const RakNet::BitStream * | bitStream,
|  | PacketPriority | priority,
|  | PacketReliability | reliability,
|  | char | orderingChannel,
|  | SystemAddress | systemAddress,
|  | bool | broadcast,
|  | RakNetTime * | includedTimestamp,
|  | NetworkID | networkID,
|  | RakNet::BitStream * | replyFromTarget |
| ) |  |  | `[virtual, inherited]`

Calls a C function on the remote system that was already registered using RegisterAsRemoteProcedureCall. If you want that function to return data you should call RPC from that system in the same wayReturns true on a successful packet send (this does not indicate the recipient performed the call), false on failure

Precondition:
  To use object member RPC (networkID!=UNASSIGNED_OBJECT_ID), The recipient must have called SetNetworkIDManager so the system can handle the object lookups

Parameters:

  `[in]` | uniqueID | A NULL terminated string identifying the function to call. Recommended you use the macro CLASS_MEMBER_ID for class member functions.
  `[in]` | data | The data to send
  `[in]` | bitLength | The number of bits of data
  `[in]` | priority | What priority level to send on. See PacketPriority.h.
  `[in]` | reliability | How reliability to send this data. See PacketPriority.h.
  `[in]` | orderingChannel | When using ordered or sequenced message, what channel to order these on.
  `[in]` | systemAddress | Who to send this message to, or in the case of broadcasting who not to send it to. Use UNASSIGNED_SYSTEM_ADDRESS to specify none
  `[in]` | broadcast | True to send this packet to all connected systems. If true, then systemAddress specifies who not to send the packet to.
  `[in]` | includedTimestamp | Pass a timestamp if you wish, to be adjusted in the usual fashion as per ID_TIMESTAMP. Pass 0 to not include a timestamp.
  `[in]` | networkID | For static functions, pass UNASSIGNED_NETWORK_ID. For member functions, you must derive from NetworkIDObject and pass the value returned by NetworkIDObject::GetNetworkID for that object.
  `[in]` | replyFromTarget | If 0, this function is non-blocking. Otherwise it will block while waiting for a reply from the target procedure, which should be remotely written to RPCParameters::replyToSender and copied to replyFromTarget. The block will return early on disconnect or if the sent packet is unreliable and more than 3X the ping has elapsed.

Returns:
  True on a successful packet send (this does not indicate the recipient performed the call), false on failure

Implements RakPeerInterface.

bool RakPeer::RPC | ( | const char * | uniqueID,
|  | const char * | data,
|  | BitSize_t | bitLength,
|  | PacketPriority | priority,
|  | PacketReliability | reliability,
|  | char | orderingChannel,
|  | SystemAddress | systemAddress,
|  | bool | broadcast,
|  | RakNetTime * | includedTimestamp,
|  | NetworkID | networkID,
|  | RakNet::BitStream * | replyFromTarget |
| ) |  |  | `[virtual, inherited]`

Calls a C function on the remote system that was already registered using RegisterAsRemoteProcedureCall().

Precondition:
  To use object member RPC (networkID!=UNASSIGNED_OBJECT_ID), The recipient must have called SetNetworkIDManager so the system can handle the object lookups

Parameters:

  `[in]` | uniqueID | A NULL terminated string identifying the function to call. Recommended you use the macro CLASS_MEMBER_ID for class member functions.
  `[in]` | data | The data to send
  `[in]` | bitLength | The number of bits of data
  `[in]` | priority | What priority level to send on. See PacketPriority.h.
  `[in]` | reliability | How reliability to send this data. See PacketPriority.h.
  `[in]` | orderingChannel | When using ordered or sequenced message, what channel to order these on.
  `[in]` | systemAddress | Who to send this message to, or in the case of broadcasting who not to send it to. Use UNASSIGNED_SYSTEM_ADDRESS to specify none
  `[in]` | broadcast | True to send this packet to all connected systems. If true, then systemAddress specifies who not to send the packet to.
  `[in]` | includedTimestamp | Pass a timestamp if you wish, to be adjusted in the usual fashion as per ID_TIMESTAMP. Pass 0 to not include a timestamp.
  `[in]` | networkID | For static functions, pass UNASSIGNED_NETWORK_ID. For member functions, you must derive from NetworkIDObject and pass the value returned by NetworkIDObject::GetNetworkID for that object.
  `[in]` | replyFromTarget | If 0, this function is non-blocking. Otherwise it will block while waiting for a reply from the target procedure, which should be remotely written to RPCParameters::replyToSender and copied to replyFromTarget. The block will return early on disconnect or if the sent packet is unreliable and more than 3X the ping has elapsed.

Returns:
  True on a successful packet send (this does not indicate the recipient performed the call), false on failure

Implements RakPeerInterface.

virtual void RakPeerInterface::SetNetworkIDManager | ( | NetworkIDManager * | manager | ) | `[pure virtual, inherited]`

Used by Object member RPC to lookup objects given that object's ID Also used by the ReplicaManager plugin

Parameters:

  `[in]` | An | instance of NetworkIDManager to use for the lookup.

Implemented in RakPeer.

void RakPeer::SetNetworkIDManager | ( | NetworkIDManager * | manager | ) | `[virtual, inherited]`

Used by Object member RPC to lookup objects given that object's ID Also used by the ReplicaManager plugin

Parameters:

  `[in]` | An | instance of NetworkIDManager to use for the loookup.

Implements RakPeerInterface.

virtual void RakPeerInterface::UnregisterAsRemoteProcedureCall | ( | const char * | uniqueID | ) | `[pure virtual, inherited]`

Use the AutoRPC plugin instead Unregisters a C function as available for calling as a remote procedure call that was formerly registered with RegisterAsRemoteProcedureCall. Only call offline.

Parameters:

  `[in]` | uniqueID | A string of only letters to identify this procedure. Recommended you use the macro CLASS_MEMBER_ID for class member functions.

Implemented in RakPeer.

void RakPeer::UnregisterAsRemoteProcedureCall | ( | const char * | uniqueID | ) | `[virtual, inherited]`

Unregisters a C function as available for calling as a remote procedure call that was formerly registered with RegisterAsRemoteProcedureCall. Only call offline.

Parameters:

  `[in]` | uniqueID | A string of only letters to identify this procedure. Recommended you use the macro CLASS_MEMBER_ID for class member functions.

Implements RakPeerInterface.