This file is indexed.

/usr/include/libcw.h is in libcw6-dev 3.4.2-1build1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
/*
 * Copyright (C) 2001-2006  Simon Baldwin (simon_baldwin@yahoo.com)
 * Copyright (C) 2011-2015  Kamil Ignacak (acerion@wp.pl)
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef _LIBCW_H
#define _LIBCW_H

#include <sys/time.h>  /* For struct timeval */

#include <stdint.h>    /* int16_t */
#include <pthread.h>
#include <stdbool.h>


static const int        CW_AUDIO_CHANNELS = 1;                /* Sound in mono */


#if defined(__cplusplus)
extern "C"
{
#endif


enum cw_return_values {
	CW_FAILURE = false,
	CW_SUCCESS = true };

/* supported audio sound systems */
enum cw_audio_systems {
	CW_AUDIO_NONE = 0,  /* initial value; this is not the same as CW_AUDIO_NULL */
	CW_AUDIO_NULL,      /* empty audio output (no sound, just timing); this is not the same as CW_AUDIO_NONE */
	CW_AUDIO_CONSOLE,   /* console buzzer */
	CW_AUDIO_OSS,
	CW_AUDIO_ALSA,
	CW_AUDIO_PA,        /* PulseAudio */
	CW_AUDIO_SOUNDCARD  /* OSS, ALSA or PulseAudio (PA) */
};

enum {
	CW_KEY_STATE_OPEN = 0,  /* key is open, no electrical contact in key, no sound */
	CW_KEY_STATE_CLOSED     /* key is closed, there is an electrical contact in key, a sound is generated */
};


typedef int16_t cw_sample_t;



/* Default outputs for audio systems. Used by libcw unless
   client code decides otherwise. */
#define CW_DEFAULT_NULL_DEVICE      ""
#define CW_DEFAULT_CONSOLE_DEVICE   "/dev/console"
#define CW_DEFAULT_OSS_DEVICE       "/dev/audio"
#define CW_DEFAULT_ALSA_DEVICE      "default"
#define CW_DEFAULT_PA_DEVICE        "( default )"


/* Limits on values of CW send and timing parameters */
#define CW_SPEED_MIN             4   /* Lowest WPM allowed */
#define CW_SPEED_MAX            60   /* Highest WPM allowed */
#define CW_SPEED_STEP            1
#define CW_SPEED_INITIAL        12   /* Initial send speed in WPM */
#define CW_FREQUENCY_MIN         0   /* Lowest tone allowed (0=silent) */
#define CW_FREQUENCY_MAX      4000   /* Highest tone allowed */
#define CW_FREQUENCY_INITIAL   800   /* Initial tone in Hz */
#define CW_FREQUENCY_STEP       20
#define CW_VOLUME_MIN            0   /* Quietest volume allowed (0=silent) */
#define CW_VOLUME_MAX          100   /* Loudest volume allowed */
#define CW_VOLUME_INITIAL       70   /* Initial volume percent */
#define CW_VOLUME_STEP           1
#define CW_GAP_MIN               0   /* Lowest extra gap allowed */
#define CW_GAP_MAX              60   /* Highest extra gap allowed */
#define CW_GAP_INITIAL           0   /* Initial gap setting */
#define CW_GAP_STEP              1
#define CW_WEIGHTING_MIN        20   /* Lowest weighting allowed */
#define CW_WEIGHTING_MAX        80   /* Highest weighting allowed */
#define CW_WEIGHTING_INITIAL    50   /* Initial weighting setting */
#define CW_TOLERANCE_MIN         0   /* Lowest receive tolerance allowed */
#define CW_TOLERANCE_MAX        90   /* Highest receive tolerance allowed */
#define CW_TOLERANCE_INITIAL    50   /* Initial tolerance setting */


/*
 * Representation characters for Dot and Dash.  Only the following
 * characters are permitted in Morse representation strings.
 */
enum { CW_DOT_REPRESENTATION = '.', CW_DASH_REPRESENTATION = '-' };



/* Debugging support. */

/* Definitions of debug flags. */
enum {
	/* Suppress KIOCSOUND ioctls.
	   The flag is unused at the moment in libcw.c. */
	CW_DEBUG_SILENT               = 1 << 0,

	/* Print out keying control data (key open / key closed). */
	CW_DEBUG_KEYING               = 1 << 1,

	/* Print out information related to main object generating
	   audio (i.e. the generator). */
	CW_DEBUG_GENERATOR            = 1 << 2,

	/* Print out tone queue data. */
	CW_DEBUG_TONE_QUEUE           = 1 << 3,

	/* Print out send and receive timing parameters. */
	CW_DEBUG_PARAMETERS           = 1 << 4,

	/* Print out changes of 'receive state'. */
	CW_DEBUG_RECEIVE_STATES       = 1 << 5,

	/* Print out iambic keyer information. */
	CW_DEBUG_KEYER_STATES         = 1 << 6,

	/* Print out straight key information. */
	CW_DEBUG_STRAIGHT_KEY_STATES  = 1 << 7,

	/* Print out table lookup results. */
	CW_DEBUG_LOOKUPS              = 1 << 8,

	/* Print out finalization actions. */
	CW_DEBUG_FINALIZATION         = 1 << 9,

	/* Print out information related to calls to standard library
	   functions.  This does not include calls that are directly
	   related to configuring audio devices (e.g. calling open()
	   to open OSS device).

	   Printing debug information about problems with malloc()
	   seems to be most common use case for this flag. */
	CW_DEBUG_STDLIB               = 1 << 10,

	/* Print out any events directly related to sound systems: to
	   opening audio device, configuring it, writing to it, and
	   closing it.  In case of e.g. OSS sound system, this may
	   also include information about libc's open(), write() and
	   ioctl() calls, as they are directly related to
	   opening/configuring/writing to audio device. */
	CW_DEBUG_SOUND_SYSTEM         = 1 << 11,

	/* Print out information related to internal states / errors /
	   inconsistencies of libcw library. */
	CW_DEBUG_INTERNAL             = 1 << 12,

	/* Bit mask of all defined debug bits. */
	CW_DEBUG_MASK                 = (1 << 13) - 1
};



/* Debug levels of debug messages. */
enum {
	CW_DEBUG_DEBUG   = 0,
	CW_DEBUG_INFO    = 1,
	CW_DEBUG_WARNING = 2,
	CW_DEBUG_ERROR   = 3,
	CW_DEBUG_NONE    = 4  /* Don't print any debug info. */
};




/* Values deciding the shape of slopes of tones generated by
   generator.

   If a generated tone is declared to have one or two slopes,
   generator has to know what shape of the slope(s) should be. Since
   the shape of tones is common for all tones generated by generator,
   shape of tone is a property of generator rather than of tone.

   These names are to be used as values of argument 'slope_shape' of
   cw_generator_set_tone_slope() function.  */
enum {
	CW_TONE_SLOPE_SHAPE_LINEAR,          /* Ramp/linearly raising slope. */
	CW_TONE_SLOPE_SHAPE_RAISED_COSINE,   /* Shape of cosine function in range <-pi - zero).  */
	CW_TONE_SLOPE_SHAPE_SINE,            /* Shape of sine function in range <zero - pi/2). */
	CW_TONE_SLOPE_SHAPE_RECTANGULAR      /* Slope changes from zero for sample n, to full amplitude of tone in sample n+1. */
};

typedef struct cw_gen_struct cw_gen_t;


/* Functions handling library meta data */
extern int  cw_version(void);
extern void cw_license(void);
extern const char *cw_get_audio_system_label(int audio_system);



/* Functions handling 'generator' */
extern int  cw_generator_new(int audio_system, const char *device);
extern void cw_generator_delete(void);
extern int  cw_generator_start(void);
extern void cw_generator_stop(void);
extern const char *cw_generator_get_audio_system_label(void);
/* FIXME: first argument of the function is gen, but no function provides access to generator variable. */
extern int  cw_generator_set_tone_slope(cw_gen_t *gen, int slope_shape, int slope_usecs);

/* Core Morse code data and lookup */
extern int   cw_get_character_count(void);
extern void  cw_list_characters(char *list);
extern int   cw_get_maximum_representation_length(void);
extern char *cw_character_to_representation(int c);
extern bool  cw_representation_is_valid(const char *representation);
extern int   cw_representation_to_character(const char *representation);


/* Extended Morse code data and lookup (procedural signals) */
extern int cw_get_procedural_character_count(void);
extern void cw_list_procedural_characters(char *list);
extern int cw_get_maximum_procedural_expansion_length(void);

extern int cw_lookup_procedural_character (char c, char *representation,
                                           int *is_usually_expanded);


/* Phonetic alphabet */
extern int cw_get_maximum_phonetic_length(void);
extern int cw_lookup_phonetic(char c, char *phonetic);


/* Morse code controls and timing parameters */
extern void cw_get_speed_limits(int *min_speed, int *max_speed);
extern void cw_get_frequency_limits(int *min_frequency, int *max_frequency);
extern void cw_get_volume_limits(int *min_volume, int *max_volume);
extern void cw_get_gap_limits(int *min_gap, int *max_gap);
extern void cw_get_tolerance_limits(int *min_tolerance, int *max_tolerance);
extern void cw_get_weighting_limits(int *min_weighting, int *max_weighting);
extern void cw_reset_send_receive_parameters(void);
extern int cw_set_send_speed(int new_value);
extern int cw_set_receive_speed(int new_value);
extern int cw_set_frequency(int new_value);
extern int cw_set_volume(int new_value);
extern int cw_set_gap(int new_value);
extern int cw_set_tolerance(int new_value);
extern int cw_set_weighting(int new_value);
extern int cw_get_send_speed(void);
extern int cw_get_receive_speed(void);
extern int cw_get_frequency(void);
extern int cw_get_volume(void);
extern int cw_get_gap(void);
extern int cw_get_tolerance(void);
extern int cw_get_weighting(void);
extern 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);
extern 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);
extern int cw_set_noise_spike_threshold(int new_value);
extern int cw_get_noise_spike_threshold(void);


extern void cw_block_callback(int block);


/* General control of console buzzer and of soundcard */
extern const char *cw_get_console_device(void);
extern const char *cw_get_soundcard_device(void);


extern bool cw_is_null_possible(const char *device);
extern bool cw_is_console_possible(const char *device);
extern bool cw_is_oss_possible(const char *device);
extern bool cw_is_alsa_possible(const char *device);
extern bool cw_is_pa_possible(const char *device);




/* Finalization and cleanup */
extern void cw_complete_reset(void);
extern int  cw_register_signal_handler(int signal_number,
				       void (*callback_func)(int));
extern int  cw_unregister_signal_handler(int signal_number);




/* Keying control */
extern void cw_register_keying_callback(void (*callback_func)(void*, int),
					void *callback_arg);
extern void cw_iambic_keyer_register_timer(struct timeval *timer);


/* Tone queue */
extern int cw_register_tone_queue_low_callback(void (*callback_func) (void*),
                                                void *callback_arg, int level);
extern bool cw_is_tone_busy(void);
extern int  cw_wait_for_tone(void);
extern int  cw_wait_for_tone_queue(void);
extern int  cw_wait_for_tone_queue_critical(int level);
extern bool cw_is_tone_queue_full(void);
extern int  cw_get_tone_queue_capacity(void);
extern int  cw_get_tone_queue_length(void);
extern void cw_flush_tone_queue(void);
extern int  cw_queue_tone(int usecs, int frequency);
extern void cw_reset_tone_queue(void);



/* Sending */
extern int cw_send_dot(void);
extern int cw_send_dash(void);
extern int cw_send_character_space(void);
extern int cw_send_word_space(void);
extern int cw_send_representation(const char *representation);
extern int cw_send_representation_partial(const char *representation);
extern int cw_send_character(char c);
extern int cw_send_character_partial(char c);
extern int cw_send_string(const char *string);

extern bool cw_character_is_valid(char c);
extern bool cw_string_is_valid(const char *string);



/* Receive tracking and statistics helpers */
extern void cw_get_receive_statistics(double *dot_sd, double *dash_sd,
                                       double *element_end_sd,
                                       double *character_end_sd);
extern void cw_reset_receive_statistics(void);


/* Receiving */
extern void cw_enable_adaptive_receive(void);
extern void cw_disable_adaptive_receive(void);
extern bool cw_get_adaptive_receive_state(void);
extern int cw_start_receive_tone(const struct timeval *timestamp);
extern int cw_end_receive_tone(const struct timeval *timestamp);

/* If I'm reading xcwcp/receiver.cc correctly then currently libcw
   implements polling interface to receiver code. Client code must
   periodically poll libcw to see if there is a new character or space
   in receiver's representation buffer. These four functions below are
   the main part of "polling".

   TODO: implement alternative way of accessing receiver's
   representation buffer (or maybe sharing the buffer's content by
   receiver). Some kind of scheme where receiver informs client code
   about the fact that the receiver ended receiving marks/spaces and
   recognized full character or space. Some kind of notification to
   the client code, or calling client's callback function. */
extern int cw_receive_buffer_dot(const struct timeval *timestamp);
extern int cw_receive_buffer_dash(const struct timeval *timestamp);
extern int cw_receive_representation(const struct timeval *timestamp,
				     char *representation,
				     bool *is_end_of_word, bool *is_error);
extern int cw_receive_character(const struct timeval *timestamp,
                                 char *c, bool *is_end_of_word, bool *is_error);
/* It seems that this function is a part of the polling interface as
   well. It is called by client code in xcwcp/receiver.cc after
   passing recognized character from receiver to client code. It makes
   space in the receiver's buffer for next character. */
extern void cw_clear_receive_buffer(void);

extern int cw_get_receive_buffer_capacity(void);
extern int cw_get_receive_buffer_length(void);
extern void cw_reset_receive(void);


/* Iambic keyer */
extern void cw_enable_iambic_curtis_mode_b(void);
extern void cw_disable_iambic_curtis_mode_b(void);
extern int cw_get_iambic_curtis_mode_b_state(void);

extern int cw_notify_keyer_paddle_event(int dot_paddle_state,
					int dash_paddle_state);
extern int cw_notify_keyer_dot_paddle_event(int dot_paddle_state);
extern int cw_notify_keyer_dash_paddle_event(int dash_paddle_state);
extern void cw_get_keyer_paddles(int *dot_paddle_state,
				 int *dash_paddle_state);
extern void cw_get_keyer_paddle_latches(int *dot_paddle_latch_state,
					int *dash_paddle_latch_state);
extern bool cw_is_keyer_busy(void);
extern int cw_wait_for_keyer_element(void);
extern int cw_wait_for_keyer(void);
extern void cw_reset_keyer(void);


/* Straight key */
extern int cw_notify_straight_key_event(int key_state);
extern int cw_get_straight_key_state(void);
extern bool cw_is_straight_key_busy(void);
extern void cw_reset_straight_key(void);




/* deprecated functions */
extern int cw_check_representation(const char *representation)           __attribute__ ((deprecated));   /* Use cw_representation_is_valid(). */
extern int cw_lookup_representation(const char *representation, char *c) __attribute__ ((deprecated));   /* Use cw_representation_to_character(). */
extern int cw_lookup_character(char c, char *representation)             __attribute__ ((deprecated));   /* Use cw_character_to_representation(). */
extern int cw_check_character(char c)                                    __attribute__ ((deprecated));   /* Use cw_character_is_valid(). */
extern int cw_check_string(const char *string)                           __attribute__ ((deprecated));   /* Use cw_string_is_valid(). */


#if defined(__cplusplus)
}
#endif
#endif  /* _LIBCW_H */