Implementing multikit "invoked commands"

An "invoked command" is the command that is executed whenever a program - including a directory - is launched (usually by double-clicking). The name of this command is determined by the program's "invokedCmd" attribute.

An invoked command can be implemented in one of three ways

  1. As a built-in command. The current version of multikit automatically implements three invoked commands
  2. As a separate executable program
  3. As a script written in the Tcl scripting language
The latter two methods are described below.

Note: A built-in invoked command can be overridden by a Tcl script (or separate executable) for the same invoked command.

Invoked commands as separate executable programs

An invoked command "foo" can be implemented as a program named "foo" (with an appropriate extension - e.g., ".exe" - if you're running Windows). This program must reside in the same directory as multikit itself. (This is a security measure, to give the user control over the set of programs that might be executed when a multikit program is invoked.)

This program will be invoked with the following arguments:

  1. <Program Id>: multikit's identifier for this program. (This can be treated as just an opaque string.)
  2. <Internet Address>: The program's internet's address in "dotted quad" form (or the string "{}" if the program is not a channel).
  3. <Port>: The program's port number (or the string "{}" if the program is not a channel).
  4. <TTL>: The program's TTL (or the string "{}" if the program is not a channel).
  5. <Key>: The program's encryption key (currently, the string "nokey", or "{}" if the program is not a channel).
  6. The remaining arguments are attribute pairs: an even number of arguments - the first of each pair being an attribute name, and the second being its value.

    (These arguments may be 'quoted' using Tcl's quoting conventions. E.g., if an attribute value consists of more than one word, then it will be surrounded by curly braces.)

Note that the invoked command for a directory cannot, at present, be implemented as a separate program. Instead, a directory invoked command must be implemented as a Tcl script, as described below.

Invoked commands as Tcl scripts

For examples of these scripts, please see the following files (which were included in the multikit distribution, and should be present in the same directory as "multikit" itself): The script file for an invoked command "foo" must be named "foo.tcl", and, again, must reside in the same directory as "multikit" itself.

The invoked command proc

Each script file (for invoked command "foo") must contain a Tcl proc, also named "foo", with the same argument signature as described above: program id, internet address, port number, ttl, key, attribute-name-1, attribute-value-1, ..., attribute-name-N, attribute-value-N

"proc multikit_input"

If the invoked command is for a directory, then the script file should also contain a proc "multikit_input". This proc is called by multikit whenever the user adds a new program to the directory (or deletes a program from the directory). This proc takes the following arguments:
  1. <Participation Code>: A 1-letter code that indicates the way in which the new program should be 'announced' or 'shared' in the directory. The following codes are currently defined:
  2. <Incarnation>: A numeric string that indicates the 'freshness' of this announcement. This number is updated, by multikit, whenever the announcement is changed in some way - e.g., the attributes change, or an 'addition' (p or d participation code) turns into a 'deletion' (x participation code), or vice versa. Receiving nodes use the 'incarnation' in order to recognize (and reject) stale announcements.
  3. <TTL>: The TTL that should be used when announcing the new program on this directory. (This is not necessarily the same as the directory's TTL; it can be less, if the new program is a channel.)
  4. <Directory Id>: The id of the directory being added to (i.e., this one).
  5. The remaining arguments form a <program description> for the new program.

    A <program description> is defined as follows:

    Notes:

"proc multikit_cleanup"

If the invoked command is for a directory, then the script file should also contain a proc "multikit_cleanup". This proc is called by multikit whenever the directory is no longer needed (e.g., when no windows for the directory are being shown, and multikit is making no ongoing 'announcements' to the directory).

"multikit_cleanup" should reclaim any state that was previously created by the invoked command. In particular, if the invoked command had previously created a multicast socket (using "groupsock_create"), then "multikit_cleanup" should close it (by calling "groupsock_delete"). "multikit_cleanup" takes a single argument: <Directory Id>

Calling "multikit_output"

If the invoked command for a directory receives information, over the network, that announces a new program, refreshes or updates information about an existing program, or deletes a program (from a directory), then it should call "multikit_output", with arguments: <Participation Code> <Incarnation> <Directory Id> <program description>, each as described above. (multikit will then use this information to update its internal database.)

Notes:

Additional commands available to scripts

In addition to the usual Tcl commands, the following special commands are also available for use by invoked command scripts:

Querying the state of the local "multikit"

Updating the state of the local "multikit"

Miscellaneous routines

The "groupsock" library

This is a simple library for multicast datagram communication. The following new Tcl commands can be called from an invoked command script: Example: The following script listens to a multicast group, printing out data whenever it arrives: 

	set socket [groupsock_create 224.42.42.42 54321 15]
	fileevent $socket readable {puts [groupsock_read $socket]}

Note: Upon request, LIVE555.COM can provide special variants of the Tcl/Tk shells "tclsh" & "wish" that have the "groupsock" library built in. (These new shells are called "groupsock_tclsh" and "groupsock_wish".)

Customized directory views

Using an invoked command script for a directory, it is possible to create your own, customized, view(s) of this directory, instead of using the views ("itemized" or "positional") that are built into multikit.

A script for a customized directory view must contain a Tcl proc: 

proc multikit_createView {handle} {
    ...some customized code for showing the view...
}
multikit_createView is called - by multikit - whenever it requests a new, customized, view of this directory.

When this new view is later deleted, the script must then call the routine

where the <handle> parameter is the value that had earlier been passed to multikit_createView. (The <handle> is multikit's internal id for the view.) This call to multikit_deleteView is important. If it is omitted, multikit will think that the view is still active, and will remain running even after its last window has been deleted. (It is OK, however, to call multikit_exit before deleting a view. If you do this, then the view will be reinstated automatically when multikit is restarted.)

A script for a customized directory view can obtain its directory contents by periodically calling the multikit_listMembers routine, described earlier.

Notes

Return to the main multikit page