irForceInit - forcibly obtain a channel, initialize a channel, and obtain a channel ID
#include <irapi.h>
int irForceInit (int channel_nbr, channel_id *cid_ptr, int tag);
The irForceInit function unconditionally obtains ownership and initializes a channel specified by a channel_nbr. This function is similar to irInit(3IRAPI), but does not permit the previous owner to retain ownership of a channel. This function is reserved for use by maintenance and related processes and should not be used by applications.
Except upon failure, this function sets *cid_ptr to the channel_id that is to be used by most of the other functions when referencing the channel.
irForceInit sets all channel parameters to their appropriate default values. "Save on Exec" parameters are set to their default values, unlike irInit(3IRAPI) which preserves parameter values on initialization.
If irForceInit returns IRR_OK, the channel is in the IRS_IDLE state [see IrSTATES(4IRAPI)]. If irForceInit returns IRR_PENDING, the channel is in the IRS_INIT_PENDING state.
A maintenance process can unconditionally request a channel from an application with irForceInit. The application that previously owned the channel should discontinue use of the channel_id as the channel is invalid.
If the channel is not allocated at the time of the request, the requesting maintenance process receives a return value of IRR_OK and *cid_ptr is set to the channel_id that should be used with other functions.
If the channel is allocated at the time of the request, the requesting maintenance process receives a return value of IRR_PENDING and *cid_ptr is set to the channel_id that should be used with other functions. In this case, the owning process, acting on behalf of the library, frees the channel and passes ownership to the requesting process. The requesting process experiences a slight delay before receiving the IRE_GRANT event. The current owner of the channel cannot control whether the channel ownership passes from itself to the requester with the IRP_CHAN_NEGOTIATION parameter. The current owner is informed of the channel deallocation through the IRE_CHAN_REMOVED event.
The IRE_GRANT event is returned from a call to irForceInit in which the return value is IRR_PENDING.
IRR_OK is returned on success.
IRR_PENDING is returned if the channel has not yet been released by the prior application. The *cid_ptr is valid but no other functions may be called until the IRE_GRANT event is received to indicate a state change from IRS_INIT_PENDING to IRS_IDLE.
IRR_FAIL is returned if an error occurs.
irError is set as follows if an error occurs:
IRER_INVALID if the channel_nbr specifies an invalid channel or if the cid_ptr is NULL
IRER_NOREGISTER if the process has not previously called irRegister(3IRAPI)
IRER_PREVIOUS_INIT if the channel has already been initialized. If a process attempts to initialize a channel it already has a cid for, but does not think it should, it should irDeinit(3IRAPI) or irReturn(3IRAPI) the cid.
IRER_SYSERROR if a system or driver call failure occurs (see irSysError for additional information)
Note the use of "&" before the cid argument to irForceInit in the following example:
int channel_nbr;
channel_id cid;
int retval;
int tag;
...
retval = irForceInit(channel_nbr, &cid, tag);
switch (retval) {
case IRR_FAIL:
<report failure as appropriate>
break;
case IRR_OK:
irChanOOS(cid);
break;
case IRR_PENDING:
<wait for IRE_GRANT event>
break;
}
...
irDeinit(3IRAPI), irReturn(3IRAPI), irInit(3IRAPI), irChanOOS(3IRAPI).
This is version 12/16/02 of this man page.