Plug-ins and Helper Applications

Read-only and read-write helper applications

Some helper applications only read the file they get sent, whereas others modify it as well. Checkpoint Commander allows you to specify this for each helper application - where a helper application is known not to modify the file, Checkpoint Commander can handle the interaction more efficiently.

Fileful and fileless helper applications

Some helper applications must be launched with a file to process - they don't work properly without one. Others do not accept a file at all (less common but still possible). Others work either way.

Connecting to the file

The helper application needs to be given a reference to the file on its command line. Checkpoint Commander supports three mechanisms for this:

Straight file

The old-school way. The application accepts a filename. This was the only mechanism supported in earlier versions of Checkpoint Commander. This allows media players which support the feature to jump around within an individual track. Unfortunately, when used with XSPF for files which are in JAR / Zip containers or CPAs, this can cause a severe delay before the player starts up - Checkpoint Commander has to extract the entire playlist to the hard drive before playback can start. Unless you really need random access within tracks, or your player doesn't support it, you're better off with the HTTP URL mechanism.

File URL

Instead of a filename, the application accepts a file:// URL. This using a different "escaping" mechanism to cope with any awkward characters in the filename, such as spaces. If a helper application doesn't like files which have spaces in the filename, try using this mechanism instead. In particular, OpenOffice 2.0 appears to prefer this. The comments about media players and XSPFs under Straight file also apply here.

HTTP URL

Instead of providing a file directly, Checkpoint Commander passes an HTTP (Web) URL pointing to its internal browser interface. This is read-only. However, it is more secure, since no plaintext copy is required on disk while the file is being read. It also greatly reduces the latency (start-up delay) when launching the helper application against large files in CPAs, since the file doesn't need to be completely decrypted first. Finally, if the target file contains (relative) links to other files (as do, eg. web pages), those links will work, even if the target file is inside an archive or zip. What a deal. If the application supports it, and doesn't need to modify the target file, this mechanism is the one to go for. The one drawback is that you can't generally jump around within an individual file (track), only from one track to another (or right back to the beginning of the current track, usually). The player is effectively in "streaming" mode here.

[NOTE] For the curious: When an HTTP URL is used to access a file in a CPA, three alternative strategies are used depending on the file size. If it's small (by default, < 512K) it's buffered in memory and fed from there. If it's "medium" size, it's buffered to disk first. Finally, large files are streamed directly out of the CPA.

The definition of "medium" here is currently anything between 512K and 1M. This category exists because there's overhead involved in setting up for direct streaming; for these medium sized files there's less latency to buffer than there would be to stream directly. The on-disk buffers are encrypted using an ephemeral (random, throwaway) key. When Checkpoint Commander is terminated, the ephemeral key goes away with it. Thus, even if an attacker can recover the encrypted temporary file, she can't read it because the key is lost.

[NOTE] Files served out of JAR / ZIP archives are always extracted completely before reading. If you don't like the latency this introduces, we recommend transferring the files to a CPA.

[NOTE] One disadvantage of direct streaming is that if the data is corrupt, you won't find this out until it's finished streaming. However, data corruption is rare, and in any case a media stream can generally recover from a brief burst of garbage. Start-up delay, on the other hand, is annoying every single time. Therefore it's a good tradeoff.

Special option for XSPF files

In order to maximise the usefulness of the XSPF files which Checkpoint Commander uses, there is an extended option which only applies when the helper application is launched against an XSPF file.

Pre-process playlist (XSPF only)

If your helper application will execute this XSPF as a playlist, set this option. [If your application has fully conformant XSPF handling and is using HTTP URLs, you could turn this off, but it's mostly harmless so we recommend leaving it on for the sake of robustness.]

If your helper application will edit this XSPF, clear this option. [Putative applications which do both are not supported.]

Installing and managing helper applications

To install and manage helper applications, use the "Manage helper applications" option on the Tools menu. None are bundled with Checkpoint Commander - you add your own according to taste.

In the command-line which starts the viewer, the @ character is used as an "escape", for which Checkpoint Commander substitutes the name of the file (if any) which this viewer is supposed to view. To include a literal @ character in the command line, double it, thus @@.

You may encounter problems if the path to your viewer executable contains spaces. If this happens, try putting double-quote marks around the path, "like this".

Helper application lifecycle

When you launch a helper application with a file, Checkpoint Commander follows this general procedure:

1. The file is realised - it is decrypted (as required) and copied onto a disk device, so that the helper can get at it.
2. The helper is launched, and does its thing. Checkpoint Commander monitors it.
3. When the helper finishes, Checkpoint Commander detects this, and virtualises the file back to wherever it came from. The temporary disk copy is wiped.

If the file is on a disk device already, it doesn't need to be realised and re-virtualised. If no file is involved, or the helper application is using the HTTP URL connection mechanism, then only step 2 applies.

Security: no survivors!

If Checkpoint Commander is shut down, it takes all running helper applications with it (forcibly), and re-virtualises any files before finishing. This is a security precaution: clearly it is vital to wipe temporary, plaintext versions of sensitive files which you rely on keeping encrypted. When accessing a file via the HTTP URL connection mechanism, the temporary copy is encrypted; this is safe even if Checkpoint Commander is not shut down properly.

NB. Like any other program, Checkpoint Commander cannot resist being killed by the OS. If this happens, it will not be able to clean up after itself. This can lead to plaintext being left out in the open - a breach of security. As soon as possible after such an event you should launch another instance of Checkpoint Commander to complete the job by wiping these files under manual control.

The 'execute-this' gotcha

This policy of leaving no survivors leads to the following "gotcha". It is a simple matter to create a "helper application" whose effect is to execute the file it's launched against. (The command-line for such a helper is a single @ character). It's easy to forget that this is still treated as a helper application, and as such is killed when you shut down Checkpoint Commander.

Tracking

The biggest advantage of plug-ins is that they can track. A tracking plug-in stays in communication with the panel you launched it from. You can change files in the viewer itself, and the panel will track to the new file. For example, you can request "next file in folder listing" in the plug-in. The panel will "teleport" to the folder containing the file currently being accessed by the plug-in, find the next file of any type the plug-in has been set to handle, select that file in the panel and bring it up in the viewer.

Because helper applications have only very limited communication with Checkpoint Commander, they can't do this.

Other attributes of plug-ins

The other attributes of helper applications - whether they modify the file they access, and whether they require a file, don't accept one, or can work either way - are shared by plug-ins. However, they're stipulated automatically by the plug-in itself.

Plugins have their own connection mechanism. They don't use any of the ones used by helper applications.

Installing plug-ins

Plug-ins are made available as JAR files whose filenames follow a certain pattern. (Specifically, the filename must start with the prefix cpc.plugin. and end with .jar .) To install the plug-in, simply copy the JAR file into the lib subfolder of your Checkpoint installation. Restart Checkpoint Commander, and the plug-in will be available.

Plug-in lifecycle

Plug-ins have a somewhat similar lifecycle to helper-applications; in particular they do not survive Checkpoint Commander being shut down.

However, because they are integrated more tightly with Checkpoint Commander, it is not necessary to copy a file onto disk before a plug-in can read it. A properly-written plug-in can obtain the file directly in memory, without it needing to be decrypted and copied onto disk. Clearly this removes a significant potential security hazard compared to using a helper application (unless the helper application is using the HTTP URL connection mechanism).

A many-to-many problem, in spades

So, you've got a file. You've got some helper applications and plug-ins. You wish to access the file. The question is, what with? While this sounds simple enough, it's actually quite a nasty problem.

Firstly, what kind of file is it? There's not much point trying to open an image file with a spreadsheet program. Like pretty much everybody else, we use filename extensions to tell file types apart. (The alternative is to look inside the file itself for some sequence of magic numbers which indicate what this file is. However, this can be very difficult - some types of file either don't have magic, are proprietary and so aren't telling, or have very complex formats such that the magic, while there, is almost impossible to figure out.) For our purposes the filename extension is everything including and after the last dot (full stop) character in the filename. (Exception: a filename which starts with a dot, and contains no other dots, is defined to have no extension.)

Therefore, to summarize:

• There are many kinds of file.
• Every kind of file may have many possible extensions.
• Every kind of file may be readable by many helper applications and plug-ins.
• Every helper application and plug-in may be able to read many kinds of file. (This is not the same thing as the previous point.)

MIME types

The way to tackle this beast is to break it down. As the above suggests, to tackle this problem we need the concept of "kind of file". Checkpoint Commander uses the standard way to classify files: it assigns them a so-called MIME type. MIME types take the form type/subtype. The type is one of the following, usually:

application

Generic binary type, that isn't any of the others

audio

An audio stream

image

An image type

text

A human-readable text file.

video

A video stream.

The subtype section describes what format the file is in. For example, there are many kinds of video formats, each of which requires a different COder/DECoder (CODEC) function. Here's a selection:

video/mpeg

A video clip in one of the MPEG (Motion Picture Experts Group) formats.

text/plain

Ordinary text, without special formatting.

text/css

Text which is a Cascading Style Sheet (used for styling HTML etc.).

application/zip

A binary which is a ZIP archive.

application/x-unreal

A file which is to be opened using the Unreal game engine. The "x-" prefix indicates that this is a made-up subtype, which has not been sanctioned by the IANA and so you're on your own.

application/octet-stream

This is a catch-all, which means "This is a miscellaneous binary, and I don't know any more about it".

[NOTE] In fact, solving the general problem involves dealing with three interlocked many-to-many relationships. We have simplified things so that we only have to deal with one many-to-many relationship: the one between viewers and file extensions. Those with some programming experience will realise that 'MIME type' is being used to resolve this relationship. Most users will find that they can do everything they want within this framework.

application/octet-stream is special

Checkpoint Commander uses the MIME type application/octet-stream for a file which either has no extension, or whose extension doesn't appear in Checkpoint Commander's extension registry.

Anything bound to this MIME type will also be used for any file whose MIME type is known, but which doesn't have anything bound to it.

Specifying how to access a file

There are two ways to launch a helper application or plug-in against a given file. The first is to right-click the file in a panel. This will bring up the list of all such that you have bound to the file's MIME type (see below), or - under "other" - the list of all available, whether apparently suitable or not.

The right-click menu

The second is to double-click the file. This will launch the first helper / plug-in on the list.

When a file is of a MIME type which you haven't bound anything to, the ones bound to application/octet-stream are used instead.

The same right-click menu also has a properties option. This tells you information about the file: MIME type, size, and when it was last modified.

Managing bindings

Checkpoint Commander uses the function "Manage MIME types and bindings" on the Tools menu to allow you to manage all this. The dialog this brings up allows you to:

• Maintain the list of MIME types which Checkpoint Commander knows about.
• Define which filename extensions belong to which type.
• Specify which plug-ins and helper applications work with (ie. are "bound to") each MIME type.

Manage MIME types and viewers dialog

The dialog may look a bit scary at first glance, but its bark is worse than its bite. There are three panels, from left to right:

• The Extensions panel deals with the extensions bound to the currently selected MIME type (New, Delete) and allows you to find which MIME type (if any) owns an arbitrary extension (Find).
• The MIME types panel allows you to maintain the list of MIME types. The New, Edit and Delete buttons should be self-explanatory (the latter two apply to the currently-selected MIME type in the list). Restore defaults allows you to restore the system-default list of MIME types and / or the default set of bindings.
• The Helpers / plug-ins panel allows you to set which helpers and / or plug-ins (if any) are bound to the currently-selected MIME type. The left-hand list in the panel (nearest the MIME panel) contains whatever helpers or plug-ins are currently bound to the MIME type; the right-hand list contains all the others.

Finally, a few notes:

• Where there is more than one helper or plug-in bound to a type, the top one in the list is the default, and will be used when you double-click a file of this type in a panel. The order of the rest is the order in which the viewers will appear in the right-click menu for that file: arrange it as you prefer.
• Any changes you make in this dialog or any of its subdialogs do not "take" until (and unless) you click the OK button in the main dialog (not any subdialog). If you make a mistake, simply cancel the dialog.
• The fall-through MIME type application/octet-stream is special: it cannot be deleted.
• When specifying the list of extensions for a MIME type in the New MIME type and Edit MIME type subdialogs, you can separate entries with spaces, commas, semicolons, colons or any combination thereof.

General

By default, Checkpoint Commander comes bundled with some basic plug-ins. These are described below.

CPC text editor

A basic text editor. Supports DOS or UNIX line-endings, variable font, variable tab size, optional word-wrap, and a visible right margin.

The CPC text editor

The text editor tracks. Use Alt+up-arrow and Alt+down-arrow to track next and previous, respectively, or use the File menu.

If the file contains non-printable characters, the text editor can morph into the CPC hex viewer (q.v.)

CPC hex viewer

Displays a hex dump of the file. Read-only.

The CPC Hex editor

The hex viewer tracks. Use Alt+up-arrow and Alt+down-arrow to track next and previous, respectively, or use the file menu.

CPC image viewer

Displays GIF, JPEG and PNG images. Right-click in the image to bring up the options menu.

The CPC image viewer

When launched, the viewer is in "auto-scale" mode. In this mode, the image will zoom in or out as you expand or shrink the window, up to a maximum of 100%. Auto-scale is turned off either by toggling it explicitly (Ctrl+A or use the right-click menu) or by selecting manual zoom (Plus / Minus, or use the right-click menu).

In manual scaling mode, if the window is smaller than the effective size of the image (ie. the real size of the image multiplied by the current zoom factor), you can "pan" around it. There are three ways to do this:

• With the mouse towards the centre of the image (the pointer turns into a hand shape), left-drag to "pick up" the image and move it across the window, as though the image were stuck to the mouse pointer.
• With the mouse towards the edge of the image (the pointer turns into an arrow-head shape), click and hold to pan the image in the direction shown.
• Use the arrow keys to pan. Hold down Ctrl to pan more slowly.

To toggle full-screen mode, either use the right-click menu option, F11 (toggle), Alt+Enter (toggle) or Enter / Esc (full-screen and windowed mode respectively).

Refresh / reset (on the right-click menu, or Ctrl+R) resets to windowed mode with auto-scale and 100% zoom (if the screen is big enough). It also re-loads the image from the source device.

Finally, Image properties (right-click menu) displays some basic statistics for the image.

The image viewer tracks. Use Alt+up-arrow or space, and Alt+down-arrow or backspace, to track next and previous, respectively. Or (as always!) use the right-click menu.

CPC browser interface

HTML (web) pages and other multimedia etc. can be viewed by a web browser. This plug-in allows Checkpoint Commander to talk to your web browser of choice. (You may well be using it to read this.)

The browser interface tracks by using an HTML frame-set to display a video-style "toolbar" below your page (outlined in red on the screenshot). Click on the buttons in this toolbar to track: single arrows are next / previous, double arrows are top / bottom. It will also track when you follow relative links from the page, provided that whatever is on the other end of the link is of a MIME type which is bound to this plug-in. (See managing bindings above.)

The CPC browser interface

NB. If you have Options|Prompt before looping round enabled, and the browser window is sitting on top of the Checkpoint Commander GUI window, then when you click the one of the single-arrow (track-to-next / track-to-previous) controls on the toolbar, the prompt may not show up over the browser window. If this happens, the browser will sit there, as though connecting to a really slow website. To fix this, Alt+Tab (or the equivalent on your system) to bring the prompt to the top, and answer it.

One powerful use of this technique is that if you have a folder containing many HTML pages on your hard drive, or inside a CDB, then using the toolbar buttons enable you to skim backward an forward through the folder in order to have a quick look at the contents of each files. This is similar to skimming through a folder full of images using the CPC image viewer.

[NOTE] This flexibility can some times lead to surprising results if you bind the browser interface to MIME types normally used for page furniture, or other images. If you launch the viewer to display an HTML page then the viewer will track all browser requests for furniture and images. When the page has finished rendering, the HTML viewer will have tracked to the last image requested. Depending on the structure of the web page this may not even be in the same folder as the original page, and using the buttons on the toolbar can produce puzzling results.

CPC Audio Player

This plug-in plays MP3s and Ogg Vorbis, WAVs and various other sound formats. The MP3 and Ogg Vorbis support is via bundled, third-party libraries which plug into the Java runtime. These libraries are still rather new, so expect some glitches.

The CPC Audio Player

The audio player tracks via Alt+Up / Alt+Down in the usual way, or use the Previous / Next buttons on the player itself.

Archive opener

This plug-in opens a Checkpoint Commander archive. A simple way of automating this function is to assign a special file extension (we tend to use .cdb, for various reasons which aren't important here) to these archives and set up a MIME type for it. (We use application/x-cdb, for the same reasons.) You can then bind the archive opener to the MIME type, so that when you double-click the file the archive opener comes straight up. See Mapping files to helpers and plug-ins for a more detailed discussion of this procedure).

If you prefer not to make your archives so obvious, an alternative is to assign the archive opener to MIME type x-unknown/x-unknown. This way, whenever an unfamiliar filename extension comes up, the archive opener will be bound to it.

This plug-in doesn't track.

[TIP] Tip for advanced users: Checkpoint Commander can be used to open the "filesystem set" of any Checkpoint Database file (CDB) which has one. For example, every Checkpoint Module (CPM) file contains a filesystem set.

JAR / ZIP opener

a JAR or ZIP file. Otherwise it's similar to the archive opener.

This plug-in opens a JAR or ZIP file as a new device. Due to the limitations of the format (it does not provide random-access) these can only be opened read-only. The password option of PKZIP is not supported: the format leaks filenames even when the file is encrypted, and Paul Kocher has discovered a known-plaintext attack against the algorithm [101]. We advise you not to use this option, even for ZIPs which you don't want to open with Checkpoint Commander. Use an encrypted Checkpoint Commander archive instead.

This plug-in doesn't track.

Result set opener

Checkpoint Commander result sets can be stored. This plug-in allows stored result sets to be re-loaded.

This plug-in doesn't track.