Instruction set reference
In a client-host relationship between two applications, the client sends this instruction to the framing manager to signal that it is opening a 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 the host application.
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: 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: The access mode that the client will be using.
- arg: If file seek mode is supported, this argument allows an initial file position (in bytes -- offset from the beginning of the file) to be specified.
- arg: If directory index mode is supported, this argument contains the name of the file to be opened.
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. 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.
|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.
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.
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. If no filename is specified here, the client can access the directory itself, which shall be formatted as follows:
[iso date] [iso date] [size] [filename]\n
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.