Instruction set reference
HIPE_OP_FIFO_CLOSE
Sent by either end of a FIFO relationship (and relayed to the other end by the framing manager) to say that the sender has finished with the current transfer, and whether the transfer succeeded at its end. The resource still exists and may be opened again later.
Each end sends this instruction once per transfer. The end that finishes first sends it, and the other end closes the FIFO at its own end and answers with its own HIPE_OP_FIFO_CLOSE. The transfer is over when both have been sent, and the resource is then ready to be opened again, in a different mode if required.
- 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 outcome of the transfer at the sender's end. Empty if it ended normally. Otherwise the transfer failed at the sender's end, and this is the reason, as text that can be shown to the user (for example No space left on device).
Who sends it, and what the outcome means
| Situation | What is sent | What the receiver should do |
|---|---|---|
| The client has finished writing. | The client sends HIPE_OP_FIFO_CLOSE with arg[1] empty, after writing all its data and closing its end. | The host reads the remaining data, stores it, and answers as in the next two rows. |
| The host has stored what the client wrote. | The host answers with arg[1] empty. | The client can report the data as saved. |
| The host could not store what the client wrote (disk full, no permission...). | The host answers with the reason in arg[1]. | The client reports that saving failed, and can show the reason. |
| The client gives up part-way through writing. | The client sends HIPE_OP_FIFO_CLOSE with a reason in arg[1]. | The host discards what it received, leaving the stored data as it was, and answers. |
| The host has finished writing what the client asked to read. | The host sends HIPE_OP_FIFO_CLOSE with arg[1] empty, after writing all the data. | The client reads the remaining data and answers. |
| The host fails part-way through writing (the file became unreadable...). | The host sends HIPE_OP_FIFO_CLOSE with the reason in arg[1]. | The client discards what it received, reports the failure, and answers. |
| The client needs no more of what it is reading. | The client sends HIPE_OP_FIFO_CLOSE with arg[1] empty. | The host stops writing and answers. |
| The host cannot do what a HIPE_OP_FIFO_OPEN asked (no such file, no permission...). | The host sends HIPE_OP_FIFO_CLOSE with the reason in arg[1], in place of relaying the HIPE_OP_FIFO_OPEN back. | The client closes its end and reports the failure. No transfer was opened, so it sends no answer. |
Notes
A client that writes data should treat it as saved only once the host's answer arrives with arg[1] empty. Until then the host may still fail to store it.
A program should act only on whether arg[1] is empty. The text itself comes from the other application and is meant for the user; its wording is not defined.
A HIPE_OP_FIFO_DROP_PEER for the resource that arrives while a transfer is open also ends the transfer, as a failure: the other application has gone or has ended the relationship. An application should also give up on a transfer whose other end stays silent for too long.
Applications written before arg[1] was defined send it empty and ignore it when receiving, so they report every transfer as successful.
Like the other FIFO instructions, this one is passed between frames without the Hipe display server interpreting its contents.