Instruction set reference
HIPE_OP_FIFO_GET_PEER
Requests (or handles a request) for a program to begin communications with a FIFO peer that has the required ability. This leads to the creation of a FIFO resource between the two applications.
There is a one-to-many relationship between a supported ability and the number of peers that may be making use of that ability.
- 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.
- requestor: An optional user-defined value that will be received back by the client when the HIPE_OP_FIFO_RESPONSE arrives. A complex client program with multiple sources for requests should use unique requestor values for different requests to ensure that responses can be dealt with without ambiguity.
- 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. This filename should not include the filename extension (nor a trailing slash for directories) as this information is provided separately through arg[2]. May be blank under certain circumstances (see Notes below).
- 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.
- arg[3]: Initially blank when sent from a client, however the framing manager should place the unique name of the chosen ability in this argument when it relays the instruction to the host selected by the user.
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.
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.
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
In certain cases a peer relationship needs to be set up to transfer a group of files that are not physically located in a particular named directory. For this case, request a peer using a blank filename in arg[0] and the directory type (/) specified via arg[2]. The treatment of a group of files is the same as a directory of files except that the lack of a filename tells the peer that they should not be copied into a new directory but should be placed within a given location.
FIFO functionality in Hipe is under development and this instruction and documentation may be subject to change as we figure out the best approach.