Asterisk Management Interface (AMI)
===================================

The AMI interface consists primarily of a number of action classes that are sent to Asterisk to
ellicit responses. Additionally, a number of event classes are defined to provide convenience
processing on the various messages Asterisk generates.

.. toctree::
    :maxdepth: 2
    
    actions/index.rst
    events/index.rst
    
All of these concepts are bound together by the :class:`ami.Manager` class, which provides
facilities for sending actions and serving callback handlers when events are received.

Members
-------

All of the following objects should be accessed as part of the `ami` namespace, regardless of the
modules in which they are defined.

Constants
+++++++++

Aside, perhaps, from the "GENERIC" values, to be matched against :attr:`ami.ami._Message.name` responses,
these constants are largely unnecessary outside of internal module usage, but they're exposed for
convenience's sake.

.. data:: RESPONSE_GENERIC

    A header-value provided as a surrogate for unidentifiable responses
    
.. data:: EVENT_GENERIC

    A header-value provided as a surrogate for unidentifiable unsolicited events

.. data:: KEY_ACTION

    The header key used to identify an action being requested of Asterisk
    
.. data:: KEY_ACTIONID

    The header key used to hold the ActionID of a request, for matching with responses
    
.. data:: KEY_EVENT

    The header key used to hold the event-name of a response
    
.. data:: KEY_RESPONSE

    The header key used to hold the event-name of a request

Classes
+++++++

.. autoclass:: ami.Manager
    :members:
    
Internal classes
~~~~~~~~~~~~~~~~

The following classes are not meant to be worked with directly, but are important for other parts of
the system, with members that are worth knowing about.

.. autoclass:: ami.ami._MessageTemplate
    
    .. attribute:: action_id
    
        The Asterisk Action-ID associated with this message, or `None` if undefined, as is the case
        with unsolicited events.
        
.. autoclass:: ami.ami._Aggregate
    :show-inheritance:
    
    .. attribute:: valid
    
        Indicates whether the aggregate is consistent with Asterisk's protocol.
        
    .. attribute:: error_message
    
        If `valid` is `False`, this will offer a string explaining why validation failed.
        
.. autoclass:: ami.ami._Event
    :show-inheritance:
    
    .. automethod:: ami.ami._Event.process
    
.. autoclass:: ami.ami._Message
    :show-inheritance:
    
    .. attribute:: data
    
        A series of lines containing the message's payload from Asterisk.
        
    .. attribute:: headers
    
        A reference to a dictionary containing all headers associated with this message. Simply
        treating the message itself as a dictionary for headers is preferred, however; the two
        methods are equivalent.
        
    .. attribute:: raw
    
        The raw response from Asterisk as a series of lines, provided for applications that need
        access to the original data.
        
.. autoclass:: ami.ami._Request
    
    .. attribute:: aggregate
    
        If `True` (`False` by default), an aggregate-event will be generated after the list of
        independent events generated by this request.
        
        This only has an effect with requests that generate lists of events to begin with and will
        be ignored in other cases.
    
    .. attribute:: synchronous
    
        If `True` (`False` by default), any events generated by this request will be collected and
        returned in the response.
        
        Synchronous requests will suppress generation of associated asynchronous events and
        aggregates.
    
    .. attribute:: timeout
    
        The number of seconds to wait before considering this request timed out, defaulting to `5`;
        may be a float.
        
        Indefinite waiting is not supported, but arbitrarily large values may be provided.
        
        A request that has timed out may still be serviced by Asterisk, with the notification being
        treated as an orphaned event.
        
        Changing the timeout value of the request object has no effect on any previously-sent
        instances of the request object, since the value is copied at dispatch-time.
        
.. class:: ami.ami._Response
    
    .. attribute:: action_id
    
        The action-ID associated with the request that led to the creation of this response.
    
    .. attribute:: events
    
        If the corresponding request was `synchronous`, this is a dictionary containing any events
        emitted in response. If not, this is `None`.
        
        The dictionary will contain references to either the events themselves or lists of events,
        depending on what is appropriate, keyed by the event's class-object and its friendly name
        as a string, like `pystrix.ami.core_events.CoreShowChannels` and "CoreShowChannels".
        
    .. attribute:: events_timeout
    
        A boolean value indicating whether any events were still unreceived when the response was
        returned. This is meaningful only if the reqyest had `synchronous` set.
        
    .. attribute:: response
    
        The response from Asterisk, without any post-processing applied. You will generally want to
        use `result` instead, unless you need to see exactly what Asterisk returned.
        
    .. attribute:: request
    
        The request object that led to this response. This will be `None` if the response is an
        orhpan, which may happen when a request times out, but a response is generated anyway,
        if multiple AMI clients are working with the same Asterisk instance (they won't know each
        other's action-IDs), or when working with buggy or experimental versions of Asterisk.
        
    .. attribute:: result
    
        The response from Asterisk, with post-processing applied to make it easier to work with in
        Python. This is the attribute about which you will likely care most.
        
    .. attribute:: success
    
        A boolean value that indicates whether the response appears to indicate that the request
        succeeded.
        
    .. attribute:: time
    
        The amount of time, as a UNIX timestamp, that elapsed while waiting for a response.
        
Exceptions
++++++++++

.. autoexception:: ami.Error
    :show-inheritance:

.. autoexception:: ami.ManagerError
    :show-inheritance:

.. autoexception:: ami.ManagerSocketError
    :show-inheritance:

