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_generator_remove_last_character(void)
45 int cw_register_tone_queue_low_callback(void (*callback_func)(void*),
46 void *callback_arg, int level)
47 bool cw_is_tone_busy(void)
48 int cw_wait_for_tone(void)
49 int cw_wait_for_tone_queue(void)
50 int cw_wait_for_tone_queue_critical(int level)
51 bool cw_is_tone_queue_full(void)
52 int cw_get_tone_queue_capacity(void)
53 int cw_get_tone_queue_length(void)
54 void cw_flush_tone_queue(void)
55 void cw_reset_tone_queue(void)
56 int cw_queue_tone(int usecs, int frequency)
57 int cw_set_receive_speed(int new_value)
58 int cw_get_receive_speed(void)
59 int cw_set_tolerance(int new_value)
60 int cw_get_tolerance(void)
61 void cw_get_receive_parameters(int *dot_usecs, int *dash_usecs,
62 int *dot_min_usecs, int *dot_max_usecs,
63 int *dash_min_usecs, int
64 *dash_max_usecs,
65 int *end_of_element_min_usecs,
66 int *end_of_element_max_usecs,
67 int *end_of_element_ideal_usecs,
68 int *end_of_character_min_usecs,
69 int *end_of_character_max_usecs,
70 int *end_of_character_ideal_usecs,
71 int *adaptive_threshold)
72 int cw_set_noise_spike_threshold(int new_value)
73 int cw_get_noise_spike_threshold(void)
74 void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
75 double *element_end_sd, double *charac‐
76 ter_end_sd)
77 void cw_reset_receive_statistics(void)
78 void cw_enable_adaptive_receive(void)
79 void cw_disable_adaptive_receive(void)
80 bool cw_get_adaptive_receive_state(void)
81 int cw_start_receive_tone(const struct timeval *timestamp)
82 int cw_end_receive_tone(const struct timeval *timestamp)
83 int cw_receive_buffer_dot(const struct timeval *timestamp)
84 int cw_receive_buffer_dash(const struct timeval *timestamp)
85 int cw_receive_representation(const struct timeval *timestamp,
86 /* out */ char *representation,
87 /* out */ bool *is_end_of_word,
88 /* out */ bool *is_error)
89 int cw_receive_character(const struct timeval *timestamp,
90 /* out */ char *c,
91 /* out */ bool *is_end_of_word,
92 /* out */ bool *is_error)
93 void cw_clear_receive_buffer(void)
94 int cw_get_receive_buffer_capacity(void)
95 int cw_get_receive_buffer_length(void)
96 void cw_reset_receive(void)
97 void cw_register_keying_callback(void (*callback_func)(void*, int),
98 void *callback_arg)
99 void cw_enable_iambic_curtis_mode_b(void)
100 void cw_disable_iambic_curtis_mode_b(void)
101 int cw_get_iambic_curtis_mode_b_state(void)
102 int cw_notify_keyer_paddle_event(int dot_paddle_state, int dash_pad‐
103 dle_state)
104 int cw_notify_keyer_dot_paddle_event(int dot_paddle_state)
105 int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
106 void cw_get_keyer_paddles(int *dot_paddle_state, int *dash_pad‐
107 dle_state)
108 void cw_get_keyer_paddle_latches(int *dot_paddle_latch_state, int
109 *dash_paddle_latch_state)
110 bool cw_is_keyer_busy(void)
111 int cw_wait_for_keyer_element(void)
112 int cw_wait_for_keyer(void)
113 void cw_reset_keyer(void)
114 int cw_notify_straight_key_event(int key_state)
115 int cw_get_straight_key_state(void)
116 bool cw_is_straight_key_busy(void)
117 void cw_reset_straight_key(void)
118 bool cw_is_alsa_possible(const char * device_name)
119 bool cw_is_console_possible(const char * device_name)
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 character, char * representation)
124 char * cw_character_to_representation(int character)
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 * char‐
128 acter)
129 int cw_representation_to_character(const char * representation)
130 int cw_get_procedural_character_count(void)
131 void cw_list_procedural_characters(char * list)
132 int cw_get_maximum_procedural_expansion_length(void)
133 int cw_lookup_procedural_character(char character, char *expansion, int
134 * is_usually_expanded)
135 int cw_get_maximum_phonetic_length(void)
136 int cw_lookup_phonetic(char character, char * phonetic)
137 bool cw_character_is_valid(char character)
138 int cw_check_character(char character)
139 bool cw_string_is_valid(const char * string)
140 int cw_check_string(const char * string)
141 void cw_set_debug_flags(uint32_t flags)
142 void cw_debug_set_flags(cw_debug_t * debug_object, uint32_t flags)
143 uint32_t cw_get_debug_flags(void)
144 uint32_t cw_debug_get_flags(const cw_debug_t * debug_object)
145 bool cw_debug_has_flag(const cw_debug_t * debug_object, uint32_t flag)
146 int cw_generator_set_tone_slope(cw_gen_t * gen, int slope_shape, int
147 slope_duration)
148 bool cw_is_null_possible(__attribute__((unused)) const char *
149 device_name)
150 bool cw_is_oss_possible(const char * device_name)
151 bool cw_is_pa_possible(const char * device_name)
152 void cw_block_callback(int block)
153 int cw_register_signal_handler(int signal_number, void (*call‐
154 back_func)(int))
155 int cw_unregister_signal_handler(int signal_number)
156 int cw_version(void)
157 void cw_license(void)
158 const char * cw_get_audio_system_label(int sound_system)
159 void cw_get_speed_limits(int * min_speed, int * max_speed)
160 void cw_get_frequency_limits(int * min_frequency, int * max_frequency)
161 void cw_get_volume_limits(int * min_volume, int * max_volume)
162 void cw_get_gap_limits(int * min_gap, int * max_gap)
163 void cw_get_tolerance_limits(int * min_tolerance, int * max_tolerance)
164 void cw_get_weighting_limits(int * min_weighting, int * max_weighting)
165 void cw_complete_reset(void)
166 DESCRIPTION
169 libcw is a general purpose CW (Morse code) functions library. It con‐
170 tains routines for converting characters into Morse code representa‐
171 tions and back again, for sending Morse code characters, and for
172 receiving characters. It also contains routines to emulate an Iambic
173 Morse keyer, and a straight key.
174 The library can be included in any program that wishes to make use of
176 these features. It forms the heart of three Morse code tutor applica‐
177 tions that accompany the package in which it is distributed.
178 See the cw(7) man page for information on Morse code timings, and the
180 dot and dash representations for the various Morse characters.
181 TONE QUEUE
183 libcw contains an inbuilt tone queue. The queue is emptied by back‐
184 ground processing, using SIGALRM calls and itimers, so a caller program
185 can continue with other tasks while the library sends tones and keys
186 any external device.
187 As well as being used by the library functions that sound Morse code
189 characters and provide a keyer sidetone, the primitive tone queue func‐
190 tions are publicly available to caller programs.
191 CONTROLLING AN EXTERNAL DEVICE
193 libcw may be passed the address of a function that controls external
194 keying. This function is called each time the library changes the key‐
195 ing state, either as a result of sending a Morse character or represen‐
196 tation, or as a result of an iambic keyer or straight key state change.
197 The argument passed is a single integer, TRUE for key-down, and FALSE
198 for key-up.
199 libcw calls the external keying function only when the keying state
201 changes. A call is likely each time a tone is taken off the tone
202 queue.
203 SENDING CW CHARACTERS AND STRINGS
205 libcw offers several functions that send individual characters and
206 character strings as Morse code. It also offers functions that allow
207 specialized 'representations' to be sent. A 'representation' is an
208 ASCII string that consists of only the characters '.' and '-'.
209 Characters and strings are converted into representations, and then the
211 correct tones for the dots and dashes in these representations are
212 queued on the tone queue, for action by the background queue emptying
213 process.
214 RECEIVING CW CHARACTERS AND REPRESENTATIONS
216 libcw contains functions to allow it to receive Morse code. To
217 receive, the library must be told when a tone start is detected, and
218 when a tone end is detected. It then determines whether the tone was a
219 dot or a dash depending on the timing difference between the two.
220 After the required silence gap has passed, the library may be queried
221 to see what the received representation or character was.
222 Errors in receiving may be detected by means of the flags passed back
224 on receive character functions.
225 IAMBIC KEYER
227 libcw offers functions to simulate an Iambic Morse keyer. The caller
228 program needs to tell the library of paddle state changes. Iambic
229 keyer functions are mutually exclusive with character send and straight
230 key functions.
231 STRAIGHT KEY
233 libcw offers simple functions to allow effective pass-through of
234 straight key information. The caller program needs to tell the library
235 of key state changes. Straight key functions are mutually exclusive
236 with character send and iambic keyer functions.
237 RETURN CODES
239 Some of the library's function return a return code of type int. The
240 return code has two values, as defined in libcw.h: CW_SUCCESS or
241 CW_FAILURE. The two symbolic constants are guaranteed to be identical
242 to boolean true and false.
243 FUNCTIONS
245 The following list describes the functions available to a libcw caller:
246 int cw_generator_new(int audio_system, const char *device)
250 Brief: Create new generator
251 Allocate memory for new generator data structure, set up default values
253 of some of the generator's properties. The function does not start the
254 generator (generator does not produce a sound), you have to use cw_gen‐
255 erator_start() for this.
256 Notice that the function doesn't return a generator variable. There is
258 at most one generator variable at any given time. You can't have two
259 generators. In some future version of the library the function will
260 return pointer to newly allocated generator, and then you could have as
261 many of them as you want, but not yet.
262 audio_system can be one of following: NULL, console, OSS, ALSA,
264 PulseAudio, soundcard. See "enum cw_audio_systems" in libcw.h for exact
265 names of symbolic constants.
266 Parameter: audio_system - audio system to be used by the generator
268 Parameter: device - name of audio device to be used; if NULL then
269 library will use default device.
270 void cw_generator_delete(void)
274 Brief: Deallocate generator
275 Deallocate/destroy generator data structure created with call to
277 cw_generator_new(). You can't start nor use the generator after the
278 call to this function.
279 int cw_generator_start(void)
283 Brief: Start a generator
284 Start producing tones using generator created with cw_generator_new().
286 The source of tones is a tone queue associated with the generator. If
287 the tone queue is empty, the generator will wait for new tones to be
288 queued.
289 Returns: CW_FAILURE on errors
291 Returns: CW_SUCCESS on success
292 void cw_generator_stop(void)
296 Brief: Shut down a generator
297 Silence tone generated by generator (level of generated sine wave is
299 set to zero, with falling slope), and shut the generator down.
300 The shutdown does not erase generator's configuration.
302 If you want to have this generator running again, you have to call
304 cw_generator_start().
305 int cw_set_send_speed(int new_value)
309 Brief: Set sending speed of generator
310 See libcw.h/CW_SPEED_{INITIAL|MIN|MAX} for initial/minimal/maximal
312 value of send speed.
313 errno is set to EINVAL if new_value is out of range.
315 Parameter: new_value - new value of send speed to be assigned to gener‐
317 ator
318 Returns: CW_SUCCESS on success
320 Returns: CW_FAILURE on failure
321 int cw_set_frequency(int new_value)
325 Brief: Set frequency of generator
326 Set frequency of sound wave generated by generator. The frequency must
328 be within limits marked by CW_FREQUENCY_MIN and CW_FREQUENCY_MAX.
329 See libcw.h/CW_FREQUENCY_{INITIAL|MIN|MAX} for initial/minimal/maximal
331 value of frequency.
332 errno is set to EINVAL if new_value is out of range.
334 Parameter: new_value - new value of frequency to be assigned to genera‐
336 tor
337 Returns: CW_SUCCESS on success
339 Returns: CW_FAILURE on failure
340 int cw_set_volume(int new_value)
344 Brief: Set volume of generator
345 Set volume of sound wave generated by generator. The volume must be
347 within limits marked by CW_VOLUME_MIN and CW_VOLUME_MAX.
348 Note that volume settings are not fully possible for the console
350 speaker. In this case, volume settings greater than zero indicate con‐
351 sole speaker sound is on, and setting volume to zero will turn off con‐
352 sole speaker sound.
353 See libcw.h/CW_VOLUME_{INITIAL|MIN|MAX} for initial/minimal/maximal
355 value of volume. errno is set to EINVAL if new_value is out of range.
356 Parameter: new_value - new value of volume to be assigned to generator
358 Returns: CW_SUCCESS on success
360 Returns: CW_FAILURE on failure
361 int cw_set_gap(int new_value)
365 Brief: Set sending gap of generator
366 See libcw.h/CW_GAP_{INITIAL|MIN|MAX} for initial/minimal/maximal value
368 of gap. errno is set to EINVAL if new_value is out of range.
369 Notice that this function also sets the same gap value for library's
371 receiver.
372 Parameter: new_value - new value of gap to be assigned to generator
374 Returns: CW_SUCCESS on success
376 Returns: CW_FAILURE on failure
377 int cw_set_weighting(int new_value)
381 Brief: Set sending weighting for generator
382 See libcw.h/CW_WEIGHTING_{INITIAL|MIN|MAX} for initial/minimal/maximal
384 value of weighting. errno is set to EINVAL if new_value is out of
385 range.
386 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
399 int cw_get_frequency(void)
403 Brief: Get frequency from generator
404 Function returns "frequency" parameter of generator, even if the gener‐
406 ator is stopped, or volume of generated sound is zero.
407 Returns: current value of generator's frequency
409 int cw_get_volume(void)
413 Brief: Get sound volume from generator
414 Function returns "volume" parameter of generator, even if the generator
416 is stopped.
417 Returns: current value of generator's sound volume
419 int cw_get_gap(void)
423 Brief: Get sending gap from generator
424 Returns: current value of generator's sending gap
426 int cw_get_weighting(void)
430 Brief: Get sending weighting from generator
431 Returns: current value of generator's sending weighting
433 void cw_get_send_parameters(int *dot_usecs, int *dash_usecs,
437 int *end_of_element_usecs,
438 int *end_of_character_usecs, int
439 *end_of_word_usecs,
440 int *additional_usecs, int *adjustment_usecs)
441 Brief: Get timing parameters for sending
442 Return the low-level timing parameters calculated from the speed, gap,
444 tolerance, and weighting set. Parameter values are returned in
445 microseconds.
446 Use NULL for the pointer argument to any parameter value not required.
448 Parameter: dot_usecs
450 Parameter: dash_usecs
451 Parameter: end_of_element_usecs
452 Parameter: end_of_character_usecs
453 Parameter: end_of_word_usecs
454 Parameter: additional_usecs
455 Parameter: adjustment_usecs
456 int cw_send_dot(void)
460 Brief: Low-level primitive for sending a Dot Mark
461 Low-level primitive function able to play/send single Dot Mark. The
463 function appends to a tone queue a normal inter-mark-space after the
464 Dot Mark.
465 Returns: CW_SUCCESS on success
467 Returns: CW_FAILURE on failure
468 int cw_send_dash(void)
472 Brief: Low-level primitive for sending a Dash Mark
473 Low-level primitive function able to play/send single Dash Mark. The
475 function appends to a tone queue a normal inter-mark-space after the
476 Dash Mark.
477 Returns: CW_SUCCESS on success
479 Returns: CW_FAILURE on failure
480 int cw_send_character_space(void)
484 The function enqueues space of specific length: together with previ‐
485 ously implicitly enqueued inter-mark-space of size 1 Unit, enqueueing
486 this space will form a full inter-character-space of size 3 Units.
487 Returns: CW_SUCCESS on success
489 Returns: CW_FAILURE on failure
490 int cw_send_word_space(void)
494 The function enqueues space of specific length: together with previ‐
495 ously implicitly enqueued inter-mark-space of size 1 Unit and implic‐
496 itly or explicitly enqueued inter-character-space, enqueueing this
497 space will form a full inter-word-space of size 7 Units.
498 Returns: CW_SUCCESS on success
500 Returns: CW_FAILURE on failure
501 int cw_send_representation(const char *representation)
505 Brief: Check, then send the given string as dots and dashes.
506 The representation passed in is assumed to be a complete Morse charac‐
508 ter; that is, all post-character delays will be added when the charac‐
509 ter is sent.
510 On success, the routine returns CW_SUCCESS. On failure, it returns
512 CW_FAILURE, with errno set to EINVAL if any character of the represen‐
513 tation is invalid, EBUSY if the sound card, console speaker, or keying
514 system is busy, or EAGAIN if the tone queue is full, or if there is
515 insufficient space to queue the tones or the representation.
516 Parameter: representation - representation to send
518 Returns: CW_SUCCESS on success
520 Returns: CW_FAILURE on failure
521 int cw_send_representation_partial(const char *representation)
525 Brief: Check, then send the given string as dots and dashes
526 The representation passed in is assumed to be only part of a larger
528 Morse representation; that is, no post-character delays will be added
529 when the character is sent.
530 On success, the routine returns CW_SUCCESS. On failure, it returns
532 CW_FAILURE, with errno set to EINVAL if any character of the represen‐
533 tation is invalid, EBUSY if the sound card, console speaker, or keying
534 system is busy, or EAGAIN if the tone queue is full, or if there is
535 insufficient space to queue the tones for the representation.
536 int cw_send_character(char c)
540 Brief: Look up and send a given ASCII character as Morse
541 The end of character delay is appended to the Morse sent.
543 On success the routine returns CW_SUCCESS. On failure the function
545 returns CW_FAILURE and sets errno.
546 errno is set to ENOENT if the given character c is not a valid Morse
548 character. errno is set to EBUSY if current audio sink or keying sys‐
549 tem is busy. errno is set to EAGAIN if the generator's tone queue is
550 full, or if there is insufficient space to queue the tones for the
551 character.
552 This routine returns as soon as the character has been successfully
554 queued for sending; that is, almost immediately. The actual sending
555 happens in background processing. See cw_wait_for_tone() and
556 cw_wait_for_tone_queue() for ways to check the progress of sending.
557 Parameter: c - character to send
559 Returns: CW_SUCCESS on success
561 Returns: CW_FAILURE on failure
562 int cw_send_character_partial(char c)
566 Brief: Look up and send a given ASCII character as Morse code
567 "partial" means that the "end of character" delay is not appended to
569 the Morse code sent by the function, to support the formation of combi‐
570 nation characters.
571 On success the function returns CW_SUCCESS. On failure the function
573 returns CW_FAILURE and sets errno.
574 errno is set to ENOENT if the given character c is not a valid Morse
576 character. errno is set to EBUSY if the audio sink or keying system is
577 busy. errno is set to EAGAIN if the tone queue is full, or if there is
578 insufficient space to queue the tones for the character.
579 This routine queues its arguments for background processing. See
581 cw_wait_for_tone() and cw_wait_for_tone_queue() for ways to check the
582 progress of sending.
583 Parameter: c - character to send
585 Returns: CW_SUCCESS on success
587 Returns: CW_FAILURE on failure
588 int cw_send_string(const char *string)
592 Brief: Send a given ASCII string in Morse code
593 errno is set to ENOENT if any character in the string is not a valid
595 Morse character.
596 errno is set to EBUSY if audio sink or keying system is busy.
598 errno is set to EAGAIN if the tone queue is full or if the tone queue
600 runs out of space part way through queueing the string. However, an
601 indeterminate number of the characters from the string will have
602 already been queued.
603 For safety, clients can ensure the tone queue is empty before queueing
605 a string, or use cw_send_character() if they need finer control.
606 This routine queues its arguments for background processing, the actual
608 sending happens in background processing. See cw_wait_for_tone() and
609 cw_wait_for_tone_queue() for ways to check the progress of sending.
610 Parameter: string - string to send
612 Returns: CW_SUCCESS on success
614 Returns: CW_FAILURE on failure
615 void cw_reset_send_receive_parameters(void)
619 Brief: Reset send/receive parameters
620 Reset the library speed, frequency, volume, gap, tolerance, weighting,
622 adaptive receive, and noise spike threshold to their initial default
623 values: send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0
624 dots, tolerance 50 %, and weighting 50 %.
625 const char *cw_get_console_device(void)
629 Brief: Return char string with console device path
630 Returned pointer is owned by library.
632 Returns: char string with current console device path
634 const char *cw_get_soundcard_device(void)
638 Brief: Return char string with soundcard device name/path
639 Returned pointer is owned by library.
641 Returns: char string with current soundcard device name or device path
643 const char *cw_generator_get_audio_system_label(void)
647 Brief: Get a readable label of current audio system
648 The function returns one of following strings: None, Null, Console,
650 OSS, ALSA, PulseAudio, Soundcard
651 Returns: audio system's label
653 int cw_generator_remove_last_character(void)
657 Brief: Remove last character from queue of already enqueued characters
658 If the character is not actually played by sound sink yet, library may
660 be able to remove the character. The character's Dots and Dashes won't
661 be played.
662 This function may be useful if user presses backspace in UI to
664 remove/undo a character.
665 If your application doesn't enqueue whole characters or strings of
667 characters but is using low-level cw_send_dot()/cw_send_dash() func‐
668 tions to enqueue individual Marks, don't use this function. This func‐
669 tion won't be able to recognize whole characters and is likely to
670 remove more tones than expected.
671 Returns: CW_SUCCESS if function managed to remove a last character
673 before it has been played
674 Returns: CW_FAILURE otherwise
675 int cw_register_tone_queue_low_callback(void (*callback_func)(void*),
679 void *callback_arg, int level)
680 Brief: Register callback for low queue state
681 Register a function to be called automatically by the dequeue routine
683 whenever the count of tones in tone queue falls to a given level. To be
684 more precise: the callback is called by queue's dequeue function if,
685 after dequeueing a tone, the function notices that tone queue length
686 has become equal or less than level.
687 level can't be negative.
689 level can't be equal to or larger than tone queue capacity.
691 If level is zero, the behaviour of the mechanism is not guaranteed to
693 work correctly.
694 If callback_func is NULL then the mechanism becomes disabled.
696 callback_arg will be passed to callback_arg.
698 errno is set to EINVAL when level is invalid.
700 Parameter: callback_func - callback function to be registered
702 Parameter: callback_arg - argument for callback_func to pass return
703 value
704 Parameter: level - low level of queue triggering callback call
705 Returns: CW_SUCCESS on successful registration
707 Returns: CW_FAILURE on failure
708 bool cw_is_tone_busy(void)
712 Brief: Check if tone sender is busy
713 Indicate if the tone sender is busy.
715 Returns: true if there are still entries in the tone queue
717 Returns: false if the queue is empty
718 int cw_wait_for_tone(void)
722 Brief: Wait for the current tone to complete
723 Returns: CW_SUCCESS on success
725 Returns: CW_FAILURE on failure
726 int cw_wait_for_tone_queue(void)
730 Brief: Wait for the tone queue to drain
731 Notice that generator must be running (started with cw_genera‐
733 tor_start()) when this function is called, otherwise it will be waiting
734 forever for a change of tone queue's level that will never happen.
735 Returns: CW_SUCCESS on success
737 Returns: CW_FAILURE on failure
738 int cw_wait_for_tone_queue_critical(int level)
742 Brief: Wait for the tone queue to drain until only as many tones as
743 given in level remain queued
744 This routine is for use by programs that want to optimize themselves to
746 avoid the cleanup that happens when the tone queue drains completely;
747 such programs have a short time in which to add more tones to the
748 queue.
749 Notice that generator must be running (started with cw_genera‐
751 tor_start()) when this function is called, otherwise it will be waiting
752 forever for a change of tone queue's level that will never happen.
753 If level is negative, function sets errno to EINVAL and returns
755 CW_FAILURE.
756 Parameter: level - low level in queue, at which to return
758 Returns: CW_SUCCESS on success
760 Returns: CW_FAILURE on failure
761 bool cw_is_tone_queue_full(void)
765 Brief: Indicate if the tone queue is full
766 Returns: true if tone queue is full
768 Returns: false if tone queue is not full
769 int cw_get_tone_queue_capacity(void)
773 Brief: Return the number of entries the tone queue can accommodate
774 int cw_get_tone_queue_length(void)
778 Brief: Return the number of entries currently pending in the tone queue
779 void cw_flush_tone_queue(void)
783 Brief: Cancel all pending queued tones, and return to silence.
784 If there is a tone in progress, the function will wait until this last
786 one has completed, then silence the tones.
787 void cw_reset_tone_queue(void)
791 Cancel all pending queued tones, reset any queue low callback regis‐
792 tered, and return to silence. This function is suitable for calling
793 from an application exit handler.
794 int cw_queue_tone(int usecs, int frequency)
798 Brief: Primitive access to simple tone generation
799 This routine queues a tone of given duration and frequency. The rou‐
801 tine returns CW_SUCCESS on success. If usec or frequency are invalid,
802 it returns CW_FAILURE with errno set to EINVAL. If the sound card,
803 console speaker, or keying function are busy, it returns CW_FAILURE
804 with errno set to EBUSY. If the tone queue is full, it returns false
805 with errno set to EAGAIN.
806 Parameter: usecs - duration of queued tone, in microseconds
808 Parameter: frequency - frequency of queued tone
809 Returns: CW_SUCCESS on success
811 Returns: CW_FAILURE on failure
812 int cw_set_receive_speed(int new_value)
816 Brief: Set receiving speed of receiver
817 See documentation of cw_set_send_speed() for more information.
819 See libcw.h/CW_SPEED_{INITIAL|MIN|MAX} for initial/minimal/maximal
821 value of receive speed. errno is set to EINVAL if new_value is out of
822 range. errno is set to EPERM if adaptive receive speed tracking is
823 enabled.
824 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
837 int cw_set_tolerance(int new_value)
841 Brief: Set tolerance for receiver
842 See libcw.h/CW_TOLERANCE_{INITIAL|MIN|MAX} for initial/minimal/maximal
844 value of tolerance. errno is set to EINVAL if new_value is out of
845 range.
846 Parameter: new_value - new value of tolerance to be assigned to
848 receiver
849 Returns: CW_SUCCESS on success
851 Returns: CW_FAILURE on failure
852 int cw_get_tolerance(void)
856 Brief: Get tolerance from receiver
857 Returns: current value of receiver's tolerance
859 void cw_get_receive_parameters(int *dot_usecs, int *dash_usecs,
863 int *dot_min_usecs, int *dot_max_usecs,
864 int *dash_min_usecs, int *dash_max_usecs,
865 int *end_of_element_min_usecs,
866 int *end_of_element_max_usecs,
867 int *end_of_element_ideal_usecs,
868 int *end_of_character_min_usecs,
869 int *end_of_character_max_usecs,
870 int *end_of_character_ideal_usecs,
871 int *adaptive_threshold)
872 Brief: Get timing parameters for receiving, and adaptive threshold
873 Return the low-level timing parameters calculated from the speed, gap,
875 tolerance, and weighting set. Parameter values are returned in
876 microseconds.
877 Use NULL for the pointer argument to any parameter value not required.
879 Parameter: dot_usecs
881 Parameter: dash_usecs
882 Parameter: dot_min_usecs
883 Parameter: dot_max_usecs
884 Parameter: dash_min_usecs
885 Parameter: dash_max_usecs
886 Parameter: end_of_element_min_usecs
887 Parameter: end_of_element_max_usecs
888 Parameter: end_of_element_ideal_usecs
889 Parameter: end_of_character_min_usecs
890 Parameter: end_of_character_max_usecs
891 Parameter: end_of_character_ideal_usecs
892 Parameter: adaptive_threshold
893 int cw_set_noise_spike_threshold(int new_value)
897 Brief: Set noise spike threshold for receiver
898 Set the period shorter than which, on receive, received marks are
900 ignored. This allows the "receive mark" functions to apply noise can‐
901 celing for very short apparent marks. For useful results the value
902 should never exceed the dot length of a dot at maximum speed: 20000
903 microseconds (the dot length at 60WPM). Setting a noise threshold of
904 zero turns off receive mark noise canceling.
905 The default noise spike threshold is 10000 microseconds.
907 errno is set to EINVAL if new_value is out of range.
909 Parameter: new_value - new value of noise spike threshold to be
911 assigned to receiver
912 Returns: CW_SUCCESS on success
914 Returns: CW_FAILURE on failure
915 int cw_get_noise_spike_threshold(void)
919 Brief: Get noise spike threshold from receiver
920 See documentation of cw_set_noise_spike_threshold() for more informa‐
922 tion
923 Returns: current value of receiver's threshold
925 void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
929 double *element_end_sd, double *charac‐
930 ter_end_sd)
931 Brief: Calculate and return receiver's timing statistics
932 These statistics may be used to obtain a measure of the accuracy of
934 received CW. The values dot_sd and dot_sd contain the standard devia‐
935 tion of dot and dash lengths from the ideal values, and element_end_sd
936 and element_end_sd the deviations for inter element and inter character
937 spacing. Statistics are held for all timings in a 256 element circular
938 buffer. If any statistic cannot be calculated, because no records for
939 it exist, the returned value is 0.0. Use NULL for the pointer argument
940 to any statistic not required.
941 Parameter: dot_sd
943 Parameter: dash_sd
944 Parameter: element_end_sd
945 Parameter: character_end_sd
946 void cw_reset_receive_statistics(void)
950 Brief: Clear the receive statistics buffer
951 Clear the receive statistics buffer by removing all records from it and
953 returning it to its initial default state.
954 void cw_enable_adaptive_receive(void)
958 Brief: Enable adaptive receive speed tracking
959 If adaptive speed tracking is enabled, the receive functions will
961 attempt to automatically adjust the receive speed setting to match the
962 speed of the incoming Morse code. If it is disabled, the receive func‐
963 tions will use fixed speed settings, and reject incoming Morse which is
964 not at the expected speed.
965 Adaptive speed tracking uses a moving average length of the past N
967 marks as its baseline for tracking speeds. The default state is adap‐
968 tive speed tracking disabled.
969 void cw_disable_adaptive_receive(void)
973 Brief: Disable adaptive receive speed tracking
974 See documentation of cw_enable_adaptive_receive() for more information
976 bool cw_get_adaptive_receive_state(void)
980 Brief: Get adaptive receive speed tracking flag
981 The function returns state of "adaptive receive enabled" flag. See
983 documentation of cw_enable_adaptive_receive() for more information
984 Returns: true if adaptive speed tracking is enabled
986 Returns: false otherwise
987 int cw_start_receive_tone(const struct timeval *timestamp)
991 Brief: Signal beginning of receive mark
992 Called on the start of a receive mark. If the timestamp is NULL, the
994 current timestamp is used as beginning of mark.
995 The function should be called by client application when pressing a key
997 down (closing a circuit) has been detected by client application.
998 On error the function returns CW_FAILURE, with errno set to ERANGE if
1000 the call is directly after another cw_start_receive_tone() call or if
1001 an existing received character has not been cleared from the buffer, or
1002 EINVAL if the timestamp passed in is invalid.
1003 Parameter: timestamp - time stamp of "key down" event
1005 Returns: CW_SUCCESS on success
1007 Returns: CW_FAILURE otherwise (with errno set)
1008 int cw_end_receive_tone(const struct timeval *timestamp)
1012 Brief: Signal end of mark
1013 The function should be called by client application when releasing a
1015 key (opening a circuit) has been detected by client application.
1016 If the timestamp is NULL, the current time is used as timestamp of end
1018 of mark.
1019 On success, the routine adds a dot or dash to the receiver's represen‐
1021 tation buffer, and returns CW_SUCCESS.
1022 On failure, it returns CW_FAIURE, with errno set to: ERANGE if the call
1024 was not preceded by a cw_start_receive_tone() call, EINVAL if the time‐
1025 stamp passed in is not valid, ENOENT if function can't tell from dura‐
1026 tion of the Mark if it's Dot or Dash, ENOMEM if the receiver's repre‐
1027 sentation buffer is full, EAGAIN if the mark was shorter than the
1028 threshold for noise and was therefore ignored.
1029 Parameter: timestamp - time stamp of "key up" event
1031 Returns: CW_SUCCESS on success
1033 Returns: CW_FAILURE on failure
1034 int cw_receive_buffer_dot(const struct timeval *timestamp)
1038 Brief: Add a dot to the receiver's representation buffer
1039 Documentation for both cw_receive_buffer_dot() and cw_receive_buf‐
1041 fer_dash():
1042 Since we can't add a mark to the buffer without any accompanying timing
1044 information, the functions accepts timestamp of the "end of mark"
1045 event. If the timestamp is NULL, the current timestamp is used.
1046 These routines are for client code that has already determined whether
1048 a dot or dash was received by a method other than calling the routines
1049 cw_start_receive_tone() and cw_end_receive_tone().
1050 On success, the relevant mark is added to the receiver's representation
1052 buffer.
1053 On failure, the routines return CW_FAILURE and set errno: ERANGE if
1055 preceded by a cw_start_receive_tone() call with no matching
1056 cw_end_receive_tone() or if an error condition currently exists within
1057 the receiver's buffer, EINVAL if the timestamp passed in is not valid,
1058 ENOMEM if the receiver's representation buffer is full.
1059 Parameter: timestamp - timestamp of "end of dot" event
1061 Returns: CW_SUCCESS on success
1063 Returns: CW_FAILURE on failure
1064 int cw_receive_buffer_dash(const struct timeval *timestamp)
1068 Brief: Add a dash to the receiver's representation buffer
1069 See documentation of cw_receive_buffer_dot() for more information.
1071 Parameter: timestamp - timestamp of "end of dash" event
1073 Returns: CW_SUCCESS on success
1075 Returns: CW_FAILURE on failure
1076 int cw_receive_representation(const struct timeval *timestamp,
1080 /* out */ char *representation,
1081 /* out */ bool *is_end_of_word,
1082 /* out */ bool *is_error)
1083 Brief: Get the current buffered representation from the receiver's rep‐
1084 resentation buffer
1085 On success the function fills in representation with the contents of
1087 the current representation buffer and returns CW_SUCCESS.
1088 On failure, it returns CW_FAILURE and sets errno to: ERANGE if not pre‐
1090 ceded by a cw_end_receive_tone() call, a prior successful
1091 cw_receive_representation call, or a prior cw_receive_buffer_dot or
1092 cw_receive_buffer_dash, EINVAL if the timestamp passed in is invalid,
1093 EAGAIN if the call is made too early to determine whether a complete
1094 representation has yet been placed in the buffer (that is, less than
1095 the inter-character-space duration elapsed since the last
1096 cw_end_receive_tone() or cw_receive_buffer_dot/dash call). This is not
1097 a *hard* error, just an information that the caller should try to get
1098 the representation later.
1099 is_end_of_word indicates that the space after the last mark received is
1101 longer that the inter-character-space, so it must be qualified as
1102 inter-word-space.
1103 is_error indicates that the representation was terminated by an error
1105 condition.
1106 The function is called periodically (poll()-like function) by client
1108 code in hope that at some attempt receiver will be ready to pass repre‐
1109 sentation. The attempt succeeds only if data stream is in "space"
1110 state. To mark end of the space, client code has to provide a timestamp
1111 (or pass NULL timestamp, the function will get time stamp at function
1112 call). The receiver needs to know the "end of space" event - thus the
1113 timestamp parameter.
1114 Parameter: timestamp - timestamp of event that ends inter-character-
1116 space or inter-word-space
1117 Parameter: representation - buffer for representation (output parame‐
1118 ter)
1119 Parameter: is_end_of_word - buffer for "is end of word" state (output
1120 parameter)
1121 Parameter: is_error - buffer for "error" state (output parameter)
1122 Returns: CW_SUCCESS on success
1124 Returns: CW_FAILURE on failure
1125 int cw_receive_character(const struct timeval *timestamp,
1129 /* out */ char *c,
1130 /* out */ bool *is_end_of_word,
1131 /* out */ bool *is_error)
1132 Brief: Get a current character
1133 Function returns the character currently stored in receiver's represen‐
1135 tation buffer.
1136 On success the function returns CW_SUCCESS, and fills c with the con‐
1138 tents of the current representation buffer, translated into a charac‐
1139 ter.
1140 On failure the function returns CW_FAILURE, with errno set to:
1142 ERANGE if not preceded by a cw_end_receive_tone() call, a prior suc‐
1144 cessful cw_receive_character() call, or a cw_receive_buffer_dot() or
1145 cw_receive_buffer_dash() call, EINVAL if the timestamp passed in is
1146 invalid, or EAGAIN if the call is made too early to determine whether a
1147 complete character has yet been placed in the buffer (that is, less
1148 than the inter-character-space duration elapsed since the last
1149 cw_end_receive_tone() or cw_receive_buffer_dot/dash call). ENOENT if
1150 character stored in receiver cannot be recognized as valid
1151 is_end_of_word indicates that the space after the last mark received is
1153 longer that the inter-character-space, so it must be qualified as
1154 inter-word-space.
1155 is_error indicates that the character was terminated by an error condi‐
1157 tion.
1158 Parameter: timestamp - timestamp of event that ends inter-character-
1160 space or inter-word-space
1161 Parameter: c - buffer for character (output parameter)
1162 Parameter: is_end_of_word - buffer for "is end of word" state (output
1163 parameter)
1164 Parameter: is_error - buffer for "error" state (output parameter)
1165 Returns: CW_SUCCESS on success
1167 Returns: CW_FAILURE on failure
1168 void cw_clear_receive_buffer(void)
1172 Brief: Clear receiver's representation buffer
1173 Clears the receiver's representation buffer, resets receiver's internal
1175 state. This prepares the receiver to receive marks and spaces again.
1176 This routine must be called after successful, or terminating,
1178 cw_receive_representation() or cw_receive_character() calls, to clear
1179 the states and prepare the buffer to receive more marks and spaces.
1180 When migrating to libcw2.h, use cw_rec_reset_state() instead of this
1182 function.
1183 int cw_get_receive_buffer_capacity(void)
1187 Brief: Get the number of elements (dots/dashes) the receiver's buffer
1188 can accommodate
1189 The maximum number of elements written out by cw_receive_representa‐
1191 tion() is the capacity + 1, the extra character being used for the ter‐
1192 minating NUL.
1193 Returns: number of elements that can be stored in receiver's represen‐
1195 tation buffer
1196 int cw_get_receive_buffer_length(void)
1200 Brief: Get the number of elements (dots/dashes) currently pending in
1201 the cw_receiver's representation buffer
1202 Returns: number of elements in receiver's representation buffer
1204 void cw_reset_receive(void)
1208 Brief: Clear receive data
1209 Clear the receiver's representation buffer, statistics, and any
1211 retained receiver's state. This function is suitable for calling from
1212 an application exit handler.
1213 When migrating to libcw2.h, use cw_rec_reset_state() and
1215 cw_rec_reset_statistics() instead of this function.
1216 void cw_register_keying_callback(void (*callback_func)(void*, int),
1220 void *callback_arg)
1221 Brief: Register external callback function for keying
1222 Register a callback_func function that should be called when a state of
1224 a key changes from "key open" to "key closed", or vice-versa.
1225 The first argument passed to the registered callback function is the
1227 supplied callback_arg, if any. The second argument passed to regis‐
1228 tered callback function is the key state: CW_KEY_STATE_CLOSED
1229 (one/true) for "key closed", and CW_KEY_STATE_OPEN (zero/false) for
1230 "key open".
1231 Calling this routine with a NULL function address disables keying call‐
1233 backs. Any callback supplied will be called in signal handler context
1234 (??).
1235 Parameter: callback_func - callback function to be called on key state
1237 changes
1238 Parameter: callback_arg - first argument to callback_func
1239 void cw_enable_iambic_curtis_mode_b(void)
1243 Brief: Enable iambic Curtis mode B
1244 Normally, the iambic keying functions will emulate Curtis 8044 Keyer
1246 mode A. In this mode, when both paddles are pressed together, the last
1247 dot or dash being sent on release is completed, and nothing else is
1248 sent. In mode B, when both paddles are pressed together, the last dot
1249 or dash being sent on release is completed, then an opposite element is
1250 also sent. Some operators prefer mode B, but timing is more critical in
1251 this mode. The default mode is Curtis mode A.
1252 void cw_disable_iambic_curtis_mode_b(void)
1256 See documentation of cw_enable_iambic_curtis_mode_b() for more informa‐
1257 tion
1258 int cw_get_iambic_curtis_mode_b_state(void)
1262 See documentation of cw_enable_iambic_curtis_mode_b() for more informa‐
1263 tion
1264 int cw_notify_keyer_paddle_event(int dot_paddle_state, int dash_pad‐
1268 dle_state)
1269 Brief: Inform about changed state of iambic keyer's paddles
1270 Function informs the library that the iambic keyer paddles have changed
1272 state. The new paddle states are recorded, and if either transition
1273 from false to true, paddle latches, for iambic functions, are also set.
1274 On success, the routine returns CW_SUCCESS. On failure, it returns
1276 CW_FAILURE, with errno set to EBUSY if the tone queue or straight key
1277 are using the sound card, console speaker, or keying system.
1278 If appropriate, this routine starts the keyer functions sending the
1280 relevant element. Element send and timing occurs in the background, so
1281 this routine returns almost immediately.
1282 Parameter: dot_paddle_state
1284 Parameter: dash_paddle_state
1285 Returns: CW_SUCCESS on success
1287 Returns: CW_FAILURE on failure
1288 int cw_notify_keyer_dot_paddle_event(int dot_paddle_state)
1292 Brief: Change state of dot paddle
1293 Alter the state of just one of the two iambic keyer paddles. The other
1295 paddle state of the paddle pair remains unchanged.
1296 See cw_notify_keyer_paddle_event() for details of iambic keyer back‐
1298 ground processing, and how to check its status.
1299 Parameter: dot_paddle_state
1301 int cw_notify_keyer_dash_paddle_event(int dash_paddle_state)
1305 See documentation of cw_notify_keyer_dot_paddle_event() for more infor‐
1306 mation
1307 void cw_get_keyer_paddles(int *dot_paddle_state, int *dash_pad‐
1311 dle_state)
1312 Brief: Get the current saved states of the two paddles
1313 Parameter: dot_paddle_state
1315 Parameter: dash_paddle_state
1316 void cw_get_keyer_paddle_latches(int *dot_paddle_latch_state, int
1320 *dash_paddle_latch_state)
1321 Brief: Get the current states of paddle latches
1322 Function returns the current saved states of the two paddle latches. A
1324 paddle latches is set to true when the paddle state becomes true, and
1325 is cleared if the paddle state is false when the element finishes send‐
1326 ing.
1327 Parameter: dot_paddle_latch_state
1329 Parameter: dash_paddle_latch_state
1330 bool cw_is_keyer_busy(void)
1334 Brief: Check if a keyer is busy
1335 Returns: true if keyer is busy
1337 Returns: false if keyer is not busy
1338 int cw_wait_for_keyer_element(void)
1342 Brief: Wait for end of element from the keyer
1343 Waits until the end of the current element, dot or dash, from the
1345 keyer.
1346 Returns: CW_SUCCESS on success
1348 Returns: CW_FAILURE on failure
1349 int cw_wait_for_keyer(void)
1353 Brief: Wait for the current keyer cycle to complete
1354 Returns: CW_SUCCESS on success
1356 Returns: CW_FAILURE on failure
1357 void cw_reset_keyer(void)
1361 Brief: Reset iambic keyer data
1362 Clear all latches and paddle states of iambic keyer, return to Curtis
1364 8044 Keyer mode A, and return to silence. This function is suitable
1365 for calling from an application exit handler.
1366 int cw_notify_straight_key_event(int key_state)
1370 Brief: Inform the library that the straight key has changed state
1371 This routine returns CW_SUCCESS on success. On error, it returns
1373 CW_FAILURE, with errno set to EBUSY if the tone queue or iambic keyer
1374 are using the sound card, console speaker, or keying control system.
1375 If key_state indicates no change of state, the call is ignored.
1376 key_state may be either CW_KEY_STATE_OPEN (false) or
1378 CW_KEY_STATE_CLOSED (true).
1379 Parameter: key_state - state of straight key
1381 int cw_get_straight_key_state(void)
1385 Brief: Get saved state of straight key
1386 Returns the current saved state of the straight key.
1388 Returns: CW_KEY_STATE_CLOSED (true) if the key is down
1390 Returns: CW_KEY_STATE_OPEN (false) if the key up
1391 bool cw_is_straight_key_busy(void)
1395 Brief: Check if the straight key is busy
1396 This routine is just a pseudonym for cw_get_straight_key_state(), and
1398 exists to fill a hole in the API naming conventions.
1399 Returns: true if the straight key is busy
1401 Returns: false if the straight key is not busy
1402 void cw_reset_straight_key(void)
1406 Brief: Clear the straight key state, and return to silence
1407 This function is suitable for calling from an application exit handler.
1409 bool cw_is_alsa_possible(const char * device_name)
1413 Brief: Check if it is possible to open ALSA output with given device
1414 name
1415 The check consists of two parts: -# whether it's possible to load ALSA
1417 shared library, -# whether it's possible to open ALSA device specified
1418 by device_name
1419 If it's possible to use ALSA with given device name, the function
1421 leaves library handle (returned by dlopen()) open and some library
1422 function symbols loaded, but does not leave any ALSA PCM handle open.
1423 Parameter(in): device_name name of ALSA device to be used; if NULL or
1429 empty then the function will use library-default device name.
1430 Returns: true if opening ALSA output succeeded
1432 Returns: false if opening ALSA output failed
1433 bool cw_is_console_possible(const char * device_name)
1437 Brief: Check if it is possible to open console buzzer output
1438 Function does a test opening and test writing to console buzzer device
1440 device_name, but it closes it before returning.
1441 The function tests that the given console buzzer device exists, and
1443 that it will accept the KIOCSOUND ioctl. It unconditionally returns
1444 false on platforms that do no support the KIOCSOUND ioctl.
1445 Call to ioctl will fail if calling code doesn't have root privileges.
1447 This is the only place where we ask if KIOCSOUND is defined, so client
1449 code must call this function whenever it wants to use console output,
1450 as every other function called to perform console operations will hap‐
1451 pily assume that it is allowed to perform such operations.
1452 Parameter(in): device_name name of console buzzer device to be used; if
1456 NULL or empty then the function will use library-default device name.
1457 Returns: true if opening console output succeeded
1459 Returns: false if opening console output failed
1460 int cw_get_character_count(void)
1464 Brief: Return the number of characters present in main character lookup
1465 table
1466 Return the number of characters that are known to libcw. The number
1468 includes: @li ASCII 7bit letters, @li numerals, @li punctuation, @li
1469 ISO 8859-1 accented characters, @li ISO 8859-2 accented characters, @li
1470 non-standard procedural signal extensions to standard CW characters.
1471 Returns: number of characters known to libcw
1477 void cw_list_characters(char * list)
1481 Brief: Get list of characters present in character lookup table
1482 Function provides a string containing all of the characters represented
1484 in library's lookup table.
1485 The list includes: @li ASCII 7bit letters, @li numerals, @li punctua‐
1487 tion, @li ISO 8859-1 accented characters, @li ISO 8859-2 accented char‐
1488 acters, @li non-standard procedural signal extensions to standard CW
1489 characters.
1490 list should be allocated and managed by caller. The length of list
1492 must be at least one greater than the number of characters represented
1493 in the character lookup table, returned by cw_get_character_count().
1494 The string placed in list will be NUL-terminated.
1495 Parameter(out): list buffer for string with all characters
1501 int cw_get_maximum_representation_length(void)
1505 Brief: Get length of the longest representation of characters
1506 Function returns the string length of the longest representation in the
1508 main character lookup table. It is the count of dots and dashes in the
1509 longest representation of characters known to libcw (not including ter‐
1510 minating NUL).
1511 Returns: length of the longest representation
1517 int cw_lookup_character(char character, char * representation)
1521 Brief: Get representation of a given character
1522 The function is depreciated, use cw_character_to_representation()
1524 instead.
1525 Return the string representation of a given character character.
1527 The routine returns CW_SUCCESS on success, and fills in the string
1529 pointer (representation) passed in. On failure, it returns CW_FAILURE
1530 and sets errno to ENOENT, indicating that the character character could
1531 not be found.
1532 The length of representation buffer must be at least one greater than
1534 the length of longest representation held in the character lookup ta‐
1535 ble. The largest value of length is returned by cw_get_maximum_repre‐
1536 sentation_length().
1537 Parameter(in): character character to look up Parameter(out): represen‐
1543 tation pointer to space for representation of character
1544 Returns: CW_SUCCESS on success
1546 Returns: CW_FAILURE on failure
1547 char * cw_character_to_representation(int character)
1551 Brief: Get representation of a given character
1552 On success return representation of a given character. Returned
1554 pointer is owned by caller of the function.
1555 On failure function returns NULL and sets errno.
1557 ERRNO ENOENT the character could not be found. ERRNO ENOMEM character
1559 has been found, but function failed to strdup() representation.
1560 Parameter(in): character character to look up
1566 Returns: pointer to freshly allocated representation on success
1568 Returns: NULL on failure
1569 int cw_check_representation(const char * representation)
1573 Brief: Check if representation of a character is valid
1574 This function is depreciated, use cw_representation_is_valid() instead.
1576 Check that the given string is a valid Morse representation. A valid
1578 string is one composed of only "." and "-" characters. This means that
1579 the function checks only if representation is error-free, and not
1580 whether the representation represents existing/defined character.
1581 If representation is invalid, function returns CW_FAILURE and sets
1583 errno to EINVAL.
1584 Parameter(in): representation representation of a character to check
1590 Returns: CW_SUCCESS on success
1592 Returns: CW_FAILURE on failure
1593 bool cw_representation_is_valid(const char * representation)
1597 Brief: Check if representation of a character is valid
1598 Check that the given string is a valid Morse representation. A valid
1600 string is one composed of only "." and "-" characters. This means that
1601 the function checks only if representation is error-free, and not
1602 whether the representation represents existing/defined character.
1603 ERRNO EINVAL representation is invalid
1609 Parameter(in): representation representation of a character to check
1611 Returns: true if representation is valid
1613 Returns: false if representation is invalid
1614 int cw_lookup_representation(const char * representation, char * char‐
1618 acter)
1619 Brief: Get the character represented by a given Morse representation
1620 This function is depreciated, use cw_representation_to_character()
1622 instead.
1623 Function checks representation, and if it is valid and represents a
1625 known character, function returns CW_SUCCESS. Additionally, if charac‐
1626 ter is non-NULL, function puts the looked up character in character.
1627 character should be allocated by caller. Function assumes that charac‐
1629 ter being NULL pointer is a valid situation, and can return CW_SUCCESS
1630 in such situation.
1631 On error, function returns CW_FAILURE. errno is set to EINVAL if any
1633 character of the representation is invalid, or ENOENT to indicate that
1634 the character represented by representation could not be found.
1635 Parameter(in): representation representation of a character to look up
1641 Parameter(out): character location where to put looked up character
1642 Returns: CW_SUCCESS on success
1644 Returns: CW_FAILURE on failure
1645 int cw_representation_to_character(const char * representation)
1649 Brief: Return the character represented by a given Morse representation
1650 Function checks representation, and if it is valid and represents a
1652 known character, function returns the character (a non-zero value).
1653 On error, function returns zero (character represented by representa‐
1655 tion was not found).
1656 ERRNO EINVAL representation contains invalid symbol (other than Dots
1662 and Dashes) ERRNO ENOENT a character represented by representation
1663 could not be found
1664 Parameter(in): representation representation of a character to look up
1666 Returns: non-zero character on success
1668 Returns: zero on failure
1669 int cw_get_procedural_character_count(void)
1673 Brief: Get number of procedural signals
1674 Returns: the number of characters stored in the procedural signal
1680 expansion lookup table
1681 void cw_list_procedural_characters(char * list)
1685 Brief: Get list of characters for which procedural expansion is avail‐
1686 able
1687 Function copies into preallocated buffer list a string containing all
1689 of the Morse characters for which procedural expansion is available.
1690 The length of list must be at least by one greater than the number of
1691 characters represented in the procedural signal expansion lookup table,
1692 returned by cw_get_procedural_character_count().
1693 list buffer is allocated and managed by caller.
1695 Parameter(out): list buffer for returned string
1701 int cw_get_maximum_procedural_expansion_length(void)
1705 Brief: Get length of the longest procedural expansion
1706 Function returns the string length of the longest expansion in the pro‐
1708 cedural signal expansion table.
1709 Returns: the string length of the longest expansion of procedural sig‐
1715 nals
1716 int cw_lookup_procedural_character(char character, char *expansion, int
1720 * is_usually_expanded)
1721 Brief: Get the string expansion of a given Morse code procedural signal
1722 character
1723 On success the function @li fills expansion with the string expansion
1725 of a given Morse code procedural signal character character; @li sets
1726 is_usually_expanded to appropriate value as a display hint for the
1727 caller; @li returns CW_SUCCESS.
1728 Both expansion and expansion must be allocated and managed by caller.
1730 They can be NULL, then the function won't attempt to use them.
1731 The length of expansion must be at least by one greater than the long‐
1733 est expansion held in the procedural signal character lookup table, as
1734 returned by cw_get_maximum_procedural_expansion_length().
1735 ERRNO ENOENT procedural signal character character cannot be found
1741 Parameter(in): character character to look up Parameter(out): expansion
1743 buffer to fill with expansion of the character Parameter(out): is_usu‐
1744 ally_expanded visual hint
1745 Returns: CW_FAILURE on failure (character cannot be found)
1747 Returns: CW_SUCCESS on success
1748 int cw_get_maximum_phonetic_length(void)
1752 Brief: Get length of a longest phonetic
1753 Returns: the string length of the longest phonetic in the phonetics
1759 lookup table
1760 int cw_lookup_phonetic(char character, char * phonetic)
1764 Brief: Look up the phonetic of a given character
1765 On success the routine copies a phonetic corresponding to character
1767 into phonetic. phonetic is managed and owned by caller.
1768 It is NOT considered an error if phonetic is NULL. In such case the
1770 function will just verify if character can be represented by a pho‐
1771 netic, i.e. if character is a letter.
1772 If non-NULL, the size of phonetic must be greater by at least 1 than
1774 the longest phonetic held in the phonetic lookup table, as returned by
1775 cw_get_maximum_phonetic_length().
1776 ERRNO ENOENT phonetic for given character cannot be found
1782 Parameter(in): character character to look up Parameter(out): phonetic
1784 buffer for phonetic of a character (may be NULL)
1785 Returns: CW_SUCCESS on success (phonetic has been found and - if pho‐
1787 netic is non-NULL) has been copied to the buffer
1788 Returns: CW_FAILURE on failure (phonetic for given character cannot be
1789 found)
1790 bool cw_character_is_valid(char character)
1794 Brief: Check if given character is valid
1795 Check that a given character is valid, i.e. it is present in library's
1797 character-to-representation lookup table and can be represented with
1798 Dots and Dashes.
1799 Space character (' ') is also considered to be a valid character.
1801 ERRNO ENOENT on failure (character is invalid).
1803 Notice the difference in errno set by cw_character_is_valid() (ENOENT)
1805 and cw_string_is_valid() (EINVAL). This different behaviour goes way
1806 back to unixcw-2.3 and is preserved in new versions for backwards com‐
1807 patibility reasons.
1808 Parameter(in): character character to check
1814 Returns: true if character is valid
1816 Returns: false otherwise
1817 int cw_check_character(char character)
1821 bool cw_string_is_valid(const char * string)
1828 Brief: Check if all characters in given string are valid
1829 Check that each character in the given string is valid and can be con‐
1831 verted by libcw to Morse code symbols sent as a Morse character.
1832 Space character (' ') is also considered to be a valid character.
1834 ERRNO EINVAL on failure (when an invalid character has been found in
1836 string).
1837 Notice the difference in errno set by cw_character_is_valid() (ENOENT)
1839 and cw_string_is_valid() (EINVAL). This different behaviour goes way
1840 back to unixcw-2.3 and is preserved in new versions for backwards com‐
1841 patibility reasons.
1842 Parameter(in): string string to check
1848 Returns: true if all characters in string are valid
1850 Returns: false otherwise
1851 int cw_check_string(const char * string)
1855 void cw_set_debug_flags(uint32_t flags)
1862 Brief: Set a value of internal debug flags variable
1863 Assign specified value to library's internal debug flags variable.
1865 Note that this function doesn't *append* given flag to the variable, it
1866 erases existing value and assigns new one. Use cw_get_debug_flags() if
1867 you want to OR new flag with existing ones.
1868 Parameter: flags new value of flags to be assigned to the debug object
1874 void cw_debug_set_flags(cw_debug_t * debug_object, uint32_t flags)
1878 Brief: Set a value of debug flags in given debug variable
1879 Assign specified value to given debug variable.
1881 Note that this function doesn't *append* given flag to the variable, it
1883 erases existing value and assigns new one. Use cw_debug_get_flags() if
1884 you want to OR new flag with existing ones.
1885 Parameter(in): debug_object debug object for which to set flags Parame‐
1891 ter(in): flags new value to be assigned to the object, a sum of one or
1892 more of CW_DEBUG_* flags from libcw.h
1893 uint32_t cw_get_debug_flags(void)
1897 Brief: Get library's current debug flags
1898 Function returns value of library's internal debug variable, a sum of
1900 one or more of CW_DEBUG_* flags from libcw.h.
1901 Returns: value of library's debug flags variable
1909 uint32_t cw_debug_get_flags(const cw_debug_t * debug_object)
1913 Brief: Get current debug flags from given debug object
1914 Function returns value of debug object's debug flags, a sum of one or
1916 more of CW_DEBUG_* flags from libcw.h.
1917 Returns: value of debug object's debug flags
1923 bool cw_debug_has_flag(const cw_debug_t * debug_object, uint32_t flag)
1927 Brief: Check if given debug flag is set
1928 Function checks if a specified debug flag is set in given debug object.
1930 Parameter(in): debug_object debug object to be checked Parameter(in):
1936 flag flag to be checked, one of CW_DEBUG_* flags from libcw.h
1937 Returns: true if given flag is set
1939 Returns: false otherwise
1940 int cw_generator_set_tone_slope(cw_gen_t * gen, int slope_shape, int
1944 slope_duration)
1945 Brief: Set parameters describing slopes of tones generated by generator
1946 Most of variables related to slope of tones is in tone, but there are
1948 still some variables that are generator-specific, as they are common
1949 for all tones. This function sets two of these generator-specific
1950 variables.
1951 A: If you pass to function conflicting values of slope_shape and
1953 slope_duration, the function will return CW_FAILURE. These conflicting
1954 values are rectangular slope shape and larger than zero slope length.
1955 You just can't have rectangular slopes that have non-zero length.
1956 B: If you pass to function '-1' as value of both slope_shape and
1958 slope_duration, the function won't change any of the related two gener‐
1959 ator's parameters.
1960 C1: If you pass to function '-1' as value of either slope_shape or
1962 slope_duration, the function will attempt to set only this generator's
1963 parameter that is different than '-1'.
1964 C2: However, if selected slope shape is rectangular, function will set
1966 generator's slope length to zero, even if value of
1967 slope_duration is '-1'.
1968 D: Notice that the function allows non-rectangular slope shape with
1970 zero length of the slopes. The slopes will be non-rectangular, but just
1971 unusually short.
1972 The function should be called every time one of following parameters
1976 change:
1977 @li shape of slope, @li duration of slope, @li generator's sample rate,
1979 @li generator's volume.
1980 There are four supported shapes of slopes: @li linear (the only one
1982 supported by libcw until version 4.1.1), @li raised cosine (supposedly
1983 the most desired shape), @li sine, @li rectangular.
1984 Use CW_TONE_SLOPE_SHAPE_* symbolic names as values of slope_shape.
1986 FIXME: first argument of this public function is gen, but no function
1988 provides access to generator variable.
1989 Parameter(in): gen generator for which to set tone slope parameters
1995 Parameter(in): slope_shape shape of slope: linear, raised cosine, sine,
1996 rectangular Parameter(in): slope_duration duration of slope [microsec‐
1997 onds]
1998 Returns: CW_SUCCESS on success
2000 Returns: CW_FAILURE on failure
2001 bool cw_is_null_possible(__attribute__((unused)) const char *
2005 device_name)
2006 Brief: Check if it is possible to open Null sound output
2007 Parameter(in): device_name name of Null device to be used. Value is
2011 ignored for Null sound system.
2012 Returns: true it's always possible to write to Null device
2014 bool cw_is_oss_possible(const char * device_name)
2018 Brief: Check if it is possible to open OSS output with given device
2019 name
2020 Function does a test opening and test configuration of OSS output, but
2022 it closes it before returning.
2023 Parameter(in): device_name name of OSS device to be used; if NULL or
2027 empty then the function will use library-default device name.
2028 Returns: true if opening OSS output succeeded
2030 Returns: false if opening OSS output failed
2031 bool cw_is_pa_possible(const char * device_name)
2035 Brief: Check if it is possible to open PulseAudio output with given
2036 device name
2037 Function first tries to load PulseAudio library, and then does a test
2039 opening of PulseAudio output, but it closes it before returning.
2040 Parameter(in): device_name name of PulseAudio device to be used; if
2044 NULL then the function will use library-default device name.
2045 Returns: true if opening PulseAudio output succeeded
2047 Returns: false if opening PulseAudio output failed
2048 void cw_block_callback(int block)
2052 Brief: Block the callback from being called
2053 Function blocks the callback from being called for a critical section
2055 of caller code if block is true, and unblocks the callback if block is
2056 false.
2057 Function works by blocking SIGALRM; a block should always be matched by
2059 an unblock, otherwise the tone queue will suspend forever.
2060 Parameter: block - pass 1 to block SIGALRM, and 0 to unblock it
2062 int cw_register_signal_handler(int signal_number, void (*call‐
2066 back_func)(int))
2067 Brief: Register a signal handler and optional callback function for
2068 given signal number
2069 On receipt of that signal, all library features will be reset to their
2071 default states. Following the reset, if callback_func is a function
2072 pointer, the function is called; if it is SIG_DFL, the library calls
2073 exit(); and if it is SIG_IGN, the library returns from the signal han‐
2074 dler.
2075 This is a convenience function for clients that need to clean up
2077 library on signals, with either exit, continue, or an additional func‐
2078 tion call; in effect, a wrapper round a restricted form of sigaction.
2079 The signal_number argument indicates which signal to catch.
2081 On problems errno is set to EINVAL if signal_number is invalid or if a
2083 handler is already installed for that signal, or to the sigaction error
2084 code.
2085 Parameter: signal_number
2087 Parameter: callback_func
2088 Returns: CW_SUCCESS - if the signal handler installs correctly
2090 Returns: CW_FAILURE - on errors or problems
2091 int cw_unregister_signal_handler(int signal_number)
2095 Brief: Unregister a signal handler interception
2096 Function removes a signal handler interception previously registered
2098 with cw_register_signal_handler().
2099 Parameter: signal_number
2101 Returns: true if the signal handler uninstalls correctly
2103 Returns: false otherwise (with errno set to EINVAL or to the sigaction
2104 error code)
2105 int cw_version(void)
2109 Brief: Return version number of libcw library
2110 Return the version number of the library. Version numbers (major and
2112 minor) are returned as an int, composed of major_version << 16 |
2113 minor_version.
2114 Returns: library's major and minor version number encoded as single int
2118 void cw_license(void)
2122 Brief: Print libcw's license text to stdout
2123 Function prints to stdout information about libcw version, followed by
2125 short text presenting libcw's copyright and license notice.
2126 const char * cw_get_audio_system_label(int sound_system)
2130 Brief: Get a readable label of given sound system
2131 The function returns one of following strings: None, Null, Console,
2133 OSS, ALSA, PulseAudio, Soundcard
2134 Returned pointer is owned and managed by the library.
2136 *const cw_get_audio_system_label(...)"?
2138 Parameter(in): sound_system ID of sound system
2142 Returns: sound system's label
2144 void cw_get_speed_limits(int * min_speed, int * max_speed)
2148 Brief: Get speed limits
2149 Get (through function's arguments) limits on speed of Morse code that
2151 are supported by libcw.
2152 See CW_SPEED_MIN and CW_SPEED_MAX in libcw.h for values.
2154 Any of functions two arguments can be NULL - function won't update
2156 value of that argument.
2157 Parameter(out): min_speed minimal allowed speed Parameter(out):
2161 max_speed maximal allowed speed
2162 void cw_get_frequency_limits(int * min_frequency, int * max_frequency)
2166 Brief: Get frequency limits
2167 Get (through function's arguments) limits on frequency that are sup‐
2169 ported by libcw.
2170 See CW_FREQUENCY_MIN and CW_FREQUENCY_MAX in libcw.h for values.
2172 Any of functions two arguments can be NULL - function won't update
2174 value of that argument.
2175 Parameter(out): min_frequency minimal allowed frequency Parameter(out):
2179 max_frequency maximal allowed frequency
2180 void cw_get_volume_limits(int * min_volume, int * max_volume)
2184 Brief: Get volume limits
2185 Get (through function's arguments) limits on volume of sound supported
2187 by libcw and generated by generator.
2188 See CW_VOLUME_MIN and CW_VOLUME_MAX in libcw.h for values.
2190 Any of functions two arguments can be NULL - function won't update
2192 value of that argument.
2193 Parameter(out): min_volume minimal allowed volume Parameter(out):
2197 max_volume maximal allowed volume
2198 void cw_get_gap_limits(int * min_gap, int * max_gap)
2202 Brief: Get gap limits
2203 Get (through function's arguments) limits on gap in cw signal supported
2205 by libcw.
2206 See CW_GAP_MIN and CW_GAP_MAX in libcw.h for values.
2208 Any of functions two arguments can be NULL - function won't update
2210 value of that argument.
2211 Parameter(out): min_gap minimal allowed gap Parameter(out): max_gap
2215 maximal allowed gap
2216 void cw_get_tolerance_limits(int * min_tolerance, int * max_tolerance)
2220 Brief: Get tolerance limits
2221 Get (through function's arguments) limits on "tolerance" parameter sup‐
2223 ported by libcw.
2224 See CW_TOLERANCE_MIN and CW_TOLERANCE_MAX in libcw.h for values.
2226 Any of functions two arguments can be NULL - function won't update
2228 value of that argument.
2229 Parameter(out): min_tolerance minimal allowed tolerance Parameter(out):
2233 max_tolerance maximal allowed tolerance
2234 void cw_get_weighting_limits(int * min_weighting, int * max_weighting)
2238 Brief: Get weighting limits
2239 Get (through function's arguments) limits on "weighting" parameter sup‐
2241 ported by libcw.
2242 See CW_WEIGHTING_MIN and CW_WEIGHTING_MAX in libcw.h for values.
2244 Any of functions two arguments can be NULL - function won't update
2246 value of that argument.
2247 Parameter(out): min_weighting minimal allowed weighting Parameter(out):
2251 max_weighting maximal allowed weighting
2252 void cw_complete_reset(void)
2256 Brief: Reset all library features to their default states
2257 Clears the tone queue, receive buffers and retained state information,
2259 any current keyer activity, and any straight key activity, returns to
2260 silence, and closes soundcard and console devices. This function is
2261 suitable for calling from an application exit handler.
2262
2264 Despite the fact that this manual page constantly and consistently
2265 refers to Morse code elements as dots and dashes, DO NOT think in these
2266 terms when trying to learn Morse code. Always think of them as 'dit's
2267 and 'dah's.
2268 libcw uses system itimers for its internal timing. On most UNIX
2270 flavours, itimers are not guaranteed to signal a program exactly at the
2271 specified time, and they generally offer a resolution only as good as
2272 the normal system 'clock tick' resolution. An itimer SIGALRM usually
2273 falls on a system clock tick, making it accurate to no better than 10mS
2274 on a typical 100Hz kernel.
2275 The effect of this is that an itimer period is generally either exactly
2277 as specified, or, more likely, slightly longer. At higher WPM set‐
2278 tings, the cumulative effect of this affects timing accuracy, because
2279 at higher speeds, there are fewer 10mS clock ticks in a dot period.
2280 For example, at 12 WPM, the dot length is 100mS, enough to contain five
2281 kernel clock ticks; at 60 WPM, the dot length is 20mS, or just two ker‐
2282 nel clock ticks. So at higher speeds, the effect of itimer resolutions
2283 becomes more pronounced.
2284
2286 Man pages for cw(7,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL), cwcp(1,LOCAL),
2287 and xcwcp(1,LOCAL).
2288libcw ver. 7.0.0 CW Tutor Package LIBCW(3)