(v13) D_IP_CHANNEL_DESTROY

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

D_IP_CHANNEL_DESTROY Selector

Parameter: ChannelDestroyParam *param

Call type: Multi‐call

The RIP makes this call-in response to inputs being shut down from the main menu, or when a channel is disabled by the Input Manager, or when a device is explicitly dismounted with the PostScript language devdismount operator, or when the user asks the RIP to quit.

If the channel was open before this selector is called, an attempt to close it will already have been made. If it failed to close, perhaps because of some error, the plugin must take whatever action it reasonably can to close it during this selector call. Just in case this happens, it is worth coding some means of closing a channel into D_IP_CHANNEL_DESTROY .

Once a destroy call has succeeded, the ChannelContext for the channel is deallocated by the RIP. Any existing pointers to the ChannelContext therefore become invalid.

In the destroy call, plugins should ensure they deallocate any memory that is only accessible from the private state memory pointed to by the channelState field of the ChannelContext structure.

TEXT

      typedef struct channelDestroyParam { int32 version ; ChannelContext *channelContext ; int32 finalAttempt; MultiCallData multi ;
      IPStatus status ;
    } ChannelDestroyParam ;

version

The version field should be ignored.

channelContext

A pointer to data the RIP holds about the channel.

finalAttempt

The RIP makes a second attempt to destroy a channel if the first fails. If the finalAttempt flag is non‐ zero, this is the last attempt that will be made to destroy the channel. The plugin should therefore take whatever action it can to destroy the channel. Whatever the result, the ChannelContext and associated memory are deallocated. Any pointers to them become invalid.

multi

Controls the sequence of calls to the selector. See (v13) The MultiCallData structure .

status

The plugin should set the IPmajor field of this IPStatus structure to IPS_OK if the call was successful and to IPS_FAIL otherwise.

If IPS_FAIL is returned, the RIP leaves the ChannelContext allocated (though any buffer space associated with its PLUGIN_BUFFER structures is deallocated) unless finalAttempt is set. The RIP calls the plugin again to make one more attempt to destroy the channel.