See: Description
Interface | Description |
---|---|
DatagramPacket |
A received datagram packet (UDP) which contains the data and information about the sender of the data itself.
|
DatagramSocket |
A datagram socket can be used to send
DatagramPacket 's to remote datagram servers
and receive DatagramPacket s . |
Class | Description |
---|---|
DatagramSocketOptions |
Options used to configure a datagram socket.
|
DatagramSocketOptionsConverter |
Converter for
DatagramSocketOptions . |
DatagramSocket
. It does not matter here if you only want to send data or send
and receive.
[source,$lang]
----
examples.DatagramExamples#example1
----
The returned DatagramSocket
will not be bound to a specific port. This is not a
problem if you only want to send data (like a client), but more on this in the next section.
=== Sending Datagram packets
As mentioned before, User Datagram Protocol (UDP) sends data in packets to remote peers but is not connected to
them in a persistent fashion.
This means each packet can be sent to a different remote peer.
Sending packets is as easy as shown here:
[source,$lang]
----
examples.DatagramExamples#example2
----
=== Receiving Datagram packets
If you want to receive packets you need to bind the DatagramSocket
by calling
`listen(...)}` on it.
This way you will be able to receive DatagramPacket
s that were sent to the address and port on
which the DatagramSocket
listens.
Beside this you also want to set a `Handler` which will be called for each received DatagramPacket
.
The DatagramPacket
has the following methods:
- DatagramPacket.sender()
: The InetSocketAddress which represent the sender of the packet
- DatagramPacket.data()
: The Buffer which holds the data which was received.
So to listen on a specific address and port you would do something like shown here:
[source,$lang]
----
examples.DatagramExamples#example3
----
Be aware that even if the {code AsyncResult} is successed it only means it might be written on the network
stack, but gives no guarantee that it ever reached or will reach the remote peer at all.
If you need such a guarantee then you want to use TCP with some handshaking logic build on top.
=== Multicast
==== Sending Multicast packets
Multicast allows multiple sockets to receive the same packets. This works by have same join a multicast group
to which you can send packets.
We will look at how you can joint a Multicast Group and so receive packets in the next section.
For now let us focus on how to send those. Sending multicast packets is not different to send normal Datagram Packets.
The only difference is that you would pass in a multicast group address to the send method.
This is show here:
[source,$lang]
----
examples.DatagramExamples#example4
----
All sockets that have joined the multicast group 230.0.0.1 will receive the packet.
===== Receiving Multicast packets
If you want to receive packets for specific Multicast group you need to bind the DatagramSocket
by
calling `listen(...)` on it and join the Multicast group.
This way you will be able to receive DatagramPackets that were sent to the address and port on which the
DatagramSocket
listens and also to those sent to the Multicast group.
Beside this you also want to set a Handler which will be called for each received DatagramPacket.
The DatagramPacket
has the following methods:
- `sender()`: The InetSocketAddress which represent the sender of the packet
- `data()`: The Buffer which holds the data which was received.
So to listen on a specific address and port and also receive packets for the Multicast group 230.0.0.1 you
would do something like shown here:
[source,$lang]
----
examples.DatagramExamples#example5
----
===== Unlisten / leave a Multicast group
There are sometimes situations where you want to receive packets for a Multicast group for a limited time.
In this situations you can first start to listen for them and then later unlisten.
This is shown here:
[source,$lang]
----
examples.DatagramExamples#example6
----
===== Blocking multicast
Beside unlisten a Multicast address it's also possible to just block multicast for a specific sender address.
Be aware this only work on some Operating Systems and kernel versions. So please check the Operating System
documentation if it's supported.
This an expert feature.
To block multicast from a specific address you can call `blockMulticastGroup(...)` on the DatagramSocket
like shown here:
[source,$lang]
----
examples.DatagramExamples#example7
----
==== DatagramSocket properties
When creating a DatagramSocket
there are multiple properties you can set to
change it's behaviour with the DatagramSocketOptions
object. Those are listed here:
- DatagramSocketOptions.setSendBufferSize(int)
Sets the send buffer size in bytes.
- DatagramSocketOptions.setReceiveBufferSize(int)
Sets the TCP receive buffer size
in bytes.
- DatagramSocketOptions.setReuseAddress(boolean)
If true then addresses in TIME_WAIT
state can be reused after they have been closed.
- DatagramSocketOptions.setTrafficClass(int)
- DatagramSocketOptions.setBroadcast(boolean)
Sets or clears the SO_BROADCAST socket
option. When this option is set, Datagram (UDP) packets may be sent to a local interface's broadcast address.
- DatagramSocketOptions.setMulticastNetworkInterface(java.lang.String)
Sets or clears
the IP_MULTICAST_LOOP socket option. When this option is set, multicast packets will also be received on the
local interface.
- DatagramSocketOptions.setMulticastTimeToLive(int)
Sets the IP_MULTICAST_TTL socket
option. TTL stands for "Time to Live," but in this context it specifies the number of IP hops that a packet is
allowed to go through, specifically for multicast traffic. Each router or gateway that forwards a packet decrements
the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.
==== DatagramSocket Local Address
You can find out the local address of the socket (i.e. the address of this side of the UDP Socket) by calling
DatagramSocket.localAddress()
. This will only return an `InetSocketAddress` if you
bound the DatagramSocket
with `listen(...)` before, otherwise it will return null.
==== Closing a DatagramSocket
You can close a socket by invoking the DatagramSocket.close(io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>>)
method. This will close
the socket and release all resourcesCopyright © 2018. All rights reserved.