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