Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIBCW(3)		   Library Functions Manual		      LIBCW(3)

NAME
       libcw - general purpose Morse code functions library

SYNOPSIS
       #include	<libcw.h>

       int cw_generator_new(int	audio_system, const char *device)
       void cw_generator_delete(void)
       int cw_generator_start(void)
       void cw_generator_stop(void)
       int cw_set_send_speed(int new_value)
       int cw_set_frequency(int	new_value)
       int cw_set_volume(int new_value)
       int cw_set_gap(int new_value)
       int cw_set_weighting(int	new_value)
       int cw_get_send_speed(void)
       int cw_get_frequency(void)
       int cw_get_volume(void)
       int cw_get_gap(void)
       int cw_get_weighting(void)
       void cw_get_send_parameters(int *dot_usecs, int *dash_usecs,
				   int *end_of_element_usecs,
				       int     *end_of_character_usecs,	   int
       *end_of_word_usecs,
				     int   *additional_usecs,	int   *adjust-
       ment_usecs)
       int cw_send_dot(void)
       int cw_send_dash(void)
       int cw_send_character_space(void)
       int cw_send_word_space(void)
       int cw_send_representation(const	char *representation)
       int cw_send_representation_partial(const	char *representation)
       int cw_send_character(char c)
       int cw_send_character_partial(char c)
       int cw_send_string(const	char *string)
       void cw_reset_send_receive_parameters(void)
       const char *cw_get_console_device(void)
       const char *cw_get_soundcard_device(void)
       const char *cw_generator_get_audio_system_label(void)
       int  cw_register_tone_queue_low_callback(void  (*callback_func)(void*),
       void *callback_arg, int level)
       bool cw_is_tone_busy(void)
       int cw_wait_for_tone(void)
       int cw_wait_for_tone_queue(void)
       int cw_wait_for_tone_queue_critical(int level)
       bool cw_is_tone_queue_full(void)
       int cw_get_tone_queue_capacity(void)
       int cw_get_tone_queue_length(void)
       void cw_flush_tone_queue(void)
       void cw_reset_tone_queue(void)
       int cw_queue_tone(int usecs, int	frequency)
       int cw_set_receive_speed(int new_value)
       int cw_get_receive_speed(void)
       int cw_set_tolerance(int	new_value)
       int cw_get_tolerance(void)
       void cw_get_receive_parameters(int *dot_usecs, int *dash_usecs,
				      int *dot_min_usecs, int *dot_max_usecs,
					   int	    *dash_min_usecs,	   int
       *dash_max_usecs,
				      int *end_of_element_min_usecs,
				      int *end_of_element_max_usecs,
				      int *end_of_element_ideal_usecs,
				      int *end_of_character_min_usecs,
				      int *end_of_character_max_usecs,
				      int *end_of_character_ideal_usecs,
				      int *adaptive_threshold)
       int cw_set_noise_spike_threshold(int new_value)
       int cw_get_noise_spike_threshold(void)
       void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
				       double *element_end_sd, double *charac-
       ter_end_sd)
       void cw_reset_receive_statistics(void)
       void cw_enable_adaptive_receive(void)
       void cw_disable_adaptive_receive(void)
       bool cw_get_adaptive_receive_state(void)
       int cw_start_receive_tone(const struct timeval *timestamp)
       int cw_end_receive_tone(const struct timeval *timestamp)
       int cw_receive_buffer_dot(const struct timeval *timestamp)
       int cw_receive_buffer_dash(const	struct timeval *timestamp)
       int cw_receive_representation(const struct timeval *timestamp,
				     /*	out */ char *representation,
				     /*	out */ bool *is_end_of_word,
				     /*	out */ bool *is_error)
       int cw_receive_character(const struct timeval *timestamp,
				/* out */ char *c,
				/* out */ bool *is_end_of_word,
				/* out */ bool *is_error)
       void cw_clear_receive_buffer(void)
       int cw_get_receive_buffer_capacity(void)
       int cw_get_receive_buffer_length(void)
       void cw_reset_receive(void)
       void  cw_register_keying_callback(void  (*callback_func)(void*,	 int),
       void *callback_arg)
       void cw_enable_iambic_curtis_mode_b(void)
       void cw_disable_iambic_curtis_mode_b(void)
       int cw_get_iambic_curtis_mode_b_state(void)
       int  cw_notify_keyer_paddle_event(int  dot_paddle_state,	 int dash_pad-
       dle_state)
       int cw_notify_keyer_dot_paddle_event(int	dot_paddle_state)
       int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
       void   cw_get_keyer_paddles(int	 *dot_paddle_state,   int   *dash_pad-
       dle_state)
       void   cw_get_keyer_paddle_latches(int	*dot_paddle_latch_state,   int
       *dash_paddle_latch_state)
       bool cw_is_keyer_busy(void)
       int cw_wait_for_keyer_element(void)
       int cw_wait_for_keyer(void)
       void cw_reset_keyer(void)
       int cw_notify_straight_key_event(int key_state)
       int cw_get_straight_key_state(void)
       bool cw_is_straight_key_busy(void)
       void cw_reset_straight_key(void)
       bool cw_is_alsa_possible(const char *device)
       bool cw_is_console_possible(const char *device)
       int cw_console_write(cw_gen_t *gen, cw_tone_t *tone)
       int cw_get_character_count(void)
       void cw_list_characters(char *list)
       int cw_get_maximum_representation_length(void)
       int cw_lookup_character(char c, char *representation)
       char *cw_character_to_representation(int	c)
       int cw_check_representation(const char *representation)
       bool cw_representation_is_valid(const char *representation)
       int cw_lookup_representation(const char *representation,	char *c)
       int cw_representation_to_character(const	char *representation)
       int cw_get_procedural_character_count(void)
       void cw_list_procedural_characters(char *list)
       int cw_get_maximum_procedural_expansion_length(void)
       int  cw_lookup_procedural_character(char	 c,   char   *expansion,   int
       *is_usually_expanded)
       int cw_get_maximum_phonetic_length(void)
       int cw_lookup_phonetic(char c, char *phonetic)
       bool cw_character_is_valid(char c)
       bool cw_string_is_valid(const char *string)
       void cw_debug_flush(cw_debug_t *debug)
       void cw_set_debug_flags(uint32_t	flags)
       void cw_debug_set_flags(cw_debug_t *debug_object, uint32_t flags)
       uint32_t	cw_get_debug_flags(void)
       uint32_t	cw_debug_get_flags(cw_debug_t *debug_object)
       bool cw_debug_has_flag(cw_debug_t *debug_object,	uint32_t flag)
       int  cw_generator_set_tone_slope(cw_gen_t  *gen,	 int  slope_shape, int
       slope_len)
       bool cw_is_oss_possible(const char *device)
       bool cw_is_pa_possible(const char *device)
       void cw_block_callback(int block)
       int   cw_register_signal_handler(int   signal_number,   void    (*call-
       back_func)(int))
       int cw_unregister_signal_handler(int signal_number)
       int cw_version(void)
       void cw_license(void)
       const char *cw_get_audio_system_label(int audio_system)
       void cw_get_speed_limits(int *min_speed,	int *max_speed)
       void cw_get_frequency_limits(int	*min_frequency,	int *max_frequency)
       void cw_get_volume_limits(int *min_volume, int *max_volume)
       void cw_get_gap_limits(int *min_gap, int	*max_gap)
       void cw_get_tolerance_limits(int	*min_tolerance,	int *max_tolerance)
       void cw_get_weighting_limits(int	*min_weighting,	int *max_weighting)
       void cw_complete_reset(void)

   DESCRIPTION
       libcw  is a general purpose CW (Morse code) functions library.  It con-
       tains routines for converting characters	into  Morse  code  representa-
       tions  and  back	 again,	for sending Morse code characters, and for re-
       ceiving characters.  It also contains routines  to  emulate  an	Iambic
       Morse keyer, and	a straight key.

       The  library  can be included in	any program that wishes	to make	use of
       these features.	It forms the heart of three Morse code tutor  applica-
       tions that accompany the	package	in which it is distributed.

       See  the	 cw(7) man page	for information	on Morse code timings, and the
       dot and dash representations for	the various Morse characters.

   TONE	QUEUE
       libcw contains an inbuilt tone queue.  The queue	is  emptied  by	 back-
       ground processing, using	SIGALRM	calls and itimers, so a	caller program
       can continue with other tasks while the library sends  tones  and  keys
       any external device.

       As  well	 as  being used	by the library functions that sound Morse code
       characters and provide a	keyer sidetone,	the primitive tone queue func-
       tions are publicly available to caller programs.

   CONTROLLING AN EXTERNAL DEVICE
       libcw  may  be  passed the address of a function	that controls external
       keying.	This function is called	each time the library changes the key-
       ing state, either as a result of	sending	a Morse	character or represen-
       tation, or as a result of an iambic keyer or straight key state change.
       The  argument  passed is	a single integer, TRUE for key-down, and FALSE
       for key-up.

       libcw calls the external	keying function	only  when  the	 keying	 state
       changes.	  A  call  is  likely  each  time a tone is taken off the tone
       queue.

   SENDING CW CHARACTERS AND STRINGS
       libcw offers several functions  that  send  individual  characters  and
       character  strings  as Morse code.  It also offers functions that allow
       specialized 'representations' to	be sent.   A  'representation'	is  an
       ASCII string that consists of only the characters '.' and '-'.

       Characters and strings are converted into representations, and then the
       correct tones for the dots and  dashes  in  these  representations  are
       queued  on  the tone queue, for action by the background	queue emptying
       process.

   RECEIVING CW	CHARACTERS AND REPRESENTATIONS
       libcw contains functions	to allow it to receive	Morse  code.   To  re-
       ceive, the library must be told when a tone start is detected, and when
       a tone end is detected.	It then	determines whether the tone was	a  dot
       or  a  dash  depending on the timing difference between the two.	 After
       the required silence gap	has passed, the	library	may be queried to  see
       what the	received representation	or character was.

       Errors  in  receiving may be detected by	means of the flags passed back
       on receive character functions.

   IAMBIC KEYER
       libcw offers functions to simulate an Iambic Morse keyer.   The	caller
       program	needs  to  tell	 the  library of paddle	state changes.	Iambic
       keyer functions are mutually exclusive with character send and straight
       key functions.

   STRAIGHT KEY
       libcw  offers  simple  functions	 to  allow  effective  pass-through of
       straight	key information.  The caller program needs to tell the library
       of  key	state  changes.	 Straight key functions	are mutually exclusive
       with character send and iambic keyer functions.

   RETURN CODES
       Some of the library's function return a return code of type  int.   The
       return  code  has  two  values,	as  defined  in	libcw.h: CW_SUCCESS or
       CW_FAILURE. The two symbolic constants are guaranteed to	 be  identical
       to boolean true and false.

   FUNCTIONS
       The following list describes the	functions available to a libcw caller:

       int cw_generator_new(int	audio_system, const char *device)
       Brief: Create new generator

       Allocate	memory for new generator data structure, set up	default	values
       of some of the generator's properties.  The function does not start the
       generator (generator does not produce a sound), you have	to use cw_gen-
       erator_start() for this.

       Notice that the function	doesn't	return a generator variable. There  is
       at  most	 one  generator	variable at any	given time. You	can't have two
       generators. In some future version of the library the function will re-
       turn  pointer  to newly allocated generator, and	then you could have as
       many of them as you want, but not yet.

       audio_system can	 be  one  of  following:  NULL,	 console,  OSS,	 ALSA,
       PulseAudio, soundcard. See "enum	cw_audio_systems" in libcw.h for exact
       names of	symbolic constants.

       Parameter: audio_system - audio system to be used by the	generator
       Parameter: device - name	of audio device	to be used; if NULL  then  li-
       brary will use default device.

       void cw_generator_delete(void)
       Brief: Deallocate generator

       Deallocate/destroy  generator  data  structure  created	with  call  to
       cw_generator_new(). You can't start nor use  the	 generator  after  the
       call to this function.

       int cw_generator_start(void)
       Brief: Start a generator

       Start  producing	tones using generator created with cw_generator_new().
       The source of tones is a	tone queue associated with the	generator.  If
       the  tone  queue	 is empty, the generator will wait for new tones to be
       queued.

       Returns:	CW_FAILURE on errors
       Returns:	CW_SUCCESS on success

       void cw_generator_stop(void)
       Brief: Shut down	a generator

       Silence tone generated by generator (level of generated	sine  wave  is
       set to zero, with falling slope), and shut the generator	down.

       The shutdown does not erase generator's configuration.

       If  you	want  to  have	this generator running again, you have to call
       cw_generator_start().

       int cw_set_send_speed(int new_value)
       Brief: Set sending speed	of generator

       See  libcw.h/CW_SPEED_{INITIAL|MIN|MAX}	 for   initial/minimal/maximal
       value of	send speed.

       errno is	set to EINVAL if new_value is out of range.

       Parameter: new_value - new value	of send	speed to be assigned to	gener-
       ator

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_set_frequency(int	new_value)
       Brief: Set frequency of generator

       Set frequency of	sound wave generated by	generator.  The	frequency must
       be within limits	marked by CW_FREQUENCY_MIN and CW_FREQUENCY_MAX.

       See  libcw.h/CW_FREQUENCY_{INITIAL|MIN|MAX} for initial/minimal/maximal
       value of	frequency.

       errno is	set to EINVAL if new_value is out of range.

       Parameter: new_value - new value	of frequency to	be assigned to genera-
       tor

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_set_volume(int new_value)
       Brief: Set volume of generator

       Set  volume  of	sound wave generated by	generator.  The	volume must be
       within limits marked by CW_VOLUME_MIN and CW_VOLUME_MAX.

       Note that volume	settings  are  not  fully  possible  for  the  console
       speaker.	 In this case, volume settings greater than zero indicate con-
       sole speaker sound is on, and setting volume to zero will turn off con-
       sole speaker sound.

       See   libcw.h/CW_VOLUME_{INITIAL|MIN|MAX}  for  initial/minimal/maximal
       value of	volume.	 errno is set to EINVAL	if new_value is	out of range.

       Parameter: new_value - new value	of volume to be	assigned to generator

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_set_gap(int new_value)
       Brief: Set sending gap of generator

       See libcw.h/CW_GAP_{INITIAL|MIN|MAX} for	initial/minimal/maximal	 value
       of gap.	errno is set to	EINVAL if new_value is out of range.

       Notice  that  this  function also sets the same gap value for library's
       receiver.

       Parameter: new_value - new value	of gap to be assigned to generator

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_set_weighting(int	new_value)
       Brief: Set sending weighting for	generator

       See libcw.h/CW_WEIGHTING_{INITIAL|MIN|MAX} for  initial/minimal/maximal
       value  of  weighting.   errno  is  set to EINVAL	if new_value is	out of
       range.

       Parameter: new_value - new value	of weighting to	be assigned for	gener-
       ator

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_get_send_speed(void)
       Brief: Get sending speed	from generator

       Returns:	current	value of the generator's send speed

       int cw_get_frequency(void)
       Brief: Get frequency from generator

       Function	returns	"frequency" parameter of generator, even if the	gener-
       ator is stopped,	or volume of generated sound is	zero.

       Returns:	current	value of generator's frequency

       int cw_get_volume(void)
       Brief: Get sound	volume from generator

       Function	returns	"volume" parameter of generator, even if the generator
       is stopped.

       Returns:	current	value of generator's sound volume

       int cw_get_gap(void)
       Brief: Get sending gap from generator

       Returns:	current	value of generator's sending gap

       int cw_get_weighting(void)
       Brief: Get sending weighting from generator

       Returns:	current	value of generator's sending weighting

       void cw_get_send_parameters(int *dot_usecs, int *dash_usecs,
				int *end_of_element_usecs,
				     int      *end_of_character_usecs,	   int
       *end_of_word_usecs,
				int *additional_usecs, int *adjustment_usecs)
       Brief: Get timing parameters for	sending

       Return the low-level timing parameters calculated from the speed,  gap,
       tolerance,  and	weighting  set.	  Parameter values are returned	in mi-
       croseconds.

       Use NULL	for the	pointer	argument to any	parameter value	not required.

       Parameter: dot_usecs
       Parameter: dash_usecs
       Parameter: end_of_element_usecs
       Parameter: end_of_character_usecs
       Parameter: end_of_word_usecs
       Parameter: additional_usecs
       Parameter: adjustment_usecs

       int cw_send_dot(void)
       Brief: Low-level	primitive for sending a	dot mark

       Low-level primitive function able to play/send  single  dot  mark.  The
       function	 appends to a tone queue a normal inter-mark gap after the dot
       mark.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_dash(void)
       Brief: Low-level	primitive for sending a	dash mark

       Low-level primitive function able to play/send single dash  mark.   The
       function	appends	to a tone queue	a normal inter-mark gap	after the dash
       mark.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_character_space(void)

       The function plays space	timed to exclude the expected  prior  dot/dash
       inter-mark gap.	FIXME: fix this	description.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_word_space(void)

       The  function  sends  space  timed  to  exclude both the	expected prior
       dot/dash	inter-mark gap and the prior end of character  space.	FIXME:
       fix this	description.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_representation(const	char *representation)
       Brief: Check, then send the given string	as dots	and dashes.

       The  representation passed in is	assumed	to be a	complete Morse charac-
       ter; that is, all post-character	delays will be added when the  charac-
       ter is sent.

       On  success,  the  routine  returns CW_SUCCESS.	On failure, it returns
       CW_FAILURE, with	errno set to EINVAL if any character of	the  represen-
       tation  is invalid, EBUSY if the	sound card, console speaker, or	keying
       system is busy, or EAGAIN if the	tone queue is full, or if there	is in-
       sufficient space	to queue the tones or the representation.

       Parameter: representation - representation to send

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_representation_partial(const	char *representation)
       Brief: Check, then send the given string	as dots	and dashes

       The  representation  passed  in	is assumed to be only part of a	larger
       Morse representation; that is, no post-character	delays will  be	 added
       when the	character is sent.

       On  success,  the  routine  returns CW_SUCCESS.	On failure, it returns
       CW_FAILURE, with	errno set to EINVAL if any character of	the  represen-
       tation  is invalid, EBUSY if the	sound card, console speaker, or	keying
       system is busy, or EAGAIN if the	tone queue is full, or if there	is in-
       sufficient space	to queue the tones for the representation.

       int cw_send_character(char c)
       Brief: Look up and send a given ASCII character as Morse

       The end of character delay is appended to the Morse sent.

       On success the routine returns CW_SUCCESS.  On failure the function re-
       turns CW_FAILURE	and sets errno.

       errno is	set to ENOENT if the given character c is not  a  valid	 Morse
       character.   errno is set to EBUSY if current audio sink	or keying sys-
       tem is busy.  errno is set to EAGAIN if the generator's tone  queue  is
       full,  or  if  there  is	 insufficient space to queue the tones for the
       character.

       This routine returns as soon as the  character  has  been  successfully
       queued  for  sending;  that is, almost immediately.  The	actual sending
       happens	in  background	 processing.	See   cw_wait_for_tone()   and
       cw_wait_for_tone_queue()	for ways to check the progress of sending.

       Parameter: c - character	to send

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_character_partial(char c)
       Brief: Look up and send a given ASCII character as Morse	code

       "partial"  means	 that  the "end	of character" delay is not appended to
       the Morse code sent by the function, to support the formation of	combi-
       nation characters.

       On  success  the	 function returns CW_SUCCESS.  On failure the function
       returns CW_FAILURE and sets errno.

       errno is	set to ENOENT if the given character c is not  a  valid	 Morse
       character.  errno is set	to EBUSY if the	audio sink or keying system is
       busy.  errno is set to EAGAIN if	the tone queue is full,	or if there is
       insufficient space to queue the tones for the character.

       This  routine  queues  its  arguments  for  background processing.  See
       cw_wait_for_tone() and cw_wait_for_tone_queue() for ways	to  check  the
       progress	of sending.

       Parameter: c - character	to send

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_send_string(const	char *string)
       Brief: Send a given ASCII string	in Morse code

       errno  is  set  to ENOENT if any	character in the string	is not a valid
       Morse character.

       errno is	set to EBUSY if	audio sink or keying system is busy.

       errno is	set to EAGAIN if the tone queue	is full	or if the  tone	 queue
       runs  out  of  space part way through queueing the string.  However, an
       indeterminate number of the characters from the string  will  have  al-
       ready been queued.

       For  safety, clients can	ensure the tone	queue is empty before queueing
       a string, or use	cw_send_character() if they need finer control.

       This routine queues its arguments for background	processing, the	actual
       sending	happens	 in  background	processing. See	cw_wait_for_tone() and
       cw_wait_for_tone_queue()	for ways to check the progress of sending.

       Parameter: string - string to send

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       void cw_reset_send_receive_parameters(void)
       Brief: Reset send/receive parameters

       Reset the library speed,	frequency, volume, gap,	tolerance,  weighting,
       adaptive	 receive,  and	noise spike threshold to their initial default
       values: send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0
       dots, tolerance 50 %, and weighting 50 %.

       const char *cw_get_console_device(void)
       Brief: Return char string with console device path

       Returned	pointer	is owned by library.

       Returns:	char string with current console device	path

       const char *cw_get_soundcard_device(void)
       Brief: Return char string with soundcard	device name/path

       Returned	pointer	is owned by library.

       Returns:	char string with current soundcard device name or device path

       const char *cw_generator_get_audio_system_label(void)
       Brief: Get a readable label of current audio system

       The  function  returns  one  of following strings: None,	Null, Console,
       OSS, ALSA, PulseAudio, Soundcard

       Returns:	audio system's label

       int  cw_register_tone_queue_low_callback(void  (*callback_func)(void*),
       void *callback_arg, int level)
       Brief: Register callback	for low	queue state

       Register	 a  function to	be called automatically	by the dequeue routine
       whenever	the tone queue falls to	a given	level. To be more precise: the
       callback	 is  called  by	queue manager if, after	dequeueing a tone, the
       manager notices that tone queue length has become equal	or  less  than
       level.

       callback_arg may	be used	to give	a value	passed back on callback	calls.
       A NULL function pointer suppresses callbacks.  On success, the  routine
       returns CW_SUCCESS.

       If  level  is invalid, the routine returns CW_FAILURE with errno	set to
       EINVAL.	Any callback supplied will be called in	 signal	 handler  con-
       text.

       Parameter: callback_func	- callback function to be registered
       Parameter:  callback_arg	 -  argument  for callback_func	to pass	return
       value
       Parameter: level	- low level of queue triggering	callback call

       Returns:	CW_SUCCESS on successful registration
       Returns:	CW_FAILURE on failure

       bool cw_is_tone_busy(void)
       Brief: Check if tone sender is busy

       Indicate	if the tone sender is busy.

       Returns:	true if	there are still	entries	in the tone queue
       Returns:	false if the queue is empty

       int cw_wait_for_tone(void)
       Brief: Wait for the current tone	to complete

       The routine returns CW_SUCCESS on  success.   If	 called	 with  SIGALRM
       blocked,	 the routine returns CW_FAILURE, with errno set	to EDEADLK, to
       avoid indefinite	waits.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_wait_for_tone_queue(void)
       Brief: Wait for the tone	queue to drain

       The routine returns CW_SUCCESS  on  success.  If	 called	 with  SIGALRM
       blocked,	the routine returns false, with	errno set to EDEADLK, to avoid
       indefinite waits.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_wait_for_tone_queue_critical(int level)
       Brief: Wait for the tone	queue to drain until only  as  many  tones  as
       given in	level remain queued

       This routine is for use by programs that	want to	optimize themselves to
       avoid the cleanup that happens when the tone queue  drains  completely;
       such  programs  have  a	short  time  in	which to add more tones	to the
       queue.

       The routine returns CW_SUCCESS on  success.   If	 called	 with  SIGALRM
       blocked,	the routine returns false, with	errno set to EDEADLK, to avoid
       indefinite waits.

       Parameter: level	- low level in queue, at which to return

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       bool cw_is_tone_queue_full(void)
       Brief: Indicate if the tone queue is full

       Returns:	true if	tone queue is full
       Returns:	false if tone queue is not full

       int cw_get_tone_queue_capacity(void)
       Brief: Return the number	of entries the tone queue can accommodate

       int cw_get_tone_queue_length(void)
       Brief: Return the number	of entries currently pending in	the tone queue

       void cw_flush_tone_queue(void)
       Brief: Cancel all pending queued	tones, and return to silence.

       If there	is a tone in progress, the function will wait until this  last
       one has completed, then silence the tones.

       This function may be called with	SIGALRM	blocked, in which case it will
       empty the queue as best it can, then return without waiting for the fi-
       nal  tone to complete.  In this case, it	may not	be possible to guaran-
       tee silence after the call.

       void cw_reset_tone_queue(void)
       Cancel all pending queued tones,	reset any queue	 low  callback	regis-
       tered,  and  return  to silence.	 This function is suitable for calling
       from an application exit	handler.

       int cw_queue_tone(int usecs, int	frequency)
       Brief: Primitive	access to simple tone generation

       This routine queues a tone of given duration and	frequency.   The  rou-
       tine  returns CW_SUCCESS	on success.  If	usec or	frequency are invalid,
       it returns CW_FAILURE with errno	set to EINVAL.	 If  the  sound	 card,
       console	speaker,  or  keying  function are busy, it returns CW_FAILURE
       with errno set to EBUSY.	 If the	tone queue is full, it	returns	 false
       with errno set to EAGAIN.

       Parameter: usecs	- duration of queued tone, in microseconds
       Parameter: frequency - frequency	of queued tone

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_set_receive_speed(int new_value)
       Brief: Set receiving speed of receiver

       See documentation of cw_set_send_speed()	for more information.

       See   libcw.h/CW_SPEED_{INITIAL|MIN|MAX}	  for  initial/minimal/maximal
       value of	receive	speed.	errno is set to	EINVAL if new_value is out  of
       range.  errno is	set to EPERM if	adaptive receive speed tracking	is en-
       abled.

       Parameter: new_value - new value	of receive speed to be assigned	to re-
       ceiver

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_get_receive_speed(void)
       Brief: Get receiving speed from receiver

       Returns:	current	value of the receiver's	receive	speed

       int cw_set_tolerance(int	new_value)
       Brief: Set tolerance for	receiver

       See  libcw.h/CW_TOLERANCE_{INITIAL|MIN|MAX} for initial/minimal/maximal
       value of	tolerance.  errno is set to EINVAL  if	new_value  is  out  of
       range.

       Parameter:  new_value  -	 new  value of tolerance to be assigned	to re-
       ceiver

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_get_tolerance(void)
       Brief: Get tolerance from receiver

       Returns:	current	value of receiver's tolerance

       void cw_get_receive_parameters(int *dot_usecs, int *dash_usecs,
				   int *dot_min_usecs, int *dot_max_usecs,
				   int *dash_min_usecs,	int *dash_max_usecs,
				   int *end_of_element_min_usecs,
				   int *end_of_element_max_usecs,
				   int *end_of_element_ideal_usecs,
				   int *end_of_character_min_usecs,
				   int *end_of_character_max_usecs,
				   int *end_of_character_ideal_usecs,
				   int *adaptive_threshold)
       Brief: Get timing parameters for	receiving, and adaptive	threshold

       Return the low-level timing parameters calculated from the speed,  gap,
       tolerance,  and	weighting  set.	  Parameter values are returned	in mi-
       croseconds.

       Use NULL	for the	pointer	argument to any	parameter value	not required.

       Parameter: dot_usecs
       Parameter: dash_usecs
       Parameter: dot_min_usecs
       Parameter: dot_max_usecs
       Parameter: dash_min_usecs
       Parameter: dash_max_usecs
       Parameter: end_of_element_min_usecs
       Parameter: end_of_element_max_usecs
       Parameter: end_of_element_ideal_usecs
       Parameter: end_of_character_min_usecs
       Parameter: end_of_character_max_usecs
       Parameter: end_of_character_ideal_usecs
       Parameter: adaptive_threshold

       int cw_set_noise_spike_threshold(int new_value)
       Brief: Set noise	spike threshold	for receiver

       Set the period shorter than which, on receive, received marks  are  ig-
       nored.  This allows the "receive	mark" functions	to apply noise cancel-
       ing for very short apparent marks.  For useful results the value	should
       never  exceed the dot length of a dot at	maximum	speed: 20000 microsec-
       onds (the dot length at 60WPM).	Setting	 a  noise  threshold  of  zero
       turns off receive mark noise canceling.

       The default noise spike threshold is 10000 microseconds.

       errno is	set to EINVAL if new_value is out of range.

       Parameter:  new_value  -	 new  value of noise spike threshold to	be as-
       signed to receiver

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_get_noise_spike_threshold(void)
       Brief: Get noise	spike threshold	from receiver

       See documentation of cw_set_noise_spike_threshold() for	more  informa-
       tion

       Returns:	current	value of receiver's threshold

       void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
				    double  *element_end_sd,  double  *charac-
       ter_end_sd)
       Brief: Calculate	and return receiver's timing statistics

       These statistics	may be used to obtain a	measure	of the accuracy	of re-
       ceived CW.  The values dot_sd and dot_sd	contain	the standard deviation
       of dot and dash lengths from the	ideal values, and  element_end_sd  and
       element_end_sd  the  deviations	for  inter element and inter character
       spacing.	 Statistics are	held for all timings in	a 256 element circular
       buffer.	 If any	statistic cannot be calculated,	because	no records for
       it exist, the returned value is 0.0.  Use NULL for the pointer argument
       to any statistic	not required.

       Parameter: dot_sd
       Parameter: dash_sd
       Parameter: element_end_sd
       Parameter: character_end_sd

       void cw_reset_receive_statistics(void)
       Brief: Clear the	receive	statistics buffer

       Clear the receive statistics buffer by removing all records from	it and
       returning it to its initial default state.

       void cw_enable_adaptive_receive(void)
       Brief: Enable adaptive receive speed tracking

       If adaptive speed tracking is enabled, the receive functions  will  at-
       tempt  to  automatically	 adjust	the receive speed setting to match the
       speed of	the incoming Morse code. If it is disabled, the	receive	 func-
       tions will use fixed speed settings, and	reject incoming	Morse which is
       not at the expected speed.

       Adaptive	speed tracking uses a moving average  length  of  the  past  N
       marks  as its baseline for tracking speeds.  The	default	state is adap-
       tive speed tracking disabled.

       void cw_disable_adaptive_receive(void)
       Brief: Disable adaptive receive speed tracking

       See documentation of cw_enable_adaptive_receive() for more information

       bool cw_get_adaptive_receive_state(void)
       Brief: Get adaptive receive speed tracking flag

       The function returns state of "adaptive	receive	 enabled"  flag.   See
       documentation of	cw_enable_adaptive_receive() for more information

       Returns:	true if	adaptive speed tracking	is enabled
       Returns:	false otherwise

       int cw_start_receive_tone(const struct timeval *timestamp)
       Brief: Signal beginning of receive mark

       Called  on  the start of	a receive mark.	 If the	timestamp is NULL, the
       current timestamp is used as beginning of mark.

       The function should be called by	client application when	pressing a key
       down (closing a circuit)	has been detected by client application.

       On  error  the function returns CW_FAILURE, with	errno set to ERANGE if
       the call	is directly after another cw_start_receive_tone() call	or  if
       an existing received character has not been cleared from	the buffer, or
       EINVAL if the timestamp passed in is invalid.

       Parameter: timestamp - time stamp of "key down" event

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE otherwise (with errno set)

       int cw_end_receive_tone(const struct timeval *timestamp)
       Brief: Signal end of mark

       The function should be called by	client application  when  releasing  a
       key (opening a circuit) has been	detected by client application.

       If  the timestamp is NULL, the current time is used as timestamp	of end
       of mark.

       On success, the routine adds a dot or dash to the receiver's  represen-
       tation buffer, and returns CW_SUCCESS.

       On failure, it returns CW_FAIURE, with errno set	to: ERANGE if the call
       was not preceded	by a cw_start_receive_tone() call, EINVAL if the time-
       stamp  passed  in  is  not  valid, ENOENT if the	mark length was	out of
       bounds for the permissible dot and dash lengths and fixed speed receiv-
       ing  is	selected,  ENOMEM  if  the receiver's representation buffer is
       full, EAGAIN if the mark	was shorter than the threshold for  noise  and
       was therefore ignored.

       Parameter: timestamp - time stamp of "key up" event

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_receive_buffer_dot(const struct timeval *timestamp)
       Brief: Add a dot	to the receiver's representation buffer

       Documentation  for  both	 cw_receive_buffer_dot()  and  cw_receive_buf-
       fer_dash():

       Since we	can't add a mark to the	buffer without any accompanying	timing
       information,  the  functions  accepts  timestamp	 of  the "end of mark"
       event.  If the timestamp	is NULL, the current timestamp is used.

       These routines are for client code that has already determined  whether
       a  dot or dash was received by a	method other than calling the routines
       cw_start_receive_tone() and cw_end_receive_tone().

       On success, the relevant	mark is	added to the receiver's	representation
       buffer.

       On failure, the routines	return CW_FAILURE, with	errno set to ERANGE if
       preceded	by a cw_start_receive_tone() call with no matching  cw_end_re-
       ceive_tone()  or	 if an error condition currently exists	within the re-
       ceiver's	buffer,	or ENOMEM if the receiver's representation  buffer  is
       full.

       Parameter: timestamp - timestamp	of "end	of dot"	event

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_receive_buffer_dash(const	struct timeval *timestamp)
       Brief: Add a dash to the	receiver's representation buffer

       See documentation of cw_receive_buffer_dot() for	more information.

       Parameter: timestamp - timestamp	of "end	of dash" event

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_receive_representation(const struct timeval *timestamp,
				  /* out */ char *representation,
				  /* out */ bool *is_end_of_word,
				  /* out */ bool *is_error)
       Brief: Get the current buffered representation from the receiver's rep-
       resentation buffer

       On success the function fills in	representation with  the  contents  of
       the current representation buffer and returns CW_SUCCESS.

       On failure, it returns CW_FAILURE and sets errno	to: ERANGE if not pre-
       ceded by	 a  cw_end_receive_tone()  call,  a  prior  successful	cw_re-
       ceive_representation  call,  or a prior cw_receive_buffer_dot or	cw_re-
       ceive_buffer_dash, EINVAL if the	timestamp passed in is invalid,	EAGAIN
       if the call is made too early to	determine whether a complete represen-
       tation has yet been placed in the buffer	(that is, less than  the  end-
       of-character gap	period elapsed since the last cw_end_receive_tone() or
       cw_receive_buffer_dot/dash call). This is not a *hard* error,  just  an
       information that	the caller should try to get the representation	later.

       is_end_of_word indicates	that the space after the last mark received is
       longer that the end-of-character	gap, so	it must	be qualified  as  end-
       of-word gap.

       is_error	 indicates  that the representation was	terminated by an error
       condition.

       TODO: the function should be called cw_receiver_poll_representation().

       The function is called periodically (poll()-like	 function)  by	client
       code in hope that at some attempt receiver will be ready	to pass	repre-
       sentation. The attempt succeeds only  if	 data  stream  is  in  "space"
       state. To mark end of the space,	client code has	to provide a timestamp
       (or pass	NULL timestamp,	the function will get time stamp  at  function
       call).  The  receiver needs to know the "end of space" event - thus the
       timestamp parameter.

       Parameter: timestamp - timestamp	of event that ends  "end-of-character"
       gap or "end-of-word" gap
       Parameter:  representation  - buffer for	representation (output parame-
       ter)
       Parameter: is_end_of_word - buffer for "is end of word"	state  (output
       parameter)
       Parameter: is_error - buffer for	"error"	state (output parameter)

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_receive_character(const struct timeval *timestamp,
			     /*	out */ char *c,
			     /*	out */ bool *is_end_of_word,
			     /*	out */ bool *is_error)
       Brief: Get a current character

       Function	returns	the character currently	stored in receiver's represen-
       tation buffer.

       On success the function returns CW_SUCCESS, and fills c with  the  con-
       tents  of  the current representation buffer, translated	into a charac-
       ter.

       On failure the function returns CW_FAILURE, with	errno set to:

       ERANGE if not preceded by a cw_end_receive_tone() call,	a  prior  suc-
       cessful	cw_receive_character()	call,  or a cw_receive_buffer_dot() or
       cw_receive_buffer_dash()	call, EINVAL if	the timestamp passed in	is in-
       valid,  or  EAGAIN if the call is made too early	to determine whether a
       complete	character has yet been placed in the  buffer  (that  is,  less
       than  the end-of-character gap period elapsed since the last cw_end_re-
       ceive_tone() or cw_receive_buffer_dot/dash call).  ENOENT if  character
       stored in receiver cannot be recognized as valid

       is_end_of_word indicates	that the space after the last mark received is
       longer that the end-of-character	gap, so	it must	be qualified  as  end-
       of-word gap.

       is_error	indicates that the character was terminated by an error	condi-
       tion.

       Parameter: timestamp - timestamp	of event  that	ends  end-of-character
       gap or end-of-word gap
       Parameter: c - buffer for character (output parameter)
       Parameter:  is_end_of_word  - buffer for	"is end	of word" state (output
       parameter)
       Parameter: is_error - buffer for	"error"	state (output parameter)

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       void cw_clear_receive_buffer(void)
       Brief: Clear receiver's representation buffer

       Clears the receiver's representation buffer, resets receiver's internal
       state. This prepares the	receiver to receive marks and spaces again.

       This  routine  must  be called after successful,	or terminating,	cw_re-
       ceive_representation() or cw_receive_character()	calls,	to  clear  the
       states and prepare the buffer to	receive	more marks and spaces.

       int cw_get_receive_buffer_capacity(void)
       Brief:  Get  the	number of elements (dots/dashes) the receiver's	buffer
       can accommodate

       The maximum number of elements written  out  by	cw_receive_representa-
       tion() is the capacity +	1, the extra character being used for the ter-
       minating	NUL.

       Returns:	number of elements that	can be stored in receiver's  represen-
       tation buffer

       int cw_get_receive_buffer_length(void)
       Brief:  Get  the	 number	of elements (dots/dashes) currently pending in
       the cw_receiver's representation	buffer

       Returns:	number of elements in receiver's representation	buffer

       void cw_reset_receive(void)
       Brief: Clear receive data

       Clear the receiver's representation buffer,  statistics,	 and  any  re-
       tained receiver's state.	 This function is suitable for calling from an
       application exit	handler.

       void  cw_register_keying_callback(void  (*callback_func)(void*,	 int),
       void *callback_arg)
       Brief: Register external	callback function for keying

       Register	a callback_func	function that should be	called when a state of
       a key changes from "key open" to	"key closed", or vice-versa.

       The first argument passed to the	registered callback  function  is  the
       supplied	 callback_arg,	if  any.  The second argument passed to	regis-
       tered  callback	function  is  the   key	  state:   CW_KEY_STATE_CLOSED
       (one/true)  for	"key  closed",	and CW_KEY_STATE_OPEN (zero/false) for
       "key open".

       Calling this routine with a NULL	function address disables keying call-
       backs.	Any callback supplied will be called in	signal handler context
       (??).

       Parameter: callback_func	- callback function to be called on key	 state
       changes
       Parameter: callback_arg - first argument	to callback_func

       void cw_enable_iambic_curtis_mode_b(void)
       Brief: Enable iambic Curtis mode	B

       Normally,  the  iambic  keying functions	will emulate Curtis 8044 Keyer
       mode A.	In this	mode, when both	paddles	are pressed together, the last
       dot  or	dash  being  sent on release is	completed, and nothing else is
       sent. In	mode B,	when both paddles are pressed together,	the  last  dot
       or dash being sent on release is	completed, then	an opposite element is
       also sent. Some operators prefer	mode B,	but timing is more critical in
       this mode. The default mode is Curtis mode A.

       void cw_disable_iambic_curtis_mode_b(void)
       See documentation of cw_enable_iambic_curtis_mode_b() for more informa-
       tion

       int cw_get_iambic_curtis_mode_b_state(void)
       See documentation of cw_enable_iambic_curtis_mode_b() for more informa-
       tion

       int  cw_notify_keyer_paddle_event(int  dot_paddle_state,	 int dash_pad-
       dle_state)
       Brief: Inform about changed state of iambic keyer's paddles

       Function	informs	the library that the iambic keyer paddles have changed
       state.	The  new  paddle states	are recorded, and if either transition
       from false to true, paddle latches, for iambic functions, are also set.

       On success, the routine returns CW_SUCCESS.   On	 failure,  it  returns
       CW_FAILURE,  with  errno	set to EBUSY if	the tone queue or straight key
       are using the sound card, console speaker, or keying system.

       If appropriate, this routine starts the	keyer  functions  sending  the
       relevant	element.  Element send and timing occurs in the	background, so
       this routine returns almost immediately.	  See  cw_keyer_element_wait()
       and  cw_keyer_wait()  for details about how to check the	current	status
       of iambic keyer background processing.

       Parameter: dot_paddle_state
       Parameter: dash_paddle_state

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_notify_keyer_dot_paddle_event(int	dot_paddle_state)
       Brief: Change state of dot paddle

       Alter the state of just one of the two iambic keyer paddles.  The other
       paddle state of the paddle pair remains unchanged.

       See  cw_notify_keyer_paddle_event()  for	 details of iambic keyer back-
       ground processing, and how to check its status.

       Parameter: dot_paddle_state

       int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
       See documentation of cw_notify_keyer_dot_paddle_event() for more	infor-
       mation

       void   cw_get_keyer_paddles(int	 *dot_paddle_state,   int   *dash_pad-
       dle_state)
       Brief: Get the current saved states of the two paddles

       Parameter: dot_paddle_state
       Parameter: dash_paddle_state

       void   cw_get_keyer_paddle_latches(int	*dot_paddle_latch_state,   int
       *dash_paddle_latch_state)
       Brief: Get the current states of	paddle latches

       Function	returns	the current saved states of the	two paddle latches.  A
       paddle latches is set to	true when the paddle state becomes  true,  and
       is cleared if the paddle	state is false when the	element	finishes send-
       ing.

       Parameter: dot_paddle_latch_state
       Parameter: dash_paddle_latch_state

       bool cw_is_keyer_busy(void)
       Brief: Check if a keyer is busy

       Returns:	true if	keyer is busy
       Returns:	false if keyer is not busy

       int cw_wait_for_keyer_element(void)
       Brief: Wait for end of element from the keyer

       Waits until the end of the current  element,  dot  or  dash,  from  the
       keyer.

       On  error the function returns CW_FAILURE, with errno set to EDEADLK if
       SIGALRM is blocked.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_wait_for_keyer(void)
       Brief: Wait for the current keyer cycle to complete

       The routine returns  CW_SUCCESS	on  success.   On  error,  it  returns
       CW_FAILURE,  with  errno	set to EDEADLK if SIGALRM is blocked or	if ei-
       ther paddle state is true.

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       void cw_reset_keyer(void)
       Brief: Reset iambic keyer data

       Clear all latches and paddle states of iambic keyer, return  to	Curtis
       8044  Keyer  mode  A, and return	to silence.  This function is suitable
       for calling from	an application exit handler.

       int cw_notify_straight_key_event(int key_state)
       Brief: Inform the library that the straight key has changed state

       This routine returns CW_SUCCESS	on  success.   On  error,  it  returns
       CW_FAILURE,  with  errno	set to EBUSY if	the tone queue or iambic keyer
       are using the sound card, console speaker, or  keying  control  system.
       If key_state indicates no change	of state, the call is ignored.

       key_state     may    be	  either    CW_KEY_STATE_OPEN	 (false)    or
       CW_KEY_STATE_CLOSED (true).

       Parameter: key_state - state of straight	key

       int cw_get_straight_key_state(void)
       Brief: Get saved	state of straight key

       Returns the current saved state of the straight key.

       Returns:	CW_KEY_STATE_CLOSED (true) if the key is down
       Returns:	CW_KEY_STATE_OPEN (false) if the key up

       bool cw_is_straight_key_busy(void)
       Brief: Check if the straight key	is busy

       This routine is just a pseudonym	for  cw_get_straight_key_state(),  and
       exists to fill a	hole in	the API	naming conventions.

       Returns:	true if	the straight key is busy
       Returns:	false if the straight key is not busy

       void cw_reset_straight_key(void)
       Brief: Clear the	straight key state, and	return to silence

       This function is	suitable for calling from an application exit handler.

       bool cw_is_alsa_possible(const char *device)
       Brief: Check if it is possible to open ALSA output

       Function	first tries to load ALSA library, and then does	a test opening
       of ALSA output, but it closes it	before returning.

       Parameter: device - name	of ALSA	device to be used; if  NULL  then  li-
       brary will use default device.

       Returns:	true if	opening	ALSA output succeeded;
       Returns:	false if opening ALSA output failed;

       bool cw_is_console_possible(const char *device)
       Brief: Check if it is possible to open console output

       Function	does a test opening and	test writing to	console	device,	but it
       closes it before	returning.

       The function tests that the given console file exists, and that it will
       accept  the KIOCSOUND ioctl.  It	unconditionally	returns	false on plat-
       forms that do no	support	the KIOCSOUND ioctl.

       Call to ioctl will fail if calling code doesn't have root privileges.

       This is the only	place where we ask if KIOCSOUND	is defined, so	client
       code  must  call	this function whenever it wants	to use console output,
       as every	other function called to perform console operations will  hap-
       pily assume that	it is allowed to perform such operations.

       Parameter: device - name	of console device to be	used; if NULL then li-
       brary will use default device.

       Returns:	true if	opening	console	output succeeded;
       Returns:	false if opening console output	failed;

       int cw_console_write(cw_gen_t *gen, cw_tone_t *tone)
       Brief: Pseudo-device for	playing	sound with console

       Function	behaving like a	device,	to which one does  a  blocking	write.
       It  generates  sound with parameters (frequency and duration) specified
       in tone..  After	playing	X microseconds of tone it returns. It  is  in-
       tended to behave	like a blocking	write()	function.

       Parameter: gen -	current	generator
       Parameter: tone - tone to play with generator

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_get_character_count(void)
       Brief:  Return the number of characters present in character lookup ta-
       ble

       Return the number of characters that are	known to  libcw.   The	number
       includes:

	      o
		      ASCII 7bit letters,

	      o
		      numerals,

	      o
		      punctuation,

	      o
		      ISO 8859-1 accented characters,

	      o
		      ISO 8859-2 accented characters,

	      o
		      non-standard procedural signal extensions	to standard CW
		     characters.

       Returns:	number of characters known to libcw

       void cw_list_characters(char *list)
       Brief: Get list of characters present in	character lookup table

       Function	provides a string containing all of the	characters represented
       in library's lookup table.

       The list	includes:

	      o
		      ASCII 7bit letters,

	      o
		      numerals,

	      o
		      punctuation,

	      o
		      ISO 8859-1 accented characters,

	      o
		      ISO 8859-2 accented characters,

	      o
		      non-standard procedural signal extensions	to standard CW
		     characters.

       list should be allocated	and managed by caller.	 The  length  of  list
       must  be	at least one greater than the number of	characters represented
       in the character	lookup table, returned by cw_get_character_count().

       Parameter: list - pointer to space to be	filled by function

       int cw_get_maximum_representation_length(void)
       Brief: Get length of the	longest	representation

       Function	returns	the string length of the longest representation	in the
       character lookup	table.

       Returns:	a positive number - length of the longest representation

       int cw_lookup_character(char c, char *representation)
       Brief: Get representation of a given character

       The  function  is depreciated, use cw_character_to_representation() in-
       stead.

       Return the string representation	(shape)	of a given Morse code  charac-
       ter c.

       The  routine  returns  CW_SUCCESS  on  success, and fills in the	string
       pointer (representation)	passed in.  On failure,	it returns  CW_FAILURE
       and  sets errno to ENOENT, indicating that the character	c could	not be
       found.

       The length of representation buffer must	be at least one	 greater  than
       the  length  of longest representation held in the character lookup ta-
       ble. The	largest	value of length	is returned  by	 cw_get_maximum_repre-
       sentation_length().

       Parameter: c - character	to look	up
       Parameter:  representation  -  pointer  to  space for representation of
       character

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       char *cw_character_to_representation(int	c)
       Brief: Get representation of a given character

       On success  return  representation  of  a  given	 character.   Returned
       pointer is owned	by caller of the function.

       On  failure function returns NULL and sets errno: ENOENT	indicates that
       the character could not be found.  ENOMEM indicates that	character  has
       been found, but function	failed to strdup() representation.

       Parameter: c - character	to look	up

       Returns:	pointer	to freshly allocated representation on success
       Returns:	NULL on	failure

       int cw_check_representation(const char *representation)
       Brief: Check if representation of a character is	valid

       This function is	depreciated, use cw_representation_is_valid() instead.

       Check  that  the	given string is	a valid	Morse representation.  A valid
       string is one composed of only "." and "-" characters.

       If representation is invalid, function returns CW_FAILURE and sets  er-
       rno to EINVAL.

       Parameter: representation - representation of a character to check

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       bool cw_representation_is_valid(const char *representation)
       Brief: Check if representation of a character is	valid

       Check  that  the	given string is	a valid	Morse representation.  A valid
       string is one composed of only "." and "-" characters.  This means that
       the  function  checks  only  if	representation	is error-free, and not
       whether the representation represents existing/defined character.

       If representation is invalid, function returns false and	sets errno  to
       EINVAL.

       Parameter: representation - representation of a character to check

       Returns:	true on	success
       Returns:	false on failure

       int cw_lookup_representation(const char *representation,	char *c)
       Brief: Get the character	represented by a given Morse representation

       This  function is depreciated, use cw_representation_to_character() in-
       stead.

       Function	checks representation, and if it is  valid  and	 represents  a
       known  character,  function  returns  CW_SUCCESS. Additionally, if c is
       non-NULL, function puts the looked up character in c.

       c should	be allocated by	caller.	Function assumes  that	c  being  NULL
       pointer	is a valid situation, and can return CW_SUCCESS	in such	situa-
       tion.

       On error, function returns CW_FAILURE. errno is set to  EINVAL  if  any
       character  of the representation	is invalid, or ENOENT to indicate that
       the character represented by representation could not be	found.

       Parameter: representation - representation of a character to look up
       Parameter: c - location where to	put looked up character

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       int cw_representation_to_character(const	char *representation)
       Brief: Return the character represented by a given Morse	representation

       Function	checks representation, and if it is  valid  and	 represents  a
       known character,	function returns the character (a non-zero value).

       On  error, function returns zero. errno is set to EINVAL	if any charac-
       ter of the representation is invalid, or	ENOENT to  indicate  that  the
       character represented by	representation could not be found.

       Parameter: representation - representation of a character to look up

       Returns:	non-zero character on success
       Returns:	zero on	failure

       int cw_get_procedural_character_count(void)
       Brief: Get number of procedural signals

       Returns:	 the number of characters represented in the procedural	signal
       expansion lookup	table

       void cw_list_procedural_characters(char *list)
       Brief: Get list of characters for which procedural expansion is	avail-
       able

       Function	returns	into list a string containing all of the Morse charac-
       ters for	which procedural expansion is available.  The length  of  list
       must  be	 at  least by one greater than the number of characters	repre-
       sented in the procedural	signal expansion  lookup  table,  returned  by
       cw_get_procedural_character_count().

       list is managed by caller

       Parameter: list - space for returned characters

       int cw_get_maximum_procedural_expansion_length(void)
       Brief: Get length of the	longest	procedural expansion

       Function	returns	the string length of the longest expansion in the pro-
       cedural signal expansion	table.

       Returns:	length

       int  cw_lookup_procedural_character(char	 c,   char   *expansion,   int
       *is_usually_expanded)
       Brief: Get the string expansion of a given Morse	code procedural	signal
       character

       On success the function - fills expansion with the string expansion  of
       a  given	Morse code procedural signal character c; - sets is_usuall_ex-
       panded to true as a display hint	for the	caller;	- returns CW_SUCCESS.

       Both expansion and expansion must be allocated and managed  by  caller.
       They can	be NULL, then the function won't attempt to use	them.

       The  length of expansion	must be	at least by one	greater	than the long-
       est expansion held in the procedural signal character lookup table,  as
       returned	by cw_get_maximum_procedural_expansion_length().

       If procedural signal character c	cannot be found, the function sets er-
       rno to ENOENT and returns CW_FAILURE.

       Parameter: c - character	to look	up
       Parameter: expansion - output, space to	fill  with  expansion  of  the
       character
       Parameter: is_usually_expanded -	visual hint

       Returns:	CW_FAILURE on failure (errno is	set to ENOENT)
       Returns:	CW_SUCCESS on success

       int cw_get_maximum_phonetic_length(void)
       Brief: Get maximum length of a phonetic

       Returns:	 the  string  length  of the longest phonetic in the phonetics
       lookup table

       int cw_lookup_phonetic(char c, char *phonetic)
       Brief: Get the phonetic of a given character

       On success the routine fills in the string pointer passed in  with  the
       phonetic	of given character c.

       The  length  of	phonetic must be at least one greater than the longest
       phonetic	held in	the phonetic lookup table, as returned by cw_get_maxi-
       mum_phonetic_length().

       If character cannot be found, the function sets errno to	ENOENT.

       Parameter: c - character	to look	up
       Parameter: phonetic - output, space for phonetic	of a character

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       bool cw_character_is_valid(char c)
       Brief: Checks that the given character is validly sendable in Morse

       Function	sets errno to ENOENT on	failure.

       Parameter: c - character	to check

       Returns:	CW_SUCCESS if character	is valid
       Returns:	CW_FAILURE if character	is invalid

       bool cw_string_is_valid(const char *string)
       Brief: Validate a string

       Check  that each	character in the given string is valid and can be sent
       by libcw	as a Morse character.

       Function	sets errno to EINVAL on	failure

       Parameter: string - string to check

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       void cw_debug_flush(cw_debug_t *debug)
       Brief: Write all	events from the	debug object to	a file

       Function	writes all events stored in the	debug object to	 file  associ-
       ated with the object, and removes the events.

       List  of	 events	 is  preceded with "FLUSH START0 line, and followed by
       "FLUSH END0 line.

       Parameter: debug	- debug	object

       void cw_set_debug_flags(uint32_t	flags)
       Brief: Set a value of internal debug flags variable

       Assign specified	value to  library's  internal  debug  flags  variable.
       Note that this function doesn't *append*	given flag to the variable, it
       erases existing value and assigns new one. Use cw_get_debug_flags()  if
       you want	to OR new flag with existing ones.

       Parameter: new_value - new value	to be assigned to the library

       void cw_debug_set_flags(cw_debug_t *debug_object, uint32_t flags)

       uint32_t	cw_get_debug_flags(void)
       Brief: Get current library's debug flags

       Function	returns	value of library's internal debug variable.

       Returns:	value of library's debug flags variable

       uint32_t	cw_debug_get_flags(cw_debug_t *debug_object)

       bool cw_debug_has_flag(cw_debug_t *debug_object,	uint32_t flag)
       Brief: Check if given debug flag	is set

       Function	 checks	 if a specified	debug flag is set in internal variable
       of libcw	library.

       Parameter: flag - flag to be checked.

       Returns:	true if	given flag is set
       Returns:	false if given flag is not set

       int cw_generator_set_tone_slope(cw_gen_t	 *gen,	int  slope_shape,  int
       slope_len)
       Brief: Set parameters of	tones generated	by generator

       Most  of	 variables related to slope of tones is	in tone	data type, but
       there are still some variables that are generator-specific, as they are
       common for all tones.  This function sets two of	these variables.

       A:  If  you  pass  to  function	conflicting  values of slope_shape and
       slope_len, the function will return CW_FAILURE. These conflicting  val-
       ues  are	rectangular slope shape	and larger than	zero slope length. You
       just can't have rectangular slopes that have non-zero length.

       B: If you pass to function  '-1'	 as  value  of	both  slope_shape  and
       slope_len, the function won't change any	of the related two generator's
       parameters.

       C1: If you pass to function '-1'	as  value  of  either  slope_shape  or
       slope_len,  the	function will attempt to set only this generator's pa-
       rameter that is different than '-1'.

       C2: However, if selected	slope shape is rectangular, function will  set
       generator's    slope    length	 to    zero,	even   if   value   of
       slope_len is '-1'.

       D: Notice that the function allows  non-rectangular  slope  shape  with
       zero length of the slopes. The slopes will be non-rectangular, but just
       unusually short.

       The function should be called every time	one  of	 following  parameters
       change:

	      o
		      shape of slope,

	      o
		      length of	slope,

	      o
		      generator's sample rate,

	      o
		      generator's volume.

       There are four supported	shapes of slopes:

	      o
		      linear  (the  only  one supported	by libcw until version
		     4.1.1),

	      o
		      raised cosine (supposedly	the most desired shape),

	      o
		      sine,

	      o
		      rectangular.

       Use CW_TONE_SLOPE_SHAPE_* symbolic names	as values of slope_shape.

       FIXME: first argument of	this public function is	gen, but  no  function
       provides	access to generator variable.

       Parameter: gen -	generator for which to set tone	slope parameters
       Parameter:  slope_shape	- shape	of slope: linear, raised cosine, sine,
       rectangular
       Parameter: slope_len - length of	slope [microseconds]

       Returns:	CW_SUCCESS on success
       Returns:	CW_FAILURE on failure

       bool cw_is_oss_possible(const char *device)
       Brief: Check if it is possible to open OSS output

       Function	does a test opening and	test configuration of OSS output,  but
       it closes it before returning.

       Parameter: device - name	of OSS device to be used; if NULL then library
       will use	default	device.

       Returns:	true if	opening	OSS output succeeded;
       Returns:	false if opening OSS output failed;

       bool cw_is_pa_possible(const char *device)
       Brief: Check if it is possible to open PulseAudio output

       Function	first tries to load PulseAudio library,	and then does  a  test
       opening of PulseAudio output, but it closes it before returning.

       Parameter: device - sink	device,	NULL for default PulseAudio device

       Returns:	true if	opening	PulseAudio output succeeded;
       Returns:	false if opening PulseAudio output failed;

       void cw_block_callback(int block)
       Brief: Block the	callback from being called

       Function	 blocks	 the callback from being called	for a critical section
       of caller code if block is true,	and unblocks the callback if block  is
       false.

       Function	works by blocking SIGALRM; a block should always be matched by
       an unblock, otherwise the tone queue will suspend forever.

       Parameter: block	- pass 1 to block SIGALRM, and 0 to unblock it

       int   cw_register_signal_handler(int   signal_number,   void    (*call-
       back_func)(int))
       Brief:  Register	 a  signal  handler and	optional callback function for
       given signal number

       On receipt of that signal, all library features will be reset to	 their
       default	states.	  Following  the reset,	if callback_func is a function
       pointer,	the function is	called;	if it is SIG_DFL,  the	library	 calls
       exit();	and if it is SIG_IGN, the library returns from the signal han-
       dler.

       This is a convenience function for clients that need to	clean  up  li-
       brary on	signals, with either exit, continue, or	an additional function
       call; in	effect,	a wrapper round	a restricted form of sigaction.

       The signal_number argument indicates which signal to catch.

       On problems errno is set	to EINVAL if signal_number is invalid or if  a
       handler is already installed for	that signal, or	to the sigaction error
       code.

       Parameter: signal_number
       Parameter: callback_func

       Returns:	CW_SUCCESS - if	the signal handler installs correctly
       Returns:	CW_FAILURE - on	errors or problems

       int cw_unregister_signal_handler(int signal_number)
       Brief: Unregister a signal handler interception

       Function	removes	a signal handler  interception	previously  registered
       with cw_register_signal_handler().

       Parameter: signal_number

       Returns:	true if	the signal handler uninstalls correctly
       Returns:	 false otherwise (with errno set to EINVAL or to the sigaction
       error code)

       int cw_version(void)
       Brief: Return version number of libcw library

       Return the version number of the	library.  Version numbers  (major  and
       minor)  are  returned  as an int, composed of major_version << 16 | mi-
       nor_version.

       Returns:	library's major	and minor version number encoded as single int

       void cw_license(void)
       Brief: Print libcw's license text to stdout

       Function	prints information about libcw version,	followed by short text
       presenting libcw's copyright and	license	notice.

       const char *cw_get_audio_system_label(int audio_system)
       Brief: Get a readable label of given audio system

       The  function  returns  one  of following strings: None,	Null, Console,
       OSS, ALSA, PulseAudio, Soundcard

       Returned	pointer	is owned and managed by	the library.

       TODO: change the	declaration to "const  char  *const  cw_get_audio_sys-
       tem_label(...)"?

       Parameter: audio_system - ID of audio system

       Returns:	audio system's label

       void cw_get_speed_limits(int *min_speed,	int *max_speed)
       Brief: Get speed	limits

       Get  (through  function's arguments) limits on speed of morse code that
       can be generated	by generator.

       See CW_SPEED_MIN	and CW_SPEED_MAX in libcw.h for	values.

       Parameter: min_speed - minimal allowed speed
       Parameter: max_speed - maximal allowed speed

       void cw_get_frequency_limits(int	*min_frequency,	int *max_frequency)
       Brief: Get frequency limits

       Get (through function's arguments) limits on frequency that can be gen-
       erated by generator.

       See CW_FREQUENCY_MIN and	CW_FREQUENCY_MAX in libcw.h for	values.

       Parameter: min_frequency	- minimal allowed frequency
       Parameter: max_frequency	- maximal allowed frequency

       void cw_get_volume_limits(int *min_volume, int *max_volume)
       Brief: Get volume limits

       Get  (through function's	arguments) limits on volume of sound generated
       by generator.

       See CW_VOLUME_MIN and CW_VOLUME_MAX in libcw.h for values.

       Parameter: min_volume - minimal allowed volume
       Parameter: max_volume - maximal allowed volume

       void cw_get_gap_limits(int *min_gap, int	*max_gap)
       Brief: Get gap limits

       Get (through function's arguments) limits on gap	in cw signal generated
       by generator.

       See CW_GAP_MIN and CW_GAP_MAX in	libcw.h	for values.

       Parameter: min_gap - minimal allowed gap
       Parameter: max_gap - maximal allowed gap

       void cw_get_tolerance_limits(int	*min_tolerance,	int *max_tolerance)
       Brief: Get tolerance limits

       Get  (through  function's arguments) limits on "tolerance" parameter of
       generator.

       See CW_TOLERANCE_MIN and	CW_TOLERANCE_MAX in libcw.h for	values.

       Parameter: min_tolerance	- minimal allowed tolerance
       Parameter: max_tolerance	- maximal allowed tolerance

       void cw_get_weighting_limits(int	*min_weighting,	int *max_weighting)
       Brief: Get weighting limits

       Get (through function's arguments) limits on "weighting"	 parameter  of
       generator.

       See CW_WEIGHTING_MIN and	CW_WEIGHTING_MAX in libcw.h for	values.

       Parameter: min_weighting	- minimal allowed weighting
       Parameter: max_weighting	- maximal allowed weighting

       void cw_complete_reset(void)
       Brief: Reset all	library	features to their default states

       Clears  the tone	queue, receive buffers and retained state information,
       any current keyer activity, and any straight key	activity,  returns  to
       silence,	 and  closes  soundcard	and console devices.  This function is
       suitable	for calling from an application	exit handler.

NOTES
       Despite the fact	that this  manual  page	 constantly  and  consistently
       refers to Morse code elements as	dots and dashes, DO NOT	think in these
       terms when trying to learn Morse	code.  Always think of them as	'dit's
       and 'dah's.

       libcw  uses  system  itimers  for  its  internal	 timing.  On most UNIX
       flavours, itimers are not guaranteed to signal a	program	exactly	at the
       specified  time,	 and they generally offer a resolution only as good as
       the normal system 'clock	tick' resolution.  An itimer  SIGALRM  usually
       falls on	a system clock tick, making it accurate	to no better than 10mS
       on a typical 100Hz kernel.

       The effect of this is that an itimer period is generally	either exactly
       as  specified,  or,  more  likely, slightly longer.  At higher WPM set-
       tings, the cumulative effect of this affects timing  accuracy,  because
       at  higher  speeds,  there  are fewer 10mS clock	ticks in a dot period.
       For example, at 12 WPM, the dot length is 100mS,	enough to contain five
       kernel clock ticks; at 60 WPM, the dot length is	20mS, or just two ker-
       nel clock ticks.	 So at higher speeds, the effect of itimer resolutions
       becomes more pronounced.

SEE ALSO
       Man  pages for cw(7,LOCAL), cw(1,LOCAL),	cwgen(1,LOCAL),	cwcp(1,LOCAL),
       and xcwcp(1,LOCAL).

libcw ver. 6.5.1	       CW Tutor	Package			      LIBCW(3)

NAME | SYNOPSIS | NOTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libcw&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help