EasyTCPSocket

From Xojo Documentation
Jump to: navigation, search

Class (inherits from TCPSocket)

Communicates with remote Xojo 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
Connected Error SendComplete
DataAvailable ReceivedMessage SendProgress


Properties
Address IsConnected ReadOnlyProperty.png Port
BytesAvailable ReadOnlyProperty.png LastErrorCode ReadOnlyProperty.png RemoteAddress ReadOnlyProperty.png
BytesLeftToSend ReadOnlyProperty.png LocalAddress ReadOnlyProperty.png
Handle ReadOnlyProperty.png NetworkInterface


Methods
Close Lookahead SendMessage
Connect Poll WaitForConnection
Disconnect Purge WaitForMessage
EOF Read Write
Flush ReadAll WriteError
Listen ReadError

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

Interfaces

The EasyTCPSocket class implements the Readable and Writeable class interfaces.

Notes

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.

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. Use the Super keyword.

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 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.

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.

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.

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

See Also

AutoDiscovery, EasyUDPSocket, TCPSocket, UDPSocket classes.

Personal tools
Namespaces

Variants
Actions
Main
Content
Starting Out
Dig Deeper
More Help
Toolbox
About