TCPSocket → SocketCore → Object

EasyTCPSocket Class

Communicates with remote REALbasic applications with a proprietary protocol that is implemented over TCP. It is provided so that a user who is new to TCP/IP communications can use a higher-level class than the TCPSocket class to network their applications.

Events
Error
ReceivedMessage

Methods
SendMessage
WaitForConnection
WaitForMessage

# Notes

The DataAvailable event of the TCPSocket class is not available.

Even though you have access to the Write, Read and ReadAll methods of the TCPSocket 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.

# Class Constants

These constants indicate which error occurred. They are the same error codes returned by SocketCore. When an Error event occurs, check the value of the passed parameter Code against these class constants.

Error Code | Class Constant
--- | ---
100 | OpenDriverError
102 | LostConnection
103 | NameResolutionError
105 | AddressInUseError
106 | InvalidStateError
107 | InvalidPortError
108 | OutOfMemoryError

If you are subclassing a EasyTCPSocket, 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.

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 string data is actually a memory block containing a FolderItem. Or, you could define ID 101 as the 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 just make up a miscellaneous command ID and send your arbitrary data.

Command ID's 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.

The EasyTCPSocket class allows you to establish connections and communicate via the TCP protocol with a remote machine. The main difference between the EasyTCPSocket class and the regular TCPSocket class is the message-based aspects of the protocol. The connection process is identical to a regular TCPSocket. However, when you want to send data to a remote machine you must use the SendMessage method to do so.

When you receive data, you are not given a DataAvailable event, as is you are for TCPSocket. Instead, the entire message is passed to you via the ReceivedMessage event. Because of this, we do not allow you to read in arbitrary data using the Read or ReadAll methods of the TCPSocket class.When you receive a message sent via this protocol, you handle it via the ReceivedMessage event handler.

For synchronous communications, there is a WaitForConnection method which will synchronously wait a predetermined amount of time for a connection to be established. If the connection is made, it returns True, otherwise, it returns False.

REALbasic calls the DoEvents method of the Application class internally so that your application's user interface will remain responsive during this call. For synchronous communications, use the WaitForMessage method. This method waits for a message to come in with the command ID you specify. Once that message comes in, it will return the string data portion of that message. If a message comes in with a command ID that is different from the one you are expecting, it will drop that message. This method also internally calls the DoEvents method of the Application class, so your user interface will stay responsive.

The EasyTCPSocket class is designed only for easy communication among REALbasic applications on the network. It isn't designed to be the basis for custom TCP-based communication protocols. It works only for other applications that implement the EasyTCPSocket protocol.

# Examples

Connecting to the network. This example uses an EasyTCPSocket named "Connector".

Connector.Address = "localhost"
Connector.Port =1270
Connector.Connect

Listening for a message. This example uses an EasyTCPSocket named "Listener".

Listener.Port = 1270
Listener.Listen

Sending a message. This example uses the EasyTCPSocket named "Connector". EditField2 contains the value of the Command parameter and EditField3 the text of the message.

Connector.SendMessage( Val(EditField2.Text), EditField3.Text)

# See Also

AutoDiscovery, EasyUDPSocket, TCPSocket classes.