Device state management. More...
#include "asterisk/channel.h"

Go to the source code of this file.
Data Structures | |
| struct | ast_devstate_aggregate |
| You shouldn't care about the contents of this struct. More... | |
Enumerations | |
| enum | ast_device_state { AST_DEVICE_UNKNOWN, AST_DEVICE_NOT_INUSE, AST_DEVICE_INUSE, AST_DEVICE_BUSY, AST_DEVICE_INVALID, AST_DEVICE_UNAVAILABLE, AST_DEVICE_RINGING, AST_DEVICE_RINGINUSE, AST_DEVICE_ONHOLD, AST_DEVICE_TOTAL } |
Device States. More... | |
Functions | |
| enum ast_device_state | ast_device_state (const char *device) |
| Asks a channel for device state. | |
| int | ast_device_state_changed (const char *fmt,...) |
| Tells Asterisk the State for Device is changed. (Accept change notification, add it to change queue.). | |
| int | ast_device_state_changed_literal (const char *device) |
| Tells Asterisk the State for Device is changed. | |
| const char * | ast_devstate2str (enum ast_device_state devstate) attribute_pure |
| Find devicestate as text message for output. | |
| void | ast_devstate_aggregate_add (struct ast_devstate_aggregate *agg, enum ast_device_state state) |
| Add a device state to the aggregate device state. | |
| void | ast_devstate_aggregate_init (struct ast_devstate_aggregate *agg) |
| Initialize aggregate device state. | |
| enum ast_device_state | ast_devstate_aggregate_result (struct ast_devstate_aggregate *agg) |
| Get the aggregate device state result. | |
| int | ast_devstate_changed (enum ast_device_state state, const char *fmt,...) |
| Tells Asterisk the State for Device is changed. | |
| int | ast_devstate_changed_literal (enum ast_device_state state, const char *device) |
| Tells Asterisk the State for Device is changed. | |
| int | ast_devstate_prov_add (const char *label, ast_devstate_prov_cb_type callback) |
| Add device state provider. | |
| int | ast_devstate_prov_del (const char *label) |
| Remove device state provider. | |
| const char * | ast_devstate_str (enum ast_device_state devstate) attribute_pure |
| Convert device state to text string that is easier to parse. | |
| enum ast_device_state | ast_devstate_val (const char *val) |
| Convert device state from text to integer value. | |
| int | ast_enable_distributed_devstate (void) |
| Enable distributed device state processing. | |
| enum ast_device_state | ast_parse_device_state (const char *device) |
| Search the Channels by Name. | |
| enum ast_device_state | ast_state_chan2dev (enum ast_channel_state chanstate) |
| Convert channel state to devicestate. | |
| const char * | devstate2str (enum ast_device_state devstate) attribute_pure |
| Convert device state to text string for output. | |
Variables | |
| enum ast_device_state(* | ast_devstate_prov_cb_type )(const char *data) |
| Devicestate provider call back. | |
Device state management.
To subscribe to device state changes, use the generic ast_event_subscribe method. For an example, see apps/app_queue.c.
Definition in file devicestate.h.
| enum ast_device_state |
Device States.
Definition at line 51 of file devicestate.h.
00051 { 00052 AST_DEVICE_UNKNOWN, /*!< Device is valid but channel didn't know state */ 00053 AST_DEVICE_NOT_INUSE, /*!< Device is not used */ 00054 AST_DEVICE_INUSE, /*!< Device is in use */ 00055 AST_DEVICE_BUSY, /*!< Device is busy */ 00056 AST_DEVICE_INVALID, /*!< Device is invalid */ 00057 AST_DEVICE_UNAVAILABLE, /*!< Device is unavailable */ 00058 AST_DEVICE_RINGING, /*!< Device is ringing */ 00059 AST_DEVICE_RINGINUSE, /*!< Device is ringing *and* in use */ 00060 AST_DEVICE_ONHOLD, /*!< Device is on hold */ 00061 AST_DEVICE_TOTAL, /*/ Total num of device states, used for testing */ 00062 };
| enum ast_device_state ast_device_state | ( | const char * | device | ) |
Asks a channel for device state.
| device | like a dial string |
Asks a channel for device state, data is normally a number from a dial string used by the low level module Tries the channel device state callback if not supported search in the active channels list for the device.
| an | AST_DEVICE_??? state | |
| -1 | on failure |
Definition at line 360 of file devicestate.c.
References _ast_device_state().
00361 { 00362 /* This function is called from elsewhere in the code to find out the 00363 * current state of a device. Check the cache, first. */ 00364 00365 return _ast_device_state(device, 1); 00366 }
| int ast_device_state_changed | ( | const char * | fmt, | |
| ... | ||||
| ) |
Tells Asterisk the State for Device is changed. (Accept change notification, add it to change queue.).
| fmt | device name like a dial string with format parameters |
Asterisk polls the new extension states and calls the registered callbacks for the changed extensions
| 0 | on success | |
| -1 | on failure |
Definition at line 520 of file devicestate.c.
References AST_DEVICE_UNKNOWN, ast_devstate_changed_literal(), AST_MAX_EXTENSION, and buf.
00521 { 00522 char buf[AST_MAX_EXTENSION]; 00523 va_list ap; 00524 00525 va_start(ap, fmt); 00526 vsnprintf(buf, sizeof(buf), fmt, ap); 00527 va_end(ap); 00528 00529 return ast_devstate_changed_literal(AST_DEVICE_UNKNOWN, buf); 00530 }
| int ast_device_state_changed_literal | ( | const char * | device | ) |
Tells Asterisk the State for Device is changed.
| device | device name like a dial string |
Asterisk polls the new extension states and calls the registered callbacks for the changed extensions
| 0 | on success | |
| -1 | on failure |
Definition at line 503 of file devicestate.c.
References AST_DEVICE_UNKNOWN, and ast_devstate_changed_literal().
00504 { 00505 return ast_devstate_changed_literal(AST_DEVICE_UNKNOWN, dev); 00506 }
| const char* ast_devstate2str | ( | enum ast_device_state | devstate | ) |
Find devicestate as text message for output.
Definition at line 209 of file devicestate.c.
Referenced by __queues_show(), do_state_change(), handle_statechange(), notify_metermaids(), page_exec(), and process_collection().
00210 { 00211 return devstatestring[devstate][0]; 00212 }
| void ast_devstate_aggregate_add | ( | struct ast_devstate_aggregate * | agg, | |
| enum ast_device_state | state | |||
| ) |
Add a device state to the aggregate device state.
| [in] | agg | the state object |
| [in] | state | the state to add |
Definition at line 743 of file devicestate.c.
References ast_devstate_aggregate::all_busy, ast_devstate_aggregate::all_free, ast_devstate_aggregate::all_unavail, ast_devstate_aggregate::all_unknown, AST_DEVICE_BUSY, AST_DEVICE_INUSE, AST_DEVICE_INVALID, AST_DEVICE_NOT_INUSE, AST_DEVICE_ONHOLD, AST_DEVICE_RINGING, AST_DEVICE_RINGINUSE, AST_DEVICE_TOTAL, AST_DEVICE_UNAVAILABLE, AST_DEVICE_UNKNOWN, ast_devstate_aggregate::busy, ast_devstate_aggregate::in_use, ast_devstate_aggregate::on_hold, and ast_devstate_aggregate::ring.
Referenced by ast_extension_state2(), and process_collection().
00744 { 00745 switch (state) { 00746 case AST_DEVICE_NOT_INUSE: 00747 agg->all_unknown = 0; 00748 agg->all_unavail = 0; 00749 agg->all_busy = 0; 00750 break; 00751 case AST_DEVICE_INUSE: 00752 agg->in_use = 1; 00753 agg->all_unavail = 0; 00754 agg->all_free = 0; 00755 agg->all_unknown = 0; 00756 break; 00757 case AST_DEVICE_RINGING: 00758 agg->ring = 1; 00759 agg->all_unavail = 0; 00760 agg->all_free = 0; 00761 agg->all_unknown = 0; 00762 break; 00763 case AST_DEVICE_RINGINUSE: 00764 agg->in_use = 1; 00765 agg->ring = 1; 00766 agg->all_unavail = 0; 00767 agg->all_free = 0; 00768 agg->all_unknown = 0; 00769 break; 00770 case AST_DEVICE_ONHOLD: 00771 agg->all_unknown = 0; 00772 agg->all_unavail = 0; 00773 agg->all_free = 0; 00774 agg->on_hold = 1; 00775 break; 00776 case AST_DEVICE_BUSY: 00777 agg->all_unknown = 0; 00778 agg->all_unavail = 0; 00779 agg->all_free = 0; 00780 agg->busy = 1; 00781 agg->in_use = 1; 00782 break; 00783 case AST_DEVICE_UNAVAILABLE: 00784 agg->all_unknown = 0; 00785 case AST_DEVICE_INVALID: 00786 agg->all_busy = 0; 00787 agg->all_free = 0; 00788 break; 00789 case AST_DEVICE_UNKNOWN: 00790 agg->all_busy = 0; 00791 agg->all_free = 0; 00792 break; 00793 case AST_DEVICE_TOTAL: /* not a device state, included for completeness. */ 00794 break; 00795 } 00796 }
| void ast_devstate_aggregate_init | ( | struct ast_devstate_aggregate * | agg | ) |
Initialize aggregate device state.
| [in] | agg | the state object |
Definition at line 733 of file devicestate.c.
References ast_devstate_aggregate::all_busy, ast_devstate_aggregate::all_free, ast_devstate_aggregate::all_unavail, and ast_devstate_aggregate::all_unknown.
Referenced by ast_extension_state2(), and process_collection().
00734 { 00735 memset(agg, 0, sizeof(*agg)); 00736 00737 agg->all_unknown = 1; 00738 agg->all_unavail = 1; 00739 agg->all_busy = 1; 00740 agg->all_free = 1; 00741 }
| enum ast_device_state ast_devstate_aggregate_result | ( | struct ast_devstate_aggregate * | agg | ) |
Get the aggregate device state result.
| [in] | agg | the state object |
Definition at line 799 of file devicestate.c.
References ast_devstate_aggregate::all_busy, ast_devstate_aggregate::all_free, ast_devstate_aggregate::all_unavail, ast_devstate_aggregate::all_unknown, AST_DEVICE_BUSY, AST_DEVICE_INUSE, AST_DEVICE_NOT_INUSE, AST_DEVICE_ONHOLD, AST_DEVICE_RINGING, AST_DEVICE_RINGINUSE, AST_DEVICE_UNAVAILABLE, AST_DEVICE_UNKNOWN, ast_devstate_aggregate::busy, ast_devstate_aggregate::in_use, ast_devstate_aggregate::on_hold, and ast_devstate_aggregate::ring.
Referenced by ast_extension_state2(), and process_collection().
00800 { 00801 if (agg->all_free) 00802 return AST_DEVICE_NOT_INUSE; 00803 if ((agg->in_use || agg->on_hold) && agg->ring) 00804 return AST_DEVICE_RINGINUSE; 00805 if (agg->ring) 00806 return AST_DEVICE_RINGING; 00807 if (agg->busy) 00808 return AST_DEVICE_BUSY; 00809 if (agg->in_use) 00810 return AST_DEVICE_INUSE; 00811 if (agg->on_hold) 00812 return AST_DEVICE_ONHOLD; 00813 if (agg->all_busy) 00814 return AST_DEVICE_BUSY; 00815 if (agg->all_unknown) 00816 return AST_DEVICE_UNKNOWN; 00817 if (agg->all_unavail) 00818 return AST_DEVICE_UNAVAILABLE; 00819 00820 return AST_DEVICE_NOT_INUSE; 00821 }
| int ast_devstate_changed | ( | enum ast_device_state | state, | |
| const char * | fmt, | |||
| ... | ||||
| ) |
Tells Asterisk the State for Device is changed.
| state | the new state of the device | |
| fmt | device name like a dial string with format parameters |
The new state of the device will be sent off to any subscribers of device states. It will also be stored in the internal event cache.
| 0 | on success | |
| -1 | on failure |
Definition at line 508 of file devicestate.c.
References ast_devstate_changed_literal(), AST_MAX_EXTENSION, and buf.
Referenced by __expire_registry(), __iax2_poke_noanswer(), agent_call(), agent_hangup(), agent_logoff_maintenance(), agent_read(), conf_run(), devstate_write(), expire_register(), handle_cli_devstate_change(), handle_offhook_message(), handle_onhook_message(), handle_response_peerpoke(), handle_soft_key_event_message(), handle_stimulus_message(), load_module(), login_exec(), notify_metermaids(), reg_source_db(), register_verify(), reload_agents(), sip_peer_hold(), sip_poke_noanswer(), skinny_register(), skinny_unregister(), sla_change_trunk_state(), sla_handle_hold_event(), sla_station_exec(), socket_process(), update_call_counter(), and update_registry().
00509 { 00510 char buf[AST_MAX_EXTENSION]; 00511 va_list ap; 00512 00513 va_start(ap, fmt); 00514 vsnprintf(buf, sizeof(buf), fmt, ap); 00515 va_end(ap); 00516 00517 return ast_devstate_changed_literal(state, buf); 00518 }
| int ast_devstate_changed_literal | ( | enum ast_device_state | state, | |
| const char * | device | |||
| ) |
Tells Asterisk the State for Device is changed.
| state | the new state of the device | |
| device | device name like a dial string with format parameters |
The new state of the device will be sent off to any subscribers of device states. It will also be stored in the internal event cache.
| 0 | on success | |
| -1 | on failure |
Definition at line 465 of file devicestate.c.
References ast_calloc, ast_cond_signal(), AST_DEVICE_UNKNOWN, AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_UNLOCK, change_thread, state_change::device, devstate_event(), and do_state_change().
Referenced by ast_channel_free(), ast_device_state_changed(), ast_device_state_changed_literal(), ast_devstate_changed(), ast_setstate(), and dahdi_new().
00466 { 00467 struct state_change *change; 00468 00469 /* 00470 * If we know the state change (how nice of the caller of this function!) 00471 * then we can just generate a device state event. 00472 * 00473 * Otherwise, we do the following: 00474 * - Queue an event up to another thread that the state has changed 00475 * - In the processing thread, it calls the callback provided by the 00476 * device state provider (which may or may not be a channel driver) 00477 * to determine the state. 00478 * - If the device state provider does not know the state, or this is 00479 * for a channel and the channel driver does not implement a device 00480 * state callback, then we will look through the channel list to 00481 * see if we can determine a state based on active calls. 00482 * - Once a state has been determined, a device state event is generated. 00483 */ 00484 00485 if (state != AST_DEVICE_UNKNOWN) { 00486 devstate_event(device, state); 00487 } else if (change_thread == AST_PTHREADT_NULL || !(change = ast_calloc(1, sizeof(*change) + strlen(device)))) { 00488 /* we could not allocate a change struct, or */ 00489 /* there is no background thread, so process the change now */ 00490 do_state_change(device); 00491 } else { 00492 /* queue the change */ 00493 strcpy(change->device, device); 00494 AST_LIST_LOCK(&state_changes); 00495 AST_LIST_INSERT_TAIL(&state_changes, change, list); 00496 ast_cond_signal(&change_pending); 00497 AST_LIST_UNLOCK(&state_changes); 00498 } 00499 00500 return 1; 00501 }
| int ast_devstate_prov_add | ( | const char * | label, | |
| ast_devstate_prov_cb_type | callback | |||
| ) |
Add device state provider.
| label | to use in hint, like label:object | |
| callback | Callback |
| 0 | success | |
| -1 | failure |
Definition at line 369 of file devicestate.c.
References ast_calloc, ast_copy_string(), AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, devstate_prov::callback, and devstate_prov::label.
Referenced by ast_features_init(), and load_module().
00370 { 00371 struct devstate_prov *devprov; 00372 00373 if (!callback || !(devprov = ast_calloc(1, sizeof(*devprov)))) 00374 return -1; 00375 00376 devprov->callback = callback; 00377 ast_copy_string(devprov->label, label, sizeof(devprov->label)); 00378 00379 AST_RWLIST_WRLOCK(&devstate_provs); 00380 AST_RWLIST_INSERT_HEAD(&devstate_provs, devprov, list); 00381 AST_RWLIST_UNLOCK(&devstate_provs); 00382 00383 return 0; 00384 }
| int ast_devstate_prov_del | ( | const char * | label | ) |
Remove device state provider.
| label | to use in hint, like label:object |
| -1 | on failure | |
| 0 | on success |
Definition at line 387 of file devicestate.c.
References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and devstate_prov::label.
Referenced by unload_module().
00388 { 00389 struct devstate_prov *devcb; 00390 int res = -1; 00391 00392 AST_RWLIST_WRLOCK(&devstate_provs); 00393 AST_RWLIST_TRAVERSE_SAFE_BEGIN(&devstate_provs, devcb, list) { 00394 if (!strcasecmp(devcb->label, label)) { 00395 AST_RWLIST_REMOVE_CURRENT(list); 00396 ast_free(devcb); 00397 res = 0; 00398 break; 00399 } 00400 } 00401 AST_RWLIST_TRAVERSE_SAFE_END; 00402 AST_RWLIST_UNLOCK(&devstate_provs); 00403 00404 return res; 00405 }
| const char* ast_devstate_str | ( | enum ast_device_state | devstate | ) |
Convert device state to text string that is easier to parse.
| devstate | Current device state |
Definition at line 233 of file devicestate.c.
Referenced by devstate_read().
00234 { 00235 return devstatestring[state][1]; 00236 }
| enum ast_device_state ast_devstate_val | ( | const char * | val | ) |
Convert device state from text to integer value.
| val | The text representing the device state. Valid values are anything that comes after AST_DEVICE_ in one of the defined values. |
Definition at line 238 of file devicestate.c.
References AST_DEVICE_BUSY, AST_DEVICE_INUSE, AST_DEVICE_INVALID, AST_DEVICE_NOT_INUSE, AST_DEVICE_ONHOLD, AST_DEVICE_RINGING, AST_DEVICE_RINGINUSE, AST_DEVICE_UNAVAILABLE, and AST_DEVICE_UNKNOWN.
Referenced by custom_devstate_callback(), devstate_write(), handle_cli_devstate_change(), and load_module().
00239 { 00240 if (!strcasecmp(val, "NOT_INUSE")) 00241 return AST_DEVICE_NOT_INUSE; 00242 else if (!strcasecmp(val, "INUSE")) 00243 return AST_DEVICE_INUSE; 00244 else if (!strcasecmp(val, "BUSY")) 00245 return AST_DEVICE_BUSY; 00246 else if (!strcasecmp(val, "INVALID")) 00247 return AST_DEVICE_INVALID; 00248 else if (!strcasecmp(val, "UNAVAILABLE")) 00249 return AST_DEVICE_UNAVAILABLE; 00250 else if (!strcasecmp(val, "RINGING")) 00251 return AST_DEVICE_RINGING; 00252 else if (!strcasecmp(val, "RINGINUSE")) 00253 return AST_DEVICE_RINGINUSE; 00254 else if (!strcasecmp(val, "ONHOLD")) 00255 return AST_DEVICE_ONHOLD; 00256 00257 return AST_DEVICE_UNKNOWN; 00258 }
| int ast_enable_distributed_devstate | ( | void | ) |
Enable distributed device state processing.
By default, Asterisk assumes that device state change events will only be originating from one instance. If a module gets loaded and configured such that multiple instances of Asterisk will be sharing device state, this function should be called to enable distributed device state processing. It is off by default to save on unnecessary processing.
| 0 | success | |
| -1 | failure |
Definition at line 823 of file devicestate.c.
References ast_cond_init(), AST_EVENT_DEVICE_STATE_CHANGE, AST_EVENT_IE_END, ast_event_subscribe(), ast_log(), ast_mutex_init(), ast_pthread_create_background, devstate_change_collector_cb(), devstate_collector, LOG_ERROR, and run_devstate_collector().
Referenced by add_publish_event(), and add_subscribe_event().
00824 { 00825 if (devstate_collector.enabled) { 00826 return 0; 00827 } 00828 00829 devstate_collector.event_sub = ast_event_subscribe(AST_EVENT_DEVICE_STATE_CHANGE, 00830 devstate_change_collector_cb, NULL, AST_EVENT_IE_END); 00831 00832 if (!devstate_collector.event_sub) { 00833 ast_log(LOG_ERROR, "Failed to create subscription for the device state change collector\n"); 00834 return -1; 00835 } 00836 00837 ast_mutex_init(&devstate_collector.lock); 00838 ast_cond_init(&devstate_collector.cond, NULL); 00839 if (ast_pthread_create_background(&devstate_collector.thread, NULL, run_devstate_collector, NULL) < 0) { 00840 ast_log(LOG_ERROR, "Unable to start device state collector thread.\n"); 00841 return -1; 00842 } 00843 00844 devstate_collector.enabled = 1; 00845 00846 return 0; 00847 }
| enum ast_device_state ast_parse_device_state | ( | const char * | device | ) |
Search the Channels by Name.
| device | like a dial string |
Search the Device in active channels by compare the channel name against the device name. Compared are only the first chars to the first '-' char.
| AST_DEVICE_UNKNOWN | if no channel found | |
| AST_DEVICE_INUSE | if a channel is found |
Search the Channels by Name.
Definition at line 265 of file devicestate.c.
References ast_channel::_state, AST_CHANNEL_NAME, ast_channel_unlock, ast_copy_string(), AST_DEVICE_INUSE, AST_DEVICE_RINGING, AST_DEVICE_UNKNOWN, ast_get_channel_by_name_prefix_locked(), AST_STATE_RINGING, chan, and match().
Referenced by _ast_device_state(), and chanavail_exec().
00266 { 00267 struct ast_channel *chan; 00268 char match[AST_CHANNEL_NAME]; 00269 enum ast_device_state res; 00270 00271 ast_copy_string(match, device, sizeof(match)-1); 00272 strcat(match, "-"); 00273 chan = ast_get_channel_by_name_prefix_locked(match, strlen(match)); 00274 00275 if (!chan) 00276 return AST_DEVICE_UNKNOWN; 00277 00278 if (chan->_state == AST_STATE_RINGING) 00279 res = AST_DEVICE_RINGING; 00280 else 00281 res = AST_DEVICE_INUSE; 00282 00283 ast_channel_unlock(chan); 00284 00285 return res; 00286 }
| enum ast_device_state ast_state_chan2dev | ( | enum ast_channel_state | chanstate | ) |
Convert channel state to devicestate.
| chanstate | Current channel state |
Definition at line 220 of file devicestate.c.
References AST_DEVICE_UNKNOWN, and chan.
Referenced by dahdi_new().
00221 { 00222 int i; 00223 chanstate &= 0xFFFF; 00224 for (i = 0; chan2dev[i].chan != -100; i++) { 00225 if (chan2dev[i].chan == chanstate) { 00226 return chan2dev[i].dev; 00227 } 00228 } 00229 return AST_DEVICE_UNKNOWN; 00230 }
| const char* devstate2str | ( | enum ast_device_state | devstate | ) |
Convert device state to text string for output.
| devstate | Current device state |
Definition at line 215 of file devicestate.c.
00216 { 00217 return devstatestring[devstate][0]; 00218 }
| enum ast_device_state(* ast_devstate_prov_cb_type)(const char *data) |
Devicestate provider call back.
1.6.2