Wed Oct 28 11:46:07 2009

Asterisk developer's documentation

devicestate.h File Reference

Device state management. More...

This graph shows which files directly or indirectly include this file:

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.
int ast_device_state_changed_literal (const char *device)
 Tells Asterisk the State for Device is changed.
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)
 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.
enum ast_device_state ast_parse_device_state (const char *device)
 Search the Channels by Name.
const char * devstate2str (enum ast_device_state devstate)
 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.

Detailed Description

Device state management.

To subscribe to device state changes, use the generic ast_event_subscribe method. For an example, see apps/app_queue.c.

Todo:
Currently, when the state of a device changes, the device state provider calls one of the functions defined here to queue an object to say that the state of a device has changed. However, this does not include the new state. Another thread processes these device state change objects and calls the device state provider's callback to figure out what the new state is. It would make a lot more sense for the new state to be included in the original function call that says the state of a device has changed. However, it will take a lot of work to change this.

Definition in file devicestate.h.

Enumeration Type Documentation

enum ast_device_state

Device States.

Note:
The order of these states may not change because they are included in Asterisk events which may be transmitted across the network to other servers.
Enumerator:
AST_DEVICE_UNKNOWN  Device is valid but channel didn't know state
AST_DEVICE_NOT_INUSE  Device is not used
AST_DEVICE_INUSE  Device is in use
AST_DEVICE_BUSY  Device is busy
AST_DEVICE_INVALID  Device is invalid
AST_DEVICE_UNAVAILABLE  Device is unavailable
AST_DEVICE_RINGING  Device is ringing
AST_DEVICE_RINGINUSE  Device is ringing *and* in use
AST_DEVICE_ONHOLD  Device is on hold
AST_DEVICE_TOTAL 

Definition at line 49 of file devicestate.h.

00049                       {
00050    AST_DEVICE_UNKNOWN,      /*!< Device is valid but channel didn't know state */
00051    AST_DEVICE_NOT_INUSE,    /*!< Device is not used */
00052    AST_DEVICE_INUSE,        /*!< Device is in use */
00053    AST_DEVICE_BUSY,         /*!< Device is busy */
00054    AST_DEVICE_INVALID,      /*!< Device is invalid */
00055    AST_DEVICE_UNAVAILABLE,  /*!< Device is unavailable */
00056    AST_DEVICE_RINGING,      /*!< Device is ringing */
00057    AST_DEVICE_RINGINUSE,    /*!< Device is ringing *and* in use */
00058    AST_DEVICE_ONHOLD,       /*!< Device is on hold */
00059    AST_DEVICE_TOTAL,        /*/ Total num of device states, used for testing */
00060 };

Function Documentation

enum ast_device_state ast_device_state ( const char *  device  ) 

Asks a channel for device state.

Parameters:
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.

Return values:
an AST_DEVICE_??? state
-1 on failure

Definition at line 346 of file devicestate.c.

References _ast_device_state().

00347 {
00348    /* This function is called from elsewhere in the code to find out the
00349     * current state of a device.  Check the cache, first. */
00350 
00351    return _ast_device_state(device, 1);
00352 }

int ast_device_state_changed ( const char *  fmt,
  ... 
)

Tells Asterisk the State for Device is changed.

Parameters:
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

Return values:
0 on success
-1 on failure
Note:
This is deprecated in favor of ast_devstate_changed()

Definition at line 490 of file devicestate.c.

References AST_DEVICE_UNKNOWN, 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(), expire_register(), handle_offhook_message(), handle_onhook_message(), handle_response_peerpoke(), handle_soft_key_event_message(), handle_stimulus_message(), login_exec(), reg_source_db(), register_verify(), reload_agents(), sip_peer_hold(), sip_poke_noanswer(), skinny_register(), skinny_unregister(), socket_process(), update_call_counter(), and update_registry().

00491 {
00492    char buf[AST_MAX_EXTENSION];
00493    va_list ap;
00494 
00495    va_start(ap, fmt);
00496    vsnprintf(buf, sizeof(buf), fmt, ap);
00497    va_end(ap);
00498 
00499    return ast_devstate_changed_literal(AST_DEVICE_UNKNOWN, buf);
00500 }

int ast_device_state_changed_literal ( const char *  device  ) 

Tells Asterisk the State for Device is changed.

Parameters:
device device name like a dial string
Asterisk polls the new extension states and calls the registered callbacks for the changed extensions

Return values:
0 on success
-1 on failure
Note:
This is deprecated in favor of ast_devstate_changed_literal()

Definition at line 472 of file devicestate.c.

References AST_DEVICE_UNKNOWN, and ast_devstate_changed_literal().

Referenced by ast_channel_free(), ast_setstate(), and dahdi_new().

00473 {
00474    return ast_devstate_changed_literal(AST_DEVICE_UNKNOWN, dev);
00475 }

void ast_devstate_aggregate_add ( struct ast_devstate_aggregate *  agg,
enum ast_device_state  state 
)

Add a device state to the aggregate device state.

Parameters:
[in] agg the state object
[in] state the state to add
Returns:
nothing

Definition at line 549 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().

00550 {
00551    switch (state) {
00552    case AST_DEVICE_NOT_INUSE:
00553       agg->all_unknown = 0;
00554       agg->all_unavail = 0;
00555       agg->all_busy = 0;
00556       break;
00557    case AST_DEVICE_INUSE:
00558       agg->in_use = 1;
00559       agg->all_unavail = 0;
00560       agg->all_free = 0;
00561       agg->all_unknown = 0;
00562       break;
00563    case AST_DEVICE_RINGING:
00564       agg->ring = 1;
00565       agg->all_unavail = 0;
00566       agg->all_free = 0;
00567       agg->all_unknown = 0;
00568       break;
00569    case AST_DEVICE_RINGINUSE:
00570       agg->in_use = 1;
00571       agg->ring = 1;
00572       agg->all_unavail = 0;
00573       agg->all_free = 0;
00574       agg->all_unknown = 0;
00575       break;
00576    case AST_DEVICE_ONHOLD:
00577       agg->all_unknown = 0;
00578       agg->all_unavail = 0;
00579       agg->all_free = 0;
00580       agg->on_hold = 1;
00581       break;
00582    case AST_DEVICE_BUSY:
00583       agg->all_unknown = 0;
00584       agg->all_unavail = 0;
00585       agg->all_free = 0;
00586       agg->busy = 1;
00587       agg->in_use = 1;
00588       break;
00589    case AST_DEVICE_UNAVAILABLE:
00590       agg->all_unknown = 0;
00591    case AST_DEVICE_INVALID:
00592       agg->all_busy = 0;
00593       agg->all_free = 0;
00594       break;
00595    case AST_DEVICE_UNKNOWN:
00596       agg->all_busy = 0;
00597       agg->all_free = 0;
00598       break;
00599    case AST_DEVICE_TOTAL: /* not a device state, included for completeness. */
00600       break;
00601    }
00602 }

void ast_devstate_aggregate_init ( struct ast_devstate_aggregate *  agg  ) 

Initialize aggregate device state.

Parameters:
[in] agg the state object
Returns:
nothing

Definition at line 539 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().

00540 {
00541    memset(agg, 0, sizeof(*agg));
00542 
00543    agg->all_unknown = 1;
00544    agg->all_unavail = 1;
00545    agg->all_busy = 1;
00546    agg->all_free = 1;
00547 }

enum ast_device_state ast_devstate_aggregate_result ( struct ast_devstate_aggregate *  agg  ) 

Get the aggregate device state result.

Parameters:
[in] agg the state object
Returns:
the aggregate device state after adding some number of device states.

Definition at line 605 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().

00606 {
00607    if (agg->all_free)
00608       return AST_DEVICE_NOT_INUSE;
00609    if ((agg->in_use || agg->on_hold) && agg->ring)
00610       return AST_DEVICE_RINGINUSE;
00611    if (agg->ring)
00612       return AST_DEVICE_RINGING;
00613    if (agg->busy)
00614       return AST_DEVICE_BUSY;
00615    if (agg->in_use)
00616       return AST_DEVICE_INUSE;
00617    if (agg->on_hold)
00618       return AST_DEVICE_ONHOLD;
00619    if (agg->all_busy)
00620       return AST_DEVICE_BUSY;
00621    if (agg->all_unknown)
00622       return AST_DEVICE_UNKNOWN;
00623    if (agg->all_unavail)
00624       return AST_DEVICE_UNAVAILABLE;
00625 
00626    return AST_DEVICE_NOT_INUSE;
00627 }

int ast_devstate_changed ( enum ast_device_state  state,
const char *  fmt,
  ... 
)

Tells Asterisk the State for Device is changed.

Parameters:
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.

Return values:
0 on success
-1 on failure

Definition at line 477 of file devicestate.c.

References ast_devstate_changed_literal(), AST_MAX_EXTENSION, and buf.

Referenced by conf_run(), devstate_write(), handle_cli_devstate_change(), load_module(), notify_metermaids(), register_verify(), sla_change_trunk_state(), sla_handle_hold_event(), and sla_station_exec().

00478 {
00479    char buf[AST_MAX_EXTENSION];
00480    va_list ap;
00481 
00482    va_start(ap, fmt);
00483    vsnprintf(buf, sizeof(buf), fmt, ap);
00484    va_end(ap);
00485 
00486    return ast_devstate_changed_literal(state, buf);
00487 }

int ast_devstate_changed_literal ( enum ast_device_state  state,
const char *  device 
)

Tells Asterisk the State for Device is changed.

Parameters:
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.

Return values:
0 on success
-1 on failure

Definition at line 448 of file devicestate.c.

References ast_calloc, ast_cond_signal(), ast_debug, AST_DEVICE_UNKNOWN, AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_UNLOCK, AST_PTHREADT_NULL, CACHE_ON, change_pending, change_thread, state_change::device, devstate_event(), and do_state_change().

Referenced by ast_device_state_changed(), ast_device_state_changed_literal(), and ast_devstate_changed().

00449 {
00450    struct state_change *change;
00451 
00452    ast_debug(3, "Notification of state change to be queued on device/channel %s\n", device);
00453 
00454    if (state != AST_DEVICE_UNKNOWN) {
00455       devstate_event(device, state, CACHE_ON);
00456    } else if (change_thread == AST_PTHREADT_NULL || !(change = ast_calloc(1, sizeof(*change) + strlen(device)))) {
00457       /* we could not allocate a change struct, or */
00458       /* there is no background thread, so process the change now */
00459       do_state_change(device);
00460    } else {
00461       /* queue the change */
00462       strcpy(change->device, device);
00463       AST_LIST_LOCK(&state_changes);
00464       AST_LIST_INSERT_TAIL(&state_changes, change, list);
00465       ast_cond_signal(&change_pending);
00466       AST_LIST_UNLOCK(&state_changes);
00467    }
00468 
00469    return 1;
00470 }

int ast_devstate_prov_add ( const char *  label,
ast_devstate_prov_cb_type  callback 
)

Add device state provider.

Parameters:
label to use in hint, like label:object
callback Callback
Return values:
0 success
-1 failure

Definition at line 355 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().

00356 {
00357    struct devstate_prov *devprov;
00358 
00359    if (!callback || !(devprov = ast_calloc(1, sizeof(*devprov))))
00360       return -1;
00361 
00362    devprov->callback = callback;
00363    ast_copy_string(devprov->label, label, sizeof(devprov->label));
00364 
00365    AST_RWLIST_WRLOCK(&devstate_provs);
00366    AST_RWLIST_INSERT_HEAD(&devstate_provs, devprov, list);
00367    AST_RWLIST_UNLOCK(&devstate_provs);
00368 
00369    return 0;
00370 }

int ast_devstate_prov_del ( const char *  label  ) 

Remove device state provider.

Parameters:
label to use in hint, like label:object
Return values:
-1 on failure
0 on success

Definition at line 373 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().

00374 {
00375    struct devstate_prov *devcb;
00376    int res = -1;
00377 
00378    AST_RWLIST_WRLOCK(&devstate_provs);
00379    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&devstate_provs, devcb, list) {
00380       if (!strcasecmp(devcb->label, label)) {
00381          AST_RWLIST_REMOVE_CURRENT(list);
00382          ast_free(devcb);
00383          res = 0;
00384          break;
00385       }
00386    }
00387    AST_RWLIST_TRAVERSE_SAFE_END;
00388    AST_RWLIST_UNLOCK(&devstate_provs);
00389 
00390    return res;
00391 }

const char* ast_devstate_str ( enum ast_device_state  devstate  ) 

Convert device state to text string that is easier to parse.

Parameters:
devstate Current device state

Definition at line 183 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_TOTAL, AST_DEVICE_UNAVAILABLE, and AST_DEVICE_UNKNOWN.

Referenced by devstate_read().

00184 {
00185    const char *res = "UNKNOWN";
00186 
00187    switch (state) {
00188    case AST_DEVICE_UNKNOWN:
00189       break;
00190    case AST_DEVICE_NOT_INUSE:
00191       res = "NOT_INUSE";
00192       break;
00193    case AST_DEVICE_INUSE:
00194       res = "INUSE";
00195       break;
00196    case AST_DEVICE_BUSY:
00197       res = "BUSY";
00198       break;
00199    case AST_DEVICE_INVALID:
00200       res = "INVALID";
00201       break;
00202    case AST_DEVICE_UNAVAILABLE:
00203       res = "UNAVAILABLE";
00204       break;
00205    case AST_DEVICE_RINGING:
00206       res = "RINGING";
00207       break;
00208    case AST_DEVICE_RINGINUSE:
00209       res = "RINGINUSE";
00210       break;
00211    case AST_DEVICE_ONHOLD:
00212       res = "ONHOLD";
00213       break;
00214    case AST_DEVICE_TOTAL: /* included only for completeness */
00215       break;
00216    }
00217 
00218    return res;
00219 }

enum ast_device_state ast_devstate_val ( const char *  val  ) 

Convert device state from text to integer value.

Parameters:
val The text representing the device state. Valid values are anything that comes after AST_DEVICE_ in one of the defined values.
Returns:
The AST_DEVICE_ integer value

Definition at line 221 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().

00222 {
00223    if (!strcasecmp(val, "NOT_INUSE"))
00224       return AST_DEVICE_NOT_INUSE;
00225    else if (!strcasecmp(val, "INUSE"))
00226       return AST_DEVICE_INUSE;
00227    else if (!strcasecmp(val, "BUSY"))
00228       return AST_DEVICE_BUSY;
00229    else if (!strcasecmp(val, "INVALID"))
00230       return AST_DEVICE_INVALID;
00231    else if (!strcasecmp(val, "UNAVAILABLE"))
00232       return AST_DEVICE_UNAVAILABLE;
00233    else if (!strcasecmp(val, "RINGING"))
00234       return AST_DEVICE_RINGING;
00235    else if (!strcasecmp(val, "RINGINUSE"))
00236       return AST_DEVICE_RINGINUSE;
00237    else if (!strcasecmp(val, "ONHOLD"))
00238       return AST_DEVICE_ONHOLD;
00239 
00240    return AST_DEVICE_UNKNOWN;
00241 }

enum ast_device_state ast_parse_device_state ( const char *  device  ) 

Search the Channels by Name.

Parameters:
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.

Return values:
AST_DEVICE_UNKNOWN if no channel found
AST_DEVICE_INUSE if a channel is found
Search the Channels by Name.

Note:
find channels with the device's name in it This function is only used for channels that does not implement devicestate natively

Definition at line 248 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().

00249 {
00250    struct ast_channel *chan;
00251    char match[AST_CHANNEL_NAME];
00252    enum ast_device_state res;
00253 
00254    ast_copy_string(match, device, sizeof(match)-1);
00255    strcat(match, "-");
00256    chan = ast_get_channel_by_name_prefix_locked(match, strlen(match));
00257 
00258    if (!chan)
00259       return AST_DEVICE_UNKNOWN;
00260 
00261    if (chan->_state == AST_STATE_RINGING)
00262       res = AST_DEVICE_RINGING;
00263    else
00264       res = AST_DEVICE_INUSE;
00265    
00266    ast_channel_unlock(chan);
00267 
00268    return res;
00269 }

const char* devstate2str ( enum ast_device_state  devstate  ) 

Convert device state to text string for output.

Parameters:
devstate Current device state

Definition at line 178 of file devicestate.c.

Referenced by __queues_show(), do_state_change(), handle_statechange(), notify_metermaids(), and page_exec().

00179 {
00180    return devstatestring[devstate];
00181 }

Variable Documentation

enum ast_device_state(* ast_devstate_prov_cb_type)(const char *data)

Devicestate provider call back.

Generated on Wed Oct 28 11:46:07 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6