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 comlimentary 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_ACCEPT message.
arg[1]: The access mode that the client will be using.
arg[2]: For W and R modes, specifies starting position and optionally total length of the transfter (see below).
arg[3]: If directory index mode is supported, this argument contains the name of the file to be opened.

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.

Access mode

The access mode should be a single specifier from those that were granted to the client when the HIPE_OP_FIFO_ACCEPT 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.

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.

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 thise 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 presense 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.

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.

FIFO functionality in Hipe is under development and this instruction and documentation may be subject to change as we figure out the best approach.