NAME
          irSetParam, irGetParam, irGetChanParam, irSetParamStr,
          irSetParamStrCnt, irGetParamStr, irGetChanParamStr, irInit-
          Param, irInitAllParams - set/get/initialize the value of one
          or more IRAPI library channel-based parameters

     SYNOPSIS
          #include <irapi.h>

          int irGetParam (channel_id cid, int identifier, int *value);

          int irGetChanParam (int chan, int identifier, int *value);

          int irGetParamStr (channel_id cid, int identifier, char
          *value, int count);

          int irGetChanParamStr (int chan, int identifier, char
          *value, int count);

          int irSetParam (channel_id cid, int identifier, intvalue);

          int irSetParamStr (channel_id cid, int identifier, const
          char *value);

          int irSetParamStrCnt (channel_id cid, int identifier, const
          char *value, int count);

          int irInitParam (channel_id cid, int identifier);

          int irInitAllParams (channel_id cid);

     DESCRIPTION
          The irSetParam, irSetParamStr and irSetParamStrCnt functions
          assign values to an IRAPI library parameter for later use on
          the specified channel cid while irGetParam and irGetChan-
          Param get the current value of a parameter. See
          IrPARAMETERS(4IRAPI) for a list of valid parameters and
          their default and legal values.

          The irGetParamStr and irGetChanParamStr copies, at most,
          count bytes into value.  The application developer must ver-
          ify that value is large enough; the number of bytes required
          can be found by calling irGetParamStr or irGetChanParamStr
          with count set to 0.

          irGetParamStr and irGetChanParamStr return exactly count
          bytes of data to the area specified by value.  Since some
          string parameters are actually blocks of data, such as
          IRP_REGISTER, irGetParamStr and irGetChanParamStr ignore any
          NULL characters in the parameter data.  They also makes no
          attempt to NULL terminate the string.  irSetParamStr and
          irSetParamStrCnt also ignore NULL characters and copy the
          number of bytes for the parameter [specified in
          IrPARAMETERS(4IRAPI) or through count] into the call pro-
          file.  Use irSetParamStr only with pointers to data objects
          at least as large as the size requirements specified in
          IrPARAMETERS(4IRAPI).  irSetParamStrCnt copies only count
          bytes of data beginning at the address specified by value,
          therefore, value need only point to an area of size count.

          irInitParam allows an application to set parameter
          identifier back to its default value for channel cid.

          irInitAllParams allows an application to set all parameters
          for the cid to default values.

          Parameters are preserved across irExec(3IRAPI) and
          irSubProg(3IRAPI) boundaries.

          irGetChanParam and irGetChanParamStr are identical to irGet-
          Param and irGetParamStr, respectively, except they get
          parameters from the call profile of the specified channel.
          Only "save-on-exec" parameters which are stored in the chan-
          nel call profile are available to irGetChanParam and
          irGetChanParamStr.

     EXAMPLE
          The following example shows an application that wants to
          record speech. It uses irGetParam and irSetParam to first
          check current values of two recording parameters, sets the
          parameters if they are not appropriate, and then calls the
          recording function:
              /* contrived example */
              int value;
              irGetParam (cid, IRP_RECORD_ALGO, &value);
              if ( value != IRA_A_CS16 )
                  irSetParam(cid, IRP_RECORD_ALGO, IRA_A_CS16 );
              irGetParam (cid, IRP_RECORD_TONE, &value );
              if ( value != IRD_ON )
                  irSetParam(cid, IRP_RECORD_TONE, IRD_ON);
              irFRecord (cid, tag, vfile, cnt);

     RETURN VALUE
          irGetParamStr and irGetChanParamStr return the number of
          bytes copied to value if count is positive.  If count is 0,
          the number of bytes that would have been copied to value is
          returned.

          irGetParam, irGetChanParam, irSetParam, and irSetParamStr
          return IRR_OK if successful.

          All functions return IRR_FAIL if an error occurs.

     ERROR
          irError is set as follows if an error occurs:

          IRER_INVALID if the cid is not valid, if the identifier is
          not valid, if count is negative or if value is not valid for
          identifier

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

          IRER_UNSUPPORTED if irGetChanParam or irGetChanParamStr are
          called for non-"save-on-exec" parameters.

     WARNING
          Use irGetParamStr and irSetParamStr only with pointers to
          data objects at least as large as the size requirements
          specified in IrPARAMETERS(4IRAPI) otherwise memory faults
          may occur.  For example the following:

               irSetParamStr( cid, IRP_DNIS, "" );

          should not be used, instead use:

               irSetParamStrCnt( cid, IRP_DNIS, "", 1 );

          and similarly for all other string parameters.

     SEE ALSO
          IrPARAMETERS(4IRAPI), irGlobalParam(3IRAPI)

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