/*<html><pre>*/
#ifndef   V_IOCTL_H
#define   V_IOCTL_H

/*  Codes for pctl_get_type */
#define PCTL_BLOCK_DEVICE   1   /* device can 'seek' */
#define PCTL_SUPPORT_MMAP   2   /* device can be mmap()'ed */

/*
 *  Defined generic IO port IOCTL's to pass to fileControl().
 *  Note: mentioned below return values defined for inner ioctl()'s;
 *  when port->ioctl() returns zero, fileControl() returns 'true',
 *  otherwise fileControl() complains and returns 'false'.
 *  ----------------------------------------------------------------------
 *  pctl_get_type
 *  Provides client with information about type of the data stream.
 *  IOCTL (internal) return code: 0 on success.
 *  Parameters: 'data' must be set to address of the 32-bit integer. Upon
 *  successful exit, type of stream stored in that variable.
 *  ----------------------------------------------------------------------
 *  pctl_map_ispace
 *  Returns base address of the stream data.
 *  IOCTL (internal) return code: 0 on success.
 *  Parameters: 'data' must be set to address of 'void*' pointer. Upon
 *  successful exit, base address of data stored in that variable.
 *  ----------------------------------------------------------------------
 *  pctl_comm_reset (COM ports only)
 *  Cancels any pending IO request. Returns 0 on success.
 *  Parameters: not used.
 *  ----------------------------------------------------------------------
 *  pctl_wave_get_num_channels (WAV file I/O channels only)
 *  Returns number of audio channels.
 *  Parameters: 'data' must be pointer to 32-bit unsigned.
 *  ----------------------------------------------------------------------
 *  pctl_wave_get_sampling_frequency (WAV file I/O channels only)
 *  Returns sampling frequency.
 *  Parameters: 'data' must be pointer to 32-bit unsigned.
 *  ----------------------------------------------------------------------
 *  pctl_wave_get_bits_per_sample (WAV file I/O channels only)
 *  Returns number of bits per sample.
 *  Parameters: 'data' must be pointer to 32-bit unsigned.
 *  ----------------------------------------------------------------------
 *  pctl_wave_get_num_samples (WAV file I/O channels only)
 *  Returns number of samples in file.
 *  Parameters: 'data' must be pointer to 32-bit unsigned.
 *  ----------------------------------------------------------------------
 *  pctl_wave_loop (WAV file I/O channels only)
 *  Sets normal / circular input mode.
 *  Parameters: NULL for normal mode, any other - for loop mode.
 *  ----------------------------------------------------------------------
 *  pctl_waveout_wait (wave output I/O channels only)
 *  Suspends execution of caller thread until data writing in progress.
 *  Returns: -1: wait failed, 0 - no pending data.
 *  Parameters: 'data' can be pointer to 32-bit unsigned number of
 *  maximum timeout.
 *  ----------------------------------------------------------------------
 *  pctl_waveout_pause (wave output I/O channels only)
 *  Suspends wave playback.
 *  Retuns: 0 on success.
 *  Parameters: none.
 *  ----------------------------------------------------------------------
 *  pctl_waveout_resume (wave output I/O channels only)
 *  Resumes wave playback.
 *  Retuns: 0 on success.
 *  Parameters: none.
 *  ----------------------------------------------------------------------
 *  pctl_waveout_reset (wave output I/O channels only)
 *  Purges all panding data and stops wave playback.
 *  Retuns: 0 on success.
 *  Parameters: none.
 *  ----------------------------------------------------------------------
 *  pctl_waveout_get_pending_samples
 *  Returns write queue length, in samples.
 *  Parameters: 'data' must be pointer to 32-bit unsigned integer.
 *  Retun value: 0 on success.
 */

typedef enum
{
  /* IOCTL codes for generic files returned by fileOpenXXX() */
  pctl_get_type,        /* type of stream */
  pctl_map_ispace,      /* mmap() input space */
  /* IOCTL for COM port handle, returned by commOpen() */
  pctl_comm_reset,      /* reset port */
  /* IOCTL codes for "WAV file" and - TODO !!! - "Wave capture" */
  pctl_wave_get_num_channels,
  pctl_wave_get_sampling_frequency,
  pctl_wave_get_bits_per_sample,
  pctl_wave_get_num_samples,
  pctl_wave_loop,
  /* wave out channels */
  pctl_waveout_wait,
  pctl_waveout_pause,
  pctl_waveout_resume,
  pctl_waveout_reset,
  pctl_waveout_get_pending_samples,
  /* IOCTL limit - used for error detection */
  pctl_max_code
} pctl_contol_codes;

#endif  /* V_IOCTL_H */
