Class

IPCSocket

Description

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

Properties

Name	Type	Read-Only
BytesAvailable	Integer	✓
BytesLeftToSend	Integer	✓
Handle	Integer	✓
IsConnected	Boolean	✓
Path	String

Methods

Name	Parameters	Returns
Close
Connect
EndOfFile		Boolean
Flush
Listen
Lookahead	encoding As TextEncoding = Nil
Poll
Read	byteCount As Integer, encoding As TextEncoding = Nil	String
ReadAll	encoding As TextEncoding = Nil	String
Write	Data As String

Events

Name	Parameters	Returns
Connected
DataAvailable
Error	e As RuntimeException

Property descriptions

IPCSocket.BytesAvailable

BytesAvailable As Integer

The number of bytes of data are available in the internal receive buffer.

This property is read-only.

TextField1.Text = Me.BytesAvailable.ToString

IPCSocket.BytesLeftToSend

BytesLeftToSend As Integer

The number of bytes left in the queue remaining to be sent.

This property is read-only.

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

IPCSocket.Handle

Handle As Integer

This is the IPCSocket's internal descriptor and it can be used with Declare statements.

This property is read-only.

The descriptor is platform-specific. If Handle is less than zero, the descriptor is not available.

IPCSocket.IsConnected

IsConnected As Boolean

Returns True if connected to another application.

This property is read-only.

IPCSocket.Path

Path As String

Path to a directory that you have write access to, followed by the name chosen for your socket (maximum of 103 characters).

Use FolderItem to assign the proper path type for all platforms. On Windows, this is an absolute path, e.g. "C:TempmySocketName", while on Linux and macOS it is a POSIX (Unix) path, e.g. "/var/tmp/mySocketName".

The name and path can be chosen arbitrarily. Ideally, the path should be a private folder you have full control over or, preferably, the system's temporary items folder.

If you choose a folder you share with other applications, such as the temp folder, you need to ensure that the socket file name is unique to avoid conflicts with other applications that might want to place files into the temp folder as well. Therefore, use a name specific to both you and your application. On macOS, the application bundle identifier, made up from a domain name owned by you, is a good technique. .. warning:: If you use SpecialFolder.Temporary to create the IPCSocket file, then the name of the file cannot be the same name as a Mutex (as it also uses that folder).

Also, if one app invokes the other, the first app could create a random file name and pass its path to the other app. Keep in mind that you may end up with lots of socket files in that folder this way, unless you make sure to delete them after you stop using the IPC socket, as the files don't get deleted automatically (however, macOS and Linux clear up the temp folder upon system restart, so that's one reason why using that folder is recommended).

Here's an example for a fairly safe generation of the socket path:

' Replace myEmail and emailDomain.xyz with the parts from your email address,
' and replace myAppName with you app's Name:
Var chosenName As String = "myEmail.emailDomain.xyz.myAppName.socket"
Var chosenFolder As FolderItem = SpecialFolder.Temporary
IPCSocket1.Path = chosenFolder.Child(myAppName).NativePath

Method descriptions

IPCSocket.Close

Close

Closes the connection. Call Close when you want to terminate the session.

IPCSocket.Connect

Connect

Attempts to make the connection using the specified Path.

IPCSocket.EndOfFile

EndOfFile As Boolean

Returns True when there's no more data left to read.

This code reads the rows and columns of data from a tab-delimited text file into a ListBox:

Var f As FolderItem
Var textInput As TextInputStream
Var rowFromFile, oneCell As String

f = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
If f <> Nil Then
  textInput = TextInputStream.Open(f)
  textInput.Encoding = Encodings.UTF8

  Do
    rowFromFile = textInput.ReadLine
    Var values() As String = rowFromFile.ToArray(String.Chr(9))
    ListBox1.ColumnCount = values.Count
    ListBox1.AddRow("")
    Var col As Integer
    For Each value As String In values
      ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, col) = value
      col = col + 1
    End For
  Loop Until textInput.EndOfFile

  textInput.Close
End If

This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box. The EOF property is used to terminate the Do...Loop.

Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
If readFile <> Nil Then
  Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
  ReadStream.LittleEndian = True
  Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
  If writeFile <> Nil Then
    Var writeStream As BinaryStream = BinaryStream.Create(writeFile, True)
    writeStream.LittleEndian = True
    Do Until ReadStream.EndOfFile
      writeStream.WriteInt8(ReadStream.ReadInt8)
    Loop
    writeStream = Nil
  End If
  readStream = Nil
End If

IPCSocket.Flush

Flush

Immediately sends the contents of internal write buffers to disk or to the output stream.

This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.

When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.

Avoid calling this method too often. For example, do not call it between successive Write calls because you'll slow down performance without getting much benefit.

A typical use case would look like this:

mySocket.Write("you typed: ")
mySocket.Write(key)
mySocket.Write(".")
mySocket.Flush

IPCSocket.Listen

Listen

Listens for a connection.

IPCSocket.Lookahead

Lookahead(encoding As TextEncoding = Nil)

Returns a String, containing the data that is available in the internal queue without removing it.

The optional encoding parameter enables you to specify the text encoding of the data to be returned. The default is Nil. Use the Encodings module to specify an encoding.

This example adds the contents of the internal queue to a TextArea. The Listener IPCSocket has been added to the window.

TextArea1.AppendText(listener.Lookahead)

IPCSocket.Poll

Poll

Manually polls the socket.

The following example polls the IPCSocket.

IPCSocket1.Poll

IPCSocket.Read

Read(byteCount As Integer, encoding As TextEncoding = Nil) As String

Reads byteCount bytes from the input stream and returns a String.

If provided, the optional parameter encoding specifies the text encoding to be defined for the String to be read.

If byteCount is higher than the amount of bytes currently available in the stream, all available bytes will be returned. Therefore, make sure to always consider the case that you get less than you requested. To see if you received all requested bytes, check the returned string's String property (avoid using Length as it may give a different number if the encoding is not nil).

If not enough memory is available, you get back an empty string.

This example reads the first 1000 bytes from a BinaryStream.

Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text/plain")
If readFile <> Nil Then
  Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
  ReadStream.LittleEndian = True
  TextArea1.Text = ReadStream.Read(1000, Encodings.UTF8)
End If

IPCSocket.ReadAll

ReadAll(encoding As TextEncoding = Nil) As String

Reads all the data from the internal buffer.

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.

IPCSocket.Write

Write(Data As String)

Writes the passed data to the output stream.

Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the Flush method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the Flush method to reduce latencies that this buffering may cause in such cases.

If Write fails, an IOException will be raised.

This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.

Var f As FolderItem
Var stream As BinaryStream
f = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
If f<> Nil Then
  stream = BinaryStream.Create(f, True)
  stream.Write(TextArea1.Text)
  stream.Close
End If

Event descriptions

IPCSocket.Connected

Connected

Executes when the connection is established with the server.

IPCSocket.DataAvailable

DataAvailable

Occurs when additional data has come into the internal receive buffer.

It is your responsibility to read the data from the buffer using Read or ReadAll methods.

IPCSocket.Error

Error(e As RuntimeException)

An error occurred. Examine the value of the ErrorNumber and ErrorMessage properties of the RuntimeException to determine which error occurred.

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

Sample code

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 Buttons 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 macOS) 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.Text)
  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: " + e.ErrorNumber.ToString)

Compatibility

All project types on all supported operating systems.

IPCSocket

Description

Properties

Methods

Events

Property descriptions

Method descriptions

Event descriptions

Interfaces

Notes

Performance

Sample code

Compatibility

See also