` | err As `RuntimeException` | |
## Property descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.BytesAvailable
**BytesAvailable** As `Integer`
> The number of bytes of data are available in the internal receive buffer.
>
> This property is read-only.
>
> ``` xojo
> TextField1.Text = Me.BytesAvailable.ToString
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.BytesLeftToSend
**BytesLeftToSend** As `Integer`
> The number of bytes left in the queue remaining to be sent.
>
> This enables you to create a synchronous socket without needing to subclass it.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Handle
**Handle** As `Integer`
> This is the IPCSocket's internal descriptor and it can be used with `Declare` statements.
>
> The descriptor is platform-specific. If *Handle* is less than zero, the descriptor is not available.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.IsConnected
**IsConnected** As `Boolean`
> Returns `True` if connected to another application.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> ' 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
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Close
**Close**
> Closes the connection. Call Close when you want to terminate the session.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Connect
**Connect**
> Attempts to make the connection using the specified *Path*.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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`:
>
> ``` xojo
> Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
>
> If f <> Nil Then
>
> Var textInput As TextInputStream
> Var rowFromFile, oneCell As String
>
> 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`.
>
> ``` xojo
> Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
>
> If readFile <> Nil Then
>
> Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
> Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
>
> ReadStream.LittleEndian = True
>
> 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
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> mySocket.Write("you typed: ")
> mySocket.Write(key)
> mySocket.Write(".")
> mySocket.Flush
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Listen
**Listen**
> Listens for a connection.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
>
> ``` xojo
> TextArea1.AddText(listener.Lookahead)
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Poll
**Poll**
> Manually polls the socket.
>
> The following example polls the IPCSocket.
>
> ``` xojo
> IPCSocket1.Poll
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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`.
>
> ``` xojo
> 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
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Write
**Write**(Text As `String`)
> Writes the passed *Text* 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.
>
> ``` xojo
> Var f As FolderItem = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
>
> If f <> Nil Then
>
> Var stream As BinaryStream
>
> stream = BinaryStream.Create(f, True)
> stream.Write(TextArea1.Text)
> stream.Close
>
> End If
> ```
## Event descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Connected
**Connected**
> Executes when the connection is established with the server.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
IPCSocket.Error
**Error**(err As `RuntimeException`)
> An error occurred. Examine the value of the ErrorNumber and Message properties of the RuntimeException to determine which error occurred.
## Interfaces
This 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:
``` xojo
'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:
``` xojo
MyIPCSocket.Path = SpecialFolder.Temporary.Child("com.mydomain.appname.socket").NativePath
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The Connect button calls the Connect method and disables itself and the Listen button:
``` xojo
IPCSocket1.Connect
Me.Enabled = False
ListenButton.Enabled = False
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The Listen button calls the Listen method and disables itself and the Connect button.
``` xojo
IPCSocket1.Listen
Me.Enabled = False
ConnectButton.Enabled = False
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The Close button calls the Close method to close the connection:
``` xojo
IPCSocket1.Close
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The KeyDown event handler for the `TextArea` is:
``` xojo
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:
``` xojo
ListBox1.AddRow("Connected")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Its DataAvailable event handler is:
``` xojo
ListBox1.AddRow("DataRecieved: " + Me.ReadAll)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Its Error event handler is:
``` xojo
ListBox1.AddRow("Error: " + e.ErrorNumber.ToString)
```
## Compatibility
| | |
|-----------------------|-----------------------|
| **Project Types** | Console, Desktop, Web |
| **Operating Systems** | All |
`Object` parent class; `SocketCore`, `TCPSocket` classes.