Asterisk - The Open Source Telephony Project  GIT-master-a24979a
utils/frame.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Programs for processing sound files in raw- or WAV-format.
4  * -- Useful functions for parsing command line options and
5  * issuing errors, warnings, and chit chat.
6  *
7  * Name: frame.h
8  * Version: see frame.c
9  * Author: Mark Roberts <mark@manumark.de>
10  *
11  ****************************************************************************/
12 /****************************************************************************
13  * These are useful functions that all DSP programs might find handy
14  ****************************************************************************/
15 
16 /* fileswitch for parseargs:
17 
18  The following are masks for several different ways of opening files.
19  --------------------------------------------------------------------
20  Bit 0: Open infile?
21  Bit 1: Open infile as binary (as opposed to text)
22  Bit 2: Open outfile?
23  Bit 3: Open outfile as binary (as opposed to text)
24  Bit 4: Do not complain about too many file arguments
25  Bit 5: Open one file for input AND output, binary.
26 */
27 #define INTEXT (1+0)
28 #define INBIN (1+2)
29 #define OUTTEXT (4)
30 #define OUTBIN (4+8)
31 #define NOFILES (0)
32 #define NOCOMPLAIN (16)
33 #define IOBIN (32)
34 
35 #ifndef FALSE
36  #define FALSE (0==1)
37  #define TRUE (0==0)
38 #endif
39 
40 extern int samplefrequency;
41 extern unsigned short samplewidth;
42 extern unsigned short channels;
43 extern int wavout; /* TRUE iff out file is .WAV file */
44 extern int iswav; /* TRUE iff in file was found to be a .WAV file */
45 extern FILE *in, *out;
46 extern char *infilename, *outfilename;
47 extern int verboselevel;
48 extern char *version; /* String to be issued as version string. Should
49  be set by application. */
50 extern char *usage; /* String to be issued as usage string. Should be
51  set by application. */
52 
53 #define DEFAULTFREQ 44100
54 #define BUFFSIZE 50000 /* How many samples to read in one go (preferred) */
55 #define MINBUFFSIZE 5000 /* How many samples to read in one go (minimum) */
56 
57 /*************************************************
58  * Types of errors handled by argerrornum() *
59  *************************************************/
60 typedef enum
61 {
78 
79 
80 /* -----------------------------------------------------------------------
81  Create memory and copy 'string', returning a pointer to the copy.
82  NULL is returned if malloc fails.
83  -----------------------------------------------------------------------*/
84 extern char *malloccopy( char *string);
85 
86 /* -----------------------------------------------------------------------
87  Start the stopwatch and make sure the user is informed at end of program.
88  -----------------------------------------------------------------------*/
89 extern void startstopwatch(void);
90 
91 /* -----------------------------------------------------------------------
92  Writes the number of samples to result that are yet to be read from anyin.
93  I.e. the number of remaining bytes is divided by the number of bytes per
94  sample value, but not by the number of channels.
95  Return values are TRUE on success, FALSE on failure.
96  -----------------------------------------------------------------------*/
97 extern int getremainingfilelength( FILE *anyin, long *result);
98 
99 /* -----------------------------------------------------------------------
100  Read a .pk-header from 'anyin' and printf the entries.
101  -----------------------------------------------------------------------*/
102 void readpkheader( FILE *anyin);
103 
104 /* -----------------------------------------------------------------------
105  Read a .WAV header from 'anyin'.
106  If it is recognised, the data is used.
107  Otherwise, we assume it's PCM-data and ignore the header.
108  The global variable 'iswav' is set on success, otherwise cleared.
109  -----------------------------------------------------------------------*/
110 extern void readwavheader( FILE *anyin);
111 
112 /* -----------------------------------------------------------------------
113  Write a .WAV header to 'out'.
114  The filepointer is placed at the end of 'out' before operation.
115  This should be called before any data is
116  written, and again, when ALL the data has been written.
117  First time, this positions the file pointer correctly; second time, the
118  missing data can be inserted that wasn't known the first time round.
119  -----------------------------------------------------------------------*/
120 extern void makewavheader( void);
121 
122 /* --------------------------------------------------------------------
123  Tests the character 'coal' for being a command line option character,
124  momentarily '/' or '-'.
125  -------------------------------------------------------------------- */
126 extern int isoptionchar (char coal);
127 
128 /* -----------------------------------------------------------------------
129  Reads through the arguments on the lookout for an option starting
130  with 'string'. The rest of the option is read as a time and passed
131  to *result, where the result is meant to mean 'number of samples' in
132  that time.
133  On failure, *result is unchanged.
134  return value is TRUE on success, FALSE otherwise.
135  -----------------------------------------------------------------------*/
136 extern int parsetimearg( int argcount, char *args[], char *string,
137  int *result);
138 
139 /* -----------------------------------------------------------------------
140  The string argument is read as a time and passed to *result, where
141  the result is meant to mean 'number of samples' in that time. On
142  failure, *result is unchanged.
143  return value is TRUE on success, FALSE otherwise.
144  -----------------------------------------------------------------------*/
145 int parsetime(char *string, int *result);
146 
147 /* -----------------------------------------------------------------------
148  The string argument is read as a frequency and passed
149  to *result, where the result is meant to mean 'number of samples' in
150  one cycle of that frequency.
151  On failure, *result is unchanged.
152  return value is TRUE on success, FALSE otherwise.
153  -----------------------------------------------------------------------*/
154 int parsefreq(char *string, double *result);
155 
156 /* --------------------------------------------------------------------
157  Reads through the arguments on the lookout for a switch -'string'.
158  return value is TRUE if one exists, FALSE otherwise.
159  If characters remain after the switch, a fatal error is issued.
160  -------------------------------------------------------------------- */
161 extern int parseswitcharg( int argcount, char *args[], char *string);
162 
163 /* --------------------------------------------------------------------
164  Reads through the arguments on the lookout for an option starting
165  with 'string'. The rest of the option is read as an integer and
166  passed to &result.
167  On failure, &result is unchanged.
168  return value is TRUE on success, FALSE otherwise.
169  -------------------------------------------------------------------- */
170 extern int parseintarg( int argcount, char *args[], char *string,
171  int *result);
172 
173 /* --------------------------------------------------------------------
174  Reads through the arguments on the lookout for a filename, i.e. anything
175  that does not start with the optionchar. The filename is copied to
176  newly allocated memory, a pointer to which is returned.
177  The argument is marked as used. Therefore repeated use of this function
178  will yield a complete list of filenames on the command-line.
179  If malloc() fails, the function does not return.
180  -------------------------------------------------------------------- */
181 extern char *parsefilearg( int argcount, char *args[]);
182 
183 /* --------------------------------------------------------------------
184  Reads through the arguments on the lookout for an option starting
185  with 'string'. The rest of the option is read as a double and
186  passed to *result.
187  On failure, *result is unchanged.
188  return value is TRUE on success, FALSE otherwise.
189  -------------------------------------------------------------------- */
190 extern int parsedoublearg( int argcount, char *args[], char *string,
191  double *result);
192 
193 /* --------------------------------------------------------------------
194  Reads through the arguments on the lookout for an option starting
195  with 'string'. The rest of the option is read as a volume, i.e.
196  absolute, percent or db. The result is passed to *result.
197  On failure, *result is unchanged.
198  -------------------------------------------------------------------- */
199 extern int parsevolarg( int argcount, char *args[], char *string,
200  double *result);
201 
202 /* --------------------------------------------------------------------
203  Reads the specified string and interprets it as a volume. The string
204  would be of the form 1.8 or 180% or 5db.
205  On success, the return value is the relative volume, i.e. 1.8
206  On failure, -1 is returned.
207  -------------------------------------------------------------------- */
208 extern int parsevolume(char *s, double *result);
209 
210 /* --------------------------------------------------------------------
211  Reads through the arguments on the lookout for a switch -'string'.
212  return value is TRUE if one exists, FALSE otherwise.
213  If characters remain after the switch, a fatal error is issued.
214  -------------------------------------------------------------------- */
215 extern int parseswitch( char *found, char *wanted);
216 
217 /* --------------------------------------------------------------------
218  Reports an error due to parsing the string 's' encountered on the
219  command line.
220  -------------------------------------------------------------------- */
221 extern void argerror(char *s);
222 
223 /* --------------------------------------------------------------------
224  Reports an error due to parsing the string 's' encountered on the
225  command line. 'code' indicates the type of error.
226  -------------------------------------------------------------------- */
227 extern void argerrornum(char *s, Errornum code);
228 
229 /* --------------------------------------------------------------------
230  Reports an error due to parsing the string 's' encountered on the
231  command line. 'message' explains the type of error.
232  -------------------------------------------------------------------- */
233 extern void argerrortxt(char *s, char *message);
234 
235 /* --------------------------------------------------------------------
236  Check for any remaining arguments and complain about their existence.
237  If arguments are found, this function does not return.
238  -------------------------------------------------------------------- */
239 extern void checknoargs( int argcount, char *args[]);
240 
241 /* --------------------------------------------------------------------
242  Parses the command line arguments as represented by the function
243  arguments. Sets the global variables 'in', 'out', 'samplefrequency'
244  and 'samplewidth' accordingly.
245  According to 'fileswitch', in and out files are opened or not. See
246  above for an explanation of 'fileswitch'.
247  -------------------------------------------------------------------- */
248 extern void parseargs( int argcount, char *args[], int fileswitch);
249 
250 /* --------------------------------------------------------------------
251  Returns the index 'i' of the first argument that IS an option, and
252  which begins with the label 's'. If there is none, -1.
253  We also mark that option as done with, i.e. we cross it out.
254  -------------------------------------------------------------------- */
255 extern int findoption( int argcount, char *args[], char *s);
256 
257 /* --------------------------------------------------------------------
258  Finishes off the .WAV header (if any) and exits correctly and formerly.
259  -------------------------------------------------------------------- */
260 extern int myexit (int value);
261 
262 /* --------------------------------------------------------------------
263  Reads the stated input file bufferwise, calls the function 'work'
264  with the proper values, and writes the result to the stated output file.
265  Return value: TRUE on success, FALSE otherwise.
266  -------------------------------------------------------------------- */
267 extern int workloop( FILE *theinfile, FILE *theoutfile,
268  int (*work)( short *buffer, int length) );
269 
270 /* --------------------------------------------------------------------
271  Five functions for printing to stderr. Depending on the level of verbose,
272  output may be supressed. fatalerror() is like error() but does not return.
273  fatalperror() is like the standard function perror() but does not return.
274  -------------------------------------------------------------------- */
275 extern int chat( const char *format, ...);
276 extern int inform( const char *format, ...);
277 extern int error( const char *format, ...);
278 extern void fatalerror( const char *format, ...);
279 extern void fatalperror( const char *string);
280 
281 /* --------------------------------------------------------------------
282  And one functions for printing to stdout.
283  -------------------------------------------------------------------- */
284 extern int say( const char *format, ...);
285 
286 /* --------------------------------------------------------------------
287  Allocate memory for it and return a pointer to a string made up of
288  the two argument strings.
289  -------------------------------------------------------------------- */
290 extern char *mallocconcat( char *one, char *two);
291 
292 /* --------------------------------------------------------------------
293  Convert a sample value to decibel.
294  -------------------------------------------------------------------- */
295 extern double double2db( double value);
296 
297 /* --------------------------------------------------------------------
298  Read 'size' samples from file 'in' and lose them.
299  -------------------------------------------------------------------- */
300 extern void readawaysamples( FILE *in, size_t size);
static PGresult * result
Definition: cel_pgsql.c:84
static snd_pcm_format_t format
Definition: chan_alsa.c:106
int value
Definition: syslog.c:37
const char * args
char * mallocconcat(char *one, char *two)
Definition: utils/frame.c:1049
double double2db(double value)
Definition: utils/frame.c:1062
int verboselevel
Definition: utils/frame.c:35
void argerrornum(char *s, Errornum code)
Definition: utils/frame.c:635
void fatalperror(const char *string)
Definition: utils/frame.c:1020
int myexit(int value)
Definition: utils/frame.c:922
int say(const char *format,...)
Definition: utils/frame.c:1026
char * parsefilearg(int argcount, char *args[])
Definition: utils/frame.c:419
int parsetimearg(int argcount, char *args[], char *string, int *result)
Definition: utils/frame.c:332
FILE * out
Definition: utils/frame.h:45
int error(const char *format,...)
Definition: utils/frame.c:999
void argerror(char *s)
Definition: utils/frame.c:625
char * version
int iswav
Definition: utils/frame.c:32
char * malloccopy(char *string)
Definition: utils/frame.c:1038
void readwavheader(FILE *anyin)
Definition: utils/frame.c:126
int wavout
Definition: utils/frame.c:31
void readawaysamples(FILE *in, size_t size)
Definition: utils/frame.c:1069
int getremainingfilelength(FILE *anyin, long *result)
Definition: utils/frame.c:58
void argerrortxt(char *s, char *message)
Definition: utils/frame.c:704
int samplefrequency
Definition: utils/frame.c:28
int parsetime(char *string, int *result)
Definition: utils/frame.c:352
int parsevolarg(int argcount, char *args[], char *string, double *result)
Definition: utils/frame.c:539
int findoption(int argcount, char *args[], char *s)
Definition: utils/frame.c:900
unsigned short channels
Definition: utils/frame.c:30
void fatalerror(const char *format,...)
Definition: utils/frame.c:1010
int parseswitch(char *found, char *wanted)
Definition: utils/frame.c:445
int isoptionchar(char coal)
Definition: utils/frame.c:319
char * usage
Definition: utils/frame.c:37
int chat(const char *format,...)
Definition: utils/frame.c:971
int parsevolume(char *s, double *result)
Definition: utils/frame.c:590
int inform(const char *format,...)
Definition: utils/frame.c:985
void checknoargs(int argcount, char *args[])
Definition: utils/frame.c:717
int workloop(FILE *theinfile, FILE *theoutfile, int(*work)(short *buffer, int length))
Definition: utils/frame.c:943
FILE * in
Definition: utils/frame.c:33
char * infilename
Definition: utils/frame.c:34
int parsedoublearg(int argcount, char *args[], char *string, double *result)
Definition: utils/frame.c:505
char * outfilename
Definition: utils/frame.h:46
int parsefreq(char *string, double *result)
Definition: utils/frame.c:393
unsigned short samplewidth
Definition: utils/frame.c:29
int parseintarg(int argcount, char *args[], char *string, int *result)
Definition: utils/frame.c:471
void readpkheader(FILE *anyin)
Definition: utils/frame.c:76
int parseswitcharg(int argcount, char *args[], char *string)
Definition: utils/frame.c:457
void parseargs(int argcount, char *args[], int fileswitch)
Definition: utils/frame.c:744
void startstopwatch(void)
Definition: utils/frame.c:307
void makewavheader(void)
Definition: utils/frame.c:219
Errornum
Definition: utils/frame.h:61
@ ME_THISCANTHAPPEN
Definition: utils/frame.h:76
@ ME_NOSWITCH
Definition: utils/frame.h:66
@ ME_NOIOFILE
Definition: utils/frame.h:71
@ ME_NOSTDOUT
Definition: utils/frame.h:73
@ ME_NOINFILE
Definition: utils/frame.h:69
@ ME_NOVOL
Definition: utils/frame.h:65
@ ME_NOSTDIN
Definition: utils/frame.h:72
@ ME_TOOMANYFILES
Definition: utils/frame.h:67
@ ME_HEADERONTEXTFILE
Definition: utils/frame.h:68
@ ME_NOINT
Definition: utils/frame.h:62
@ ME_NODOUBLE
Definition: utils/frame.h:63
@ ME_NOOUTFILE
Definition: utils/frame.h:70
@ ME_NOSTDIO
Definition: utils/frame.h:74
@ ME_NOTIME
Definition: utils/frame.h:64
@ ME_NOTENOUGHFILES
Definition: utils/frame.h:75