UniMRCP: mpf_dtmf_generator.h Source File

00001 /*
00002  * Copyright 2009-2010 Tomas Valenta, Arsen Chaloyan
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MPF_DTMF_GENERATOR_H
00018 #define MPF_DTMF_GENERATOR_H
00019 
00020 /**
00021  * @file mpf_dtmf_generator.h
00022  * @brief DTMF generator
00023  *
00024  * Generator used to send DTMF tones. Capable to send digits
00025  * either in-band as audible tones or out-of-band according
00026  * to RFC4733.
00027  */
00028 
00029 #include "apr_pools.h"
00030 #include "apt.h"
00031 #include "mpf_frame.h"
00032 #include "mpf_stream.h"
00033 
00034 APT_BEGIN_EXTERN_C
00035 
00036 /** DTMF generator band */
00037 typedef enum mpf_dtmf_generator_band_e {
00038         /** Generate tones in-band */
00039         MPF_DTMF_GENERATOR_INBAND  = 0x1,
00040         /** Generate named events out-of-band */
00041         MPF_DTMF_GENERATOR_OUTBAND = 0x2,
00042         /** Generate both tones and named events */
00043         MPF_DTMF_GENERATOR_BOTH = MPF_DTMF_GENERATOR_INBAND | MPF_DTMF_GENERATOR_OUTBAND
00044 } mpf_dtmf_generator_band_e;
00045 
00046 /** Opaque MPF DTMF generator structure definition */
00047 typedef struct mpf_dtmf_generator_t mpf_dtmf_generator_t;
00048 
00049 
00050 /**
00051  * Create MPF DTMF generator (advanced).
00052  * @param stream      A stream to transport digits via.
00053  * @param band        MPF_DTMF_GENERATOR_INBAND or MPF_DTMF_GENERATOR_OUTBAND
00054  * @param tone_ms     Tone duration in milliseconds.
00055  * @param silence_ms  Inter-digit silence in milliseconds.
00056  * @param pool        Memory pool to allocate DTMF generator from.
00057  * @return The object or NULL on error.
00058  * @see mpf_dtmf_generator_create
00059  */
00060 MPF_DECLARE(struct mpf_dtmf_generator_t *) mpf_dtmf_generator_create_ex(
00061                                                                 const struct mpf_audio_stream_t *stream,
00062                                                                 enum mpf_dtmf_generator_band_e band,
00063                                                                 apr_uint32_t tone_ms,
00064                                                                 apr_uint32_t silence_ms,
00065                                                                 struct apr_pool_t *pool);
00066 
00067 /**
00068  * Create MPF DTMF generator (simple). Calls mpf_dtmf_generator_create_ex
00069  * with band = MPF_DTMF_GENERATOR_OUTBAND if supported by the stream or
00070  * MPF_DTMF_GENERATOR_INBAND otherwise, tone_ms = 70, silence_ms = 50.
00071  * @param stream      A stream to transport digits via.
00072  * @param pool        Memory pool to allocate DTMF generator from.
00073  * @return The object or NULL on error.
00074  * @see mpf_dtmf_generator_create_ex
00075  */
00076 static APR_INLINE struct mpf_dtmf_generator_t *mpf_dtmf_generator_create(
00077                                                                 const struct mpf_audio_stream_t *stream,
00078                                                                 struct apr_pool_t *pool)
00079 {
00080         return mpf_dtmf_generator_create_ex(stream,
00081                 stream->rx_event_descriptor ? MPF_DTMF_GENERATOR_OUTBAND : MPF_DTMF_GENERATOR_INBAND,
00082                 70, 50, pool);
00083 }
00084 
00085 /**
00086  * Add DTMF digits to the queue.
00087  * @param generator The generator.
00088  * @param digits    DTMF character sequence [0-9*#A-D].
00089  * @return TRUE if ok, FALSE if there are too many digits.
00090  */
00091 MPF_DECLARE(apt_bool_t) mpf_dtmf_generator_enqueue(
00092                                                                 struct mpf_dtmf_generator_t *generator,
00093                                                                 const char *digits);
00094 
00095 /**
00096  * Empty the queue and immediately stop generating.
00097  * @param generator The generator.
00098  */
00099 MPF_DECLARE(void) mpf_dtmf_generator_reset(struct mpf_dtmf_generator_t *generator);
00100 
00101 /**
00102  * Check state of the generator.
00103  * @param generator The generator.
00104  * @return TRUE if generating a digit or there are digits waiting in queue.
00105  * FALSE if the queue is empty or generating silence after the last digit.
00106  */
00107 MPF_DECLARE(apt_bool_t) mpf_dtmf_generator_sending(const struct mpf_dtmf_generator_t *generator);
00108 
00109 /**
00110  * Put frame into the stream.
00111  * @param generator The generator.
00112  * @param frame     Frame object passed in stream_read().
00113  * @return TRUE if frame with tone (both in-band and out-of-band) was generated,
00114  * FALSE otherwise. In contrast to mpf_dtmf_generator_sending, returns FALSE even
00115  * if generating inter-digit silence. In other words returns TRUE iff the frame
00116  * object was filled with data. This method MUST be called for each frame for
00117  * proper timing.
00118  */
00119 MPF_DECLARE(apt_bool_t) mpf_dtmf_generator_put_frame(
00120                                                                 struct mpf_dtmf_generator_t *generator,
00121                                                                 struct mpf_frame_t *frame);
00122 
00123 /**
00124  * Free all resources associated with the generator.
00125  * @param generator The generator.
00126  */
00127 MPF_DECLARE(void) mpf_dtmf_generator_destroy(struct mpf_dtmf_generator_t *generator);
00128 
00129 APT_END_EXTERN_C
00130 
00131 #endif /* MPF_DTMF_GENERATOR_H */