NAME
          irServiceState - return the service state of a channel

     SYNOPSIS
          #include <irapi.h>

          int irServiceState (channel_id cid);

     DESCRIPTION
          The irServiceState function returns the service state iden-
          tifier associated with the channel identifier (cid). The two
          most likely service states are IRD_ACTIVE and IRD_INACTIVE.
          These are analogous to a channel being off-hook or on-hook,
          respectively.  Additional service states are described below
          and in IrDEFINES(4IRAPI).

          In general applications should react to reported events
          without needing to check the service state.  Knowing the
          service state is useful when investigating
          IRER_SERVICE_STATE errors.  That information often can be
          obtained by tracing the application that encounters the
          error.

          The currently defined service states may be changed in
          future releases and additional service states may be pro-
          vided by add on packages.

          Some service states currently apply to all telephony types.
          IRD_INACTIVE means that a channel is idle or on-hook and
          available for use.  IRD_RINGING means that a channel has
          detected an incoming call and is ready for the channel to be
          answered with irAnswer(3IRAPI).  IRD_ACTIVE means that the
          channel is off-hook or active.  IRD_CHAN_OOS means that the
          channel is out of service [owned by maintenance (MTC)].

          Some service states are specific to the primary rate inter-
          face (PRI).  IRD_WAIT_IDLE indicates that the IRAPI is wait-
          ing for the network to complete the clearing of the channel.
          IRD_REMOTE_DISCON indicates that the remote end has discon-
          nected.  IRD_REMOTE_IDLE indicates that the call has been
          cleared from the network perspective, but the library is
          waiting for the IRAPI application to disconnect.
          IRD_WAIT_ANI indicates that an incoming call is coming in,
          but the IRAPI library is waiting for the switch to provide
          the ANI requested on a call-by-call basis.  IRD_WAIT_DNIS
          may be used in the future to support Overlap Receiving and
          will be used to indicate that an incoming call is coming in,
          but the IRAPI library is waiting for the switch to provide
          the DNIS which was not provided in the SETUP message.

          IRD_WAIT_DNIS is used with Adjunct/Switch Application Inter-
          face (ASAI) channels and indicates that the IRAPI is waiting
          for the dialed number identification service (DNIS) and
          automatic number identification (ANI) information to be pro-
          vided via the basic rate interface (BRI) D channel.

     EVENT
          No event is generated as a result of the call to irService-
          State.

     RETURN VALUE
          irServiceState returns a service state, such as IRD_INACTIVE
          or IRD_ACTIVE, if successful.

          IRR_FAIL is returned if an error occurs.

     ERROR
          irError is set to IRER_INVALID if the cid is invalid.

     SEE ALSO
          irLibState(3IRAPI), irName(3IRAPI).

     VERSION
          This is version 11/25/02 of this man page.