Cynical Network Plugin
Download Cynical Network (Release Notes)
This plugin allows Indigo to make and receive network connections over the Internet. You may write text with actions. You may define events that fire when a particular text pattern is seen in a received line, using regular expressions. You may enable and disable these events dynamically so as to shape a conversation - all that without writing any Python or AppleScript code.
Only text-based TCP connections are currently supported. (This means no UDP and no binary streams. If you don't know what that means, don't worry about it.)
Overview
For each network connection you want to use, create either a TCP Out device if you want to originate it, or a TCP In device if you want to wait for an incoming connection. Choose your port numbers well. For TCP Out devices, you can either use an explicit Connect action to connect it, or you can check the Auto-connect configuration checkbox to ask Indigo to keep the connection up all the time. For TCP In devices, the connection will happen when someone asks for it.
Use Device State Change event triggers on these network devices to respond to the situation. Watch for connected to respond to the start of a connection, and for disconnected for the end - which may come because the other end has disconnected on you.
Use Send Text actions to send whole or partial text lines to a connected device. Use Recognized Input and Unrecognized Input triggers to respond to incoming text. Enable and disable individual triggers, using ordinary Indigo actions, to tailor the response to the state of your conversation. End connections with the Disconnect action.
Devices
The TCP Out and TCP In devices support TCP (stream) connections to or from some Internet service somewhere (which may be on your own computer). They differ only in how a connection is established; once connected, they behave exactly the same:
- The Send Text action sends text to the connection.
- The Disconnect action terminates the connection. If the remote end drops the connection, it terminates automatically.
- Use the Recognized Input and Unrecognized Input event triggers to respond to received lines of text.
- If you have specified a Last line read variable in the device configuration, you can always find the last line received there, for use in AppleScript or Python actions.
TCP Out
A TCP Out device is a way to make a TCP connection to some server out there. By default, it remains idle until a Connect action for it is executed, at which point it attempts to make the connection.
If the Auto-connect checkbox is enabled, this is automatically done whenever the connection is idle. In other words, an autoconnect device will continuously attempt to establish and maintain its connection. Note that applying the Disconnect action to an autoconnecting device will terminate the present connection but immediately attempt to establish a new one. The only way to stop an auto-connecting device from re-establishing its connection is to disable it.
TCP In
A TCP In device is Indigo's way of listening for some other program out there making a connection to Indigo. When a request for a connection is received, Indigo establishes the connection and handles it as described above. Only one connection can ever be active for each TCP In device; additional incoming requests are queued (within reason) and accepted when the present connection terminates.
Device States
The disconnected state is momentary; after a brief hesitation, the state will automatically move on - usually to idle or connecting. This state exists just so you can have a device state change trigger that fires whenever a connection ends, regardless of the circumstances.
Actions
Connect
Tells a TCP Out device to try and establish its connection. This does nothing (and produces an error message in the Indigo log) if the connection is not idle.
A persistent connection automatically performs a Connect whenever it is becoming idle.
Connect cannot be used on TCP In devices; they are connecting automatically in response to incoming connection requests as long as they are enabled.
Disconnect
Immediately disconnects a connected TCP Out or TCP In device. The device state becomes momentarily disconnected. The device then follows its normal progression:
- A TCP In device picks up the next waiting incoming connection. If there is none, it will wait for one to arrive.
- An ordinary TCP Out connection will become idle and wait until a Connect action tells it to connect again.
- A persistent TCP Out device will immediately attempt to re-establish the connection.
Disabling a device automatically disconnects it. If you want to finish an existing connection but then not allow subsequent ones, disable the device in a device state change trigger for the disconnected state.
Send Text
Send some text to a connected device. A full line is sent by automatically appending the device's line ending characters - see Line Endings. The partial checkbox defeats this completion and sends a partial line instead.
This action will fail (with an error message in the Indigo log) if the device state is not currently connected.
Events
Incoming text lines on a connected device trigger events you can use to take action. Recognized Input events can be configured with regular expressions to match particular input lines. They are only eligible for matching when they are enabled; you can conduct an entire network conversation by selectively enabling and disabling these event triggers based on the situation.
If you need to deal with arbitrary input, use Unrecognized Input events and read the actual line received from the Indigo variable configured for the device. This is also useful for handling unexpected error cases.
Recognized Input
A Recognized Input event applies to a particular TCP device. It specifies a regular expression. Whenever that device receives a complete line that matches this regular expression, the event fires and Indigo performs its actions. If you specified a variable in the device configuration, it will contain the line that triggered the event.
You can have any number of Recognized Input events for the same device, but they should all have distinct patterns that don't overlap. If an incoming text line matches multiple enabled pattern events, the system will pick a single one at random and trigger it; the others will not fire for that line.
Unrecognized Input
An Unrecognized Input event fires whenever a particular network device receives a complete text line that does not match any enabled Recognized Input triggers for that device. It acts as a catch-all to consume unexpected input. If you have no enabled Recognized Input triggers, each incoming line will be delivered this way. If you have multiple enabled triggers of this type for a device, they will all fire in some unspecified order. If you specified a variable in the device configuration, it will contain the line that triggered the event.
Line Endings
Cynical Network handles data one line at a time. The line ending configuration setting determines what separates lines. You can set this separately for each connection device.
To determine which line ending to use, consult the documentation for the protocol or device you connect to. Internet protocols usually use the CRNL or newline settings.
The null line ending means that lines
are separated by single bytes of zero value. This is unusual; you'll know if you need this.
The none line ending means that we're not really processing lines at all. The send text action does not append anything to outgoing text; and anything arriving from the remote partner is immediately matched as a line
and delivered accordingly, even if it is just a single character. Use this if you have to work with a protocol that is not line oriented. Happily, this is rare in practice.
Release Notes