Register forum user name Search FAQ

UdpListen

Script function

world.UdpListen

Read about scripting

Type

Method

Summary

Listens for incoming packets using the UDP protocol

Prototype

long UdpListen(BSTR IP, short Port, BSTR Script);

View list of data type meanings

Description

This lets you set up a plugin script function that will be called whenever a UDP packet arrives on the specified port.

This lets you set up a separate program which can communicate with MUSHclient by sending it UDP packets.

The maximum size message that can be received is 999 bytes. In practice, attempting to receive more than 512 bytes may fail due to fragmentation over the network. Note that UDP packets are not guaranteed to arrive, or may arrive out of order. If UDP packets are fragmented by routers, and any fragment does not arrive, then the whole packet is discarded.

UDP is best used in situations where smallish amounts of data, which are not critical that they arrive at all, or in sequence, need to be sent. An example would be something like player or mob status information, where if one packet is lost, another would arrive shortly afterwards, and the loss of a single packet would be an inconvenience, not a disaster.

To listen to messages from any address use the address "0.0.0.0".

The address must be a dotted number, not a name (eg. "10.0.0.8")

You can cancel a listener by calling this function (for a previously-setup port) with an empty script name.

The script must be in a plugin, and be defined to accept a single string (which is the text that arrives in the UDP packet). For example, in Lua:

function listener (s)
-- process UDP packet "s" here
end -- listener


Available in MUSHclient version 3.56 onwards.



VBscript example

UdpListen "0.0.0.0", 4111, "MyScript"


Jscript example

UdpListen ("0.0.0.0", 4111, "MyScript")


Lua example

-- listening function in plugin:
function listener (s)
  ColourNote ("white", "blue", "Got UDP packet: " .. s)
end -- listener 

-- set up listener
require "check"
check (UdpListen ("0.0.0.0", 4111, "listener"))


Return value

eNotAPlugin: This must be called from a plugin
eBadParameter: The port is already in use by another plugin, or the UDP socket could not be created
eNoNameSpecified: No script name was specified
eOK: succeeded

View list of return code meanings

See Also ...

Functions

(GetUdpPort) Find a free port for UDP listening
(UdpPortList) Returns an array of all the UDP ports in use by this world
(UdpSend) Sends a packet over the network using the UDP protocol

(Help topic: function=UdpListen)

Documentation contents page


Search ...

Enter a search string to find matching documentation.

Search for:   

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.