Instruction set reference
HIPE_OP_FIFO_ADD_ABILITY
This instruction is usually sent by a client to its parent frame (the framing manager for the desktop environment) to indicate that the client may be called on to carry out a particular action. This means the client can act as a FIFO host when the user selects the listed ability.
- location: Sending a message: A value of 0 (corresponding to the body element of
the client frame) means the message should be sent to the direct parent of this client.
Receiving a message: A location value corresponding to a child frame means the message came from that client. - arg[0]: The name of the ability offered. For example "Save", "Print", "Open".
- arg[1]: The set of supported access modes. For example, "rwa". See below.
- arg[2]: Additional line-separated metadata including extended description and supported file types.
Name of ability
The name of the ability serves two purposes: (1) it is shown to the user to help the user decide which host function to select when exchanging data with another application. (2) it is used to identify the particular ability within Hipe (together with the client ID).
If a client application offers multiple host abilities, each must have a unique name.
The name of the ability is case sensitive.
FIFO access modes
The following specifiers can be used to control how data is read or written to the FIFO stream. The direction of transfer is specified from the client's point of view.
Typically, a host should not be expected to implement all of these access modes. For example, it might not be appropriate to save a document to a scanner or to load a file from a printer, but reading a scanned page from a scanner and sending it to a printer is more reasonable. Likewise, for some sources of data, it is only sensible (or technically feasible) to transfer the data sequentially from beginning to end, while a database system might allow random access from any position within a file.
| Specifier | Description |
|---|---|
| r | Read sequentially from the beginning of the data. Data to be read should already exist at the host. |
| R | Read data from a specified position, rather than from the start of the file. Data to be read should already exist at the host. |
| w | Write new data sequentially from the beginning, discarding all existing data held by the host. |
| W | Write data from a specified position, overwriting a section of existing data held by the host. |
| a | Write data by appending it to the end of the existing data held by the host. Existing data is preserved. If there is no pre-existing data in the resource, data will be written from the beginning. |
Notes on access modes
- If the initial mode used for a resource is r or R, it is expected that the host will select an existing resource (ideally containing existing data) rather than creating a new empty resource. For example, if the user wishes to open a file on a drive for viewing, the file manager should not prompt the user to create a brand new file for saving to.
- The R and W modes effectively work as random access modes because they allow the client to select a position to read or write from. (For example, write an entry 215 bytes into the file.) This is useful for database-style storage where the file is organised into fixed-length sections and the correct lookup position can be figured out using knowledge of the file format. However, not all hosts may support such functionality. Regular file seek operations (e.g. lseek, fseek and rewind in C) are not supported by FIFOs and cannot be used. Instead, the position within a file or resource can be manipulated by closing and reopening the resource in the desired position using the appropriate hipe instructions – which communicates the request to the host.
- If a host offers R and/or W functionality, it should also list support for the corresponding r and w equivalent(s) which are effectively subsets of this functionality with a seek position of 0. The reason to list both is because a client may specify sequential access as the minimal required access code, even though it is capable of instead using random access if available.
Order of access modes
The order of access mode specifiers is significant: where appropriate, the expected initial access mode should be specified first. For example, "rw" means that data will initially be read, and may be written back to later, while "wr" means that fresh data will be written from the start. An initial access mode of r or R means that the host acts (initially at least) as a source of data rather than a destination.
An example of "read then write" ordering would be a file which is opened for editing. First the editor must read the file to load its contents. Later the user may save changes back into the file.
Metadata about ability
The metadata argument is used to specify what sort of data the host can work with. This information spans multiple lines, separated by a newline character (in C, \n is used to represent a newline character).
| Line | Description | Example |
|---|---|---|
| 1 | Description of ability | Get image from scanner |
| 2 | Preferred file format pattern | pdf:Portable document format |
| 3 | Alternative file format pattern (optional) | jpg;jpeg;gif:Graphical image |
| ... | Additional lines for other file formats as necessary. | txt:scan to text |
Where multiple file formats are supported, the filename extension normally associated with that format is used. For example, gif means a GIF image format. To prevent ambiguity (in cases where two very different file formats might share a common filename extension), a description is added. The description is not used to identify the file, but is displayed to the user so the user can exclude inappropriate files where prompted to select a file from disk. The client application will probably use a different description for the same file format. Since descriptions are intended for user information only and are subject to be altered in transit, descriptions alone cannot be used to differentiate between different file formats with the same extension. (Therefore each extension should only be listed once in the entire metadata argument).
We use Windows-style file extensions to filter file formats as they are well-understood in practice. Why are MIME types not used? Whilst MIME types were envisaged as a way to remove ambiguity from file format types, they tend to produce less clarity than confusion in reality.
The file type (extension) should be in lowercase, and should not include the *. prefix often used in Windows where the file type follows a dot at the end of each filename. It is worth noting that the host may not organise files with filename extensions, but may use a different scheme.
Some FIFO-hosts can handle any file format. In this case, a single * is specified to indicate a single file of any type. (Note, the * character does not work for matching filename patterns, and should be used by itself only.)
Directory resources
In some cases, the resource is not a single file-style resource, but a directory resource (the client can access multiple files in the directory, which are indexed by filenames). This is useful in cases where a client works on an entire project rather than a single file. To specify that any directory is allowed, use a single forward slash / for the type. To require a directory to have a certain filename extension (e.g. to denote an application, python project, etc.) place the slash after the type, e.g. pro/ would match a directory named myproject.pro/. Note that 'directories' here are an abstract resource. It may not be a physical directory on disk, but something with a directory-like structure, like a set of database tables.
Notes
Abilities are added by FIFO 'hosts' (applications that provide access to a FIFO resource) and the framing manager is expected to maintain a list of these. The list is not given to FIFO-client applications, which never see the name of the ability they access. The framing manager mediates the connection by displaying the ability for the user to select, afterwhich the FIFO-client receives the filename of the FIFO resource.
FIFO functionality in Hipe is under development and this instruction and documentation may be subject to change as we figure out the best approach.