Extension state is the state of an Asterisk extension, as opposed to the direct state of a device or a user. It is the aggregate of Device state from devices mapped to the extension through a hint directive. See the States and Presence section for a diagram showing the relationship of all the various states.
Asterisk's SIP channel drivers provide facilities to allow SIP presence subscriptions (RFC3856) to extensions with a defined hint. With an active subscription, devices can receive notification of state changes for the subscribed to extension. That notification will take the form of a SIP NOTIFY with PIDF content (RFC3863) containing the presence/state information.
For Asterisk to store and provide state for an extension, you must first define a hint for that extension. Hints are defined in the Asterisk dialplan, i.e. extensions.conf.
When Asterisk loads the configuration file it will create hints in memory for each hint defined in the dialplan. Those hints can then be queried or manipulated by functions and CLI commands. The state of each hint will regularly be updated based on state changes for any devices mapped to a hint.
The full syntax for a hint is
exten = <extension>,hint,<device state id>[& <more dev state id],<presence state id>
Here is what you might see for a few configured hints.
[internal] exten = 6001,hint,SIP/Alice&SIP/Alice-mobile exten = 6002,hint,SIP/Bob exten = 6003,hint,SIP/Charlie&DAHDI/3 exten = 6004,hint,SIP/Diane,CustomPresence:Diane exten = 6005,hint,,CustomPresence:Ellen
Things of note:
- You may notice that the syntax for a hint is similar to a regular extension, except you use the hint keyword in place of the priority. Remember these special hint directives are used at load-time and not during run-time, so there is no need for a priority.
- Multiple devices can be mapped to an extension by providing an ampersand delimited list.
- A presence state ID is set after the device state IDs. If set with only a presence state provider you must be sure to include a blank field after the hint as in the example for extension 6005.
- Hints can be anywhere in the dialplan. Though, remember that dialplan referencing the extension and devices subscribing to it will need use the extension number/name and context. The hints shown above would be [email protected], [email protected], etc, just like regular extensions.
Querying Extension State
The Querying and Manipulating State section covers accessing and affecting the various types of state.
For a quick CLI example, once you have defined some hints, you can easily check from the CLI to verify they get loaded correctly.
*CLI> core show hints -= Registered Asterisk Dial Plan Hints =- [email protected] : SIP/Charlie&DAHDI/3 State:Unavailable Watchers 0 [email protected] : SIP/Bob State:Unavailable Watchers 0 [email protected] : SIP/Alice&SIP/Alice- State:Unavailable Watchers 0 [email protected] : ,CustomPresence:Elle State:Unavailable Watchers 0 [email protected] : SIP/Diane,CustomPres State:Unavailable Watchers 0 ---------------- - 5 hints registered
In this example I was lazy, so they don't have real providers mapped otherwise you would see various states represented.
SIP Subscription to Asterisk hints
Once a hint is configured, Asterisk's SIP drivers can be configured to allow SIP User Agents to subscribe to the hints. A subscription will result in state change notifications being sent to the subscriber.
Configuration for chan_sip is discussed in Configuring chan_sip for Presence Subscriptions
Configuration for res_pjsip is discussed in Configuring res_pjsip for Presence Subscriptions