Instruction set reference

`HIPE_OP_FIFO_OPEN`

In a client-host relationship between two applications, the client sends this instruction to the framing manager to coordinate opening a FIFO resource which has previously been granted to it through a HIPE_OP_FIFO_RESPONSE instruction. A framing manager that supports FIFO-based communication among applications is then required to relay the instruction to and from the host application.

When the host receives this instruction, it is required to open the FIFO resource at its end in the complementary direction of transfer, and relay the same HIPE_OP_FIFO_OPEN instruction back to the client to acknowledge that the resource is now likely to be open at both ends and ready to be used. The FIFO resource ID string (FIFO path) is used to uniquely identify the FIFO resource on the system, and the framing manager should use this to identify where to relay the acknowledgement back to when the host retransmits it.

This does not mean establishing a shared resource (done through HIPE_OP_FIFO_GET_PEER), but beginning a transfer in a particular direction. The same resource may be opened or closed multiple times in the lifetime of a FIFO resource.

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. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
arg[0]: The FIFO resource ID string that was provided to the client when the resource was made available through a HIPE_OP_FIFO_RESPONSE message.
arg[1]: The access mode that the client will be using.
arg[2]: Depends on the access mode. For W and R modes, specifies starting position and optionally total length of the transfer (see below). For m and M modes, the entry's new name (see "Changing the contents of a directory" below). For s, the access modes granted to the new client (see "Swapping roles" below). Not used in other modes.
arg[3]: If directory index mode is supported, this argument contains the name of the file to be opened, or of the entry to be made, moved or deleted.

Synchronising opening a FIFO resource at both ends of transfer

A FIFO is a special file in a UNIX-style environment that does not buffer any data on the disk. One end is written to (in one application) while the other end is read from (in another application). In the Linux programming environment, the C open() and close() function are normally used to tell the operating system to open a FIFO resource. Often a Hipe application would open a FIFO in 'nonblocking' mode which means an application will not freeze up if the other end of the transfer is too slow to process data or open the resource. However this means that the application that is going to read from the FIFO must open its end of the FIFO first before the other end begins writing. If the reader has not opened the FIFO yet, any data written into the FIFO will have nowhere to go and will be discarded by the operating system. So to avoid data loss, both applications must cooperate to ensure the reading end is opened first.

The FIFO resource should initially be in a closed state at both ends. (If in an open state, the HIPE_OP_FIFO_CLOSE instruction is used to coordinate closing both ends.
The client opens its end of the FIFO resource for either reading or writing depending on the mode being used, but does not actually begin reading or writing yet.
The client should then send a HIPE_OP_FIFO_OPEN instruction to location 0 (which then goes to the parent frame/framing manager to be relayed to the host application that it shares the FIFO resource with)
The host application receives the HIPE_OP_FIFO_OPEN instruction and opens the FIFO at its end in the opposite direction to the mode requested by the client (e.g. if the client is reading, the host opens the FIFO for writing).
At this point the host updates its internal status and may begin reading/writing operations on the FIFO.
The host application sends the HIPE_OP_FIFO_OPEN instruction back in the other direction (by sending it to location 0). The arguments should be the same as those it received except that the file position should be updated as necessary to reflect the actual position in the file represented by the host (e.g. if the file is opened in append mode, the host should send back the position of the existing end of the file). The designated host application is always required to relay this instruction back regardless of the access mode. The framing manager relays it back to the client.
The client receives the HIPE_OP_FIFO_OPEN instruction, and begins reading/writing at its end.
At this point the client updates its internal status and may begin reading/writing operations on the FIFO.

If the host cannot open the resource as asked (for example the file no longer exists, or it has no permission), it does not relay the HIPE_OP_FIFO_OPEN back. It sends a HIPE_OP_FIFO_CLOSE for the resource with the reason in arg[1]. So a client waiting for the HIPE_OP_FIFO_OPEN to come back must also accept a HIPE_OP_FIFO_CLOSE (or a HIPE_OP_FIFO_DROP_PEER) for that resource: either means no transfer was opened, and the client should close its end. See HIPE_OP_FIFO_CLOSE for how the end of a transfer, and its success or failure, is reported.

Access mode

The access mode should be a single specifier from those that were granted to the client when the HIPE_OP_FIFO_RESPONSE instruction was relayed to the client. For example, if "w" access (write mode) was not granted, then "w" should not be specified. The access mode tells the host what it should now do.

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.
`n`	Make a new, empty directory inside a directory resource. No data is transferred.
`m`	Move or rename an entry inside a directory resource. Fails if something already has the new name. No data is transferred.
`M`	As `m`, but if a file already has the new name, it is replaced. No data is transferred.
`d`	Delete an entry inside a directory resource: a file, or an empty directory. No data is transferred.
`s`	Swap roles: the host becomes the client for the rest of the relationship, and the client the host. Used once, before any transfer. No data is transferred.

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.
The modes n, m, M and d change what a directory resource contains and transfer no data. They are described under HIPE_OP_FIFO_OPEN. A host lists the ones it supports along with its other access modes, so a client can offer the user only the operations the host can carry out. A host that offers M should also offer m.
s is not a way of accessing the data and is never the minimal access mode. A client lists it in its full set if it can also act as the host, and a host grants it only if it can also act as the client. Granting it does not swap the roles yet: see "Swapping roles" under HIPE_OP_FIFO_OPEN. After a swap, "client" and "host" here mean the new roles.

Starting position/transfer length

For modes r,w,a, the starting position is implied and the total length is never specified when opening the transfer. arg[2] is not used in these modes. If the client is reading, the host writes the whole contents down the FIFO pipe until the end of the file or close of transfer. If the client is writing (or appending), it writes as much as it needs to and then closes the transfer.

For modes R and W, the client is able to specify a starting position within the file for the host to seek to. If it is reading, it is also useful to specify a maximum number of characters required so that the host does not write everything to the end of the file if the client only requires a fixed number of characters (e.g. a customer record in a database).

For these modes arg[2] is specified as a starting position, optionally followed by a comma and a length in bytes, without spaces. A negative starting position means a distance from the end of the file, such that -1 in W mode is equivalent to a. A specified length of 0 is equivalent to omitting the length.

Directories

If the filename of the shared resource has a trailing slash /, this means the resource is treated as a directory, and filenames within the directory can be specified in arg[3] regardless of the access mode used. If no filename is specified here, the client can access the directory itself, which shall be formatted as follows:

[iso date] [iso date] [size] [accessmodes] [filename]\n

Note that for filenames within a directory, the filename extension should be included if present (e.g. a_photograph.jpg) since for clients that are capable of dealing with directories, Hipe does not filter client abilities by file type within a directory, only the type of the main directory itself.

Representing files within subdirectories

Many real-world directories also contain files within subdirectories. These should also be included in the same flat list (Hipe's FIFO interface treats all files within the base directory on the same footing regardless of how deep they are in a subdirectory hierarchy) however the subdirectory structure is preserved within the filename of each entry as follows.

Each subdirectory is included in the list with a trailing slash at the end of the filename. For example, subdir/, or for a subdirectory within another, subdir/another_dir/.
A file within a subdirectory is prefixed by its subdirectory path, for example a picture with filename something.jpg inside an img/ subdirectory would have its filename written as img/something.jpg.

Subject to what is sensible for each implementation, subdirectories are normally represented as separate items in the list regardless of whether they are empty or contain files. The presence of a trailing slash at the end of the filename indicates that the entry is a subdirectory. The size value given to a subdirectory is undefined and is not used, since there is no data to be read or transmitted through the FIFO from the subdirectory itself.

Changing the contents of a directory

Four access modes change what a directory resource contains, without transferring any data: n makes a new directory, m and M move or rename an entry, and d deletes one. A client may use only those the host granted it.

These work differently from a transfer. Neither application opens the FIFO. The client sends HIPE_OP_FIFO_OPEN and the host carries out the operation at once. The host does not relay the HIPE_OP_FIFO_OPEN back: it answers with a HIPE_OP_FIFO_CLOSE for the resource, whose arg[1] is empty if the operation was done, or says why it was not (see HIPE_OP_FIFO_CLOSE). The client sends no HIPE_OP_FIFO_CLOSE of its own. As with a transfer, the client must wait for the answer before opening the resource again.

Mode	`arg[3]`	`arg[2]`	What the host does	It fails if
`n`	The directory to make, e.g. `img/thumbs/`	Not used	Makes one new, empty directory.	The directory it would be made in doesn't exist, or something already has that name.
`m`	An existing entry, e.g. `notes.txt`	Its new name, e.g. `old/notes-2019.txt`	Gives the entry the new name, which may place it in a different directory of the resource. A directory keeps its contents.	The entry doesn't exist, the directory the new name is in doesn't exist, or something already has the new name.
`M`	As for `m`	As for `m`	As `m`, except that a file which already has the new name is replaced, in a single step: the new name refers to the old file's contents until it refers to the moved entry's, and is never missing.	As for `m`, except that a file with the new name is not a failure. It still fails if a directory has the new name, or if the entry being moved is a directory and a file has the new name.
`d`	The entry to delete	Not used	Deletes a file, or a directory that has nothing in it.	The entry doesn't exist, or it is a directory that still has entries in it.

Names are written as they appear in the directory's list: relative to the directory resource, and with a trailing slash for a directory (for m and M, in both the old and the new name).

m is the mode for renaming at the user's request: because it never replaces anything, a client can ask the user before anything is lost. M lets a client save a file safely, by writing the new contents under a temporary name and then moving that over the original.

A host may include m, M and d in an entry's access modes in the directory's list to show that the entry may be moved or deleted, and n in a directory's access modes to show that directories may be made in it. The client should be prepared for the host to refuse all the same.

The directory's list is not updated for the client. After a change, the client reads the list again if it needs the new contents.

What deleting means is up to the host. For example, a file manager might move the entry to a wastebasket of its own. In all cases the entry is no longer in the directory resource afterwards. A host should also refuse names that would reach outside the directory it is sharing.

Swapping roles

Only the client can start a transfer. When the application that asked for the resource should instead serve it (for example, a file manager that hands a file to an editor, which then saves its changes back), the two applications can swap roles once:

The client lists s in the full set of access modes in its HIPE_OP_FIFO_GET_PEER, e.g. "w ws".
A host that can act as the client grants s in its HIPE_OP_FIFO_RESPONSE. A host that doesn't grant it stays the host.
The client sends HIPE_OP_FIFO_OPEN with mode s before any transfer. arg[2] holds the access modes the new client may use, from its own point of view, as they would be granted in a HIPE_OP_FIFO_RESPONSE: for example "rw", "r" for a file that may only be read, or "rwnmd" for a directory. arg[3] is not used.
Neither application opens the FIFO. The host does not relay the HIPE_OP_FIFO_OPEN back: it answers with a HIPE_OP_FIFO_CLOSE, with arg[1] empty if it accepts the swap, otherwise the reason. The client sends no HIPE_OP_FIFO_CLOSE of its own.

Answer	Afterwards
Accepted	The former host is the client: only it sends `HIPE_OP_FIFO_OPEN` to start a transfer, using the modes it was given in `arg[2]`. The former client serves each one exactly as a host does, relaying it back or refusing it with a `HIPE_OP_FIFO_CLOSE`.
Refused	The roles stay as they were. The client may still use the modes it was granted, for example to write the data with `w`.

s may be sent only while no transfer is open, and only once in a relationship. The roles can't be swapped back.
A host that granted s must still serve the client normally if the client never sends it.
Swapping changes who starts transfers, not who owns the FIFO: the application that sent the HIPE_OP_FIFO_RESPONSE still created it, and still removes it when the relationship is dropped (see HIPE_OP_FIFO_DROP_PEER).
The access modes in a directory resource's list are those of the current client.

A host that the user carries on working in, such as an editor or a viewer, should grant s whenever the client offers it, even if it will only read the data once: the framing manager then leaves it in front (see HIPE_OP_FIFO_RESPONSE). A viewer, for example, swaps, reads the resource with r, and drops the relationship when the user closes the document.

Notes

Hipe is just the messenger here. It does not open anything, but merely relays the request to the client. The access mode and arguments tell the FIFO-host what to do with the shared resource. Both host and client should then open and access the resource using regular file read/write operations.

This instruction works in the same way as HIPE_OP_MESSAGE in that the instruction contents are passed to a child or parent frame without interpretation of the contents by the Hipe display server. This means that applications are required to supply and/or read the specified arguments in order to understand one another, but the Hipe display server is not itself involved in interpreting them.