NAME¶
libcw - general purpose Morse code functions library
SYNOPSIS¶
#include <libcw.h>
int cw_version(void)
void cw_license(void)
void cw_set_debug_flags(unsigned int new_value)
unsigned int cw_get_debug_flags(void)
bool cw_is_debugging_internal(unsigned int flag)
int cw_get_character_count(void)
void cw_list_characters(char *list)
int cw_get_maximum_representation_length(void)
const char *cw_lookup_character_internal(char c)
int cw_lookup_character(char c, char *representation)
unsigned int cw_hash_representation_internal(const char *representation)
char cw_lookup_representation_internal(const char *representation)
int cw_check_representation(const char *representation)
int cw_lookup_representation(const char *representation, char *c)
int cw_get_procedural_character_count(void)
void cw_list_procedural_characters(char *list)
int cw_get_maximum_procedural_expansion_length(void)
const char *cw_lookup_procedural_character_internal(char c, int
*is_usually_expanded)
int cw_lookup_procedural_character(char c, char *representation,
int *is_usually_expanded)
int cw_get_maximum_phonetic_length(void)
int cw_lookup_phonetic(char c, char *phonetic)
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_sync_parameters_internal(void)
void cw_reset_send_receive_parameters(void)
int cw_set_send_speed(int new_value)
int cw_set_receive_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_tolerance(int new_value)
int cw_set_weighting(int new_value)
int cw_get_send_speed(void)
int cw_get_receive_speed(void)
int cw_get_frequency(void)
int cw_get_volume(void)
int cw_get_gap(void)
int cw_get_tolerance(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 *adjustment_usecs)
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 threshold)
int cw_get_noise_spike_threshold(void)
void cw_sigalrm_handler_internal(int signal_number)
int cw_set_timer_internal(int usecs)
int cw_request_timeout_internal(int usecs, void (*request_handler)(void))
int cw_release_timeouts_internal(void)
int cw_check_signal_mask_internal(void)
int cw_block_signal_internal(int is_block)
void cw_block_callback(int is_block)
int cw_wait_for_signal_internal(void)
int cw_set_audio_device(const char *device)
const char *cw_get_console_device(void)
const char *cw_get_soundcard_device(void)
int cw_sound_soundcard_internal(int state)
int cw_release_sound_internal(void)
int cw_sound_internal(int frequency)
void cw_finalization_clock_internal(void)
void cw_schedule_finalization_internal(void)
void cw_cancel_finalization_internal(void)
void cw_complete_reset(void)
void cw_interpose_signal_handler_internal(int signal_number)
int cw_register_signal_handler(int signal_number,
void (*callback_func) (int))
int cw_unregister_signal_handler(int signal_number)
void cw_register_keying_callback(void (*callback_func)(void*, int),
void *callback_arg)
void cw_key_control_internal(int requested_key_state)
int cw_get_tone_queue_length_internal(void)
int cw_next_tone_queue_index_internal(int current)
void cw_tone_queue_clock_internal(void)
int cw_enqueue_tone_internal(int usecs, int frequency)
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)
int cw_queue_tone(int usecs, int frequency)
void cw_reset_tone_queue(void)
int cw_send_element_internal(char element)
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_internal(const char *representation, int
partial)
int cw_send_representation(const char *representation)
int cw_send_representation_partial(const char *representation)
int cw_send_character_internal(char c, int partial)
int cw_check_character(char c)
int cw_send_character(char c)
int cw_send_character_partial(char c)
int cw_check_string(const char *string)
int cw_send_string(const char *string)
void cw_reset_adaptive_average_internal(cw_tracking_t *tracking, int
initial)
void cw_update_adaptive_average_internal(cw_tracking_t *tracking, int
element_usec)
int cw_get_adaptive_average_internal(cw_tracking_t *tracking)
void cw_add_receive_statistic_internal(stat_type_t type, int usecs)
double cw_get_receive_statistic_internal(stat_type_t type)
void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
double *element_end_sd, double *character_end_sd)
void cw_reset_receive_statistics(void)
void cw_set_adaptive_receive_internal(bool flag)
void cw_enable_adaptive_receive(void)
void cw_disable_adaptive_receive(void)
bool cw_get_adaptive_receive_state(void)
int cw_validate_timestamp_internal(const struct timeval *timestamp,
struct timeval *return_timestamp)
int cw_compare_timestamps_internal(const struct timeval *earlier,
const struct timeval *later)
int cw_start_receive_tone(const struct timeval *timestamp)
int cw_identify_receive_tone_internal(int element_usec, char
*representation)
void cw_update_adaptive_tracking_internal(int element_usec, char element)
int cw_end_receive_tone(const struct timeval *timestamp)
int cw_receive_buffer_element_internal(const struct timeval *timestamp,
char element)
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,
char *representation, bool *is_end_of_word,
bool *is_error)
int cw_receive_character(const struct timeval *timestamp,
char *c, bool *is_end_of_word, 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_enable_iambic_curtis_mode_b(void)
void cw_disable_iambic_curtis_mode_b(void)
int cw_get_iambic_curtis_mode_b_state(void)
void cw_keyer_clock_internal(void)
int cw_notify_keyer_paddle_event(int dot_paddle_state,
int dash_paddle_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_paddle_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)
void cw_straight_key_clock_internal(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)
const char *cw_generator_get_audio_system_label(void)
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_generator_calculate_sine_wave(cw_gen_t *gen)
int cw_generator_calculate_amplitude(cw_gen_t *gen)
bool cw_is_console_possible(const char *device)
int cw_open_device_console(const char *device)
void cw_close_device_console(void)
int cw_sound_console_internal(int state)
bool cw_is_oss_possible(const char *device)
int cw_open_device_oss(const char *device)
int cw_open_device_oss_ioctls(int *fd, int *sample_rate)
void cw_close_device_oss(void)
void *cw_generator_write_sine_wave_oss(void *arg)
bool cw_is_alsa_possible(const char *device)
int cw_open_device_alsa(const char *device)
void cw_close_device_alsa(void)
void *cw_generator_write_sine_wave_alsa(void *arg)
int cw_set_alsa_hw_params(snd_pcm_t *handle, snd_pcm_hw_params_t *params)
DESCRIPTION¶
libcw is a general purpose CW (Morse code) functions library. It contains
routines for converting characters into Morse code representations 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 applications 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 background
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 functions 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 keying
state, either as a result of sending a Morse character or representation, 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.
FUNCTIONS¶
The following list describes the functions available to a
libcw caller:
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.
void cw_set_debug_flags(unsigned int new_value)
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
unsigned int 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
bool cw_is_debugging_internal(unsigned int 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_get_character_count(void)
Returns the number of characters represented in the character lookup table.
void cw_list_characters(char *list)
Returns into list a string containing all of the Morse characters represented in
the table. 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.
int cw_get_maximum_representation_length(void)
Returns the string length of the longest representation in the character lookup
table.
const char *cw_lookup_character_internal(char c)
Look up the given character, and return the representation of that character.
Returns NULL if there is no table entry for the given character.
int cw_lookup_character(char c, char *representation)
Returns the string 'shape' of a given Morse code character. The routine returns
true on success, and fills in the string pointer passed in. On error, it
returns false and sets errno to ENOENT, indicating that the character could
not be found. The length of representation must be at least one greater than
the longest representation held in the character lookup table, returned by
cw_get_maximum_representation_length.
unsigned int cw_hash_representation_internal(const char *representation)
Return a hash value, in the range 2-255, for a lookup table representation. The
routine returns 0 if no valid hash could be made from the string. To avoid
casting the value a lot in the caller (we want to use it as an array index),
we actually return an unsigned int.
This hash algorithm is designed ONLY for valid CW representations; that is,
strings composed of only '.' and '-', and in this case, strings shorter than
eight characters. The algorithm simply turns the representation into a
'bitmask', based on occurrences of '.' and '-'. The first bit set in the mask
indicates the start of data (hence the 7-character limit). This mask is
viewable as an integer in the range 2 (".") to 255
("-------"), and can be used as an index into a fast lookup array.
char cw_lookup_representation_internal(const char *representation)
Look up the given representation, and return the character that it represents.
Returns zero if there is no table entry for the given representation.
int cw_check_representation(const char *representation)
Checks that the given string is a valid Morse representation. A valid string is
one composed of only '.' and '-' characters. On success, the routine returns
true. On error, it returns false, with errno set to EINVAL.
int cw_lookup_representation(const char *representation, char *c)
Returns the character for a given Morse representation. On success, the routine
returns true, and fills in char *c. On error, it returns false, and sets errno
to EINVAL if any character of the representation is invalid, or ENOENT to
indicate that the representation could not be found.
int cw_get_procedural_character_count(void)
Returns the number of characters represented in the procedural signal expansion
lookup table.
void cw_list_procedural_characters(char *list)
Returns into list a string containing all of the Morse characters for which
procedural expansion are available. The length of list must be at least one
greater than the number of characters represented in the procedural signal
expansion lookup table, returned by cw_get_procedural_character_count.
int cw_get_maximum_procedural_expansion_length(void)
Returns the string length of the longest expansion in the procedural signal
expansion table.
const char *cw_lookup_procedural_character_internal(char c, int
*is_usually_expanded)
Look up the given procedural character, and return the expansion of that
procedural character, with a display hint in is_usually_expanded. Returns NULL
if there is no table entry for the given character.
int cw_lookup_procedural_character(char c, char *representation,
int *is_usually_expanded)
Returns the string expansion of a given Morse code procedural signal character.
The routine returns true on success, filling in the string pointer passed in
and setting is_usuall_expanded to true as a display hint for the caller. On
error, it returns false and sets errno to ENOENT, indicating that the
procedural signal character could not be found. The length of representation
must be at least one greater than the longest representation held in the
procedural signal character lookup table, returned by
cw_get_maximum_procedural_expansion_length.
int cw_get_maximum_phonetic_length(void)
Returns the string length of the longest phonetic in the phonetics lookup table.
int cw_lookup_phonetic(char c, char *phonetic)
Returns the phonetic of a given character. The routine returns true on success,
and fills in the string pointer passed in. On error, it returns false and sets
errno to ENOENT, indicating that the character could not be found. The length
of phonetic must be at least one greater than the longest phonetic held in the
phonetic lookup table, returned by cw_get_maximum_phonetic_length.
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 current 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 generated by
current 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
current 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
current 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 current
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 current
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_sync_parameters_internal(void)
Synchronize the dot, dash, end of element, end of character, and end of word
timings and ranges to new values of Morse speed, 'Farnsworth' gap, receive
tolerance, or weighting.
void cw_reset_send_receive_parameters(void)
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 %.
int cw_set_send_speed(int new_value)
cw_set_[send_speed|receive_speed|frequency|volume|gap|tolerance|weighting]()
cw_get_[send_speed|receive_speed|frequency|volume|gap|tolerance|weighting]()
Get and set routines for all the Morse code parameters available to control the
library. Set routines return true on success, or false on failure, with errno
set to indicate the problem, usually EINVAL, except for cw_set_receive_speed,
which returns EINVAL if the new value is invalid, or EPERM if the receive mode
is currently set for adaptive receive speed tracking. Get routines simply
return the current value.
The default values of the parameters where none are explicitly set are
send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0 dots,
tolerance 50 %, and weighting 50 %. Note that volume settings are not fully
possible for the console speaker; in this case, volume settings greater than
zero indicate console speaker sound is on, and setting volume to zero will
turn off console speaker sound.
int cw_set_receive_speed(int new_value)
See documentation of cw_set_send_speed() for more information.
int cw_set_frequency(int new_value)
Brief: Set frequency of current generator
Set frequency of sound wave generated by current generator. The frequency must
be within limits marked by CW_FREQUENCY_MIN and CW_FREQUENCY_MAX.
The function sets errno to EINVAL on errors.
Parameter: new_value - new value of frequency to be associated with current
generator
Returns: CW_SUCCESS on success
Returns: CW_FAILURE on failure
int cw_set_volume(int new_value)
Brief: Set volume of current generator
Set volume of sound wave generated by current generator. The volume must be
within limits marked by CW_VOLUME_MIN and CW_VOLUME_MAX.
The function sets errno to EINVAL on errors.
Parameter: new_value - new value of volume to be associated with current
generator
Returns: CW_SUCCESS on success
Returns: CW_FAILURE on failure
int cw_set_gap(int new_value)
See documentation of cw_set_send_speed() for more information.
int cw_set_tolerance(int new_value)
See documentation of cw_set_send_speed() for more information.
int cw_set_weighting(int new_value)
See documentation of cw_set_send_speed() for more information.
int cw_get_send_speed(void)
See documentation of cw_set_send_speed() for more information.
int cw_get_receive_speed(void)
See documentation of cw_set_send_speed() for more information.
int cw_get_frequency(void)
Brief: Return frequency of current generator
Function returns 'frequency' parameter of current generator, even if the
generator is stopped, or volume of generated sound is zero.
Returns: Frequency of current generator
int cw_get_volume(void)
Brief: Return volume of current generator
Function returns 'volume' parameter of current generator, even if the generator
is stopped.
Returns: Volume of current generator
int cw_get_gap(void)
See documentation of cw_set_send_speed() for more information.
int cw_get_tolerance(void)
See documentation of cw_set_send_speed() for more information.
int cw_get_weighting(void)
See documentation of cw_set_send_speed() for more information.
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)
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.
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)
See documentation of cw_get_send_parameters() for more information
int cw_set_noise_spike_threshold(int threshold)
Set and get the period shorter than which, on receive, received tones are
ignored. This allows the receive tone functions to apply noise canceling for
very short apparent tones. For useful results the value should never exceed
the dot length of a dot at maximum speed; 20,000 microseconds (the dot length
at 60WPM). Setting a noise threshold of zero turns off receive tone noise
canceling. The default noise spike threshold is 10,000 microseconds.
int cw_get_noise_spike_threshold(void)
See documentation of cw_set_noise_spike_threshold() for more information
void cw_sigalrm_handler_internal(int signal_number)
Common SIGALRM handler. This function calls the signal handlers of the library
subsystems, expecting them to ignore unexpected calls.
int cw_set_timer_internal(int usecs)
Convenience function to set the itimer for a single shot timeout after a given
number of microseconds.
int cw_request_timeout_internal(int usecs, void (*request_handler)(void))
Install the SIGALRM handler, if not yet installed. Add any given lower level
handler to the list of registered handlers. Then set an itimer to expire after
the requested number of microseconds.
int cw_release_timeouts_internal(void)
Uninstall the SIGALRM handler, if installed. Return SIGALRM's disposition for
the system to the state we found it in before we installed our own SIGALRM
handler.
int cw_check_signal_mask_internal(void)
Check the signal mask of the process, and return an error, with errno set to
EDEADLK, if SIGALRM is blocked.
int cw_block_signal_internal(int is_block)
Block SIGALRM for the duration of certain critical sections, or unblock after;
passed true to block SIGALRM, and false to unblock.
void cw_block_callback(int is_block)
Blocks the callback from being called for a critical section of caller code if
is_block is true, and unblocks the callback if block is false. Works by
blocking SIGALRM; a block should always be matched by an unblock, otherwise
the tone queue will suspend forever.
int cw_wait_for_signal_internal(void)
Wait for a signal, usually a SIGALRM. Assumes SIGALRM is not blocked.
int cw_set_audio_device(const char *device)
Brief: Set audio device name or path
Set path to audio device, or name of audio device. The path/name will be
associated with current generator, and used when opening audio device.
Use this function only when setting up a generator.
Function creates its own copy of input string.
Parameter: device - device to be associated with generator
Returns: CW_SUCCESS on success
Returns: CW_FAILURE on errors
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 soudcard device name or device path
int cw_sound_soundcard_internal(int state)
Brief: Start generating a sound using soundcard
Start generating sound on soundcard with frequency depending on state of current
generator. The function has a single argument 'state'. The argument toggles
between zero volume (state == 0) and full volume (frequency > 0).
The function only initializes generation, you have to do another function call
to change the tone generated.
Parameter: state - toggle between full volume and no volume
Returns: CW_SUCCESS on success
Returns: CW_FAILURE on errors
int cw_release_sound_internal(void)
Brief: Stop and delete generator
Stop and delete current generator. This causes silencing current sound wave.
Returns: CW_SUCCESS
int cw_sound_internal(int frequency)
Brief: Start generating a sound
Start generating sound with frequency depending on state of current generator.
The function has a single argument 'frequency'. The name is old and
meaningless, the argument now only toggles between zero volume (frequency ==
0, or frequency == CW_TONE_SILENCE), and full volume (frequency > 0).
Current generator decides if the sound will be played using soundcard or console
buzzer.
The function only initializes generation, you have to do another function call
to change the tone generated.
Parameter: frequency - toggle between full volume and no volume
Returns: CW_SUCCESS on success
Returns: CW_FAILURE on errors
void cw_finalization_clock_internal(void)
If finalization is pending, decrement the countdown, and if this reaches zero,
we've waited long enough to release sound and timeouts.
void cw_schedule_finalization_internal(void)
Set the finalization pending flag, and request a timeout to call the
finalization function after a delay of a few seconds. Cancel any pending
finalization on noting other library activity, indicated by a call from the
timeout request function telling us that it is setting a timeout.
void cw_cancel_finalization_internal(void)
See documentation of cw_schedule_finalization_internal() for more information
void cw_complete_reset(void)
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.
void cw_interpose_signal_handler_internal(int signal_number)
Signal handler function registered when cw_register_signal_handler is requested.
Resets the library, and then either calls any supplied sub-handler, exits (if
SIG_DFL) or continues (if SIG_IGN).
int cw_register_signal_handler(int signal_number,
void (*callback_func) (int))
Register a signal handler and optional callback function for signals. 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 handler. This is a convenience function for
clients that need to clean up library 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.
Returns true if the signal handler installs correctly, false otherwise, with
errno set to EINVAL if signal_number is invalid or if a handler is already
installed for that signal, or to the sigaction error code.
int cw_unregister_signal_handler(int signal_number)
Removes a signal handler interception previously registered with
cw_register_signal_handler. Returns true if the signal handler uninstalls
correctly, false otherwise, with errno set to EINVAL or to the sigaction error
code.
void cw_register_keying_callback(void (*callback_func)(void*, int),
void *callback_arg)
Register a function that should be called when a tone state changes from key-up
to key-down, or vice-versa. The first argument passed out to the registered
function is the supplied callback_arg, if any. The second argument passed out
is the key state: true for down, false for up. Calling this routine with an
NULL function address disables keying callbacks. Any callback supplied will be
called in signal handler context.
void cw_key_control_internal(int requested_key_state)
Control function that calls any requested keying callback only when there is a
change of keying state. This function filters successive key-down or key-up
actions into a single action.
int cw_get_tone_queue_length_internal(void)
Return the count of tones currently held in the circular tone buffer, and
advance a tone queue index, including circular wrapping.
int cw_next_tone_queue_index_internal(int current)
See documentation of cw_get_tone_queue_length_internal() for more information
void cw_tone_queue_clock_internal(void)
Signal handler for itimer. Dequeue a tone request, and send the ioctl to
generate the tone. If the queue is empty when we get the signal, then we're at
the end of the work list, so set the dequeue state to idle and return.
int cw_enqueue_tone_internal(int usecs, int frequency)
Enqueue a tone for specified frequency and number of microseconds. This routine
adds the new tone to the queue, and if necessary starts the itimer process to
have the tone sent. The routine returns true on success. If the tone queue is
full, the routine returns false, with errno set to EAGAIN. If the iambic keyer
or straight key are currently busy, the routine returns false, with errno set
to EBUSY.
int cw_register_tone_queue_low_callback(void (*callback_func)(void*),
void *callback_arg, int level)
Registers a function to be called automatically by the dequeue routine whenever
the tone queue falls to a given 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 true. If level is invalid, the
routine returns false with errno set to EINVAL. Any callback supplied will be
called in signal handler context.
bool cw_is_tone_busy(void)
Indicates if the tone sender is busy; returns true if there are still entries in
the tone queue, false if the queue is empty.
int cw_wait_for_tone(void)
Wait for the current tone to complete. The routine returns true on success. If
called with SIGALRM blocked, the routine returns false, with errno set to
EDEADLK, to avoid indefinite waits.
int cw_wait_for_tone_queue(void)
Wait for the tone queue to drain. The routine returns true on success. If called
with SIGALRM blocked, the routine returns false, with errno set to EDEADLK, to
avoid indefinite waits.
int cw_wait_for_tone_queue_critical(int level)
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 true on success. If called with SIGALRM blocked,
the routine returns false, with errno set to EDEADLK, to avoid indefinite
waits.
bool cw_is_tone_queue_full(void)
Indicates if the tone queue is full, returning true if full, false if not.
int cw_get_tone_queue_capacity(void)
Returns the number of entries the tone queue can accommodate.
int cw_get_tone_queue_length(void)
Returns the number of entries currently pending in the tone queue.
void cw_flush_tone_queue(void)
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 guarantee silence after the
call.
int cw_queue_tone(int usecs, int frequency)
Provides primitive access to simple tone generation. This routine queues a tone
of given duration and frequency. The routine returns true on success. If usec
or frequency are invalid, it returns false with errno set to EINVAL. If the
sound card, console speaker, or keying function are busy, it returns false
with errno set to EBUSY. If the tone queue is full, it returns false with
errno set to EAGAIN.
void cw_reset_tone_queue(void)
Cancel all pending queued tones, reset any queue low callback registered, and
return to silence. This function is suitable for calling from an application
exit handler.
int cw_send_element_internal(char element)
Low level primitive to send a tone element of the given type, followed by the
standard inter-element silence.
int cw_send_dot(void)
cw_send_[dot|dash|character_space|word_space]()
Low level primitives, available to send single dots, dashes, character spaces,
and word spaces. The dot and dash routines always append the normal
inter-element gap after the tone sent. The cw_send_character_space routine
sends space timed to exclude the expected prior dot/dash inter-element gap.
The cw_send_word_space routine sends space timed to exclude both the expected
prior dot/dash inter-element gap and the prior end of character space. These
functions return true on success, or false with errno set to EBUSY or EAGAIN
on error.
int cw_send_dash(void)
See documentation of cw_send_dot() for more information
int cw_send_character_space(void)
See documentation of cw_send_dot() for more information
int cw_send_word_space(void)
See documentation of cw_send_dot() for more information
int cw_send_representation_internal(const char *representation, int
partial)
Send the given string as dots and dashes, adding the post-character gap.
int cw_send_representation(const char *representation)
Checks, then sends the given string as dots and dashes. The representation
passed in is assumed to be a complete Morse character; that is, all post-
character delays will be added when the character is sent. On success, the
routine returns true. On error, it returns false, with errno set to EINVAL if
any character of the representation 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_representation_partial(const char *representation)
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 true. On error, it returns false, with errno set to EINVAL
if any character of the representation 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_internal(char c, int partial)
Lookup, and send a given ASCII character as cw. If 'partial' is set, the end of
character delay is not appended to the Morse sent. On success, the routine
returns true, otherwise it returns an error.
int cw_check_character(char c)
Checks that the given character is validly sendable in Morse. If it is, the
routine returns true. If not, the routine returns false, with errno set to
ENOENT.
int cw_send_character(char c)
Lookup, and send a given ASCII character as Morse. The end of character delay is
appended to the Morse sent. On success, the routine returns true. On error, it
returns false, with errno set to ENOENT if the given character is not a valid
Morse character, 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.
This routine returns as soon as the character has been successfully queued for
send; 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.
int cw_send_character_partial(char c)
Lookup, and send a given ASCII character as Morse. The end of character delay is
not appended to the Morse sent by the function, to support the formation of
combination characters. On success, the routine returns true. On error, it
returns false, with errno set to ENOENT if the given character is not a valid
Morse character, 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.
This routine queues its arguments for background processing. See
cw_send_character for details of how to check the queue status.
int cw_check_string(const char *string)
Checks that each character in the given string is validly sendable in Morse. On
success, the routine returns true. On error, it returns false, with errno set
to EINVAL.
int cw_send_string(const char *string)
Send a given ASCII string as cw. On success, the routine returns true. On error,
it returns false, with errno set to ENOENT if any character in the string is
not a valid Morse character, EBUSY if the sound card, console speaker, or
keying system is in use by the iambic keyer or the straight key, or EAGAIN if
the tone queue is full. If the tone queue runs out of space part way through
queueing the string, the function returns EAGAIN. 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. See
cw_send_character for details of how to check the queue status.
void cw_reset_adaptive_average_internal(cw_tracking_t *tracking, int
initial)
Moving average functions for smoothed tracking of dot and dash lengths.
void cw_update_adaptive_average_internal(cw_tracking_t *tracking, int
element_usec)
See documentation of cw_reset_adaptive_average_internal() for more information
int cw_get_adaptive_average_internal(cw_tracking_t *tracking)
See documentation of cw_reset_adaptive_average_internal() for more information
void cw_add_receive_statistic_internal(stat_type_t type, int usecs)
Add an element timing with a given statistic type to the circular statistics
buffer. The buffer stores only the delta from the ideal value; the ideal is
inferred from the type passed in.
double cw_get_receive_statistic_internal(stat_type_t type)
Calculate and return one given timing statistic type. If no records of that type
were found, return 0.0.
void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
double *element_end_sd, double *character_end_sd)
Calculate and return receive timing statistics. These statistics may be used to
obtain a measure of the accuracy of received CW. The values dot_sd and dash_sd
contain the standard deviation of dot and dash lengths from the ideal values,
and element_end_sd and character_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.
void cw_reset_receive_statistics(void)
Clear the receive statistics buffer, removing all records from it and returning
it to its initial default state.
void cw_set_adaptive_receive_internal(bool flag)
Set the value of the flag that controls whether, on receive, the receive
functions do fixed speed receive, or track the speed of the received Morse
code by adapting to the input stream.
void cw_enable_adaptive_receive(void)
Enable/disable/get adaptive receive speeds. 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 functions will use fixed speed settings, and reject
incoming Morse which is not at the expected speed. The
cw_get_adaptive_receive_state function returns true if adaptive speed tracking
is enabled, false otherwise. Adaptive speed tracking uses a moving average of
the past four elements as its baseline for tracking speeds. The default state
is adaptive tracking disabled.
void cw_disable_adaptive_receive(void)
See documentation of cw_enable_adaptive_receive() for more information
bool cw_get_adaptive_receive_state(void)
See documentation of cw_enable_adaptive_receive() for more information
int cw_validate_timestamp_internal(const struct timeval *timestamp,
struct timeval *return_timestamp)
If an input timestamp is given, validate it for correctness, and if valid, copy
it into return_timestamp and return true. If invalid, return false with errno
set to EINVAL. If an input timestamp is not given (NULL), return true with the
current system time in return_timestamp.
int cw_compare_timestamps_internal(const struct timeval *earlier,
const struct timeval *later)
Compare two timestamps, and return the difference between them in microseconds,
taking care to clamp values which would overflow an int. This routine always
returns a positive integer in the range 0 to INT_MAX.
int cw_start_receive_tone(const struct timeval *timestamp)
Called on the start of a receive tone. If the timestamp is NULL, the current
time is used. On success, the routine returns true. On error, it returns
false, 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.
int cw_identify_receive_tone_internal(int element_usec, char
*representation)
Analyses a tone using the ranges provided by the low level timing parameters. On
success, it returns true and sends back either a dot or a dash in
representation. On error, it returns false with errno set to ENOENT if the
tone is not recognizable as either a dot or a dash, and sets the receive state
to one of the error states, depending on the tone length passed in.
Note; for adaptive timing, the tone should _always_ be recognized as a dot or a
dash, because the ranges will have been set to cover 0 to INT_MAX.
void cw_update_adaptive_tracking_internal(int element_usec, char element)
Updates the averages of dot and dash lengths, and recalculates the adaptive
threshold for the next receive tone.
int cw_end_receive_tone(const struct timeval *timestamp)
Called on the end of a receive tone. If the timestamp is NULL, the current time
is used. On success, the routine adds a dot or dash to the receive
representation buffer, and returns true. On error, it returns false, with
errno set to ERANGE if the call was not preceded by a cw_start_receive_tone
call, EINVAL if the timestamp passed in is not valid, ENOENT if the tone
length was out of bounds for the permissible dot and dash lengths and fixed
speed receiving is selected, ENOMEM if the representation buffer is full, or
EAGAIN if the tone was shorter than the threshold for noise and was therefore
ignored.
int cw_receive_buffer_element_internal(const struct timeval *timestamp,
char element)
Adds either a dot or a dash to the receive representation buffer. If the
timestamp is NULL, the current timestamp is used. The receive state is updated
as if we had just received a call to cw_end_receive_tone.
int cw_receive_buffer_dot(const struct timeval *timestamp)
Brief: Add a dot to the receive representation buffer.
If the timestamp is NULL, the current timestamp is used. These routines are for
callers that have 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 element is added to the receive
representation buffer. On error, the routines return false, 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
receive buffer, or ENOMEM if the receive representation buffer is full.
int cw_receive_buffer_dash(const struct timeval *timestamp)
Brief: Add a dash to the receive representation buffer.
See documentation of cw_receive_buffer_dot() for more information
int cw_receive_representation(const struct timeval *timestamp,
char *representation, bool *is_end_of_word,
bool *is_error)
Returns the current buffered representation from the receive buffer. On success,
the function returns true, and fills in representation with the contents of
the current representation buffer. On error, it returns false, with errno set
to ERANGE if not preceded 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, or
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
inter-character gap period elapsed since the last cw_end_receive_tone or
cw_receive_buffer_dot/dash call). is_end_of_word indicates that the delay
after the last tone received is longer that the inter-word gap, and is_error
indicates that the representation was terminated by an error condition.
int cw_receive_character(const struct timeval *timestamp,
char *c, bool *is_end_of_word, bool *is_error)
Returns the current buffered character from the representation buffer. On
success, the function returns true, and fills char *c with the contents of the
current representation buffer, translated into a character. On error, it
returns false, with errno set to ERANGE if not preceded by a
cw_end_receive_tone call, a prior successful 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 inter-character gap period elapsed since the last cw_end_receive_tone
or cw_receive_buffer_dot/dash call). is_end_of_word indicates that the delay
after the last tone received is longer that the inter-word gap, and is_error
indicates that the character was terminated by an error condition.
void cw_clear_receive_buffer(void)
Clears the receive representation buffer to receive tones 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 tones.
int cw_get_receive_buffer_capacity(void)
Returns the number of entries the receive buffer can accommodate. The maximum
number of character written out by cw_receive_representation is the capacity +
1, the extra character being used for the terminating NUL.
int cw_get_receive_buffer_length(void)
Returns the number of elements currently pending in the receive buffer.
void cw_reset_receive(void)
Clear the receive representation buffer, statistics, and any retained receive
state. This function is suitable for calling from an application exit handler.
void cw_enable_iambic_curtis_mode_b(void)
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 information
int cw_get_iambic_curtis_mode_b_state(void)
See documentation of cw_enable_iambic_curtis_mode_b() for more information
void cw_keyer_clock_internal(void)
Informs the internal keyer states that the itimer expired, and we received
SIGALRM.
int cw_notify_keyer_paddle_event(int dot_paddle_state,
int dash_paddle_state)
Informs the internal keyer states that the 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 true. On error, it returns false, 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.
int cw_notify_keyer_dot_paddle_event(int dot_paddle_state)
Convenience functions to alter the state of just one of the two iambic keyer
paddles. The other paddle state of the paddle pair remains unchanged.
See cw_keyer_paddle_event for details of iambic keyer background processing, and
how to check its status.
int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
See documentation of cw_notify_keyer_dot_paddle_event() for more information
void cw_get_keyer_paddles(int *dot_paddle_state, int *dash_paddle_state)
Returns the current saved states of the two paddles.
void cw_get_keyer_paddle_latches(int *dot_paddle_latch_state,
int *dash_paddle_latch_state)
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 sending.
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)
Waits until the end of the current element, dot or dash, from the keyer. This
routine returns true on success. On error, it returns false, with errno set to
EDEADLK if SIGALRM is blocked.
int cw_wait_for_keyer(void)
Waits for the current keyer cycle to complete. The routine returns true on
success. On error, it returns false, with errno set to EDEADLK if SIGALRM is
blocked or if either paddle state is true.
void cw_reset_keyer(void)
Clear all keyer latches and paddle states, return to Curtis 8044 Keyer mode A,
and return to silence. This function is suitable for calling from an
application exit handler.
void cw_straight_key_clock_internal(void)
Soundcard tone data is only buffered to last about a second on each
cw_generate_sound_internal() call, and holding down the straight key for
longer than this could cause a soundcard data underrun. To guard against this,
a timeout is generated every half-second or so while the straight key is down.
The timeout generates a chunk of sound data for the soundcard.
int cw_notify_straight_key_event(int key_state)
Informs the library that the straight key has changed state. This routine
returns true on success. On error, it returns false, 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.
int cw_get_straight_key_state(void)
Returns the current saved state of the straight key; true if the key is down,
false if up.
bool cw_is_straight_key_busy(void)
Returns true if the straight key is busy, false if not. This routine is just a
pseudonym for cw_get_straight_key_state, and exists to fill a hole in the API
naming conventions.
void cw_reset_straight_key(void)
Clears the straight key state, and returns to silence. This function is suitable
for calling from an application exit handler.
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, Console, OSS, ALSA,
Soundcard
Returns: audio system's label
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_generator_start() for
this.
Parameter: audio_system - audio system to be used by the generator (console,
OSS, ALSA, soundcard, see 'enum cw_audio_systems')
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 sound using generator created with cw_generator_new().
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. If you want to use the
generator again, you have to call cw_generator_start().
int cw_generator_calculate_sine_wave(cw_gen_t *gen)
Brief: Calculate a fragment of sine wave
Calculate a fragment of sine wave, as many samples as can be fitted in
generator's buffer. There will be gen->buffer_n_samples samples put into
gen->buffer, starting from gen->buffer[0].
The function takes into account all state variables from gen, so initial phase
of new fragment of sine wave in the buffer matches ending phase of a sine wave
generated in current call.
Parameter: gen - current generator
Returns: CW_SUCCESS
int cw_generator_calculate_amplitude(cw_gen_t *gen)
Brief: Calculate value of a sample of sine wave
Parameter: gen - generator used to generate a sine wave
Returns: value of a sample of sine wave, a non-negative number
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 platforms 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 happily 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_open_device_console(const char *device)
Brief: Open console PC speaker device
The function doesn't check if ioctl(fd, KIOCSOUND, ...) works, the client code
must use cw_is_console_possible() instead, prior to calling this function.
Parameter: device - name of console device to be used; if NULL then library will
use default device.
Returns: CW_FAILURE on errors
Returns: CW_SUCCESS on success
void cw_close_device_console(void)
Brief: Close console device associated with current generator
int cw_sound_console_internal(int state)
Brief: Start generating a sound using console PC speaker
The function calls the KIOCSOUND ioctl to start a particular tone. Once started,
the console tone generation needs no maintenance.
The function only initializes generation, you have to do another function call
to change the tone generated.
Parameter: state - flag deciding if a sound should be generated (> 0) or not
(== 0)
Returns: CW_FAILURE on errors
Returns: CW_SUCCESS on success
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;
int cw_open_device_oss(const char *device)
Brief: Open OSS output, associate it with current generator
Parameter: device - name of OSS device to be used; if NULL then library will use
default device.
Returns: CW_FAILURE on errors
Returns: CW_SUCCESS on success
int cw_open_device_oss_ioctls(int *fd, int *sample_rate)
Brief: Perform all necessary ioctl calls on OSS file descriptor
Wrapper function for ioctl calls that need to be done when configuring file
descriptor
fd for OSS playback.
Parameter: fd - file descriptor of open OSS file;
Parameter: sample_rate - sample rate configured by ioctl calls (output
parameter)
Returns: CW_FAILURE on errors
Returns: CW_SUCCESS on success
void cw_close_device_oss(void)
Brief: Close OSS device associated with current generator
void *cw_generator_write_sine_wave_oss(void *arg)
Brief: Write a constant sine wave to OSS output
Parameter: arg - current generator (casted to (void *))
Returns: NULL pointer
bool cw_is_alsa_possible(const char *device)
Brief: Check if it is possible to open ALSA output
Function 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;
int cw_open_device_alsa(const char *device)
Brief: Open ALSA output, associate it with current generator
Parameter: device - name of ALSA device to be used; if NULL then library will
use default device.
Returns: CW_FAILURE on errors
Returns: CW_SUCCESS on success
void cw_close_device_alsa(void)
Brief: Close ALSA device associated with current generator
void *cw_generator_write_sine_wave_alsa(void *arg)
Brief: Write a constant sine wave to ALSA output
Parameter: arg - current generator (casted to (void *))
Returns: NULL pointer
int cw_set_alsa_hw_params(snd_pcm_t *handle, snd_pcm_hw_params_t *params)
Brief: Set up hardware buffer parameters of ALSA sink
Parameter: handle - ALSA handle to configure
Parameter: params - allocated hw params data structure to be used
Returns: CW_FAILURE on errors
Returns: CW_SUCCESS on success
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 settings, 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 kernel 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).