udp

(plugins.udp)

Overview

The UDP plugin facilitates communication using UDP sockets, enabling the sending and receiving of data packets. It supports creating and manipulating custom data packets, starting and stopping sockets, and testing packet handling logic.

For creating packets, use createNewPacket to initialize an empty packet and add data such as UTF strings, integers, or bytes. To receive data, use getReceivedPacket, which retrieves packets from the receive buffer until it is empty. To send data, utilize sendPacket by specifying the destination IP or hostname and an optional port. The testPacket function allows for placing test packets in the receive buffer to validate handling methods.

Sockets can be managed using startSocket to bind to a specific port and specify a callback method triggered when packets are received. The stopSocket method halts the socket’s operation.

This plugin supports practical use cases like real-time data transfer and network communication testing.

Returned Types

JSPacket,

Methods Summarized

Type	Name	Summary
JSPacket	createNewPacket()	Create a new empty packet.
JSPacket	getReceivedPacket()	Get a packet from receive buffer, read buffer until empty (null is returned).
Boolean	sendPacket(destIpOrHostname, packet)	Send a packet.
Boolean	sendPacket(destIpOrHostname, packet, port)	Send a packet on another port.
Boolean	startSocket(port_number, method_to_call_when_packet_received_and_buffer_is_empty)	Start a UDP socket for a port.
void	stopSocket()	Stop the UDP socket for a port.
Boolean	testPacket(packet)	Put a test packet in the receive buffer to test your method call and getReceivedPacket.

Methods Detailed

createNewPacket()

Create a new empty packet.

Returns: JSPacket a new, empty JSPacket instance for creating and sending UDP packets.

Sample

var packet = plugins.udp.createNewPacket()
packet.writeUTF('hello world!')//writes UTF
packet.writeInt(12348293)//writes 4 bytes
packet.writeShort(14823)//writes 2 bytes
packet.writeByte(123)//writes 1 byte

getReceivedPacket()

Get a packet from receive buffer, read buffer until empty (null is returned).

Returns: JSPacket the next JSPacket from the receive buffer, or null if the buffer is empty.

Sample

var packet = null
while( ( packet = plugins.udp.getReceivedPacket() ) != null)
{
	var text = packet.readUTF()
	var count = packet.readInt()
}

sendPacket(destIpOrHostname, packet)

Send a packet.

Parameters

• String destIpOrHostname the ip of the destination or the hostname
• JSPacket packet the JSPacket to send

Returns: Boolean true if the packet was successfully sent; otherwise, false.

Sample

var packet = plugins.udp.createNewPacket()
packet.writeUTF('hello world!')
plugins.udp.sendPacket('10.0.0.1',packet)

sendPacket(destIpOrHostname, packet, port)

Send a packet on another port.

Parameters

• String destIpOrHostname the ip of the destination or the hostname
• JSPacket packet the JSPacket to send
• Number port the port on which to send the packet

Returns: Boolean true if the packet was successfully sent to the specified port; otherwise, false.

Sample

var packet = plugins.udp.createNewPacket()
packet.writeUTF('hello world!')
plugins.udp.sendPacket('10.0.0.1',packet, 4321)

startSocket(port_number, method_to_call_when_packet_received_and_buffer_is_empty)

Start a UDP socket for a port.

Parameters

• Number port_number the local port that this UDP socket will bind to.
• Object method_to_call_when_packet_received_and_buffer_is_empty when the socket receives one or more packages, it calls this method once. The method will no longer be called even if new packages are received - until a call to UDPProvider#js_getReceivedPacket() returns null. So you should consume all available packets before you expect this method to be called again.

Returns: Boolean true if the UDP socket was successfully started; otherwise, false.

Sample

plugins.udp.startSocket(1234,my_packet_process_method)

stopSocket()

Stop the UDP socket for a port.

Returns: void

Sample

plugins.udp.stopSocket()

testPacket(packet)

Put a test packet in the receive buffer to test your method call and getReceivedPacket.

Parameters

• JSPacket packet ;

Returns: Boolean true if the test packet was successfully added to the receive buffer; otherwise, false.

Sample

var packet = plugins.udp.createNewPacket()
packet.writeUTF('hello world!')
plugins.udp.testPacket(packet)

---