Used for interprocess communication between two applications on the same computer. Use TCPSocket for interprocess communication between applications on different computers.
Encoding As TextEncoding = Nil
Count As Integer, [Enc As TextEncoding]
[Encoding As TextEncoding]
Data As String
e As RuntimeException
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
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.
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.
IsConnected As Boolean
Returns True if connected to another application.
This property is read-only.
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
Closes the connection. Call Close when you want to terminate the session.
Attempts to make the connection using the specified Path.
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
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
Listens for a connection.
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.
Manually polls the socket.
The following example polls the IPCSocket.
Read(Count As Integer, [Enc As TextEncoding]) As String
Reads Count bytes from the input stream and returns a String.
If provided, the optional parameter Enc specifies the text encoding to be defined for the String to be read.
If Count 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
ReadAll([Encoding As TextEncoding]) 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.
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
Executes when the connection is established with the server.
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.
Error(e As RuntimeException)
An error occurred. Examine the value of the ErrorNumber and ErrorMessage properties of the RuntimeException to determine which error occurred.
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.
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.
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:
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:
Its DataAvailable event handler is:
ListBox1.AddRow("DataRecieved: " + Me.ReadAll)
Its Error event handler is:
ListBox1.AddRow("Error: " + e.ErrorNumber.ToString)
All project types on all supported operating systems.
Object parent class; SocketCore, TCPSocket classes.