From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Class (inherits from SocketCore)

Used for UDP (User Datagram Protocol) communications.

DataAvailable Error SendComplete
BroadcastAddress fa-lock-32.png NetworkInterface RouterHops
Handle fa-lock-32.png PacketsAvailable fa-lock-32.png SendToSelf
IsConnected fa-lock-32.png PacketsLeftToSend fa-lock-32.png
LocalAddress fa-lock-32.png Port
Close LeaveMulticastGroup Read
Connect Poll Write
JoinMulticastGroup Purge Write


For a more detailed example, refer to the example project: Example Projects/Communication/Internet/UDPExample.

You do not need to add a UDPSocket control to a window in order to use it. Since it is not a subclass of Control, you can instantiate it via code.

The User Datagram Protocol, or UDP, is the basis for most high speed, highly distributed network traffic. It is a connectionless protocol that has very low overhead, but is not as secure as TCP. Since there is no connection, you do not need to take nearly as many steps to prepare when you wish to use a UDPSocket.

In order to use a UDPSocket, it must be bound to a specific port on your machine. This is done using the Connect method of the SocketCore class. Once the bind has occurred, the UDPSocket is ready for use. It will immediately begin accepting any data that it sees on the port it has bound to. It also allows you to send data out, as well as set UDP socket options (which will be described later).

In order to differentiate between which machine is sending you what data, a UDPSocket uses a data structure known as a Datagram. A Datagram consists of two parts, the IP address of the remote machine that sent you the data, and the payload - or the actual data itself. When you attempt to send data out, you must specify information in the form of a Datagram. This information is usually the remote address of the machine you want to receive your packet, the port it should be sent to, and the data you wish to send the remote machine.

UDP sockets can operate in various modes, which are all very similar, but have vastly different uses. The mode that most resembles a TCP communication is called "unicasting." This occurs when the IP address you specify when you write data out is that of a single machine. An example would be sending data to www.example.com, or some other network address. It is a Datagram that has one intended receiver.

The second mode of operation is called "broadcasting." As the name implies, this is a broadcasted write. It is akin to yelling into a megaphone. Everyone gets the message, whether they want to or not. If the machine happens to be listening on the specific port you specified, then it will receive the data on that port. This type of send is very network intensive. As you can imagine, broadcasting can amount to huge amount of network traffic. The good news is, when you broadcast data out, it does not leave your subnet. Basically, a broadcast send will not leave your network to travel out into the world. When you want to broadcast data, instead of sending the data to an IP address of a remote machine, you specify the broadcast address for your machine. This address changes from machine to machine, so use the BroadcastAddress property of the UDPSocket class which tells you the correct broadcast address.

The third mode of operation for UDP sockets is "multicasting." It is a combination of unicasting and broadcasting that is very powerful and practical. Multicasting is a lot like a chat room: you enter the chatroom, and are able to hold conversations with everyone else in the chatroom. When you want to enter the chatroom, you call JoinMulticastGroup, and you only need to specify the group you wish to join. The group parameter is a special kind of IP address, called a Class D IP. They range from to Think of the IP address as the name of the chatroom. If you want to start chatting with two other people, all three of you need to call JoinMulticastGroup with the same Class D IP address specified as the group. When you wish to leave the chatroom, you only need to call LeaveMulticastGroup, and again, specify the group you wish to leave. You can join as many multicast groups as you like, you are not limited to just one at a time. When you wish to send data to the multicast group, you only need to specify the multicast group's IP address. All people who have joined the same group as you will receive the message.

Multicasting has some extra features that make it an even more powerful utility for network applications. If you wish to receive the data you sent out with a multicast send, you can set the SendToSelf property (also known as loopback) of the UDPSocket. If it is set to True, then when you do a send (to a multicast group) you will get that data back. You can also set the number of router hops a multicast datagram will take (also known as the Time to Live). When your Datagram gets sent out, it runs through a series of routers on the way to its destinations. Every time the Datagram hits a router, its RouterHops property gets decremented. When that number reaches zero, the Datagram is destroyed. This means you can control who gets your datagrams with a lot more precision. There are some "best guesses" as to what the value of RouterHops should be.

Value Description
0 Same host
1 Same subnet
32 Same site
64 Same region
128 Same continent
255 Unrestricted

Note that if your Datagram runs through a router that does not support multicasting, it is killed immediately.

Due to the connectionless functionality of UDP, it does not make any guarantees that your data will reach its destination. You can work around this by creating your own protocol on top of the UDP protocol which acknowledges receives.

The UDPsocket operates in asynchronous mode, but the Connect method works synchronously. If the connect fails, you will get an error event immediately, and the IsConnected property will be set immediately.

Xojo Cloud

Web apps running on Xojo Cloud first have to use the FirewallPort class to open the port used to permit external or internal connections to UDP.


All project types on all supported operating systems.

See Also

Datagram, EasyUDPSocket, SocketCore classes.