# 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](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket),[UDPSocket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/udpsocket),

## Methods Summarized

| Type                                                                                         | Name                                                                                                                                                                            | Summary                                                                                 |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [JSPacket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket)   | [createNewPacket()](#createnewpacket)                                                                                                                                           | Create a new empty packet.                                                              |
| [UDPSocket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/udpsocket) | [createSocket(port\_number)](#createsocket-port_number)                                                                                                                         | Create a new UDPSocket.                                                                 |
| [UDPSocket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/udpsocket) | [createSocket(port\_number, laddr)](#createsocket-port_number-laddr)                                                                                                            | Create a new UDPSocket that is binded to a specific local address.                      |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)                   | [getAllInetAddresses()](#getallinetaddresses)                                                                                                                                   | Get all available network interfaces.                                                   |
| [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object)                 | [getInetAddress({String})](#getinetaddress-{string})                                                                                                                            | Returns a InetAddress for a specific (local) ip or hostname.                            |
| [JSPacket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket)   | [getReceivedPacket()](#getreceivedpacket)                                                                                                                                       | Get a packet from receive buffer, read buffer until empty (null is returned).           |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)               | [sendPacket(destIpOrHostname, packet)](#sendpacket-destiporhostname-packet)                                                                                                     | Send a packet.                                                                          |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)               | [sendPacket(destIpOrHostname, packet, port)](#sendpacket-destiporhostname-packet-port)                                                                                          | Send a packet on another port.                                                          |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)               | [startSocket(port\_number, method\_to\_call\_when\_packet\_received\_and\_buffer\_is\_empty)](#startsocket-port_number-method_to_call_when_packet_received_and_buffer_is_empty) | Start a UDP socket for a port.                                                          |
| void                                                                                         | [stopSocket()](#stopsocket)                                                                                                                                                     | Stop the UDP socket for a port.                                                         |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)               | [testPacket(packet)](#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](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket) a new, empty JSPacket instance for creating and sending UDP packets.

**Sample**

```js
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
```

### createSocket(port\_number)

Create a new UDPSocket.

**Parameters**

* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **port\_number** the local port that this UDP socket will bind to.

**Returns:** [UDPSocket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/udpsocket) a new UDPSocket instance for sending and/or receiving UDP packets.

**Sample**

```js
var socket = plugins.udp.createSocket(4321);
var packet = plugins.udp.createNewPacket()
packet.writeUTF('hello world!')
socket.sendPacket('10.0.0.1',packet, 4321)
socket.close();
```

### createSocket(port\_number, laddr)

Create a new UDPSocket that is binded to a specific local address.

**Parameters**

* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **port\_number** the local port that this UDP socket will bind to.
* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **laddr** the local address that this UDP socket will bind to

**Returns:** [UDPSocket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/udpsocket) a new UDPSocket instance for sending and/or receiving UDP packets.

**Sample**

```js
var address = plugins.udp.getAllInetAddresses().find(xxxx);
var socket = plugins.udp.createSocket(4321, address).start(reveive_callback|);
var packet = plugins.udp.createNewPacket()
packet.writeUTF('hello world!')
socket.sendPacket('10.0.0.1',packet, 4321)
socket.close();
```

### getAllInetAddresses()

Get all available network interfaces.

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) An array of all available IP addresses from the system's network interfaces.

### getInetAddress({String})

Returns a InetAddress for a specific (local) ip or hostname.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **{String}** destIpOrHostname The IP address or hostname to resolve into an InetAddress.

**Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) The InetAddress object for the given IP address or hostname, or null if the address could not be resolved.

### getReceivedPacket()

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

**Returns:** [JSPacket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket) the next JSPacket from the receive buffer, or null if the buffer is empty.

**Sample**

```js
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](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **destIpOrHostname** the ip of the destination or the hostname
* [JSPacket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket) **packet** the JSPacket to send

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the packet was successfully sent; otherwise, false.

**Sample**

```js
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](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **destIpOrHostname** the ip of the destination or the hostname
* [JSPacket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket) **packet** the JSPacket to send
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **port** the port on which to send the packet

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the packet was successfully sent to the specified port; otherwise, false.

**Sample**

```js
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](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **port\_number** the local port that this UDP socket will bind to.
* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/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](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the UDP socket was successfully started; otherwise, false.

**Sample**

```js
plugins.udp.startSocket(1234,my_packet_process_method)
```

### stopSocket()

Stop the UDP socket for a port.

**Returns:** void

**Sample**

```js
plugins.udp.stopSocket()
```

### testPacket(packet)

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

**Parameters**

* [JSPacket](https://docs.servoy.com/reference/servoyextensions/server-plugins/udp/jspacket) **packet** ;

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the test packet was successfully added to the receive buffer; otherwise, false.

**Sample**

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

***