Linux Certif

Toute la documentation sur la certification Linux LPI

cwlib

NAME

cwlib - general purpose Morse code functions library

SYNOPSIS

 #include <cwlib.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)
 
 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)
 
 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)
 
 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_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_block_callback (int is_block)
 
 void cw_set_console_file (const char *new_value)
 
 const char * cw_get_console_file (void)
 
 void cw_set_soundcard_file (const char *new_value)
 
 const char * cw_get_soundcard_file (void)
 
 void cw_set_soundmixer_file (const char *new_value)
 
 const char * cw_get_soundmixer_file (void)
 
 int cw_is_soundcard_possible (void)
 
 int cw_is_console_possible (void)
 
 void cw_set_console_sound (int sound_state)
 
 int cw_get_console_sound (void)
 
 void cw_set_soundcard_sound (int sound_state)
 
 int cw_get_soundcard_sound (void)
 
 void cw_complete_reset (void)
 
 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)
 
 int cw_register_tone_queue_low_callback (void (*callback_func) (void*),
 void *callback_arg, int level)
 
 int 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)
 
 int 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_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_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_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_enable_adaptive_receive (void)
 
 void cw_disable_adaptive_receive (void)
 
 int 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,
 char *representation, int *is_end_of_word,
 int *is_error)
 
 int cw_receive_character (const struct timeval *timestamp,
 char *c, int *is_end_of_word, int *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)
 
 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)
 
 int 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)
 
 int cw_is_straight_key_busy (void)
 
 void cw_reset_straight_key (void)
 
 

DESCRIPTION

cwlib 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

cwlib 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

cwlib 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.

cwlib 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

cwlib 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

cwlib 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

cwlib 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

cwlib 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 cwlib caller:

 
 
 int cw_version (void)
 
 

Returns the version number of the library. Version numbers are returned as an int, composed of major_version << 16 | minor_version.

 
 
 void cw_license (void)
 
 

Prints a short library licensing message to stdout.

 
 
 void cw_set_debug_flags (unsigned int new_value)
 
 

Sets a value for the library debug flags. Debug output is generally strings printed on stderr. There is no validation of flags.

 
 
 unsigned int cw_get_debug_flags (void)
 
 

Retrieves library debug flags. If no flags are set, then on first call, it will check the environment variable CWLIB_DEBUG, and if it is available, will set debug flags to its value. The provides a way for a program to set the debug flags without needing to make any source code changes.

 
 
 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.

 
 
 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.

 
 
 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.

 
 
 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)
 
 
 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)
 
 

Return the limits on the speed, frequency, volume, gap, tolerance, and weighting parameters. Normal values are speed 4-60 WPM, frequency 0-10,000 Hz, volume 0-70 %, gap 0-20 dots, tolerance 0-90 %, and weighting 20-80 %.

 
 
 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)
 
 
 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)
 
 

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.

 
 
 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)
 
 

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.

 
 
 int cw_set_noise_spike_threshold (int threshold)
 
 
 int cw_get_noise_spike_threshold (void)
 
 

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.

 
 
 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.

 
 
 void cw_set_console_file (const char *new_value)
 
 
 const char * cw_get_console_file (void)
 
 

Get and set routines for the path to the console device through which the library generates PC speaker sound. The set routine does not return any indication of whether the device is a valid console; for that, use cw_is_console_possible() to test to see if the value passed in might be an acceptable console device.

The default console file is /dev/console. The call is ingored on platforms that do no support the KIOCSOUND ioctl.

 
 
 void cw_set_soundcard_file (const char *new_value)
 
 
 const char * cw_get_soundcard_file (void)
 
 

Get and set routines for the path to the sound device through which the library generates soundcard sound. The set routine does not return any indication of whether the device is a valid soundcard; use cw_is_soundcard_possible() to test to see if the value passed in might be an acceptable soundcard device.

The default soundcard file is /dev/audio.

 
 
 void cw_set_soundmixer_file (const char *new_value)
 
 
 const char * cw_get_soundmixer_file (void)
 
 

Get and set routines for the path to the mixer device that the library may use to gate soundcard sound. The library uses the mixer device where the main sound device does not support the PCM volume control ioctl call; this tends to occur on newer OSS drivers, but not on older ones, or on ALSA in OSS emulation mode. The set routine does not return any indication of whether the device is a valid mixer.

The default sound mixer file is /dev/mixer.

 
 
 int cw_is_soundcard_possible (void)
 
 

Return success status if it appears that the library will be able to generate tones through a sound card. If it appears that a sound card may not work, the routine returns FALSE to indicate failure.

The function tests only that the given sound card file exists and is writable.

 
 
 int cw_is_console_possible (void)
 
 

Return success status if it appears that the library will be able to generate tones through the console speaker. If it appears that console sound may not work, the routine returns FALSE to indicate failure.

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.

 
 
 void cw_set_console_sound (int sound_state)
 
 
 int cw_get_console_sound (void)
 
 

Enable and disable console sound output, and return the current console sound output setting. By default, console sound output is disabled. On platforms that do not support the KIOCSOUND ioctl, enabling console sound output has no effect.

 
 
 void cw_set_soundcard_sound (int sound_state)
 
 
 int cw_get_soundcard_sound (void)
 
 

Enable and disable soundcard sound output, and return the current soundcard sound output setting. By default, soundcard sound output is enabled.

 
 
 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.

 
 
 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.

 
 
 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.

 
 
 int 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.

 
 
 int 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_dot (void)
 
 
 int cw_send_dash (void)
 
 
 int cw_send_character_space (void)
 
 
 int cw_send_word_space (void)
 
 

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_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_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_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_enable_adaptive_receive (void)
 
 
 void cw_disable_adaptive_receive (void)
 
 
 int cw_get_adaptive_receive_state (void)
 
 

Enable and disable 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.

 
 
 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_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_dot (const struct timeval *timestamp)
 
 
 int cw_receive_buffer_dash (const struct timeval *timestamp)
 
 

Adds either a dot or a dash 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_representation (const struct timeval *timestamp,
 char *representation, int *is_end_of_word,
 int *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, int *is_end_of_word, int *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)
 
 
 void cw_disable_iambic_curtis_mode_b (void)
 
 
 int cw_get_iambic_curtis_mode_b_state (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.

 
 
 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)
 
 
 int cw_notify_keyer_dash_paddle_event (int dash_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.

 
 
 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.

 
 
 int cw_is_keyer_busy (void)
 
 

Indicates if the keyer is busy; returns TRUE if the keyer is going through a dot or dash cycle, FALSE if the keyer is idle.

 
 
 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.

 
 
 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.

 
 
 int 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.

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.

cwlib 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).