Instruction set reference
HIPE_OP_FIFO_GET_PEER
Proper documentation for this instruction is yet to be written. For further information about this instruction, look in the source code for its definition in hipe_instruction.h.
- 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]: A suggested default 'filename' to be given to the resource, for example untitled picture. The FIFO-host may or may not use this suggestion where a new file is to be created. Some FIFO-hosts may use this name to identify the document for the user's benefit.
- arg[1]: Minimal required access mode(e.g. r), optionally followed by a space, and the full set of supported access modes that the FIFO-client can take advantage of. See below.
- arg[2]: Metadata formatted using the same convention as that given by the FIFO-host in HIPE_OP_FIFO_ADD_ABILITY, except from the client's point of view. The metadata describes the function the client requires and the file formats the FIFO-client can work with. The framing manager attempts to match the client to a host based on both having supported file types in common.
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.
| 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.
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.
Minimal vs desired access modes
An application might be able to deal with a multitude of access modes (such as file seeking, reading and writing) but may also be able to make do with a minimal set of access modes. For example, a text editor might be capable of opening a file for reading and writing. However, in the worst case, loading a file read-only may be supported too. In this case, arg[1] might be specified as: "r rw"
Notes
FIFO functionality in Hipe is under development and this instruction and documentation may be subject to change as we figure out the best approach.