Simple one-way IPC protocol

The SimpleIPC unit provides classes to implement a simple, one-way IPC mechanism using string messages. It provides a component for the server, and a component for the client. The components are cross-platform, and should work both on Windows and unix-like systems.

The Unix implementation of the SimpleIPC unit uses file-based sockets. It will attempt to clean up any registered server socket files that were not removed cleanly.

It does this in the unit finalization code. It does not install a signal handler by itself, that is the task of the programmer. But program crashes (access violations and such) that are handled by the RTL will be handled gracefully.

This also means that if the process is killed with the KILL signal, it has no chance of removing the files (KILL signals cannot be caught), in which case socket files may remain in the filesystem.

TComponent definition. Exception support and formatting support Current version of the messaging protocol Unknown message type String message type For backwards compatibility TMessageType is provided for backward compatibility with earlier versions of the simpleipc unit. Message header record TMsgHeader is used internally by the IPC client and server components to transmit data. The Version field denotes the protocol version. The MsgType field denotes the type of data (mtString for string messages), and MsgLen is the length of the message which will follow. Version number Message data type Message length Internal message communication component

TIPCServerComm is an abstract component which implements the server-side communication protocol. The behaviour expected of this class must be implemented in a platform-dependent descendent class.

The class does not implement the messaging protocol by itself. Instead, it creates an instance of a (platform dependent) descendent of TIPCServerComm which handles the internals of the commnication protocol.

The client side of the messaging protocol is handled by the component. The descenent components must always be implemented in pairs.

Create a new instance of the communication handler Create initializes a new instance of the communication handler. It simply saves the AOwner parameter in the Owner property. Owner TSimpleIPCServer instance for which to handle transport TSimpleIPCServer instance for which to handle transport Owner refers to the instance for which this instance of TSimpleIPCServer handles the transport. It is specified when the TIPCServerComm is created. Start the server-side of the communication channel

StartServer sets up the server-side of the communication channel. After StartServer was called, a client can connect to the communication channel, and send messages to the server.

It is called when the property of the instance is set to True.

In case of an error, an exception is raised. Stop the server side of the communication channel.

StartServer closes down the server-side of the communication channel. After StartServer was called, a client can no longer connect to the communication channel, or even send messages to the server if it was previously connected (i.e. it will be disconnected).

It is called when the property of the instance is set to False.

In case of an error, an exception is raised. See if a message is available.

PeekMessage can be used to see if a message is available: it returns True if a message is available. It will wait maximum TimeOut milliseconds for a message to arrive. If no message was available after this time, it will return False.

If a message was available, it can be read with the ReadMessage call.

ReadMessage True if a message was available. Number of milliseconds to wait for a message. Unique identifier for the communication channel. InstanceID returns a textual representation which uniquely identifies the communication channel on the server. The value is system dependent, and should be usable by the client-side to establish a communication channel with this instance. Unique identification of the channel Read message from the channel.

ReadMessage reads the message for the channel, and stores the information in the data structures in the Owner class.

ReadMessage is a blocking call: if no message is available, the program will wait till a message arrives. Use PeekMessage to see if a message is available.

Class reference for TIPCServerComm TIPCServerCommClass is used by to decide which kind of communication channel to set up. Ancestor for client/server simple IPC classes TSimpleIPC is the common ancestor for the and classes. It implements some common properties between client and server. Communication channel active Active can be set to True to set up the client or server end of the communication channel. For the server this means that the server end is set up, for the client it means that the client tries to connect to the server with ServerID identification. ServerID Unique server identification ServerID is the unique server identification: on the server, it determines how the server channel is set up, on the client it determines the server with which to connect. Active Simple IPC server component

TSimpleIPCServer is the server side of the simple IPC communication protocol. The server program should create a TSimpleIPCServer instance, set its ServerID property to a unique name for the system, and then set the Active property to True (or call StartServer).

After the server was started, it can check for availability of messages with the PeekMessage call, and read the message with ReadMessage.

Create a new instance of TSimpleIPCServer Create instantiates a new instance of the TSimpleIPCServer class. It initializes the data structures needed to handle the server side of the communication. Destroy Owner of the TSimpleIPCServer instance. Remove the TSimpleIPCServer instance from memory

Destroy stops the server, cleans up the internal data structures maintained by TSimpleIPCServer and then calls the inherited Destroy, which will remove the instance from memory.

Never call Destroy directly, use the Free method instead or the FreeAndNil procedure in SysUtils.

Create Start the server

StartServer starts the server side of the communication channel. It is called automatically when the Active property is set to True. It creates the internal communication object (a descendent) and activates the communication channel.

After this method was called, clients can connect and send messages.

Prior to calling this method, the ServerID property must be set.

If an error occurs a exception may be raised. Active ServerID StopServer Stop the server

StopServer stops the server side of the communication channel. It is called automatically when the Active property is set to False. It deactivates the communication channel and frees the internal communication object (a descendent).

Active ServerID StartServer Check if a client message is available.

PeekMessage checks if a message from a client is available. It will return True if a message is available. The call will wait for TimeOut milliseconds for a message to arrive: if after TimeOut milliseconds, no message is available, the function will return False.

If DoReadMessage is True then PeekMessage will read the message. If it is False, it does not read the message. The message should then be read manually with ReadMessage.

ReadMessage True if a client message is available. Number of milliseconds to wait for a message. Should the message be read or not ? Last message as a string.

StringMessage is the content of the last message as a string.

This property will contain valid data only after a succesful call to ReadMessage.

GetMessageData. Read the data of the last message in a stream

GetMessageData reads the data of the last message from and stores it in stream Stream. If no data was available, the stream will be cleared.

This function will return valid data only after a succesful call to ReadMessage. It will also not clear the data buffer.

StringMessage MsgData MsgType Stream to store message data in Last message type

MsgType contains the message type of the last message.

This property will contain valid data only after a succesful call to ReadMessage.

ReadMessage Last message data

MsgData contains the actual data from the last read message. If the data is a string, then StringMessage is better suited to read the data.

This property will contain valid data only after a succesful call to ReadMessage.

StringMessage ReadMessage Instance ID InstanceID is the unique identifier for this server communication channel endpoint, and will be appended to the ServerID property to form the unique server endpoint which a client should use. ServerID Global Is the server reachable to all users or not Global indicates whether the server is reachable to all users (True) or if it is private to the current process (False). In the latter case, the unique channel endpoint identification may change: a unique identification of the current process is appended to the ServerID name. ServerID InstanceID Event triggered when a message arrives OnMessage is called by ReadMessage when a message has been read. The actual message data can be retrieved with one of the StringMessage, MsgData or MsgType properties. StringMessage MsgData MsgType Internal client-side communication protocol

TIPCClientComm is an abstract component which implements the client-side communication protocol. The behaviour expected of this class must be implemented in a platform-dependent descendent class.

The class does not implement the messaging protocol by itself. Instead, it creates an instance of a (platform dependent) descendent of TIPCClientComm which handles the internals of the commnication protocol.

The server side of the messaging protocol is handled by the component. The descenent components must always be implemented in pairs.

Create a new instance of the TIPCClientComm Create instantiates a new instance of the TIPCClientComm class, and stores the AOwner reference to the instance for which it will handle communitation. It can be retrieved later using the Owner property. Owner TSimpleIPCClient instance for which communication must be handled. TSimpleIPCClient instance for which communication must be handled. Owner is the instance for which the communication must be handled. It cannot be changed, and must be specified when the TIPCClientComm instance is created. Connect to the server

Connect must establish a communication channel with the server. The server endpoint must be constructed from the ServerID and ServerInstance properties of the owning instance.

Connect is called by the call or when the Active property is set to True

Messages can be sent only after Connect was called succesfully.

If the connection setup fails, or the connection was already set up , then an exception may be raised. Active Disconnect Disconnect from the server

Disconnect closes the communication channel with the server. Any calls to SendMessage are invalid after Disconnect was called.

Disconnect is called by the call or when the Active property is set to False.

Messages can no longer be sent after Disconnect was called.

If the connection shutdown fails, or the connection was already shut down, then an exception may be raised. Active Connect Check if the server is running. ServerRunning returns True if the server endpoint of the communication channel can be found, or False if not. The server endpoint should be obtained from the ServerID and InstanceID properties of the owning component. True if the server communication channel endpoint can be reached. Send a message SendMessage should deliver the message with type MsgType and data in Stream to the server. It should not return until the message was delivered. If the delivery of the message fails, an exception will be raised. Type of message Message data Class reference for TIPCClientComm TIPCClientCommClass is used by to decide which kind of communication channel to set up. Simple IPC client component

TSimpleIPCClient is the client side of the simple IPC communication protocol. The client program should create a TSimpleIPCClient instance, set its ServerID property to the unique name for the server it wants to send messages to, and then set the Active property to True (or call Connect).

After the connection with the server was established, messages can be sent to the server with the SendMessage or SendStringMessage calls.

Create a new instance of TSimpleIPCClient Create instantiates a new instance of the TSimpleIPCClient class. It initializes the data structures needed to handle the client side of the communication. Destroy Owner of the instance Remove the TSimpleIPCClient instance from memory

Destroy disconnects the client from the server if need be, and cleans up the internal data structures maintained by TSimpleIPCClient and then calls the inherited Destroy, which will remove the instance from memory.

Never call Destroy directly, use the Free method instead or the FreeAndNil procedure in SysUtils.

Create Connect to the server

Connect connects to the server indicated in the ServerID and InstanceID properties. Connect is called automatically if the Active property is set to True.

After a successful call to Connect, messages can be sent to the server using SendMessage or SendStringMessage.

Calling Connect if the connection is already open has no effect.

If creating the connection fails, an exception may be raised. ServerID InstanceID Active SendMessage SendStringMessage Disconnect Disconnect from the server

Disconnect shuts down the connection with the server as previously set up with Connect. Disconnect is called automatically if the Active property is set to False.

After a successful call to Disconnect, messages can no longer be sent to the server. Attempting to do so will result in an exception.

Calling Disconnect if there is no connection has no effect.

If creating the connection fails, an exception may be raised. Active Connect Check if the server is running. ServerRunning verifies if the server indicated in the ServerID and InstanceID properties is running. It returns True if the server communication endpoint can be reached, False otherwise. This function can be called before a connection is made. Connect True if the server can be reached Send a message to the server SendMessage sends a message of type MsgType and data from stream to the server. The client must be connected for this call to work. In case an error occurs, or there is no connection to the server, an exception is raised. Connect SendStringMessage Message type Message data. Send a string message to the server SendStringMessage sends a string message with type MsgTyp and data Msg to the server. This is a convenience function: a small wrapper around the SendMessage method Same as for SendMessage. SendMessage Connect SendStringMessageFmt String message Message type Send a formatted string message SendStringMessageFmt sends a string message with type MsgTyp and message formatted from Msg and Args to the server. This is a convenience function: a small wrapper around the SendStringMessage method Same as for SendMessage. SendMessage Connect SendStringMessage Format string for message Arguments to format string with Message type. Server instance identification ServerInstance should be used in case a particular instance of the server identified with ServerID should be contacted. This must be used if the server has its GLobal property set to False, and should match the server's InstanceID property. ServerID GLobal InstanceID Error reporting exception EIPCError is the exception used by the various classes in the SimpleIPC unit to report errors. Default server communication class DefaultIPCServerClass is filled with a class pointer indicating which kind of communication protocol class should be instantiated by the class. It is set to a default value by the default implementation in the SimpleIPC unit, but can be set to another class if another method of transport is desired. Default client communication class DefaultIPCClientClass is filled with a class pointer indicating which kind of communication protocol class should be instantiated by the class. It is set to a default value by the default implementation in the SimpleIPC unit, but can be set to another class if another method of transport is desired. (it should match the communication protocol used by the server, obviously). Error message if server is not active Error message if client/server is active. Error message if client/server is not active.