Interprocess Communication as Implemented in BEAM-ish

How

BEAM-ish uses UNIX sockets to facilitate the transfer of information between two or more instances of BEAM-ish. The sockets are created in the directory specified by in the beamish.ini file.

Details

Communication of all messages occurs as a two step transaction first an instance initiates a message then it receives a reply. Messages are composed of two main parts. The first segment is the header which is followed by an optional body. The header is broken down as follows. The first line of the header contains a command token pair. Following the command token pair are optional lines consisting of variable=value pairs. The only guaranteed parameter in the header other than the command token pair is the ExtraLength parameter which contains the length of the body of the message in bytes.

The messages themselves are sent in plain text. This may not be the fastest transmission method but it is much easier to debug when problems arise.

The header is separated from the body by a blank line.

Summary of Command Token Pairs

Command: Ping

Token: Hello

This message is sent to every socket a new instance of BEAM-ish finds to announce it presence and ability to accept information. It is used by other instances to adjust their internal lists of available instances.

Token: GoodBye

This message is sent to every socket an exiting instance of BEAM-ish finds to announce that it will no longer be able to accept information. It is used by other instances to adjust their internal lists of available instances.

Token: Pong

This message is sent as a reply to a Ping when it is interpreted successfully.

Command: Request

Token: ProjectName

This message is sent when one instance needs to know the name of the currently opened project on another instance

Token: HKLList

This message is sent when one project need the list of reflection ids and h k l values to perform processing related to looking for symmetry related reflections.

Command: Update

Token: ImageOverlaySettings

This message is how a version of BEAM-ish behaving as a master orders the slaves to adjust various image settings that the user has changed. Multiple settings can be adjusted in just one message. They include things like the settings for the zoom window, reflection overlay, filtering, etc...

Token: SelectedReflection

This message is used to tell a remote version of BEAM-ish which reflection to select on its screen. It is useful when studying symmetry related reflections.

Token: HKLList

This message is used to tell a remote version of BEAM-ish that it needs to update reflection parameters with these new ones. The is used to update symmetry related reflection data after it is processed in a central location.

Token: ProjectList

This message is used to tell a remote version of BEAM-ish that it needs to update its recent project list because another instance had to modify the beamish.ini file with more recent information.

Command: Clear

Token: HKLList

This message is used to tell a remote version of BEAM-ish that it should reset the information stored on symmetry related reflections.

Command: Append

Token: MasterReport

This message is used to tell an instance of BEAM-ish that it should append its information related to reflections into a master file.

The following tokens apply to all commands

Token: Ok

This is used in a reply to indicate that the command was processed successfully.

Token: Error

This is used in a reply to indicate that the command was valid but that the token did not exist or could not be operated on.

Command: Error

The command is issued as a reply when the command could not be interpreted as valid.

Other commands and tokens will be added as they are needed.