RakNet  4.0
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
RakNet::RPC3 Class Reference

The RPC3 plugin allows you to call remote functions as if they were local functions, using the standard function call syntax. More...

#include <RPC3.h>

Inheritance diagram for RakNet::RPC3:
RakNet::PluginInterface2

Public Member Functions

void SetNetworkIDManager (NetworkIDManager *idMan)
 
template<typename Function >
bool RegisterFunction (const char *uniqueIdentifier, Function functionPtr)
 
template<typename Function >
void RegisterSlot (const char *sharedIdentifier, Function functionPtr, NetworkID objectInstanceId, int callPriority)
 
bool UnregisterFunction (const char *uniqueIdentifier)
 
bool IsFunctionRegistered (const char *uniqueIdentifier)
 
void SetTimestamp (RakNet::Time timeStamp)
 
void SetSendParams (PacketPriority priority, PacketReliability reliability, char orderingChannel)
 
void SetRecipientAddress (const SystemAddress &systemAddress, bool broadcast)
 
void SetRecipientObject (NetworkID networkID)
 
RakNet::Time GetLastSenderTimestamp (void) const
 
SystemAddress GetLastSenderAddress (void) const
 
void InterruptSignal (void)
 If called while processing a slot, no further slots for the currently executing signal will be executed.
 
RakPeerInterfaceGetRakPeer (void) const
 Returns the instance of RakPeer this plugin was attached to.
 
const char * GetCurrentExecution (void) const
 
bool Call (const char *uniqueIdentifier)
 
bool CallExplicit (const char *uniqueIdentifier, const CallExplicitParameters *const callExplicitParameters)
 
bool Signal (const char *sharedIdentifier)
 
bool SignalExplicit (const char *sharedIdentifier, const SignalExplicitParameters *const signalExplicitParameters)
 Same as Signal(), but you are forced to specify the remote system parameters.
 
void InvokeSignal (DataStructures::HashIndex functionIndex, RakNet::BitStream *serializedParameters, bool temporarilySetUSA)
 Call a given signal with a bitstream representing the parameter list.
 
- Public Member Functions inherited from RakNet::PluginInterface2
virtual void OnDetach (void)
 Called when the interface is detached.
 
virtual void Update (void)
 Update is called every time a packet is checked for .
 
virtual void OnRakPeerStartup (void)
 Called when RakPeer is initialized.
 
virtual void OnRakPeerShutdown (void)
 Called when RakPeer is shutdown.
 
virtual void OnNewConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID, bool isIncoming)
 
virtual void OnFailedConnectionAttempt (Packet *packet, PI2_FailedConnectionAttemptReason failedConnectionAttemptReason)
 
virtual bool UsesReliabilityLayer (void) const
 
virtual void OnDirectSocketSend (const char *data, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress)
 
virtual void OnDirectSocketReceive (const char *data, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress)
 
virtual void OnReliabilityLayerNotification (const char *errorMessage, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress, bool isError)
 
virtual void OnInternalPacket (InternalPacket *internalPacket, unsigned frameNumber, SystemAddress remoteSystemAddress, RakNet::TimeMS time, int isSend)
 
virtual void OnAck (unsigned int messageNumber, SystemAddress remoteSystemAddress, RakNet::TimeMS time)
 
virtual void OnPushBackPacket (const char *data, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress)
 

Protected Member Functions

void OnAttach (void)
 Called when the interface is attached.
 
virtual PluginReceiveResult OnReceive (Packet *packet)
 
virtual void OnClosedConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID, PI2_LostConnectionReason lostConnectionReason)
 

Protected Attributes

unsigned int nextSlotRegistrationCount
 Used so slots are called in the order they are registered.
 

Detailed Description

The RPC3 plugin allows you to call remote functions as if they were local functions, using the standard function call syntax.

No serialization or deserialization is needed.
As of this writing, the system is not threadsafe.
Features:
Pointers to classes that derive from NetworkID are automatically looked up using NetworkIDManager Types are written to BitStream, meaning built-in serialization operations are performed, including endian swapping Types can customize autoserialization by providing an implementation of operator << and operator >> to and from BitStream

Note
You cannot use RPC4 at the same time as RPC3

Member Function Documentation

bool RakNet::RPC3::Call ( const char *  uniqueIdentifier)
inline

Calls a remote function, using as send parameters whatever was last passed to SetTimestamp(), SetSendParams(), SetRecipientAddress(), and SetRecipientObject() If you call a C++ class member function, don't forget to first call SetRecipientObject(). You can use CallExplicit() instead of Call() to force yourself not to forget.

Parameters passed to Call are processed as follows:

  1. If the parameter is not a pointer
  2. - And you overloaded RakNet::BitStream& operator<<(RakNet::BitStream& out, MyClass& in) then that will be used to do the serialization
  3. - Otherwise, it will use bitStream.Write(myClass); BitStream already defines specializations for NetworkIDObject, SystemAddress, other BitStreams
  4. If the parameter is a pointer
  5. - And the pointer can be converted to NetworkIDObject, then it will write bitStream.Write(myClass->GetNetworkID()); To make it also dereference the pointer, use RakNet::_RPC3::Deref(myClass)
  6. - And the pointer can not be converted to NetworkID, but it is a pointer to RakNet::RPC3, then it is skipped
  7. Otherwise, the pointer is dereferenced and written as in step 2 and 3.
Note
If you need endian swapping (Mac talking to PC for example), you pretty much need to define operator << and operator >> for all classes you want to serialize. Otherwise the member variables will not be endian swapped.
If the call fails on the remote system, you will get back ID_RPC_REMOTE_ERROR. packet->data[1] will contain one of the values of RPCErrorCodes. packet->data[2] and on will contain the name of the function.
Parameters
[in]uniqueIdentifierparameter of the same name passed to RegisterFunction() on the remote system
bool RakNet::RPC3::CallExplicit ( const char *  uniqueIdentifier,
const CallExplicitParameters *const  callExplicitParameters 
)
inline

Calls a remote function, using whatever was last passed to SetTimestamp(), SetSendParams(), SetRecipientAddress(), and SetRecipientObject() Passed parameter(s), if any, are serialized using operator << with RakNet::BitStream. If you provide an overload it will be used, otherwise the seriailzation is equivalent to memcpy except for native RakNet types (NetworkIDObject, SystemAddress, etc.) If the type is a pointer to a type deriving from NetworkIDObject, then only the NetworkID is sent, and the object looked up on the remote system. Otherwise, the pointer is dereferenced and the contents serialized as usual.

Note
The this pointer, for this instance of RPC3, is pushed as the last parameter on the stack. See RPC3Sample.cpp for an example of this
If the call fails on the remote system, you will get back ID_RPC_REMOTE_ERROR. packet->data[1] will contain one of the values of RPCErrorCodes. packet->data[2] and on will contain the name of the function.
Parameters
[in]uniqueIdentifierparameter of the same name passed to RegisterFunction() on the remote system
[in]timeStampSee SetTimestamp()
[in]prioritySee SetSendParams()
[in]reliabilitySee SetSendParams()
[in]orderingChannelSee SetSendParams()
[in]systemAddressSee SetRecipientAddress()
[in]broadcastSee SetRecipientAddress()
[in]networkIDSee SetRecipientObject()
const char* RakNet::RPC3::GetCurrentExecution ( void  ) const

Returns the currently running RPC call identifier, set from RegisterFunction::uniqueIdentifier Returns an empty string "" if none

Returns
which RPC call is currently running
SystemAddress RakNet::RPC3::GetLastSenderAddress ( void  ) const

Returns the system address of the last system to send us a received function call Equivalent to the old system RPCParameters::sender

Returns
Last system to send an RPC call using this system
RakNet::Time RakNet::RPC3::GetLastSenderTimestamp ( void  ) const

If the last received function call has a timestamp included, it is stored and can be retrieved with this function.

Returns
0 if the last call did not have a timestamp, else non-zero
bool RakNet::RPC3::IsFunctionRegistered ( const char *  uniqueIdentifier)

Returns if a function identifier was previously registered on this system with RegisterFunction(), and not unregistered with UnregisterFunction()

Parameters
[in]uniqueIdentifierString identifying the function.
Returns
True if the function was registered, false otherwise
virtual void RakNet::RPC3::OnClosedConnection ( const SystemAddress systemAddress,
RakNetGUID  rakNetGUID,
PI2_LostConnectionReason  lostConnectionReason 
)
protectedvirtual

Called when a connection is dropped because the user called RakPeer::CloseConnection() for a particular system

Parameters
[in]systemAddressThe system whose connection was closed
[in]rakNetGuidThe guid of the specified system
[in]lostConnectionReasonHow the connection was closed: manually, connection lost, or notification of disconnection

Reimplemented from RakNet::PluginInterface2.

virtual PluginReceiveResult RakNet::RPC3::OnReceive ( Packet packet)
protectedvirtual

OnReceive is called for every packet.

Parameters
[in]packetthe packet that is being returned to the user
Returns
True to allow the game and other plugins to get this message, false to absorb it

Reimplemented from RakNet::PluginInterface2.

template<typename Function >
bool RakNet::RPC3::RegisterFunction ( const char *  uniqueIdentifier,
Function  functionPtr 
)
inline

Register a function pointer as callable using RPC()

Parameters
[in]uniqueIdentifierString identifying the function. Recommended that this is the name of the function
[in]functionPtrPointer to the function. For C, just pass the name of the function. For C++, use ARPC_REGISTER_CPP_FUNCTION
Returns
True on success, false on uniqueIdentifier already used
template<typename Function >
void RakNet::RPC3::RegisterSlot ( const char *  sharedIdentifier,
Function  functionPtr,
NetworkID  objectInstanceId,
int  callPriority 
)
inline

Register a slot, which is a function pointer to one or more instances of a class that supports this function signature When a signal occurs, all slots with the same identifier are called.

Parameters
[in]sharedIdentifierA string to identify the slot. Recommended to be the same as the name of the function.
[in]functionPtrPointer to the function. For C, just pass the name of the function. For C++, use ARPC_REGISTER_CPP_FUNCTION
[in]objectInstanceIf 0, then this slot is just a regular C function. Otherwise, this is a member of the given class instance.
[in]callPrioritySlots are called by order of the highest callPriority first. For slots with the same priority, they are called in the order they are registered
void RakNet::RPC3::SetNetworkIDManager ( NetworkIDManager idMan)

Sets the network ID manager to use for object lookup Required to call C++ object member functions via SetRecipientObject()

Parameters
[in]idManPointer to the network ID manager to use
void RakNet::RPC3::SetRecipientAddress ( const SystemAddress systemAddress,
bool  broadcast 
)

Set system to send to for all following calls to Call() Defaults to RakNet::UNASSIGNED_SYSTEM_ADDRESS, broadcast=true

Parameters
[in]systemAddressSee RakPeer::Send()
[in]broadcastSee RakPeer::Send()
void RakNet::RPC3::SetRecipientObject ( NetworkID  networkID)

Set the NetworkID to pass for all following calls to Call() Defaults to UNASSIGNED_NETWORK_ID (none) If set, the remote function will be considered a C++ function, e.g. an object member function If set to UNASSIGNED_NETWORK_ID (none), the remote function will be considered a C function If this is set incorrectly, you will get back either RPC_ERROR_CALLING_C_AS_CPP or RPC_ERROR_CALLING_CPP_AS_C

See Also
NetworkIDManager
Parameters
[in]networkIDReturned from NetworkIDObject::GetNetworkID()
void RakNet::RPC3::SetSendParams ( PacketPriority  priority,
PacketReliability  reliability,
char  orderingChannel 
)

Set parameters to pass to RakPeer::Send() for all following calls to Call() Deafults to HIGH_PRIORITY, RELIABLE_ORDERED, ordering channel 0

Parameters
[in]prioritySee RakPeer::Send()
[in]reliabilitySee RakPeer::Send()
[in]orderingChannelSee RakPeer::Send()
void RakNet::RPC3::SetTimestamp ( RakNet::Time  timeStamp)

Send or stop sending a timestamp with all following calls to Call() Use GetLastSenderTimestamp() to read the timestamp.

Parameters
[in]timeStampNon-zero to pass this timestamp using the ID_TIMESTAMP system. 0 to clear passing a timestamp.
bool RakNet::RPC3::Signal ( const char *  sharedIdentifier)
inline

Calls zero or more functions identified by sharedIdentifier. Uses as send parameters whatever was last passed to SetTimestamp(), SetSendParams(), and SetRecipientAddress() You can use CallExplicit() instead of Call() to force yourself not to forget to set parameters

See the Call() function for a description of parameters

Parameters
[in]sharedIdentifierparameter of the same name passed to RegisterSlot() on the remote system
bool RakNet::RPC3::UnregisterFunction ( const char *  uniqueIdentifier)

Unregisters a function pointer to be callable given an identifier for the pointer

Parameters
[in]uniqueIdentifierString identifying the function.
Returns
True on success, false on function was not previously or is not currently registered.

The documentation for this class was generated from the following file: