EasyUDPSocket

From Real Software Documentation

Supports communication via the UDP protocol using unicasting, multicasting, or broadcasting. It provides a simple "wrapper" around the UDPSocket class that makes easier for beginners to get started with UDP networking.

Events

DataAvailable ReceivedMessage Error SendComplete Error

Properties

BroadcastAddress LocalAddress Port Handle NetworkInterface RouterHops IsConnected PacketsAvailable SendToSelf LastErrorCode PacketsLeftToSend

Methods

Bind Read Close Register Connect SendMessageToGroup JoinMulticast Group SendMessageToIndividual LeaveMulticastGroup Unregister Poll Write Purge Write

Even though you have access to the Write and Read methods of the UDPSocket class, you should never call them. Doing so will cause a RuntimeException to be raised (with an appropriate message set). This is so the internal protocol is enforced.

Notes

If you are subclassing a EasyUDPSocket, you must call the Super class’s constructor in your own subclass’s constructor. The subclass will not work or exhibit “strange” behavior unless this is done. Use the Super keyword for this.

The DataAvailable event of the UDPSocket class is not available.

The EasyUDPSocket class provides a simple “wrapper” around the UDPSocket class that makes easier for beginners to get started with UDP networking. With the EasyUDPSocket class, you can send messages either to an individual or to an entire group. One main benefit to the EasyUDPSocket class is the way it handles multicasting. It’s a nuisance to look up which IP addresses can be used with multicasting.

The Command parameter can be used as a code to identify the type of data that is sent. For example, you could send a command ID of 100 to mean that the data is actually a memory block containing a FolderItem. Or, you could define ID 101 as the username of a remote application. This message mode is enforced on you in that you cannot use an arbitrary Write command. If you’d like to send arbitrary data, then you can make up a miscellaneous command ID and send your arbitrary data.

Command IDs less than 0 are reserved for internal use. When you are sending messages, you should not use a command ID less than 0, as it may very well cause issues with other classes.

To send a message to a group, you pass the group name that you have previously assigned to the group using the Register method. This means that you can pass “MyLocalGroup” as the parameter to the Register method and use that string for calls to SendMessageToGroup. To send a message to an individual, you need the IP address of the user&‘s computer in the SendMessageToIndividual method.

You can still pass a valid Class D IP address; Real Studio will use it. One other helper function is the Bind function. This sets up the socket for you properly (so you don’t have to set RouterHops or SendToSelf up yourself) and does the bind on the port specified.

One thing to keep in mind is that EasyUDPSocket defaults to having SendToSelf on. You are welcome to override this default yourself by setting SendToSelf to False after the making the Bind call. While you can still call [Join/Leave]MulticastGroup, we suggest that you only use Register and Unregister for your EasyUDPSocket application.

Examples

The EasyUDPSocket Example Project

The Examples folder that ships with Real Studio contains a simple example project that demonstrates the EasyUDPSocket. It establishes a two-machine group, lets you name the group, and send messages to the group or to each member of the group. The Layout Editor for the app is shown below.

The app creates two connections on the local machine. You first need to specify the Port. On Unix-based systems, you need to use a port number higher than 1024.

The first connection uses the port number you entered and increments it, so that the next bind does not attempt to use the same port.

Enter a name for the group. The join button is used to register the two connections.

The SendMessageToGroup can then be used to broadcast a message to both member.

The TextField3 field contains the message, TextField2 contains the command number, and TextField5 contains the goup name.

The Send button sends the message to either the first or second port numbers. It looks as the pair of radiobuttons to determine which port number to use.

The Wait button puts the app in a Waiting state until it receives a message. TextField4 is the TextArea for displaying the status message.

After clicking the Wait button, you should send a message.

The ReceivedMessage event displays a message in TextArea1 whenever the first port gets a message.

The Error event fires when an error occurs. It is passed the error code that is documented in the SocketCore class.

Other Examples

Binding to a port. TextField1 contains the user-specified port number:

Registering in a group. Everyone on the network should use the same name.

Sending a message to the group. TextField1 is the text of the message.

Sending a message to an individual in the group. The individual's IP address and port is passed as the first parameter. The second parameter is the value of the Command parameter and, TextField1 contains the text of the message.

Receiving a message in the ReceivedMessage event:

See Also

AutoDiscovery, SocketCore, UDPSocket classes.