channel locking: Add locking for channel snapshot creation
[asterisk/asterisk.git] / main / dial.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2007, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief Dialing API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 /*** MODULEINFO
27         <support_level>core</support_level>
28  ***/
29
30 #include "asterisk.h"
31
32 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
33
34 #include <sys/time.h>
35 #include <signal.h>
36
37 #include "asterisk/channel.h"
38 #include "asterisk/utils.h"
39 #include "asterisk/lock.h"
40 #include "asterisk/linkedlists.h"
41 #include "asterisk/dial.h"
42 #include "asterisk/pbx.h"
43 #include "asterisk/musiconhold.h"
44 #include "asterisk/app.h"
45 #include "asterisk/causes.h"
46 #include "asterisk/stasis_channels.h"
47
48 /*! \brief Main dialing structure. Contains global options, channels being dialed, and more! */
49 struct ast_dial {
50         int num;                                           /*!< Current number to give to next dialed channel */
51         int timeout;                                       /*!< Maximum time allowed for dial attempts */
52         int actual_timeout;                                /*!< Actual timeout based on all factors (ie: channels) */
53         enum ast_dial_result state;                        /*!< Status of dial */
54         void *options[AST_DIAL_OPTION_MAX];                /*!< Global options */
55         ast_dial_state_callback state_callback;            /*!< Status callback */
56         void *user_data;                                   /*!< Attached user data */
57         AST_LIST_HEAD(, ast_dial_channel) channels; /*!< Channels being dialed */
58         pthread_t thread;                                  /*!< Thread (if running in async) */
59         struct ast_callid *callid;                         /*!< callid pointer (if running in async) */
60         ast_mutex_t lock;                                  /*! Lock to protect the thread information above */
61 };
62
63 /*! \brief Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more! */
64 struct ast_dial_channel {
65         int num;                                /*!< Unique number for dialed channel */
66         int timeout;                            /*!< Maximum time allowed for attempt */
67         char *tech;                             /*!< Technology being dialed */
68         char *device;                           /*!< Device being dialed */
69         void *options[AST_DIAL_OPTION_MAX];     /*!< Channel specific options */
70         int cause;                              /*!< Cause code in case of failure */
71         unsigned int is_running_app:1;          /*!< Is this running an application? */
72         struct ast_channel *owner;              /*!< Asterisk channel */
73         AST_LIST_ENTRY(ast_dial_channel) list;  /*!< Linked list information */
74 };
75
76 /*! \brief Typedef for dial option enable */
77 typedef void *(*ast_dial_option_cb_enable)(void *data);
78
79 /*! \brief Typedef for dial option disable */
80 typedef int (*ast_dial_option_cb_disable)(void *data);
81
82 /*! \brief Structure for 'ANSWER_EXEC' option */
83 struct answer_exec_struct {
84         char app[AST_MAX_APP]; /*!< Application name */
85         char *args;            /*!< Application arguments */
86 };
87
88 /*! \brief Enable function for 'ANSWER_EXEC' option */
89 static void *answer_exec_enable(void *data)
90 {
91         struct answer_exec_struct *answer_exec = NULL;
92         char *app = ast_strdupa((char*)data), *args = NULL;
93
94         /* Not giving any data to this option is bad, mmmk? */
95         if (ast_strlen_zero(app))
96                 return NULL;
97
98         /* Create new data structure */
99         if (!(answer_exec = ast_calloc(1, sizeof(*answer_exec))))
100                 return NULL;
101
102         /* Parse out application and arguments */
103         if ((args = strchr(app, ','))) {
104                 *args++ = '\0';
105                 answer_exec->args = ast_strdup(args);
106         }
107
108         /* Copy application name */
109         ast_copy_string(answer_exec->app, app, sizeof(answer_exec->app));
110
111         return answer_exec;
112 }
113
114 /*! \brief Disable function for 'ANSWER_EXEC' option */
115 static int answer_exec_disable(void *data)
116 {
117         struct answer_exec_struct *answer_exec = data;
118
119         /* Make sure we have a value */
120         if (!answer_exec)
121                 return -1;
122
123         /* If arguments are present, free them too */
124         if (answer_exec->args)
125                 ast_free(answer_exec->args);
126
127         /* This is simple - just free the structure */
128         ast_free(answer_exec);
129
130         return 0;
131 }
132
133 static void *music_enable(void *data)
134 {
135         return ast_strdup(data);
136 }
137
138 static int music_disable(void *data)
139 {
140         if (!data)
141                 return -1;
142
143         ast_free(data);
144
145         return 0;
146 }
147
148 static void *predial_enable(void *data)
149 {
150         return ast_strdup(data);
151 }
152
153 static int predial_disable(void *data)
154 {
155         if (!data) {
156                 return -1;
157         }
158
159         ast_free(data);
160
161         return 0;
162 }
163
164 /*! \brief Application execution function for 'ANSWER_EXEC' option */
165 static void answer_exec_run(struct ast_dial *dial, struct ast_dial_channel *dial_channel, char *app, char *args)
166 {
167         struct ast_channel *chan = dial_channel->owner;
168         struct ast_app *ast_app = pbx_findapp(app);
169
170         /* If the application was not found, return immediately */
171         if (!ast_app)
172                 return;
173
174         /* All is well... execute the application */
175         pbx_exec(chan, ast_app, args);
176
177         /* If another thread is not taking over hang up the channel */
178         ast_mutex_lock(&dial->lock);
179         if (dial->thread != AST_PTHREADT_STOP) {
180                 ast_hangup(chan);
181                 dial_channel->owner = NULL;
182         }
183         ast_mutex_unlock(&dial->lock);
184
185         return;
186 }
187
188 struct ast_option_types {
189         enum ast_dial_option option;
190         ast_dial_option_cb_enable enable;
191         ast_dial_option_cb_disable disable;
192 };
193
194 /*!
195  * \brief Map options to respective handlers (enable/disable).
196  *
197  * \note This list MUST be perfectly kept in order with enum
198  * ast_dial_option, or else madness will happen.
199  */
200 static const struct ast_option_types option_types[] = {
201         { AST_DIAL_OPTION_RINGING, NULL, NULL },                                  /*!< Always indicate ringing to caller */
202         { AST_DIAL_OPTION_ANSWER_EXEC, answer_exec_enable, answer_exec_disable }, /*!< Execute application upon answer in async mode */
203         { AST_DIAL_OPTION_MUSIC, music_enable, music_disable },                   /*!< Play music to the caller instead of ringing */
204         { AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, NULL, NULL },                  /*!< Disable call forwarding on channels */
205         { AST_DIAL_OPTION_PREDIAL, predial_enable, predial_disable },             /*!< Execute a subroutine on the outbound channels prior to dialing */
206         { AST_DIAL_OPTION_MAX, NULL, NULL },                                      /*!< Terminator of list */
207 };
208
209 /*! \brief Maximum number of channels we can watch at a time */
210 #define AST_MAX_WATCHERS 256
211
212 /*! \brief Macro for finding the option structure to use on a dialed channel */
213 #define FIND_RELATIVE_OPTION(dial, dial_channel, ast_dial_option) (dial_channel->options[ast_dial_option] ? dial_channel->options[ast_dial_option] : dial->options[ast_dial_option])
214
215 /*! \brief Macro that determines whether a channel is the caller or not */
216 #define IS_CALLER(chan, owner) (chan == owner ? 1 : 0)
217
218 /*! \brief New dialing structure
219  * \note Create a dialing structure
220  * \return Returns a calloc'd ast_dial structure, NULL on failure
221  */
222 struct ast_dial *ast_dial_create(void)
223 {
224         struct ast_dial *dial = NULL;
225
226         /* Allocate new memory for structure */
227         if (!(dial = ast_calloc(1, sizeof(*dial))))
228                 return NULL;
229
230         /* Initialize list of channels */
231         AST_LIST_HEAD_INIT(&dial->channels);
232
233         /* Initialize thread to NULL */
234         dial->thread = AST_PTHREADT_NULL;
235
236         /* No timeout exists... yet */
237         dial->timeout = -1;
238         dial->actual_timeout = -1;
239
240         /* Can't forget about the lock */
241         ast_mutex_init(&dial->lock);
242
243         return dial;
244 }
245
246 /*! \brief Append a channel
247  * \note Appends a channel to a dialing structure
248  * \return Returns channel reference number on success, -1 on failure
249  */
250 int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device)
251 {
252         struct ast_dial_channel *channel = NULL;
253
254         /* Make sure we have required arguments */
255         if (!dial || !tech || !device)
256                 return -1;
257
258         /* Allocate new memory for dialed channel structure */
259         if (!(channel = ast_calloc(1, sizeof(*channel))))
260                 return -1;
261
262         /* Record technology and device for when we actually dial */
263         channel->tech = ast_strdup(tech);
264         channel->device = ast_strdup(device);
265
266         /* Grab reference number from dial structure */
267         channel->num = ast_atomic_fetchadd_int(&dial->num, +1);
268
269         /* No timeout exists... yet */
270         channel->timeout = -1;
271
272         /* Insert into channels list */
273         AST_LIST_INSERT_TAIL(&dial->channels, channel, list);
274
275         return channel->num;
276 }
277
278 /*! \brief Helper function that requests all channels */
279 static int begin_dial_prerun(struct ast_dial_channel *channel, struct ast_channel *chan, struct ast_format_cap *cap, const char *predial_string)
280 {
281         char numsubst[AST_MAX_EXTENSION];
282         struct ast_format_cap *cap_all_audio = NULL;
283         struct ast_format_cap *cap_request;
284
285         /* Copy device string over */
286         ast_copy_string(numsubst, channel->device, sizeof(numsubst));
287
288         if (!ast_format_cap_is_empty(cap)) {
289                 cap_request = cap;
290         } else if (chan) {
291                 cap_request = ast_channel_nativeformats(chan);
292         } else {
293                 cap_all_audio = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_NOLOCK);
294                 ast_format_cap_add_all_by_type(cap_all_audio, AST_FORMAT_TYPE_AUDIO);
295                 cap_request = cap_all_audio;
296         }
297
298         /* If we fail to create our owner channel bail out */
299         if (!(channel->owner = ast_request(channel->tech, cap_request, chan, numsubst, &channel->cause))) {
300                 cap_all_audio = ast_format_cap_destroy(cap_all_audio);
301                 return -1;
302         }
303         cap_request = NULL;
304         cap_all_audio = ast_format_cap_destroy(cap_all_audio);
305
306         ast_channel_lock(channel->owner);
307         ast_channel_stage_snapshot(channel->owner);
308
309         ast_channel_appl_set(channel->owner, "AppDial2");
310         ast_channel_data_set(channel->owner, "(Outgoing Line)");
311         ast_publish_channel_state(channel->owner);
312         memset(ast_channel_whentohangup(channel->owner), 0, sizeof(*ast_channel_whentohangup(channel->owner)));
313
314         /* Inherit everything from he who spawned this dial */
315         if (chan) {
316                 ast_channel_inherit_variables(chan, channel->owner);
317                 ast_channel_datastore_inherit(chan, channel->owner);
318
319                 /* Copy over callerid information */
320                 ast_party_redirecting_copy(ast_channel_redirecting(channel->owner), ast_channel_redirecting(chan));
321
322                 ast_channel_dialed(channel->owner)->transit_network_select = ast_channel_dialed(chan)->transit_network_select;
323
324                 ast_connected_line_copy_from_caller(ast_channel_connected(channel->owner), ast_channel_caller(chan));
325
326                 ast_channel_language_set(channel->owner, ast_channel_language(chan));
327                 ast_channel_accountcode_set(channel->owner, ast_channel_accountcode(chan));
328                 if (ast_strlen_zero(ast_channel_musicclass(channel->owner)))
329                         ast_channel_musicclass_set(channel->owner, ast_channel_musicclass(chan));
330
331                 ast_channel_adsicpe_set(channel->owner, ast_channel_adsicpe(chan));
332                 ast_channel_transfercapability_set(channel->owner, ast_channel_transfercapability(chan));
333         }
334
335         ast_channel_stage_snapshot_done(channel->owner);
336         ast_channel_unlock(channel->owner);
337
338         if (!ast_strlen_zero(predial_string)) {
339                 const char *predial_callee = ast_app_expand_sub_args(chan, predial_string);
340                 if (!predial_callee) {
341                         ast_log(LOG_ERROR, "Could not expand subroutine arguments in predial request '%s'\n", predial_string);
342                 }
343                 ast_autoservice_start(chan);
344                 ast_pre_call(channel->owner, predial_callee);
345                 ast_autoservice_stop(chan);
346                 ast_free((char *) predial_callee);
347         }
348
349         return 0;
350 }
351
352 int ast_dial_prerun(struct ast_dial *dial, struct ast_channel *chan, struct ast_format_cap *cap)
353 {
354         struct ast_dial_channel *channel;
355         int res = -1;
356         char *predial_string = dial->options[AST_DIAL_OPTION_PREDIAL];
357
358         if (!ast_strlen_zero(predial_string)) {
359                 ast_replace_subargument_delimiter(predial_string);
360         }
361
362         AST_LIST_LOCK(&dial->channels);
363         AST_LIST_TRAVERSE(&dial->channels, channel, list) {
364                 if ((res = begin_dial_prerun(channel, chan, cap, predial_string))) {
365                         break;
366                 }
367         }
368         AST_LIST_UNLOCK(&dial->channels);
369
370         return res;
371 }
372
373 /*! \brief Helper function that does the beginning dialing per-appended channel */
374 static int begin_dial_channel(struct ast_dial_channel *channel, struct ast_channel *chan, int async, const char *predial_string)
375 {
376         char numsubst[AST_MAX_EXTENSION];
377         int res = 1;
378
379         /* If no owner channel exists yet execute pre-run */
380         if (!channel->owner && begin_dial_prerun(channel, chan, NULL, predial_string)) {
381                 return 0;
382         }
383
384         /* Copy device string over */
385         ast_copy_string(numsubst, channel->device, sizeof(numsubst));
386
387         /* Attempt to actually call this device */
388         if ((res = ast_call(channel->owner, numsubst, 0))) {
389                 res = 0;
390                 ast_hangup(channel->owner);
391                 channel->owner = NULL;
392         } else {
393                 if (chan) {
394                         ast_poll_channel_add(chan, channel->owner);
395                 }
396                 ast_channel_publish_dial(async ? NULL : chan, channel->owner, channel->device, NULL);
397                 res = 1;
398                 ast_verb(3, "Called %s\n", numsubst);
399         }
400
401         return res;
402 }
403
404 /*! \brief Helper function that does the beginning dialing per dial structure */
405 static int begin_dial(struct ast_dial *dial, struct ast_channel *chan, int async)
406 {
407         struct ast_dial_channel *channel = NULL;
408         int success = 0;
409         char *predial_string = dial->options[AST_DIAL_OPTION_PREDIAL];
410
411         if (!ast_strlen_zero(predial_string)) {
412                 ast_replace_subargument_delimiter(predial_string);
413         }
414
415         /* Iterate through channel list, requesting and calling each one */
416         AST_LIST_LOCK(&dial->channels);
417         AST_LIST_TRAVERSE(&dial->channels, channel, list) {
418                 success += begin_dial_channel(channel, chan, async, predial_string);
419         }
420         AST_LIST_UNLOCK(&dial->channels);
421
422         /* If number of failures matches the number of channels, then this truly failed */
423         return success;
424 }
425
426 /*! \brief Helper function to handle channels that have been call forwarded */
427 static int handle_call_forward(struct ast_dial *dial, struct ast_dial_channel *channel, struct ast_channel *chan)
428 {
429         struct ast_channel *original = channel->owner;
430         char *tmp = ast_strdupa(ast_channel_call_forward(channel->owner));
431         char *tech = "Local", *device = tmp, *stuff;
432         char *predial_string = dial->options[AST_DIAL_OPTION_PREDIAL];
433
434         if (!ast_strlen_zero(predial_string)) {
435                 ast_replace_subargument_delimiter(predial_string);
436         }
437
438         /* If call forwarding is disabled just drop the original channel and don't attempt to dial the new one */
439         if (FIND_RELATIVE_OPTION(dial, channel, AST_DIAL_OPTION_DISABLE_CALL_FORWARDING)) {
440                 ast_hangup(original);
441                 channel->owner = NULL;
442                 return 0;
443         }
444
445         /* Figure out the new destination */
446         if ((stuff = strchr(tmp, '/'))) {
447                 *stuff++ = '\0';
448                 tech = tmp;
449                 device = stuff;
450         } else {
451                 const char *forward_context;
452                 char destination[AST_MAX_CONTEXT + AST_MAX_EXTENSION + 1];
453
454                 ast_channel_lock(original);
455                 forward_context = pbx_builtin_getvar_helper(original, "FORWARD_CONTEXT");
456                 snprintf(destination, sizeof(destination), "%s@%s", tmp, S_OR(forward_context, ast_channel_context(original)));
457                 ast_channel_unlock(original);
458                 device = ast_strdupa(destination);
459         }
460
461         /* Drop old destination information */
462         ast_free(channel->tech);
463         ast_free(channel->device);
464
465         /* Update the dial channel with the new destination information */
466         channel->tech = ast_strdup(tech);
467         channel->device = ast_strdup(device);
468         AST_LIST_UNLOCK(&dial->channels);
469
470         /* Drop the original channel */
471         channel->owner = NULL;
472
473         /* Finally give it a go... send it out into the world */
474         begin_dial_channel(channel, chan, chan ? 0 : 1, predial_string);
475
476         ast_channel_publish_dial_forward(chan, original, channel->owner, NULL, "CANCEL",
477                 ast_channel_call_forward(original));
478
479         ast_hangup(original);
480
481         return 0;
482 }
483
484 /*! \brief Helper function that finds the dialed channel based on owner */
485 static struct ast_dial_channel *find_relative_dial_channel(struct ast_dial *dial, struct ast_channel *owner)
486 {
487         struct ast_dial_channel *channel = NULL;
488
489         AST_LIST_LOCK(&dial->channels);
490         AST_LIST_TRAVERSE(&dial->channels, channel, list) {
491                 if (channel->owner == owner)
492                         break;
493         }
494         AST_LIST_UNLOCK(&dial->channels);
495
496         return channel;
497 }
498
499 static void set_state(struct ast_dial *dial, enum ast_dial_result state)
500 {
501         dial->state = state;
502
503         if (dial->state_callback)
504                 dial->state_callback(dial);
505 }
506
507 /*! \brief Helper function that handles control frames WITH owner */
508 static void handle_frame(struct ast_dial *dial, struct ast_dial_channel *channel, struct ast_frame *fr, struct ast_channel *chan)
509 {
510         if (fr->frametype == AST_FRAME_CONTROL) {
511                 switch (fr->subclass.integer) {
512                 case AST_CONTROL_ANSWER:
513                         ast_verb(3, "%s answered %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
514                         AST_LIST_LOCK(&dial->channels);
515                         AST_LIST_REMOVE(&dial->channels, channel, list);
516                         AST_LIST_INSERT_HEAD(&dial->channels, channel, list);
517                         AST_LIST_UNLOCK(&dial->channels);
518                         ast_channel_publish_dial(chan, channel->owner, channel->device, "ANSWER");
519                         set_state(dial, AST_DIAL_RESULT_ANSWERED);
520                         break;
521                 case AST_CONTROL_BUSY:
522                         ast_verb(3, "%s is busy\n", ast_channel_name(channel->owner));
523                         ast_channel_publish_dial(chan, channel->owner, channel->device, "BUSY");
524                         ast_hangup(channel->owner);
525                         channel->owner = NULL;
526                         break;
527                 case AST_CONTROL_CONGESTION:
528                         ast_verb(3, "%s is circuit-busy\n", ast_channel_name(channel->owner));
529                         ast_channel_publish_dial(chan, channel->owner, channel->device, "CONGESTION");
530                         ast_hangup(channel->owner);
531                         channel->owner = NULL;
532                         break;
533                 case AST_CONTROL_INCOMPLETE:
534                         ast_verb(3, "%s dialed Incomplete extension %s\n", ast_channel_name(channel->owner), ast_channel_exten(channel->owner));
535                         ast_indicate(chan, AST_CONTROL_INCOMPLETE);
536                         break;
537                 case AST_CONTROL_RINGING:
538                         ast_verb(3, "%s is ringing\n", ast_channel_name(channel->owner));
539                         if (!dial->options[AST_DIAL_OPTION_MUSIC])
540                                 ast_indicate(chan, AST_CONTROL_RINGING);
541                         set_state(dial, AST_DIAL_RESULT_RINGING);
542                         break;
543                 case AST_CONTROL_PROGRESS:
544                         ast_verb(3, "%s is making progress, passing it to %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
545                         ast_indicate(chan, AST_CONTROL_PROGRESS);
546                         set_state(dial, AST_DIAL_RESULT_PROGRESS);
547                         break;
548                 case AST_CONTROL_VIDUPDATE:
549                         ast_verb(3, "%s requested a video update, passing it to %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
550                         ast_indicate(chan, AST_CONTROL_VIDUPDATE);
551                         break;
552                 case AST_CONTROL_SRCUPDATE:
553                         ast_verb(3, "%s requested a source update, passing it to %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
554                         ast_indicate(chan, AST_CONTROL_SRCUPDATE);
555                         break;
556                 case AST_CONTROL_CONNECTED_LINE:
557                         ast_verb(3, "%s connected line has changed, passing it to %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
558                         if (ast_channel_connected_line_sub(channel->owner, chan, fr, 1) &&
559                                 ast_channel_connected_line_macro(channel->owner, chan, fr, 1, 1)) {
560                                 ast_indicate_data(chan, AST_CONTROL_CONNECTED_LINE, fr->data.ptr, fr->datalen);
561                         }
562                         break;
563                 case AST_CONTROL_REDIRECTING:
564                         ast_verb(3, "%s redirecting info has changed, passing it to %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
565                         if (ast_channel_redirecting_sub(channel->owner, chan, fr, 1) &&
566                                 ast_channel_redirecting_macro(channel->owner, chan, fr, 1, 1)) {
567                                 ast_indicate_data(chan, AST_CONTROL_REDIRECTING, fr->data.ptr, fr->datalen);
568                         }
569                         break;
570                 case AST_CONTROL_PROCEEDING:
571                         ast_verb(3, "%s is proceeding, passing it to %s\n", ast_channel_name(channel->owner), ast_channel_name(chan));
572                         ast_indicate(chan, AST_CONTROL_PROCEEDING);
573                         set_state(dial, AST_DIAL_RESULT_PROCEEDING);
574                         break;
575                 case AST_CONTROL_HOLD:
576                         ast_verb(3, "Call on %s placed on hold\n", ast_channel_name(chan));
577                         ast_indicate(chan, AST_CONTROL_HOLD);
578                         break;
579                 case AST_CONTROL_UNHOLD:
580                         ast_verb(3, "Call on %s left from hold\n", ast_channel_name(chan));
581                         ast_indicate(chan, AST_CONTROL_UNHOLD);
582                         break;
583                 case AST_CONTROL_OFFHOOK:
584                 case AST_CONTROL_FLASH:
585                         break;
586                 case AST_CONTROL_PVT_CAUSE_CODE:
587                         ast_indicate_data(chan, AST_CONTROL_PVT_CAUSE_CODE, fr->data.ptr, fr->datalen);
588                         break;
589                 case -1:
590                         /* Prod the channel */
591                         ast_indicate(chan, -1);
592                         break;
593                 default:
594                         break;
595                 }
596         }
597
598         return;
599 }
600
601 /*! \brief Helper function that handles control frames WITHOUT owner */
602 static void handle_frame_ownerless(struct ast_dial *dial, struct ast_dial_channel *channel, struct ast_frame *fr)
603 {
604         /* If we have no owner we can only update the state of the dial structure, so only look at control frames */
605         if (fr->frametype != AST_FRAME_CONTROL)
606                 return;
607
608         switch (fr->subclass.integer) {
609         case AST_CONTROL_ANSWER:
610                 ast_verb(3, "%s answered\n", ast_channel_name(channel->owner));
611                 AST_LIST_LOCK(&dial->channels);
612                 AST_LIST_REMOVE(&dial->channels, channel, list);
613                 AST_LIST_INSERT_HEAD(&dial->channels, channel, list);
614                 AST_LIST_UNLOCK(&dial->channels);
615                 ast_channel_publish_dial(NULL, channel->owner, channel->device, "ANSWER");
616                 set_state(dial, AST_DIAL_RESULT_ANSWERED);
617                 break;
618         case AST_CONTROL_BUSY:
619                 ast_verb(3, "%s is busy\n", ast_channel_name(channel->owner));
620                 ast_channel_publish_dial(NULL, channel->owner, channel->device, "BUSY");
621                 ast_hangup(channel->owner);
622                 channel->owner = NULL;
623                 break;
624         case AST_CONTROL_CONGESTION:
625                 ast_verb(3, "%s is circuit-busy\n", ast_channel_name(channel->owner));
626                 ast_channel_publish_dial(NULL, channel->owner, channel->device, "CONGESTION");
627                 ast_hangup(channel->owner);
628                 channel->owner = NULL;
629                 break;
630         case AST_CONTROL_RINGING:
631                 ast_verb(3, "%s is ringing\n", ast_channel_name(channel->owner));
632                 set_state(dial, AST_DIAL_RESULT_RINGING);
633                 break;
634         case AST_CONTROL_PROGRESS:
635                 ast_verb(3, "%s is making progress\n", ast_channel_name(channel->owner));
636                 set_state(dial, AST_DIAL_RESULT_PROGRESS);
637                 break;
638         case AST_CONTROL_PROCEEDING:
639                 ast_verb(3, "%s is proceeding\n", ast_channel_name(channel->owner));
640                 set_state(dial, AST_DIAL_RESULT_PROCEEDING);
641                 break;
642         default:
643                 break;
644         }
645
646         return;
647 }
648
649 /*! \brief Helper function to handle when a timeout occurs on dialing attempt */
650 static int handle_timeout_trip(struct ast_dial *dial, struct timeval start)
651 {
652         struct ast_dial_channel *channel = NULL;
653         int diff = ast_tvdiff_ms(ast_tvnow(), start), lowest_timeout = -1, new_timeout = -1;
654
655         /* If there is no difference yet return the dial timeout so we can go again, we were likely interrupted */
656         if (!diff) {
657                 return dial->timeout;
658         }
659
660         /* If the global dial timeout tripped switch the state to timeout so our channel loop will drop every channel */
661         if (diff >= dial->timeout) {
662                 set_state(dial, AST_DIAL_RESULT_TIMEOUT);
663                 new_timeout = 0;
664         }
665
666         /* Go through dropping out channels that have met their timeout */
667         AST_LIST_TRAVERSE(&dial->channels, channel, list) {
668                 if (dial->state == AST_DIAL_RESULT_TIMEOUT || diff >= channel->timeout) {
669                         ast_hangup(channel->owner);
670                         channel->owner = NULL;
671                 } else if ((lowest_timeout == -1) || (lowest_timeout > channel->timeout)) {
672                         lowest_timeout = channel->timeout;
673                 }
674         }
675
676         /* Calculate the new timeout using the lowest timeout found */
677         if (lowest_timeout >= 0)
678                 new_timeout = lowest_timeout - diff;
679
680         return new_timeout;
681 }
682
683 const char *ast_hangup_cause_to_dial_status(int hangup_cause)
684 {
685         switch(hangup_cause) {
686         case AST_CAUSE_BUSY:
687                 return "BUSY";
688         case AST_CAUSE_CONGESTION:
689                 return "CONGESTION";
690         case AST_CAUSE_NO_ROUTE_DESTINATION:
691         case AST_CAUSE_UNREGISTERED:
692                 return "CHANUNAVAIL";
693         case AST_CAUSE_NO_ANSWER:
694         default:
695                 return "NOANSWER";
696         }
697 }
698
699 /*! \brief Helper function that basically keeps tabs on dialing attempts */
700 static enum ast_dial_result monitor_dial(struct ast_dial *dial, struct ast_channel *chan)
701 {
702         int timeout = -1;
703         struct ast_channel *cs[AST_MAX_WATCHERS], *who = NULL;
704         struct ast_dial_channel *channel = NULL;
705         struct answer_exec_struct *answer_exec = NULL;
706         struct timeval start;
707
708         set_state(dial, AST_DIAL_RESULT_TRYING);
709
710         /* If the "always indicate ringing" option is set, change state to ringing and indicate to the owner if present */
711         if (dial->options[AST_DIAL_OPTION_RINGING]) {
712                 set_state(dial, AST_DIAL_RESULT_RINGING);
713                 if (chan)
714                         ast_indicate(chan, AST_CONTROL_RINGING);
715         } else if (chan && dial->options[AST_DIAL_OPTION_MUSIC] &&
716                 !ast_strlen_zero(dial->options[AST_DIAL_OPTION_MUSIC])) {
717                 char *original_moh = ast_strdupa(ast_channel_musicclass(chan));
718                 ast_indicate(chan, -1);
719                 ast_channel_musicclass_set(chan, dial->options[AST_DIAL_OPTION_MUSIC]);
720                 ast_moh_start(chan, dial->options[AST_DIAL_OPTION_MUSIC], NULL);
721                 ast_channel_musicclass_set(chan, original_moh);
722         }
723
724         /* Record start time for timeout purposes */
725         start = ast_tvnow();
726
727         /* We actually figured out the maximum timeout we can do as they were added, so we can directly access the info */
728         timeout = dial->actual_timeout;
729
730         /* Go into an infinite loop while we are trying */
731         while ((dial->state != AST_DIAL_RESULT_UNANSWERED) && (dial->state != AST_DIAL_RESULT_ANSWERED) && (dial->state != AST_DIAL_RESULT_HANGUP) && (dial->state != AST_DIAL_RESULT_TIMEOUT)) {
732                 int pos = 0, count = 0;
733                 struct ast_frame *fr = NULL;
734
735                 /* Set up channel structure array */
736                 pos = count = 0;
737                 if (chan)
738                         cs[pos++] = chan;
739
740                 /* Add channels we are attempting to dial */
741                 AST_LIST_LOCK(&dial->channels);
742                 AST_LIST_TRAVERSE(&dial->channels, channel, list) {
743                         if (channel->owner) {
744                                 cs[pos++] = channel->owner;
745                                 count++;
746                         }
747                 }
748                 AST_LIST_UNLOCK(&dial->channels);
749
750                 /* If we have no outbound channels in progress, switch state to unanswered and stop */
751                 if (!count) {
752                         set_state(dial, AST_DIAL_RESULT_UNANSWERED);
753                         break;
754                 }
755
756                 /* Just to be safe... */
757                 if (dial->thread == AST_PTHREADT_STOP)
758                         break;
759
760                 /* Wait for frames from channels */
761                 who = ast_waitfor_n(cs, pos, &timeout);
762
763                 /* Check to see if our thread is being canceled */
764                 if (dial->thread == AST_PTHREADT_STOP)
765                         break;
766
767                 /* If the timeout no longer exists OR if we got no channel it basically means the timeout was tripped, so handle it */
768                 if (!timeout || !who) {
769                         timeout = handle_timeout_trip(dial, start);
770                         continue;
771                 }
772
773                 /* Find relative dial channel */
774                 if (!chan || !IS_CALLER(chan, who))
775                         channel = find_relative_dial_channel(dial, who);
776
777                 /* See if this channel has been forwarded elsewhere */
778                 if (!ast_strlen_zero(ast_channel_call_forward(who))) {
779                         handle_call_forward(dial, channel, chan);
780                         continue;
781                 }
782
783                 /* Attempt to read in a frame */
784                 if (!(fr = ast_read(who))) {
785                         /* If this is the caller then we switch state to hangup and stop */
786                         if (chan && IS_CALLER(chan, who)) {
787                                 set_state(dial, AST_DIAL_RESULT_HANGUP);
788                                 break;
789                         }
790                         if (chan)
791                                 ast_poll_channel_del(chan, channel->owner);
792                         ast_channel_publish_dial(chan, who, channel->device, ast_hangup_cause_to_dial_status(ast_channel_hangupcause(who)));
793                         ast_hangup(who);
794                         channel->owner = NULL;
795                         continue;
796                 }
797
798                 /* Process the frame */
799                 if (chan)
800                         handle_frame(dial, channel, fr, chan);
801                 else
802                         handle_frame_ownerless(dial, channel, fr);
803
804                 /* Free the received frame and start all over */
805                 ast_frfree(fr);
806         }
807
808         /* Do post-processing from loop */
809         if (dial->state == AST_DIAL_RESULT_ANSWERED) {
810                 /* Hangup everything except that which answered */
811                 AST_LIST_LOCK(&dial->channels);
812                 AST_LIST_TRAVERSE(&dial->channels, channel, list) {
813                         if (!channel->owner || channel->owner == who)
814                                 continue;
815                         if (chan)
816                                 ast_poll_channel_del(chan, channel->owner);
817                         ast_channel_publish_dial(chan, channel->owner, channel->device, "CANCEL");
818                         ast_hangup(channel->owner);
819                         channel->owner = NULL;
820                 }
821                 AST_LIST_UNLOCK(&dial->channels);
822                 /* If ANSWER_EXEC is enabled as an option, execute application on answered channel */
823                 if ((channel = find_relative_dial_channel(dial, who)) && (answer_exec = FIND_RELATIVE_OPTION(dial, channel, AST_DIAL_OPTION_ANSWER_EXEC))) {
824                         channel->is_running_app = 1;
825                         answer_exec_run(dial, channel, answer_exec->app, answer_exec->args);
826                         channel->is_running_app = 0;
827                 }
828
829                 if (chan && dial->options[AST_DIAL_OPTION_MUSIC] &&
830                         !ast_strlen_zero(dial->options[AST_DIAL_OPTION_MUSIC])) {
831                         ast_moh_stop(chan);
832                 }
833         } else if (dial->state == AST_DIAL_RESULT_HANGUP) {
834                 /* Hangup everything */
835                 AST_LIST_LOCK(&dial->channels);
836                 AST_LIST_TRAVERSE(&dial->channels, channel, list) {
837                         if (!channel->owner)
838                                 continue;
839                         if (chan)
840                                 ast_poll_channel_del(chan, channel->owner);
841                         ast_channel_publish_dial(chan, channel->owner, channel->device, "CANCEL");
842                         ast_hangup(channel->owner);
843                         channel->owner = NULL;
844                 }
845                 AST_LIST_UNLOCK(&dial->channels);
846         }
847
848         return dial->state;
849 }
850
851 /*! \brief Dial async thread function */
852 static void *async_dial(void *data)
853 {
854         struct ast_dial *dial = data;
855         if (dial->callid) {
856                 ast_callid_threadassoc_add(dial->callid);
857         }
858
859         /* This is really really simple... we basically pass monitor_dial a NULL owner and it changes it's behavior */
860         monitor_dial(dial, NULL);
861
862         return NULL;
863 }
864
865 /*! \brief Execute dialing synchronously or asynchronously
866  * \note Dials channels in a dial structure.
867  * \return Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED).
868  */
869 enum ast_dial_result ast_dial_run(struct ast_dial *dial, struct ast_channel *chan, int async)
870 {
871         enum ast_dial_result res = AST_DIAL_RESULT_TRYING;
872
873         /* Ensure required arguments are passed */
874         if (!dial) {
875                 ast_debug(1, "invalid #1\n");
876                 return AST_DIAL_RESULT_INVALID;
877         }
878
879         /* If there are no channels to dial we can't very well try to dial them */
880         if (AST_LIST_EMPTY(&dial->channels)) {
881                 ast_debug(1, "invalid #2\n");
882                 return AST_DIAL_RESULT_INVALID;
883         }
884
885         /* Dial each requested channel */
886         if (!begin_dial(dial, chan, async))
887                 return AST_DIAL_RESULT_FAILED;
888
889         /* If we are running async spawn a thread and send it away... otherwise block here */
890         if (async) {
891                 /* reference be released at dial destruction if it isn't NULL */
892                 dial->callid = ast_read_threadstorage_callid();
893                 dial->state = AST_DIAL_RESULT_TRYING;
894                 /* Try to create a thread */
895                 if (ast_pthread_create(&dial->thread, NULL, async_dial, dial)) {
896                         /* Failed to create the thread - hangup all dialed channels and return failed */
897                         ast_dial_hangup(dial);
898                         res = AST_DIAL_RESULT_FAILED;
899                 }
900         } else {
901                 res = monitor_dial(dial, chan);
902         }
903
904         return res;
905 }
906
907 /*! \brief Return channel that answered
908  * \note Returns the Asterisk channel that answered
909  * \param dial Dialing structure
910  */
911 struct ast_channel *ast_dial_answered(struct ast_dial *dial)
912 {
913         if (!dial)
914                 return NULL;
915
916         return ((dial->state == AST_DIAL_RESULT_ANSWERED) ? AST_LIST_FIRST(&dial->channels)->owner : NULL);
917 }
918
919 /*! \brief Steal the channel that answered
920  * \note Returns the Asterisk channel that answered and removes it from the dialing structure
921  * \param dial Dialing structure
922  */
923 struct ast_channel *ast_dial_answered_steal(struct ast_dial *dial)
924 {
925         struct ast_channel *chan = NULL;
926
927         if (!dial)
928                 return NULL;
929
930         if (dial->state == AST_DIAL_RESULT_ANSWERED) {
931                 chan = AST_LIST_FIRST(&dial->channels)->owner;
932                 AST_LIST_FIRST(&dial->channels)->owner = NULL;
933         }
934
935         return chan;
936 }
937
938 /*! \brief Return state of dial
939  * \note Returns the state of the dial attempt
940  * \param dial Dialing structure
941  */
942 enum ast_dial_result ast_dial_state(struct ast_dial *dial)
943 {
944         return dial->state;
945 }
946
947 /*! \brief Cancel async thread
948  * \note Cancel a running async thread
949  * \param dial Dialing structure
950  */
951 enum ast_dial_result ast_dial_join(struct ast_dial *dial)
952 {
953         pthread_t thread;
954
955         /* If the dial structure is not running in async, return failed */
956         if (dial->thread == AST_PTHREADT_NULL)
957                 return AST_DIAL_RESULT_FAILED;
958
959         /* Record thread */
960         thread = dial->thread;
961
962         /* Boom, commence locking */
963         ast_mutex_lock(&dial->lock);
964
965         /* Stop the thread */
966         dial->thread = AST_PTHREADT_STOP;
967
968         /* If the answered channel is running an application we have to soft hangup it, can't just poke the thread */
969         AST_LIST_LOCK(&dial->channels);
970         if (AST_LIST_FIRST(&dial->channels)->is_running_app) {
971                 struct ast_channel *chan = AST_LIST_FIRST(&dial->channels)->owner;
972                 if (chan) {
973                         ast_channel_lock(chan);
974                         ast_softhangup(chan, AST_SOFTHANGUP_EXPLICIT);
975                         ast_channel_unlock(chan);
976                 }
977         } else {
978                 /* Now we signal it with SIGURG so it will break out of it's waitfor */
979                 pthread_kill(thread, SIGURG);
980         }
981         AST_LIST_UNLOCK(&dial->channels);
982
983         /* Yay done with it */
984         ast_mutex_unlock(&dial->lock);
985
986         /* Finally wait for the thread to exit */
987         pthread_join(thread, NULL);
988
989         /* Yay thread is all gone */
990         dial->thread = AST_PTHREADT_NULL;
991
992         return dial->state;
993 }
994
995 /*! \brief Hangup channels
996  * \note Hangup all active channels
997  * \param dial Dialing structure
998  */
999 void ast_dial_hangup(struct ast_dial *dial)
1000 {
1001         struct ast_dial_channel *channel = NULL;
1002
1003         if (!dial)
1004                 return;
1005
1006         AST_LIST_LOCK(&dial->channels);
1007         AST_LIST_TRAVERSE(&dial->channels, channel, list) {
1008                 ast_hangup(channel->owner);
1009                 channel->owner = NULL;
1010         }
1011         AST_LIST_UNLOCK(&dial->channels);
1012
1013         return;
1014 }
1015
1016 /*! \brief Destroys a dialing structure
1017  * \note Destroys (free's) the given ast_dial structure
1018  * \param dial Dialing structure to free
1019  * \return Returns 0 on success, -1 on failure
1020  */
1021 int ast_dial_destroy(struct ast_dial *dial)
1022 {
1023         int i = 0;
1024         struct ast_dial_channel *channel = NULL;
1025
1026         if (!dial)
1027                 return -1;
1028
1029         /* Hangup and deallocate all the dialed channels */
1030         AST_LIST_LOCK(&dial->channels);
1031         AST_LIST_TRAVERSE_SAFE_BEGIN(&dial->channels, channel, list) {
1032                 /* Disable any enabled options */
1033                 for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
1034                         if (!channel->options[i])
1035                                 continue;
1036                         if (option_types[i].disable)
1037                                 option_types[i].disable(channel->options[i]);
1038                         channel->options[i] = NULL;
1039                 }
1040
1041                 /* Hang up channel if need be */
1042                 ast_hangup(channel->owner);
1043                 channel->owner = NULL;
1044
1045                 /* Free structure */
1046                 ast_free(channel->tech);
1047                 ast_free(channel->device);
1048                 AST_LIST_REMOVE_CURRENT(list);
1049                 ast_free(channel);
1050         }
1051         AST_LIST_TRAVERSE_SAFE_END;
1052         AST_LIST_UNLOCK(&dial->channels);
1053
1054         /* Disable any enabled options globally */
1055         for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
1056                 if (!dial->options[i])
1057                         continue;
1058                 if (option_types[i].disable)
1059                         option_types[i].disable(dial->options[i]);
1060                 dial->options[i] = NULL;
1061         }
1062
1063         /* Lock be gone! */
1064         ast_mutex_destroy(&dial->lock);
1065
1066         /* Get rid of the reference to the ast_callid */
1067         if (dial->callid) {
1068                 ast_callid_unref(dial->callid);
1069         }
1070
1071         /* Free structure */
1072         ast_free(dial);
1073
1074         return 0;
1075 }
1076
1077 /*! \brief Enables an option globally
1078  * \param dial Dial structure to enable option on
1079  * \param option Option to enable
1080  * \param data Data to pass to this option (not always needed)
1081  * \return Returns 0 on success, -1 on failure
1082  */
1083 int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data)
1084 {
1085         /* If the option is already enabled, return failure */
1086         if (dial->options[option])
1087                 return -1;
1088
1089         /* Execute enable callback if it exists, if not simply make sure the value is set */
1090         if (option_types[option].enable)
1091                 dial->options[option] = option_types[option].enable(data);
1092         else
1093                 dial->options[option] = (void*)1;
1094
1095         return 0;
1096 }
1097
1098 /*! \brief Helper function for finding a channel in a dial structure based on number
1099  */
1100 static struct ast_dial_channel *find_dial_channel(struct ast_dial *dial, int num)
1101 {
1102         struct ast_dial_channel *channel = AST_LIST_LAST(&dial->channels);
1103
1104         /* We can try to predict programmer behavior, the last channel they added is probably the one they wanted to modify */
1105         if (channel->num == num)
1106                 return channel;
1107
1108         /* Hrm not at the end... looking through the list it is! */
1109         AST_LIST_LOCK(&dial->channels);
1110         AST_LIST_TRAVERSE(&dial->channels, channel, list) {
1111                 if (channel->num == num)
1112                         break;
1113         }
1114         AST_LIST_UNLOCK(&dial->channels);
1115
1116         return channel;
1117 }
1118
1119 /*! \brief Enables an option per channel
1120  * \param dial Dial structure
1121  * \param num Channel number to enable option on
1122  * \param option Option to enable
1123  * \param data Data to pass to this option (not always needed)
1124  * \return Returns 0 on success, -1 on failure
1125  */
1126 int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data)
1127 {
1128         struct ast_dial_channel *channel = NULL;
1129
1130         /* Ensure we have required arguments */
1131         if (!dial || AST_LIST_EMPTY(&dial->channels))
1132                 return -1;
1133
1134         if (!(channel = find_dial_channel(dial, num)))
1135                 return -1;
1136
1137         /* If the option is already enabled, return failure */
1138         if (channel->options[option])
1139                 return -1;
1140
1141         /* Execute enable callback if it exists, if not simply make sure the value is set */
1142         if (option_types[option].enable)
1143                 channel->options[option] = option_types[option].enable(data);
1144         else
1145                 channel->options[option] = (void*)1;
1146
1147         return 0;
1148 }
1149
1150 /*! \brief Disables an option globally
1151  * \param dial Dial structure to disable option on
1152  * \param option Option to disable
1153  * \return Returns 0 on success, -1 on failure
1154  */
1155 int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option option)
1156 {
1157         /* If the option is not enabled, return failure */
1158         if (!dial->options[option]) {
1159                 return -1;
1160         }
1161
1162         /* Execute callback of option to disable if it exists */
1163         if (option_types[option].disable)
1164                 option_types[option].disable(dial->options[option]);
1165
1166         /* Finally disable option on the structure */
1167         dial->options[option] = NULL;
1168
1169         return 0;
1170 }
1171
1172 /*! \brief Disables an option per channel
1173  * \param dial Dial structure
1174  * \param num Channel number to disable option on
1175  * \param option Option to disable
1176  * \return Returns 0 on success, -1 on failure
1177  */
1178 int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option)
1179 {
1180         struct ast_dial_channel *channel = NULL;
1181
1182         /* Ensure we have required arguments */
1183         if (!dial || AST_LIST_EMPTY(&dial->channels))
1184                 return -1;
1185
1186         if (!(channel = find_dial_channel(dial, num)))
1187                 return -1;
1188
1189         /* If the option is not enabled, return failure */
1190         if (!channel->options[option])
1191                 return -1;
1192
1193         /* Execute callback of option to disable it if it exists */
1194         if (option_types[option].disable)
1195                 option_types[option].disable(channel->options[option]);
1196
1197         /* Finally disable the option on the structure */
1198         channel->options[option] = NULL;
1199
1200         return 0;
1201 }
1202
1203 int ast_dial_reason(struct ast_dial *dial, int num)
1204 {
1205         struct ast_dial_channel *channel;
1206
1207         if (!dial || AST_LIST_EMPTY(&dial->channels) || !(channel = find_dial_channel(dial, num))) {
1208                 return -1;
1209         }
1210
1211         return channel->cause;
1212 }
1213
1214 struct ast_channel *ast_dial_get_channel(struct ast_dial *dial, int num)
1215 {
1216         struct ast_dial_channel *channel;
1217
1218         if (!dial || AST_LIST_EMPTY(&dial->channels) || !(channel = find_dial_channel(dial, num))) {
1219                 return NULL;
1220         }
1221
1222         return channel->owner;
1223 }
1224
1225 void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback)
1226 {
1227         dial->state_callback = callback;
1228 }
1229
1230 void ast_dial_set_user_data(struct ast_dial *dial, void *user_data)
1231 {
1232         dial->user_data = user_data;
1233 }
1234
1235 void *ast_dial_get_user_data(struct ast_dial *dial)
1236 {
1237         return dial->user_data;
1238 }
1239
1240 /*! \brief Set the maximum time (globally) allowed for trying to ring phones
1241  * \param dial The dial structure to apply the time limit to
1242  * \param timeout Maximum time allowed
1243  * \return nothing
1244  */
1245 void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout)
1246 {
1247         dial->timeout = timeout;
1248
1249         if (dial->timeout > 0 && (dial->actual_timeout > dial->timeout || dial->actual_timeout == -1))
1250                 dial->actual_timeout = dial->timeout;
1251
1252         return;
1253 }
1254
1255 /*! \brief Set the maximum time (per channel) allowed for trying to ring the phone
1256  * \param dial The dial structure the channel belongs to
1257  * \param num Channel number to set timeout on
1258  * \param timeout Maximum time allowed
1259  * \return nothing
1260  */
1261 void ast_dial_set_timeout(struct ast_dial *dial, int num, int timeout)
1262 {
1263         struct ast_dial_channel *channel = NULL;
1264
1265         if (!(channel = find_dial_channel(dial, num)))
1266                 return;
1267
1268         channel->timeout = timeout;
1269
1270         if (channel->timeout > 0 && (dial->actual_timeout > channel->timeout || dial->actual_timeout == -1))
1271                 dial->actual_timeout = channel->timeout;
1272
1273         return;
1274 }