From Xojo Documentation

Revision as of 18:56, 19 November 2009 by WikiSysop (talk) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Used for UDP (User Datagram Protocol) communications.

Super Class

SocketCore class.


Name Type Description
String The machine's broadcast address.

You can specify this address when you call the Write method and the data will be broadcast across the network, but you will not receive the data you sent back.

Integer The number of packets available in the internal receive buffer.
Introduced 5.5
Integer The number of packets left in the queue to send.

This enables you to create a synchronous socket without needing to subclass the UDPSocket.

RouterHops Integer Specifies how many router hops the data sent out can make.

This is also known as the Time To Live (or TTL).

SendToSelf Boolean Specifies whether the data you send out will be sent to yourself as well.

This is also known as loopback. This property applies only to multicast sends. Setting the SendToSelf property to True may not work on all versions of Windows. MSDN states that the SendToSelf property on NT 4 cannot be turned off. A multicasting socket will always receive the data it sends out.


Name Parameters Return Type Description
JoinMulticast Group Group as String Boolean Attempts to join the specified multicast group.

Returns a Boolean. If the socket successfully joined, it returns True. You can join as many multicast groups as you'd like. The Group parameter specifies a ClassD IP address in the range: to

LeaveMulticastGroup Group as String Leaves the specified multicast group.
Read [Encoding as TextEncoding]
Introduced 5.2
Datagram Returns a Datagram from the internal receive buffer.

The address property of the Datagram is the remote address from which the data was sent. The optional Encoding parameter enables you to specify the text encoding of the data to be returned. Use the Encodings module to specify a text encoding.

Write Data as DataGram Writes the data to the specified address.
Write Address as String,

Data as String

Constructs a Datagram and sends the data to the specified address.

If the address is part of a multicast group, all members of the group will get the data. If the address is the broadcast address, everyone on the network will get the data. If the address is an IP address, the data is unicast to that address only.


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.realsoftware.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 REALbasic provides a 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.

See Also

Datagram, EasyUDPSocket, SocketCore classes.