1LIBCW(3) Library Functions Manual LIBCW(3)
2
6 libcw - general purpose Morse code functions library
7
9 #include <libcw.h>
10 int cw_generator_new(int audio_system, const char *device)
12 void cw_generator_delete(void)
13 int cw_generator_start(void)
14 void cw_generator_stop(void)
15 int cw_set_send_speed(int new_value)
16 int cw_set_frequency(int new_value)
17 int cw_set_volume(int new_value)
18 int cw_set_gap(int new_value)
19 int cw_set_weighting(int new_value)
20 int cw_get_send_speed(void)
21 int cw_get_frequency(void)
22 int cw_get_volume(void)
23 int cw_get_gap(void)
24 int cw_get_weighting(void)
25 void cw_get_send_parameters(int *dot_usecs, int *dash_usecs,
26 int *end_of_element_usecs,
27 int *end_of_character_usecs, int
28 *end_of_word_usecs,
29 int *additional_usecs, int *adjust‐
30 ment_usecs)
31 int cw_send_dot(void)
32 int cw_send_dash(void)
33 int cw_send_character_space(void)
34 int cw_send_word_space(void)
35 int cw_send_representation(const char *representation)
36 int cw_send_representation_partial(const char *representation)
37 int cw_send_character(char c)
38 int cw_send_character_partial(char c)
39 int cw_send_string(const char *string)
40 void cw_reset_send_receive_parameters(void)
41 const char *cw_get_console_device(void)
42 const char *cw_get_soundcard_device(void)
43 const char *cw_generator_get_audio_system_label(void)
44 int cw_register_tone_queue_low_callback(void (*callback_func)(void*),
45 void *callback_arg, int level)
46 bool cw_is_tone_busy(void)
47 int cw_wait_for_tone(void)
48 int cw_wait_for_tone_queue(void)
49 int cw_wait_for_tone_queue_critical(int level)
50 bool cw_is_tone_queue_full(void)
51 int cw_get_tone_queue_capacity(void)
52 int cw_get_tone_queue_length(void)
53 void cw_flush_tone_queue(void)
54 void cw_reset_tone_queue(void)
55 int cw_queue_tone(int usecs, int frequency)
56 int cw_set_receive_speed(int new_value)
57 int cw_get_receive_speed(void)
58 int cw_set_tolerance(int new_value)
59 int cw_get_tolerance(void)
60 void cw_get_receive_parameters(int *dot_usecs, int *dash_usecs,
61 int *dot_min_usecs, int *dot_max_usecs,
62 int *dash_min_usecs, int
63 *dash_max_usecs,
64 int *end_of_element_min_usecs,
65 int *end_of_element_max_usecs,
66 int *end_of_element_ideal_usecs,
67 int *end_of_character_min_usecs,
68 int *end_of_character_max_usecs,
69 int *end_of_character_ideal_usecs,
70 int *adaptive_threshold)
71 int cw_set_noise_spike_threshold(int new_value)
72 int cw_get_noise_spike_threshold(void)
73 void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
74 double *element_end_sd, double *charac‐
75 ter_end_sd)
76 void cw_reset_receive_statistics(void)
77 void cw_enable_adaptive_receive(void)
78 void cw_disable_adaptive_receive(void)
79 bool cw_get_adaptive_receive_state(void)
80 int cw_start_receive_tone(const struct timeval *timestamp)
81 int cw_end_receive_tone(const struct timeval *timestamp)
82 int cw_receive_buffer_dot(const struct timeval *timestamp)
83 int cw_receive_buffer_dash(const struct timeval *timestamp)
84 int cw_receive_representation(const struct timeval *timestamp,
85 /* out */ char *representation,
86 /* out */ bool *is_end_of_word,
87 /* out */ bool *is_error)
88 int cw_receive_character(const struct timeval *timestamp,
89 /* out */ char *c,
90 /* out */ bool *is_end_of_word,
91 /* out */ bool *is_error)
92 void cw_clear_receive_buffer(void)
93 int cw_get_receive_buffer_capacity(void)
94 int cw_get_receive_buffer_length(void)
95 void cw_reset_receive(void)
96 void cw_register_keying_callback(void (*callback_func)(void*, int),
97 void *callback_arg)
98 void cw_enable_iambic_curtis_mode_b(void)
99 void cw_disable_iambic_curtis_mode_b(void)
100 int cw_get_iambic_curtis_mode_b_state(void)
101 int cw_notify_keyer_paddle_event(int dot_paddle_state, int dash_pad‐
102 dle_state)
103 int cw_notify_keyer_dot_paddle_event(int dot_paddle_state)
104 int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
105 void cw_get_keyer_paddles(int *dot_paddle_state, int *dash_pad‐
106 dle_state)
107 void cw_get_keyer_paddle_latches(int *dot_paddle_latch_state, int
108 *dash_paddle_latch_state)
109 bool cw_is_keyer_busy(void)
110 int cw_wait_for_keyer_element(void)
111 int cw_wait_for_keyer(void)
112 void cw_reset_keyer(void)
113 int cw_notify_straight_key_event(int key_state)
114 int cw_get_straight_key_state(void)
115 bool cw_is_straight_key_busy(void)
116 void cw_reset_straight_key(void)
117 bool cw_is_alsa_possible(const char *device)
118 bool cw_is_console_possible(const char *device)
119 int cw_console_write(cw_gen_t *gen, cw_tone_t *tone)
120 int cw_get_character_count(void)
121 void cw_list_characters(char *list)
122 int cw_get_maximum_representation_length(void)
123 int cw_lookup_character(char c, char *representation)
124 char *cw_character_to_representation(int c)
125 int cw_check_representation(const char *representation)
126 bool cw_representation_is_valid(const char *representation)
127 int cw_lookup_representation(const char *representation, char *c)
128 int cw_representation_to_character(const char *representation)
129 int cw_get_procedural_character_count(void)
130 void cw_list_procedural_characters(char *list)
131 int cw_get_maximum_procedural_expansion_length(void)
132 int cw_lookup_procedural_character(char c, char *expansion, int
133 *is_usually_expanded)
134 int cw_get_maximum_phonetic_length(void)
135 int cw_lookup_phonetic(char c, char *phonetic)
136 bool cw_character_is_valid(char c)
137 bool cw_string_is_valid(const char *string)
138 void cw_debug_flush(cw_debug_t *debug)
139 void cw_set_debug_flags(uint32_t flags)
140 void cw_debug_set_flags(cw_debug_t *debug_object, uint32_t flags)
141 uint32_t cw_get_debug_flags(void)
142 uint32_t cw_debug_get_flags(cw_debug_t *debug_object)
143 bool cw_debug_has_flag(cw_debug_t *debug_object, uint32_t flag)
144 int cw_generator_set_tone_slope(cw_gen_t *gen, int slope_shape, int
145 slope_len)
146 bool cw_is_oss_possible(const char *device)
147 bool cw_is_pa_possible(const char *device)
148 void cw_block_callback(int block)
149 int cw_register_signal_handler(int signal_number, void (*call‐
150 back_func)(int))
151 int cw_unregister_signal_handler(int signal_number)
152 int cw_version(void)
153 void cw_license(void)
154 const char *cw_get_audio_system_label(int audio_system)
155 void cw_get_speed_limits(int *min_speed, int *max_speed)
156 void cw_get_frequency_limits(int *min_frequency, int *max_frequency)
157 void cw_get_volume_limits(int *min_volume, int *max_volume)
158 void cw_get_gap_limits(int *min_gap, int *max_gap)
159 void cw_get_tolerance_limits(int *min_tolerance, int *max_tolerance)
160 void cw_get_weighting_limits(int *min_weighting, int *max_weighting)
161 void cw_complete_reset(void)
162 DESCRIPTION
165 libcw is a general purpose CW (Morse code) functions library. It con‐
166 tains routines for converting characters into Morse code representa‐
167 tions and back again, for sending Morse code characters, and for
168 receiving characters. It also contains routines to emulate an Iambic
169 Morse keyer, and a straight key.
170 The library can be included in any program that wishes to make use of
172 these features. It forms the heart of three Morse code tutor applica‐
173 tions that accompany the package in which it is distributed.
174 See the cw(7) man page for information on Morse code timings, and the
176 dot and dash representations for the various Morse characters.
177 TONE QUEUE
179 libcw contains an inbuilt tone queue. The queue is emptied by back‐
180 ground processing, using SIGALRM calls and itimers, so a caller program
181 can continue with other tasks while the library sends tones and keys
182 any external device.
183 As well as being used by the library functions that sound Morse code
185 characters and provide a keyer sidetone, the primitive tone queue func‐
186 tions are publicly available to caller programs.
187 CONTROLLING AN EXTERNAL DEVICE
189 libcw may be passed the address of a function that controls external
190 keying. This function is called each time the library changes the key‐
191 ing state, either as a result of sending a Morse character or represen‐
192 tation, or as a result of an iambic keyer or straight key state change.
193 The argument passed is a single integer, TRUE for key-down, and FALSE
194 for key-up.
195 libcw calls the external keying function only when the keying state
197 changes. A call is likely each time a tone is taken off the tone
198 queue.
199 SENDING CW CHARACTERS AND STRINGS
201 libcw offers several functions that send individual characters and
202 character strings as Morse code. It also offers functions that allow
203 specialized 'representations' to be sent. A 'representation' is an
204 ASCII string that consists of only the characters '.' and '-'.
205 Characters and strings are converted into representations, and then the
207 correct tones for the dots and dashes in these representations are
208 queued on the tone queue, for action by the background queue emptying
209 process.
210 RECEIVING CW CHARACTERS AND REPRESENTATIONS
212 libcw contains functions to allow it to receive Morse code. To
213 receive, the library must be told when a tone start is detected, and
214 when a tone end is detected. It then determines whether the tone was a
215 dot or a dash depending on the timing difference between the two.
216 After the required silence gap has passed, the library may be queried
217 to see what the received representation or character was.
218 Errors in receiving may be detected by means of the flags passed back
220 on receive character functions.
221 IAMBIC KEYER
223 libcw offers functions to simulate an Iambic Morse keyer. The caller
224 program needs to tell the library of paddle state changes. Iambic
225 keyer functions are mutually exclusive with character send and straight
226 key functions.
227 STRAIGHT KEY
229 libcw offers simple functions to allow effective pass-through of
230 straight key information. The caller program needs to tell the library
231 of key state changes. Straight key functions are mutually exclusive
232 with character send and iambic keyer functions.
233 RETURN CODES
235 Some of the library's function return a return code of type int. The
236 return code has two values, as defined in libcw.h: CW_SUCCESS or
237 CW_FAILURE. The two symbolic constants are guaranteed to be identical
238 to boolean true and false.
239 FUNCTIONS
241 The following list describes the functions available to a libcw caller:
242 int cw_generator_new(int audio_system, const char *device)
246 Brief: Create new generator
247 Allocate memory for new generator data structure, set up default values
249 of some of the generator's properties. The function does not start the
250 generator (generator does not produce a sound), you have to use cw_gen‐
251 erator_start() for this.
252 Notice that the function doesn't return a generator variable. There is
254 at most one generator variable at any given time. You can't have two
255 generators. In some future version of the library the function will
256 return pointer to newly allocated generator, and then you could have as
257 many of them as you want, but not yet.
258 audio_system can be one of following: NULL, console, OSS, ALSA,
260 PulseAudio, soundcard. See "enum cw_audio_systems" in libcw.h for exact
261 names of symbolic constants.
262 Parameter: audio_system - audio system to be used by the generator
264 Parameter: device - name of audio device to be used; if NULL then
265 library will use default device.
266 void cw_generator_delete(void)
270 Brief: Deallocate generator
271 Deallocate/destroy generator data structure created with call to
273 cw_generator_new(). You can't start nor use the generator after the
274 call to this function.
275 int cw_generator_start(void)
279 Brief: Start a generator
280 Start producing tones using generator created with cw_generator_new().
282 The source of tones is a tone queue associated with the generator. If
283 the tone queue is empty, the generator will wait for new tones to be
284 queued.
285 Returns: CW_FAILURE on errors
287 Returns: CW_SUCCESS on success
288 void cw_generator_stop(void)
292 Brief: Shut down a generator
293 Silence tone generated by generator (level of generated sine wave is
295 set to zero, with falling slope), and shut the generator down.
296 The shutdown does not erase generator's configuration.
298 If you want to have this generator running again, you have to call
300 cw_generator_start().
301 int cw_set_send_speed(int new_value)
305 Brief: Set sending speed of generator
306 See libcw.h/CW_SPEED_{INITIAL|MIN|MAX} for initial/minimal/maximal
308 value of send speed.
309 errno is set to EINVAL if new_value is out of range.
311 Parameter: new_value - new value of send speed to be assigned to gener‐
314 ator
315 Returns: CW_SUCCESS on success
317 Returns: CW_FAILURE on failure
318 int cw_set_frequency(int new_value)
322 Brief: Set frequency of generator
323 Set frequency of sound wave generated by generator. The frequency must
325 be within limits marked by CW_FREQUENCY_MIN and CW_FREQUENCY_MAX.
326 See libcw.h/CW_FREQUENCY_{INITIAL|MIN|MAX} for initial/minimal/maximal
328 value of frequency.
329 errno is set to EINVAL if new_value is out of range.
331 Parameter: new_value - new value of frequency to be assigned to genera‐
333 tor
334 Returns: CW_SUCCESS on success
336 Returns: CW_FAILURE on failure
337 int cw_set_volume(int new_value)
341 Brief: Set volume of generator
342 Set volume of sound wave generated by generator. The volume must be
344 within limits marked by CW_VOLUME_MIN and CW_VOLUME_MAX.
345 Note that volume settings are not fully possible for the console
347 speaker. In this case, volume settings greater than zero indicate con‐
348 sole speaker sound is on, and setting volume to zero will turn off con‐
349 sole speaker sound.
350 See libcw.h/CW_VOLUME_{INITIAL|MIN|MAX} for initial/minimal/maximal
352 value of volume. errno is set to EINVAL if new_value is out of range.
353 Parameter: new_value - new value of volume to be assigned to generator
356 Returns: CW_SUCCESS on success
358 Returns: CW_FAILURE on failure
359 int cw_set_gap(int new_value)
363 Brief: Set sending gap of generator
364 See libcw.h/CW_GAP_{INITIAL|MIN|MAX} for initial/minimal/maximal value
366 of gap. errno is set to EINVAL if new_value is out of range.
367 Notice that this function also sets the same gap value for library's
369 receiver.
370 Parameter: new_value - new value of gap to be assigned to generator
373 Returns: CW_SUCCESS on success
375 Returns: CW_FAILURE on failure
376 int cw_set_weighting(int new_value)
380 Brief: Set sending weighting for generator
381 See libcw.h/CW_WEIGHTING_{INITIAL|MIN|MAX} for initial/minimal/maximal
383 value of weighting. errno is set to EINVAL if new_value is out of
384 range.
385 Parameter: new_value - new value of weighting to be assigned for gener‐
388 ator
389 Returns: CW_SUCCESS on success
391 Returns: CW_FAILURE on failure
392 int cw_get_send_speed(void)
396 Brief: Get sending speed from generator
397 Returns: current value of the generator's send speed
400 int cw_get_frequency(void)
404 Brief: Get frequency from generator
405 Function returns "frequency" parameter of generator, even if the gener‐
407 ator is stopped, or volume of generated sound is zero.
408 Returns: current value of generator's frequency
411 int cw_get_volume(void)
415 Brief: Get sound volume from generator
416 Function returns "volume" parameter of generator, even if the generator
418 is stopped.
419 Returns: current value of generator's sound volume
422 int cw_get_gap(void)
426 Brief: Get sending gap from generator
427 Returns: current value of generator's sending gap
430 int cw_get_weighting(void)
434 Brief: Get sending weighting from generator
435 Returns: current value of generator's sending weighting
438 void cw_get_send_parameters(int *dot_usecs, int *dash_usecs,
442 int *end_of_element_usecs,
443 int *end_of_character_usecs, int
444 *end_of_word_usecs,
445 int *additional_usecs, int *adjustment_usecs)
446 Brief: Get timing parameters for sending
447 Return the low-level timing parameters calculated from the speed, gap,
449 tolerance, and weighting set. Parameter values are returned in
450 microseconds.
451 Use NULL for the pointer argument to any parameter value not required.
453 Parameter: dot_usecs
455 Parameter: dash_usecs
456 Parameter: end_of_element_usecs
457 Parameter: end_of_character_usecs
458 Parameter: end_of_word_usecs
459 Parameter: additional_usecs
460 Parameter: adjustment_usecs
461 int cw_send_dot(void)
465 Brief: Low-level primitive for sending a dot mark
466 Low-level primitive function able to play/send single dot mark. The
468 function appends to a tone queue a normal inter-mark gap after the dot
469 mark.
470 Returns: CW_SUCCESS on success
473 Returns: CW_FAILURE on failure
474 int cw_send_dash(void)
478 Brief: Low-level primitive for sending a dash mark
479 Low-level primitive function able to play/send single dash mark. The
481 function appends to a tone queue a normal inter-mark gap after the dash
482 mark.
483 Returns: CW_SUCCESS on success
486 Returns: CW_FAILURE on failure
487 int cw_send_character_space(void)
491 The function plays space timed to exclude the expected prior dot/dash
493 inter-mark gap. FIXME: fix this description.
494 Returns: CW_SUCCESS on success
497 Returns: CW_FAILURE on failure
498 int cw_send_word_space(void)
502 The function sends space timed to exclude both the expected prior
504 dot/dash inter-mark gap and the prior end of character space. FIXME:
505 fix this description.
506 Returns: CW_SUCCESS on success
509 Returns: CW_FAILURE on failure
510 int cw_send_representation(const char *representation)
514 Brief: Check, then send the given string as dots and dashes.
515 The representation passed in is assumed to be a complete Morse charac‐
517 ter; that is, all post-character delays will be added when the charac‐
518 ter is sent.
519 On success, the routine returns CW_SUCCESS. On failure, it returns
521 CW_FAILURE, with errno set to EINVAL if any character of the represen‐
522 tation is invalid, EBUSY if the sound card, console speaker, or keying
523 system is busy, or EAGAIN if the tone queue is full, or if there is
524 insufficient space to queue the tones or the representation.
525 Parameter: representation - representation to send
528 Returns: CW_SUCCESS on success
530 Returns: CW_FAILURE on failure
531 int cw_send_representation_partial(const char *representation)
535 Brief: Check, then send the given string as dots and dashes
536 The representation passed in is assumed to be only part of a larger
538 Morse representation; that is, no post-character delays will be added
539 when the character is sent.
540 On success, the routine returns CW_SUCCESS. On failure, it returns
542 CW_FAILURE, with errno set to EINVAL if any character of the represen‐
543 tation is invalid, EBUSY if the sound card, console speaker, or keying
544 system is busy, or EAGAIN if the tone queue is full, or if there is
545 insufficient space to queue the tones for the representation.
546 int cw_send_character(char c)
551 Brief: Look up and send a given ASCII character as Morse
552 The end of character delay is appended to the Morse sent.
554 On success the routine returns CW_SUCCESS. On failure the function
556 returns CW_FAILURE and sets errno.
557 errno is set to ENOENT if the given character c is not a valid Morse
559 character. errno is set to EBUSY if current audio sink or keying sys‐
560 tem is busy. errno is set to EAGAIN if the generator's tone queue is
561 full, or if there is insufficient space to queue the tones for the
562 character.
563 This routine returns as soon as the character has been successfully
565 queued for sending; that is, almost immediately. The actual sending
566 happens in background processing. See cw_wait_for_tone() and
567 cw_wait_for_tone_queue() for ways to check the progress of sending.
568 Parameter: c - character to send
571 Returns: CW_SUCCESS on success
573 Returns: CW_FAILURE on failure
574 int cw_send_character_partial(char c)
578 Brief: Look up and send a given ASCII character as Morse code
579 "partial" means that the "end of character" delay is not appended to
581 the Morse code sent by the function, to support the formation of combi‐
582 nation characters.
583 On success the function returns CW_SUCCESS. On failure the function
585 returns CW_FAILURE and sets errno.
586 errno is set to ENOENT if the given character c is not a valid Morse
588 character. errno is set to EBUSY if the audio sink or keying system is
589 busy. errno is set to EAGAIN if the tone queue is full, or if there is
590 insufficient space to queue the tones for the character.
591 This routine queues its arguments for background processing. See
593 cw_wait_for_tone() and cw_wait_for_tone_queue() for ways to check the
594 progress of sending.
595 Parameter: c - character to send
597 Returns: CW_SUCCESS on success
599 Returns: CW_FAILURE on failure
600 int cw_send_string(const char *string)
604 Brief: Send a given ASCII string in Morse code
605 errno is set to ENOENT if any character in the string is not a valid
607 Morse character.
608 errno is set to EBUSY if audio sink or keying system is busy.
610 errno is set to EAGAIN if the tone queue is full or if the tone queue
612 runs out of space part way through queueing the string. However, an
613 indeterminate number of the characters from the string will have
614 already been queued.
615 For safety, clients can ensure the tone queue is empty before queueing
617 a string, or use cw_send_character() if they need finer control.
618 This routine queues its arguments for background processing, the actual
620 sending happens in background processing. See cw_wait_for_tone() and
621 cw_wait_for_tone_queue() for ways to check the progress of sending.
622 Parameter: string - string to send
625 Returns: CW_SUCCESS on success
627 Returns: CW_FAILURE on failure
628 void cw_reset_send_receive_parameters(void)
632 Brief: Reset send/receive parameters
633 Reset the library speed, frequency, volume, gap, tolerance, weighting,
635 adaptive receive, and noise spike threshold to their initial default
636 values: send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0
637 dots, tolerance 50 %, and weighting 50 %.
638 const char *cw_get_console_device(void)
642 Brief: Return char string with console device path
643 Returned pointer is owned by library.
645 Returns: char string with current console device path
647 const char *cw_get_soundcard_device(void)
651 Brief: Return char string with soundcard device name/path
652 Returned pointer is owned by library.
654 Returns: char string with current soundcard device name or device path
656 const char *cw_generator_get_audio_system_label(void)
660 Brief: Get a readable label of current audio system
661 The function returns one of following strings: None, Null, Console,
663 OSS, ALSA, PulseAudio, Soundcard
664 Returns: audio system's label
666 int cw_register_tone_queue_low_callback(void (*callback_func)(void*),
670 void *callback_arg, int level)
671 Brief: Register callback for low queue state
672 Register a function to be called automatically by the dequeue routine
674 whenever the tone queue falls to a given level. To be more precise: the
675 callback is called by queue manager if, after dequeueing a tone, the
676 manager notices that tone queue length has become equal or less than
677 level.
678 callback_arg may be used to give a value passed back on callback calls.
680 A NULL function pointer suppresses callbacks. On success, the routine
681 returns CW_SUCCESS.
682 If level is invalid, the routine returns CW_FAILURE with errno set to
684 EINVAL. Any callback supplied will be called in signal handler con‐
685 text.
686 Parameter: callback_func - callback function to be registered
689 Parameter: callback_arg - argument for callback_func to pass return
690 value
691 Parameter: level - low level of queue triggering callback call
692 Returns: CW_SUCCESS on successful registration
694 Returns: CW_FAILURE on failure
695 bool cw_is_tone_busy(void)
699 Brief: Check if tone sender is busy
700 Indicate if the tone sender is busy.
702 Returns: true if there are still entries in the tone queue
704 Returns: false if the queue is empty
705 int cw_wait_for_tone(void)
709 Brief: Wait for the current tone to complete
710 The routine returns CW_SUCCESS on success. If called with SIGALRM
712 blocked, the routine returns CW_FAILURE, with errno set to EDEADLK, to
713 avoid indefinite waits.
714 Returns: CW_SUCCESS on success
717 Returns: CW_FAILURE on failure
718 int cw_wait_for_tone_queue(void)
722 Brief: Wait for the tone queue to drain
723 The routine returns CW_SUCCESS on success. If called with SIGALRM
725 blocked, the routine returns false, with errno set to EDEADLK, to avoid
726 indefinite waits.
727 Returns: CW_SUCCESS on success
730 Returns: CW_FAILURE on failure
731 int cw_wait_for_tone_queue_critical(int level)
735 Brief: Wait for the tone queue to drain until only as many tones as
736 given in level remain queued
737 This routine is for use by programs that want to optimize themselves to
739 avoid the cleanup that happens when the tone queue drains completely;
740 such programs have a short time in which to add more tones to the
741 queue.
742 The routine returns CW_SUCCESS on success. If called with SIGALRM
744 blocked, the routine returns false, with errno set to EDEADLK, to avoid
745 indefinite waits.
746 Parameter: level - low level in queue, at which to return
748 Returns: CW_SUCCESS on success
750 Returns: CW_FAILURE on failure
751 bool cw_is_tone_queue_full(void)
755 Brief: Indicate if the tone queue is full
756 Returns: true if tone queue is full
759 Returns: false if tone queue is not full
760 int cw_get_tone_queue_capacity(void)
764 Brief: Return the number of entries the tone queue can accommodate
765 int cw_get_tone_queue_length(void)
770 Brief: Return the number of entries currently pending in the tone queue
771 void cw_flush_tone_queue(void)
776 Brief: Cancel all pending queued tones, and return to silence.
777 If there is a tone in progress, the function will wait until this last
779 one has completed, then silence the tones.
780 This function may be called with SIGALRM blocked, in which case it will
782 empty the queue as best it can, then return without waiting for the
783 final tone to complete. In this case, it may not be possible to guar‐
784 antee silence after the call.
785 void cw_reset_tone_queue(void)
789 Cancel all pending queued tones, reset any queue low callback regis‐
790 tered, and return to silence. This function is suitable for calling
791 from an application exit handler.
792 int cw_queue_tone(int usecs, int frequency)
796 Brief: Primitive access to simple tone generation
797 This routine queues a tone of given duration and frequency. The rou‐
799 tine returns CW_SUCCESS on success. If usec or frequency are invalid,
800 it returns CW_FAILURE with errno set to EINVAL. If the sound card,
801 console speaker, or keying function are busy, it returns CW_FAILURE
802 with errno set to EBUSY. If the tone queue is full, it returns false
803 with errno set to EAGAIN.
804 Parameter: usecs - duration of queued tone, in microseconds
807 Parameter: frequency - frequency of queued tone
808 Returns: CW_SUCCESS on success
810 Returns: CW_FAILURE on failure
811 int cw_set_receive_speed(int new_value)
815 Brief: Set receiving speed of receiver
816 See documentation of cw_set_send_speed() for more information.
818 See libcw.h/CW_SPEED_{INITIAL|MIN|MAX} for initial/minimal/maximal
820 value of receive speed. errno is set to EINVAL if new_value is out of
821 range. errno is set to EPERM if adaptive receive speed tracking is
822 enabled.
823 Parameter: new_value - new value of receive speed to be assigned to
826 receiver
827 Returns: CW_SUCCESS on success
829 Returns: CW_FAILURE on failure
830 int cw_get_receive_speed(void)
834 Brief: Get receiving speed from receiver
835 Returns: current value of the receiver's receive speed
838 int cw_set_tolerance(int new_value)
842 Brief: Set tolerance for receiver
843 See libcw.h/CW_TOLERANCE_{INITIAL|MIN|MAX} for initial/minimal/maximal
845 value of tolerance. errno is set to EINVAL if new_value is out of
846 range.
847 Parameter: new_value - new value of tolerance to be assigned to
850 receiver
851 Returns: CW_SUCCESS on success
853 Returns: CW_FAILURE on failure
854 int cw_get_tolerance(void)
858 Brief: Get tolerance from receiver
859 Returns: current value of receiver's tolerance
862 void cw_get_receive_parameters(int *dot_usecs, int *dash_usecs,
866 int *dot_min_usecs, int *dot_max_usecs,
867 int *dash_min_usecs, int *dash_max_usecs,
868 int *end_of_element_min_usecs,
869 int *end_of_element_max_usecs,
870 int *end_of_element_ideal_usecs,
871 int *end_of_character_min_usecs,
872 int *end_of_character_max_usecs,
873 int *end_of_character_ideal_usecs,
874 int *adaptive_threshold)
875 Brief: Get timing parameters for receiving, and adaptive threshold
876 Return the low-level timing parameters calculated from the speed, gap,
878 tolerance, and weighting set. Parameter values are returned in
879 microseconds.
880 Use NULL for the pointer argument to any parameter value not required.
882 Parameter: dot_usecs
884 Parameter: dash_usecs
885 Parameter: dot_min_usecs
886 Parameter: dot_max_usecs
887 Parameter: dash_min_usecs
888 Parameter: dash_max_usecs
889 Parameter: end_of_element_min_usecs
890 Parameter: end_of_element_max_usecs
891 Parameter: end_of_element_ideal_usecs
892 Parameter: end_of_character_min_usecs
893 Parameter: end_of_character_max_usecs
894 Parameter: end_of_character_ideal_usecs
895 Parameter: adaptive_threshold
896 int cw_set_noise_spike_threshold(int new_value)
900 Brief: Set noise spike threshold for receiver
901 Set the period shorter than which, on receive, received marks are
903 ignored. This allows the "receive mark" functions to apply noise can‐
904 celing for very short apparent marks. For useful results the value
905 should never exceed the dot length of a dot at maximum speed: 20000
906 microseconds (the dot length at 60WPM). Setting a noise threshold of
907 zero turns off receive mark noise canceling.
908 The default noise spike threshold is 10000 microseconds.
910 errno is set to EINVAL if new_value is out of range.
912 Parameter: new_value - new value of noise spike threshold to be
914 assigned to receiver
915 Returns: CW_SUCCESS on success
917 Returns: CW_FAILURE on failure
918 int cw_get_noise_spike_threshold(void)
922 Brief: Get noise spike threshold from receiver
923 See documentation of cw_set_noise_spike_threshold() for more informa‐
925 tion
926 Returns: current value of receiver's threshold
928 void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
932 double *element_end_sd, double *charac‐
933 ter_end_sd)
934 Brief: Calculate and return receiver's timing statistics
935 These statistics may be used to obtain a measure of the accuracy of
937 received CW. The values dot_sd and dot_sd contain the standard devia‐
938 tion of dot and dash lengths from the ideal values, and element_end_sd
939 and element_end_sd the deviations for inter element and inter character
940 spacing. Statistics are held for all timings in a 256 element circular
941 buffer. If any statistic cannot be calculated, because no records for
942 it exist, the returned value is 0.0. Use NULL for the pointer argument
943 to any statistic not required.
944 Parameter: dot_sd
946 Parameter: dash_sd
947 Parameter: element_end_sd
948 Parameter: character_end_sd
949 void cw_reset_receive_statistics(void)
953 Brief: Clear the receive statistics buffer
954 Clear the receive statistics buffer by removing all records from it and
956 returning it to its initial default state.
957 void cw_enable_adaptive_receive(void)
961 Brief: Enable adaptive receive speed tracking
962 If adaptive speed tracking is enabled, the receive functions will
964 attempt to automatically adjust the receive speed setting to match the
965 speed of the incoming Morse code. If it is disabled, the receive func‐
966 tions will use fixed speed settings, and reject incoming Morse which is
967 not at the expected speed.
968 Adaptive speed tracking uses a moving average length of the past N
970 marks as its baseline for tracking speeds. The default state is adap‐
971 tive speed tracking disabled.
972 void cw_disable_adaptive_receive(void)
976 Brief: Disable adaptive receive speed tracking
977 See documentation of cw_enable_adaptive_receive() for more information
979 bool cw_get_adaptive_receive_state(void)
983 Brief: Get adaptive receive speed tracking flag
984 The function returns state of "adaptive receive enabled" flag. See
986 documentation of cw_enable_adaptive_receive() for more information
987 Returns: true if adaptive speed tracking is enabled
989 Returns: false otherwise
990 int cw_start_receive_tone(const struct timeval *timestamp)
994 Brief: Signal beginning of receive mark
995 Called on the start of a receive mark. If the timestamp is NULL, the
997 current timestamp is used as beginning of mark.
998 The function should be called by client application when pressing a key
1000 down (closing a circuit) has been detected by client application.
1001 On error the function returns CW_FAILURE, with errno set to ERANGE if
1003 the call is directly after another cw_start_receive_tone() call or if
1004 an existing received character has not been cleared from the buffer, or
1005 EINVAL if the timestamp passed in is invalid.
1006 Parameter: timestamp - time stamp of "key down" event
1008 Returns: CW_SUCCESS on success
1010 Returns: CW_FAILURE otherwise (with errno set)
1011 int cw_end_receive_tone(const struct timeval *timestamp)
1015 Brief: Signal end of mark
1016 The function should be called by client application when releasing a
1018 key (opening a circuit) has been detected by client application.
1019 If the timestamp is NULL, the current time is used as timestamp of end
1021 of mark.
1022 On success, the routine adds a dot or dash to the receiver's represen‐
1024 tation buffer, and returns CW_SUCCESS.
1025 On failure, it returns CW_FAIURE, with errno set to: ERANGE if the call
1027 was not preceded by a cw_start_receive_tone() call, EINVAL if the time‐
1028 stamp passed in is not valid, ENOENT if the mark length was out of
1029 bounds for the permissible dot and dash lengths and fixed speed receiv‐
1030 ing is selected, ENOMEM if the receiver's representation buffer is
1031 full, EAGAIN if the mark was shorter than the threshold for noise and
1032 was therefore ignored.
1033 Parameter: timestamp - time stamp of "key up" event
1035 Returns: CW_SUCCESS on success
1037 Returns: CW_FAILURE on failure
1038 int cw_receive_buffer_dot(const struct timeval *timestamp)
1042 Brief: Add a dot to the receiver's representation buffer
1043 Documentation for both cw_receive_buffer_dot() and cw_receive_buf‐
1045 fer_dash():
1046 Since we can't add a mark to the buffer without any accompanying timing
1048 information, the functions accepts timestamp of the "end of mark"
1049 event. If the timestamp is NULL, the current timestamp is used.
1050 These routines are for client code that has already determined whether
1052 a dot or dash was received by a method other than calling the routines
1053 cw_start_receive_tone() and cw_end_receive_tone().
1054 On success, the relevant mark is added to the receiver's representation
1056 buffer.
1057 On failure, the routines return CW_FAILURE, with errno set to ERANGE if
1059 preceded by a cw_start_receive_tone() call with no matching
1060 cw_end_receive_tone() or if an error condition currently exists within
1061 the receiver's buffer, or ENOMEM if the receiver's representation buf‐
1062 fer is full.
1063 Parameter: timestamp - timestamp of "end of dot" event
1065 Returns: CW_SUCCESS on success
1067 Returns: CW_FAILURE on failure
1068 int cw_receive_buffer_dash(const struct timeval *timestamp)
1072 Brief: Add a dash to the receiver's representation buffer
1073 See documentation of cw_receive_buffer_dot() for more information.
1075 Parameter: timestamp - timestamp of "end of dash" event
1077 Returns: CW_SUCCESS on success
1079 Returns: CW_FAILURE on failure
1080 int cw_receive_representation(const struct timeval *timestamp,
1084 /* out */ char *representation,
1085 /* out */ bool *is_end_of_word,
1086 /* out */ bool *is_error)
1087 Brief: Get the current buffered representation from the receiver's rep‐
1088 resentation buffer
1089 On success the function fills in representation with the contents of
1091 the current representation buffer and returns CW_SUCCESS.
1092 On failure, it returns CW_FAILURE and sets errno to: ERANGE if not pre‐
1094 ceded by a cw_end_receive_tone() call, a prior successful
1095 cw_receive_representation call, or a prior cw_receive_buffer_dot or
1096 cw_receive_buffer_dash, EINVAL if the timestamp passed in is invalid,
1097 EAGAIN if the call is made too early to determine whether a complete
1098 representation has yet been placed in the buffer (that is, less than
1099 the end-of-character gap period elapsed since the last
1100 cw_end_receive_tone() or cw_receive_buffer_dot/dash call). This is not
1101 a *hard* error, just an information that the caller should try to get
1102 the representation later.
1103 is_end_of_word indicates that the space after the last mark received is
1105 longer that the end-of-character gap, so it must be qualified as end-
1106 of-word gap.
1107 is_error indicates that the representation was terminated by an error
1109 condition.
1110 TODO: the function should be called cw_receiver_poll_representation().
1112 The function is called periodically (poll()-like function) by client
1114 code in hope that at some attempt receiver will be ready to pass repre‐
1115 sentation. The attempt succeeds only if data stream is in "space"
1116 state. To mark end of the space, client code has to provide a timestamp
1117 (or pass NULL timestamp, the function will get time stamp at function
1118 call). The receiver needs to know the "end of space" event - thus the
1119 timestamp parameter.
1120 Parameter: timestamp - timestamp of event that ends "end-of-character"
1123 gap or "end-of-word" gap
1124 Parameter: representation - buffer for representation (output parame‐
1125 ter)
1126 Parameter: is_end_of_word - buffer for "is end of word" state (output
1127 parameter)
1128 Parameter: is_error - buffer for "error" state (output parameter)
1129 Returns: CW_SUCCESS on success
1131 Returns: CW_FAILURE on failure
1132 int cw_receive_character(const struct timeval *timestamp,
1136 /* out */ char *c,
1137 /* out */ bool *is_end_of_word,
1138 /* out */ bool *is_error)
1139 Brief: Get a current character
1140 Function returns the character currently stored in receiver's represen‐
1142 tation buffer.
1143 On success the function returns CW_SUCCESS, and fills c with the con‐
1145 tents of the current representation buffer, translated into a charac‐
1146 ter.
1147 On failure the function returns CW_FAILURE, with errno set to:
1149 ERANGE if not preceded by a cw_end_receive_tone() call, a prior suc‐
1151 cessful cw_receive_character() call, or a cw_receive_buffer_dot() or
1152 cw_receive_buffer_dash() call, EINVAL if the timestamp passed in is
1153 invalid, or EAGAIN if the call is made too early to determine whether a
1154 complete character has yet been placed in the buffer (that is, less
1155 than the end-of-character gap period elapsed since the last
1156 cw_end_receive_tone() or cw_receive_buffer_dot/dash call). ENOENT if
1157 character stored in receiver cannot be recognized as valid
1158 is_end_of_word indicates that the space after the last mark received is
1160 longer that the end-of-character gap, so it must be qualified as end-
1161 of-word gap.
1162 is_error indicates that the character was terminated by an error condi‐
1164 tion.
1165 Parameter: timestamp - timestamp of event that ends end-of-character
1168 gap or end-of-word gap
1169 Parameter: c - buffer for character (output parameter)
1170 Parameter: is_end_of_word - buffer for "is end of word" state (output
1171 parameter)
1172 Parameter: is_error - buffer for "error" state (output parameter)
1173 Returns: CW_SUCCESS on success
1175 Returns: CW_FAILURE on failure
1176 void cw_clear_receive_buffer(void)
1180 Brief: Clear receiver's representation buffer
1181 Clears the receiver's representation buffer, resets receiver's internal
1183 state. This prepares the receiver to receive marks and spaces again.
1184 This routine must be called after successful, or terminating,
1186 cw_receive_representation() or cw_receive_character() calls, to clear
1187 the states and prepare the buffer to receive more marks and spaces.
1188 int cw_get_receive_buffer_capacity(void)
1192 Brief: Get the number of elements (dots/dashes) the receiver's buffer
1193 can accommodate
1194 The maximum number of elements written out by cw_receive_representa‐
1196 tion() is the capacity + 1, the extra character being used for the ter‐
1197 minating NUL.
1198 Returns: number of elements that can be stored in receiver's represen‐
1200 tation buffer
1201 int cw_get_receive_buffer_length(void)
1205 Brief: Get the number of elements (dots/dashes) currently pending in
1206 the cw_receiver's representation buffer
1207 Returns: number of elements in receiver's representation buffer
1210 void cw_reset_receive(void)
1214 Brief: Clear receive data
1215 Clear the receiver's representation buffer, statistics, and any
1217 retained receiver's state. This function is suitable for calling from
1218 an application exit handler.
1219 void cw_register_keying_callback(void (*callback_func)(void*, int),
1223 void *callback_arg)
1224 Brief: Register external callback function for keying
1225 Register a callback_func function that should be called when a state of
1227 a key changes from "key open" to "key closed", or vice-versa.
1228 The first argument passed to the registered callback function is the
1230 supplied callback_arg, if any. The second argument passed to regis‐
1231 tered callback function is the key state: CW_KEY_STATE_CLOSED
1232 (one/true) for "key closed", and CW_KEY_STATE_OPEN (zero/false) for
1233 "key open".
1234 Calling this routine with a NULL function address disables keying call‐
1236 backs. Any callback supplied will be called in signal handler context
1237 (??).
1238 Parameter: callback_func - callback function to be called on key state
1240 changes
1241 Parameter: callback_arg - first argument to callback_func
1242 void cw_enable_iambic_curtis_mode_b(void)
1246 Brief: Enable iambic Curtis mode B
1247 Normally, the iambic keying functions will emulate Curtis 8044 Keyer
1249 mode A. In this mode, when both paddles are pressed together, the last
1250 dot or dash being sent on release is completed, and nothing else is
1251 sent. In mode B, when both paddles are pressed together, the last dot
1252 or dash being sent on release is completed, then an opposite element is
1253 also sent. Some operators prefer mode B, but timing is more critical in
1254 this mode. The default mode is Curtis mode A.
1255 void cw_disable_iambic_curtis_mode_b(void)
1259 See documentation of cw_enable_iambic_curtis_mode_b() for more informa‐
1260 tion
1261 int cw_get_iambic_curtis_mode_b_state(void)
1265 See documentation of cw_enable_iambic_curtis_mode_b() for more informa‐
1266 tion
1267 int cw_notify_keyer_paddle_event(int dot_paddle_state, int dash_pad‐
1271 dle_state)
1272 Brief: Inform about changed state of iambic keyer's paddles
1273 Function informs the library that the iambic keyer paddles have changed
1275 state. The new paddle states are recorded, and if either transition
1276 from false to true, paddle latches, for iambic functions, are also set.
1277 On success, the routine returns CW_SUCCESS. On failure, it returns
1279 CW_FAILURE, with errno set to EBUSY if the tone queue or straight key
1280 are using the sound card, console speaker, or keying system.
1281 If appropriate, this routine starts the keyer functions sending the
1283 relevant element. Element send and timing occurs in the background, so
1284 this routine returns almost immediately. See cw_keyer_element_wait()
1285 and cw_keyer_wait() for details about how to check the current status
1286 of iambic keyer background processing.
1287 Parameter: dot_paddle_state
1290 Parameter: dash_paddle_state
1291 Returns: CW_SUCCESS on success
1293 Returns: CW_FAILURE on failure
1294 int cw_notify_keyer_dot_paddle_event(int dot_paddle_state)
1298 Brief: Change state of dot paddle
1299 Alter the state of just one of the two iambic keyer paddles. The other
1301 paddle state of the paddle pair remains unchanged.
1302 See cw_notify_keyer_paddle_event() for details of iambic keyer back‐
1304 ground processing, and how to check its status.
1305 Parameter: dot_paddle_state
1307 int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
1311 See documentation of cw_notify_keyer_dot_paddle_event() for more infor‐
1312 mation
1313 void cw_get_keyer_paddles(int *dot_paddle_state, int *dash_pad‐
1317 dle_state)
1318 Brief: Get the current saved states of the two paddles
1319 Parameter: dot_paddle_state
1322 Parameter: dash_paddle_state
1323 void cw_get_keyer_paddle_latches(int *dot_paddle_latch_state, int
1327 *dash_paddle_latch_state)
1328 Brief: Get the current states of paddle latches
1329 Function returns the current saved states of the two paddle latches. A
1331 paddle latches is set to true when the paddle state becomes true, and
1332 is cleared if the paddle state is false when the element finishes send‐
1333 ing.
1334 Parameter: dot_paddle_latch_state
1336 Parameter: dash_paddle_latch_state
1337 bool cw_is_keyer_busy(void)
1341 Brief: Check if a keyer is busy
1342 Returns: true if keyer is busy
1344 Returns: false if keyer is not busy
1345 int cw_wait_for_keyer_element(void)
1349 Brief: Wait for end of element from the keyer
1350 Waits until the end of the current element, dot or dash, from the
1352 keyer.
1353 On error the function returns CW_FAILURE, with errno set to EDEADLK if
1355 SIGALRM is blocked.
1356 Returns: CW_SUCCESS on success
1359 Returns: CW_FAILURE on failure
1360 int cw_wait_for_keyer(void)
1364 Brief: Wait for the current keyer cycle to complete
1365 The routine returns CW_SUCCESS on success. On error, it returns
1367 CW_FAILURE, with errno set to EDEADLK if SIGALRM is blocked or if
1368 either paddle state is true.
1369 Returns: CW_SUCCESS on success
1371 Returns: CW_FAILURE on failure
1372 void cw_reset_keyer(void)
1376 Brief: Reset iambic keyer data
1377 Clear all latches and paddle states of iambic keyer, return to Curtis
1379 8044 Keyer mode A, and return to silence. This function is suitable
1380 for calling from an application exit handler.
1381 int cw_notify_straight_key_event(int key_state)
1385 Brief: Inform the library that the straight key has changed state
1386 This routine returns CW_SUCCESS on success. On error, it returns
1388 CW_FAILURE, with errno set to EBUSY if the tone queue or iambic keyer
1389 are using the sound card, console speaker, or keying control system.
1390 If key_state indicates no change of state, the call is ignored.
1391 key_state may be either CW_KEY_STATE_OPEN (false) or
1393 CW_KEY_STATE_CLOSED (true).
1394 Parameter: key_state - state of straight key
1397 int cw_get_straight_key_state(void)
1401 Brief: Get saved state of straight key
1402 Returns the current saved state of the straight key.
1404 Returns: CW_KEY_STATE_CLOSED (true) if the key is down
1407 Returns: CW_KEY_STATE_OPEN (false) if the key up
1408 bool cw_is_straight_key_busy(void)
1412 Brief: Check if the straight key is busy
1413 This routine is just a pseudonym for cw_get_straight_key_state(), and
1415 exists to fill a hole in the API naming conventions.
1416 Returns: true if the straight key is busy
1419 Returns: false if the straight key is not busy
1420 void cw_reset_straight_key(void)
1424 Brief: Clear the straight key state, and return to silence
1425 This function is suitable for calling from an application exit handler.
1427 bool cw_is_alsa_possible(const char *device)
1431 Brief: Check if it is possible to open ALSA output
1432 Function first tries to load ALSA library, and then does a test opening
1434 of ALSA output, but it closes it before returning.
1435 Parameter: device - name of ALSA device to be used; if NULL then
1437 library will use default device.
1438 Returns: true if opening ALSA output succeeded;
1440 Returns: false if opening ALSA output failed;
1441 bool cw_is_console_possible(const char *device)
1445 Brief: Check if it is possible to open console output
1446 Function does a test opening and test writing to console device, but it
1448 closes it before returning.
1449 The function tests that the given console file exists, and that it will
1451 accept the KIOCSOUND ioctl. It unconditionally returns false on plat‐
1452 forms that do no support the KIOCSOUND ioctl.
1453 Call to ioctl will fail if calling code doesn't have root privileges.
1455 This is the only place where we ask if KIOCSOUND is defined, so client
1457 code must call this function whenever it wants to use console output,
1458 as every other function called to perform console operations will hap‐
1459 pily assume that it is allowed to perform such operations.
1460 Parameter: device - name of console device to be used; if NULL then
1462 library will use default device.
1463 Returns: true if opening console output succeeded;
1465 Returns: false if opening console output failed;
1466 int cw_console_write(cw_gen_t *gen, cw_tone_t *tone)
1470 Brief: Pseudo-device for playing sound with console
1471 Function behaving like a device, to which one does a blocking write.
1473 It generates sound with parameters (frequency and duration) specified
1474 in tone.. After playing X microseconds of tone it returns. It is
1475 intended to behave like a blocking write() function.
1476 Parameter: gen - current generator
1478 Parameter: tone - tone to play with generator
1479 Returns: CW_SUCCESS on success
1481 Returns: CW_FAILURE on failure
1482 int cw_get_character_count(void)
1486 Brief: Return the number of characters present in character lookup ta‐
1487 ble
1488 Return the number of characters that are known to libcw. The number
1490 includes:
1491 ·
1493 ASCII 7bit letters,
1494 ·
1496 numerals,
1497 ·
1499 punctuation,
1500 ·
1502 ISO 8859-1 accented characters,
1503 ·
1505 ISO 8859-2 accented characters,
1506 ·
1508 non-standard procedural signal extensions to standard CW
1509 characters.
1510 Returns: number of characters known to libcw
1513 void cw_list_characters(char *list)
1517 Brief: Get list of characters present in character lookup table
1518 Function provides a string containing all of the characters represented
1520 in library's lookup table.
1521 The list includes:
1523 ·
1525 ASCII 7bit letters,
1526 ·
1528 numerals,
1529 ·
1531 punctuation,
1532 ·
1534 ISO 8859-1 accented characters,
1535 ·
1537 ISO 8859-2 accented characters,
1538 ·
1540 non-standard procedural signal extensions to standard CW
1541 characters.
1542 list should be allocated and managed by caller. The length of list
1544 must be at least one greater than the number of characters represented
1545 in the character lookup table, returned by cw_get_character_count().
1546 Parameter: list - pointer to space to be filled by function
1549 int cw_get_maximum_representation_length(void)
1553 Brief: Get length of the longest representation
1554 Function returns the string length of the longest representation in the
1556 character lookup table.
1557 Returns: a positive number - length of the longest representation
1560 int cw_lookup_character(char c, char *representation)
1564 Brief: Get representation of a given character
1565 The function is depreciated, use cw_character_to_representation()
1567 instead.
1568 Return the string representation (shape) of a given Morse code charac‐
1570 ter c.
1571 The routine returns CW_SUCCESS on success, and fills in the string
1573 pointer (representation) passed in. On failure, it returns CW_FAILURE
1574 and sets errno to ENOENT, indicating that the character c could not be
1575 found.
1576 The length of representation buffer must be at least one greater than
1578 the length of longest representation held in the character lookup ta‐
1579 ble. The largest value of length is returned by cw_get_maximum_repre‐
1580 sentation_length().
1581 Parameter: c - character to look up
1583 Parameter: representation - pointer to space for representation of
1584 character
1585 Returns: CW_SUCCESS on success
1587 Returns: CW_FAILURE on failure
1588 char *cw_character_to_representation(int c)
1592 Brief: Get representation of a given character
1593 On success return representation of a given character. Returned
1595 pointer is owned by caller of the function.
1596 On failure function returns NULL and sets errno: ENOENT indicates that
1598 the character could not be found. ENOMEM indicates that character has
1599 been found, but function failed to strdup() representation.
1600 Parameter: c - character to look up
1603 Returns: pointer to freshly allocated representation on success
1605 Returns: NULL on failure
1606 int cw_check_representation(const char *representation)
1610 Brief: Check if representation of a character is valid
1611 This function is depreciated, use cw_representation_is_valid() instead.
1613 Check that the given string is a valid Morse representation. A valid
1615 string is one composed of only "." and "-" characters.
1616 If representation is invalid, function returns CW_FAILURE and sets
1618 errno to EINVAL.
1619 Parameter: representation - representation of a character to check
1621 Returns: CW_SUCCESS on success
1623 Returns: CW_FAILURE on failure
1624 bool cw_representation_is_valid(const char *representation)
1628 Brief: Check if representation of a character is valid
1629 Check that the given string is a valid Morse representation. A valid
1631 string is one composed of only "." and "-" characters. This means that
1632 the function checks only if representation is error-free, and not
1633 whether the representation represents existing/defined character.
1634 If representation is invalid, function returns false and sets errno to
1636 EINVAL.
1637 Parameter: representation - representation of a character to check
1640 Returns: true on success
1642 Returns: false on failure
1643 int cw_lookup_representation(const char *representation, char *c)
1647 Brief: Get the character represented by a given Morse representation
1648 This function is depreciated, use cw_representation_to_character()
1650 instead.
1651 Function checks representation, and if it is valid and represents a
1653 known character, function returns CW_SUCCESS. Additionally, if c is
1654 non-NULL, function puts the looked up character in c.
1655 c should be allocated by caller. Function assumes that c being NULL
1657 pointer is a valid situation, and can return CW_SUCCESS in such situa‐
1658 tion.
1659 On error, function returns CW_FAILURE. errno is set to EINVAL if any
1661 character of the representation is invalid, or ENOENT to indicate that
1662 the character represented by representation could not be found.
1663 Parameter: representation - representation of a character to look up
1665 Parameter: c - location where to put looked up character
1666 Returns: CW_SUCCESS on success
1668 Returns: CW_FAILURE on failure
1669 int cw_representation_to_character(const char *representation)
1673 Brief: Return the character represented by a given Morse representation
1674 Function checks representation, and if it is valid and represents a
1676 known character, function returns the character (a non-zero value).
1677 On error, function returns zero. errno is set to EINVAL if any charac‐
1679 ter of the representation is invalid, or ENOENT to indicate that the
1680 character represented by representation could not be found.
1681 Parameter: representation - representation of a character to look up
1684 Returns: non-zero character on success
1686 Returns: zero on failure
1687 int cw_get_procedural_character_count(void)
1691 Brief: Get number of procedural signals
1692 Returns: the number of characters represented in the procedural signal
1695 expansion lookup table
1696 void cw_list_procedural_characters(char *list)
1700 Brief: Get list of characters for which procedural expansion is avail‐
1701 able
1702 Function returns into list a string containing all of the Morse charac‐
1704 ters for which procedural expansion is available. The length of list
1705 must be at least by one greater than the number of characters repre‐
1706 sented in the procedural signal expansion lookup table, returned by
1707 cw_get_procedural_character_count().
1708 list is managed by caller
1710 Parameter: list - space for returned characters
1713 int cw_get_maximum_procedural_expansion_length(void)
1717 Brief: Get length of the longest procedural expansion
1718 Function returns the string length of the longest expansion in the pro‐
1720 cedural signal expansion table.
1721 Returns: length
1724 int cw_lookup_procedural_character(char c, char *expansion, int
1728 *is_usually_expanded)
1729 Brief: Get the string expansion of a given Morse code procedural signal
1730 character
1731 On success the function - fills expansion with the string expansion of
1733 a given Morse code procedural signal character c; - sets is_usu‐
1734 all_expanded to true as a display hint for the caller; - returns
1735 CW_SUCCESS.
1736 Both expansion and expansion must be allocated and managed by caller.
1738 They can be NULL, then the function won't attempt to use them.
1739 The length of expansion must be at least by one greater than the long‐
1741 est expansion held in the procedural signal character lookup table, as
1742 returned by cw_get_maximum_procedural_expansion_length().
1743 If procedural signal character c cannot be found, the function sets
1745 errno to ENOENT and returns CW_FAILURE.
1746 Parameter: c - character to look up
1749 Parameter: expansion - output, space to fill with expansion of the
1750 character
1751 Parameter: is_usually_expanded - visual hint
1752 Returns: CW_FAILURE on failure (errno is set to ENOENT)
1754 Returns: CW_SUCCESS on success
1755 int cw_get_maximum_phonetic_length(void)
1759 Brief: Get maximum length of a phonetic
1760 Returns: the string length of the longest phonetic in the phonetics
1763 lookup table
1764 int cw_lookup_phonetic(char c, char *phonetic)
1768 Brief: Get the phonetic of a given character
1769 On success the routine fills in the string pointer passed in with the
1771 phonetic of given character c.
1772 The length of phonetic must be at least one greater than the longest
1774 phonetic held in the phonetic lookup table, as returned by cw_get_maxi‐
1775 mum_phonetic_length().
1776 If character cannot be found, the function sets errno to ENOENT.
1778 Parameter: c - character to look up
1781 Parameter: phonetic - output, space for phonetic of a character
1782 Returns: CW_SUCCESS on success
1784 Returns: CW_FAILURE on failure
1785 bool cw_character_is_valid(char c)
1789 Brief: Checks that the given character is validly sendable in Morse
1790 Function sets errno to ENOENT on failure.
1792 Parameter: c - character to check
1795 Returns: CW_SUCCESS if character is valid
1797 Returns: CW_FAILURE if character is invalid
1798 bool cw_string_is_valid(const char *string)
1802 Brief: Validate a string
1803 Check that each character in the given string is valid and can be sent
1805 by libcw as a Morse character.
1806 Function sets errno to EINVAL on failure
1808 Parameter: string - string to check
1811 Returns: CW_SUCCESS on success
1813 Returns: CW_FAILURE on failure
1814 void cw_debug_flush(cw_debug_t *debug)
1818 Brief: Write all events from the debug object to a file
1819 Function writes all events stored in the debug object to file associ‐
1821 ated with the object, and removes the events.
1822 List of events is preceded with "FLUSH START0 line, and followed by
1824 "FLUSH END0 line.
1825 Parameter: debug - debug object
1827 void cw_set_debug_flags(uint32_t flags)
1831 Brief: Set a value of internal debug flags variable
1832 Assign specified value to library's internal debug flags variable.
1834 Note that this function doesn't *append* given flag to the variable, it
1835 erases existing value and assigns new one. Use cw_get_debug_flags() if
1836 you want to OR new flag with existing ones.
1837 Parameter: new_value - new value to be assigned to the library
1839 void cw_debug_set_flags(cw_debug_t *debug_object, uint32_t flags)
1843 uint32_t cw_get_debug_flags(void)
1847 Brief: Get current library's debug flags
1848 Function returns value of library's internal debug variable.
1850 Returns: value of library's debug flags variable
1852 uint32_t cw_debug_get_flags(cw_debug_t *debug_object)
1856 bool cw_debug_has_flag(cw_debug_t *debug_object, uint32_t flag)
1860 Brief: Check if given debug flag is set
1861 Function checks if a specified debug flag is set in internal variable
1863 of libcw library.
1864 Parameter: flag - flag to be checked.
1866 Returns: true if given flag is set
1868 Returns: false if given flag is not set
1869 int cw_generator_set_tone_slope(cw_gen_t *gen, int slope_shape, int
1873 slope_len)
1874 Brief: Set parameters of tones generated by generator
1875 Most of variables related to slope of tones is in tone data type, but
1877 there are still some variables that are generator-specific, as they are
1878 common for all tones. This function sets two of these variables.
1879 A: If you pass to function conflicting values of slope_shape and
1882 slope_len, the function will return CW_FAILURE. These conflicting val‐
1883 ues are rectangular slope shape and larger than zero slope length. You
1884 just can't have rectangular slopes that have non-zero length.
1885 B: If you pass to function '-1' as value of both slope_shape and
1888 slope_len, the function won't change any of the related two generator's
1889 parameters.
1890 C1: If you pass to function '-1' as value of either slope_shape or
1893 slope_len, the function will attempt to set only this generator's
1894 parameter that is different than '-1'.
1895 C2: However, if selected slope shape is rectangular, function will set
1897 generator's slope length to zero, even if value of
1898 slope_len is '-1'.
1899 D: Notice that the function allows non-rectangular slope shape with
1902 zero length of the slopes. The slopes will be non-rectangular, but just
1903 unusually short.
1904 The function should be called every time one of following parameters
1907 change:
1908 ·
1911 shape of slope,
1912 ·
1914 length of slope,
1915 ·
1917 generator's sample rate,
1918 ·
1920 generator's volume.
1921 There are four supported shapes of slopes:
1923 ·
1925 linear (the only one supported by libcw until version
1926 4.1.1),
1927 ·
1929 raised cosine (supposedly the most desired shape),
1930 ·
1932 sine,
1933 ·
1935 rectangular.
1936 Use CW_TONE_SLOPE_SHAPE_* symbolic names as values of slope_shape.
1938 FIXME: first argument of this public function is gen, but no function
1940 provides access to generator variable.
1941 Parameter: gen - generator for which to set tone slope parameters
1943 Parameter: slope_shape - shape of slope: linear, raised cosine, sine,
1944 rectangular
1945 Parameter: slope_len - length of slope [microseconds]
1946 Returns: CW_SUCCESS on success
1948 Returns: CW_FAILURE on failure
1949 bool cw_is_oss_possible(const char *device)
1953 Brief: Check if it is possible to open OSS output
1954 Function does a test opening and test configuration of OSS output, but
1956 it closes it before returning.
1957 Parameter: device - name of OSS device to be used; if NULL then library
1959 will use default device.
1960 Returns: true if opening OSS output succeeded;
1962 Returns: false if opening OSS output failed;
1963 bool cw_is_pa_possible(const char *device)
1967 Brief: Check if it is possible to open PulseAudio output
1968 Function first tries to load PulseAudio library, and then does a test
1970 opening of PulseAudio output, but it closes it before returning.
1971 Parameter: device - sink device, NULL for default PulseAudio device
1973 Returns: true if opening PulseAudio output succeeded;
1975 Returns: false if opening PulseAudio output failed;
1976 void cw_block_callback(int block)
1980 Brief: Block the callback from being called
1981 Function blocks the callback from being called for a critical section
1983 of caller code if block is true, and unblocks the callback if block is
1984 false.
1985 Function works by blocking SIGALRM; a block should always be matched by
1987 an unblock, otherwise the tone queue will suspend forever.
1988 Parameter: block - pass 1 to block SIGALRM, and 0 to unblock it
1990 int cw_register_signal_handler(int signal_number, void (*call‐
1994 back_func)(int))
1995 Brief: Register a signal handler and optional callback function for
1996 given signal number
1997 On receipt of that signal, all library features will be reset to their
1999 default states. Following the reset, if callback_func is a function
2000 pointer, the function is called; if it is SIG_DFL, the library calls
2001 exit(); and if it is SIG_IGN, the library returns from the signal han‐
2002 dler.
2003 This is a convenience function for clients that need to clean up
2005 library on signals, with either exit, continue, or an additional func‐
2006 tion call; in effect, a wrapper round a restricted form of sigaction.
2007 The signal_number argument indicates which signal to catch.
2009 On problems errno is set to EINVAL if signal_number is invalid or if a
2011 handler is already installed for that signal, or to the sigaction error
2012 code.
2013 Parameter: signal_number
2015 Parameter: callback_func
2016 Returns: CW_SUCCESS - if the signal handler installs correctly
2018 Returns: CW_FAILURE - on errors or problems
2019 int cw_unregister_signal_handler(int signal_number)
2023 Brief: Unregister a signal handler interception
2024 Function removes a signal handler interception previously registered
2026 with cw_register_signal_handler().
2027 Parameter: signal_number
2029 Returns: true if the signal handler uninstalls correctly
2031 Returns: false otherwise (with errno set to EINVAL or to the sigaction
2032 error code)
2033 int cw_version(void)
2037 Brief: Return version number of libcw library
2038 Return the version number of the library. Version numbers (major and
2040 minor) are returned as an int, composed of major_version << 16 |
2041 minor_version.
2042 Returns: library's major and minor version number encoded as single int
2045 void cw_license(void)
2049 Brief: Print libcw's license text to stdout
2050 Function prints information about libcw version, followed by short text
2053 presenting libcw's copyright and license notice.
2054 const char *cw_get_audio_system_label(int audio_system)
2058 Brief: Get a readable label of given audio system
2059 The function returns one of following strings: None, Null, Console,
2061 OSS, ALSA, PulseAudio, Soundcard
2062 Returned pointer is owned and managed by the library.
2064 TODO: change the declaration to "const char *const cw_get_audio_sys‐
2066 tem_label(...)"?
2067 Parameter: audio_system - ID of audio system
2069 Returns: audio system's label
2071 void cw_get_speed_limits(int *min_speed, int *max_speed)
2075 Brief: Get speed limits
2076 Get (through function's arguments) limits on speed of morse code that
2078 can be generated by generator.
2079 See CW_SPEED_MIN and CW_SPEED_MAX in libcw.h for values.
2081 Parameter: min_speed - minimal allowed speed
2084 Parameter: max_speed - maximal allowed speed
2085 void cw_get_frequency_limits(int *min_frequency, int *max_frequency)
2089 Brief: Get frequency limits
2090 Get (through function's arguments) limits on frequency that can be gen‐
2092 erated by generator.
2093 See CW_FREQUENCY_MIN and CW_FREQUENCY_MAX in libcw.h for values.
2095 Parameter: min_frequency - minimal allowed frequency
2098 Parameter: max_frequency - maximal allowed frequency
2099 void cw_get_volume_limits(int *min_volume, int *max_volume)
2103 Brief: Get volume limits
2104 Get (through function's arguments) limits on volume of sound generated
2106 by generator.
2107 See CW_VOLUME_MIN and CW_VOLUME_MAX in libcw.h for values.
2109 Parameter: min_volume - minimal allowed volume
2112 Parameter: max_volume - maximal allowed volume
2113 void cw_get_gap_limits(int *min_gap, int *max_gap)
2117 Brief: Get gap limits
2118 Get (through function's arguments) limits on gap in cw signal generated
2120 by generator.
2121 See CW_GAP_MIN and CW_GAP_MAX in libcw.h for values.
2123 Parameter: min_gap - minimal allowed gap
2126 Parameter: max_gap - maximal allowed gap
2127 void cw_get_tolerance_limits(int *min_tolerance, int *max_tolerance)
2131 Brief: Get tolerance limits
2132 Get (through function's arguments) limits on "tolerance" parameter of
2134 generator.
2135 See CW_TOLERANCE_MIN and CW_TOLERANCE_MAX in libcw.h for values.
2137 Parameter: min_tolerance - minimal allowed tolerance
2140 Parameter: max_tolerance - maximal allowed tolerance
2141 void cw_get_weighting_limits(int *min_weighting, int *max_weighting)
2145 Brief: Get weighting limits
2146 Get (through function's arguments) limits on "weighting" parameter of
2148 generator.
2149 See CW_WEIGHTING_MIN and CW_WEIGHTING_MAX in libcw.h for values.
2151 Parameter: min_weighting - minimal allowed weighting
2154 Parameter: max_weighting - maximal allowed weighting
2155 void cw_complete_reset(void)
2159 Brief: Reset all library features to their default states
2160 Clears the tone queue, receive buffers and retained state information,
2162 any current keyer activity, and any straight key activity, returns to
2163 silence, and closes soundcard and console devices. This function is
2164 suitable for calling from an application exit handler.
2165
2167 Despite the fact that this manual page constantly and consistently
2168 refers to Morse code elements as dots and dashes, DO NOT think in these
2169 terms when trying to learn Morse code. Always think of them as 'dit's
2170 and 'dah's.
2171 libcw uses system itimers for its internal timing. On most UNIX
2173 flavours, itimers are not guaranteed to signal a program exactly at the
2174 specified time, and they generally offer a resolution only as good as
2175 the normal system 'clock tick' resolution. An itimer SIGALRM usually
2176 falls on a system clock tick, making it accurate to no better than 10mS
2177 on a typical 100Hz kernel.
2178 The effect of this is that an itimer period is generally either exactly
2180 as specified, or, more likely, slightly longer. At higher WPM set‐
2181 tings, the cumulative effect of this affects timing accuracy, because
2182 at higher speeds, there are fewer 10mS clock ticks in a dot period.
2183 For example, at 12 WPM, the dot length is 100mS, enough to contain five
2184 kernel clock ticks; at 60 WPM, the dot length is 20mS, or just two ker‐
2185 nel clock ticks. So at higher speeds, the effect of itimer resolutions
2186 becomes more pronounced.
2187
2189 Man pages for cw(7,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL), cwcp(1,LOCAL),
2190 and xcwcp(1,LOCAL).
2191libcw ver. 6.5.1 CW Tutor Package LIBCW(3)