fNSend

 

PURPOSE: Send passed in data to destination receive function on specified node from CoC_ClientList and/or CoC_PeerList arrays. Since NS 1.2 these sends are queued and therefore are guaranteed to arrive in the order in which they were sent (unless "NO_NQ" is used, see description).  Clients considered disconnected will not receive any messages (unless "NO_DISC" is used, see description).

 

SYNTAX: [

            dest:Integer or Object, data:Array, destFunc:String or Integer

          *(,dataFail:Array,failFunc:String)

          **(,dataSuccess:Array,successFunc:String)

            (,"NO_NQ")(,"NO_DISC")

        ] call fNSend

 

* optional but dataFail and failFunc must be present together in order

** optional but dataFail,failFunc,dataSuccess and successFunc must be present together in order to use the success functionality

 

RETURNS: Integer    1 when executed.

 

DESCRIPTION: The fNSend function takes 3 or more parameters and is used to send virtually any data type across the network to any specific OFP network node. A network node is simply any OFP session connected in a network OFP session (game) listed in the CoC_ClientList and or CoC_PeerList arrays.

dest:Integer or Object

destination OFP network node index from the CoC_ClientList and or CoC_PeerList arrays, index 0 of both arrays always refers to the server node.  Can be a player object and will be automatically translated into the CoC_ClientChannel.

 

data:Array
data to send, this array of data will be sent across the network to the destination
network node and specific pre-processed receive function. Since version 2.0 any data type is supported, even
String, however make sure no string is linger than 4000 characters and that you limit the number of string sends for bandwidth concerns.


destFunc:String or Integer
Destination function name, this name will be used as the pre-processed function name to call remotely using the data sent. The 2nd parameter
data:Array will be passed to this pre-processed function on the destination network node as input.  Since version 2.0 the destination function name must be added to CoC_NSFunTable, identically on all nodes.  The destination function name will be turned into an index from CoC_NSFunTable before the send commences.  Optionally if a scripter is sure of the index as with CoC_NS core functions the function may be passed in as an Integer.
 

(optional dataFail:Array and failFunc:String)
dataFail:Array
data to pass to failed function, this array of data will be passed to the failed function in case a network communication error occurs and the destination node never receives the desired information. Strings can be passed normally as this is strictly local to the calling node.
 

failFunc:String
failed function name, this
String specifies the name of the pre-processed function which will be called in case a network communication error occurs during the send. The dataFail:Array will be passed to this pre-processed function as input.

 

(optional dataSuccess:Array and successFunc:String)
dataSuccess:Array
data to pass to success function, this array of data will be passed to the success function in case a network send succeeds and the destination node  receives the desired information. Strings can be passed normally as this is strictly local to the calling node.
 

successFunc:String
success function name, this
String specifies the name of the pre-processed function which will be called case a network send succeeds and the destination node receives the desired information. The dataSuccess:Array will be passed to this pre-processed function as input.

 

"NO_NQ" optional

case sensitive; asks the given message not to be en-queued in the message queue to the particular node.  The send will thus transfer ASAP but order in which these sends are received is not guaranteed.

 

"NO_DISC" optional

case sensitive; asks the given message to ignore the disconnected flag in CoC_PeerList and CoC_ClientList and attempt to send the message anyway.  Throwing (calling) the failFunc if it does not make it.

 

 

EXAMPLES:

[1,[player,"Hi"],"fNPrint"] call fNSend

 

[2,[player,"Hi"],"fNtest"],[daytime,"failed"],"fNFailtest"] call fNSend;

 

(ping client 3)
[3,[CoC_ClientChannel,daytime],"fnping"] call fNSend

(ping server)
[0,[CoC_ClientChannel,daytime],["fnping"]] call fNSend

(ping all)
[[CoC_ClientChannel,daytime],"fNping"] call fNSendAll

(ping all but do not queue message)
[[CoC_ClientChannel,daytime],"fNping","NO_NQ"] call fNSendAll

(ping all, do not queue message and ignore the disconnected flag)
[[CoC_ClientChannel,daytime],"fNping","NO_NQ","NO_DISC"] call fNSendAll

(send player object and "Hello world" to all clients and make them report it through fNPrint function)
[[Player,["Hello world"],"fNPrint"] call fnSendClients

(same as above but only to EastPlayerX, EastPlayerX is a named reference to a unit either from editor name or scripts)
[EastPlayerX, [Player,"Hello world"],"fNPrint"] call fnSend

(since index 0 of CoC_NSFunTable is "fNPrint" this is the same as above)
[EastPlayerX, [Player,"Hello world"],0] call fNSend

(ping EastPlayerX and call function failedFunc if ping could not be transferred, do not queue message)
[EastPlayerX,[CoC_ClientChannel,daytime],"fNping",[EastPlayerX],"failedFunc","NO_NQ"] call fNSend

(ping EastPlayerX and call function failedFunc with [EastPlayerX,"FAILED"] as data if ping could not be transferred, call successFunc with [EastPlayerX, SUCCESS] if send went through)
[EastPlayerX,[CoC_ClientChannel,daytime],"fNping",[EastPlayerX,"FAILED"],"failedFunc",[EastPlayerX,"SUCCESS"],"successFunc"] call fNSend

(execute skiptime 12 on all machines)
better use fNRemoteCall

[["skiptime 12"],"fnCall"]call fnsendAll

 

HISTORY: CoC bn880 08/05/2003; revised 14/11/2003, (Bn880, Spinor 07/05/2004)

DEPENDENCIES: CoC_LIBNUMSYS, CoC_LIBNETWORK