FreeSWITCH API Documentation  1.7.0
switch_cpp.h
Go to the documentation of this file.
1 #ifndef SWITCH_CPP_H
2 #define SWITCH_CPP_H
3 
4 
5 #ifdef __cplusplus
6 extern "C" {
7 #endif
8 #ifdef DOH
9 }
10 #endif
11 #include <switch.h>
12 #define this_check(x) do { if (!this) { switch_log_printf(SWITCH_CHANNEL_LOG,SWITCH_LOG_ERROR, "object is not initalized\n"); return x;}} while(0)
13 #define this_check_void() do { if (!this) { switch_log_printf(SWITCH_CHANNEL_LOG,SWITCH_LOG_ERROR, "object is not initalized\n"); return;}} while(0)
14 #define sanity_check(x) do { if (!(session && allocated)) { switch_log_printf(SWITCH_CHANNEL_UUID_LOG(uuid),SWITCH_LOG_ERROR, "session is not initalized\n"); return x;}} while(0)
15 #define sanity_check_noreturn do { if (!(session && allocated)) { switch_log_printf(SWITCH_CHANNEL_UUID_LOG(uuid),SWITCH_LOG_ERROR, "session is not initalized\n"); return;}} while(0)
16 #define init_vars() allocated = 0; \
17  session = NULL; \
18  channel = NULL; \
19  uuid = NULL; \
20  tts_name = NULL; \
21  voice_name = NULL; \
22  xml_cdr_text = NULL; \
23  memset(&args, 0, sizeof(args)); \
24  ap = NULL; \
25  flags = 0; \
26  on_hangup = NULL; \
27  memset(&cb_state, 0, sizeof(cb_state)); \
28  hook_state = CS_NEW; \
29  fhp = NULL; \
30  cause = SWITCH_CAUSE_NONE
31 
32 //// C++ Interface: switch_to_cpp_mempool//// Description: This class allows for overloading the new operator to allocate from a switch_memory_pool_t//// Author: Yossi Neiman <freeswitch@cartissolutions.com>, (C) 2007//// Copyright: See COPYING file that comes with this distribution//
33 #if 0
34 #ifndef SWITCHTOMEMPOOL
35 #define SWITCHTOMEMPOOL
36 class SwitchToMempool {
37  public:
38  SwitchToMempool() {
39  } SwitchToMempool(switch_memory_pool_t *mem) {
40  memorypool = mem;
41  }
42  void *operator new(switch_size_t num_bytes, switch_memory_pool_t *mem) {
43  void *ptr = switch_core_alloc(mem, (switch_size_t) num_bytes);
44  return ptr;
45  }
46  protected:
47  switch_memory_pool_t *memorypool;
48 };
49 #endif
50 #endif
51 
52 /*
53 
54 Overview: once you create an object that inherits this class, since
55  the memory pool is then a class data member, you can continue to
56  allocate objects from the memory pool.
57  objects from within the class
58 
59 Notes on usage:
60 
61 1. The derived class will need to also overload the ctor so that it accepts a memory pool object as a parameter.
62 2. Instantiation of a class would then look something like this: Foo *bar = new(memory_pool) Foo(memory_pool);
63 
64 Note that the first parameter to the new operator is implicitly handled by c++... not sure I like that but it's how it is...
65 
66 */
67 
68 
69 SWITCH_DECLARE(void) setGlobalVariable(char *var_name, char *var_val);
70 SWITCH_DECLARE(char *) getGlobalVariable(char *var_name);
71 
72 SWITCH_DECLARE(void) consoleLog(char *level_str, char *msg);
73 SWITCH_DECLARE(void) consoleLog2(char *level_str, char *file, char *func, int line, char *msg);
74 SWITCH_DECLARE(void) consoleCleanLog(char *msg);
75 SWITCH_DECLARE(bool) running(void);
76 
77 SWITCH_DECLARE(bool) email(char *to, char *from, char *headers = NULL, char *body = NULL,
78  char *file = NULL, char *convert_cmd = NULL, char *convert_ext = NULL);
79 
80 
81  class CoreSession;
82 
83  class IVRMenu {
84  protected:
87  public:
88  SWITCH_DECLARE_CONSTRUCTOR IVRMenu(IVRMenu * main,
89  const char *name,
90  const char *greeting_sound,
91  const char *short_greeting_sound,
92  const char *invalid_sound,
93  const char *exit_sound,
94  const char *transfer_sound,
95  const char *confirm_macro,
96  const char *confirm_key,
97  const char *tts_engine,
98  const char *tts_voice,
99  int confirm_attempts, int inter_timeout, int digit_len,
100  int timeout, int max_failures, int max_timeouts);
102  SWITCH_DECLARE(void) bindAction(char *action, const char *arg, const char *bind);
103  SWITCH_DECLARE(void) execute(CoreSession * session, const char *name);
104  };
105 
106 
107  class API {
108  protected:
109  char time_buf[64];
111  public:
112  SWITCH_DECLARE_CONSTRUCTOR API(CoreSession *s = NULL);
113  virtual SWITCH_DECLARE_CONSTRUCTOR ~ API();
114  SWITCH_DECLARE(const char *) execute(const char *command, const char *data = NULL);
115  SWITCH_DECLARE(const char *) executeString(const char *command);
116  SWITCH_DECLARE(char *) getTime(void);
117  };
118 
119 
120  typedef struct input_callback_state {
121  void *function; // pointer to the language specific callback function
122  // eg, PyObject *pyfunc
123  void *threadState; // pointer to the language specific thread state
124  // eg, PyThreadState *threadState
125  void *extra; // currently used to store a switch_file_handle_t
126  char *funcargs; // extra string that will be passed to callback function
128 
129  typedef enum {
130  S_HUP = (1 << 0),
131  S_FREE = (1 << 1),
132  S_RDLOCK = (1 << 2)
133  } session_flag_t;
134 
135  class DTMF {
136  public:
137  char digit;
138  uint32_t duration;
139  SWITCH_DECLARE_CONSTRUCTOR DTMF(char idigit, uint32_t iduration = SWITCH_DEFAULT_DTMF_DURATION);
141  };
142 
143  class Stream {
144  protected:
147  int mine;
148  public:
152  SWITCH_DECLARE(const char *) read(int *len);
153  SWITCH_DECLARE(void) write(const char *data);
154  SWITCH_DECLARE(void) raw_write(const char *data, int len);
155  SWITCH_DECLARE(const char *) get_data(void);
156  };
157 
158  class Event {
159  protected:
160  public:
163  int mine;
164 
165  SWITCH_DECLARE_CONSTRUCTOR Event(const char *type, const char *subclass_name = NULL);
166  SWITCH_DECLARE_CONSTRUCTOR Event(switch_event_t *wrap_me, int free_me = 0);
168  SWITCH_DECLARE(int) chat_execute(const char *app, const char *data = NULL);
169  SWITCH_DECLARE(int) chat_send(const char *dest_proto = NULL);
170  SWITCH_DECLARE(const char *) serialize(const char *format = NULL);
171  SWITCH_DECLARE(bool) setPriority(switch_priority_t priority = SWITCH_PRIORITY_NORMAL);
172  SWITCH_DECLARE(const char *) getHeader(const char *header_name);
173  SWITCH_DECLARE(char *) getBody(void);
174  SWITCH_DECLARE(const char *) getType(void);
175  SWITCH_DECLARE(bool) addBody(const char *value);
176  SWITCH_DECLARE(bool) addHeader(const char *header_name, const char *value);
177  SWITCH_DECLARE(bool) delHeader(const char *header_name);
178  SWITCH_DECLARE(bool) fire(void);
179 
180  };
181 
183  protected:
185  int ready;
186  public:
189  char *e_callback;
191  char *e_cb_arg;
193  uint32_t node_index;
194 
195  SWITCH_DECLARE_CONSTRUCTOR EventConsumer(const char *event_name = NULL, const char *subclass_name = "", int len = 5000);
197  SWITCH_DECLARE(int) bind(const char *event_name, const char *subclass_name = "");
198  SWITCH_DECLARE(Event *) pop(int block = 0, int timeout = 0);
199  SWITCH_DECLARE(void) cleanup();
200  };
201 
202 #ifdef SWIG
203  class CoreSession {
204 #else
205  class SWITCH_DECLARE_CLASS CoreSession {
206 #endif
207  protected:
208  switch_input_args_t args; // holds ptr to cb function and input_callback_state struct
209  // which has a language specific callback function
210  switch_input_args_t *ap; // ptr to args .. (is this really needed?)
211  // instead set them here first
213  void store_file_handle(switch_file_handle_t *fh);
214  void *on_hangup; // language specific callback function, cast as void *
216  char dtmf_buf[512];
217 
218  public:
219  SWITCH_DECLARE_CONSTRUCTOR CoreSession();
220  SWITCH_DECLARE_CONSTRUCTOR CoreSession(char *nuuid, CoreSession *a_leg = NULL);
221  SWITCH_DECLARE_CONSTRUCTOR CoreSession(switch_core_session_t *new_session);
225  unsigned int flags;
227  input_callback_state cb_state; // callback state, always pointed to by the buf
228  // field in this->args
229  switch_channel_state_t hook_state; // store hookstate for on_hangup callback
231 
232  char *uuid;
233  char *tts_name;
234  char *voice_name;
235 
236  SWITCH_DECLARE(int) insertFile(const char *file, const char *insert_file, int sample_point);
237  SWITCH_DECLARE(int) answer();
238  SWITCH_DECLARE(int) preAnswer();
239  SWITCH_DECLARE(void) hangup(const char *cause = "normal_clearing");
240  SWITCH_DECLARE(void) hangupState(void);
241  SWITCH_DECLARE(void) setVariable(char *var, char *val);
242  SWITCH_DECLARE(void) setPrivate(char *var, void *val);
243  SWITCH_DECLARE(void *) getPrivate(char *var);
244  SWITCH_DECLARE(const char *) getVariable(char *var);
245  SWITCH_DECLARE(switch_status_t) process_callback_result(char *result);
246  SWITCH_DECLARE(void) say(const char *tosay, const char *module_name, const char *say_type, const char *say_method,
247  const char *say_gender = NULL);
248  SWITCH_DECLARE(void) sayPhrase(const char *phrase_name, const char *phrase_data = "", const char *phrase_lang = NULL);
249  SWITCH_DECLARE(const char *) hangupCause();
250  SWITCH_DECLARE(const char *) getState();
251 
252  /** \brief Record to a file
253  * \param file_name
254  * \param <[max_len]> maximum length of the recording in seconds
255  * \param <[silence_threshold]> energy level audio must fall below
256  * to be considered silence (500 is a good starting point).
257  * \param <[silence_secs]> seconds of silence to interrupt the record.
258  */
259  SWITCH_DECLARE(int) recordFile(char *file_name, int time_limit = 0, int silence_threshold = 0, int silence_hits = 0);
260 
261  /** \brief Set attributes of caller data for purposes of outgoing calls
262  * \param var - the variable name, eg, "caller_id_name"
263  * \param val - the data to set, eg, "bob"
264  */
265 
266  /** \brief Originate a call to a destination
267  *
268  * \param a_leg_session - the session where the call is originating from
269  * and also the session in which _this_ session was
270  * created
271  * \param dest - a string representing destination, eg, sofia/mydomain.com/foo\@bar.com
272  * \param timeout - time to wait for call to be answered
273  * \return an int status code indicating success or failure
274  *
275  */
276  SWITCH_DECLARE(int) originate(CoreSession * a_leg_session, char *dest, int timeout = 60, switch_state_handler_table_t *handlers = NULL);
277 
278 
279  SWITCH_DECLARE(virtual void) destroy(void);
280 
281  /** \brief set a DTMF callback function
282  *
283  * The DTMF callback function will be set and persist
284  * for the life of the session, and be called when a dtmf
285  * is pressed by user during streamfile(), collectDigits(), and
286  * certain other methods are executing.
287  *
288  */
289  SWITCH_DECLARE(void) setDTMFCallback(void *cbfunc, char *funcargs);
290 
291  SWITCH_DECLARE(int) speak(char *text);
292  SWITCH_DECLARE(void) set_tts_parms(char *tts_name, char *voice_name);
293  SWITCH_DECLARE(void) set_tts_params(char *tts_name, char *voice_name);
294 
295  /**
296  * For timeout milliseconds, call the dtmf function set previously
297  * by setDTMFCallback whenever a dtmf or event is received
298  */
299  SWITCH_DECLARE(int) collectDigits(int abs_timeout);
300  SWITCH_DECLARE(int) collectDigits(int digit_timeout, int abs_timeout);
301 
302  /**
303  * Collect up to maxdigits digits worth of digits
304  * and store them in dtmf_buf. In the case of mod_python, the
305  * dtmf_buf parameter is configured to act as a _return_ value,
306  * (see mod_python.i). This does NOT call any callbacks upon
307  * receiving dtmf digits. For that, use collectDigits.
308  */
309  SWITCH_DECLARE(char *) getDigits(int maxdigits, char *terminators, int timeout);
310  SWITCH_DECLARE(char *) getDigits(int maxdigits, char *terminators, int timeout, int interdigit);
311  SWITCH_DECLARE(int) transfer(char *extension, char *dialplan = NULL, char *context = NULL);
312 
313 
314  SWITCH_DECLARE(char *) read(int min_digits, int max_digits,
315  const char *prompt_audio_file, int timeout, const char *valid_terminators, int digit_timeout = 0);
316 
317  /** \brief Play a file into channel and collect dtmfs
318  *
319  * See API docs in switch_ivr.h: switch_play_and_get_digits(..)
320  *
321  * NOTE: this does not call any dtmf callbacks set by
322  * setDTMFCallback(..) as it uses its own internal callback
323  * handler.
324  */
325  SWITCH_DECLARE(char *) playAndGetDigits(int min_digits,
326  int max_digits,
327  int max_tries,
328  int timeout, char *terminators, char *audio_files, char *bad_input_audio_files,
329  char *digits_regex, const char *var_name = NULL, int digit_timeout = 0,
330  const char *transfer_on_failure = NULL);
331 
332  /** \brief Play a file that resides on disk into the channel
333  *
334  * \param file - the path to the .wav/.mp3 to be played
335  * \param starting_sample_count - the index of the sample to
336  * start playing from
337  * \return an int status code indicating success or failure
338  *
339  */
340  SWITCH_DECLARE(int) streamFile(char *file, int starting_sample_count = 0);
341  SWITCH_DECLARE(int) sleep(int ms, int sync=0);
342 
343  /** \brief flush any pending events
344  */
345  SWITCH_DECLARE(int) flushEvents();
346 
347  /** \brief flush any pending digits
348  */
349  SWITCH_DECLARE(int) flushDigits();
350 
351  SWITCH_DECLARE(int) setAutoHangup(bool val);
352 
353  /** \brief Set the hangup callback function
354  * \param hangup_func - language specific function ptr cast into void *
355  */
356  SWITCH_DECLARE(void) setHangupHook(void *hangup_func);
357 
358  SWITCH_DECLARE(bool) ready();
359  SWITCH_DECLARE(bool) bridged();
360  SWITCH_DECLARE(bool) answered();
361  SWITCH_DECLARE(bool) mediaReady();
362 
363  SWITCH_DECLARE(void) waitForAnswer(CoreSession *calling_session);
364 
365  SWITCH_DECLARE(void) execute(const char *app, const char *data = NULL);
366 
367  SWITCH_DECLARE(void) sendEvent(Event * sendME);
368 
369  SWITCH_DECLARE(void) setEventData(Event * e);
370  SWITCH_DECLARE(char *) getXMLCDR();
371 
372  virtual bool begin_allow_threads() = 0;
373  virtual bool end_allow_threads() = 0;
374 
375  /** \brief Get the uuid of this session
376  * \return the uuid of this session
377  */
378  const char *get_uuid() const {
379  return uuid ? uuid : (char *) "uninitialized";
380  };
381 
382  /** \brief Get the callback function arguments associated with this session
383  * \return a const reference to the callback function arguments
384  */
386  return args;
387  };
388 
389  /** \brief Callback to the language specific hangup callback
390  */
391  virtual void check_hangup_hook() = 0;
392 
393  virtual switch_status_t run_dtmf_callback(void *input, switch_input_type_t itype) = 0;
394 
395  SWITCH_DECLARE(void) consoleLog(char *level_str, char *msg);
396  SWITCH_DECLARE(void) consoleLog2(char *level_str, char *file, char *func, int line, char *msg);
397  };
398 
399 
400 /* ---- functions not bound to CoreSession instance ----- */
401 
402 SWITCH_DECLARE(void) console_log(char *level_str, char *msg);
403 SWITCH_DECLARE(void) console_log2(char *level_str, char *file, char *func, int line, char *msg);
404 SWITCH_DECLARE(void) console_clean_log(char *msg);
405 SWITCH_DECLARE(void) switch_msleep(unsigned ms);
406 
407 /** \brief bridge the audio of session_b into session_a
408  *
409  * NOTE: the stuff regarding the dtmf callback might be completely
410  * wrong and has not been reviewed or tested
411  */
412 SWITCH_DECLARE(void) bridge(CoreSession & session_a, CoreSession & session_b);
413 
414 
415 /** \brief the actual hangup hook called back by freeswitch core
416  * which in turn gets the session and calls the appropriate
417  * instance method to complete the callback.
418  */
420 
422  void *input, switch_input_type_t itype, void *buf, unsigned int buflen);
423 
424 
425 
426 #ifdef __cplusplus
427 }
428 #endif
429 
430 #endif
431 /* For Emacs:
432  * Local Variables:
433  * mode:c
434  * indent-tabs-mode:t
435  * tab-width:4
436  * c-basic-offset:4
437  * End:
438  * For VIM:
439  * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet:
440  */
struct apr_queue_t switch_queue_t
Definition: switch_apr.h:590
switch_channel_t * channel
Definition: switch_cpp.h:224
switch_event_types_t e_event_id
Definition: switch_cpp.h:188
int mine
Definition: switch_cpp.h:163
DTMF(char idigit, uint32_t iduration=SWITCH_DEFAULT_DTMF_DURATION)
Definition: switch_cpp.cpp:524
void console_clean_log(char *msg)
void raw_write(const char *data, int len)
Definition: switch_cpp.cpp:587
void console_log2(char *level_str, char *file, char *func, int line, char *msg)
Stream(void)
Definition: switch_cpp.cpp:541
switch_input_args_t * ap
Definition: switch_cpp.h:210
switch_event_types_t
Built-in Events.
char * voice_name
Definition: switch_cpp.h:234
switch_priority_t
Priority Indication.
Definition: switch_types.h:991
switch_event_t * event
Definition: switch_cpp.h:161
switch_ivr_menu_t * menu
Definition: switch_cpp.h:85
Representation of an event.
Definition: switch_event.h:80
char * tts_name
Definition: switch_cpp.h:233
virtual ~DTMF()
Definition: switch_cpp.cpp:535
switch_status_t dtmf_callback(switch_core_session_t *session, void *input, switch_input_type_t itype, void *buf, unsigned int buflen)
switch_stream_handle_t mystream
Definition: switch_cpp.h:145
switch_core_session_t * session
Definition: switch_cpp.h:223
struct input_callback_state input_callback_state_t
#define SWITCH_DEFAULT_DTMF_DURATION
Definition: switch_types.h:115
A node to store binded events.
Definition: switch_event.c:46
char * e_subclass_name
Definition: switch_cpp.h:190
unsigned int flags
Definition: switch_cpp.h:225
switch_input_type_t
int mine
Definition: switch_cpp.h:147
switch_stream_handle_t * stream_p
Definition: switch_cpp.h:146
int main(int argc, char *argv[])
Definition: fs_encode.c:56
char * getGlobalVariable(char *var_name)
switch_memory_pool_t * pool
Definition: switch_cpp.h:184
switch_queue_t * events
Definition: switch_cpp.h:187
void console_log(char *level_str, char *msg)
switch_byte_t switch_byte_t * buf
switch_status_t hanguphook(switch_core_session_t *session)
the actual hangup hook called back by freeswitch core which in turn gets the session and calls the ap...
void consoleCleanLog(char *msg)
void consoleLog(char *level_str, char *msg)
#define SWITCH_DECLARE_CLASS
#define switch_core_alloc(_pool, _mem)
Allocate memory directly from a memory pool.
Definition: switch_core.h:682
char * e_callback
Definition: switch_cpp.h:189
switch_core_session_t * session
Definition: switch_cpp.h:110
switch_file_handle_t * fhp
Definition: switch_cpp.h:215
void setGlobalVariable(char *var_name, char *var_val)
void * on_hangup
Definition: switch_cpp.h:214
#define SWITCH_DECLARE_CONSTRUCTOR
session_flag_t
Definition: switch_cpp.h:129
uintptr_t switch_size_t
char digit
Definition: switch_cpp.h:137
void bridge(CoreSession &session_a, CoreSession &session_b)
bridge the audio of session_b into session_a
switch_memory_pool_t * pool
Definition: switch_cpp.h:86
switch_byte_t switch_byte_t uint32_t buflen
switch_call_cause_t cause
Definition: switch_cpp.h:230
switch_channel_state_t hook_state
Definition: switch_cpp.h:229
uint32_t node_index
Definition: switch_cpp.h:193
switch_call_cause_t
#define SWITCH_DECLARE_NONSTD(type)
bool email(char *to, char *from, char *headers=NULL, char *body=NULL, char *file=NULL, char *convert_cmd=NULL, char *convert_ext=NULL)
switch_channel_state_t
Channel States (these are the defaults, CS_SOFT_EXECUTE, CS_EXCHANGE_MEDIA, and CS_CONSUME_MEDIA are ...
uint32_t duration
Definition: switch_cpp.h:138
void consoleLog2(char *level_str, char *file, char *func, int line, char *msg)
switch_status_t
Common return values.
char * e_cb_arg
Definition: switch_cpp.h:191
Main Library Header.
#define SWITCH_DECLARE(type)
const switch_input_args_t & get_cb_args() const
Get the callback function arguments associated with this session.
Definition: switch_cpp.h:385
bool running(void)
switch_input_args_t args
Definition: switch_cpp.h:208
char * serialized_string
Definition: switch_cpp.h:162
struct apr_pool_t switch_memory_pool_t
virtual ~Stream()
Definition: switch_cpp.cpp:555
char * uuid
Definition: switch_cpp.h:232
const char * get_data(void)
Definition: switch_cpp.cpp:593
void switch_msleep(unsigned ms)
char * xml_cdr_text
Definition: switch_cpp.h:212
input_callback_state cb_state
Definition: switch_cpp.h:227
void write(const char *data)
Definition: switch_cpp.cpp:581
const char * read(int *len)
Definition: switch_cpp.cpp:563