Hipe : The DOM on the desktop
How Hipe Works  |  Installation  |  Running hiped  |  Hipe API

The Hipe API
Including libhipe
libhipe functions
C++ extensions
Multithreading considerations
Hipe instructions
Interprocess communication
HIPE_OP_ADD_FONT
HIPE_OP_ADD_STYLE_RULE
HIPE_OP_ADD_STYLE_RULE_SRC
HIPE_OP_APPEND_TAG
HIPE_OP_APPEND_TEXT
HIPE_OP_ATTRIBUTE_RETURN
HIPE_OP_AUDIOVIDEO_STATE
HIPE_OP_CANVAS_ACTION
HIPE_OP_CANVAS_SET_PROPERTY
HIPE_OP_CARAT_POSITION
HIPE_OP_CLEAR
HIPE_OP_EDIT_ACTION
HIPE_OP_CONTAINER_GRANT
HIPE_OP_CONTENT_RETURN
HIPE_OP_DELETE
HIPE_OP_DIALOG
HIPE_OP_DIALOG_INPUT
HIPE_OP_DIALOG_RETURN
HIPE_OP_EVENT
HIPE_OP_EVENT_CANCEL
HIPE_OP_EVENT_REQUEST
HIPE_OP_FIFO_ADD_ABILITY
HIPE_OP_FIFO_CLOSE
HIPE_OP_FIFO_DROP_PEER
HIPE_OP_FIFO_GET_PEER
HIPE_OP_FIFO_OPEN
HIPE_OP_FIFO_REMOVE_ABILITY
HIPE_OP_FIFO_RESPONSE
HIPE_OP_FILE_RETURN
HIPE_OP_FIND_TEXT
HIPE_OP_FRAME_CLOSE
HIPE_OP_FRAME_EVENT
HIPE_OP_FREE_LOCATION
HIPE_OP_GEOMETRY_RETURN
HIPE_OP_GET_ATTRIBUTE
HIPE_OP_GET_AUDIOVIDEO_STATE
HIPE_OP_GET_BY_ID
HIPE_OP_GET_CARAT_POSITION
HIPE_OP_GET_CONTENT
HIPE_OP_GET_FIRST_CHILD
HIPE_OP_GET_FRAME_KEY
HIPE_OP_GET_GEOMETRY
HIPE_OP_GET_LAST_CHILD
HIPE_OP_GET_NEXT_SIBLING
HIPE_OP_GET_PREV_SIBLING
HIPE_OP_GET_SCROLL_GEOMETRY
HIPE_OP_GET_SELECTION
HIPE_OP_KEY_RETURN
HIPE_OP_LOCATION_RETURN
HIPE_OP_MESSAGE
HIPE_OP_OPEN_LINK
HIPE_OP_REMOVE_ATTRIBUTE
HIPE_OP_REQUEST_CONTAINER
HIPE_OP_SCROLL_BY
HIPE_OP_SCROLL_TO
HIPE_OP_SERVER_DENIED
HIPE_OP_SET_ATTRIBUTE
HIPE_OP_SET_FOCUS
HIPE_OP_SET_ICON
HIPE_OP_SET_SRC
HIPE_OP_SET_STYLE
HIPE_OP_SET_STYLE_SRC
HIPE_OP_SET_TEXT
HIPE_OP_SET_TITLE
HIPE_OP_TAKE_SNAPSHOT
HIPE_OP_TOGGLE_CLASS
HIPE_OP_USE_CANVAS

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.

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.

SpecifierDescription
rRead sequentially from the beginning of the data. Data to be read should already exist at the host.
RRead data from a specified position, rather than from the start of the file. Data to be read should already exist at the host.
wWrite new data sequentially from the beginning, discarding all existing data held by the host.
WWrite data from a specified position, overwriting a section of existing data held by the host.
aWrite 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

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).

LineDescriptionExample
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.