--- name: "libcw" section: "3" platform: "linux" package: "libcw-dev" version: "3.6.1-2+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/libcw" --- # libcw(3) general purpose Morse code functions library ## NAME libcw - general purpose Morse code functions library ## SYNOPSIS ``` #include ``` **int cw\_generator\_new(int audio\_system, const char \*device)**\ **void cw\_generator\_delete(void)**\ **int cw\_generator\_start(void)**\ **void cw\_generator\_stop(void)**\ **int cw\_set\_send\_speed(int new\_value)**\ **int cw\_set\_frequency(int new\_value)**\ **int cw\_set\_volume(int new\_value)**\ **int cw\_set\_gap(int new\_value)**\ **int cw\_set\_weighting(int new\_value)**\ **int cw\_get\_send\_speed(void)**\ **int cw\_get\_frequency(void)**\ **int cw\_get\_volume(void)**\ **int cw\_get\_gap(void)**\ **int cw\_get\_weighting(void)**\ **void cw\_get\_send\_parameters(int \*dot\_usecs, int \*dash\_usecs,**\ **int \*end\_of\_element\_usecs,**\ **int \*end\_of\_character\_usecs, int \*end\_of\_word\_usecs,**\ **int \*additional\_usecs, int \*adjustment\_usecs)**\ **int cw\_send\_dot(void)**\ **int cw\_send\_dash(void)**\ **int cw\_send\_character\_space(void)**\ **int cw\_send\_word\_space(void)**\ **int cw\_send\_representation(const char \*representation)**\ **int cw\_send\_representation\_partial(const char \*representation)**\ **int cw\_send\_character(char c)**\ **int cw\_send\_character\_partial(char c)**\ **int cw\_send\_string(const char \*string)**\ **void cw\_reset\_send\_receive\_parameters(void)**\ **const char \*cw\_get\_console\_device(void)**\ **const char \*cw\_get\_soundcard\_device(void)**\ **const char \*cw\_generator\_get\_audio\_system\_label(void)**\ **int cw\_generator\_remove\_last\_character(void)**\ **int cw\_register\_tone\_queue\_low\_callback(void (\*callback\_func)(void\*), void \*callback\_arg, int level)**\ **bool cw\_is\_tone\_busy(void)**\ **int cw\_wait\_for\_tone(void)**\ **int cw\_wait\_for\_tone\_queue(void)**\ **int cw\_wait\_for\_tone\_queue\_critical(int level)**\ **bool cw\_is\_tone\_queue\_full(void)**\ **int cw\_get\_tone\_queue\_capacity(void)**\ **int cw\_get\_tone\_queue\_length(void)**\ **void cw\_flush\_tone\_queue(void)**\ **void cw\_reset\_tone\_queue(void)**\ **int cw\_queue\_tone(int usecs, int frequency)**\ **int cw\_set\_receive\_speed(int new\_value)**\ **int cw\_get\_receive\_speed(void)**\ **int cw\_set\_tolerance(int new\_value)**\ **int cw\_get\_tolerance(void)**\ **void cw\_get\_receive\_parameters(int \*dot\_usecs, int \*dash\_usecs,**\ **int \*dot\_min\_usecs, int \*dot\_max\_usecs,**\ **int \*dash\_min\_usecs, int \*dash\_max\_usecs,**\ **int \*end\_of\_element\_min\_usecs,**\ **int \*end\_of\_element\_max\_usecs,**\ **int \*end\_of\_element\_ideal\_usecs,**\ **int \*end\_of\_character\_min\_usecs,**\ **int \*end\_of\_character\_max\_usecs,**\ **int \*end\_of\_character\_ideal\_usecs,**\ **int \*adaptive\_threshold)**\ **int cw\_set\_noise\_spike\_threshold(int new\_value)**\ **int cw\_get\_noise\_spike\_threshold(void)**\ **void cw\_get\_receive\_statistics(double \*dot\_sd, double \*dash\_sd,**\ **double \*element\_end\_sd, double \*character\_end\_sd)**\ **void cw\_reset\_receive\_statistics(void)**\ **void cw\_enable\_adaptive\_receive(void)**\ **void cw\_disable\_adaptive\_receive(void)**\ **bool cw\_get\_adaptive\_receive\_state(void)**\ **int cw\_start\_receive\_tone(const struct timeval \*timestamp)**\ **int cw\_end\_receive\_tone(const struct timeval \*timestamp)**\ **int cw\_receive\_buffer\_dot(const struct timeval \*timestamp)**\ **int cw\_receive\_buffer\_dash(const struct timeval \*timestamp)**\ **int cw\_receive\_representation(const struct timeval \*timestamp,**\ **/\* out \*/ char \*representation,**\ **/\* out \*/ bool \*is\_end\_of\_word,**\ **/\* out \*/ bool \*is\_error)**\ **int cw\_receive\_character(const struct timeval \*timestamp,**\ **/\* out \*/ char \*c,**\ **/\* out \*/ bool \*is\_end\_of\_word,**\ **/\* out \*/ bool \*is\_error)**\ **void cw\_clear\_receive\_buffer(void)**\ **int cw\_get\_receive\_buffer\_capacity(void)**\ **int cw\_get\_receive\_buffer\_length(void)**\ **void cw\_reset\_receive(void)**\ **void cw\_register\_keying\_callback(void (\*callback\_func)(void\*, int), void \*callback\_arg)**\ **void cw\_enable\_iambic\_curtis\_mode\_b(void)**\ **void cw\_disable\_iambic\_curtis\_mode\_b(void)**\ **int cw\_get\_iambic\_curtis\_mode\_b\_state(void)**\ **int cw\_notify\_keyer\_paddle\_event(int dot\_paddle\_state, int dash\_paddle\_state)**\ **int cw\_notify\_keyer\_dot\_paddle\_event(int dot\_paddle\_state)**\ **int cw\_notify\_keyer\_dash\_paddle\_event(int dash\_paddle\_state)**\ **void cw\_get\_keyer\_paddles(int \*dot\_paddle\_state, int \*dash\_paddle\_state)**\ **void cw\_get\_keyer\_paddle\_latches(int \*dot\_paddle\_latch\_state, int \*dash\_paddle\_latch\_state)**\ **bool cw\_is\_keyer\_busy(void)**\ **int cw\_wait\_for\_keyer\_element(void)**\ **int cw\_wait\_for\_keyer(void)**\ **void cw\_reset\_keyer(void)**\ **int cw\_notify\_straight\_key\_event(int key\_state)**\ **int cw\_get\_straight\_key\_state(void)**\ **bool cw\_is\_straight\_key\_busy(void)**\ **void cw\_reset\_straight\_key(void)**\ **bool cw\_is\_alsa\_possible(const char \* device\_name)**\ **bool cw\_is\_console\_possible(const char \* device\_name)**\ **int cw\_get\_character\_count(void)**\ **void cw\_list\_characters(char \* list)**\ **int cw\_get\_maximum\_representation\_length(void)**\ **int cw\_lookup\_character(char character, char \* representation)**\ **char \* cw\_character\_to\_representation(int character)**\ **int cw\_check\_representation(const char \* representation)**\ **bool cw\_representation\_is\_valid(const char \* representation)**\ **int cw\_lookup\_representation(const char \* representation, char \* character)**\ **int cw\_representation\_to\_character(const char \* representation)**\ **int cw\_get\_procedural\_character\_count(void)**\ **void cw\_list\_procedural\_characters(char \* list)**\ **int cw\_get\_maximum\_procedural\_expansion\_length(void)**\ **int cw\_lookup\_procedural\_character(char character, char \*expansion, int \* is\_usually\_expanded)**\ **int cw\_get\_maximum\_phonetic\_length(void)**\ **int cw\_lookup\_phonetic(char character, char \* phonetic)**\ **bool cw\_character\_is\_valid(char character)**\ **int cw\_check\_character(char character)**\ **bool cw\_string\_is\_valid(const char \* string)**\ **int cw\_check\_string(const char \* string)**\ **void cw\_set\_debug\_flags(uint32\_t flags)**\ **void cw\_debug\_set\_flags(cw\_debug\_t \* debug\_object, uint32\_t flags)**\ **uint32\_t cw\_get\_debug\_flags(void)**\ **uint32\_t cw\_debug\_get\_flags(const cw\_debug\_t \* debug\_object)**\ **bool cw\_debug\_has\_flag(const cw\_debug\_t \* debug\_object, uint32\_t flag)**\ **int cw\_generator\_set\_tone\_slope(cw\_gen\_t \* gen, int slope\_shape, int slope\_duration)**\ **bool cw\_is\_null\_possible(\_\_attribute\_\_((unused)) const char \* device\_name)**\ **bool cw\_is\_oss\_possible(const char \* device\_name)**\ **bool cw\_is\_pa\_possible(const char \* device\_name)**\ **void cw\_block\_callback(int block)**\ **int cw\_register\_signal\_handler(int signal\_number, void (\*callback\_func)(int))**\ **int cw\_unregister\_signal\_handler(int signal\_number)**\ **int cw\_version(void)**\ **void cw\_license(void)**\ **const char \* cw\_get\_audio\_system\_label(int sound\_system)**\ **void cw\_get\_speed\_limits(int \* min\_speed, int \* max\_speed)**\ **void cw\_get\_frequency\_limits(int \* min\_frequency, int \* max\_frequency)**\ **void cw\_get\_volume\_limits(int \* min\_volume, int \* max\_volume)**\ **void cw\_get\_gap\_limits(int \* min\_gap, int \* max\_gap)**\ **void cw\_get\_tolerance\_limits(int \* min\_tolerance, int \* max\_tolerance)**\ **void cw\_get\_weighting\_limits(int \* min\_weighting, int \* max\_weighting)**\ **void cw\_complete\_reset(void)**\ ### DESCRIPTION **libcw** is a general purpose CW (Morse code) functions library. It contains routines for converting characters into Morse code representations and back again, for sending Morse code characters, and for receiving characters. It also contains routines to emulate an Iambic Morse keyer, and a straight key. The library can be included in any program that wishes to make use of these features. It forms the heart of three Morse code tutor applications that accompany the package in which it is distributed. See the [**cw**(7)](/cw/7.md) man page for information on Morse code timings, and the dot and dash representations for the various Morse characters. ### TONE QUEUE **libcw** contains an inbuilt tone queue. The queue is emptied by background processing, using SIGALRM calls and itimers, so a caller program can continue with other tasks while the library sends tones and keys any external device. As well as being used by the library functions that sound Morse code characters and provide a keyer sidetone, the primitive tone queue functions are publicly available to caller programs. ### CONTROLLING AN EXTERNAL DEVICE **libcw** may be passed the address of a function that controls external keying. This function is called each time the library changes the keying state, either as a result of sending a Morse character or representation, or as a result of an iambic keyer or straight key state change. The argument passed is a single integer, TRUE for key-down, and FALSE for key-up. **libcw** calls the external keying function only when the keying state changes. A call is likely each time a tone is taken off the tone queue. ### SENDING CW CHARACTERS AND STRINGS **libcw** offers several functions that send individual characters and character strings as Morse code. It also offers functions that allow specialized 'representations' to be sent. A 'representation' is an ASCII string that consists of only the characters '.' and '-'. Characters and strings are converted into representations, and then the correct tones for the dots and dashes in these representations are queued on the tone queue, for action by the background queue emptying process. ### RECEIVING CW CHARACTERS AND REPRESENTATIONS **libcw** contains functions to allow it to receive Morse code. To receive, the library must be told when a tone start is detected, and when a tone end is detected. It then determines whether the tone was a dot or a dash depending on the timing difference between the two. After the required silence gap has passed, the library may be queried to see what the received representation or character was. Errors in receiving may be detected by means of the flags passed back on receive character functions. ### IAMBIC KEYER **libcw** offers functions to simulate an Iambic Morse keyer. The caller program needs to tell the library of paddle state changes. Iambic keyer functions are mutually exclusive with character send and straight key functions. ### STRAIGHT KEY **libcw** offers simple functions to allow effective pass-through of straight key information. The caller program needs to tell the library of key state changes. Straight key functions are mutually exclusive with character send and iambic keyer functions. ### RETURN CODES Some of the library's function return a return code of type int. The return code has two values, as defined in libcw.h: **CW\_SUCCESS** or **CW\_FAILURE**. The two symbolic constants are guaranteed to be identical to boolean **true** and **false**. ### FUNCTIONS The following list describes the functions available to a **libcw** caller: **int cw\_generator\_new(int audio\_system, const char \*device)**\ Brief: Create new generator Allocate memory for new generator data structure, set up default values of some of the generator's properties. The function does not start the generator (generator does not produce a sound), you have to use cw\_generator\_start() for this. Notice that the function doesn't return a generator variable. There is at most one generator variable at any given time. You can't have two generators. In some future version of the library the function will return pointer to newly allocated generator, and then you could have as many of them as you want, but not yet. **audio\_system** can be one of following: NULL, console, OSS, ALSA, PulseAudio, soundcard. See "enum cw\_audio\_systems" in libcw.h for exact names of symbolic constants. Parameter: audio\_system - audio system to be used by the generator\ Parameter: device - name of audio device to be used; if NULL then library will use default device. **void cw\_generator\_delete(void)**\ Brief: Deallocate generator Deallocate/destroy generator data structure created with call to cw\_generator\_new(). You can't start nor use the generator after the call to this function. **int cw\_generator\_start(void)**\ Brief: Start a generator Start producing tones using generator created with cw\_generator\_new(). The source of tones is a tone queue associated with the generator. If the tone queue is empty, the generator will wait for new tones to be queued. Returns: CW\_FAILURE on errors\ Returns: CW\_SUCCESS on success **void cw\_generator\_stop(void)**\ Brief: Shut down a generator Silence tone generated by generator (level of generated sine wave is set to zero, with falling slope), and shut the generator down. The shutdown does not erase generator's configuration. If you want to have this generator running again, you have to call cw\_generator\_start(). **int cw\_set\_send\_speed(int new\_value)**\ Brief: Set sending speed of generator See libcw.h/CW\_SPEED\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of send speed. errno is set to EINVAL if **new\_value** is out of range. Parameter: new\_value - new value of send speed to be assigned to generator Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_set\_frequency(int new\_value)**\ Brief: Set frequency of generator Set frequency of sound wave generated by generator. The frequency must be within limits marked by CW\_FREQUENCY\_MIN and CW\_FREQUENCY\_MAX. See libcw.h/CW\_FREQUENCY\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of frequency. errno is set to EINVAL if **new\_value** is out of range. Parameter: new\_value - new value of frequency to be assigned to generator Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_set\_volume(int new\_value)**\ Brief: Set volume of generator Set volume of sound wave generated by generator. The volume must be within limits marked by CW\_VOLUME\_MIN and CW\_VOLUME\_MAX. Note that volume settings are not fully possible for the console speaker. In this case, volume settings greater than zero indicate console speaker sound is on, and setting volume to zero will turn off console speaker sound. See libcw.h/CW\_VOLUME\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of volume. errno is set to EINVAL if **new\_value** is out of range. Parameter: new\_value - new value of volume to be assigned to generator Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_set\_gap(int new\_value)**\ Brief: Set sending gap of generator See libcw.h/CW\_GAP\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of gap. errno is set to EINVAL if **new\_value** is out of range. Notice that this function also sets the same gap value for library's receiver. Parameter: new\_value - new value of gap to be assigned to generator Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_set\_weighting(int new\_value)**\ Brief: Set sending weighting for generator See libcw.h/CW\_WEIGHTING\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of weighting. errno is set to EINVAL if **new\_value** is out of range. Parameter: new\_value - new value of weighting to be assigned for generator Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_get\_send\_speed(void)**\ Brief: Get sending speed from generator Returns: current value of the generator's send speed **int cw\_get\_frequency(void)**\ Brief: Get frequency from generator Function returns "frequency" parameter of generator, even if the generator is stopped, or volume of generated sound is zero. Returns: current value of generator's frequency **int cw\_get\_volume(void)**\ Brief: Get sound volume from generator Function returns "volume" parameter of generator, even if the generator is stopped. Returns: current value of generator's sound volume **int cw\_get\_gap(void)**\ Brief: Get sending gap from generator Returns: current value of generator's sending gap **int cw\_get\_weighting(void)**\ Brief: Get sending weighting from generator Returns: current value of generator's sending weighting **void cw\_get\_send\_parameters(int \*dot\_usecs, int \*dash\_usecs,**\ **int \*end\_of\_element\_usecs,**\ **int \*end\_of\_character\_usecs, int \*end\_of\_word\_usecs,**\ **int \*additional\_usecs, int \*adjustment\_usecs)**\ Brief: Get timing parameters for sending Return the low-level timing parameters calculated from the speed, gap, tolerance, and weighting set. Parameter values are returned in microseconds. Use NULL for the pointer argument to any parameter value not required. Parameter: dot\_usecs\ Parameter: dash\_usecs\ Parameter: end\_of\_element\_usecs\ Parameter: end\_of\_character\_usecs\ Parameter: end\_of\_word\_usecs\ Parameter: additional\_usecs\ Parameter: adjustment\_usecs **int cw\_send\_dot(void)**\ Brief: Low-level primitive for sending a Dot Mark Low-level primitive function able to play/send single Dot Mark. The function appends to a tone queue a normal inter-mark-space after the Dot Mark. Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_dash(void)**\ Brief: Low-level primitive for sending a Dash Mark Low-level primitive function able to play/send single Dash Mark. The function appends to a tone queue a normal inter-mark-space after the Dash Mark. Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_character\_space(void)**\ The function enqueues space of specific length: together with previously implicitly enqueued inter-mark-space of size 1 Unit, enqueueing this space will form a full inter-character-space of size 3 Units. Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_word\_space(void)**\ The function enqueues space of specific length: together with previously implicitly enqueued inter-mark-space of size 1 Unit and implicitly or explicitly enqueued inter-character-space, enqueueing this space will form a full inter-word-space of size 7 Units. Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_representation(const char \*representation)**\ Brief: Check, then send the given string as dots and dashes. The representation passed in is assumed to be a complete Morse character; that is, all post-character delays will be added when the character is sent. On success, the routine returns CW\_SUCCESS. On failure, it returns CW\_FAILURE, with errno set to EINVAL if any character of the representation is invalid, EBUSY if the sound card, console speaker, or keying system is busy, or EAGAIN if the tone queue is full, or if there is insufficient space to queue the tones or the representation. Parameter: representation - representation to send Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_representation\_partial(const char \*representation)**\ Brief: Check, then send the given string as dots and dashes The **representation** passed in is assumed to be only part of a larger Morse representation; that is, no post-character delays will be added when the character is sent. On success, the routine returns CW\_SUCCESS. On failure, it returns CW\_FAILURE, with errno set to EINVAL if any character of the representation is invalid, EBUSY if the sound card, console speaker, or keying system is busy, or EAGAIN if the tone queue is full, or if there is insufficient space to queue the tones for the representation. **int cw\_send\_character(char c)**\ Brief: Look up and send a given ASCII character as Morse The end of character delay is appended to the Morse sent. On success the routine returns CW\_SUCCESS. On failure the function returns CW\_FAILURE and sets errno. errno is set to ENOENT if the given character **c** is not a valid Morse character. errno is set to EBUSY if current audio sink or keying system is busy. errno is set to EAGAIN if the generator's tone queue is full, or if there is insufficient space to queue the tones for the character. This routine returns as soon as the character has been successfully queued for sending; that is, almost immediately. The actual sending happens in background processing. See cw\_wait\_for\_tone() and cw\_wait\_for\_tone\_queue() for ways to check the progress of sending. Parameter: c - character to send Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_character\_partial(char c)**\ Brief: Look up and send a given ASCII character as Morse code "partial" means that the inter-character-space is not appended to the Morse code sent by the function, to support the formation of combination characters. On success the function returns CW\_SUCCESS. On failure the function returns CW\_FAILURE and sets errno. errno is set to ENOENT if the given character **c** is not a valid Morse character. errno is set to EBUSY if the audio sink or keying system is busy. errno is set to EAGAIN if the tone queue is full, or if there is insufficient space to queue the tones for the character. This routine queues its arguments for background processing. See cw\_wait\_for\_tone() and cw\_wait\_for\_tone\_queue() for ways to check the progress of sending. Parameter: c - character to send Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_send\_string(const char \*string)**\ Brief: Send a given ASCII string in Morse code errno is set to ENOENT if any character in the string is not a valid Morse character. errno is set to EBUSY if audio sink or keying system is busy. errno is set to EAGAIN if the tone queue is full or if the tone queue runs out of space part way through queueing the string. However, an indeterminate number of the characters from the string will have already been queued. For safety, clients can ensure the tone queue is empty before queueing a string, or use cw\_send\_character() if they need finer control. This routine queues its arguments for background processing, the actual sending happens in background processing. See cw\_wait\_for\_tone() and cw\_wait\_for\_tone\_queue() for ways to check the progress of sending. Parameter: string - string to send Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **void cw\_reset\_send\_receive\_parameters(void)**\ Brief: Reset send/receive parameters Reset the library speed, frequency, volume, gap, tolerance, weighting, adaptive receive, and noise spike threshold to their initial default values: send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0 dots, tolerance 50 %, and weighting 50 %. **const char \*cw\_get\_console\_device(void)**\ Brief: Return char string with console device path Returned pointer is owned by library. Returns: char string with current console device path **const char \*cw\_get\_soundcard\_device(void)**\ Brief: Return char string with soundcard device name/path Returned pointer is owned by library. Returns: char string with current soundcard device name or device path **const char \*cw\_generator\_get\_audio\_system\_label(void)**\ Brief: Get a readable label of current audio system The function returns one of following strings: None, Null, Console, OSS, ALSA, PulseAudio, Soundcard Returns: audio system's label **int cw\_generator\_remove\_last\_character(void)**\ Brief: Remove last character from queue of already enqueued characters If the character is not actually played by sound sink yet, library may be able to remove the character. The character's Dots and Dashes won't be played. This function may be useful if user presses backspace in UI to remove/undo a character. If your application doesn't enqueue whole characters or strings of characters but is using low-level cw\_send\_dot()/cw\_send\_dash() functions to enqueue individual Marks, don't use this function. This function won't be able to recognize whole characters and is likely to remove more tones than expected. Returns: CW\_SUCCESS if function managed to remove a last character before it has been played\ Returns: CW\_FAILURE otherwise **int cw\_register\_tone\_queue\_low\_callback(void (\*callback\_func)(void\*), void \*callback\_arg, int level)**\ Brief: Register callback for low queue state Register a function to be called automatically by the dequeue routine whenever the count of tones in tone queue falls to a given **level**. To be more precise: the callback is called by queue's dequeue function if, after dequeueing a tone, the function notices that tone queue length has become equal or less than **level**. **level** can't be negative. **level** can't be equal to or larger than tone queue capacity. If **level** is zero, the behaviour of the mechanism is not guaranteed to work correctly. If **callback\_func** is NULL then the mechanism becomes disabled. **callback\_arg** will be passed to **callback\_arg**. errno is set to EINVAL when **level** is invalid. Parameter: callback\_func - callback function to be registered\ Parameter: callback\_arg - argument for callback\_func to pass return value\ Parameter: level - low level of queue triggering callback call Returns: CW\_SUCCESS on successful registration\ Returns: CW\_FAILURE on failure **bool cw\_is\_tone\_busy(void)**\ Brief: Check if tone sender is busy Indicate if the tone sender is busy. Returns: true if there are still entries in the tone queue\ Returns: false if the queue is empty **int cw\_wait\_for\_tone(void)**\ Brief: Wait for the current tone to complete Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_wait\_for\_tone\_queue(void)**\ Brief: Wait for the tone queue to drain Notice that generator must be running (started with cw\_generator\_start()) when this function is called, otherwise it will be waiting forever for a change of tone queue's level that will never happen. Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_wait\_for\_tone\_queue\_critical(int level)**\ Brief: Wait for the tone queue to drain until only as many tones as given in level remain queued This routine is for use by programs that want to optimize themselves to avoid the cleanup that happens when the tone queue drains completely; such programs have a short time in which to add more tones to the queue. Notice that generator must be running (started with cw\_generator\_start()) when this function is called, otherwise it will be waiting forever for a change of tone queue's level that will never happen. If **level** is negative, function sets errno to EINVAL and returns CW\_FAILURE. Parameter: level - low level in queue, at which to return Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **bool cw\_is\_tone\_queue\_full(void)**\ Brief: Indicate if the tone queue is full Returns: true if tone queue is full\ Returns: false if tone queue is not full **int cw\_get\_tone\_queue\_capacity(void)**\ Brief: Return the number of entries the tone queue can accommodate **int cw\_get\_tone\_queue\_length(void)**\ Brief: Return the number of entries currently pending in the tone queue **void cw\_flush\_tone\_queue(void)**\ Brief: Cancel all pending queued tones, and return to silence. If there is a tone in progress, the function will wait until this last one has completed, then silence the tones. **void cw\_reset\_tone\_queue(void)**\ Cancel all pending queued tones, reset any queue low callback registered, and return to silence. This function is suitable for calling from an application exit handler. **int cw\_queue\_tone(int usecs, int frequency)**\ Brief: Primitive access to simple tone generation This routine queues a tone of given duration and frequency. The routine returns CW\_SUCCESS on success. If usec or frequency are invalid, it returns CW\_FAILURE with errno set to EINVAL. If the sound card, console speaker, or keying function are busy, it returns CW\_FAILURE with errno set to EBUSY. If the tone queue is full, it returns false with errno set to EAGAIN. Parameter: usecs - duration of queued tone, in microseconds\ Parameter: frequency - frequency of queued tone Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_set\_receive\_speed(int new\_value)**\ Brief: Set receiving speed of receiver See documentation of cw\_set\_send\_speed() for more information. See libcw.h/CW\_SPEED\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of receive speed. errno is set to EINVAL if **new\_value** is out of range. errno is set to EPERM if adaptive receive speed tracking is enabled. Parameter: new\_value - new value of receive speed to be assigned to receiver Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_get\_receive\_speed(void)**\ Brief: Get receiving speed from receiver Returns: current value of the receiver's receive speed **int cw\_set\_tolerance(int new\_value)**\ Brief: Set tolerance for receiver See libcw.h/CW\_TOLERANCE\_{INITIAL\|MIN\|MAX} for initial/minimal/maximal value of tolerance. errno is set to EINVAL if **new\_value** is out of range. Parameter: new\_value - new value of tolerance to be assigned to receiver Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_get\_tolerance(void)**\ Brief: Get tolerance from receiver Returns: current value of receiver's tolerance **void cw\_get\_receive\_parameters(int \*dot\_usecs, int \*dash\_usecs,**\ **int \*dot\_min\_usecs, int \*dot\_max\_usecs,**\ **int \*dash\_min\_usecs, int \*dash\_max\_usecs,**\ **int \*end\_of\_element\_min\_usecs,**\ **int \*end\_of\_element\_max\_usecs,**\ **int \*end\_of\_element\_ideal\_usecs,**\ **int \*end\_of\_character\_min\_usecs,**\ **int \*end\_of\_character\_max\_usecs,**\ **int \*end\_of\_character\_ideal\_usecs,**\ **int \*adaptive\_threshold)**\ Brief: Get timing parameters for receiving, and adaptive threshold Return the low-level timing parameters calculated from the speed, gap, tolerance, and weighting set. Parameter values are returned in microseconds. Use NULL for the pointer argument to any parameter value not required. Parameter: dot\_usecs\ Parameter: dash\_usecs\ Parameter: dot\_min\_usecs\ Parameter: dot\_max\_usecs\ Parameter: dash\_min\_usecs\ Parameter: dash\_max\_usecs\ Parameter: end\_of\_element\_min\_usecs\ Parameter: end\_of\_element\_max\_usecs\ Parameter: end\_of\_element\_ideal\_usecs\ Parameter: end\_of\_character\_min\_usecs\ Parameter: end\_of\_character\_max\_usecs\ Parameter: end\_of\_character\_ideal\_usecs\ Parameter: adaptive\_threshold **int cw\_set\_noise\_spike\_threshold(int new\_value)**\ Brief: Set noise spike threshold for receiver Set the period shorter than which, on receive, received marks are ignored. This allows the "receive mark" functions to apply noise canceling for very short apparent marks. For useful results the value should never exceed the dot length of a dot at maximum speed: 20000 microseconds (the dot length at 60WPM). Setting a noise threshold of zero turns off receive mark noise canceling. The default noise spike threshold is 10000 microseconds. errno is set to EINVAL if **new\_value** is out of range. Parameter: new\_value - new value of noise spike threshold to be assigned to receiver Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_get\_noise\_spike\_threshold(void)**\ Brief: Get noise spike threshold from receiver See documentation of cw\_set\_noise\_spike\_threshold() for more information Returns: current value of receiver's threshold **void cw\_get\_receive\_statistics(double \*dot\_sd, double \*dash\_sd,**\ **double \*element\_end\_sd, double \*character\_end\_sd)**\ Brief: Calculate and return receiver's timing statistics These statistics may be used to obtain a measure of the accuracy of received CW. The values **dot\_sd** and **dot\_sd** contain the standard deviation of dot and dash lengths from the ideal values, and **element\_end\_sd** and **element\_end\_sd** the deviations for inter element and inter character spacing. Statistics are held for all timings in a 256 element circular buffer. If any statistic cannot be calculated, because no records for it exist, the returned value is 0.0. Use NULL for the pointer argument to any statistic not required. Parameter: dot\_sd\ Parameter: dash\_sd\ Parameter: element\_end\_sd\ Parameter: character\_end\_sd **void cw\_reset\_receive\_statistics(void)**\ Brief: Clear the receive statistics buffer Clear the receive statistics buffer by removing all records from it and returning it to its initial default state. **void cw\_enable\_adaptive\_receive(void)**\ Brief: Enable adaptive receive speed tracking If adaptive speed tracking is enabled, the receive functions will attempt to automatically adjust the receive speed setting to match the speed of the incoming Morse code. If it is disabled, the receive functions will use fixed speed settings, and reject incoming Morse which is not at the expected speed. Adaptive speed tracking uses a moving average length of the past N marks as its baseline for tracking speeds. The default state is adaptive speed tracking disabled. **void cw\_disable\_adaptive\_receive(void)**\ Brief: Disable adaptive receive speed tracking See documentation of cw\_enable\_adaptive\_receive() for more information **bool cw\_get\_adaptive\_receive\_state(void)**\ Brief: Get adaptive receive speed tracking flag The function returns state of "adaptive receive enabled" flag. See documentation of cw\_enable\_adaptive\_receive() for more information Returns: true if adaptive speed tracking is enabled\ Returns: false otherwise **int cw\_start\_receive\_tone(const struct timeval \*timestamp)**\ Brief: Signal beginning of receive mark Called on the start of a receive mark. If the **timestamp** is NULL, the current timestamp is used as beginning of mark. The function should be called by client application when pressing a key down (closing a circuit) has been detected by client application. On error the function returns CW\_FAILURE, with errno set to ERANGE if the call is directly after another cw\_start\_receive\_tone() call or if an existing received character has not been cleared from the buffer, or EINVAL if the timestamp passed in is invalid. Parameter: timestamp - time stamp of "key down" event Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE otherwise (with errno set) **int cw\_end\_receive\_tone(const struct timeval \*timestamp)**\ Brief: Signal end of mark The function should be called by client application when releasing a key (opening a circuit) has been detected by client application. If the **timestamp** is NULL, the current time is used as timestamp of end of mark. On success, the routine adds a dot or dash to the receiver's representation buffer, and returns CW\_SUCCESS. On failure, it returns CW\_FAIURE, with errno set to: ERANGE if the call was not preceded by a cw\_start\_receive\_tone() call, EINVAL if the timestamp passed in is not valid, ENOENT if function can't tell from duration of the Mark if it's Dot or Dash, ENOMEM if the receiver's representation buffer is full, EAGAIN if the mark was shorter than the threshold for noise and was therefore ignored. Parameter: timestamp - time stamp of "key up" event Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_receive\_buffer\_dot(const struct timeval \*timestamp)**\ Brief: Add a dot to the receiver's representation buffer Documentation for both cw\_receive\_buffer\_dot() and cw\_receive\_buffer\_dash(): Since we can't add a mark to the buffer without any accompanying timing information, the functions accepts **timestamp** of the "end of mark" event. If the **timestamp** is NULL, the current timestamp is used. These routines are for client code that has already determined whether a dot or dash was received by a method other than calling the routines cw\_start\_receive\_tone() and cw\_end\_receive\_tone(). On success, the relevant mark is added to the receiver's representation buffer. On failure, the routines return CW\_FAILURE and set errno: ERANGE if preceded by a cw\_start\_receive\_tone() call with no matching cw\_end\_receive\_tone() or if an error condition currently exists within the receiver's buffer, EINVAL if the timestamp passed in is not valid, ENOMEM if the receiver's representation buffer is full. Parameter: timestamp - timestamp of "end of dot" event Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_receive\_buffer\_dash(const struct timeval \*timestamp)**\ Brief: Add a dash to the receiver's representation buffer See documentation of cw\_receive\_buffer\_dot() for more information. Parameter: timestamp - timestamp of "end of dash" event Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_receive\_representation(const struct timeval \*timestamp,**\ **/\* out \*/ char \*representation,**\ **/\* out \*/ bool \*is\_end\_of\_word,**\ **/\* out \*/ bool \*is\_error)**\ Brief: Get the current buffered representation from the receiver's representation buffer On success the function fills in **representation** with the contents of the current representation buffer and returns CW\_SUCCESS. On failure, it returns CW\_FAILURE and sets errno to: ERANGE if not preceded by a cw\_end\_receive\_tone() call, a prior successful cw\_receive\_representation call, or a prior cw\_receive\_buffer\_dot or cw\_receive\_buffer\_dash, EINVAL if the timestamp passed in is invalid, EAGAIN if the call is made too early to determine whether a complete representation has yet been placed in the buffer (that is, less than the inter-character-space duration elapsed since the last cw\_end\_receive\_tone() or cw\_receive\_buffer\_dot/dash call). This is not a \*hard\* error, just an information that the caller should try to get the representation later. **is\_end\_of\_word** indicates that the space after the last mark received is longer that the inter-character-space, so it must be qualified as inter-word-space. **is\_error** indicates that the representation was terminated by an error condition. The function is called periodically (poll()-like function) by client code in hope that at some attempt receiver will be ready to pass **representation**. The attempt succeeds only if data stream is in "space" state. To mark end of the space, client code has to provide a timestamp (or pass NULL timestamp, the function will get time stamp at function call). The receiver needs to know the "end of space" event - thus the **timestamp** parameter. Parameter: timestamp - timestamp of event that ends inter-character-space or inter-word-space\ Parameter: representation - buffer for representation (output parameter)\ Parameter: is\_end\_of\_word - buffer for "is end of word" state (output parameter)\ Parameter: is\_error - buffer for "error" state (output parameter) Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_receive\_character(const struct timeval \*timestamp,**\ **/\* out \*/ char \*c,**\ **/\* out \*/ bool \*is\_end\_of\_word,**\ **/\* out \*/ bool \*is\_error)**\ Brief: Get a current character Function returns the character currently stored in receiver's representation buffer. On success the function returns CW\_SUCCESS, and fills **c** with the contents of the current representation buffer, translated into a character. On failure the function returns CW\_FAILURE, with errno set to: ERANGE if not preceded by a cw\_end\_receive\_tone() call, a prior successful cw\_receive\_character() call, or a cw\_receive\_buffer\_dot() or cw\_receive\_buffer\_dash() call, EINVAL if the timestamp passed in is invalid, or EAGAIN if the call is made too early to determine whether a complete character has yet been placed in the buffer (that is, less than the inter-character-space duration elapsed since the last cw\_end\_receive\_tone() or cw\_receive\_buffer\_dot/dash call). ENOENT if character stored in receiver cannot be recognized as valid **is\_end\_of\_word** indicates that the space after the last mark received is longer that the inter-character-space, so it must be qualified as inter-word-space. **is\_error** indicates that the character was terminated by an error condition. Parameter: timestamp - timestamp of event that ends inter-character-space or inter-word-space\ Parameter: c - buffer for character (output parameter)\ Parameter: is\_end\_of\_word - buffer for "is end of word" state (output parameter)\ Parameter: is\_error - buffer for "error" state (output parameter) Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **void cw\_clear\_receive\_buffer(void)**\ Brief: Clear receiver's representation buffer Clears the receiver's representation buffer, resets receiver's internal state. This prepares the receiver to receive marks and spaces again. This routine must be called after successful, or terminating, cw\_receive\_representation() or cw\_receive\_character() calls, to clear the states and prepare the buffer to receive more marks and spaces. When migrating to libcw2.h, use cw\_rec\_reset\_state() instead of this function. **int cw\_get\_receive\_buffer\_capacity(void)**\ Brief: Get the number of elements (dots/dashes) the receiver's buffer can accommodate The maximum number of elements written out by cw\_receive\_representation() is the capacity + 1, the extra character being used for the terminating NUL. Returns: number of elements that can be stored in receiver's representation buffer **int cw\_get\_receive\_buffer\_length(void)**\ Brief: Get the number of elements (dots/dashes) currently pending in the cw\_receiver's representation buffer Returns: number of elements in receiver's representation buffer **void cw\_reset\_receive(void)**\ Brief: Clear receive data Clear the receiver's representation buffer, statistics, and any retained receiver's state. This function is suitable for calling from an application exit handler. When migrating to libcw2.h, use cw\_rec\_reset\_state() and cw\_rec\_reset\_statistics() instead of this function. **void cw\_register\_keying\_callback(void (\*callback\_func)(void\*, int), void \*callback\_arg)**\ Brief: Register external callback function for keying Register a **callback\_func** function that should be called when a state of a key changes from "key open" to "key closed", or vice-versa. The first argument passed to the registered callback function is the supplied **callback\_arg**, if any. The second argument passed to registered callback function is the key state: CW\_KEY\_STATE\_CLOSED (one/true) for "key closed", and CW\_KEY\_STATE\_OPEN (zero/false) for "key open". Calling this routine with a NULL function address disables keying callbacks. Any callback supplied will be called in signal handler context (??). Parameter: callback\_func - callback function to be called on key state changes\ Parameter: callback\_arg - first argument to callback\_func **void cw\_enable\_iambic\_curtis\_mode\_b(void)**\ Brief: Enable iambic Curtis mode B Normally, the iambic keying functions will emulate Curtis 8044 Keyer mode A. In this mode, when both paddles are pressed together, the last dot or dash being sent on release is completed, and nothing else is sent. In mode B, when both paddles are pressed together, the last dot or dash being sent on release is completed, then an opposite element is also sent. Some operators prefer mode B, but timing is more critical in this mode. The default mode is Curtis mode A. **void cw\_disable\_iambic\_curtis\_mode\_b(void)**\ See documentation of cw\_enable\_iambic\_curtis\_mode\_b() for more information **int cw\_get\_iambic\_curtis\_mode\_b\_state(void)**\ See documentation of cw\_enable\_iambic\_curtis\_mode\_b() for more information **int cw\_notify\_keyer\_paddle\_event(int dot\_paddle\_state, int dash\_paddle\_state)**\ Brief: Inform about changed state of iambic keyer's paddles Function informs the library that the iambic keyer paddles have changed state. The new paddle states are recorded, and if either transition from false to true, paddle latches, for iambic functions, are also set. On success, the routine returns CW\_SUCCESS. On failure, it returns CW\_FAILURE, with errno set to EBUSY if the tone queue or straight key are using the sound card, console speaker, or keying system. If appropriate, this routine starts the keyer functions sending the relevant element. Element send and timing occurs in the background, so this routine returns almost immediately. Parameter: dot\_paddle\_state\ Parameter: dash\_paddle\_state Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_notify\_keyer\_dot\_paddle\_event(int dot\_paddle\_state)**\ Brief: Change state of dot paddle Alter the state of just one of the two iambic keyer paddles. The other paddle state of the paddle pair remains unchanged. See cw\_notify\_keyer\_paddle\_event() for details of iambic keyer background processing, and how to check its status. Parameter: dot\_paddle\_state **int cw\_notify\_keyer\_dash\_paddle\_event(int dash\_paddle\_state)**\ See documentation of cw\_notify\_keyer\_dot\_paddle\_event() for more information **void cw\_get\_keyer\_paddles(int \*dot\_paddle\_state, int \*dash\_paddle\_state)**\ Brief: Get the current saved states of the two paddles Parameter: dot\_paddle\_state\ Parameter: dash\_paddle\_state **void cw\_get\_keyer\_paddle\_latches(int \*dot\_paddle\_latch\_state, int \*dash\_paddle\_latch\_state)**\ Brief: Get the current states of paddle latches Function returns the current saved states of the two paddle latches. A paddle latches is set to true when the paddle state becomes true, and is cleared if the paddle state is false when the element finishes sending. Parameter: dot\_paddle\_latch\_state\ Parameter: dash\_paddle\_latch\_state **bool cw\_is\_keyer\_busy(void)**\ Brief: Check if a keyer is busy Returns: true if keyer is busy\ Returns: false if keyer is not busy **int cw\_wait\_for\_keyer\_element(void)**\ Brief: Wait for end of element from the keyer Waits until the end of the current element, dot or dash, from the keyer. Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_wait\_for\_keyer(void)**\ Brief: Wait for the current keyer cycle to complete Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **void cw\_reset\_keyer(void)**\ Brief: Reset iambic keyer data Clear all latches and paddle states of iambic keyer, return to Curtis 8044 Keyer mode A, and return to silence. This function is suitable for calling from an application exit handler. **int cw\_notify\_straight\_key\_event(int key\_state)**\ Brief: Inform the library that the straight key has changed state This routine returns CW\_SUCCESS on success. On error, it returns CW\_FAILURE, with errno set to EBUSY if the tone queue or iambic keyer are using the sound card, console speaker, or keying control system. If **key\_state** indicates no change of state, the call is ignored. **key\_state** may be either CW\_KEY\_STATE\_OPEN (false) or CW\_KEY\_STATE\_CLOSED (true). Parameter: key\_state - state of straight key **int cw\_get\_straight\_key\_state(void)**\ Brief: Get saved state of straight key Returns the current saved state of the straight key. Returns: CW\_KEY\_STATE\_CLOSED (true) if the key is down\ Returns: CW\_KEY\_STATE\_OPEN (false) if the key up **bool cw\_is\_straight\_key\_busy(void)**\ Brief: Check if the straight key is busy This routine is just a pseudonym for cw\_get\_straight\_key\_state(), and exists to fill a hole in the API naming conventions. Returns: true if the straight key is busy\ Returns: false if the straight key is not busy **void cw\_reset\_straight\_key(void)**\ Brief: Clear the straight key state, and return to silence This function is suitable for calling from an application exit handler. **bool cw\_is\_alsa\_possible(const char \* device\_name)**\ Brief: Check if it is possible to open ALSA output with given device name The check consists of two parts: -# whether it's possible to load ALSA shared library, -# whether it's possible to open ALSA device specified by **device\_name** If it's possible to use ALSA with given device name, the function leaves library handle (returned by dlopen()) open and some library function symbols loaded, but does not leave any ALSA PCM handle open. Parameter(in): device\_name name of ALSA device to be used; if NULL or empty then the function will use library-default device name. Returns: true if opening ALSA output succeeded\ Returns: false if opening ALSA output failed **bool cw\_is\_console\_possible(const char \* device\_name)**\ Brief: Check if it is possible to open console buzzer output Function does a test opening and test writing to console buzzer device **device\_name**, but it closes it before returning. The function tests that the given console buzzer device exists, and that it will accept the KIOCSOUND ioctl. It unconditionally returns false on platforms that do no support the KIOCSOUND ioctl. Call to ioctl will fail if calling code doesn't have root privileges. This is the only place where we ask if KIOCSOUND is defined, so client code must call this function whenever it wants to use console output, as every other function called to perform console operations will happily assume that it is allowed to perform such operations. Parameter(in): device\_name name of console buzzer device to be used; if NULL or empty then the function will use library-default device name. Returns: true if opening console output succeeded\ Returns: false if opening console output failed **int cw\_get\_character\_count(void)**\ Brief: Return the number of characters present in main character lookup table Return the number of characters that are known to libcw. The number includes: @li ASCII 7bit letters, @li numerals, @li punctuation, @li ISO 8859-1 accented characters, @li ISO 8859-2 accented characters, @li non-standard procedural signal extensions to standard CW characters. Returns: number of characters known to libcw **void cw\_list\_characters(char \* list)**\ Brief: Get list of characters present in character lookup table Function provides a string containing all of the characters represented in library's lookup table. The list includes: @li ASCII 7bit letters, @li numerals, @li punctuation, @li ISO 8859-1 accented characters, @li ISO 8859-2 accented characters, @li non-standard procedural signal extensions to standard CW characters. **list** should be allocated and managed by caller. The length of **list** must be at least one greater than the number of characters represented in the character lookup table, returned by cw\_get\_character\_count(). The string placed in **list** will be NUL-terminated. Parameter(out): list buffer for string with all characters **int cw\_get\_maximum\_representation\_length(void)**\ Brief: Get length of the longest representation of characters Function returns the string length of the longest representation in the main character lookup table. It is the count of dots and dashes in the longest representation of characters known to libcw (not including terminating NUL). Returns: length of the longest representation **int cw\_lookup\_character(char character, char \* representation)**\ Brief: Get representation of a given character The function is depreciated, use cw\_character\_to\_representation() instead. Return the string representation of a given character **character**. The routine returns CW\_SUCCESS on success, and fills in the string pointer (**representation**) passed in. On failure, it returns CW\_FAILURE and sets errno to ENOENT, indicating that the character **character** could not be found. The length of **representation** buffer must be at least one greater than the length of longest representation held in the character lookup table. The largest value of length is returned by cw\_get\_maximum\_representation\_length(). Parameter(in): character character to look up Parameter(out): representation pointer to space for representation of character Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **char \* cw\_character\_to\_representation(int character)**\ Brief: Get representation of a given character On success return representation of a given character. Returned pointer is owned by caller of the function. On failure function returns NULL and sets errno. ERRNO ENOENT the character could not be found. ERRNO ENOMEM character has been found, but function failed to strdup() representation. Parameter(in): character character to look up Returns: pointer to freshly allocated representation on success\ Returns: NULL on failure **int cw\_check\_representation(const char \* representation)**\ Brief: Check if representation of a character is valid This function is depreciated, use cw\_representation\_is\_valid() instead. Check that the given string is a valid Morse representation. A valid string is one composed of only "." and "-" characters. This means that the function checks only if representation is error-free, and not whether the representation represents existing/defined character. If representation is invalid, function returns CW\_FAILURE and sets errno to EINVAL. Parameter(in): representation representation of a character to check Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **bool cw\_representation\_is\_valid(const char \* representation)**\ Brief: Check if representation of a character is valid Check that the given string is a valid Morse representation. A valid string is one composed of only "." and "-" characters. This means that the function checks only if representation is error-free, and not whether the representation represents existing/defined character. ERRNO EINVAL representation is invalid Parameter(in): representation representation of a character to check Returns: true if representation is valid\ Returns: false if representation is invalid **int cw\_lookup\_representation(const char \* representation, char \* character)**\ Brief: Get the character represented by a given Morse representation This function is depreciated, use cw\_representation\_to\_character() instead. Function checks **representation**, and if it is valid and represents a known character, function returns CW\_SUCCESS. Additionally, if **character** is non-NULL, function puts the looked up character in **character**. **character** should be allocated by caller. Function assumes that **character** being NULL pointer is a valid situation, and can return CW\_SUCCESS in such situation. On error, function returns CW\_FAILURE. errno is set to EINVAL if any character of the representation is invalid, or ENOENT to indicate that the character represented by **representation** could not be found. Parameter(in): representation representation of a character to look up Parameter(out): character location where to put looked up character Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **int cw\_representation\_to\_character(const char \* representation)**\ Brief: Return the character represented by a given Morse representation Function checks **representation**, and if it is valid and represents a known character, function returns the character (a non-zero value). On error, function returns zero (character represented by **representation** was not found). ERRNO EINVAL **representation** contains invalid symbol (other than Dots and Dashes) ERRNO ENOENT a character represented by **representation** could not be found Parameter(in): representation representation of a character to look up Returns: non-zero character on success\ Returns: zero on failure **int cw\_get\_procedural\_character\_count(void)**\ Brief: Get number of procedural signals Returns: the number of characters stored in the procedural signal expansion lookup table **void cw\_list\_procedural\_characters(char \* list)**\ Brief: Get list of characters for which procedural expansion is available Function copies into preallocated buffer **list** a string containing all of the Morse characters for which procedural expansion is available. The length of **list** must be at least by one greater than the number of characters represented in the procedural signal expansion lookup table, returned by cw\_get\_procedural\_character\_count(). **list** buffer is allocated and managed by caller. Parameter(out): list buffer for returned string **int cw\_get\_maximum\_procedural\_expansion\_length(void)**\ Brief: Get length of the longest procedural expansion Function returns the string length of the longest expansion in the procedural signal expansion table. Returns: the string length of the longest expansion of procedural signals **int cw\_lookup\_procedural\_character(char character, char \*expansion, int \* is\_usually\_expanded)**\ Brief: Get the string expansion of a given Morse code procedural signal character On success the function @li fills **expansion** with the string expansion of a given Morse code procedural signal character **character**; @li sets **is\_usually\_expanded** to appropriate value as a display hint for the caller; @li returns CW\_SUCCESS. Both **expansion** and **expansion** must be allocated and managed by caller. They can be NULL, then the function won't attempt to use them. The length of **expansion** must be at least by one greater than the longest expansion held in the procedural signal character lookup table, as returned by cw\_get\_maximum\_procedural\_expansion\_length(). ERRNO ENOENT procedural signal character **character** cannot be found Parameter(in): character character to look up Parameter(out): expansion buffer to fill with expansion of the character Parameter(out): is\_usually\_expanded visual hint Returns: CW\_FAILURE on failure (character cannot be found)\ Returns: CW\_SUCCESS on success **int cw\_get\_maximum\_phonetic\_length(void)**\ Brief: Get length of a longest phonetic Returns: the string length of the longest phonetic in the phonetics lookup table **int cw\_lookup\_phonetic(char character, char \* phonetic)**\ Brief: Look up the phonetic of a given character On success the routine copies a phonetic corresponding to **character** into **phonetic**. **phonetic** is managed and owned by caller. It is NOT considered an error if **phonetic** is NULL. In such case the function will just verify if **character** can be represented by a phonetic, i.e. if **character** is a letter. If non-NULL, the size of **phonetic** must be greater by at least 1 than the longest phonetic held in the phonetic lookup table, as returned by cw\_get\_maximum\_phonetic\_length(). ERRNO ENOENT phonetic for given character cannot be found Parameter(in): character character to look up Parameter(out): phonetic buffer for phonetic of a character (may be NULL) Returns: CW\_SUCCESS on success (phonetic has been found and - if **phonetic** is non-NULL) has been copied to the buffer\ Returns: CW\_FAILURE on failure (phonetic for given character cannot be found) **bool cw\_character\_is\_valid(char character)**\ Brief: Check if given character is valid Check that a given character is valid, i.e. it is present in library's character-to-representation lookup table and can be represented with Dots and Dashes. Space character (' ') is also considered to be a valid character. ERRNO ENOENT on failure (character is invalid). Notice the difference in errno set by cw\_character\_is\_valid() (ENOENT) and cw\_string\_is\_valid() (EINVAL). This different behaviour goes way back to unixcw-2.3 and is preserved in new versions for backwards compatibility reasons. Parameter(in): character character to check Returns: true if character is valid\ Returns: false otherwise **int cw\_check\_character(char character)**\ **bool cw\_string\_is\_valid(const char \* string)**\ Brief: Check if all characters in given string are valid Check that each character in the given string is valid and can be converted by libcw to Morse code symbols sent as a Morse character. Space character (' ') is also considered to be a valid character. ERRNO EINVAL on failure (when an invalid character has been found in **string**). Notice the difference in errno set by cw\_character\_is\_valid() (ENOENT) and cw\_string\_is\_valid() (EINVAL). This different behaviour goes way back to unixcw-2.3 and is preserved in new versions for backwards compatibility reasons. Parameter(in): string string to check Returns: true if all characters in string are valid\ Returns: false otherwise **int cw\_check\_string(const char \* string)**\ **void cw\_set\_debug\_flags(uint32\_t flags)**\ Brief: Set a value of internal debug flags variable Assign specified value to library's internal debug flags variable. Note that this function doesn't \*append\* given flag to the variable, it erases existing value and assigns new one. Use cw\_get\_debug\_flags() if you want to OR new flag with existing ones. Parameter: flags new value of flags to be assigned to the debug object **void cw\_debug\_set\_flags(cw\_debug\_t \* debug\_object, uint32\_t flags)**\ Brief: Set a value of debug flags in given debug variable Assign specified value to given debug variable. Note that this function doesn't \*append\* given flag to the variable, it erases existing value and assigns new one. Use cw\_debug\_get\_flags() if you want to OR new flag with existing ones. Parameter(in): debug\_object debug object for which to set flags Parameter(in): flags new value to be assigned to the object, a sum of one or more of CW\_DEBUG\_\* flags from libcw.h **uint32\_t cw\_get\_debug\_flags(void)**\ Brief: Get library's current debug flags Function returns value of library's internal debug variable, a sum of one or more of CW\_DEBUG\_\* flags from libcw.h. Returns: value of library's debug flags variable **uint32\_t cw\_debug\_get\_flags(const cw\_debug\_t \* debug\_object)**\ Brief: Get current debug flags from given debug object Function returns value of debug object's debug flags, a sum of one or more of CW\_DEBUG\_\* flags from libcw.h. Returns: value of debug object's debug flags **bool cw\_debug\_has\_flag(const cw\_debug\_t \* debug\_object, uint32\_t flag)**\ Brief: Check if given debug flag is set Function checks if a specified debug flag is set in given debug object. Parameter(in): debug\_object debug object to be checked Parameter(in): flag flag to be checked, one of CW\_DEBUG\_\* flags from libcw.h Returns: true if given flag is set\ Returns: false otherwise **int cw\_generator\_set\_tone\_slope(cw\_gen\_t \* gen, int slope\_shape, int slope\_duration)**\ Brief: Set parameters describing slopes of tones generated by generator Most of variables related to slope of tones is in **tone**, but there are still some variables that are generator-specific, as they are common for all tones. This function sets two of these generator-specific variables. A: If you pass to function conflicting values of **slope\_shape** and **slope\_duration**, the function will return CW\_FAILURE. These conflicting values are rectangular slope shape and larger than zero slope length. You just can't have rectangular slopes that have non-zero length. B: If you pass to function '-1' as value of both **slope\_shape** and **slope\_duration**, the function won't change any of the related two generator's parameters. C1: If you pass to function '-1' as value of either **slope\_shape** or **slope\_duration**, the function will attempt to set only this generator's parameter that is different than '-1'. C2: However, if selected slope shape is rectangular, function will set generator's slope length to zero, even if value of slope\_duration is '-1'. D: Notice that the function allows non-rectangular slope shape with zero length of the slopes. The slopes will be non-rectangular, but just unusually short. The function should be called every time one of following parameters change: @li shape of slope, @li duration of slope, @li generator's sample rate, @li generator's volume. There are four supported shapes of slopes: @li linear (the only one supported by libcw until version 4.1.1), @li raised cosine (supposedly the most desired shape), @li sine, @li rectangular. Use CW\_TONE\_SLOPE\_SHAPE\_\* symbolic names as values of **slope\_shape**. FIXME: first argument of this public function is gen, but no function provides access to generator variable. Parameter(in): gen generator for which to set tone slope parameters Parameter(in): slope\_shape shape of slope: linear, raised cosine, sine, rectangular Parameter(in): slope\_duration duration of slope \[microseconds\] Returns: CW\_SUCCESS on success\ Returns: CW\_FAILURE on failure **bool cw\_is\_null\_possible(\_\_attribute\_\_((unused)) const char \* device\_name)**\ Brief: Check if it is possible to open Null sound output Parameter(in): device\_name name of Null device to be used. Value is ignored for Null sound system. Returns: true it's always possible to write to Null device **bool cw\_is\_oss\_possible(const char \* device\_name)**\ Brief: Check if it is possible to open OSS output with given device name Function does a test opening and test configuration of OSS output, but it closes it before returning. Parameter(in): device\_name name of OSS device to be used; if NULL or empty then the function will use library-default device name. Returns: true if opening OSS output succeeded\ Returns: false if opening OSS output failed **bool cw\_is\_pa\_possible(const char \* device\_name)**\ Brief: Check if it is possible to open PulseAudio output with given device name Function first tries to load PulseAudio library, and then does a test opening of PulseAudio output, but it closes it before returning. Parameter(in): device\_name name of PulseAudio device to be used; if NULL then the function will use library-default device name. Returns: true if opening PulseAudio output succeeded\ Returns: false if opening PulseAudio output failed **void cw\_block\_callback(int block)**\ Brief: Block the callback from being called Function blocks the callback from being called for a critical section of caller code if **block** is true, and unblocks the callback if **block** is false. Function works by blocking SIGALRM; a block should always be matched by an unblock, otherwise the tone queue will suspend forever. Parameter: block - pass 1 to block SIGALRM, and 0 to unblock it **int cw\_register\_signal\_handler(int signal\_number, void (\*callback\_func)(int))**\ Brief: Register a signal handler and optional callback function for given signal number On receipt of that signal, all library features will be reset to their default states. Following the reset, if **callback\_func** is a function pointer, the function is called; if it is SIG\_DFL, the library calls exit(); and if it is SIG\_IGN, the library returns from the signal handler. This is a convenience function for clients that need to clean up library on signals, with either exit, continue, or an additional function call; in effect, a wrapper round a restricted form of sigaction. The **signal\_number** argument indicates which signal to catch. On problems errno is set to EINVAL if **signal\_number** is invalid or if a handler is already installed for that signal, or to the sigaction error code. Parameter: signal\_number\ Parameter: callback\_func Returns: CW\_SUCCESS - if the signal handler installs correctly\ Returns: CW\_FAILURE - on errors or problems **int cw\_unregister\_signal\_handler(int signal\_number)**\ Brief: Unregister a signal handler interception Function removes a signal handler interception previously registered with cw\_register\_signal\_handler(). Parameter: signal\_number Returns: true if the signal handler uninstalls correctly\ Returns: false otherwise (with errno set to EINVAL or to the sigaction error code) **int cw\_version(void)**\ Brief: Return version number of libcw library Return the version number of the library. Version numbers (major and minor) are returned as an int, composed of major\_version \<\< 16 \| minor\_version. Returns: library's major and minor version number encoded as single int **void cw\_license(void)**\ Brief: Print libcw's license text to stdout Function prints to stdout information about libcw version, followed by short text presenting libcw's copyright and license notice. **const char \* cw\_get\_audio\_system\_label(int sound\_system)**\ Brief: Get a readable label of given sound system The function returns one of following strings: None, Null, Console, OSS, ALSA, PulseAudio, Soundcard Returned pointer is owned and managed by the library. \*const cw\_get\_audio\_system\_label(...)"? Parameter(in): sound\_system ID of sound system Returns: sound system's label **void cw\_get\_speed\_limits(int \* min\_speed, int \* max\_speed)**\ Brief: Get speed limits Get (through function's arguments) limits on speed of Morse code that are supported by libcw. See CW\_SPEED\_MIN and CW\_SPEED\_MAX in libcw.h for values. Any of functions two arguments can be NULL - function won't update value of that argument. Parameter(out): min\_speed minimal allowed speed Parameter(out): max\_speed maximal allowed speed **void cw\_get\_frequency\_limits(int \* min\_frequency, int \* max\_frequency)**\ Brief: Get frequency limits Get (through function's arguments) limits on frequency that are supported by libcw. See CW\_FREQUENCY\_MIN and CW\_FREQUENCY\_MAX in libcw.h for values. Any of functions two arguments can be NULL - function won't update value of that argument. Parameter(out): min\_frequency minimal allowed frequency Parameter(out): max\_frequency maximal allowed frequency **void cw\_get\_volume\_limits(int \* min\_volume, int \* max\_volume)**\ Brief: Get volume limits Get (through function's arguments) limits on volume of sound supported by libcw and generated by generator. See CW\_VOLUME\_MIN and CW\_VOLUME\_MAX in libcw.h for values. Any of functions two arguments can be NULL - function won't update value of that argument. Parameter(out): min\_volume minimal allowed volume Parameter(out): max\_volume maximal allowed volume **void cw\_get\_gap\_limits(int \* min\_gap, int \* max\_gap)**\ Brief: Get gap limits Get (through function's arguments) limits on gap in cw signal supported by libcw. See CW\_GAP\_MIN and CW\_GAP\_MAX in libcw.h for values. Any of functions two arguments can be NULL - function won't update value of that argument. Parameter(out): min\_gap minimal allowed gap Parameter(out): max\_gap maximal allowed gap **void cw\_get\_tolerance\_limits(int \* min\_tolerance, int \* max\_tolerance)**\ Brief: Get tolerance limits Get (through function's arguments) limits on "tolerance" parameter supported by libcw. See CW\_TOLERANCE\_MIN and CW\_TOLERANCE\_MAX in libcw.h for values. Any of functions two arguments can be NULL - function won't update value of that argument. Parameter(out): min\_tolerance minimal allowed tolerance Parameter(out): max\_tolerance maximal allowed tolerance **void cw\_get\_weighting\_limits(int \* min\_weighting, int \* max\_weighting)**\ Brief: Get weighting limits Get (through function's arguments) limits on "weighting" parameter supported by libcw. See CW\_WEIGHTING\_MIN and CW\_WEIGHTING\_MAX in libcw.h for values. Any of functions two arguments can be NULL - function won't update value of that argument. Parameter(out): min\_weighting minimal allowed weighting Parameter(out): max\_weighting maximal allowed weighting **void cw\_complete\_reset(void)**\ Brief: Reset all library features to their default states Clears the tone queue, receive buffers and retained state information, any current keyer activity, and any straight key activity, returns to silence, and closes soundcard and console devices. This function is suitable for calling from an application exit handler. ## NOTES Despite the fact that this manual page constantly and consistently refers to Morse code elements as dots and dashes, DO NOT think in these terms when trying to learn Morse code. Always think of them as 'dit's and 'dah's. **libcw** uses system itimers for its internal timing. On most UNIX flavours, itimers are not guaranteed to signal a program exactly at the specified time, and they generally offer a resolution only as good as the normal system 'clock tick' resolution. An itimer SIGALRM usually falls on a system clock tick, making it accurate to no better than 10mS on a typical 100Hz kernel. The effect of this is that an itimer period is generally either exactly as specified, or, more likely, slightly longer. At higher WPM settings, the cumulative effect of this affects timing accuracy, because at higher speeds, there are fewer 10mS clock ticks in a dot period. For example, at 12 WPM, the dot length is 100mS, enough to contain five kernel clock ticks; at 60 WPM, the dot length is 20mS, or just two kernel clock ticks. So at higher speeds, the effect of itimer resolutions becomes more pronounced. ## SEE ALSO Man pages for **cw**(7,LOCAL), **cw**(1,LOCAL), **cwgen**(1,LOCAL), **cwcp**(1,LOCAL), and **xcwcp**(1,LOCAL).