Xojo Documentation Xojo Documentation

Class (inherits from Object)

Used for interprocess communication between two applications on the same computer. Use TCPSocket for interprocess communication between applications on different computers.

Events

Connected DataAvailable Error

Properties

BytesAvailable Handle Path BytesLeftToSend IsConnected

Methods

Close Listen ReadAll Connect LookAhead Write EndOfFile Poll Flush Read

Interfaces

The IPCSocket class implements the Readable and Writeable class interfaces.

Notes

IPCSocket works similarly to a regular TCPSocket, but instead of using an IP address and Port number, a local file path is used, leading to a so-called socket file. The same path must used on both ends of the connection, and it should preferrably be a unique file location inside a temporary folder that's not usually visible to the user. The file might remain in existance even after closing the connection, so you should delete any leftover files from previous connections when you make a new connection.

To connect, first one side must invoke Listen after having set the Path. Then the other can connect to the socket file using the Connect method.

To terminate the connection, call the Close method. This will invoke the Error event on the other end, with its RuntimeException.ErrorNumber set to 102.

Performance

The time between the message being sent and the DataAvailable being fired can be as low as 350 microseconds but it varies considerably depending on the type of your application (GUI or Console), what is currently happening on your system, accesses to your hard drive...

For GUI applications, it may take more than 80000 microseconds (80 milliseconds). If your application needs high performance (low latency) exchanging data over a socket, consider these optimizations:

• Call the Flush method to push out written data without further delay.
• Use a Timer with a very low Period value, e.g. 1, to call the Poll method in order to have the DataAvailable event fire as quickly as possible after receiving new data. The Timer can be anywhere in your app, as long as it's active and in continuous mode. Keep in mind that such a fast firing Timer will raise the CPU consumption of your application significantly, though. Fine-tune this adequately.

IPCSockets used in a Console application react faster than in a GUI application, most notably because there is no event loop to take care of the graphical interface and user events. In the following code:

// In the Run event of a Console application
Do
App.DoEvents n // n = 10 or 1
Loop

When n=10, the maximum latency was 20000 microseconds (20 ms). When n=1, the maximum latency was almost 10 times less (2500 microseconds) but the CPU time consumption raised to 3-4%. Compare the values to those given for a GUI application above. The "App.DoEvents" line does the polling of the IPCSocket.

Note: The values given will vary on your systems.

Examples

The following example establishes communications with another copy of the application. The main window has a ListBox for displaying information sent by the other copy of the application, status information, and error messages. There are PushButtons for listening, connecting, and for closing the connection. There is a TextArea that you use to enter the messages that you send to the other instance of the application. It sends the contents of the TextArea when the TextArea has the focus and the Enter key (Return on Macintosh) is pressed. An IPCSocket has been added to the window.

Before two ends can connect, they both need to set their path to the same location, using a unique name, e.g. like this:

MyIPCSocket.Path = SpecialFolder.Temporary.Child("com.mydomain.appname.socket").NativePath

The Connect button calls the Connect method and disables itself and the Listen button:

IPCSocket1.Connect

Me.Enabled = False
ListenButton.Enabled = False

The Listen button calls the Listen method and disables itself and the Connect button.

IPCSocket1.Listen
Me.Enabled = False
ConnectButton.Enabled = False

The Close button calls the Close method to close the connection:

IPCSocket1.Close

The KeyDown event handler for the TextArea is:

If Key = Chr(13) Or Key = Chr(3) Then // Return or Enter pressed?
IPCSocket1.Write(Me.Value)
IPCSocket1.Flush // makes sure the data gets sent without delay
Return True
End If
Return False

The event handlers for the IPCSocket have code that populate the Listbox. Its Connected event handler is:

ListBox1.AddRow("Connected")

Its DataAvailable event handler is:

ListBox1.AddRow("DataRecieved: " + Me.ReadAll)

Its Error event handler is:

ListBox1.AddRow("Error: " + Str(e.ErrorNumber))

To run the example, launch two copies of the application. In one instance of the application, click the Listen button. Then click the Connect button in the other instance of the application. You should get the message "Connected" in the ListBoxes. Then you can send messages via the TextField.

See Also

SocketCore, TCPSocket classes.