(v13) Single-call and multi-call selectors
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
There are two kinds of input plugin selector call:
Single‐call | The RIP makes one function call to the plugin, during which the plugin must complete the operation associated with the selector. |
Multi‐call | Some operations associated with particular selectors may take a significant, but typically unknown, time to complete. It would be undesirable for the RIP to have to wait for completion. The multi‐call approach allows for a fast return. The RIP makes an initial call to the plugin. The plugin starts the operation, and returns a flag saying that the operation is in progress but incomplete. Periodically, the RIP makes more calls with the same selector, to which the plugin replies with the progress of the operation. Eventually, the plugin indicates that no further time is required, by setting the “done” flag in the Note:
The progress‐checking function calls need not be consecutive. The RIP can interleave the progress‐checking calls with other calls to the same plugin, which may deal with different channels or with dialogs, and calls to different plugins. The RIP does not change the |
In both kinds of call, the plugin sets fields in the parameter passed to the plugin on the call - to store call‐status information. The status structure is called IPStatus
. (See (v13) The IPStatus structure
.) The RIP examines the status structure at the end of the call and takes appropriate action.