LIBCW(3)LIBCW(3)NAMElibcw - 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
receiving 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
receive, 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
return 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
library 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
microseconds.
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
insufficient 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
insufficient 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
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 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
already 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
final tone to complete. In this case, it may not be possible to guar‐
antee 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
enabled.
Parameter: new_value - new value of receive speed to be assigned to
receiver
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
receiver
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
microseconds.
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
ignored. This allows the "receive mark" functions to apply noise can‐
celing for very short apparent marks. For useful results the value
should never exceed the dot length of a dot at maximum speed: 20000
microseconds (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
assigned 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
received CW. The values dot_sd and dot_sd contain the standard devia‐
tion 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
attempt 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_receive_tone() or if an error condition currently exists within
the receiver's buffer, or ENOMEM if the receiver's representation buf‐
fer 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_receive_representation call, or a prior cw_receive_buffer_dot or
cw_receive_buffer_dash, EINVAL if the timestamp passed in is invalid,
EAGAIN if the call is made too early to determine whether a complete
representation 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
invalid, 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_receive_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_receive_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
retained 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
either 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
library 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
library 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
intended 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:
·
ASCII 7bit letters,
·
numerals,
·
punctuation,
·
ISO 8859-1 accented characters,
·
ISO 8859-2 accented characters,
·
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:
·
ASCII 7bit letters,
·
numerals,
·
punctuation,
·
ISO 8859-1 accented characters,
·
ISO 8859-2 accented characters,
·
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()
instead.
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
errno 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()
instead.
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_usu‐
all_expanded 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
errno 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
parameter 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:
·
shape of slope,
·
length of slope,
·
generator's sample rate,
·
generator's volume.
There are four supported shapes of slopes:
·
linear (the only one supported by libcw until version
4.1.1),
·
raised cosine (supposedly the most desired shape),
·
sine,
·
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
library on signals, with either exit, continue, or an additional func‐
tion 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 |
minor_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)
