NAME
          irReserveResource - reserve resources for later use

     SYNOPSIS
          #include <irapi.h>

          int irReserveResource (channel_id cid, int tag, ir_reserve_t
          *presources, long mode, int *failure);

          int irReservedResourceNumber (channel_id cid, int
          capability, int implementation);

     DESCRIPTION
          The irReserveResource function acquires or allocates one or
          more resources for later use on a particular voice channel
          (cid).  Only one resource of each type
          (capability/implementation) may be reserved per channel.

          Normally, a process automatically allocates a single
          resource by using it.  For example, playing a voice file
          uses (allocates) the resources necessary to play the file
          and performing speech recognition allocates ASR resources.
          A resource then is deallocated automatically after using it.
          irReserveResource allows an application to insure that a
          resource is available before using it.  Typically this
          should be done immediately after channel initialization [
          irInit(3IRAPI)].  The application frees the resource when it
          is no longer required by calling irFreeResource(3IRAPI).

          If irReserveResource succeeds, the requested resources are
          dedicated to the channel.  Other channels can not access
          this channel's allocated resource until either the owner
          relinquishes control [via irFreeResource(3IRAPI)], the chan-
          nel is released via irDeinit(3IRAPI)irReturn(3IRAPI), or the
          channel owner exit(2)s.  Since this dedication can cause
          requests for resources from other channels to fail that nor-
          mally would succeed, irReserveResource should be used with
          care.  In general, an application that uses
          irReserveResource uses more resources than an application
          that does not.

          tag is a user supplied number that associates the irReser-
          veResource call with a subsequent event.

          presources is a pointer to an array of
          capability/implementation pairs to be allocated.  If imple-
          mentation is set to IRD_INVALID, the implementation specific
          switch parameter [see IrRESOURCES(4IRAPI)] is referenced to
          determine the implementation.  A capability of IRC_NULL
          indicates the end of the list.

          If the requested resources are available, irReserveResource
          returns IRR_OK.  mode defines the return operation of
          irReserveResource when the requested resource is not immedi-
          ately available:

          IRD_IMMEDIATE  If the requested resources are not available,
                         irReserveResource returns IRR_FAIL.

          Once irReserveResource is called, no other processing can be
          done on the cid until the request for reserve is complete as
          the channel is placed in the IRS_RESERVING library state.

          failure contains an index into the reserve array indicating
          the element which could not be allocated.

          The reserved resources are preserved across irExec(3IRAPI)
          and irSubProg(3IRAPI) boundaries.

          A call to irDeinit(3IRAPI) cancels pending resource
          requests.

          irReservedResourceNumber returns the resource number of the
          resource reserved by irReserveResource.

     EVENT
          No events are generated by irReservedResource and 
	  irReservedResourceNumber.

     RETURN VALUE
          irReserveResource has the following return codes:

          IRR_OK is returned if the request is successful.

          IRR_FAIL is returned if an error occurs.  On a multi-
          resource request, all successful intermediate resource allo-
          cation made by the current call to irReserveResource before
          failure is freed before irReserveResource returns.  That is,
          failure implies complete failure.

          irReservedResourceNumber returns the resource number for the
          resource previously reserved for capability and implementa-
          tion.  If there is no such resource then IRR_FAIL is
          returned.

     ERROR
          irError is set as follows if an error occurs:

          IRER_INVALID if the cid, mode or some capability in
          presources is not valid

          IRER_SYSERROR if a system or driver call failure occurs
          (check irSysError for additional information)

          IRER_RTU_BUSY if the required Feature License's are all in
          use and IRP_RESOURCE_RETURNMODE is set to IRD_IMMEDIATE

          IRER_NO_RTU if no Feature License has been purchased for
          this function

          IRER_RESOURCEBUSY if there are no resources available and
          IRP_RESOURCE_RETURNMODE is set to IRD_IMMEDIATE

          IRER_NORESOURCES if no resources exist with the indicated
          capability

          IRER_BADSTATE if the cid is not in the IRS_IDLE,
          IRS_PLAY_QUEUED, or IRS_SAY_QUEUED state

     CAVEAT
          Use of this function is not mandatory.  It is provided for
          special cases where it is desirable to reserve resources in
          advance.  Otherwise, all IRAPI functions implicitly reserve
          resources when needed.

          IRER_NODATA if the resource list specified by presources is
          empty (ie. the first capability specified is IRC_NULL).
          IRER_NOTCOLLOCATED if a resource allocation for echo cancel-
          lation or recognition failed because IRP_RESOURCE_MASK was
          set to other than IRD_ANY_RESOURCE.  The application may
          want to reset IRP_RESOURCE_MASK to IRD_ANY_RESOURCE or some
          other value and retry the resource allocation.

     SEE ALSO
          irFreeResource(3IRAPI), IrRESOURCES(4IRAPI), irEcho(3IRAPI),
          irRecog(3IRAPI), IrPARAMETERS(4IRAPI)

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