RemoteCall2

From HEWIKI
Jump to: navigation, search
This is the "newest" form of RemoteCall where parameters are included directly in the statement. For the older version where the parameters are included in a separate variable, please see RemoteCall (old syntax).

Contents

call area <an ID> instance <an ID> <a function>(<arguments>) [[optional failure clause]]

call area <an ID> instance <an ID> <a ScriptRef>:<a function>(<arguments>) [[optional failure clause]]

call area <an ID> instance <an ID> <a NodeRef or ID>.<a method>(<arguments>) [[optional failure clause]]

call client <an ID or list of ID> <a ScriptRef>:<a function>(<arguments>) [[optional failure clause]]

call client <an ID or list of ID> <a node ID>.<a method>(<arguments>) [[optional failure clause]]

call clientReplicas <a node ID>.<a method>(<arguments>) [[optional failure clause]]

call serverReplicas <a NodeRef>.<a method>(<arguments>)

call server <a ScriptRef>:<a function>(<arguments>) [[optional failure clause]]

call server <a node ID>.<a method>(<arguments>) [[optional failure clause]]

call reply <a ScriptRef>:<a function>(<arguments>) [[optional failure clause]]

call reply <a node ID>.<a method>(<arguments>) [[optional failure clause]]

Overview

RemoteCall2 handles direct script to script Inter-Process Communication, both between servers, and between client and server.


Description

RemoteCall2 differs from the older version of RemoteCall, by trying to make remote calls as close as possible to regular function or method calls. Data is passed in the form of arguments, just like non-remote calls. It is still necessary to specify which area and instance to call, and the remote function or method must be marked as remotely callable via an appropriate modifier. There is also the option of specifying a function or method to be called in the event the remote call did not succeed.

The function or method being called must meet a couple of restrictions:

Passing NodeRefs

When a NodeRef is passed in a remote call, it is only the node ID that is passed. If a node with the same ID does not exist on the remote side, the NodeRef becomes equal to NONE.

Note: even System Nodes have different IDs in different areas, so they cannot be passed in a remote call. However, as an exception, the node being called in a method call can be a System Node, and it will be looked up automatically.


On the Sending Side

The keyword CALL is followed by keywords which determine which remote process will be called. After that, a normal function or method call is specified. Then comes the optional failure routing clause.

For server to server calls, the keywords to determine where the call goes are AREA, INSTANCE, and REPLY. REPLY is only valid inside a remote function or method and automatically designates the area and instance that sent the message being processed. If not using REPLY, both the AREA and INSTANCE keywords must be used and each followed by a value or expression.

For server to client calls, the keywords which determine where the call goes area CLIENT and REPLY. REPLY is only valid inside a untrusted function or method and automatically designates the client that sent the message being processed. The keyword CLIENT must be followed by an expression providing the ID of a _PlayerAccount node or a list of IDs.

For client to server calls, the CALL keyword must be followed by just the SERVER keyword.

The failure clause consists of the keyword failure followed by identification of what to be called. The identification looks like another function or method call except that there are no arguments or the usual parenthesis around them. The arguments that will be passed are the sames ones passed to the remote function or method. Here are some examples:

call area a instance i Example(<arguments>) failure <a function>

call area a instance i Example(<arguments>) failure <ScriptRef>:<a function>

call area a instance i Example(<arguments>) failure <NodeRef>.<a method>

Calling System Nodes Client/Server

Since there are different DOMs for client v. server, they each have their own set of prototypes and thus System Nodes. To emphasize this, system nodes are designated differently when the definition is to be found in the other DOM (% instead of $). The compiler will give an error if you attempt to Remote Call a method on the wrong kind of system node.


Calling a Method on all Clients where a Node is replicated

It is often desirable to issue a remote call to all of the clients that have a particular node replicated (See Replication). This is supported by a special syntax:

call clientReplicas <a node ID>.<a method>(<arguments>) [[optional failure clause]]

So any client to which <a node ID> is being replicated will receive the method call.


Calling a Method on all Servers where a Node is replicated

You can remote call to all of the servers that have a particular node replicated. This is supported by a special syntax:

call serverReplicas <a NodeRef>.<a method>(<arguments>)

So any server to which <a NodeRef> is being replicated, will receive the method call on the proxied node. Those methods need to be marked with the remote modifier and, in most cases, proxyLocal.


At the receiving end

Note: Client to Server calls no longer set the me node to the player's account. Instead, the account node is available in SYSTEM.REMOTE.CLIENT. This was necessary for remote method calls to any node.

System variables

When the remote call (or the failure call) is received, the following system variable values are available in addition to the passed parameters:

Field Name Description
SYSTEM.REMOTE.FROMSCRIPT The script that generated the call
SYSTEM.REMOTE.FROMFUNCTION The function or method which generated the call
SYSTEM.REMOTE.FROMNODE The me node when the call was generated
SYSTEM.REMOTE.TOSCRIPT The script to be called (None if method call)
SYSTEM.REMOTE.TOFUNCTION The function or method that was being sought
SYSTEM.REMOTE.TONODE The node ID for the method that was being sought
SYSTEM.REMOTE.FROMAREA The area ID of the server that made the original call
SYSTEM.REMOTE.FROMINSTANCE The area instance number of the server that made the original call
SYSTEM.REMOTE.TOAREA The area ID of the server that was being called
SYSTEM.REMOTE.TOINSTANCE The area instance number of the server that was being called
SYSTEM.REMOTE.CLIENT The account node ID for client to server calls
SYSTEM.REMOTE.ERROR A description for failed server to client calls


In the event of an error

If the call does not work, or it generates a script error, notification of the failure goes back to the calling location. A script call is then made to either the call's failure handler or the default handler.

If the call specified a failure clause, that function or method is called with the same parameters originally passed. This function or method must be marked remote-callable with the appropriate UNTRUSTED or REMOTE modifier.

If there was no failure clause, a method is called on the debug system node. When the original call was server to client, it is the method _clientRemoteCallFail; otherwise, it is the method _serverRemoteCallFail. In this case, none of the parameters are passed, but the system variables are available.


Examples

Making a call from a script in one instance, to the function MyRemoteCalledFunc in a script of the same name on Area 1, Instance 0. 

public function makeRemoteCall()   // This initializes the data for the call
  myid as id = me
  call area 1 instance 0 MyRemoteCalledFunc( myid ) failure MyRCFailHandler
.
 
remote function MyRemoteCalledFunc ( myid as id)   // This would be the destination function being called
  msgplayer(myid, "rc got script="+SYSTEM.REMOTE.FROMSCRIPT+" func="+SYSTEM.REMOTE.FROMFUNCTION+" area="+SYSTEM.REMOTE.FROMAREA+":"+SYSTEM.REMOTE.FROMINSTANCE)
 
  // could make a call back to the sending area with:
  call reply AnotherRemoteFunction("got the message!")
.
 
remote function MyRCFailHandler( myid as id)    // This is the function on the calling server,
  msgplayer(myid, "rc fail script="+SYSTEM.REMOTE.FROMSCRIPT+" func="+SYSTEM.REMOTE.FROMFUNCTION+"
area="+SYSTEM.REMOTE.FROMAREA+":"SYSTEM.REMOTE.FROMINSTANCE)
.

Calling a client from the server. 

// a server script
public function makeRemoteCall(account as NodeRef)
  call client account aClientScript:aClientFunction( "test", 42 )
.

// a client script
remote function aClientFunction( s as string, i as integer)
  println("got s="+s+" i="+i)
.

Calling the server from a client. 

// a client script
public function makeRemoteCall()
  call server aServerScript:aServerFunction( 0, "hello")
.

// a server script
untrusted function aServerFunction( i as integer, s as string)
  println("got s="+s+" i="+i+" from "+SYSTEM.REMOTE.CLIENT)
 
  // could make a call back to the sending client with:
  call reply aClientScript:aClientFunction("got the message!")
.

Calling a system node on the server from the client 

// a client script
public function makeRemoteCall()
  call server %aSystemNode.aServerMethod( 0, "hello")
.

// a server script on the system node
untrusted method aServerMethod( i as integer, s as string)
  println("got s="+s+" i="+i+" from "+SYSTEM.REMOTE.CLIENT)
.

Calling clients where exampleNode is replicated 

// a server script
public function demo(exampleNode as NodeRef)
  call clientReplicas exampleNode.aClientMethod()
.

See also

Retrieved from "http://hewiki.heroengine.com/wiki/RemoteCall2"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox